From cbab226a74fbaaa43220dee80e8435555c6506ce Mon Sep 17 00:00:00 2001 From: Karol Lewandowski Date: Tue, 23 Jan 2024 12:58:00 +0100 Subject: Imported Upstream version 2.03.22 --- man/lvm.8_main | 589 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 589 insertions(+) create mode 100644 man/lvm.8_main (limited to 'man/lvm.8_main') diff --git a/man/lvm.8_main b/man/lvm.8_main new file mode 100644 index 0000000..4710963 --- /dev/null +++ b/man/lvm.8_main @@ -0,0 +1,589 @@ +.TH LVM 8 "LVM TOOLS #VERSION#" "Red Hat, Inc." \" -*- nroff -*- +. +.SH NAME +. +lvm \(em LVM2 tools +. +.SH SYNOPSIS +. +.B lvm +.RI [ command | file ] +. +.SH DESCRIPTION +. +The Logical Volume Manager (LVM) provides tools to create virtual block +devices from physical devices. Virtual devices may be easier to manage +than physical devices, and can have capabilities beyond what the physical +devices provide themselves. A Volume Group (VG) is a collection of one or +more physical devices, each called a Physical Volume (PV). A Logical +Volume (LV) is a virtual block device that can be used by the system or +applications. Each block of data in an LV is stored on one or more PV in +the VG, according to algorithms implemented by Device Mapper (DM) in the +kernel. +.P +The lvm command, and other commands listed below, are the command-line +tools for LVM. A separate manual page describes each command in detail. +.P +If \fBlvm\fP is invoked with no arguments it presents a #DEFAULT_LIBLINE# prompt +(assuming it was compiled with #DEFAULT_LIBLINE# support). +LVM commands may be entered interactively at this prompt with +#DEFAULT_LIBLINE# facilities including history and command name and option +completion. Refer to \fB#DEFAULT_LIBLINE#\fP(3) for details. +.P +If \fBlvm\fP is invoked with argv[0] set to the name of a specific +LVM command (for example by using a hard or soft link) it acts as +that command. +.P +On invocation, \fBlvm\fP requires that only the standard file descriptors +stdin, stdout and stderr are available. If others are found, they +get closed and messages are issued warning about the leak. +This warning can be suppressed by setting the environment variable +.BR LVM_SUPPRESS_FD_WARNINGS . +.P +Where commands take VG or LV names as arguments, the full path name is +optional. An LV called "lvol0" in a VG called "vg0" can be specified +as "vg0/lvol0". Where a list of VGs is required but is left empty, +a list of all VGs will be substituted. Where a list of LVs is required +but a VG is given, a list of all the LVs in that VG will be substituted. +So \fBlvdisplay vg0\fP will display all the LVs in "vg0". +Tags can also be used - see \fB--addtag\fP below. +.P +One advantage of using the built-in shell is that configuration +information gets cached internally between commands. +.P +A file containing a simple script with one command per line +can also be given on the command line. The script can also be +executed directly if the first line is #! followed by the absolute +path of \fBlvm\fP. +.P +Additional hyphens within option names are ignored. For example, +\fB--readonly\fP and \fB--read-only\fP are both accepted. +. +.SH BUILT-IN COMMANDS +. +The following commands are built into lvm without links +normally being created in the filesystem for them. +.sp +.PD 0 +.TP 16 +.B config +The same as \fBlvmconfig\fP(8) below. +.TP +.B devtypes +Display the recognised built-in block device types. +.TP +.B dumpconfig +The same as \fBlvmconfig\fP(8) below. +.TP +.B formats +Display recognised metadata formats. +.TP +.B fullreport +Report information about PVs, PV segments, VGs, LVs and LV segments, +all at once. +.TP +.B help +Display the help text. +.TP +.B lastlog +Display log report of last command run in LVM shell +if command log reporting is enabled. +.TP +.B lvpoll +Complete lvmpolld operations (Internal command). +.TP +.B segtypes +Display recognised Logical Volume segment types. +.TP +.B systemid +Display any system ID currently set on this host. +.TP +.B tags +Display any tags defined on this host. +.TP +.B version +Display version information. +.PD +. +.SH COMMANDS +. +The following commands implement the core LVM functionality. +.sp +.PD 0 +.TP 16 +.B pvchange +Change attributes of a Physical Volume. +.TP +.B pvck +Check Physical Volume metadata. +.TP +.B pvcreate +Initialize a disk or partition for use by LVM. +.TP +.B pvdisplay +Display attributes of a Physical Volume. +.TP +.B pvmove +Move Physical Extents. +.TP +.B pvremove +Remove a Physical Volume. +.TP +.B pvresize +Resize a disk or partition in use by LVM2. +.TP +.B pvs +Report information about Physical Volumes. +.TP +.B pvscan +Scan all disks for Physical Volumes. +.TP +.B vgcfgbackup +Backup Volume Group descriptor area. +.TP +.B vgcfgrestore +Restore Volume Group descriptor area. +.TP +.B vgchange +Change attributes of a Volume Group. +.TP +.B vgck +Check Volume Group metadata. +.TP +.B vgconvert +Convert Volume Group metadata format. +.TP +.B vgcreate +Create a Volume Group. +.TP +.B vgdisplay +Display attributes of Volume Groups. +.TP +.B vgexport +Make volume Groups unknown to the system. +.TP +.B vgextend +Add Physical Volumes to a Volume Group. +.TP +.B vgimport +Make exported Volume Groups known to the system. +.TP +.B vgimportclone +Import and rename duplicated Volume Group (e.g. a hardware snapshot). +.TP +.B vgimportdevices +Add PVs from a VG to the devices file. +.TP +.B vgmerge +Merge two Volume Groups. +.TP +.B vgmknodes +Recreate Volume Group directory and Logical Volume special files +.TP +.B vgreduce +Reduce a Volume Group by removing one or more Physical Volumes. +.TP +.B vgremove +Remove a Volume Group. +.TP +.B vgrename +Rename a Volume Group. +.TP +.B vgs +Report information about Volume Groups. +.TP +.B vgscan +Scan all disks for Volume Groups. +.TP +.B vgsplit +Split a Volume Group into two, moving any logical +volumes from one Volume Group to another by moving entire Physical +Volumes. +.TP +.B lvchange +Change attributes of a Logical Volume. +.TP +.B lvconvert +Convert a Logical Volume from linear to mirror or snapshot. +.TP +.B lvcreate +Create a Logical Volume in an existing Volume Group. +.TP +.B lvdisplay +Display attributes of a Logical Volume. +.TP +.B lvextend +Extend the size of a Logical Volume. +.TP +.B lvmconfig +Display the configuration information after +loading \fBlvm.conf\fP(5) and any other configuration files. +.TP +.B lvmdevices +Manage the devices file. +.TP +.B lvmdiskscan +Scan for all devices visible to LVM2. +.TP +.B lvmdump +Create lvm2 information dumps for diagnostic purposes. +.TP +.B lvreduce +Reduce the size of a Logical Volume. +.TP +.B lvremove +Remove a Logical Volume. +.TP +.B lvrename +Rename a Logical Volume. +.TP +.B lvresize +Resize a Logical Volume. +.TP +.B lvs +Report information about Logical Volumes. +.TP +.B lvscan +Scan (all disks) for Logical Volumes. +.PD +.P +The following LVM1 commands are not implemented in LVM2: +.BR lvmchange ", " lvmsadc ", " lvmsar ", " pvdata . +For performance metrics, use \fBdmstats\fP(8) or to manipulate the kernel +device-mapper driver used by LVM2 directly, use \fBdmsetup\fP(8). +. +.SH VALID NAMES +. +The valid characters for VG and LV names are: +.BR a - z +.BR A - Z +.BR 0 - 9 +.B + _ . - +.P +VG names cannot begin with a hyphen. +The name of a new LV also cannot begin with a hyphen. However, if the +configuration setting \fBmetadata/record_lvs_history\fP is enabled then an LV +name with a hyphen as a prefix indicates that, although the LV was +removed, it is still being tracked because it forms part of the history of at +least one LV that is still present. This helps to record the ancestry of +thin snapshots even after some links in the chain have been removed. +A reference to the historical LV 'lvol1' in VG 'vg00' would be 'vg00/-lvol1' +or just '-lvol1' if the VG is already set. (The latter form must be preceded +by '--' to terminate command line option processing before reaching this +argument.) +.P +There are also various reserved names that are used internally by lvm that can +not be used as LV or VG names. A VG cannot be called anything that exists in +\fI/dev/\fP at the time of creation, nor can it be called +.RB ' . ' +or +.RB ' .. '. +An LV cannot be called +.RB ' . ', +.RB ' .. ', +.RB ' snapshot ' +or +.RB ' pvmove '. +The LV name may also not contain any of the following strings: +.RB ' _cdata ', +.RB ' _cmeta ', +.RB ' _corig ', +.RB ' _iorig ', +.RB ' _mimage ', +.RB ' _mlog ', +.RB ' _pmspare ', +.RB ' _rimage ', +.RB ' _rmeta ', +.RB ' _tdata ', +.RB ' _tmeta ', +.RB ' _vdata ', +.RB ' _vorigin ' +or +.RB ' _wcorig '. +A directory bearing the name of each Volume Group is created under +\fI/dev\fP when any of its Logical Volumes are activated. +Each active Logical Volume is accessible from this directory as a symbolic +link leading to a device node. +Links or nodes in \fI/dev/mapper\fP are intended only for internal use and +the precise format and escaping might change between releases and distributions. +Other software and scripts should use the +\fI/dev/VolumeGroupName/LogicalVolumeName\fP format to reduce the chance of needing +amendment when the software is updated. Should you need to process the node +names in /dev/mapper, you may use \fBdmsetup splitname\fP to separate out the +original VG, LV and internal layer names. +.P +. +.SH UNIQUE NAMES +. +VG names should be unique. vgcreate will produce an error if the +specified VG name matches an existing VG name. However, there are cases +where different VGs with the same name can appear to LVM, e.g. after +moving disks or changing filters. +.P +When VGs with the same name exist, commands operating on all VGs will +include all of the VGs with the same name. If the ambiguous VG name is +specified on the command line, the command will produce an error. The +error states that multiple VGs exist with the specified name. To process +one of the VGs specifically, the --select option should be used with the +UUID of the intended VG: --select vg_uuid= +.P +An exception is if all but one of the VGs with the shared name is foreign +(see +.BR lvmsystemid (7)). +In this case, the one VG that is not foreign is assumed to be the intended +VG and is processed. +.P +LV names are unique within a VG. The name of an historical LV cannot be +reused until the historical LV has itself been removed or renamed. +. +.SH ALLOCATION +. +When an operation needs to allocate Physical Extents for one or more +Logical Volumes, the tools proceed as follows: +.P +First of all, they generate the complete set of unallocated Physical Extents +in the Volume Group. If any ranges of Physical Extents are supplied at +the end of the command line, only unallocated Physical Extents within +those ranges on the specified Physical Volumes are considered. +.P +Then they try each allocation policy in turn, starting with the strictest +policy (\fBcontiguous\fP) and ending with the allocation policy specified +using \fB--alloc\fP or set as the default for the particular Logical +Volume or Volume Group concerned. For each policy, working from the +lowest-numbered Logical Extent of the empty Logical Volume space that +needs to be filled, they allocate as much space as possible according to +the restrictions imposed by the policy. If more space is needed, +they move on to the next policy. +.P +The restrictions are as follows: +.P +\fBContiguous\fP requires that the physical location of any Logical +Extent that is not the first Logical Extent of a Logical Volume is +adjacent to the physical location of the Logical Extent immediately +preceding it. +.P +\fBCling\fP requires that the Physical Volume used for any Logical +Extent to be added to an existing Logical Volume is already in use by at +least one Logical Extent earlier in that Logical Volume. If the +configuration parameter \fBallocation/cling_tag_list\fP is defined, then two +Physical Volumes are considered to match if any of the listed tags is +present on both Physical Volumes. This allows groups of Physical +Volumes with similar properties (such as their physical location) to be +tagged and treated as equivalent for allocation purposes. +.P +When a Logical Volume is striped or mirrored, the above restrictions are +applied independently to each stripe or mirror image (leg) that needs +space. +.P +\fBNormal\fP will not choose a Physical Extent that shares the same Physical +Volume as a Logical Extent already allocated to a parallel Logical +Volume (i.e. a different stripe or mirror image/leg) at the same offset +within that parallel Logical Volume. +.P +When allocating a mirror log at the same time as Logical Volumes to hold +the mirror data, Normal will first try to select different Physical +Volumes for the log and the data. If that's not possible and the +.B allocation/mirror_logs_require_separate_pvs +configuration parameter is set to 0, it will then allow the log +to share Physical Volume(s) with part of the data. +.P +When allocating thin pool metadata, similar considerations to those of a +mirror log in the last paragraph apply based on the value of the +.B allocation/thin_pool_metadata_require_separate_pvs +configuration parameter. +.P +If you rely upon any layout behaviour beyond that documented here, be +aware that it might change in future versions of the code. +.P +For example, if you supply on the command line two empty Physical +Volumes that have an identical number of free Physical Extents available for +allocation, the current code considers using each of them in the order +they are listed, but there is no guarantee that future releases will +maintain that property. If it is important to obtain a specific layout +for a particular Logical Volume, then you should build it up through a +sequence of \fBlvcreate\fP(8) and \fBlvconvert\fP(8) steps such that the +restrictions described above applied to each step leave the tools no +discretion over the layout. +.P +To view the way the allocation process currently works in any specific +case, read the debug logging output, for example by adding \fB-vvvv\fP to +a command. +. +.SH LOGICAL VOLUME TYPES +. +Some logical volume types are simple to create and can be done with a +single \fBlvcreate\fP(8) command. The linear and striped logical +volume types are an example of this. Other logical volume types may +require more than one command to create. The cache (\fBlvmcache\fP(7)) +and thin provisioning (\fBlvmthin\fP(7)) types are examples of this. +. +.SH DIAGNOSTICS +. +All tools return a status code of zero on success or non-zero on failure. +The non-zero codes distinguish only between the broad categories of +unrecognised commands, problems processing the command line arguments +and any other failures. As LVM remains under active development, the +code used in a specific case occasionally changes between releases. +Message text may also change. +. +.SH ENVIRONMENT VARIABLES +. +.TP +.B HOME +Directory containing \fI.lvm_history\fP if the internal #DEFAULT_LIBLINE# +shell is invoked. +.TP +.B LVM_OUT_FD +File descriptor to use for common output from LVM commands. +.TP +.B LVM_ERR_FD +File descriptor to use for error output from LVM commands. +.TP +.B LVM_REPORT_FD +File descriptor to use for report output from LVM commands. +.TP +.B LVM_COMMAND_PROFILE +Name of default command profile to use for LVM commands. This profile +is overridden by direct use of \fB--commandprofile\fP command line option. +.TP +.B LVM_RUN_BY_DMEVENTD +This variable is normally set by dmeventd plugin to inform lvm2 command +it is running from dmeventd plugin so lvm2 takes some extra action +to avoid communication and deadlocks with dmeventd. +.TP +.B LVM_SYSTEM_DIR +Directory containing \fBlvm.conf\fP(5) and other LVM system files. +Defaults to "\fI#DEFAULT_SYS_DIR#\fP". +.TP +.B LVM_SUPPRESS_FD_WARNINGS +Suppress warnings about unexpected file descriptors passed into LVM. +.TP +.B LVM_SUPPRESS_SYSLOG +Suppress contacting syslog. +.TP +.B LVM_VG_NAME +The Volume Group name that is assumed for +any reference to a Logical Volume that doesn't specify a path. +Not set by default. +.TP +.B LVM_LVMPOLLD_PIDFILE +Path to the file that stores the lvmpolld process ID. +.TP +.B LVM_LVMPOLLD_SOCKET +Path to the socket used to communicate with lvmpolld.. +.TP +.B LVM_LOG_FILE_EPOCH +A string of up to 32 letters appended to the log filename and +followed by the process ID and a startup timestamp using +this format string "_%s_%d_%llu". When set, each process logs to a +separate file. +.TP +.B LVM_LOG_FILE_MAX_LINES +If more than this number of lines are sent to the log file, the command gets +aborted. Automated tests use this to terminate looping commands. +.TP +.B LVM_EXPECTED_EXIT_STATUS +The status anticipated when the process exits. Use ">N" to match any +status greater than N. If the actual exit status matches and a log +file got produced, it is deleted. +.B LVM_LOG_FILE_EPOCH +and +.B LVM_EXPECTED_EXIT_STATUS +together allow automated test scripts to discard uninteresting log data. +.TP +.B LVM_SUPPRESS_LOCKING_FAILURE_MESSAGES +Used to suppress warning messages when the configured locking is known +to be unavailable. +.TP +.B DM_ABORT_ON_INTERNAL_ERRORS +Abort processing if the code detects a non-fatal internal error. +.TP +.B DM_DISABLE_UDEV +Avoid interaction with udev. LVM will manage the relevant nodes in /dev +directly. +.TP +.B DM_DEBUG_WITH_LINE_NUMBERS +Prepends source file name and code line number with libdm debugging. +. +.SH FILES +. +.I #DEFAULT_SYS_DIR#/lvm.conf +.br +.I $HOME/.lvm_history +. +.SH SEE ALSO +. +.nh +.ad l +.BR lvm (8), +.BR lvm.conf (5), +.BR lvmconfig (8), +.BR lvmdevices (8), +.P +.BR pvchange (8), +.BR pvck (8), +.BR pvcreate (8), +.BR pvdisplay (8), +.BR pvmove (8), +.BR pvremove (8), +.BR pvresize (8), +.BR pvs (8), +.BR pvscan (8), +.P +.BR vgcfgbackup (8), +.BR vgcfgrestore (8), +.BR vgchange (8), +.BR vgck (8), +.BR vgcreate (8), +.BR vgconvert (8), +.BR vgdisplay (8), +.BR vgexport (8), +.BR vgextend (8), +.BR vgimport (8), +.BR vgimportclone (8), +.BR vgimportdevices (8), +.BR vgmerge (8), +.BR vgmknodes (8), +.BR vgreduce (8), +.BR vgremove (8), +.BR vgrename (8), +.BR vgs (8), +.BR vgscan (8), +.BR vgsplit (8), +.P +.BR lvcreate (8), +.BR lvchange (8), +.BR lvconvert (8), +.BR lvdisplay (8), +.BR lvextend (8), +.BR lvreduce (8), +.BR lvremove (8), +.BR lvrename (8), +.BR lvresize (8), +.BR lvs (8), +.BR lvscan (8), +.P +.BR lvm-fullreport (8), +.BR lvm-lvpoll (8), +.BR blkdeactivate (8), +.BR lvmdump (8), +.P +.BR dmeventd (8), +.BR lvmpolld (8), +.BR lvmlockd (8), +.BR lvmlockctl (8), +.BR cmirrord (8), +.BR lvmdbusd (8), +.BR fsadm (8), +.P +.BR lvmsystemid (7), +.BR lvmreport (7), +.BR lvmcache (7), +.BR lvmraid (7), +.BR lvmthin (7), +.BR lvmvdo (7), +.BR lvmautoactivation (7), +.P +.BR dmsetup (8), +.BR dmstats (8), +.BR #DEFAULT_LIBLINE# (3) -- cgit v1.2.3