1LVM(8)                      System Manager's Manual                     LVM(8)
2
3
4

NAME

6       lvm — LVM2 tools
7

SYNOPSIS

9       lvm [command|file]
10

DESCRIPTION

12       The Logical Volume Manager (LVM) provides tools to create virtual block
13       devices from physical devices.  Virtual devices may be easier to manage
14       than physical devices, and can have capabilities beyond what the physi‐
15       cal devices provide themselves.  A Volume Group (VG) is a collection of
16       one  or  more  physical devices, each called a Physical Volume (PV).  A
17       Logical Volume (LV) is a virtual block device that can be used  by  the
18       system  or  applications.  Each block of data in an LV is stored on one
19       or more PV in the VG, according to  algorithms  implemented  by  Device
20       Mapper (DM) in the kernel.
21
22       The  lvm command, and other commands listed below, are the command-line
23       tools for LVM.  A  separate  manual  page  describes  each  command  in
24       detail.
25
26       If  lvm  is  invoked  with  no  arguments it presents a readline prompt
27       (assuming it was compiled with readline support).  LVM commands may  be
28       entered interactively at this prompt with readline facilities including
29       history and command name and option completion.  Refer  to  readline(3)
30       for details.
31
32       If  lvm  is invoked with argv[0] set to the name of a specific LVM com‐
33       mand (for example by using a hard or soft link) it acts  as  that  com‐
34       mand.
35
36       On  invocation,  lvm  requires  that only the standard file descriptors
37       stdin, stdout and stderr are available.  If others are found, they  get
38       closed  and  messages  are issued warning about the leak.  This warning
39       can  be  suppressed  by  setting  the  environment  variable   LVM_SUP‐
40       PRESS_FD_WARNINGS.
41
42       Where  commands take VG or LV names as arguments, the full path name is
43       optional.  An LV called "lvol0" in a VG called "vg0" can  be  specified
44       as  "vg0/lvol0".   Where a list of VGs is required but is left empty, a
45       list of all VGs will be substituted.  Where a list of LVs  is  required
46       but  a  VG  is  given, a list of all the LVs in that VG will be substi‐
47       tuted.  So lvdisplay vg0 will display all the LVs in "vg0".   Tags  can
48       also be used - see --addtag below.
49
50       One  advantage of using the built-in shell is that configuration infor‐
51       mation gets cached internally between commands.
52
53       A file containing a simple script with one command per line can also be
54       given on the command line.  The script can also be executed directly if
55       the first line is #! followed by the absolute path of lvm.
56
57       Additional hyphens within  option  names  are  ignored.   For  example,
58       --readonly and --read-only are both accepted.
59

BUILT-IN COMMANDS

61       The  following commands are built into lvm without links normally being
62       created in the filesystem for them.
63
64       config        The same as lvmconfig(8) below.
65       devtypes      Display the recognised built-in block device types.
66       dumpconfig    The same as lvmconfig(8) below.
67       formats       Display recognised metadata formats.
68       fullreport    Report information about PVs, PV segments, VGs,  LVs  and
69                     LV segments, all at once.
70       help          Display the help text.
71       lastlog       Display  log  report  of last command run in LVM shell if
72                     command log reporting is enabled.
73       lvpoll        Complete lvmpolld operations (Internal command).
74       segtypes      Display recognised Logical Volume segment types.
75       systemid      Display any system ID currently set on this host.
76       tags          Display any tags defined on this host.
77       version       Display version information.
78

COMMANDS

80       The following commands implement the core LVM functionality.
81
82       pvchange      Change attributes of a Physical Volume.
83       pvck          Check Physical Volume metadata.
84       pvcreate      Initialize a disk or partition for use by LVM.
85       pvdisplay     Display attributes of a Physical Volume.
86       pvmove        Move Physical Extents.
87       pvremove      Remove a Physical Volume.
88       pvresize      Resize a disk or partition in use by LVM2.
89       pvs           Report information about Physical Volumes.
90       pvscan        Scan all disks for Physical Volumes.
91       vgcfgbackup   Backup Volume Group descriptor area.
92       vgcfgrestore  Restore Volume Group descriptor area.
93       vgchange      Change attributes of a Volume Group.
94       vgck          Check Volume Group metadata.
95       vgconvert     Convert Volume Group metadata format.
96       vgcreate      Create a Volume Group.
97       vgdisplay     Display attributes of Volume Groups.
98       vgexport      Make volume Groups unknown to the system.
99       vgextend      Add Physical Volumes to a Volume Group.
100       vgimport      Make exported Volume Groups known to the system.
101       vgimportclone Import and rename duplicated Volume Group (e.g.  a  hard‐
102                     ware snapshot).
103       vgmerge       Merge two Volume Groups.
104       vgmknodes     Recreate  Volume  Group directory and Logical Volume spe‐
105                     cial files
106       vgreduce      Reduce a Volume Group by removing one  or  more  Physical
107                     Volumes.
108       vgremove      Remove a Volume Group.
109       vgrename      Rename a Volume Group.
110       vgs           Report information about Volume Groups.
111       vgscan        Scan all disks for Volume Groups.
112       vgsplit       Split a Volume Group into two, moving any logical volumes
113                     from one Volume Group to another by moving entire  Physi‐
114                     cal Volumes.
115       lvchange      Change attributes of a Logical Volume.
116       lvconvert     Convert  a  Logical Volume from linear to mirror or snap‐
117                     shot.
118       lvcreate      Create a Logical Volume in an existing Volume Group.
119       lvdisplay     Display attributes of a Logical Volume.
120       lvextend      Extend the size of a Logical Volume.
121       lvmconfig     Display  the  configuration  information  after   loading
122                     lvm.conf(5) and any other configuration files.
123       lvmdiskscan   Scan for all devices visible to LVM2.
124       lvmdump       Create lvm2 information dumps for diagnostic purposes.
125       lvreduce      Reduce the size of a Logical Volume.
126       lvremove      Remove a Logical Volume.
127       lvrename      Rename a Logical Volume.
128       lvresize      Resize a Logical Volume.
129       lvs           Report information about Logical Volumes.
130       lvscan        Scan (all disks) for Logical Volumes.
131
132       The  following  LVM1  commands  are not implemented in LVM2: lvmchange,
133       lvmsadc, lvmsar, pvdata.  For performance metrics, use dmstats(8) or to
134       manipulate  the  kernel device-mapper driver used by LVM2 directly, use
135       dmsetup(8).
136

VALID NAMES

138       The valid characters for VG and LV names are: a-z A-Z 0-9 + _ . -
139
140       VG names cannot begin with a hyphen.  The name of a new LV also  cannot
141       begin  with  a  hyphen.   However,  if  the configuration setting meta‐
142       data/record_lvs_history is enabled then an LV name with a hyphen  as  a
143       prefix  indicates  that, although the LV was removed, it is still being
144       tracked because it forms part of the history of at least one LV that is
145       still  present.   This  helps  to record the ancestry of thin snapshots
146       even after some links in the chain have been removed.  A  reference  to
147       the  historical LV 'lvol1' in VG 'vg00' would be 'vg00/\-lvol1' or just
148       '-lvol1' if the VG is already set.  (The latter form must  be  preceded
149       by  '--'  to  terminate  command line option processing before reaching
150       this argument.)
151
152       There are also various reserved names that are used internally  by  lvm
153       that  can not be used as LV or VG names. A VG cannot be called anything
154       that exists in /dev/ at the time of creation, nor can it be called  '.'
155       or  '..'.   An  LV  cannot be called '.', '..', 'snapshot' or 'pvmove'.
156       The LV name  may  also  not  contain  any  of  the  following  strings:
157       '_cdata',  '_cmeta',  '_corig',  '_mlog', '_mimage', '_pmspare', '_rim‐
158       age', '_rmeta', '_tdata', '_tmeta' or '_vorigin'.  A directory  bearing
159       the  name  of  each  Volume Group is created under /dev when any of its
160       Logical Volumes are activated.  Each active Logical Volume is  accessi‐
161       ble  from  this  directory as a symbolic link leading to a device node.
162       Links or nodes in /dev/mapper are intended only for  internal  use  and
163       the  precise format and escaping might change between releases and dis‐
164       tributions.  Other  software  and  scripts  should  use  the  /dev/Vol‐
165       umeGroupName/LogicalVolumeName  format  to reduce the chance of needing
166       amendment when the software is updated.  Should you need to process the
167       node  names  in  /dev/mapper, you may use dmsetup splitname to separate
168       out the original VG, LV and internal layer names.
169

UNIQUE NAMES

171       VG names should be unique.  vgcreate will produce an error if the spec‐
172       ified  VG  name  matches an existing VG name.  However, there are cases
173       where different VGs with the same name can appear to  LVM,  e.g.  after
174       moving disks or changing filters.
175
176       When  VGs  with the same name exist, commands operating on all VGs will
177       include all of the VGs with the same name.  If the ambiguous VG name is
178       specified  on the command line, the command will produce an error.  The
179       error states that multiple VGs  exist  with  the  specified  name.   To
180       process one of the VGs specifically, the --select option should be used
181       with the UUID of the intended VG: '--select vg_uuid=<uuid>'.
182
183       An exception is if all but one of the VGs with the shared name is  for‐
184       eign  (see  lvmsystemid(7).)  In this case, the one VG that is not for‐
185       eign is assumed to be the intended VG and is processed.
186
187       LV names are unique within a VG.  The name of an historical  LV  cannot
188       be reused until the historical LV has itself been removed or renamed.
189
190

ALLOCATION

192       When  an  operation  needs to allocate Physical Extents for one or more
193       Logical Volumes, the tools proceed as follows:
194
195       First of all, they generate the complete set  of  unallocated  Physical
196       Extents  in  the  Volume  Group.  If any ranges of Physical Extents are
197       supplied at the end of the  command  line,  only  unallocated  Physical
198       Extents  within those ranges on the specified Physical Volumes are con‐
199       sidered.
200
201       Then they try  each  allocation  policy  in  turn,  starting  with  the
202       strictest  policy  (contiguous)  and  ending with the allocation policy
203       specified using --alloc or set as the default for the particular  Logi‐
204       cal  Volume  or  Volume Group concerned.  For each policy, working from
205       the lowest-numbered Logical Extent of the empty  Logical  Volume  space
206       that  needs  to  be  filled,  they  allocate  as much space as possible
207       according to the restrictions imposed by the policy.  If more space  is
208       needed, they move on to the next policy.
209
210       The restrictions are as follows:
211
212       Contiguous  requires  that  the physical location of any Logical Extent
213       that is not the first Logical Extent of a Logical Volume is adjacent to
214       the physical location of the Logical Extent immediately preceding it.
215
216       Cling  requires that the Physical Volume used for any Logical Extent to
217       be added to an existing Logical Volume is already in use  by  at  least
218       one  Logical  Extent earlier in that Logical Volume.  If the configura‐
219       tion parameter allocation/cling_tag_list is defined, then two  Physical
220       Volumes are considered to match if any of the listed tags is present on
221       both Physical Volumes.  This allows groups  of  Physical  Volumes  with
222       similar  properties  (such as their physical location) to be tagged and
223       treated as equivalent for allocation purposes.
224
225       When a Logical Volume is striped or mirrored,  the  above  restrictions
226       are  applied  independently  to  each stripe or mirror image (leg) that
227       needs space.
228
229       Normal will not choose a Physical Extent that shares the same  Physical
230       Volume as a Logical Extent already allocated to a parallel Logical Vol‐
231       ume (i.e. a different stripe or mirror image/leg) at  the  same  offset
232       within that parallel Logical Volume.
233
234       When  allocating  a  mirror  log at the same time as Logical Volumes to
235       hold the mirror data, Normal will first try to select different  Physi‐
236       cal  Volumes  for the log and the data.  If that's not possible and the
237       allocation/mirror_logs_require_separate_pvs configuration parameter  is
238       set  to  0, it will then allow the log to share Physical Volume(s) with
239       part of the data.
240
241       When allocating thin pool metadata, similar considerations to those  of
242       a  mirror  log  in  the  last paragraph apply based on the value of the
243       allocation/thin_pool_metadata_require_separate_pvs configuration param‐
244       eter.
245
246       If  you  rely upon any layout behaviour beyond that documented here, be
247       aware that it might change in future versions of the code.
248
249       For example, if you supply on the command line two empty Physical  Vol‐
250       umes  that  have an identical number of free Physical Extents available
251       for allocation, the current code considers using each of  them  in  the
252       order  they  are listed, but there is no guarantee that future releases
253       will maintain that property.  If it is important to obtain  a  specific
254       layout  for  a  particular  Logical Volume, then you should build it up
255       through a sequence of lvcreate(8) and lvconvert(8) steps such that  the
256       restrictions  described  above  applied to each step leave the tools no
257       discretion over the layout.
258
259       To view the way the allocation process currently works in any  specific
260       case,  read  the debug logging output, for example by adding -vvvv to a
261       command.
262

LOGICAL VOLUME TYPES

264       Some logical volume types are simple to create and can be done  with  a
265       single  lvcreate(8)  command.   The  linear  and striped logical volume
266       types are an example of this.  Other logical volume types  may  require
267       more than one command to create.  The cache (lvmcache(7)) and thin pro‐
268       visioning (lvmthin(7)) types are examples of this.
269

DIAGNOSTICS

271       All tools return a status code of zero on success or non-zero on  fail‐
272       ure.   The non-zero codes distinguish only between the broad categories
273       of unrecognised commands, problems processing the  command  line  argu‐
274       ments and any other failures.  As LVM remains under active development,
275       the code used in a specific case occasionally changes between releases.
276       Message text may also change.
277

ENVIRONMENT VARIABLES

279       HOME   Directory containing .lvm_history if the internal readline shell
280              is invoked.
281
282       LVM_OUT_FD
283              File descriptor to use for common output from LVM commands.
284
285       LVM_ERR_FD
286              File descriptor to use for error output from LVM commands.
287
288       LVM_REPORT_FD
289              File descriptor to use for report output from LVM commands.
290
291       LVM_COMMAND_PROFILE
292              Name of default command profile to use for  LVM  commands.  This
293              profile  is  overriden by direct use of --commandprofile command
294              line option.
295
296       LVM_RUN_BY_DMEVENTD
297              This variable is normally set by dmeventd plugin to inform  lvm2
298              command  it  is  running from dmeventd plugin so lvm2 takes some
299              extra action to avoid comunication and deadlocks with dmeventd.
300
301       LVM_SYSTEM_DIR
302              Directory containing lvm.conf(5) and  other  LVM  system  files.
303              Defaults to "/etc/lvm".
304
305       LVM_SUPPRESS_FD_WARNINGS
306              Suppress  warnings about unexpected file descriptors passed into
307              LVM.
308
309       LVM_SUPPRESS_SYSLOG
310              Suppress contacting syslog.
311
312       LVM_VG_NAME
313              The Volume Group name that is assumed for  any  reference  to  a
314              Logical Volume that doesn't specify a path.  Not set by default.
315
316       LVM_LVMPOLLD_PIDFILE
317              Path to the file that stores the lvmpolld process ID.
318
319       LVM_LVMPOLLD_SOCKET
320              Path to the socket used to communicate with lvmpolld..
321
322       LVM_LOG_FILE_EPOCH
323              A  string  of  up to 32 letters appended to the log filename and
324              followed by the process ID and a startup  timestamp  using  this
325              format  string  "_%s_%d_%llu".  When set, each process logs to a
326              separate file.
327
328       LVM_LOG_FILE_MAX_LINES
329              If more than this number of lines are sent to the log file,  the
330              command  gets  aborted.   Automated  tests use this to terminate
331              looping commands.
332
333       LVM_EXPECTED_EXIT_STATUS
334              The status anticipated when the  process  exits.   Use  ">N"  to
335              match  any  status  greater  than  N.  If the actual exit status
336              matches  and  a  log  file  got   produced,   it   is   deleted.
337              LVM_LOG_FILE_EPOCH  and  LVM_EXPECTED_EXIT_STATUS together allow
338              automated test scripts to discard uninteresting log data.
339
340       LVM_SUPPRESS_LOCKING_FAILURE_MESSAGES
341              Used to suppress warning messages when the configured locking is
342              known to be unavailable.
343
344       DM_ABORT_ON_INTERNAL_ERRORS
345              Abort processing if the code detects a non-fatal internal error.
346
347       DM_DISABLE_UDEV
348              Avoid interaction with udev.  LVM will manage the relevant nodes
349              in /dev directly.
350
351       DM_DEBUG_WITH_LINE_NUMBERS
352              Prepends source file name and code line number with libdm debug‐
353              ging.
354

FILES

356       /etc/lvm/lvm.conf
357       $HOME/.lvm_history
358

SEE ALSO

360       lvm(8) lvm.conf(5) lvmconfig(8)
361
362       pvchange(8)  pvck(8)  pvcreate(8)  pvdisplay(8)  pvmove(8)  pvremove(8)
363       pvresize(8) pvs(8) pvscan(8)
364
365       vgcfgbackup(8)   vgcfgrestore(8)   vgchange(8)   vgck(8)    vgcreate(8)
366       vgconvert(8)    vgdisplay(8)    vgexport(8)   vgextend(8)   vgimport(8)
367       vgimportclone(8)  vgmerge(8)   vgmknodes(8)   vgreduce(8)   vgremove(8)
368       vgrename(8) vgs(8) vgscan(8) vgsplit(8)
369
370       lvcreate(8)    lvchange(8)    lvconvert(8)   lvdisplay(8)   lvextend(8)
371       lvreduce(8) lvremove(8) lvrename(8) lvresize(8) lvs(8) lvscan(8)
372
373       lvm-fullreport(8)      lvm-lvpoll(8)       lvm2-activation-generator(8)
374       blkdeactivate(8) lvmdump(8)
375
376       dmeventd(8)    lvmpolld(8)    lvmlockd(8)   lvmlockctl(8)   cmirrord(8)
377       lvmdbusd(8)
378
379       lvmsystemid(7) lvmreport(7) lvmraid(7) lvmthin(7) lvmcache(7)
380
381       dmsetup(8), dmstats(8), readline(3)
382
383
384
385Red Hat, Inc.          LVM TOOLS 2.03.06(2) (2019-10-23)                LVM(8)
Impressum