1DMSETUP(8) MAINTENANCE COMMANDS DMSETUP(8)
2
6 dmsetup — low level logical volume management
7
9 dmsetup clear device_name
10 dmsetup create device_name [-u|--uuid uuid]
11 [--addnodeoncreate|--addnodeonresume] [-n|--notable|--table
12 table|table_file] [--readahead [+]sectors|auto|none]
13 dmsetup create --concise [concise_device_specification]
14 dmsetup deps [-o options] [device_name...]
15 dmsetup help [-c|-C|--columns]
16 dmsetup info [device_name...]
17 dmsetup info -c|-C|--columns [--count count] [--interval seconds]
18 [--nameprefixes] [--noheadings] [-o fields] [-O|--sort
19 sort_fields] [--separator separator] [device_name]
20 dmsetup load device_name [--table table|table_file]
21 dmsetup ls [--target target_type] [--exec command] [--tree] [-o
22 options]
23 dmsetup mangle [device_name...]
24 dmsetup message device_name sector message
25 dmsetup mknodes [device_name...]
26 dmsetup reload device_name [--table table|table_file]
27 dmsetup remove [-f|--force] [--retry] [--deferred] device_name...
28 dmsetup remove_all [-f|--force] [--deferred]
29 dmsetup rename device_name new_name
30 dmsetup rename device_name --setuuid uuid
31 dmsetup resume device_name... [--addnodeoncreate|--addnodeonresume]
32 [--noflush] [--nolockfs] [--readahead [+]sectors|auto|none]
33 dmsetup setgeometry device_name cyl head sect start
34 dmsetup splitname device_name [subsystem]
35 dmsetup stats command [options]
36 dmsetup status [--target target_type] [--noflush] [device_name...]
37 dmsetup suspend [--nolockfs] [--noflush] device_name...
38 dmsetup table [--concise] [--target target_type] [--showkeys]
39 [device_name...]
40 dmsetup targets
41 dmsetup udevcomplete cookie
42 dmsetup udevcomplete_all [age_in_minutes]
43 dmsetup udevcookie
44 dmsetup udevcreatecookie
45 dmsetup udevflags cookie
46 dmsetup udevreleasecookie [cookie]
47 dmsetup version
48 dmsetup wait [--noflush] device_name [event_nr]
49 dmsetup wipe_table device_name... [-f|--force] [--noflush]
50 [--nolockfs]
51 devmap_name major minor
53 devmap_name major:minor
54
56 dmsetup manages logical devices that use the device-mapper driver.
57 Devices are created by loading a table that specifies a target for each
58 sector (512 bytes) in the logical device.
59 The first argument to dmsetup is a command. The second argument is the
61 logical device name or uuid.
62 Invoking the dmsetup tool as devmap_name (which is not normally dis‐
64 tributed and is supported only for historical reasons) is equivalent to
65 dmsetup info -c --noheadings -j major -m minor.
66
68 --addnodeoncreate
69 Ensure /dev/mapper node exists after dmsetup create.
70 --addnodeonresume
72 Ensure /dev/mapper node exists after dmsetup resume (default
73 with udev).
74 --checks
76 Perform additional checks on the operations requested and report
77 potential problems. Useful when debugging scripts. In some
78 cases these checks may slow down operations noticeably.
79 -c|-C|--columns
81 Display output in columns rather than as Field: Value lines.
82 --count count
84 Specify the number of times to repeat a report. Set this to zero
85 continue until interrupted. The default interval is one second.
86 -f|--force
88 Try harder to complete operation.
89 -h|--help
91 Outputs a summary of the commands available, optionally includ‐
92 ing the list of report fields (synonym with help command).
93 --inactive
95 When returning any table information from the kernel report on
96 the inactive table instead of the live table. Requires kernel
97 driver version 4.16.0 or above.
98 --interval seconds
100 Specify the interval in seconds between successive iterations
101 for repeating reports. If --interval is specified but --count is
102 not, reports will continue to repeat until interrupted. The
103 default interval is one second.
104 --manglename auto|hex|none
106 Mangle any character not on a whitelist using mangling_mode when
107 processing device-mapper device names and UUIDs. The names and
108 UUIDs are mangled on input and unmangled on output where the
109 mangling mode is one of: auto (only do the mangling if not man‐
110 gled yet, do nothing if already mangled, error on mixed), hex
111 (always do the mangling) and none (no mangling). Default mode
112 is auto. Character whitelist: 0-9, A-Z, a-z, #+-.:=@_. This
113 whitelist is also supported by udev. Any character not on a
114 whitelist is replaced with its hex value (two digits) prefixed
115 by \x. Mangling mode could be also set through
116 DM_DEFAULT_NAME_MANGLING_MODE environment variable.
117 -j|--major major
119 Specify the major number.
120 -m|--minor minor
122 Specify the minor number.
123 -n|--notable
125 When creating a device, don't load any table.
126 --nameprefixes
128 Add a "DM_" prefix plus the field name to the output. Useful
129 with --noheadings to produce a list of field=value pairs that
130 can be used to set environment variables (for example, in
131 udev(7) rules).
132 --noheadings Suppress the headings line when using columnar output.
134 --noflush Do not flush outstading I/O when suspending a device, or do
136 not commit thin-pool metadata when obtaining thin-pool status.
137 --nolockfs
139 Do not attempt to synchronize filesystem eg, when suspending a
140 device.
141 --noopencount
143 Tell the kernel not to supply the open reference count for the
144 device.
145 --noudevrules
147 Do not allow udev to manage nodes for devices in device-mapper
148 directory.
149 --noudevsync
151 Do not synchronise with udev when creating, renaming or removing
152 devices.
153 -o|--options options
155 Specify which fields to display.
156 --readahead [+]sectors|auto|none
158 Specify read ahead size in units of sectors. The default value
159 is auto which allows the kernel to choose a suitable value auto‐
160 matically. The + prefix lets you specify a minimum value which
161 will not be used if it is smaller than the value chosen by the
162 kernel. The value none is equivalent to specifying zero.
163 -r|--readonly
165 Set the table being loaded read-only.
166 -S|--select selection
168 Process only items that match selection criteria. If the com‐
169 mand is producing report output, adding the "selected" column
170 (-o selected) displays all rows and shows 1 if the row matches
171 the selection and 0 otherwise. The selection criteria are
172 defined by specifying column names and their valid values while
173 making use of supported comparison operators. As a quick help
174 and to see full list of column names that can be used in selec‐
175 tion and the set of supported selection operators, check the
176 output of dmsetup info -c -S help command.
177 --table table
179 Specify a one-line table directly on the command line. See
180 below for more information on the table format.
181 --udevcookie cookie
183 Use cookie for udev synchronisation. Note: Same cookie should
184 be used for same type of operations i.e. creation of multiple
185 different devices. It's not adviced to combine different opera‐
186 tions on the single device.
187 -u|--uuid
189 Specify the uuid.
190 -y|--yes
192 Answer yes to all prompts automatically.
193 -v|--verbose [-v|--verbose]
195 Produce additional output.
196 --verifyudev
198 If udev synchronisation is enabled, verify that udev operations
199 get performed correctly and try to fix up the device nodes
200 afterwards if not.
201 --version
203 Display the library and kernel driver version.
204
206 clear device_name
207 Destroys the table in the inactive table slot for device_name.
208 create device_name [-u|--uuid uuid]
210 [--addnodeoncreate|--addnodeonresume] [-n|--notable|--table
211 table|table_file] [--readahead [+]sectors|auto|none]
212 Creates a device with the given name. If table or table_file is
213 supplied, the table is loaded and made live. Otherwise a table
214 is read from standard input unless --notable is used. The
215 optional uuid can be used in place of device_name in subsequent
216 dmsetup commands. If successful the device will appear in table
217 and for live device the node /dev/mapper/device_name is created.
218 See below for more information on the table format.
219 create --concise [concise_device_specification]
221 Creates one or more devices from a concise device specification.
222 Each device is specified by a comma-separated list: name, uuid,
223 minor number, flags, comma-separated table lines. Flags
224 defaults to read-write (rw) or may be read-only (ro). Uuid,
225 minor number and flags are optional so those fields may be
226 empty. A semi-colon separates specifications of different
227 devices. Use a backslash to escape the following character, for
228 example a comma or semi-colon in a name or table. See also CON‐
229 CISE FORMAT below.
230 deps [-o options] [device_name...]
232 Outputs a list of devices referenced by the live table for the
233 specified device. Device names on output can be customised by
234 following options: devno (major and minor pair, used by
235 default), blkdevname (block device name), devname (map name for
236 device-mapper devices, equal to blkdevname otherwise).
237 help [-c|-C|--columns]
239 Outputs a summary of the commands available, optionally includ‐
240 ing the list of report fields.
241 info [device_name...]
243 Outputs some brief information about the device in the form:
244 State: SUSPENDED|ACTIVE, READ-ONLY
245 Tables present: LIVE and/or INACTIVE
246 Open reference count
247 Last event sequence number (used by wait)
248 Major and minor device number
249 Number of targets in the live table
250 UUID
251 info -c|-C|--columns [--count count] [--interval seconds]
253 [--nameprefixes] [--noheadings] [-o fields] [-O|--sort
254 sort_fields] [--separator separator] [device_name]
255 Output you can customise. Fields are comma-separated and chosen
256 from the following list: name, major, minor, attr, open, seg‐
257 ments, events, uuid. Attributes are: (L)ive, (I)nactive,
258 (s)uspended, (r)ead-only, read-(w)rite. Precede the list with
259 '+' to append to the default selection of columns instead of
260 replacing it. Precede any sort field with '-' for a reverse
261 sort on that column.
262 ls [--target target_type] [--exec command] [--tree] [-o options]
264 List device names. Optionally only list devices that have at
265 least one target of the specified type. Optionally execute a
266 command for each device. The device name is appended to the
267 supplied command. Device names on output can be customised by
268 following options: devno (major and minor pair, used by
269 default), blkdevname (block device name), devname (map name for
270 device-mapper devices, equal to blkdevname otherwise). --tree
271 displays dependencies between devices as a tree. It accepts a
272 comma-separate list of options. Some specify the information
273 displayed against each node: device/nodevice; blkdevname;
274 active, open, rw, uuid. Others specify how the tree is dis‐
275 played: ascii, utf, vt100; compact, inverted, notrunc.
276 load|reload device_name [--table table|table_file]
278 Loads table or table_file into the inactive table slot for
279 device_name. If neither is supplied, reads a table from stan‐
280 dard input.
281 mangle [device_name...]
283 Ensure existing device-mapper device_name and UUID is in the
284 correct mangled form containing only whitelisted characters
285 (supported by udev) and do a rename if necessary. Any character
286 not on the whitelist will be mangled based on the --manglename
287 setting. Automatic rename works only for device names and not
288 for device UUIDs because the kernel does not allow changing the
289 UUID of active devices. Any incorrect UUIDs are reported only
290 and they must be manually corrected by deactivating the device
291 first and then reactivating it with proper mangling mode used
292 (see also --manglename).
293 message device_name sector message
295 Send message to target. If sector not needed use 0.
296 mknodes [device_name...]
298 Ensure that the node in /dev/mapper for device_name is correct.
299 If no device_name is supplied, ensure that all nodes in
300 /dev/mapper correspond to mapped devices currently loaded by the
301 device-mapper kernel driver, adding, changing or removing nodes
302 as necessary.
303 remove [-f|--force] [--retry] [--deferred] device_name...
305 Removes a device. It will no longer be visible to dmsetup.
306 Open devices cannot be removed, but adding --force will replace
307 the table with one that fails all I/O. --deferred will enable
308 deferred removal of open devices - the device will be removed
309 when the last user closes it. The deferred removal feature is
310 supported since version 4.27.0 of the device-mapper driver
311 available in upstream kernel version 3.13. (Use dmsetup version
312 to check this.) If an attempt to remove a device fails, perhaps
313 because a process run from a quick udev rule temporarily opened
314 the device, the --retry option will cause the operation to be
315 retried for a few seconds before failing. Do NOT combine
316 --force and --udevcookie, as udev may start to process udev
317 rules in the middle of error target replacement and result in
318 nondeterministic result.
319 remove_all [-f|--force] [--deferred]
321 Attempts to remove all device definitions i.e. reset the driver.
322 This also runs mknodes afterwards. Use with care! Open devices
323 cannot be removed, but adding --force will replace the table
324 with one that fails all I/O. --deferred will enable deferred
325 removal of open devices - the device will be removed when the
326 last user closes it. The deferred removal feature is supported
327 since version 4.27.0 of the device-mapper driver available in
328 upstream kernel version 3.13.
329 rename device_name new_name
331 Renames a device.
332 rename device_name --setuuid uuid
334 Sets the uuid of a device that was created without a uuid.
335 After a uuid has been set it cannot be changed.
336 resume device_name... [--addnodeoncreate|--addnodeonresume]
338 [--noflush] [--nolockfs] [--readahead [+]sectors|auto|none]
339 Un-suspends a device. If an inactive table has been loaded, it
340 becomes live. Postponed I/O then gets re-queued for processing.
341 setgeometry device_name cyl head sect start
343 Sets the device geometry to C/H/S.
344 splitname device_name [subsystem]
346 Splits given device name into subsystem constituents. The
347 default subsystem is LVM. LVM currently generates device names
348 by concatenating the names of the Volume Group, Logical Volume
349 and any internal Layer with a hyphen as separator. Any hyphens
350 within the names are doubled to escape them. The precise encod‐
351 ing might change without notice in any future release, so we
352 recommend you always decode using the current version of this
353 command.
354 stats command [options]
356 Manages IO statistics regions for devices. See dmstats(8) for
357 more details.
358 status [--target target_type] [--noflush] [device_name...]
360 Outputs status information for each of the device's targets.
361 With --target, only information relating to the specified target
362 type any is displayed. With --noflush, the thin target (from
363 version 1.3.0) doesn't commit any outstanding changes to disk
364 before reporting its statistics.
365 suspend [--nolockfs] [--noflush] device_name...
368 Suspends a device. Any I/O that has already been mapped by the
369 device but has not yet completed will be flushed. Any further
370 I/O to that device will be postponed for as long as the device
371 is suspended. If there's a filesystem on the device which sup‐
372 ports the operation, an attempt will be made to sync it first
373 unless --nolockfs is specified. Some targets such as recent
374 (October 2006) versions of multipath may support the --noflush
375 option. This lets outstanding I/O that has not yet reached the
376 device to remain unflushed.
377 table [--concise] [--target target_type] [--showkeys] [device_name...]
379 Outputs the current table for the device in a format that can be
380 fed back in using the create or load commands. With --target,
381 only information relating to the specified target type is dis‐
382 played. Real encryption keys are suppressed in the table output
383 for crypt and integrity targets unless the --showkeys parameter
384 is supplied. Kernel key references prefixed with : are not
385 affected by the parameter and get displayed always (crypt target
386 only). With --concise, the output is presented concisely on a
387 single line. Commas then separate the name, uuid, minor device
388 number, flags ('ro' or 'rw') and the table (if present). Semi-
389 colons separate devices. Backslashes escape any commas, semi-
390 colons or backslashes. See CONCISE FORMAT below.
391 targets
393 Displays the names and versions of the currently-loaded targets.
394 udevcomplete cookie
396 Wake any processes that are waiting for udev to complete pro‐
397 cessing the specified cookie.
398 udevcomplete_all [age_in_minutes]
400 Remove all cookies older than the specified number of minutes.
401 Any process waiting on a cookie will be resumed immediately.
402 udevcookie
404 List all existing cookies. Cookies are system-wide semaphores
405 with keys prefixed by two predefined bytes (0x0D4D).
406 udevcreatecookie
408 Creates a new cookie to synchronize actions with udev process‐
409 ing. The output is a cookie value. Normally we don't need to
410 create cookies since dmsetup creates and destroys them for each
411 action automatically. However, we can generate one explicitly to
412 group several actions together and use only one cookie instead.
413 We can define a cookie to use for each relevant command by using
414 --udevcookie option. Alternatively, we can export this value
415 into the environment of the dmsetup process as DM_UDEV_COOKIE
416 variable and it will be used automatically with all subsequent
417 commands until it is unset. Invoking this command will create
418 system-wide semaphore that needs to be cleaned up explicitly by
419 calling udevreleasecookie command.
420 udevflags cookie
422 Parses given cookie value and extracts any udev control flags
423 encoded. The output is in environment key format that is suit‐
424 able for use in udev rules. If the flag has its symbolic name
425 assigned then the output is DM_UDEV_FLAG_<flag_name> = '1',
426 DM_UDEV_FLAG<flag_position> = '1' otherwise. Subsystem udev
427 flags don't have symbolic names assigned and these ones are
428 always reported as DM_SUBSYSTEM_UDEV_FLAG<flag_position> = '1'.
429 There are 16 udev flags altogether.
430 udevreleasecookie [cookie]
432 Waits for all pending udev processing bound to given cookie
433 value and clean up the cookie with underlying semaphore. If the
434 cookie is not given directly, the command will try to use a
435 value defined by DM_UDEV_COOKIE environment variable.
436 version
438 Outputs version information.
439 wait [--noflush] device_name [event_nr]
441 Sleeps until the event counter for device_name exceeds event_nr.
442 Use -v to see the event number returned. To wait until the next
443 event is triggered, use info to find the last event number.
444 With --noflush, the thin target (from version 1.3.0) doesn't
445 commit any outstanding changes to disk before reporting its sta‐
446 tistics.
447 wipe_table device_name... [-f|--force] [--noflush] [--nolockfs]
449 Wait for any I/O in-flight through the device to complete, then
450 replace the table with a new table that fails any new I/O sent
451 to the device. If successful, this should release any devices
452 held open by the device's table(s).
453
455 Each line of the table specifies a single target and is of the form:
456 logical_start_sector num_sectors target_type target_args
458 Simple target types and target args include:
460 linear destination_device start_sector
462 The traditional linear mapping.
463 striped num_stripes chunk_size [destination start_sector]...
465 Creates a striped area.
466 e.g. striped 2 32 /dev/hda1 0 /dev/hdb1 0 will map the first
467 chunk (16k) as follows:
468 LV chunk 1-> hda1, chunk 1
469 LV chunk 2-> hdb1, chunk 1
470 LV chunk 3-> hda1, chunk 2
471 LV chunk 4-> hdb1, chunk 2
472 etc.
473 error Errors any I/O that goes to this area. Useful for testing or
475 for creating devices with holes in them.
476 zero Returns blocks of zeroes on reads. Any data written is dis‐
478 carded silently. This is a block-device equivalent of the
479 /dev/zero character-device data sink described in null(4).
480 More complex targets include:
482 cache Improves performance of a block device (eg, a spindle) by dynam‐
484 ically migrating some of its data to a faster smaller device
485 (eg, an SSD).
486 crypt Transparent encryption of block devices using the kernel crypto
488 API.
489 delay Delays reads and/or writes to different devices. Useful for
491 testing.
492 flakey Creates a similar mapping to the linear target but exhibits
494 unreliable behaviour periodically. Useful for simulating fail‐
495 ing devices when testing.
496 mirror Mirrors data across two or more devices.
498 multipath
500 Mediates access through multiple paths to the same device.
501 raid Offers an interface to the kernel's software raid driver, md.
503 snapshot
505 Supports snapshots of devices.
506 thin, thin-pool
508 Supports thin provisioning of devices and also provides a better
509 snapshot support.
510 To find out more about the various targets and their table formats and
512 status lines, please read the files in the Documentation/device-mapper
513 directory in the kernel source tree. (Your distribution might include
514 a copy of this information in the documentation directory for the
515 device-mapper package.)
516
518 # A table to join two disks together
519 0 1028160 linear /dev/hda 0
520 1028160 3903762 linear /dev/hdb 0
521 # A table to stripe across the two disks,
522 # and add the spare space from
523 # hdb to the back of the volume
524 0 2056320 striped 2 32 /dev/hda 0 /dev/hdb 0
525 2056320 2875602 linear /dev/hdb 1028160
526
528 A concise representation of one of more devices.
529 - A comma separates the fields of each device.
531 - A semi-colon separates devices.
532 The representation of a device takes the form:
534 <name>,<uuid>,<minor>,<flags>,<table>[,<ta‐
536 ble>+][;<dev_name>,<uuid>,<minor>,<flags>,<table>[,<table>+]]
537 The fields are:
539 name The name of the device.
541 uuid The UUID of the device (or empty).
543 minor The minor number of the device. If empty, the kernel assigns a
545 suitable minor number.
546 flags Supported flags are:
548 ro Sets the table being loaded for the device read-only
550 rw Sets the table being loaded for the device read-write
551 (default)
552 table One line of the table. See TABLE FORMAT above.
554
556 # A simple linear read-only device
557 test-linear-small,,,ro,0 2097152 linear /dev/loop0 0, 2097152 2097152
558 linear /dev/loop1 0
559 # Two linear devices
561 test-linear-small,,,,0 2097152 linear /dev/loop0 0;test-lin‐
562 ear-large,,,, 0 2097152 linear /dev/loop1 0, 2097152 2097152 linear
563 /dev/loop2 0
564
566 DM_DEV_DIR
567 The device directory name. Defaults to "/dev" and must be an
568 absolute path.
569 DM_UDEV_COOKIE
571 A cookie to use for all relevant commands to synchronize with
572 udev processing. It is an alternative to using --udevcookie
573 option.
574 DM_DEFAULT_NAME_MANGLING_MODE
576 A default mangling mode. Defaults to "auto" and it is an alter‐
577 native to using --manglename option.
578
580 Original version: Joe Thornber <thornber@redhat.com>
581
583 dmstats(8), udev(7), udevadm(8)
584 LVM2 resource page: https://www.sourceware.org/lvm2/
586 Device-mapper resource page: http://sources.redhat.com/dm/
587Linux Apr 06 2006 DMSETUP(8)