.TH LVMDEVICES 8 "LVM TOOLS #VERSION#" "Red Hat, Inc."
.
.SH NAME
.
lvmdevices \(em Manage the devices file
.
.SH SYNOPSIS
.
\fBlvmdevices\fP \fIoption_args\fP
.br
    [ \fIoption_args\fP ]
.br
.P
.ad l
    \fB--adddev\fP \fIPV\fP
.br
    \fB--addpvid\fP \fIString\fP
.br
    \fB--check\fP
.br
    \fB--commandprofile\fP \fIString\fP
.br
    \fB--config\fP \fIString\fP
.br
 \fB-d\fP|\fB--debug\fP
.br
    \fB--deldev\fP \fIString\fP
.br
    \fB--delnotfound\fP
.br
    \fB--delpvid\fP \fIString\fP
.br
    \fB--deviceidtype\fP \fIString\fP
.br
    \fB--devices\fP \fIPV\fP
.br
    \fB--devicesfile\fP \fIString\fP
.br
    \fB--driverloaded\fP \fBy\fP|\fBn\fP
.br
 \fB-h\fP|\fB--help\fP
.br
    \fB--journal\fP \fIString\fP
.br
    \fB--lockopt\fP \fIString\fP
.br
    \fB--longhelp\fP
.br
    \fB--nohints\fP
.br
    \fB--nolocking\fP
.br
    \fB--profile\fP \fIString\fP
.br
 \fB-q\fP|\fB--quiet\fP
.br
    \fB--refresh\fP
.br
 \fB-t\fP|\fB--test\fP
.br
    \fB--update\fP
.br
 \fB-v\fP|\fB--verbose\fP
.br
    \fB--version\fP
.br
 \fB-y\fP|\fB--yes\fP
.ad b
.
.SH DESCRIPTION
.
The LVM devices file lists devices that lvm can use.  The default file is
\fI#DEFAULT_SYS_DIR#/devices/system.devices\fP, and the \fBlvmdevices\fP(8) command is used to
add or remove device entries.  If the file does not exist, or if lvm.conf
includes use_devicesfile=0, then lvm will not use a devices file.
.P
To use a device with lvm, add it to the devices file with the command
lvmdevices --adddev, and to prevent lvm from seeing or using a device,
remove it from the devices file with lvmdevices --deldev.  The
vgimportdevices(8) command adds all PVs from a VG to the devices file,
and updates the VG metadata to include device IDs of the PVs.
.P
Commands that add new devices to the devices file necessarily look outside
the existing devices file to find the devices being added.  pvcreate,
vgcreate, and vgextend also look outside the devices file to create new
PVs and add those PVs to the devices file.
.P
LVM records devices in the devices file using hardware-specific IDs, such
as the WWID, and attempts to use subsystem-specific IDs for virtual device
types (which also aim to be as unique and stable as possible.) These
device IDs are also written in the VG metadata.  When no hardware or
virtual ID is available, lvm falls back using the unstable device name as
the device ID.  When devnames are used as IDs, lvm performs extra scanning
to find devices if their devname changes, e.g. after reboot.
.P
When proper device IDs are used, an lvm command will not look at devices
outside the devices file, but when devnames are used as a fallback, lvm
will scan devices outside the devices file to locate PVs on renamed
devices.  A config setting search_for_devnames can be used to control the
scanning for renamed devname entries.
.P
Related to the devices file, the command option --devices <devnames>
allows a list of devices to be specified for the command to use,
overriding the devices file.  The listed devices act as a sort of devices
file in terms of limiting which devices lvm will see and use.  Devices
that are not listed will appear to be missing to the lvm command.
.P
Multiple devices files can be kept in \fI#DEFAULT_SYS_DIR#/devices\fP, which
allows lvm to be used with different sets of devices.  For example, system
devices do not need to be exposed to a specific application, and the
application can use lvm on its own devices that are not exposed to the
system.  The option --devicesfile <filename> is used to select the devices
file to use with the command.  Without the option set, the default system
devices file is used.
.P
Setting --devicesfile "" causes lvm to not use a devices file.
.P
With no devices file, lvm will use any device on the system, and applies
the filter to limit the full set of system devices.  With a devices file,
the regex filter is not used, and the filter settings in lvm.conf or the
command line are ignored.  The vgimportdevices command is one exception
which does apply the regex filter when looking for a VG to import.
.P
If a devices file exists, lvm will use it, even if it's empty.  An empty
devices file means lvm will see no devices.
.P
If the system devices file does not yet exist, the pvcreate or vgcreate
commands will create it if they see no existing VGs on the system.
lvmdevices --addev and vgimportdevices will always create a new devices file
if it does not yet exist.
.P
It is recommended to use lvm commands to make changes to the devices file to
ensure proper updates.
.P
The device ID and device ID type are included in the VG metadata and can
be reported with pvs -o deviceid,deviceidtype.  (Note that the lvmdevices
command does not update VG metadata, but subsequent lvm commands modifying
the metadata will include the device ID.)
.P
Possible device ID types are:
.br
.IP \[bu] 2
.B sys_wwid
uses the wwid reported by the wwid sysfs file. This is the first choice.
.IP \[bu] 2
.B wwid_naa
uses the naa wwid decoded from the vpd_pg83 sysfs file.
.IP \[bu] 2
.B wwid_eui
uses the eui wwid decoded from the vpd_pg83 sysfs file.
.IP \[bu] 2
.B wwid_t10
uses the t10 wwid decoded from the vpd_pg83 sysfs file.
.IP \[bu] 2
.B sys_serial
uses the serial number reported by the serial sysfs file or the vpd_pg80
file. A serial number is used if no wwid is available.
.IP \[bu] 2
.B mpath_uuid
is used for dm multipath devices, reported by sysfs.
.IP \[bu] 2
.B crypt_uuid
is used for dm crypt devices, reported by sysfs.
.IP \[bu] 2
.B md_uuid
is used for md devices, reported by sysfs.
.IP \[bu] 2
.B lvmlv_uuid
is used if a PV is placed on top of an lvm LV, reported by sysfs.
.IP \[bu] 2
.B loop_file
is used for loop devices, the backing file name reported by sysfs.
.IP \[bu] 2
.B devname
the device name is used if no other type applies.
.P
The default choice for device ID type can be overridden using lvmdevices
--addev --deviceidtype <type>.  If the specified type is available for the
device it will be used, otherwise the device will be added using the type
that would otherwise be chosen.

LVM commands run by dmeventd will use the devices file
\fI#DEFAULT_SYS_DIR#/devices/dmeventd.devices\fP if it exists,
otherwise system.devices is used.  VGs that require the dmeventd
service should be included in system.devices, even if they are
included in dmeventd.devices.

.SS Device ID refresh
.P
A machine identifier is saved in the devices file, and is used to detect
when the devices file has been created by a different machine. If the
devices file was created by a different machine, it indicates that PVs may
have been copied or restored onto new devices on a new machine. In this
case, lvm will search for the PVs listed in system.devices on new devices.
If found, the device IDs will be updated in system.devices for the
existing PVIDs (assuming the original device IDs are also no longer
found.)
.P
The machine identifier used in system.devices will be either the DMI
product_uuid from /sys/devices/virtual/dmi/id/product_uuid, or the
hostname from uname(2). See lvm.conf device_ids_refresh_checks to
configure this.

.
.SH USAGE
.
Print devices in the devices file.
.br
.P
\fBlvmdevices\fP
.br
.RS 4
.ad l
[ COMMON_OPTIONS ]
.ad b
.RE
.P
\(em
.P
Check the devices file and report incorrect values.
.br
.P
\fBlvmdevices\fP \fB--check\fP
.br
.RS 4
.ad l
[    \fB--refresh\fP ]
.br
[ COMMON_OPTIONS ]
.ad b
.RE
.P
\(em
.P
Update the devices file to fix incorrect values.
.br
.P
\fBlvmdevices\fP \fB--update\fP
.br
.RS 4
.ad l
[    \fB--delnotfound\fP ]
.br
[    \fB--refresh\fP ]
.br
[ COMMON_OPTIONS ]
.ad b
.RE
.P
\(em
.P
Add a device to the devices file.
.br
.P
\fBlvmdevices\fP \fB--adddev\fP \fIPV\fP
.br
.RS 4
.ad l
[    \fB--deviceidtype\fP \fIString\fP ]
.br
[ COMMON_OPTIONS ]
.ad b
.RE
.P
\(em
.P
Remove a device from the devices file.
.br
.P
\fBlvmdevices\fP \fB--deldev\fP \fIString\fP|\fIPV\fP
.br
.RS 4
.ad l
[    \fB--deviceidtype\fP \fIString\fP ]
.br
[ COMMON_OPTIONS ]
.ad b
.RE
.P
\(em
.P
Find the device with the given PVID and add it to the devices file.
.br
.P
\fBlvmdevices\fP \fB--addpvid\fP \fIString\fP
.br
.RS 4
.ad l
[    \fB--deviceidtype\fP \fIString\fP ]
.br
[ COMMON_OPTIONS ]
.ad b
.RE
.P
\(em
.P
Remove the devices file entry for the given PVID.
.br
.P
\fBlvmdevices\fP \fB--delpvid\fP \fIString\fP
.br
.RS 4
.ad l
[ COMMON_OPTIONS ]
.ad b
.RE
.P
\(em
.P
Common options for lvm:
.
.RS 4
.ad l
[ \fB-d\fP|\fB--debug\fP ]
.br
[ \fB-h\fP|\fB--help\fP ]
.br
[ \fB-q\fP|\fB--quiet\fP ]
.br
[ \fB-t\fP|\fB--test\fP ]
.br
[ \fB-v\fP|\fB--verbose\fP ]
.br
[ \fB-y\fP|\fB--yes\fP ]
.br
[    \fB--commandprofile\fP \fIString\fP ]
.br
[    \fB--config\fP \fIString\fP ]
.br
[    \fB--devices\fP \fIPV\fP ]
.br
[    \fB--devicesfile\fP \fIString\fP ]
.br
[    \fB--driverloaded\fP \fBy\fP|\fBn\fP ]
.br
[    \fB--journal\fP \fIString\fP ]
.br
[    \fB--lockopt\fP \fIString\fP ]
.br
[    \fB--longhelp\fP ]
.br
[    \fB--nohints\fP ]
.br
[    \fB--nolocking\fP ]
.br
[    \fB--profile\fP \fIString\fP ]
.br
[    \fB--version\fP ]
.ad b
.RE
.
.SH OPTIONS
.
.
.HP
\fB--adddev\fP \fIPV\fP
.br
Add a device to the devices file.
.
.HP
\fB--addpvid\fP \fIString\fP
.br
Find a device with the PVID and add the device to the devices file.
.
.HP
\fB--check\fP
.br
Checks the content of the devices file.
Reports incorrect device names or PVIDs for entries.
.
.HP
\fB--commandprofile\fP \fIString\fP
.br
The command profile to use for command configuration.
See \fBlvm.conf\fP(5) for more information about profiles.
.
.HP
\fB--config\fP \fIString\fP
.br
Config settings for the command. These override \fBlvm.conf\fP(5) settings.
The String arg uses the same format as \fBlvm.conf\fP(5),
or may use section/field syntax.
See \fBlvm.conf\fP(5) for more information about config.
.
.HP
\fB-d\fP|\fB--debug\fP ...
.br
Set debug level. Repeat from 1 to 6 times to increase the detail of
messages sent to the log file and/or syslog (if configured).
.
.HP
\fB--deldev\fP \fIString\fP
.br
Remove a device from the devices file.
When used alone, --deldev specifies a device name.
When used with --deviceidtype, --deldev specifies a device id.
.
.HP
\fB--delnotfound\fP
.br
Remove devices file entries with no matching device.
.
.HP
\fB--delpvid\fP \fIString\fP
.br
Remove a device with the PVID from the devices file.
.
.HP
\fB--deviceidtype\fP \fIString\fP
.br
The type of device ID to use for the device.
If the specified type is available for the device,
then it will override the default type that lvm would use.
.
.HP
\fB--devices\fP \fIPV\fP
.br
Restricts the devices that are visible and accessible to the command.
Devices not listed will appear to be missing. This option can be
repeated, or accepts a comma separated list of devices. This overrides
the devices file.
.
.HP
\fB--devicesfile\fP \fIString\fP
.br
A file listing devices that LVM should use.
The file must exist in \fI#DEFAULT_SYS_DIR#/devices/\fP and is managed
with the \fBlvmdevices\fP(8) command.
This overrides the \fBlvm.conf\fP(5) \fBdevices/devicesfile\fP and
\fBdevices/use_devicesfile\fP settings.
.
.HP
\fB--driverloaded\fP \fBy\fP|\fBn\fP
.br
If set to no, the command will not attempt to use device-mapper.
For testing and debugging.
.
.HP
\fB-h\fP|\fB--help\fP
.br
Display help text.
.
.HP
\fB--journal\fP \fIString\fP
.br
Record information in the systemd journal.
This information is in addition to information
enabled by the lvm.conf log/journal setting.
command: record information about the command.
output: record the default command output.
debug: record full command debugging.
.
.HP
\fB--lockopt\fP \fIString\fP
.br
Used to pass options for special cases to lvmlockd.
See \fBlvmlockd\fP(8) for more information.
.
.HP
\fB--longhelp\fP
.br
Display long help text.
.
.HP
\fB--nohints\fP
.br
Do not use the hints file to locate devices for PVs. A command may read
more devices to find PVs when hints are not used. The command will still
perform standard hint file invalidation where appropriate.
.
.HP
\fB--nolocking\fP
.br
Disable locking. Use with caution, concurrent commands may produce
incorrect results.
.
.HP
\fB--profile\fP \fIString\fP
.br
An alias for --commandprofile or --metadataprofile, depending
on the command.
.
.HP
\fB-q\fP|\fB--quiet\fP ...
.br
Suppress output and log messages. Overrides --debug and --verbose.
Repeat once to also suppress any prompts with answer 'no'.
.
.HP
\fB--refresh\fP
.br
Search for missing PVs on new devices, and update the devices file
with new device IDs for the PVs if they are found on new devices.
This is useful if PVs have been moved to new devices with new WWIDs,
for example. The device ID type and name may both change for a PV.
WARNING: if a PV is detached from the system, but a device containing a
clone or snapshot of that PV is present, then refresh would replace the
correct device ID with the clone/snapshot device ID, and lvm would begin
using the wrong device for the PV. Use deldev/adddev to safely change
a PV device ID in this scenario.
.
.HP
\fB-t\fP|\fB--test\fP
.br
Run in test mode. Commands will not update metadata.
This is implemented by disabling all metadata writing but nevertheless
returning success to the calling function. This may lead to unusual
error messages in multi-stage operations if a tool relies on reading
back metadata it believes has changed but hasn't.
.
.HP
\fB--update\fP
.br
Update the content of the devices file.
.
.HP
\fB-v\fP|\fB--verbose\fP ...
.br
Set verbose level. Repeat from 1 to 4 times to increase the detail
of messages sent to stdout and stderr.
.
.HP
\fB--version\fP
.br
Display version information.
.
.HP
\fB-y\fP|\fB--yes\fP
.br
Do not prompt for confirmation interactively but always assume the
answer yes. Use with extreme caution.
(For automatic no, see -qq.)
.
.SH VARIABLES
.
.TP
.I String
See the option description for information about the string content.
.TP
.IR Size [UNIT]
Size is an input number that accepts an optional unit.
Input units are always treated as base two values, regardless of
capitalization, e.g. 'k' and 'K' both refer to 1024.
The default input unit is specified by letter, followed by |UNIT.
UNIT represents other possible input units:
.BR b | B
is bytes,
.BR s | S
is sectors of 512 bytes,
.BR k | K
is KiB,
.BR m | M
is MiB,
.BR g | G
is GiB,
.BR t | T
is TiB,
.BR p | P
is PiB,
.BR e | E
is EiB.
(This should not be confused with the output control --units, where
capital letters mean multiple of 1000.)
.
.SH ENVIRONMENT VARIABLES
.
See \fBlvm\fP(8) for information about environment variables used by lvm.
For example, LVM_VG_NAME can generally be substituted for a required VG parameter.