Provided by: lvm2_2.02.133-1ubuntu10_amd64 bug

NAME

       lvm — LVM2 tools

SYNOPSIS

       lvm [command|file]

DESCRIPTION

       lvm  provides  the  command-line  tools  for  LVM2.  A separate manual page describes each
       command in detail.

       If lvm is invoked with no arguments  it  presents  a  readline  prompt  (assuming  it  was
       compiled with readline support).  LVM commands may be entered interactively at this prompt
       with readline facilities including history and command name and option completion.   Refer
       to readline(3) for details.

       If  lvm  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.

       On invocation, lvm 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 LVM_SUPPRESS_FD_WARNINGS.

       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
       lvdisplay  vg0  will  display  all the LVs in "vg0".  Tags can also be used - see --addtag
       below.

       One advantage of using the built-in shell is that configuration  information  gets  cached
       internally between commands.

       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 lvm.

BUILT-IN COMMANDS

       The  following  commands  are  built  into lvm without links normally being created in the
       filesystem for them.

       config        The same as lvmconfig(8) below.
       devtypes      Display the recognised built-in block device types.
       dumpconfig    The same as lvmconfig(8) below.
       formats       Display recognised metadata formats.
       help          Display the help text.
       lvpoll        Complete lvmpolld operations (Internal command).
       pvdata        Not implemented in LVM2.
       segtypes      Display recognised Logical Volume segment types.
       systemid      Display any system ID currently set on this host.
       tags          Display any tags defined on this host.
       version       Display version information.

COMMANDS

       The following commands implement the core LVM functionality.

       pvchange      Change attributes of a Physical Volume.
       pvck          Check Physical Volume metadata.
       pvcreate      Initialize a disk or partition for use by LVM.
       pvdisplay     Display attributes of a Physical Volume.
       pvmove        Move Physical Extents.
       pvremove      Remove a Physical Volume.
       pvresize      Resize a disk or partition in use by LVM2.
       pvs           Report information about Physical Volumes.
       pvscan        Scan all disks for Physical Volumes.
       vgcfgbackup   Backup Volume Group descriptor area.
       vgcfgrestore  Restore Volume Group descriptor area.
       vgchange      Change attributes of a Volume Group.
       vgck          Check Volume Group metadata.
       vgconvert     Convert Volume Group metadata format.
       vgcreate      Create a Volume Group.
       vgdisplay     Display attributes of Volume Groups.
       vgexport      Make volume Groups unknown to the system.
       vgextend      Add Physical Volumes to a Volume Group.
       vgimport      Make exported Volume Groups known to the system.
       vgimportclone Import and rename duplicated Volume Group (e.g. a hardware snapshot).
       vgmerge       Merge two Volume Groups.
       vgmknodes     Recreate Volume Group directory and Logical Volume special files
       vgreduce      Reduce a Volume Group by removing one or more Physical Volumes.
       vgremove      Remove a Volume Group.
       vgrename      Rename a Volume Group.
       vgs           Report information about Volume Groups.
       vgscan        Scan all disks for Volume Groups and rebuild caches.
       vgsplit       Split a Volume Group into two, moving any logical volumes  from  one  Volume
                     Group to another by moving entire Physical Volumes.
       lvchange      Change attributes of a Logical Volume.
       lvconvert     Convert a Logical Volume from linear to mirror or snapshot.
       lvcreate      Create a Logical Volume in an existing Volume Group.
       lvdisplay     Display attributes of a Logical Volume.
       lvextend      Extend the size of a Logical Volume.
       lvmchange     Change attributes of the Logical Volume Manager.
       lvmconfig     Display  the  configuration  information  after  loading lvm.conf(5) and any
                     other configuration files.
       lvmdiskscan   Scan for all devices visible to LVM2.
       lvmdump       Create lvm2 information dumps for diagnostic purposes.
       lvreduce      Reduce the size of a Logical Volume.
       lvremove      Remove a Logical Volume.
       lvrename      Rename a Logical Volume.
       lvresize      Resize a Logical Volume.
       lvs           Report information about Logical Volumes.
       lvscan        Scan (all disks) for Logical Volumes.

       The following commands are not implemented in LVM2 but might be in  the  future:  lvmsadc,
       lvmsar, pvdata.

OPTIONS

       The  following  options  are  available  for  many  of the commands.  They are implemented
       generically and documented here rather than repeated on individual manual pages.

       Additional  hyphens  within  option  names  are  ignored.   For  example,  --readonly  and
       --read-only are both accepted.

       -h|-?|--help
              Display the help text.

       --version
              Display version information.

       -v|--verbose
              Set verbose level. Repeat from 1 to 3 times to increase the detail of messages sent
              to stdout and stderr.  Overrides config file setting.

       -d|--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).  Overrides config file setting.

       -q|--quiet
              Suppress  output  and  log  messages.   Overrides  -d  and -v.  Repeat once to also
              suppress any prompts with answer 'no'.

       --yes
              Don't prompt for confirmation interactively but instead always assume the answer is
              'yes'.  Take great care if you use this!

       -t|--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.

       --driverloaded {y|n}
              Whether or not the device-mapper kernel driver is loaded.  If you set this to n, no
              attempt will be made to contact the driver.

       -A|--autobackup {y|n}
              Whether  or  not to metadata should be backed up automatically after a change.  You
              are strongly advised not to disable this!  See vgcfgbackup(8).

       -P|--partial
              When set, the tools will do their best to provide access to Volume Groups that  are
              only  partially  available  (one  or  more Physical Volumes belonging to the Volume
              Group are missing from the system).  Where part of a  logical  volume  is  missing,
              /dev/ioerror  will  be  substituted, and you could use dmsetup(8) to set this up to
              return I/O errors when accessed, or create it as a large  block  device  of  nulls.
              Metadata  may  not  be  changed  with this option. To insert a replacement Physical
              Volume of the same or large size use pvcreate -u to  set  the  uuid  to  match  the
              original followed by vgcfgrestore(8).

       -S|--select Selection
              For  reporting commands, display only rows that match Selection criteria.  All rows
              are displayed with the additional "selected" column (-o selected) showing 1 if  the
              row matches the Selection and 0 otherwise. For non-reporting commands which process
              LVM entities, the selection can be used to match items to  process.  See  SELECTION
              CRITERIA  section of this man page for more information about the way the selection
              criteria are constructed.

       -M|--metadatatype Type
              Specifies which type of on-disk metadata to use, such as lvm1 or lvm2, which can be
              abbreviated  to  1 or 2 respectively.  The default (lvm2) can be changed by setting
              format in the global section of the config file lvm.conf(5).

       --ignorelockingfailure
              This lets you proceed with read-only metadata operations such as lvchange  -ay  and
              vgchange  -ay  even  if  the locking module fails.  One use for this is in a system
              init script if the lock directory is mounted read-only when the script runs.

       --ignoreskippedcluster
              Use to avoid exiting with an non-zero status code if the  command  is  run  without
              clustered locking and some clustered Volume Groups have to be skipped over.

       --readonly
              Run  the  command  in  a  special  read-only  mode which will read on-disk metadata
              without needing to take any locks.  This can be used to peek inside  metadata  used
              by  a  virtual  machine image while the virtual machine is running.  It can also be
              used to peek inside the metadata of clustered Volume Groups when clustered  locking
              is  not  configured  or  running.   No attempt will be made to communicate with the
              device-mapper kernel driver, so this option is unable  to  report  whether  or  not
              Logical Volumes are actually in use.

       --foreign
              Cause  the  command to access foreign VGs, that would otherwise be skipped.  It can
              be used to report or display a VG that is owned by another host.  This  option  can
              cause  a command to perform poorly because lvmetad caching is not used and metadata
              is read from disks.

       --shared
              Cause the command to access shared  VGs,  that  would  otherwise  be  skipped  when
              lvmlockd is not being used.  It can be used to report or display a lockd VG without
              locking.

       --addtag Tag
              Add the tag Tag to a PV, VG or LV.  Supply this argument multiple times to add more
              than  one  tag  at once.  A tag is a word that can be used to group LVM2 objects of
              the same type together.  Tags can be given on the command line in place of  PV,  VG
              or  LV  arguments.  Tags should be prefixed with @ to avoid ambiguity.  Each tag is
              expanded by replacing it with all objects possessing that tag which are of the type
              expected by its position on the command line.  PVs can only possess tags while they
              are part of a Volume Group: PV tags are discarded if the PV is removed from the VG.
              As  an  example, you could tag some LVs as database and others as userdata and then
              activate the database ones  with  lvchange  -ay  @database.   Objects  can  possess
              multiple  tags simultaneously.  Only the new LVM2 metadata format supports tagging:
              objects using the LVM1 metadata format cannot be tagged because the on-disk  format
              does not support it.  Characters allowed in tags are: A-Z a-z 0-9 _ + . - and as of
              version 2.02.78 the following characters are also accepted: / = ! : # &

       --deltag Tag
              Delete the tag Tag from a PV, VG or LV, if  it's  present.   Supply  this  argument
              multiple times to remove more than one tag at once.

       --alloc {anywhere|contiguous|cling|inherit|normal}
              Selects  the  allocation  policy  when a command needs to allocate Physical Extents
              from the Volume Group.  Each Volume Group and  Logical  Volume  has  an  allocation
              policy  defined.   The  default  for a Volume Group is normal which applies common-
              sense rules such as not placing parallel stripes on the same Physical Volume.   The
              default  for  a  Logical Volume is inherit which applies the same policy as for the
              Volume Group.  These policies can be changed using lvchange(8) and  vgchange(8)  or
              overridden  on  the  command  line  of  any  command that performs allocation.  The
              contiguous policy requires that new Physical Extents be placed adjacent to existing
              Physical  Extents.   The  cling  policy  places  new  Physical  Extents on the same
              Physical Volume as existing Physical Extents in the  same  stripe  of  the  Logical
              Volume.   If  there  are  sufficient free Physical Extents to satisfy an allocation
              request but normal  doesn't  use  them,  anywhere  will  -  even  if  that  reduces
              performance by placing two stripes on the same Physical Volume.

       --commandprofile ProfileName
              Selects  the  command  configuration profile to use when processing an LVM command.
              See also lvm.conf(5) for more information about command profile config and the  way
              it  fits  with  other  LVM  configuration  methods.  Using  --commandprofile option
              overrides  any  command  profile  specified  via  LVM_COMMAND_PROFILE   environment
              variable.

       --metadataprofile ProfileName
              Selects  the  metadata configuration profile to use when processing an LVM command.
              When using metadata profile during Volume Group or  Logical  Volume  creation,  the
              metadata  profile  name  is  saved  in  metadata. When such Volume Group or Logical
              Volume is processed next time, the metadata profile is  automatically  applied  and
              the use of --metadataprofile option is not necessary. See also lvm.conf(5) for more
              information about metadata profile config and  the  way  it  fits  with  other  LVM
              configuration methods.

       --profile ProfileName
              A  short  form  of  --metadataprofile for vgcreate, lvcreate, vgchange and lvchange
              command and a short form of  --commandprofile  for  any  other  command  (with  the
              exception  of  lvmconfig  command  where  the  --profile  has  special meaning, see
              lvmconfig(8) for more information).

       --config ConfigurationString
              Uses the ConfigurationString as direct string representation of  the  configuration
              to  override  the existing configuration. The ConfigurationString is of exactly the
              same format as used in  any  LVM  configuration  file.  See  lvm.conf(5)  for  more
              information  about  direct config override on command line and the way it fits with
              other LVM configuration methods.

VALID NAMES

       The valid characters for VG and LV names are: a-z A-Z 0-9 + _ . -

       VG and LV names cannot begin with a hyphen.  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 /dev/ at the time of creation, nor can it be called '.'  or  '..'.
       An  LV  cannot  be  called  '.',  '..',  'snapshot' or 'pvmove'.  The LV name may also not
       contain any of the following strings: A directory bearing the name of each Volume Group is
       created  under  /dev  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 /dev/mapper 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  /dev/VolumeGroupName/LogicalVolumeName  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  dmsetup splitname to separate out the original VG, LV and
       internal layer names.

ALLOCATION

       When an operation needs to allocate Physical Extents for one or more Logical Volumes,  the
       tools proceed as follows:

       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.

       Then they try  each  allocation  policy  in  turn,  starting  with  the  strictest  policy
       (contiguous)  and  ending with the allocation policy specified using --alloc 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.

       The restrictions are as follows:

       Contiguous 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.

       Cling  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 allocation/cling_tag_list 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.

       When a Logical  Volume  is  striped  or  mirrored,  the  above  restrictions  are  applied
       independently to each stripe or mirror image (leg) that needs space.

       Normal 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.

       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  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.

       When allocating thin pool metadata, similar considerations to those of a mirror log in the
       last      paragraph      apply      based      on       the       value       of       the
       allocation/thin_pool_metadata_require_separate_pvs configuration parameter.

       If  you rely upon any layout behaviour beyond that documented here, be aware that it might
       change in future versions of the code.

       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
       lvcreate(8)  and  lvconvert(8) steps such that the restrictions described above applied to
       each step leave the tools no discretion over the layout.

       To view the way the allocation process currently works in  any  specific  case,  read  the
       debug logging output, for example by adding -vvvv to a command.

LOGICAL VOLUME TYPES

       Some  logical  volume types are simple to create and can be done with a single lvcreate(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 (lvmcache(7))
       and thin provisioning (lvmthin(7)) types are examples of this.

SELECTION CRITERIA

       The selection criteria are a set of statements combined by logical and grouping operators.
       The  statement  consists  of  column name for which a set of valid values is defined using
       comparison operators. For complete list of column names  (fields)  that  can  be  used  in
       selection, see the output of <lvm reporting command> -S help.

   Comparison operators (cmp_op)
       =~     Matching regular expression.
       !~     Not matching regular expression.
       =      Equal to.
       !=     Not equal to.
       >=     Greater than or equal to.
       >      Greater than
       <=     Less than or equal to.
       <      Less than.

   Binary logical operators (cmp_log)
       &&     All fields must match
       ,      All fields must match
       ||     At least one field must match
       #      At least one field must match

   Unary logical operators
       !      Logical negation

   Grouping operators
       (      Left parenthesis
       )      Right parenthesis
       [      List start
       ]      List end
       {      List subset start
       }      List subset end

   Informal grammar specification
       STATEMENT = column cmp_op VALUE | STATEMENT log_op STATEMENT | (STATEMENT) | !(STATEMENT)

       VALUE = [VALUE log_op VALUE]
              For  list-based types: string list. Matches strictly.  The log_op must always be of
              one type within the whole list value.

       VALUE = {VALUE log_op VALUE}
              For list-based types: string list. Matches a subset.  The log_op must always be  of
              one type within the whole list value.

       VALUE = value
              For  scalar  types:  number  (integer),  size (floating point number with size unit
              suffix), percent (floating point number with or without % suffix), string.

DIAGNOSTICS

       All tools return a status code of zero on success or non-zero on failure.

ENVIRONMENT VARIABLES

       HOME   Directory containing .lvm_history if the internal readline shell is invoked.

       LVM_COMMAND_PROFILE
              Name of default command profile to use for LVM commands. This profile is  overriden
              by direct use of --commandprofile command line option.

       LVM_SYSTEM_DIR
              Directory   containing  lvm.conf(5)  and  other  LVM  system  files.   Defaults  to
              "/etc/lvm".

       LVM_SUPPRESS_FD_WARNINGS
              Suppress warnings about unexpected file descriptors passed into LVM.

       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.

       LVM_LVMETAD_PIDFILE
              Path to the file that stores the lvmetad process ID.

       LVM_LVMETAD_SOCKET
              Path to the socket used to communicate with lvmetad.

       LVM_LVMPOLLD_PIDFILE
              Path to the file that stores the lvmpolld process ID.

       LVM_LVMPOLLD_SOCKET
              Path to the socket used to communicate with lvmpolld..

       LVM_LOG_FILE_EPOCH
              A  string  of  up  to  32  letters appended to the log filename and followed by the
              process ID and a timestamp.  When set, each process logs to a separate file.

       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.   LVM_LOG_FILE_EPOCH  and  LVM_EXPECTED_EXIT_STATUS   together   allow
              automated test scripts to discard uninteresting log data.

       LVM_SUPPRESS_LOCKING_FAILURE_MESSAGES
              Used  to  suppress  warning  messages  when  the  configured locking is known to be
              unavailable.

       DM_ABORT_ON_INTERNAL_ERRORS
              Abort processing if the code detects a non-fatal internal error.

       DM_DISABLE_UDEV
              Avoid interaction with udev.  LVM will manage the relevant nodes in /dev directly.

FILES

       /etc/lvm/lvm.conf
       $HOME/.lvm_history

SEE ALSO

       lvm.conf(5), lvmcache(7),  lvmthin(7),  clvmd(8),  dmsetup(8),  lvchange(8),  lvcreate(8),
       lvdisplay(8),   lvextend(8),   lvmchange(8),  lvmconfig(8),  lvmdiskscan(8),  lvreduce(8),
       lvremove(8),  lvrename(8),   lvresize(8),   lvs(8),   lvscan(8),   pvchange(8),   pvck(8),
       pvcreate(8),  pvdisplay(8),  pvmove(8),  pvremove(8),  pvs(8),  pvscan(8), vgcfgbackup(8),
       vgchange(8), vgck(8), vgconvert(8), vgcreate(8), vgdisplay(8),  vgextend(8),  vgimport(8),
       vgimportclone(8), vgmerge(8), vgmknodes(8), vgreduce(8), vgremove(8), vgrename(8), vgs(8),
       vgscan(8), vgsplit(8), readline(3)