LVM(8)

📦
version 2.03.44 · 14 versions
, in arch rolling

✨ LVM — like, the whole vibe ✨

okay bestie, welcome to LVM(8), aka the LVM tools page from the System Manager's Manual. this is the group chat where all the logical volume lore lives. let's get into it 💅

🎀 SYNOPSIS 🎀

lvm [command|file]

like that's it. that's the whole entrance. slay.

💖 DESCRIPTION 💖

so. the Logical Volume Manager (LVM) gives you tools to create virtual block devices out of physical devices. why would you want that? because virtual devices are genuinely easier to manage than physical ones, and they can do stuff the physical devices literally cannot do on their own. main character energy fr fr ✨

here's the squad:

  • a Volume Group (VG) is a collection of one or more physical devices — each one called a Physical Volume (PV) 🫶
  • a Logical Volume (LV) is a virtual block device that your system or apps can actually use 🌸

every single block of data in an LV gets stored on one or more PVs inside the VG, following algorithms implemented by Device Mapper (DM) in the kernel. that's the whole magic trick, no cap.

the lvm command, plus all the other commands listed below, are the command-line tools for LVM. each command has its own separate manual page that details it, so if you're looking for deep lore on one specific thing, go there bestie.

  • if you run lvm with no arguments, it drops you into a readline prompt (assuming it was compiled with readline support, lowkey important). at that prompt you can type LVM commands interactively with all the readline facilities — history, command name completion, option completion, the works. go read readline(3) for the 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 just acts as that command. shapeshifter behavior fr.
  • on invocation, lvm requires that only the standard file descriptors stdin, stdout and stderr are available. if it finds any others, it closes them and issues a warning about the leak. you can hush that warning by setting the environment variable LVM_SUPPRESS_FD_WARNINGS.
  • when commands take VG or LV names as arguments, the full path name is optional, bestie. an LV called "lvol0" in a VG called "vg0" can be specified as "vg0/lvol0". where a list of VGs is required but left empty, a list of all VGs gets substituted. where a list of LVs is required but a VG is given, a list of all the LVs in that VG gets substituted. so like, lvdisplay vg0 will display all the LVs in "vg0". iconic. 🎀
  • you can also hand it a file containing a simple script with one command per line. and yes, the script can be executed directly if its first line is #! followed by the absolute path of lvm. chef's kiss.
  • additional hyphens within option names are ignored. for example, --readonly and --read-only are both accepted. do with that information what you will 💀
  • LVM reads and writes devices through an I/O engine selected by the global/io_engine configuration setting: auto (the default), sync, libaio, threads, or iouring. heads up — libaio and iouring are available only when LVM is built with the required libraries. the deprecated global/use_aio setting is used only when io_engine is not set, and use_aio=0 selects synchronous I/O. see lvmconfig(8) for descriptions of these settings, bestie.

🦋 BUILT-IN COMMANDS 🦋

these commands are built into lvm without links normally being created in the filesystem for them. so they just live inside, rent free. 👑

  • 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.
  • fullreport — report information about PVs, PV segments, VGs, LVs and LV segments, all at once. everything everywhere all at once fr.
  • help — display the help text.
  • lastlog — display log report of last command run in LVM shell if command log reporting is enabled.
  • lvpoll — complete lvmpolld operations (Internal command).
  • 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 🌈

these are the ones implementing the core LVM functionality. the whole roster. 💅

  • 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 LVM.
  • pvs — report information about Physical Volumes.
  • pvscan — list 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.
  • 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 a duplicated Volume Group (e.g. a hardware snapshot).
  • vgimportdevices — add PVs from a VG to the devices file.
  • 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 — list Volume Groups.
  • 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 between different types.
  • 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.
  • lvmconfig — display the configuration information after loading lvm.conf(5) and any other configuration files.
  • lvmdevices — manage the devices file.
  • lvmdiskscan — scan for all devices visible to LVM.
  • lvmdump — create LVM 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 — list Logical Volumes.

for performance metrics, use dmstats(8), or to manipulate the kernel device-mapper driver used by LVM directly, use dmsetup(8). iykyk 🧚

💜 VALID NAMES 💜

the valid characters for VG and LV names are:

a–z A–Z 0–9 + _ . -

that's the whole alphabet of allowed vibes.

now the rules, bestie, pay attention:

  • VG names cannot begin with a hyphen. also the name of a new LV cannot begin with a hyphen.
  • however (plot twist ✨), if the configuration setting metadata/record_lvs_history is enabled, then an LV name with a hyphen as a prefix indicates that — even though the LV was removed — it's still being tracked, because it forms part of the history of at least one LV that is still present. this helps record the ancestry of thin snapshots even after some links in the chain have been removed. it's giving ancestry.com for your volumes. 🦋
  • a reference to the historical LV 'lvol1' in VG 'vg00' would be 'vg00/-lvol1', or just '-lvol1' if the VG is already set. (heads up: that latter form must be preceded by '--' to terminate command line option processing before reaching this argument.)

there are also various reserved names used internally by lvm that cannot be used as LV or VG names:

  • a VG cannot be called anything that exists in /dev/ at the time of creation, and it also can't be called '.' or '..'.
  • an LV cannot be called '.', '..', 'snapshot' or 'pvmove'.
  • an LV name may also not contain any of the following strings: '_cdata', '_cmeta', '_corig', '_iorig', '_mimage', '_mlog', '_pmspare', '_rimage', '_rmeta', '_tdata', '_tmeta', '_vdata', '_vorigin' or '_wcorig'.

a directory bearing the name of each Volume Group gets 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.

⚠️ okay this part matters: links or nodes in /dev/mapper are intended only for internal use, and the precise format and escaping might change between releases and distributions. so 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. 🙈

🌸 UNIQUE NAMES 🌸

VG names should be unique, bestie. vgcreate will produce an error if the specified VG name matches an existing VG name. but — and this is the messy part — there are cases where different VGs with the same name can appear to LVM, e.g. after moving disks or changing filters. 😭

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, use the --select option with the UUID of the intended VG: --select vg_uuid=<uuid>.

one exception though 🫶: if all but one of the VGs with the shared name is foreign (see lvmsystemid(7)), then the one VG that is not foreign is assumed to be the intended VG and gets processed. the universe self-corrects, kinda.

LV names are unique within a VG. and the name of a historical LV cannot be reused until the historical LV has itself been removed or renamed. no name recycling, periodt. 💅

🍓 TAGS 🍓

tags are user-defined strings that can be attached to PVs, VGs and LVs. little name-tags for your volumes, adorable. 🎀

  • tags can be displayed with commands pvs/vgs/lvs -o tags.
  • certain commands will accept a tag name in place of a PV, VG, or LV name. in these cases, the command will operate on each PV/VG/LV with the given tag.
  • tags should be prefixed with @ to avoid ambiguity.
  • characters allowed in tags are:
A–Z a–z 0–9 _ + . - / = ! : # &

and that's where we're at for now — there's more coming, so don't go anywhere bestie 💖

💫 ALLOCATION 💫

okay bestie, so when an operation needs to allocate Physical Extents for one or more Logical Volumes, here's the little ritual the tools go through, step by step:

First, they generate the complete set of unallocated Physical Extents in the Volume Group. And if you handed over any ranges of Physical Extents at the end of the command line? Then only the unallocated Physical Extents within those ranges on the Physical Volumes you named get considered. narrow it down, periodt.

Then they try each allocation policy in turn — strictest one first (contiguous), and ending with whatever policy you set with --alloc or whatever's set as the default for that particular Logical Volume or Volume Group. For each policy, working from the lowest-numbered Logical Extent of the empty Logical Volume space that needs filling, they allocate as much space as the policy's restrictions allow. Still need more space? They move on to the next policy. no cap.

The restrictions, bestie, are giving:

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. adjacent. next to. touching. ok? 😌

Cling requires that the Physical Volume used for any Logical Extent being added to an existing Logical Volume is already in use by at least one Logical Extent earlier in that same Logical Volume. And if the config parameter allocation/cling_tag_list is defined, then two Physical Volumes are considered to match if any of the listed tags shows up on both Physical Volumes. This is the slay part: it lets groups of Physical Volumes with similar properties (like their physical location) be tagged and treated as equivalent for allocation purposes. 💅

When a Logical Volume is striped or mirrored, those restrictions above get 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. it said no sharing, we're being independent here 🫶

When allocating a mirror log at the same time as the Logical Volumes that'll hold the mirror data, Normal will first try to select different Physical Volumes for the log and the data. If that's just not possible and the allocation/mirror_logs_require_separate_pvs configuration parameter is set to 0, then it will allow the log to share Physical Volume(s) with part of the data. compromise era fr fr.

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

⚠️ okay listen up: if you rely upon any layout behaviour beyond what's documented here, be aware that it might change in future versions of the code. it is not giving stability. it's giving vibes only.

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. 🫠 So if it's 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. be the main character, dictate the layout yourself 👑

To see the way the allocation process currently works in any specific case, read the debug logging output — for example by adding -vvvv to a command. it's giving detective work 🔍

🧚 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 examples of this — one command and done, ate. ✨

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. they take a little more effort, but they're worth it bestie 😭

🩺 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
  • 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. so don't get attached to an error string, it's not your boyfriend 💀

🌈 ENVIRONMENT VARIABLES 🌈

  • HOME — Directory containing .lvm_history if the internal readline shell is invoked.
  • LVM_OUT_FD — File descriptor to use for common output from LVM commands.
  • LVM_ERR_FD — File descriptor to use for error output from LVM commands.
  • LVM_REPORT_FD — File descriptor to use for report output from LVM commands.
  • LVM_COMMAND_PROFILE — Name of default command profile to use for LVM commands. This profile is overridden by direct use of the --commandprofile command line option.
  • LVM_RUN_BY_DMEVENTD — This variable is normally set by the dmeventd plugin to inform the lvm command that it was invoked by the dmeventd plugin, so that lvm takes extra action to avoid communication and deadlocks with dmeventd.
  • 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_SUPPRESS_SYSLOG — Suppress contacting syslog.
  • 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_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 startup timestamp using this format string "_%s_%d_%llu". When set, each process logs to a separate file.
  • 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.
  • 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 was produced, that file 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.
  • DM_DEBUG_WITH_LINE_NUMBERS — Prepends the source file name and line number to libdm debug messages.

📁 FILES 📁

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

the holy trinity of lvm config files, plus your little history file 🎀

👀 SEE ALSO 👀

the whole friend group, bestie:

and that's the whole page, bestie!! 💖 this little masterpiece comes to you from Red Hat, Inc., and it's LVM TOOLS 2.03.44(2) dated 2026-10-27. go forth and partition responsibly, you gorgeous sysadmin 🫶✨👑

📦 where this page comes from