man/dmsetup.8.in

   1 .TH DMSETUP 8 "Apr 06 2006" "Linux" "MAINTENANCE COMMANDS"
   2 .SH NAME
   3 dmsetup \- low level logical volume management
   4 .SH SYNOPSIS
   5 .ad l
   6 .B dmsetup clear
   7 .I device_name
   8 .br
   9 .B dmsetup create
  10 .I device_name
  11 .RB [ \-u
  12 .IR uuid ]
  13 .RB [ \-\-notable | \-\-table
  14 .RI < table >|
  15 .RS
  16 .IR table_file ]
  17 .RB [{ \-\-addnodeoncreate | \-\-addnodeonresume }]
  18 .RB [ \-\-readahead
  19 .RI [ \+ ]< sectors >| auto | none ]
  20 .RE
  21 .br
  22 .B dmsetup deps
  23 .RB [ \-o
  24 .IR options ]
  25 .RI [ device_name ]
  26 .br
  27 .B dmsetup help
  28 .RB [ \-c | \-C | \-\-columns ]
  29 .br
  30 .B dmsetup info
  31 .RI [ device_name ]
  32 .br
  33 .B dmsetup info
  34 .BR \-c | \-C | \-\-columns
  35 .RB [ \-\-noheadings ]
  36 .RB [ \-\-separator
  37 .IR separator ]
  38 .RS
  39 .RB [ \-o
  40 .IR fields ]
  41 .RB [ \-O | \-\-sort
  42 .IR sort_fields ]
  43 .RI [ device_name ]
  44 .RE
  45 .br
  46 .B dmsetup load
  47 .I device_name
  48 .RB [ \-\-table
  49 .RI < table >| table_file ]
  50 .br
  51 .B dmsetup ls
  52 .RB [ \-\-target
  53 .IR target_type ]
  54 .RB [ \-\-exec
  55 .IR command ]
  56 .RB [ \-\-tree ]
  57 .RB [ \-o
  58 .IR options ]
  59 .RE
  60 .br
  61 .B dmsetup message
  62 .I device_name sector message
  63 .br
  64 .B dmsetup mknodes
  65 .RI [ device_name ]
  66 .br
  67 .B dmsetup mangle
  68 .RI [ device_name ]
  69 .br
  70 .B dmsetup reload
  71 .I device_name
  72 .RB [ \-\-table
  73 .RI < table >| table_file ]
  74 .br
  75 .B dmsetup wipe_table
  76 .I device_name
  77 .br
  78 .B dmsetup remove
  79 .RB [ \-f | \-\-force ]
  80 .RB [ \-\-retry ]
  81 .I device_name
  82 .br
  83 .B dmsetup remove_all
  84 .RB [ \-f | \-\-force ]
  85 .br
  86 .B dmsetup rename
  87 .I device_name new_name
  88 .br
  89 .B dmsetup rename
  90 .I device_name
  91 .B \-\-setuuid
  92 .I uuid
  93 .br
  94 .B dmsetup resume
  95 .I device_name
  96 .RB [{ \-\-addnodeoncreate | \-\-addnodeonresume }]
  97 .RS
  98 .RB [ \-\-readahead
  99 .RI [ \+ ]< sectors >| auto | none ]
 100 .RE
 101 .br
 102 .B dmsetup setgeometry
 103 .I device_name cyl head sect start
 104 .br
 105 .B dmsetup splitname
 106 .I device_name
 107 .RI [ subsystem ]
 108 .br
 109 .B dmsetup status
 110 .RB [ \-\-target
 111 .IR target_type ]
 112 .RI [ device_name ]
 113 .br
 114 .B dmsetup suspend
 115 .RB [ \-\-nolockfs ]
 116 .RB [ \-\-noflush ]
 117 .I device_name
 118 .br
 119 .B dmsetup table
 120 .RB [ \-\-target
 121 .IR target_type ]
 122 .RB [ \-\-showkeys ]
 123 .RI [ device_name ]
 124 .br
 125 .B dmsetup targets
 126 .br
 127 .B dmsetup udevcomplete
 128 .I cookie
 129 .br
 130 .B dmsetup udevcomplete_all
 131 .RI [ age_in_minutes ]
 132 .br
 133 .B dmsetup udevcookies
 134 .br
 135 .B dmsetup udevcreatecookie
 136 .br
 137 .B dmsetup udevflags
 138 .I cookie
 139 .br
 140 .B dmsetup udevreleasecookie
 141 .RI [ cookie ]
 142 .br
 143 .B dmsetup version
 144 .br
 145 .B dmsetup wait
 146 .I device_name
 147 .RI [ event_nr ]
 148 .br
 149
 150 .B devmap_name
 151 .I major minor
 152 .br
 153 .B devmap_name
 154 .I major:minor
 155 .ad b
 156 .SH DESCRIPTION
 157 dmsetup manages logical devices that use the device-mapper driver.
 158 Devices are created by loading a table that specifies a target for
 159 each sector (512 bytes) in the logical device.
 160
 161 The first argument to dmsetup is a command.
 162 The second argument is the logical device name or uuid.
 163
 164 Invoking the command as \fBdevmap_name\fP is equivalent to
 165 .br
 166 \fBdmsetup info \-c \-\-noheadings \-j \fImajor\fB \-m \fIminor\fP.
 167 .SH OPTIONS
 168 .TP
 169 .B \-\-addnodeoncreate
 170 Ensure /dev/mapper node exists after dmsetup create.
 171 .TP
 172 .B \-\-addnodeonresume
 173 Ensure /dev/mapper node exists after dmsetup resume (default with udev).
 174 .TP
 175 .B \-\-checks
 176 Perform additional checks on the operations requested and report
 177 potential problems.  Useful when debugging scripts.
 178 In some cases these checks may slow down operations noticeably.
 179 .TP
 180 .BR \-c | \-C | \-\-columns
 181 Display output in columns rather than as Field: Value lines.
 182 .TP
 183 .BR \-h | \-\-help
 184 Outputs a summary of the commands available, optionally including
 185 the list of report fields (synonym with \fBhelp\fP command).
 186 .TP
 187 .B \-\-inactive
 188 When returning any table information from the kernel report on the
 189 inactive table instead of the live table.
 190 Requires kernel driver version 4.16.0 or above.
 191 .TP
 192 .IR \fB\-\-manglename \ < mangling_mode >
 193 Mangle any character not on a whitelist using mangling_mode when
 194 processing device-mapper device names. The names are mangled on
 195 input and unmangled on output where the mangling_mode is one of:
 196 none (no mangling), hex (always do the mangling) and auto
 197 (only do the mangling if not mangled yet, do nothing if already
 198 mangled, error on mixed; this is used by default).
 199 Character whitelist: 0-9, A-Z, a-z, #+-.:=@_. This whitelist is
 200 also supported by udev. Any character not on a whitelist is replaced
 201 with its hex value (two digits) prefixed by \\x.
 202 .TP
 203 .BR \-j | \-\-major\ \fImajor
 204 Specify the major number.
 205 .TP
 206 .BR \-m | \-\-minor\ \fIminor
 207 Specify the minor number.
 208 .TP
 209 .BR \-n | \-\-noheadings
 210 Suppress the headings line when using columnar output.
 211 .TP
 212 .B \-\-noopencount
 213 Tell the kernel not to supply the open reference count for the device.
 214 .TP
 215 .B \-\-notable
 216 When creating a device, don't load any table.
 217 .TP
 218 .B \-\-noudevrules
 219 Do not allow udev to manage nodes for devices in device-mapper directory.
 220 .TP
 221 .B \-\-noudevsync
 222 Do not synchronise with udev when creating, renaming or removing devices.
 223 .TP
 224 .BR \-o | \-\-options
 225 Specify which fields to display.
 226 .TP
 227 .IR \fB\-\-readahead \ [ \+ ]< sectors >| auto | none
 228 Specify read ahead size in units of sectors.
 229 The default value is \fIauto\fP which allows the kernel to choose
 230 a suitable value automatically.  The \fI\+\fP prefix lets you
 231 specify a minimum value which will not be used if it is
 232 smaller than the value chosen by the kernel.
 233 The value \fInone\fP is equivalent to specifying zero.
 234 .TP
 235 .BR \-r | \-\-readonly
 236 Set the table being loaded read-only.
 237 .TP
 238 .IR \fB\-\-table \ < table >
 239 Specify a one-line table directly on the command line.
 240 .TP
 241 .B \-\-udevcookie \fIcookie
 242 Use cookie for udev synchronisation.
 243 .TP
 244 .BR \-u | \-\-uuid
 245 Specify the uuid.
 246 .TP
 247 .BR \-y | \-\-yes
 248 Answer yes to all prompts automatically.
 249 .TP
 250 .BR \-v | \-\-verbose \ [ \-v | \-\-verbose ]
 251 Produce additional output.
 252 .TP
 253 .B \-\-verifyudev
 254 If udev synchronisation is enabled, verify that udev operations get performed
 255 correctly and try to fix up the device nodes afterwards if not.
 256 .TP
 257 .B \-\-version
 258 Display the library and kernel driver version.
 259 .br
 260 .SH COMMANDS
 261 .TP
 262 .B clear
 263 .I device_name
 264 .br
 265 Destroys the table in the inactive table slot for device_name.
 266 .br
 267 .TP
 268 .B create
 269 .I device_name
 270 .RB [ \-u
 271 .IR uuid ]
 272 .RB [ \-\-notable | \-\-table
 273 .RI < \fItable >| table_file ]
 274 .RB [{ \-\-addnodeoncreate | \-\-addnodeonresume }]
 275 .RB [ \-\-readahead
 276 .RI [ + ]< sectors >| auto | none ]
 277 .br
 278 Creates a device with the given name.
 279 If table_file or <table> is supplied, the table is loaded and made live.
 280 Otherwise a table is read from standard input unless \-\-notable is used.
 281 The optional uuid can be used in place of
 282 device_name in subsequent dmsetup commands.
 283 If successful a device will appear as
 284 /dev/mapper/<device-name>.
 285 See below for information on the table format.
 286 .br
 287 .TP
 288 .B deps
 289 .RB [ \-o
 290 .IR options ]
 291 .RI [ device_name ]
 292 .br
 293 Outputs a list of devices referenced by the live table for the specified
 294 device. Device names on output can be customised by following options:
 295 devno (major and minor pair, used by default), blkdevname (block device name),
 296 devname (map name for device-mapper devices, equal to blkdevname otherwise).
 297 .br
 298 .TP
 299 .B help
 300 .RB [ \-c | \-C | \-\-columns ]
 301 .br
 302 Outputs a summary of the commands available, optionally including
 303 the list of report fields.
 304 .br
 305 .TP
 306 .B info
 307 .RI [ device_name ]
 308 .br
 309 Outputs some brief information about the device in the form:
 310 .RS
 311 .RS
 312  State: SUSPENDED|ACTIVE, READ-ONLY
 313  Tables present: LIVE and/or INACTIVE
 314  Open reference count
 315  Last event sequence number (used by \fBwait\fP)
 316  Major and minor device number
 317  Number of targets in the live table
 318  UUID
 319 .RE
 320 .RE
 321 .br
 322 .TP
 323 .B info
 324 .BR \-c | \-C | \-\-columns
 325 .RB [ \-\-noheadings ]
 326 .RB [ \-\-separator
 327 .IR separator ]
 328 .RB [ \-o
 329 .IR fields ]
 330 .RB [ \-O | \-\-sort
 331 .IR sort_fields ]
 332 .RI [ device_name ]
 333 .br
 334 Output you can customise.
 335 Fields are comma-separated and chosen from the following list:
 336 name, major, minor, attr, open, segments, events, uuid.
 337 Attributes are: (L)ive, (I)nactive, (s)uspended, (r)ead-only, read-(w)rite.
 338 Precede the list with '+' to append
 339 to the default selection of columns instead of replacing it.
 340 Precede any sort_field with - for a reverse sort on that column.
 341 .br
 342 .TP
 343 .B ls
 344 .RB [ \-\-target
 345 .IR target_type ]
 346 .RB [ \-\-exec
 347 .IR command ]
 348 .RB [ \-\-tree ]
 349 .RB [ \-o
 350 .IR options ]
 351 .br
 352 List device names.  Optionally only list devices that have at least
 353 one target of the specified type.  Optionally execute a command for
 354 each device.  The device name is appended to the supplied command.
 355 Device names on output can be customised by following options: devno (major
 356 and minor pair, used by default), blkdevname (block device name),
 357 devname (map name for device-mapper devices, equal to blkdevname otherwise).
 358 --tree displays dependencies between devices as a tree.
 359 It accepts a comma-separate list of options.
 360 Some specify the information displayed against each node:
 361 device/nodevice; blkdevname; active, open, rw, uuid.
 362 Others specify how the tree is displayed:
 363 ascii, utf, vt100; compact, inverted, notrunc.
 364 .br
 365 .HP
 366 .BR load | reload
 367 .I device_name
 368 .RB [ \-\-table
 369 .RI < table >| table_file ]
 370 .br
 371 Loads <table> or table_file into the inactive table slot for device_name.
 372 If neither is supplied, reads a table from standard input.
 373 .br
 374 .HP
 375 .B wipe_table
 376 .I device_name
 377 .br
 378 Wait for any I/O in-flight through the device to complete, then
 379 replace the table with a new table that fails any new I/O
 380 sent to the device.  If successful, this should release any devices
 381 held open by the device's table(s).
 382 .br
 383 .HP
 384 .B message
 385 .I device_name sector message
 386 .br
 387 Send message to target. If sector not needed use 0.
 388 .br
 389 .HP
 390 .B mknodes
 391 .RI [ device_name ]
 392 .br
 393 Ensure that the node in /dev/mapper for device_name is correct.
 394 If no device_name is supplied, ensure that all nodes in /dev/mapper
 395 correspond to mapped devices currently loaded by the device-mapper kernel
 396 driver, adding, changing or removing nodes as necessary.
 397 .br
 398 .HP
 399 .B mangle
 400 .RI [ device_name ]
 401 .br
 402 Ensure existing device-mapper device name is in the correct mangled
 403 form containing only whitelisted characters (supported by udev) and do
 404 a rename if necessary. Any character not on the whitelist will be mangled
 405 based on the --manglename settting.
 406 .br
 407 .HP
 408 .B remove
 409 .RB [ \-f | \-\-force ]
 410 .RB [ \-\-retry ]
 411 .I device_name
 412 .br
 413 Removes a device.  It will no longer be visible to dmsetup.
 414 Open devices cannot be removed except with older kernels
 415 that contain a version of device-mapper prior to 4.8.0.
 416 In this case the device will be deleted when its open_count
 417 drops to zero.  From version 4.8.0 onwards, if a device can't
 418 be removed because an uninterruptible process is waiting for
 419 I/O to return from it, adding \-\-force will replace the table
 420 with one that fails all I/O, which might allow the
 421 process to be killed. If an attempt to remove a device fails,
 422 perhaps because a process run from a quick udev rule
 423 temporarily opened the device, the \-\-retry option will cause
 424 the operation to be retried for a few seconds before failing.
 425 .br
 426 .HP
 427 .B remove_all
 428 .RB [ \-f | \-\-force ]
 429 .br
 430 Attempts to remove all device definitions i.e. reset the driver.
 431 Use with care!  From version 4.8.0 onwards, if devices can't
 432 be removed because uninterruptible processes are waiting for
 433 I/O to return from them, adding \-\-force will replace the table
 434 with one that fails all I/O, which might allow the
 435 process to be killed.  This also runs \fBmknodes\fP afterwards.
 436 .br
 437 .HP
 438 .B rename
 439 .I device_name new_name
 440 .br
 441 Renames a device.
 442 .br
 443 .HP
 444 .B rename
 445 .I device_name
 446 .B \-\-setuuid
 447 .I uuid
 448 .br
 449 Sets the uuid of a device that was created without a uuid.
 450 After a uuid has been set it cannot be changed.
 451 .br
 452 .TP
 453 .B resume
 454 .I device_name
 455 .RB [{ \-\-addnodeoncreate | \-\-addnodeonresume }]
 456 .RB [ \-\-readahead
 457 .RI [ + ]< sectors >| auto | none ]
 458 .br
 459 Un-suspends a device.
 460 If an inactive table has been loaded, it becomes live.
 461 Postponed I/O then gets re-queued for processing.
 462 .br
 463 .TP
 464 .B setgeometry \fIdevice_name cyl head sect start
 465 .br
 466 Sets the device geometry to C/H/S.
 467 .br
 468 .HP
 469 .B splitname
 470 .I device_name
 471 .RI [ subsystem ]
 472 .br
 473 Splits given device name into subsystem constituents.
 474 Default subsystem is LVM.
 475 .br
 476 .TP
 477 .B status
 478 .RB [ \-\-target
 479 .IR target_type ]
 480 .RI [ device_name ]
 481 .br
 482 Outputs status information for each of the device's targets.
 483 With \-\-target, only information relating to the specified target type
 484 is displayed.
 485 .br
 486 .HP
 487 .B suspend
 488 .RB [ \-\-nolockfs ]
 489 .RB [ \-\-noflush ]
 490 .I device_name
 491 .br
 492 Suspends a device.  Any I/O that has already been mapped by the device
 493 but has not yet completed will be flushed.  Any further I/O to that
 494 device will be postponed for as long as the device is suspended.
 495 If there's a filesystem on the device which supports the operation,
 496 an attempt will be made to sync it first unless \-\-nolockfs is specified.
 497 Some targets such as recent (October 2006) versions of multipath may support
 498 the \-\-noflush option.  This lets outstanding I/O that has not yet reached the
 499 device to remain unflushed.
 500 .br
 501 .TP
 502 .B table
 503 .RB [ \-\-target
 504 .IR target_type ]
 505 .RB [ \-\-showkeys ]
 506 .RI [ device_name ]
 507 .br
 508 Outputs the current table for the device in a format that can be fed
 509 back in using the create or load commands.
 510 With \-\-target, only information relating to the specified target type
 511 is displayed.
 512 Encryption keys are suppressed in the table output for the crypt
 513 target unless the \-\-showkeys parameter is supplied.
 514 .br
 515 .TP
 516 .B targets
 517 .br
 518 Displays the names and versions of the currently-loaded targets.
 519 .br
 520 .HP
 521 .B udevcomplete
 522 .I cookie
 523 .br
 524 Wake any processes that are waiting for udev to complete processing the specified cookie.
 525 .br
 526 .HP
 527 .B udevcomplete_all
 528 .RI [ age_in_minutes ]
 529 .br
 530 Remove all cookies older than the specified number of minutes.
 531 Any process waiting on a cookie will be resumed immediately.
 532 .br
 533 .HP
 534 .B udevcookies
 535 .br
 536 List all existing cookies. Cookies are system-wide semaphores with keys
 537 prefixed by two predefined bytes (0x0D4D).
 538 .br
 539 .TP
 540 .B udevcreatecookie
 541 .br
 542 Creates a new cookie to synchronize actions with udev processing.
 543 The output is a cookie value. Normally we don't need to create cookies since
 544 dmsetup creates and destroys them for each action automatically. However, we can
 545 generate one explicitly to group several actions together and use only one
 546 cookie instead. We can define a cookie to use for each relevant command by using
 547 \-\-udevcookie option. Alternatively, we can export this value into the environment
 548 of the dmsetup process as DM_UDEV_COOKIE variable and it will be used automatically
 549 with all subsequent commands until it is unset.
 550 Invoking this command will create system-wide semaphore that needs to be cleaned
 551 up explicitly by calling udevreleasecookie command.
 552 .br
 553 .HP
 554 .B udevflags
 555 .I cookie
 556 .br
 557 Parses given cookie value and extracts any udev control flags encoded.
 558 The output is in environment key format that is suitable for use in udev
 559 rules. If the flag has its symbolic name assigned then the output is
 560 DM_UDEV_FLAG_<flag_name>='1', DM_UDEV_FLAG<flag_position>='1' otherwise.
 561 Subsystem udev flags don't have symbolic names assigned and these ones are
 562 always reported as DM_SUBSYSTEM_UDEV_FLAG<flag_position>='1'. There are
 563 16 udev flags altogether.
 564 .br
 565 .HP
 566 .B udevreleasecookie
 567 .RI [ cookie ]
 568 .br
 569 Waits for all pending udev processing bound to given cookie value and clean up
 570 the cookie with underlying semaphore. If the cookie is not given directly,
 571 the command will try to use a value defined by DM_UDEV_COOKIE environment variable.
 572 .br
 573 .TP
 574 .B version
 575 .br
 576 Outputs version information.
 577
 578 .TP
 579 .B wait
 580 .I device_name
 581 .RI [ event_nr ]
 582 .br
 583 Sleeps until the event counter for device_name exceeds event_nr.
 584 Use \-v to see the event number returned.
 585 To wait until the next event is triggered, use \fBinfo\fP to find
 586 the last event number.
 587 .SH TABLE FORMAT
 588 Each line of the table specifies a single target and is of the form:
 589 .P
 590 .I logical_start_sector num_sectors
 591 .B target_type
 592 .RI < target_args >
 593 .P
 594 Simple target types and <target_args> include:
 595 .HP
 596 .B linear
 597 .I destination_device start_sector
 598 .br
 599 The traditional linear mapping.
 600 .HP
 601 .B striped
 602 .I num_stripes chunk_size
 603 .RI [ destination
 604 .IR start_sector ]+
 605 .br
 606 Creates a striped area.
 607 .br
 608 e.g. striped 2 32 /dev/hda1 0 /dev/hdb1 0
 609 will map the first chunk (16k) as follows:
 610 .RS
 611 .RS
 612  LV chunk 1 -> hda1, chunk 1
 613  LV chunk 2 -> hdb1, chunk 1
 614  LV chunk 3 -> hda1, chunk 2
 615  LV chunk 4 -> hdb1, chunk 2
 616  etc.
 617 .RE
 618 .RE
 619 .TP
 620 .B error
 621 .br
 622 Errors any I/O that goes to this area.  Useful for testing or
 623 for creating devices with holes in them.
 624 .TP
 625 .B zero
 626 .br
 627 Returns blocks of zeroes on reads.  Any data written is discarded silently.
 628 This is a block-device equivalent of the /dev/zero character-device data sink
 629 described in \fBnull(4)\fP.
 630 .P
 631 More complex targets include:
 632 .TP
 633 .B crypt
 634 .br
 635 Transparent encryption of block devices using the kernel crypto API.
 636 .TP
 637 .B delay
 638 .br
 639 Delays reads and/or writes to different devices.  Useful for testing.
 640 .TP
 641 .B flakey
 642 .br
 643 Creates a similar mapping to the linear target but
 644 exhibits unreliable behaviour periodically.
 645 Useful for simulating failing devices when testing.
 646 .TP
 647 .B mirror
 648 .br
 649 Mirrors data across two or more devices.
 650 .HP
 651 .B multipath
 652 .br
 653 Mediates access through multiple paths to the same device.
 654 .TP
 655 .BR raid
 656 .br
 657 Offers an interface to the kernel's software raid driver, md.
 658 .HP
 659 .B snapshot
 660 .br
 661 Supports snapshots of devices.
 662 .P
 663 To find out more about the various targets and their table formats and status
 664 lines, please read the files in the Documentation/device-mapper directory in
 665 the kernel source tree.
 666 (Your distribution might include a copy of this information in the
 667 documentation directory for the device-mapper package.)
 668
 669 .SH EXAMPLES
 670
 671 # A table to join two disks together
 672 .br
 673 .br
 674 0 1028160 linear /dev/hda 0
 675 .br
 676 1028160 3903762 linear /dev/hdb 0
 677
 678
 679 # A table to stripe across the two disks,
 680 .br
 681 # and add the spare space from
 682 .br
 683 # hdb to the back of the volume
 684
 685 0 2056320 striped 2 32 /dev/hda 0 /dev/hdb 0
 686 .br
 687 2056320 2875602 linear /dev/hdb 1028160
 688
 689 .SH ENVIRONMENT VARIABLES
 690 .TP
 691 .B DM_DEV_DIR
 692 The device directory name.
 693 Defaults to "/dev" and must be an absolute path.
 694 .TP
 695 .B DM_UDEV_COOKIE
 696 A cookie to use for all relevant commands to synchronize with udev processing.
 697 It is an alternative to using \-\-udevcookie option.
 698
 699 .SH AUTHORS
 700 Original version: Joe Thornber (thornber@sistina.com)
 701
 702 .SH SEE ALSO
 703 Device-mapper resource page: http://sources.redhat.com/dm/