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 help
   7 .I [-c|-C|--columns]
   8 .br
   9 .B dmsetup create
  10 .I device_name [-u uuid] [--notable | --table <table> | table_file]
  11 .br
  12 .B dmsetup remove
  13 .I [-f|--force] device_name
  14 .br
  15 .B dmsetup remove_all
  16 .I [-f|--force]
  17 .br
  18 .B dmsetup suspend
  19 .I [--nolockfs] [--noflush] device_name
  20 .br
  21 .B dmsetup resume
  22 .I device_name
  23 .br
  24 .B dmsetup load
  25 .I device_name [--table <table> | table_file]
  26 .br
  27 .B dmsetup clear
  28 .I device_name
  29 .br
  30 .B dmsetup reload
  31 .I device_name [--table <table> | table_file]
  32 .br
  33 .B dmsetup rename
  34 .I device_name new_name
  35 .br
  36 .B dmsetup rename
  37 .I device_name --setuuid uuid
  38 .br
  39 .B dmsetup message
  40 .I device_name sector message
  41 .br
  42 .B dmsetup ls
  43 .I [--target target_type] [--exec command] [--tree [-o options]]
  44 .br
  45 .B dmsetup info
  46 .I [device_name]
  47 .br
  48 .B dmsetup info -c|-C|--columns
  49 .I [--noheadings] [--separator separator] [-o fields] [-O|--sort sort_fields]
  50 .I [device_name]
  51 .br
  52 .B dmsetup deps
  53 .I [device_name]
  54 .br
  55 .B dmsetup status
  56 .I [--target target_type]
  57 .I [device_name]
  58 .br
  59 .B dmsetup table
  60 .I [--target target_type] [--showkeys]
  61 .I [device_name]
  62 .br
  63 .B dmsetup wait
  64 .I device_name
  65 .I [event_nr]
  66 .br
  67 .B dmsetup mknodes
  68 .I [device_name]
  69 .br
  70 .B dmsetup udevcreatecookie
  71 .br
  72 .B dmsetup udevreleasecookie
  73 .I [cookie]
  74 .br
  75 .B dmsetup udevflags
  76 .I cookie
  77 .br
  78 .B dmsetup udevcomplete
  79 .I cookie
  80 .br
  81 .B dmsetup udevcomplete_all
  82 .br
  83 .B dmsetup udevcookies
  84 .br
  85 .B dmsetup targets
  86 .br
  87 .B dmsetup version
  88 .br
  89 .B dmsetup setgeometry
  90 .I device_name cyl head sect start
  91 .br
  92 .B dmsetup splitname
  93 .I device_name
  94 .I [subsystem]
  95 .br
  96
  97 .B devmap_name
  98 .I major minor
  99 .br
 100 .B devmap_name
 101 .I major:minor
 102 .ad b
 103 .SH DESCRIPTION
 104 dmsetup manages logical devices that use the device-mapper driver.
 105 Devices are created by loading a table that specifies a target for
 106 each sector (512 bytes) in the logical device.
 107
 108 The first argument to dmsetup is a command.
 109 The second argument is the logical device name or uuid.
 110
 111 Invoking the command as \fBdevmap_name\fP is equivalent to
 112 .br
 113 \fBdmsetup info -c --noheadings -j \fImajor\fB -m \fIminor\fP.
 114 .SH OPTIONS
 115 .IP \fB-c|-C|--columns
 116 .br
 117 Display output in columns rather than as Field: Value lines.
 118 .IP \fB-h|--help
 119 .br
 120 Outputs a summary of the commands available, optionally including
 121 the list of report fields (synonym with \fBhelp\fP command).
 122 .IP \fB--inactive
 123 .br
 124 When returning any table information from the kernel report on the
 125 inactive table instead of the live table.
 126 Requires kernel driver version 4.16.0 or above.
 127 .IP \fB-j|--major\ \fImajor
 128 .br
 129 Specify the major number.
 130 .IP \fB-m|--minor\ \fIminor
 131 .br
 132 Specify the minor number.
 133 .IP \fB-n|--noheadings
 134 .br
 135 Suppress the headings line when using columnar output.
 136 .IP \fB--noopencount
 137 .br
 138 Tell the kernel not to supply the open reference count for the device.
 139 .IP \fB--notable
 140 .br
 141 When creating a device, don't load any table.
 142 .IP \fB--udevcookie\ \fIcookie
 143 .br
 144 Use cookie for udev synchronisation.
 145 .IP \fB--noudevrules
 146 Do not allow udev to manage nodes for devices in device-mapper directory.
 147 .br
 148 .IP \fB--noudevsync
 149 Do not synchronise with udev when creating, renaming or removing devices.
 150 .br
 151 .IP \fB-o|--options
 152 .br
 153 Specify which fields to display.
 154 .IP \fB-r|--readonly
 155 .br
 156 Set the table being loaded read-only.
 157 .IP \fB--readahead\ [+]<sectors>|auto|none
 158 .br
 159 Specify read ahead size in units of sectors.
 160 The default value is "auto" which allows the kernel to choose
 161 a suitable value automatically.  The + prefix lets you
 162 specify a minimum value which will not be used if it is
 163 smaller than the value chosen by the kernel.
 164 "None" is equivalent to specifying zero.
 165 .IP \fB--table\ <table>
 166 .br
 167 Specify a one-line table directly on the command line.
 168 .IP \fB-u|--uuid
 169 .br
 170 Specify the uuid.
 171 .IP \fB-y|--yes
 172 .br
 173 Answer yes to all prompts automatically.
 174 .IP \fB-v|--verbose\ [-v|--verbose]
 175 .br
 176 Produce additional output.
 177 .IP \fB--version
 178 .br
 179 Display the library and kernel driver version.
 180 .SH COMMANDS
 181 .IP \fBclear
 182 .I device_name
 183 .br
 184 Destroys the table in the inactive table slot for device_name.
 185 .IP \fBcreate
 186 .I device_name [-u uuid] [--notable | --table <table> | table_file]
 187 .br
 188 Creates a device with the given name.
 189 If table_file or <table> is supplied, the table is loaded and made live.
 190 Otherwise a table is read from standard input unless --notable is used.
 191 The optional uuid can be used in place of
 192 device_name in subsequent dmsetup commands.
 193 If successful a device will appear as
 194 /dev/device-mapper/<device-name>.
 195 See below for information on the table format.
 196 .IP \fBdeps
 197 .I [device_name]
 198 .br
 199 Outputs a list of (major, minor) pairs for devices referenced by the
 200 live table for the specified device.
 201 .IP \fBhelp
 202 .I [-c|-C|--columns]
 203 .br
 204 Outputs a summary of the commands available, optionally including
 205 the list of report fields.
 206 .IP \fBinfo
 207 .I [device_name]
 208 .br
 209 Outputs some brief information about the device in the form:
 210 .br
 211     State: SUSPENDED|ACTIVE, READ-ONLY
 212 .br
 213     Tables present: LIVE and/or INACTIVE
 214 .br
 215     Open reference count
 216 .br
 217     Last event sequence number (used by \fBwait\fP)
 218 .br
 219     Major and minor device number
 220 .br
 221     Number of targets in the live table
 222 .br
 223     UUID
 224 .IP \fBinfo
 225 .I -c|-C|--columns
 226 .I [--noheadings] [--separator separator] [-o fields] [-O|--sort sort_fields]
 227 .I [device_name]
 228 .br
 229 Output you can customise.
 230 Fields are comma-separated and chosen from the following list:
 231 name, major, minor, attr, open, segments, events, uuid.
 232 Attributes are: (L)ive, (I)nactive, (s)uspended, (r)ead-only, read-(w)rite.
 233 Precede the list with '+' to append
 234 to the default selection of columns instead of replacing it.
 235 Precede any sort_field with - for a reverse sort on that column.
 236 .IP \fBls
 237 .I [--target target_type]
 238 .I [--exec command]
 239 .I [--tree [-o options]]
 240 .br
 241 List device names.  Optionally only list devices that have at least
 242 one target of the specified type.  Optionally execute a command for
 243 each device.  The device name is appended to the supplied command.
 244 --tree displays dependencies between devices as a tree.
 245 It accepts a comma-separate list of options.
 246 Some specify the information displayed against each node:
 247 device/nodevice; active, open, rw, uuid.
 248 Others specify how the tree is displayed:
 249 ascii, utf, vt100; compact, inverted, notrunc.
 250 .IP \fBload|reload
 251 .I device_name [--table <table> | table_file]
 252 .br
 253 Loads <table> or table_file into the inactive table slot for device_name.
 254 If neither is supplied, reads a table from standard input.
 255 .IP \fBmessage
 256 .I device_name sector message
 257 .br
 258 Send message to target. If sector not needed use 0.
 259 .IP \fBmknodes
 260 .I [device_name]
 261 .br
 262 Ensure that the node in /dev/mapper for device_name is correct.
 263 If no device_name is supplied, ensure that all nodes in /dev/mapper
 264 correspond to mapped devices currently loaded by the device-mapper kernel
 265 driver, adding, changing or removing nodes as necessary.
 266 .IP \fBremove
 267 .I [-f|--force] device_name
 268 .br
 269 Removes a device.  It will no longer be visible to dmsetup.
 270 Open devices cannot be removed except with older kernels
 271 that contain a version of device-mapper prior to 4.8.0.
 272 In this case the device will be deleted when its open_count
 273 drops to zero.  From version 4.8.0 onwards, if a device can't
 274 be removed because an uninterruptible process is waiting for
 275 I/O to return from it, adding --force will replace the table
 276 with one that fails all I/O, which might allow the
 277 process to be killed.
 278 .IP \fBremove_all
 279 .I [-f|--force]
 280 .br
 281 Attempts to remove all device definitions i.e. reset the driver.
 282 Use with care!  From version 4.8.0 onwards, if devices can't
 283 be removed because uninterruptible processes are waiting for
 284 I/O to return from them, adding --force will replace the table
 285 with one that fails all I/O, which might allow the
 286 process to be killed.  This also runs \fBmknodes\fP afterwards.
 287 .IP \fBrename
 288 .I device_name new_name
 289 .br
 290 Renames a device.
 291 .IP \fBrename
 292 .I device_name --setuuid uuid
 293 .br
 294 Sets the uuid of a device that was created without a uuid.
 295 After a uuid has been set it cannot be changed.
 296 .IP \fBresume
 297 .I device_name
 298 .br
 299 Un-suspends a device.
 300 If an inactive table has been loaded, it becomes live.
 301 Postponed I/O then gets re-queued for processing.
 302 .IP \fBsetgeometry
 303 .I device_name cyl head sect start
 304 .br
 305 Sets the device geometry to C/H/S.
 306 .IP \fBsplitname
 307 .I device_name
 308 .I [subsystem]
 309 .br
 310 Splits given device name into subsystem constituents.
 311 Default subsystem is LVM.
 312 .IP \fBstatus
 313 .I [--target target_type]
 314 .I [device_name]
 315 .br
 316 Outputs status information for each of the device's targets.
 317 With --target, only information relating to the specified target type
 318 is displayed.
 319 .IP \fBsuspend
 320 .I [--nolockfs] [--noflush]
 321 .I device_name
 322 .br
 323 Suspends a device.  Any I/O that has already been mapped by the device
 324 but has not yet completed will be flushed.  Any further I/O to that
 325 device will be postponed for as long as the device is suspended.
 326 If there's a filesystem on the device which supports the operation,
 327 an attempt will be made to sync it first unless --nolockfs is specified.
 328 Some targets such as recent (October 2006) versions of multipath may support
 329 the --noflush option.  This lets outstanding I/O that has not yet reached the
 330 device to remain unflushed.
 331 .IP \fBtable
 332 .I [--target target_type] [--showkeys]
 333 .I [device_name]
 334 .br
 335 Outputs the current table for the device in a format that can be fed
 336 back in using the create or load commands.
 337 With --target, only information relating to the specified target type
 338 is displayed.
 339 Encryption keys are suppressed in the table output for the crypt
 340 target unless the --showkeys parameter is supplied.
 341 .IP \fBtargets
 342 .br
 343 Displays the names and versions of the currently-loaded targets.
 344 .br
 345 .IP \fBudevcreatecookie
 346 .br
 347 Creates a new cookie to synchronize actions with udev processing.
 348 The output is a cookie value. Normally we don't need to create cookies since
 349 dmsetup creates and destroys them for each action automatically. However, we can
 350 generate one explicitly to group several actions together and use only one
 351 cookie instead. We can define a cookie to use for each relevant command by using
 352 --udevcookie option. Alternatively, we can export this value into the environment
 353 of the dmsetup process as DM_UDEV_COOKIE variable and it will be used automatically
 354 with all subsequent commands until it is unset.
 355 Invoking this command will create system-wide semaphore that needs to be cleaned
 356 up explicitly by calling udevreleasecookie command.
 357 .br
 358 .IP \fBudevreleasecookie
 359 .I [cookie]
 360 .br
 361 Waits for all pending udev processing bound to given cookie value and clean up
 362 the cookie with underlying semaphore. If the cookie is not given directly,
 363 the command will try to use a value defined by DM_UDEV_COOKIE environment variable.
 364 .br
 365 .IP \fBudevflags
 366 .I cookie
 367 .br
 368 Parses given cookie value and extracts any udev control flags encoded.
 369 The output is in environment key format that is suitable for use in udev
 370 rules. If the flag has its symbolic name assigned then the ouput is
 371 DM_UDEV_FLAG_<flag_name>='1', DM_UDEV_FLAG<flag_position>='1' otherwise.
 372 Subsystem udev flags don't have symbolic names assigned and these ones are
 373 always reported as DM_SUBSYSTEM_UDEV_FLAG<flag_position>='1'. There are
 374 16 udev flags altogether.
 375 .br
 376 .IP \fBudevcomplete
 377 .I cookie
 378 .br
 379 Wake any processes that are waiting for udev to complete processing the specified cookie.
 380 .br
 381 .IP \fBudevcomplete_all
 382 Remove all cookies. Any process waiting on a cookie will be resumed immediately.
 383 .br
 384 .IP \fBudevcookies
 385 List all existing cookies. Cookies are system-wide semaphores with keys
 386 prefixed by two predefined bytes (0x0D4D).
 387 .br
 388 .IP \fBversion
 389 .br
 390 Outputs version information.
 391 .IP \fBwait
 392 .I device_name
 393 .I [event_nr]
 394 .br
 395 Sleeps until the event counter for device_name exceeds event_nr.
 396 Use -v to see the event number returned.
 397 To wait until the next event is triggered, use \fBinfo\fP to find
 398 the last event number.
 399 .SH TABLE FORMAT
 400 Each line of the table specifies a single target and is of the form:
 401 .br
 402     logical_start_sector num_sectors target_type target_args
 403 .br
 404 .br
 405
 406 There are currently three simple target types available together
 407 with more complex optional ones that implement snapshots and mirrors.
 408
 409 .IP \fBlinear
 410 .I destination_device start_sector
 411 .br
 412 The traditional linear mapping.
 413
 414 .IP \fBstriped
 415 .I num_stripes chunk_size [destination start_sector]+
 416 .br
 417 Creates a striped area.
 418 .br
 419 e.g. striped 2 32 /dev/hda1 0 /dev/hdb1 0
 420 will map the first chunk (16k) as follows:
 421 .br
 422     LV chunk 1 -> hda1, chunk 1
 423 .br
 424     LV chunk 2 -> hdb1, chunk 1
 425 .br
 426     LV chunk 3 -> hda1, chunk 2
 427 .br
 428     LV chunk 4 -> hdb1, chunk 2
 429 .br
 430     etc.
 431
 432 .IP \fBerror
 433 .br
 434 Errors any I/O that goes to this area.  Useful for testing or
 435 for creating devices with holes in them.
 436
 437 .SH EXAMPLES
 438
 439 # A table to join two disks together
 440 .br
 441 .br
 442 0 1028160 linear /dev/hda 0
 443 .br
 444 1028160 3903762 linear /dev/hdb 0
 445
 446
 447 # A table to stripe across the two disks,
 448 .br
 449 # and add the spare space from
 450 .br
 451 # hdb to the back of the volume
 452
 453 0 2056320 striped 2 32 /dev/hda 0 /dev/hdb 0
 454 .br
 455 2056320 2875602 linear /dev/hdb 1028160
 456
 457 .SH ENVIRONMENT VARIABLES
 458 .TP
 459 \fBDM_DEV_DIR\fP
 460 The device directory name.
 461 Defaults to "/dev" and must be an absolute path.
 462 .TP
 463 \fBDM_UDEV_COOKIE\fP
 464 A cookie to use for all relevant commands to synchronize with udev processing.
 465 It is an alternative to using --udevcookie option.
 466
 467 .SH AUTHORS
 468 Original version: Joe Thornber (thornber@sistina.com)
 469
 470 .SH SEE ALSO
 471 Device-mapper resource page: http://sources.redhat.com/dm/