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