DMSETUP(8)

📦
version 2.03.44 · 9 versions
, in arch rolling, centos-stream 10

DMSETUP(8) 💫 — the maintenance-commands girlies know

okay bestie, sit DOWN, because this is the low-level logical volume management manual and it's a whole personality 💅 it lives in the MAINTENANCE COMMANDS section, and yes it's dmsetup(8), we been knew.

✨ NAME ✨

dmsetup — Low level logical volume management 🫶

✨ SYNOPSIS ✨

dmsetup clear device_name
dmsetup create device_name [-n|--notable|--table table|table_file]
        [--readahead [+]sectors|auto|none] [-u|--uuid uuid]
        [--addnodeoncreate|--addnodeonresume]
dmsetup create --concise [concise_device_specification]
dmsetup deps [-o options] [device_name ...]
dmsetup help [-c|-C|--columns]
dmsetup info [device_name ...]
dmsetup info -c|-C|--columns [--count count] [--interval seconds]
        [--noheadings|--headings none|abbrev|full|0|1|2] [-o fields]
        [-O|--sort sort_fields] [--nameprefixes] [--separator separator]
        [device_name]
dmsetup load device_name [--table table|table_file]
dmsetup ls [--target target_type] [-o options] [--exec command] [--tree]

dmsetup mangle [device_name ...]
dmsetup measure [device_name ...]
dmsetup message device_name sector message
dmsetup mknodes [device_name ...]
dmsetup reload device_name [--table table|table_file]
dmsetup remove [-f|--force] [--retry] [--deferred] device_name ...
dmsetup remove_all [-f|--force] [--deferred]
dmsetup rename device_name new_name
dmsetup rename device_name --setuuid uuid
dmsetup resume device_name ... [--addnodeoncreate|--addnodeonresume]
        [--noflush] [--nolockfs] [--readahead [+]sectors|auto|none]
dmsetup setgeometry device_name cyl head sect start
dmsetup splitname device_name [subsystem]
dmsetup stats command [options]
dmsetup status [--target target_type] [--noflush] [device_name ...]
dmsetup suspend device_name ... [--nolockfs] [--noflush]
dmsetup table [--concise] [--target target_type] [--showkeys]
        [device_name ...]
dmsetup targets
dmsetup udevcomplete cookie
dmsetup udevcomplete_all [age_in_minutes]
dmsetup udevcookie
dmsetup udevcreatecookie
dmsetup udevflags cookie
dmsetup udevreleasecookie [cookie]
dmsetup version
dmsetup wait device_name [--noflush] [event_nr]
dmsetup wipe_table device_name ... [-f|--force] [--noflush] [--nolockfs]

devmap_name major minor
devmap_name major:minor

✨ DESCRIPTION ✨

so dmsetup is the girl who manages logical devices that use the device-mapper driver. Devices get created by loading a table, and that table specifies a target for every single sector (512 bytes) in the logical device. that's it, that's the whole vibe 🌸

The first argument to dmsetup is a command. The second argument is the logical device name or uuid. lowkey the whole interface is just that.

Now, a lil history moment 🎀 — if you invoke the dmsetup tool as devmap_name (which is not normally distributed and is supported only for historical reasons, ngl it's giving legacy code that refuses to retire 💀), it is equivalent to:

dmsetup info -c --noheadings -j major -m minor

✨ OPTIONS ✨

okay here come the flags, hydrate first bestie 🍓

  • --addnodeoncreate — makes sure the /dev/mapper node actually exists after dmsetup create. no orphan nodes in this house 🫶
  • --addnodeonresume — same energy but after dmsetup resume. and heads up: this is the default with udev. ✨
  • --checks — does extra checks on whatever operations you asked for and reports potential problems. so useful when you're debugging scripts, fr fr. tiny caveat: in some cases these checks may slow down operations noticeably. 🐌
  • -c, -C, --columns — displays output in columns instead of those Field: Value lines. glow up 💅
  • --count count — how many times to repeat a report. set it to zero and it just keeps going until you interrupt it. the default interval is one second. ⏱️
  • -f, --force — try harder to complete the operation. it's giving "no thoughts, just effort" 🔥
  • -h, --help — outputs a summary of the commands available, optionally including the list of report fields. (synonymous with the help command, so same thing, two doors 🚪)
  • --inactive — when you're returning any table info from the kernel, this reports on the inactive table instead of the live one. requires kernel driver version 4.16.0 or above, no exceptions. 👑
  • --interval seconds — the interval in seconds between successive iterations for repeating reports. if you pass --interval but not --count, reports will just keep repeating until interrupted. default interval is one second. 🕐
  • --manglename auto|hex|none — mangles any character not on a whitelist using mangling_mode when processing device-mapper device names and UUIDs. the names and UUIDs are mangled on input and unmangled on output, and the mangling mode is one of: auto (only do the mangling if not mangled yet, do nothing if already mangled, error on mixed), hex (always do the mangling) and none (no mangling). default mode is auto. character whitelist: 0–9, A–Z, a–z, #+-.:=@_. — and yes, this whitelist is also supported by udev. any character not on the whitelist is replaced with its hex value (two digits) prefixed by \x. mangling mode can also be set using the DM_DEFAULT_NAME_MANGLING_MODE environment variable. 🔤
  • -j, --major major — specify the major number.
  • -m, --minor minor — specify the minor number.
  • -n, --notable — when creating a device, don't load any table. empty on purpose, main character energy 🫥
  • --nameprefixes — adds a "DM_" prefix plus the field name to the output. so good with --noheadings to produce a list of field=value pairs you can use to set environment variables (for example, in udev(7) rules). 🏷️
  • --noheadings — suppresses the headings line when using columnar output. bye headers 👋
  • --headings none|abbrev|full|0|1|2 — the type of headings line to use for columnar output:
    • none or 0 – No headings.
    • abbrev or 1 – Column name abbreviations.
    • full or 2 – Full column names.
  • --noflush — do not flush outstanding I/O when suspending a device, or do not commit thin-pool metadata when obtaining thin-pool status. 🚫💧
  • --nolockfs — do not attempt to synchronize filesystem, e.g., when suspending a device.
  • --noopencount — tells the kernel not to supply the open reference count for the device. 🔢
  • --noudevrules — do not allow udev to manage nodes for devices in device-mapper directory.
  • --noudevsync — do not synchronize with udev when creating, renaming or removing devices. 🦋
  • -o, --options options — specify which fields to display.
  • --readahead [+]sectors|auto|none — specify read ahead size in units of sectors. the default value is auto, which lets the kernel choose a suitable value automatically. the + prefix lets you specify a minimum value, which will not be used if it's smaller than the value chosen by the kernel. the value none is equivalent to specifying zero. ⭐
  • -r, --readonly — sets the table being loaded read-only. 🔒
  • -S, --select selection — process only items that match selection criteria. if the command is producing report output, adding the "selected" column (-o selected) displays all rows and shows 1 if the row matches the selection and 0 otherwise. the selection criteria are defined by specifying column names and their valid values while making use of supported comparison operators. as a quick help, and to see the full list of column names you can use in selection plus the set of supported selection operators, check the output of the dmsetup info -c -S help command. 🔍
  • --table table — specify a one-line table directly on the command line. see below for more info on the table format. 📋
  • --udevcookie cookie — use a cookie for udev synchronization.
Note: the same cookie should be used for the same type of operations, i.e. the creation of multiple different devices. it is not advised to combine different operations on a single device. 🍪
  • -u, --uuid uuid — specify the uuid.
  • -y, --yes — answers yes to all prompts automatically. consent, but automated 💅
  • -v, --verbose [-v|--verbose] — produce additional output. repeat up to 4 times (-vvvv) to increase detail: -vv enables debug messages, -vvv adds elapsed time after each ioctl, -vvvv adds source file and line numbers. 📢
  • --verifyudev — if udev synchronization is enabled, verify that udev operations get performed correctly and try to fix up the device nodes afterwards if not. the cleanup girlie 🧹
  • --version — display the library and kernel driver version.

✨ COMMANDS ✨

clear

clear device_name

Destroys the table in the inactive table slot for device_name. poof, gone, we don't know her 💀

create

create device_name [-n|--notable|--table table|table_file] [--readahead [+]sectors|auto|none] [-u|--uuid uuid] [--addnodeoncreate|--addnodeonresume]

Creates a device with the given name. If table or table_file is supplied, the table is loaded and made live. Otherwise a table is read from standard input — unless --notable is used. The optional uuid can be used in place of device_name in subsequent dmsetup commands. If it's successful, the device will appear in the table, and for the live device, the node /dev/mapper/device_name is created. See below for more information on the table format. 🌈

create --concise

create --concise [concise_device_specification]

Creates one or more devices from a concise device specification. Each device is specified by a comma-separated list: name, uuid, minor number, flags, comma-separated table lines. Flags default to read-write (rw) or may be read-only (ro). Uuid, minor number and flags are optional, so those fields may be empty. A semicolon separates specifications of different devices. Use a backslash to escape the following character — for example a comma or semi-colon in a name or table. See also CONCISE FORMAT below. 🎀

deps

deps [-o options] [device_name ...]

Outputs a list of devices referenced by the live table for the specified device. Device names on output can be customised by the following options: devno (major and minor pair, used by default), blkdevname (block device name), devname (map name for device-mapper devices, equal to blkdevname otherwise). 🔗

help

help [-c|-C|--columns]

Outputs a summary of the commands available, optionally including the list of report fields. 🫶

info

info [device_name ...]

Outputs some brief information about the device in the form:

State: SUSPENDED|ACTIVE, READ-ONLY
Read Ahead: sectors
Tables present: LIVE and/or INACTIVE
Open reference count
Last event sequence number (used by wait)
Major and minor device number
Number of targets in the live table
UUID

a whole lil identity card for your device, iconic 👑

part 1 done, bestie — there's more coming, don't go anywhere 💜

🌸 info

info -c|-C|--columns [--count count] [--interval seconds] [--noheadings|--headings none|abbrev|full|0|1|2] [-o fields] [-O|--sort sort_fields] [--nameprefixes] [--separator separator] [device_name]

bestie this one is the customisation queen 👑 — you get output, but you decide what it looks like.

Fields are comma-separated and you choose them from this exact list: name, major, minor, attr, open, segments, events, uuid.

The attributes that show up are: (L)ive, (I)nactive, (s)uspended, (r)ead-only, read-(w)rite.

Pro tip incoming: put a + in front of the list and it appends to the default selection of columns instead of replacing it. And if you put a - in front of any sort field, that column sorts in reverse. 💅

🦋 ls

ls [--target target_type] [-o options] [--exec command] [--tree]

Lists device names, simple as. ✨

  • Optionally you can list only the devices that have at least one target of the type you specify.
  • Optionally you can run a command for each device — the device name gets appended to the command you supply.

The device names on output can be customised with these options:

  • devno — the major and minor pair, and this is what's used by default
  • blkdevname — the block device name
  • devname — the map name for device-mapper devices, and equal to blkdevname otherwise

--tree shows you the dependencies between devices as a tree 🌳 and it takes a comma-separated list of options.

Some of those options say what info gets displayed against each node:

  • device / nodevice
  • blkdevname
  • active, open, rw, uuid

And the others say how the tree is drawn:

  • ascii, utf, vt100
  • compact, inverted, notrunc

🎀 reload

reload device_name [--table table|table_file]

Loads table or table_file into the inactive table slot for device_name. If you don't supply either one, it just reads a table from standard input. no thoughts, head empty, stdin goes in 📥

🧚 mangle

mangle [device_name ...]

Makes sure the existing device-mapper device_name and UUID are in the correct mangled form, containing only whitelisted characters (the ones udev supports), and renames if it needs to. Any character that's not on the whitelist gets mangled based on the --manglename setting.

Heads up: automatic rename only works for device names, not for device UUIDs, because the kernel does not allow changing the UUID of active devices. 😭

Any incorrect UUIDs are only reported — you have to fix those by hand: deactivate the device first, then reactivate it with the proper mangling mode (see also --manglename).

💜 measure

measure [device_name ...]

Shows the data that device_name would report to the IMA subsystem if a measurement was triggered right now. This is for debugging and it does not actually trigger a measurement. it's giving "preview mode" 🫶

🔥 message

message device_name sector message

Send a message to the target. If no sector is needed, use 0.

🌈 mknodes

mknodes [device_name ...]

Makes sure the node in /dev/mapper for device_name is correct. If you don't supply a device_name, it makes sure that all nodes in /dev/mapper correspond to mapped devices currently loaded by the device-mapper kernel driver — adding, changing or removing nodes as necessary. spring cleaning energy ✨🧹

💅 remove

remove [-f|--force] [--retry] [--deferred] device_name ...

Removes a device. It will no longer be visible to dmsetup.

Open devices can't be removed, but adding --force will replace the table with one that fails all I/O. --deferred enables deferred removal of open devices — the device gets removed when the last user closes it.

The deferred removal feature is supported since version 4.27.0 of the device-mapper driver available in upstream kernel version 3.13. (Use dmsetup version to check this.)

If an attempt to remove a device fails — maybe because a process run from a quick udev rule temporarily opened the device — the --retry option causes the operation to be retried for a few seconds before it gives up.

🚨 Do NOT combine --force and --udevcookie, because udev may start processing udev rules in the middle of error target replacement and that results in nondeterministic behavior. we do not stan chaos 🙈

⭐ remove_all

remove_all [-f|--force] [--deferred]

Attempts to remove all device definitions, i.e. it resets the driver. It also runs mknodes afterwards. Use with care! 😭

Open devices can't be removed, but adding --force will replace the table with one that fails all I/O. --deferred enables deferred removal of open devices — the device gets removed when the last user closes it.

The deferred removal feature is supported since version 4.27.0 of the device-mapper driver available in upstream kernel version 3.13.

🎀 rename

rename device_name new_name

Renames a device. slay 💅

rename device_name --setuuid uuid

Sets the UUID of a device that was created without a UUID. After a UUID has been set it cannot be changed. periodt.

🌸 resume

resume device_name ... [--addnodeoncreate|--addnodeonresume] [--noflush] [--nolockfs] [--readahead [+]sectors|auto|none]

Un-suspends a device. If an inactive table has been loaded, it becomes live. Postponed I/O then gets re-queued for processing. wake up bestie, we're back 🫶✨

🦋 setgeometry

setgeometry device_name cyl head sect start

Sets the device geometry to C/H/S.

💜 splitname

splitname device_name [subsystem]

Splits the given device name into subsystem constituents. The default subsystem is LVM.

LVM currently generates device names by concatenating the names of the Volume Group, Logical Volume and any internal layer, with a hyphen as the separator. Any hyphens within the names are doubled to escape them.

⚠️ The precise encoding might change without notice in any future release, so we recommend you always decode using the current version of this command. iykyk 🔮

🌈 stats

stats command [options]

Manages IO statistics regions for devices. See dmstats(8) for more details. 📊

🔥 status

status [--target target_type] [--noflush] [device_name ...]

Outputs status information for each of the device's targets. With --target, only information relating to the specified target type is displayed.

With --noflush, the thin target (from version 1.3.0) doesn't commit any outstanding changes to disk before reporting its statistics.

💅 suspend

suspend device_name ... [--nolockfs] [--noflush]

Suspends a device. Any I/O that has already been mapped by the device but has not yet completed will be flushed. Any further I/O to that device will be postponed for as long as the device is suspended. 🧊

If there's a filesystem on the device that supports the operation, an attempt will be made to sync it first unless --nolockfs is specified.

Some targets — such as recent (October 2006) versions of multipath — may support the --noflush option. That lets outstanding I/O that has not yet reached the device remain unflushed.

⭐ table

table [--concise] [--target target_type] [--showkeys] [device_name ...]

Outputs the current table for the device in a format that can be fed back in using the create or load commands. 🔁

With --target, only information relating to the specified target type is displayed.

Real encryption keys are suppressed in the table output for crypt and integrity targets unless the --showkeys parameter is supplied. Kernel key references prefixed with : are not affected by the parameter and are always displayed (crypt target only). 🙈

With --concise, the output is presented concisely on a single line. Commas separate the name, uuid, minor device number, flags (ro or rw) and the table (if present). Semi-colons separate devices. Backslashes escape any commas, semi-colons or backslashes. See CONCISE FORMAT below.

🎀 targets

Displays the names and versions of the currently-loaded targets.

🧚 udevcomplete

udevcomplete cookie

Wake any processes that are waiting for udev to complete processing the specified cookie. ⏰

🌸 udevcomplete_all

udevcomplete_all [age_in_minutes]

Remove all cookies older than the specified number of minutes. Any process waiting on a cookie will be resumed immediately.

💜 udevcookie

List all existing cookies. Cookies are system-wide semaphores with keys prefixed by two predefined bytes (0x0D4D). 🍪

🌈 udevcreatecookie

Creates a new cookie to synchronize actions with udev processing. The output is a cookie value.

Normally we don't need to create cookies since dmsetup creates and destroys them for each action automatically. However, we can generate one explicitly to group several actions together and use only one cookie instead.

We can define a cookie to use for each relevant command by using the --udevcookie option. Alternatively, we can export this value into the environment of the dmsetup process as the DM_UDEV_COOKIE variable and it will be used automatically with all subsequent commands until it is unset.

⚠️ Invoking this command will create a system-wide semaphore that needs to be cleaned up explicitly by calling the udevreleasecookie command. don't leave it hanging bestie 😭

🔥 udevflags

udevflags cookie

Parses the given cookie value and extracts any encoded udev control flags. The output is in environment key format that is suitable for use in udev rules.

If the flag has its symbolic name assigned then the output is DM_UDEV_FLAG_<flag_name> = '1', DM_UDEV_FLAG<flag_position> = '1' otherwise.

Subsystem udev flags don't have symbolic names assigned and they are always reported as DM_SUBSYSTEM_UDEV_FLAG<flag_position> = '1'. There are 16 udev flags altogether. 🚩

💅 udevreleasecookie

udevreleasecookie [cookie]

Waits for all pending udev processing bound to the given cookie value and releases the underlying semaphore. If the cookie is not given directly, the command will try to use a value defined by the DM_UDEV_COOKIE environment variable. 🫶

⭐ version

Outputs version information.

🎀 wait

wait device_name [--noflush] [event_nr]

Sleeps until the event counter for device_name exceeds event_nr. 😴

Use -v to see the event number returned. To wait until the next event is triggered, use info to find the last event number.

With --noflush, the thin target (from version 1.3.0) doesn't commit any outstanding changes to disk before reporting its statistics.

🧹 wipe_table

wipe_table device_name ... [-f|--force] [--noflush] [--nolockfs]

okay bestie so this one is the gentle goodbye command. You wait for literally every bit of I/O still in-flight through the device to finish, and THEN you swap the table out for a brand new one that fails every single new I/O that gets sent to the device. no more requests, periodt 💅

and if it works? it should release any devices that were being held open by the device's table(s). bye girl, you're free 🦋

📋 TABLE FORMAT 📋

so every single line of the table = one single target, and the shape of it is:

logical_start_sector num_sectors target_type target_args

the simple target types and their args are giving:

linear destination_device start_sector

the classic, the OG, the traditional linear mapping. 👑

striped num_stripes chunk_size [destination start_sector] ...

creates a striped area ✨

like, striped 2 32 /dev/hda1 0 /dev/hdb1 0 will map the first chunk (16 KiB) like this:

LV chunk 1 → hda1, chunk 1
LV chunk 2 → hdb1, chunk 1
LV chunk 3 → hda1, chunk 2
LV chunk 4 → hdb1, chunk 2
etc.

error

errors out any I/O that goes to this area. useful for testing, or for making devices with literal holes in them 🕳️ (holes as in functional holes, bestie, not aesthetic ones)

zero

returns blocks of zeroes on reads. any data you write gets discarded silently, no drama, no note. it's the block-device version of the /dev/zero character-device data sink, which is described over in null(4) 💀

and then the more complex targets, the ones with main character energy:

cache

makes a block device (like, say, a spindle) faster by dynamically migrating some of its data over to a faster, smaller device (like an SSD). glow-up via relocation 🧚

crypt

transparent encryption of block devices using the kernel crypto API 🔐

delay

delays reads and/or writes to different devices. useful for testing ⏳

flakey

creates a mapping similar to the linear target but acts unreliable periodically. useful for simulating failing devices when testing 🙈

mirror

mirrors data across two or more devices 🪞

multipath

mediates access through multiple paths to the same device 🛣️

raid

offers an interface to the kernel's software raid driver, md

snapshot

supports snapshots of devices 📸

thin, thin-pool

supports thin provisioning of devices, and also gives you better snapshot support

if you wanna find out more about the various targets, their table formats and their status lines, please go read the files in the Documentation/admin-guide/device-mapper directory in the kernel source tree. (your distribution might have a copy of this info sitting in the documentation directory for the device-mapper package, so check there too 🫶)

🎀 EXAMPLES 🎀

# A table to join two disks together
0 1028160 linear /dev/hda 0
1028160 3903762 linear /dev/hdb 0

# A table to stripe across the two disks,
# and add the spare space from
# hdb to the back of the volume
0 2056320 striped 2 32 /dev/hda 0 /dev/hdb 0
2056320 2875602 linear /dev/hdb 1028160

✨ CONCISE FORMAT ✨

a concise representation of one or more devices:

  • a comma separates the fields of each device
  • a semi-colon separates devices

the representation of a device takes the form:

<name>,<uuid>,<minor>,<flags>,<table>[,<table>+][;<name>,<uuid>,\
<minor>,<flags>,<table>[,<table>+]]

the fields are, bestie, as follows:

  • name — the name of the device
  • uuid — the UUID of the device (or empty)
  • minor — the minor number of the device. if it's empty, the kernel assigns a suitable minor number for you 🎁
  • flags — the supported flags are:
    • ro — sets the table being loaded for the device read-only
    • rw — sets the table being loaded for the device read-write (this is the default)
  • table — one line of the table. see TABLE FORMAT above ⬆️

🦋 EXAMPLES 🦋

# A simple linear read-only device
test-linear-small,,,ro,\
 0 2097152 linear /dev/loop0 0,\
 2097152 2097152 linear /dev/loop1 0

# Two linear devices
test-linear-small,,,,\
 0 2097152 linear /dev/loop0 0;\
test-linear-large,,,,\
 0 2097152 linear /dev/loop1 0,\
 2097152 2097152 linear /dev/loop2 0

🌈 ENVIRONMENT VARIABLES 🌈

  • DM_DEV_DIR — the device directory name. defaults to "/dev" and it must be an absolute path, no shortcuts bestie 🚫
  • DM_UDEV_COOKIE — a cookie to use for all relevant commands so they synchronize with udev processing. it's an alternative to using the --udevcookie option 🍪
  • DM_DEFAULT_NAME_MANGLING_MODE — a default mangling mode. defaults to "auto". it's an alternative to using the --manglename option
  • DM_DEBUG_WITH_LINE_NUMBERS — set this to 1 to prepend the source file and line number to debug messages. it gets automatically enabled by -vvvv 🔍

👑 AUTHORS 👑

original version: Joe Thornber

💜 SEE ALSO 💜

dmstats(8), udev(7), udevadm(8)

LVM2 resource page:

Device-mapper resource page:

and that's the whole page, bestie!! this one is from the Linux manual, dated Mar 26 2025, and it's page DMSETUP(8) 🎀 go forth and map your devices, you absolute icon 🫶✨

📦 where this page comes from