lvm2/man/lvmdevices.8_pregen

.TH LVMDEVICES 8 "LVM TOOLS #VERSION#" "Red Hat, Inc."
.
.ie t \{\
.\" PostScript/PDF with tabs
. ds TT \t
. ds DTT \t\t
.\}
.el \{\
. ds TT \&
. ds DTT \0\0\0
.\}
.
.de OPT
.ie \\n(.$>1 \\*[TT]\fB-\\$1\fP|\\*[TT]\fB--\\$2\fP\c
.el \\*[DTT]\fB--\\$1\fP\c
..
.
.de OPA
.OPT \\$*
\ \c
..
.de OPS
.OPT \\$*
\&
..
.
.
.\"List of all options as O_string.
.
.de O_adddev
.OPA adddev
\fIPV\fP
..
.de O_addid
.OPA addid
\fIString\fP
..
.de O_addpvid
.OPA addpvid
\fIString\fP
..
.de O_check
.OPS check
..
.de O_commandprofile
.OPA commandprofile
\fIString\fP
..
.de O_config
.OPA config
\fIString\fP
..
.de O_debug
.OPA d debug
\&\.\|.\|.\&
..
.de O_deldev
.OPA deldev
\fIString\fP
..
.de O_delid
.OPA delid
\fIString\fP
..
.de O_delnotfound
.OPS delnotfound
..
.de O_delpvid
.OPA delpvid
\fIString\fP
..
.de O_deviceidtype
.OPA deviceidtype
\fIString\fP
..
.de O_devices
.OPA devices
\fIPV\fP
..
.de O_devicesfile
.OPA devicesfile
\fIString\fP
..
.de O_driverloaded
.OPA driverloaded
\fBy\fP|\fBn\fP
..
.de O_force
.OPA f force
\&\.\|.\|.\&
..
.de O_help
.OPS h help
..
.de O_journal
.OPA journal
\fIString\fP
..
.de O_listids
.OPA listids
\fIPV\fP
..
.de O_lockopt
.OPA lockopt
\fIString\fP
..
.de O_longhelp
.OPS longhelp
..
.de O_nohints
.OPS nohints
..
.de O_nolocking
.OPS nolocking
..
.de O_profile
.OPA profile
\fIString\fP
..
.de O_quiet
.OPA q quiet
\&\.\|.\|.\&
..
.de O_refresh
.OPS refresh
..
.de O_test
.OPS t test
..
.de O_update
.OPS update
..
.de O_verbose
.OPA v verbose
\&\.\|.\|.\&
..
.de O_version
.OPS version
..
.de O_yes
.OPS y yes
..
.
.SH NAME
.
lvmdevices \(em Manage the devices file
.
.SH SYNOPSIS
.
.nh
.TP
\fBlvmdevices\fP \fIoption_args\fP
[ \fIoption_args\fP ]
.P
.na
.RS 5
.if t .ta 3nR +1uL \" PostScript/PDF
.PD 0
.O_adddev
.br
.O_addid
.br
.O_addpvid
.br
.O_check
.br
.O_commandprofile
.br
.O_config
.br
.O_debug
.br
.O_deldev
.br
.O_delid
.br
.O_delnotfound
.br
.O_delpvid
.br
.O_deviceidtype
.br
.O_devices
.br
.O_devicesfile
.br
.O_driverloaded
.br
.O_force
.br
.O_help
.br
.O_journal
.br
.O_listids
.br
.O_lockopt
.br
.O_longhelp
.br
.O_nohints
.br
.O_nolocking
.br
.O_profile
.br
.O_quiet
.br
.O_refresh
.br
.O_test
.br
.O_update
.br
.O_verbose
.br
.O_version
.br
.O_yes
.PD
.if t .ta
.RE
.ad
.hy
.
.ds TT \&
.ds DTT \&
.
.
.SH DESCRIPTION
.
The LVM devices file is the list of devices that lvm commands will use.
It is located at \fI#DEFAULT_SYS_DIR#/devices/system.devices\fP.
The \fBlvmdevices\fP(8) command manages the file, and is used to
add, remove and list devices.
.P
.SS Listing devices
.
Run the lvmdevices command with no options or arguments to display the
entries in system.devices:
.br
.B lvmdevices
.P
Each line begins with a current device name from the system, followed by
its device ID from the devices file, followed by other device details used by lvm.
A line begins with "Device none" if no device on the system matches the device ID.
(Viewing the system.devices file directly does not indicate if a device is present
on the system.)
.P
.SS Adding devices
.
To use a device with lvm, add it to the devices file with one of the
following commands.
.P
Add a device by referencing its device path:
.br
.B lvmdevices --adddev
.I device
.P
Add a device by referencing its PVID:
.br
.B lvmdevices --addpvid
.I PVID
.P
Add a device by referencing its device ID:
.br
.B lvmdevices --addid
.I IDNAME
.B --deviceidtype
.I IDTYPE
.P
Add all of the PVs in a VG:
.br
.B vgimportdevices
.I VG
.P
Add all of the PVs in all visible VGs:
.br
.B vgimportdevices -a
.P
.B pvcreate,
.B vgcreate,
and
.B vgextend
also look outside of the existing devices file to find the target device,
and automatically add it to the devices file.
.P
.SS Removing devices
.
Removing a device from the devices file will prevent lvm from
seeing or using that device.  Remove a device with one of the
following commands.
.P
Remove a device by referencing its device path:
.br
.B lvmdevices --deldev
.I device
.P
Remove a device by referencing its PVID:
.br
.B lvmdevices --delpvid
.I PVID
.P
Remove a device by referencing its device ID:
.br
.B lvmdevices --delid
.I IDNAME
.B --deviceidtype
.I IDTYPE
.P
.SS device IDs
.
LVM identifies devices in the devices file using hardware-specific IDs,
such as the WWID or serial number.  Subsystem-specific IDs are used for
virtual device types, which also aim to be unique and stable.
When no hardware or subsystem ID is available, lvm falls back using the
device name as the device ID.  Using device names as IDs is not optimal
because they are not stable, and will often change after reboot.  When
device names are used as IDs, lvm must perform extra device scanning
to locate devices if the device name changes.
.P
When stable device IDs are used, lvm will not access devices outside of
those listed in the devices file.  When device names are used as IDs, lvm
will scan devices outside the devices file to locate PVs on devices that
changed names.  The config setting search_for_devnames can be used to
control lvm's behavior in locating renamed devname entries.
.P
A device ID has two parts: an IDTYPE and an IDNAME.
.P
The IDTYPE specifies the origin of the ID, and the IDNAME is the
actual identifier.  There is a predefined set of IDTYPEs listed
in the next section.  A devices file entry must have one of these
ID types.  When adding a device to the devices file, lvm automatically
chooses the best IDTYPE, which can be overridden with the --deviceidtype
option (this is not generally recommended.)
.P
To display all of the possible device IDs for a device, or the value
of one specific type, use the commands:
.P
.br
.B lvmdevices --listids
.I device
.br
.B lvmdevices --listids
.I device
.B --deviceidtype
.I IDTYPE
.P
.SS device ID types
.
The available 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]
.B wwid_naa
uses the naa wwid decoded from the vpd_pg83 sysfs file.
.IP \[bu]
.B wwid_eui
uses the eui wwid decoded from the vpd_pg83 sysfs file.
.IP \[bu]
.B wwid_t10
uses the t10 wwid decoded from the vpd_pg83 sysfs file.
.IP \[bu]
.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]
.B mpath_uuid
is used for dm multipath devices, reported by sysfs.
.IP \[bu]
.B crypt_uuid
is used for dm crypt devices, reported by sysfs.
.IP \[bu]
.B md_uuid
is used for md devices, reported by sysfs.
.IP \[bu]
.B lvmlv_uuid
is used if a PV is placed on top of an lvm LV, reported by sysfs.
.IP \[bu]
.B loop_file
is used for loop devices, the backing file name reported by sysfs.
.IP \[bu]
.B devname
the device name is used if no other type applies.
.IP \[bu]
.B nvme_uuid, nvme_nguid, nvme_eui64
are not generally used, but may appear for nvme devices that report
invalid wwid values.
.P
.SS sysfs files
Most of the device ID types read the device ID value from sysfs.
Those sysfs values can also be read directly from the following paths:
.P
.nf
/sys/dev/block/\fImajor\fP:\fIminor\fP/device/wwid
/sys/dev/block/\fImajor\fP:\fIminor\fP/device/serial
/sys/dev/block/\fImajor\fP:\fIminor\fP/wwid
/sys/dev/block/\fImajor\fP:\fIminor\fP/device/vpd_pg83 (binary)
/sys/dev/block/\fImajor\fP:\fIminor\fP/device/vpd_pg80 (binary)
/sys/dev/block/\fImajor\fP:\fIminor\fP/dm/uuid (lvm reads via ioctl)
/sys/dev/block/\fImajor\fP:\fIminor\fP/md/uuid
/sys/dev/block/\fImajor\fP:\fIminor\fP/loop/backing_file
.fi
.P
(Some sysfs values are modified before being used as the device ID,
e.g. spaces omitted or replaced with underscores.)
.P
.SS devices file contents
.
LVM writes some additional information to the devices file in addition to
the device IDs.  LVM commands automatically update this information if it
changes.  This includes the last known device name, and the PV UUID (PVID)
from the LVM disk header.
.P
Check if the devices file content needs to be updated:
.br
.B lvmdevices --check
.P
Update devices file fields that are outdated:
.br
.B lvmdevices --update
.P
The devices file is meant to be edited by lvm commands, not by the user.
The devices file contains a HASH value which lvm uses to detect if the
file has been modified since lvm last wrote it.
When lvm updates the devices file, the previous version is moved to
/etc/lvm/devices/backup/.
.P
The following fields can be found in the devices file:
.br
VERSION: incremented for each file update.
.br
PRODUCT_UUID: a unique machine ID used to detect if the system.devices
file has been moved to a new machine, and may require updating.
When not available, HOSTNAME is used.
.P
Device entry fields:
.br
IDTYPE: indicates the source of the device ID value in IDNAME.
.br
IDNAME: the unique device ID value.
.br
DEVNAME: the most recent device name associated with the device ID.
.br
PVID: the LVM PV UUID from the LVM disk header.
.br
PART: the partition number if a PV exists on a partition.
.P
.SS device ID refresh
.
When lvm writes system.devices, it includes a local machine ID in the
system.devices file (as PRODUCT_UUID or HOSTNAME.)  When lvm reads
system.devices, it compares this saved machine ID to the current machine,
which allows lvm to detect when system.devices has been copied or restored
onto a different machine.  When a machine change is detected, lvm enables
a "device ID refresh" mode (configured by lvm.conf device_ids_refresh and
device_ids_refresh_checks.)
.P
In refresh mode, a device in system.devices that is not found by its device ID
will be located using its PVID.  LVM will scan all devices on the system to
search for the missing PVIDs in system.devices.  If a PVID is found on a
new device, the system.devices entry is updated with a new device ID matching
the new device on which the PVID was found.  The refresh mode can be configured
to run once, when the machine change is first detected, or can be enabled
for period of time following the first refresh, or can be disabled
entirely.
.P
.B device_ids_refresh = 0
.br
Disables refresh mode.
.P
.B device_ids_refresh = 1
.br
Enables one attempt to refresh device IDs when a machine
change is first detected.
.P
.B device_ids_refresh =
.I seconds
.br
The refresh mode is enabled for this number of seconds
following the initial refresh attempt, or until all PVs
in system.devices are found.  During this period, a
REFRESH_UNTIL line appears in system.devices.  Accepted
values are 10-600 seconds.
.P
In addition to the automated device ID refresh mode, refresh
can be performed manually:
.P
Check if system.devices would be updated with new device IDs:
.br
.B lvmdevices --check --refresh
.P
Update system.devices with new device IDs if PVs are found on new devices:
.br
.B lvmdevices --update --refresh
.P
The machine ID used in system.devices will be either the DMI product_uuid from
.IR /sys/devices/virtual/dmi/id/product_uuid ,
or the hostname from
.BR uname (2).
See
.BR lvm.conf (5)
.B device_ids_refresh_checks
to configure this.
.P
.SS custom devices files
.
Multiple devices files can be kept in #DEFAULT_SYS_DIR#/devices, which
allows lvm to be used with different sets of devices.  For example, a
given application may not need to access the system's devices, and the
system may not need to access the application's devices.  In this case,
system.devices could list only the system's devices and
<application>.devices file could list only the application's devices.  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
If the special devices file \fI#DEFAULT_SYS_DIR#/devices/dmeventd.devices\fP
exists, then dmeventd uses dmeventd.devices instead of system.devices.
Using dmeventd.devices is necessary if VGs from separate devices files
require the services of dmeventd.  In this case, dmeventd.devices should
list devices from all of the VGs that require dmeventd.
.P
.SS disabling and overriding
.
There are multiple ways that the devices file feature can be disabled
or overridden:
.P
.IP \[bu] 2
no system.devices
.br
If the system.devices file does not exist, then the devices file feature
is disabled.
.IP \[bu] 2
.B use_devicesfile=0
.br
If lvm.conf use_devicesfile is set to 0, then the devices file feature
is disabled, even if the system.devices file exists.
.br
.IP \[bu] 2
.B --devicesfile\ ""
.br
If an empty devices file name is specified on the command line, then
that command will not use a devices file.
.br
.IP \[bu] 2
.B --devices
.I device
.br
If specific devices are named on the command line with --devices,
then the command will not use a devices file, and will only access
the named devices.
.IP \[bu] 2
.B pvs -A
.br
If given the -A or --allpvs option, the \fBpvs\fP(8) command will
not use a devices file.
.P
When the devices file is disabled, lvm commands revert to using the
lvm.conf filter.
When the devices file is used, lvm commands ignore the lvm.conf
filter setting, except for vgimportdevices which does apply the
regex filter to the set of devices on the system when looking for
VGs to import to the devices file.
.P
.SS VG metadata
.
LVM commands that write VG metadata will include the device ID of each
PV in the VG metadata.  The device ID can be displayed with the options:
.P
.B pvs -o deviceidtype,deviceid
.P
(Note that the lvmdevices command does not update VG metadata, but
subsequent lvm commands modifying the metadata will include the device
ID.)
.P
.SS creating the devices file
.P
If the system.devices file does not yet exist, the pvcreate or vgcreate
commands will create it only if they see no existing VGs on the system.
lvmdevices --adddev and vgimportdevices will always create a new devices file
if it does not yet exist.
.P
.
.SH USAGE
.
.nh
.na
Print devices in the devices file.
.P
.B lvmdevices
.RS
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Check the devices file and report incorrect values.
.P
.B lvmdevices
.O_check
.RS
[
.O_refresh
]
.br
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Update the devices file to fix incorrect values.
.P
.B lvmdevices
.O_update
.RS
[
.O_force
]
.br
[
.O_delnotfound
]
.br
[
.O_refresh
]
.br
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Add a device to the devices file.
.P
.B lvmdevices
.O_adddev
.RS
[
.O_deviceidtype
]
.br
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Remove a device from the devices file.
.P
.B lvmdevices
.O_deldev
.RS
[
.O_deviceidtype
]
.br
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Find the device with the given PVID and add it to the devices file.
.P
.B lvmdevices
.O_addpvid
.RS
[
.O_deviceidtype
]
.br
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Remove the devices file entry for the given PVID.
.P
.B lvmdevices
.O_delpvid
.RS
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Find the device with the given device_id and add it to the devices file.
.P
.B lvmdevices
.O_addid
.O_deviceidtype
.RS
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Remove the devices file entry with the given device_id.
.P
.B lvmdevices
.O_delid
.O_deviceidtype
.RS
[ COMMON_OPTIONS ]
.RE
.
.P
\(em
.P
.
Print device_id types and values available for the device.
.P
.B lvmdevices
.O_listids
.RS
[
.O_deviceidtype
]
.br
[ COMMON_OPTIONS ]
.RE
.P
\(em
.P
Common options for lvm:
.RS
[
.O_debug
]
.br
[
.O_help
]
.br
[
.O_quiet
]
.br
[
.O_test
]
.br
[
.O_verbose
]
.br
[
.O_yes
]
.br
[
.O_commandprofile
]
.br
[
.O_config
]
.br
[
.O_devices
]
.br
[
.O_devicesfile
]
.br
[
.O_driverloaded
]
.br
[
.O_journal
]
.br
[
.O_lockopt
]
.br
[
.O_longhelp
]
.br
[
.O_nohints
]
.br
[
.O_nolocking
]
.br
[
.O_profile
]
.br
[
.O_version
]
.RE
.hy
.ad
.
.SH OPTIONS
.
.TP
.O_adddev
Add a device to the devices file.
.
.TP
.O_addid
Find the device with the given device_id and add it to the devices file.
.
.TP
.O_addpvid
Find a device with the PVID and add the device to the devices file.
.
.TP
.O_check
Checks the content of the devices file.
Reports incorrect device names or PVIDs for entries.
.
.TP
.O_commandprofile
The command profile to use for command configuration.
See \fBlvm.conf\fP(5) for more information about profiles.
.
.TP
.O_config
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.
.
.TP
.O_debug
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).
.
.TP
.O_deldev
Remove a device from the devices file.
When used alone, --deldev specifies a device name.
When used with --deviceidtype, --deldev specifies a device id.
.
.TP
.O_delid
Remove the device with the specified device ID from the devices file.
.
.TP
.O_delnotfound
Remove devices file entries with no matching device.
.
.TP
.O_delpvid
Remove a device with the PVID from the devices file.
.
.TP
.O_deviceidtype
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.
.
.TP
.O_devices
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.
.
.TP
.O_devicesfile
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.
.
.TP
.O_driverloaded
If set to no, the command will not attempt to use device-mapper.
For testing and debugging.
.
.TP
.O_force
Override various checks, confirmations and protections.
Use with extreme caution.
.
.TP
.O_help
Display help text.
.
.TP
.O_journal
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.
.
.TP
.O_listids
Print a list of device IDs available for the device.
.
.TP
.O_lockopt
Used to pass options for special cases to lvmlockd.
See \fBlvmlockd\fP(8) for more information.
.
.TP
.O_longhelp
Display long help text.
.
.TP
.O_nohints
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.
.
.TP
.O_nolocking
Disable locking. Use with caution, concurrent commands may produce
incorrect results.
.
.TP
.O_profile
An alias for --commandprofile or --metadataprofile, depending
on the command.
.
.TP
.O_quiet
Suppress output and log messages. Overrides --debug and --verbose.
Repeat once to also suppress any prompts with answer 'no'.
.
.TP
.O_refresh
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.
.
.TP
.O_test
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.
.
.TP
.O_update
Update the content of the devices file.
.
.TP
.O_verbose
Set verbose level. Repeat from 1 to 4 times to increase the detail
of messages sent to stdout and stderr.
.
.TP
.O_version
Display version information.
.
.TP
.O_yes
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, \fBLVM_VG_NAME\fP can generally be substituted
for a required VG parameter.