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