contrib/lvm2/dist/man/dmsetup.8

   1 .\"    $NetBSD: dmsetup.8,v 1.2 2009/02/18 12:16:13 haad Exp $
   2 .\"
   3 .TH DMSETUP 8 "Apr 06 2006" "Linux" "MAINTENANCE COMMANDS"
   4 .SH NAME
   5 dmsetup \- low level logical volume management
   6 .SH SYNOPSIS
   7 .ad l
   8 .B dmsetup help
   9 .I [-c|-C|--columns]
  10 .br
  11 .B dmsetup create
  12 .I device_name [-u uuid] [--notable | --table <table> | table_file]
  13 .br
  14 .B dmsetup remove
  15 .I [-f|--force] device_name
  16 .br
  17 .B dmsetup remove_all
  18 .I [-f|--force]
  19 .br
  20 .B dmsetup suspend
  21 .I [--nolockfs] [--noflush] device_name
  22 .br
  23 .B dmsetup resume
  24 .I device_name
  25 .br
  26 .B dmsetup load
  27 .I device_name [--table <table> | table_file]
  28 .br
  29 .B dmsetup clear
  30 .I device_name
  31 .br
  32 .B dmsetup reload
  33 .I device_name [--table <table> | table_file]
  34 .br
  35 .B dmsetup rename
  36 .I device_name new_name
  37 .br
  38 .B dmsetup message
  39 .I device_name sector message
  40 .br
  41 .B dmsetup ls
  42 .I [--target target_type] [--exec command] [--tree [-o options]]
  43 .br
  44 .B dmsetup info
  45 .I [device_name]
  46 .br
  47 .B dmsetup info -c|-C|--columns
  48 .I [--noheadings] [--separator separator] [-o fields] [-O|--sort sort_fields]
  49 .I [device_name]
  50 .br
  51 .B dmsetup deps
  52 .I [device_name]
  53 .br
  54 .B dmsetup status
  55 .I [--target target_type]
  56 .I [device_name]
  57 .br
  58 .B dmsetup table
  59 .I [--target target_type]
  60 .I [device_name]
  61 .br
  62 .B dmsetup wait
  63 .I device_name
  64 .I [event_nr]
  65 .br
  66 .B dmsetup mknodes
  67 .I [device_name]
  68 .br
  69 .B dmsetup targets
  70 .br
  71 .B dmsetup version
  72 .br
  73 .B dmsetup setgeometry
  74 .I device_name cyl head sect start
  75 .br
  76
  77 .B devmap_name
  78 .I major minor
  79 .br
  80 .B devmap_name
  81 .I major:minor
  82 .ad b
  83 .SH DESCRIPTION
  84 dmsetup manages logical devices that use the device-mapper driver.
  85 Devices are created by loading a table that specifies a target for
  86 each sector (512 bytes) in the logical device.
  87
  88 The first argument to dmsetup is a command.
  89 The second argument is the logical device name or uuid.
  90
  91 Invoking the command as \fBdevmap_name\fP is equivalent to
  92 .br
  93 \fBdmsetup info -c --noheadings -j \fImajor\fB -m \fIminor\fP.
  94 .SH OPTIONS
  95 .IP \fB-c|-C|--columns
  96 .br
  97 Display output in columns rather than as Field: Value lines.
  98 .IP \fB-j|--major\ \fImajor
  99 .br
 100 Specify the major number.
 101 .IP \fB-m|--minor\ \fIminor
 102 .br
 103 Specify the minor number.
 104 .IP \fB-n|--noheadings
 105 .br
 106 Suppress the headings line when using columnar output.
 107 .IP \fB--noopencount
 108 .br
 109 Tell the kernel not to supply the open reference count for the device.
 110 .IP \fB--notable
 111 .br
 112 When creating a device, don't load any table.
 113 .IP \fB-o|--options
 114 .br
 115 Specify which fields to display.
 116 .IP \fB-r|--readonly
 117 .br
 118 Set the table being loaded read-only.
 119 .IP \fB--readahead\ [+]<sectors>|auto|none
 120 .br
 121 Specify read ahead size in units of sectors.
 122 The default value is "auto" which allows the kernel to choose
 123 a suitable value automatically.  The + prefix lets you
 124 specify a minimum value which will not be used if it is
 125 smaller than the value chosen by the kernel.
 126 "None" is equivalent to specifying zero.
 127 .IP \fB--table\ <table>
 128 .br
 129 Specify a one-line table directly on the command line.
 130 .IP \fB-u|--uuid
 131 .br
 132 Specify the uuid.
 133 .IP \fB-v|--verbose\ [-v|--verbose]
 134 .br
 135 Produce additional output.
 136 .IP \fB--version
 137 .br
 138 Display the library and kernel driver version.
 139 .SH COMMANDS
 140 .IP \fBcreate
 141 .I device_name [-u uuid] [--notable | --table <table> | table_file]
 142 .br
 143 Creates a device with the given name.
 144 If table_file or <table> is supplied, the table is loaded and made live.
 145 Otherwise a table is read from standard input unless --notable is used.
 146 The optional uuid can be used in place of
 147 device_name in subsequent dmsetup commands.
 148 If successful a device will appear as
 149 /dev/device-mapper/<device-name>.
 150 See below for information on the table format.
 151 .IP \fBdeps
 152 .I [device_name]
 153 .br
 154 Outputs a list of (major, minor) pairs for devices referenced by the
 155 live table for the specified device.
 156 .IP \fBhelp
 157 .I [-c|-C|--columns]
 158 .br
 159 Outputs a summary of the commands available, optionally including
 160 the list of report fields.
 161 .IP \fBinfo
 162 .I [device_name]
 163 .br
 164 Outputs some brief information about the device in the form:
 165 .br
 166     State: SUSPENDED|ACTIVE, READ-ONLY
 167 .br
 168     Tables present: LIVE and/or INACTIVE
 169 .br
 170     Open reference count
 171 .br
 172     Last event sequence number (used by \fBwait\fP)
 173 .br
 174     Major and minor device number
 175 .br
 176     Number of targets in the live table
 177 .br
 178     UUID
 179 .IP \fBinfo -c|-C|--columns
 180 .I [--noheadings] [--separator separator] [-o fields] [-O|--sort sort_fields]
 181 .I [device_name]
 182 .br
 183 Output you can customise.
 184 Fields are comma-separated and chosen from the following list:
 185 name, major, minor, attr, open, segments, events, uuid.
 186 Attributes are: (L)ive, (I)nactive, (s)uspended, (r)ead-only, read-(w)rite.
 187 Precede the list with '+' to append
 188 to the default selection of columns instead of replacing it.
 189 Precede any sort_field with - for a reverse sort on that column.
 190 .IP \fBls
 191 .I [--target target_type]
 192 .I [--exec command]
 193 .I [--tree [-o options]]
 194 .br
 195 List device names.  Optionally only list devices that have at least
 196 one target of the specified type.  Optionally execute a command for
 197 each device.  The device name is appended to the supplied command.
 198 --tree displays dependencies between devices as a tree.
 199 It accepts a comma-separate list of options.
 200 Some specify the information displayed against each node:
 201 device/nodevice; active, open, rw, uuid.
 202 Others specify how the tree is displayed:
 203 ascii, utf, vt100; compact, inverted, notrunc.
 204 .IP \fBload|reload
 205 .I device_name [--table <table> | table_file]
 206 .br
 207 Loads <table> or table_file into the inactive table slot for device_name.
 208 If neither is supplied, reads a table from standard input.
 209 .IP \fBmessage
 210 .I device_name sector message
 211 .br
 212 Send message to target. If sector not needed use 0.
 213 .IP \fBmknodes
 214 .I [device_name]
 215 .br
 216 Ensure that the node in /dev/mapper for device_name is correct.
 217 If no device_name is supplied, ensure that all nodes in /dev/mapper
 218 correspond to mapped devices currently loaded by the device-mapper kernel
 219 driver, adding, changing or removing nodes as necessary.
 220 .IP \fBremove
 221 .I [-f|--force] device_name
 222 .br
 223 Removes a device.  It will no longer be visible to dmsetup.
 224 Open devices cannot be removed except with older kernels
 225 that contain a version of device-mapper prior to 4.8.0.
 226 In this case the device will be deleted when its open_count
 227 drops to zero.  From version 4.8.0 onwards, if a device can't
 228 be removed because an uninterruptible process is waiting for
 229 I/O to return from it, adding --force will replace the table
 230 with one that fails all I/O, which might allow the
 231 process to be killed.
 232 .IP \fBremove_all
 233 .I [-f|--force]
 234 .br
 235 Attempts to remove all device definitions i.e. reset the driver.
 236 Use with care!  From version 4.8.0 onwards, if devices can't
 237 be removed because uninterruptible processess are waiting for
 238 I/O to return from them, adding --force will replace the table
 239 with one that fails all I/O, which might allow the
 240 process to be killed.  This also runs \fBmknodes\fP afterwards.
 241 .IP \fBrename
 242 .I device_name new_name
 243 .br
 244 Renames a device.
 245 .IP \fBresume
 246 .I device_name
 247 .br
 248 Un-suspends a device.
 249 If an inactive table has been loaded, it becomes live.
 250 Postponed I/O then gets re-queued for processing.
 251 .IP \fBsetgeometry
 252 .I device_name cyl head sect start
 253 .br
 254 Sets the device geometry to C/H/S.
 255 .IP \fBstatus
 256 .I [--target target_type]
 257 .I [device_name]
 258 .br
 259 Outputs status information for each of the device's targets.
 260 With --target, only information relating to the specified target type
 261 is displayed.
 262 .IP \fBsuspend
 263 .I [--nolockfs] [--noflush]
 264 .I device_name
 265 .br
 266 Suspends a device.  Any I/O that has already been mapped by the device
 267 but has not yet completed will be flushed.  Any further I/O to that
 268 device will be postponed for as long as the device is suspended.
 269 If there's a filesystem on the device which supports the operation,
 270 an attempt will be made to sync it first unless --nolockfs is specified.
 271 Some targets such as recent (October 2006) versions of multipath may support
 272 the --noflush option.  This lets outstanding I/O that has not yet reached the
 273 device to remain unflushed.
 274 .IP \fBtable
 275 .I [--target target_type]
 276 .I [device_name]
 277 .br
 278 Outputs the current table for the device in a format that can be fed
 279 back in using the create or load commands.
 280 With --target, only information relating to the specified target type
 281 is displayed.
 282 .IP \fBtargets
 283 .br
 284 Displays the names and versions of the currently-loaded targets.
 285 .IP \fBversion
 286 .br
 287 Outputs version information.
 288 .IP \fBwait
 289 .I device_name
 290 .I [event_nr]
 291 .br
 292 Sleeps until the event counter for device_name exceeds event_nr.
 293 Use -v to see the event number returned.
 294 To wait until the next event is triggered, use \fBinfo\fP to find
 295 the last event number.
 296 .SH TABLE FORMAT
 297 Each line of the table specifies a single target and is of the form:
 298 .br
 299     logical_start_sector num_sectors target_type target_args
 300 .br
 301 .br
 302
 303 There are currently three simple target types available together
 304 with more complex optional ones that implement snapshots and mirrors.
 305
 306 .IP \fBlinear
 307 .I destination_device start_sector
 308 .br
 309 The traditional linear mapping.
 310
 311 .IP \fBstriped
 312 .I num_stripes chunk_size [destination start_sector]+
 313 .br
 314 Creates a striped area.
 315 .br
 316 e.g. striped 2 32 /dev/hda1 0 /dev/hdb1 0
 317 will map the first chunk (16k) as follows:
 318 .br
 319     LV chunk 1 -> hda1, chunk 1
 320 .br
 321     LV chunk 2 -> hdb1, chunk 1
 322 .br
 323     LV chunk 3 -> hda1, chunk 2
 324 .br
 325     LV chunk 4 -> hdb1, chunk 2
 326 .br
 327     etc.
 328
 329 .IP \fBerror
 330 .br
 331 Errors any I/O that goes to this area.  Useful for testing or
 332 for creating devices with holes in them.
 333
 334 .SH EXAMPLES
 335
 336 # A table to join two disks together
 337 .br
 338 .br
 339 0 1028160 linear /dev/hda 0
 340 .br
 341 1028160 3903762 linear /dev/hdb 0
 342
 343
 344 # A table to stripe across the two disks,
 345 .br
 346 # and add the spare space from
 347 .br
 348 # hdb to the back of the volume
 349
 350 0 2056320 striped 2 32 /dev/hda 0 /dev/hdb 0
 351 .br
 352 2056320 2875602 linear /dev/hdb 1028160
 353
 354 .SH ENVIRONMENT VARIABLES
 355 .TP
 356 \fBDM_DEV_DIR\fP
 357 The device directory name.
 358 Defaults to "/dev" and must be an absolute path.
 359
 360 .SH AUTHORS
 361 Original version: Joe Thornber (thornber@sistina.com)
 362
 363 .SH SEE ALSO
 364 Device-mapper resource page: http://sources.redhat.com/dm/