Device-mapper

Normally, users rarely use dmsetup directly. The dmsetup is a very low level, and difficult tool to use. LVM, mdtool or dmsetup is generally the preferred way to do it, as it takes care of saving the metadata and issuing the dmsetup commands for you. However, sometimes one want to deal with it directly: sometimes for recovery purposes, or because LVM doesn't yet support what you want.

Create
The create command activates a new device mapper device. It appears in /dev/mapper. In addition, if the target has metadata, it reads it, or if this its first use, it initializes the metadata devices. Note the prior device mapper devices can be passed as paramters (if the target takes a device), thus it is possible to "stack" them. The syntax is:

Remove
The remove command deactivates a device mapper device. It removes it from /dev/mapper. Syntax is Note is not possible to remove a device that's in use. The -f option may be passed the replace the target with one that fails all I/O, hopefully allowing the reference count to drop to 0.

Message
The message command send a message to the device. What message are supported depend on the target Syntax is: The tends not to be used and is almost always 0.

Suspend
The suspend' command stops any NEW I/O. Existing I/O will still be completed. This can be used to quiesce a device. Syntax is:

Resume
The resume command allows I/O to be submitted to a previously suspended device. Syntax is:

Zero
See Documentation/device-mapper/zero.txt. This target has no target-specific parameters.

The "zero" target create that functions similarly to /dev/zero: All reads return binary zero, and all writes are discarded> Normaly used in tests, but also useful in recovering linear and raid-type targets, when combined with the 'snapshot' target: a "zero" target of the same size as the missing piece(s) is created, a (writable) snapshot created (usually a loop device backed by a large sparse file, but it can be far smaller than the missing piece since it only has to the hold the changes). Then the snapshot can be mounted, fsck'd, or recover tools run against it.

This creates a 1GB (1953125-sector) zero target:

Linear
See Documentation/device-mapper/linear.txt for paramters in usage. This target is the basic building block for the device mapper - it is used to both join and split (and often both at once) block device. For a simple identify mapping:

The 4 disks can be joined to together as one:

Note the peculiar sync on the join. the --table argument only allows single-tables, so the table must be fed in from stdin. Also notice the  is not 0 in all cases, as each device were appending need to start where the previous ends. Its possible to split a disk, in this case into a 4 MiB (8192 sector) "small" and 1 GB "large" (1953125 sector) disks:

Note that in the second device, the offset is not 0, since it is desired to start 4 MiB (8192 sectors) in Both joining an splitting can be combined:

This creates a 4GB device using last 1GB of each disk.

Mirror
There is no kernel documentation for the mirror target. Parameters obtained from Linux sources: drivers/md/dm-log.c and drivers/md/dm-raid1.c mirror <#log args> ... <#devs> ...  <#features>

For there are 4 values with different arguments:
 * core  [[no]sync] [block_on_error]
 * disk  [[no]sync] [block_on_error]

And the values of each argument:
 *  is the region size of the mirror in sectors. It must be power of 2 and at least of a kernel page (for Intel x86/x64 processors, this is 4 KiB (8 sectors) This is the granularity in which the mirror is kept to update, it is done in blocks of . Its a tradeoff between increased metadata and wasted I/O. LVM uses a value of 512 KiB (1024 sectors).
 *   is the device in which to store the metadata, for the disk log types
 * [no]sync is an optional argument. Default is "'sync'". nosync skips the sync steps, but any results reads from are not written to since the mirror was established are undefined. This is appropriate to use then the initial device is empty.

And there is only 1 feature:
 * handle_errors causes the mirror to respond to an error. Default is to ignore all errors. LVM enables this feature.

To create a mirror with in-memory log:

Without a persistent log, the mirror will have to be recreated every time by copying the entire block device to the other "legs". To avoid this, the log may be stored on disk:

Its possible to do LVM "--mirrorlog mirror" by creating 2 mirrors: a core mirror for the log device, and a disk mirror the data devices:

RAID1
See Documentation/device-mapper/dm-raid.txt. Note that  is unused for RAID1, but a value is still required, therefore is value should be set to 0. There 2 other important, though optional, parameters:  and <[no]sync>.


 * <region_size> has the same meaning as it does in the mirror target. Unlike the mirror target. it has a default of 4 MiB (8192 sectors). LVM uses a region size of 512 KiB (1024 sectors).
 * <[no]sync> has the same meaning as it does in the mirror target

To create a simple 1 GB raid1 with no metadata devices.

Note that because there's no metadata device, the array must be re-mirrored each time it is created. So normally, a metadata device is desired. Each "leg" needs it own metadata device If /dev/loop2 and /dev/loop3 are small metadata devices (4 MiB), then to create a 1G RAID1 would be:

Striped (RAID 0) and RAID 4/5/6/10
See Documentation/device-mapper/striped.txt</tt> and Documentation/device-mapper/dm-raid.txt</tt> for the parameters of this target. Three in particular are important: Because the number of sectors (1953125) is not a multiple of 128, it must be rounded down to the nearest multiple of 128 sectors, which can be done using this formula: bc So in this case:
 * <chunk_size> is the size I/O (in sectors) before its "split" across the array It must be both a power a two and a least a large as a kernel memory page (for x86/x64 processors, pages are 4 KiB, so must be at least 8.) LVM uses a default value of 64 KiB (128 sectors). Using LVM defaults, a 1 MiB (2048 sector) write will be split in 16 chunks, distributed as evenly as possible across the array. The size of the array MUST be a multiple of this value. Otherwise the target will give the error "Array size does not match requested target length".
 *   has the same meaning and defaults as it does for the RAID1 target.
 * [no]sync has the same meaning as it does for the RAID1 target. It is usually not appropriate for RAID 4,5 and 6 as even for blank device parity must still be computed, unless creating a degraded array.

Striped (RAID0)
The striped target parameters is asymmetric to the RAID ones. First, the # devices comes first, not the cluster size. Second, one must specify the offset (usually 0) of each device the makes up the stripe set. Because there are 4 disks of 1953024 sectors each, the total array size will be 7812096 sectors.

RAID4
Because RAID4 uses a dedicated parity disk, one disk is "unusable", therefore the total space is 3 disks * 1953024 sectors, or a total of 5859072 sectors. To create a RAID4 set with no metadevice devices:

As RAID1, because there are no metadata device, the parity disk will have to be rebuilt every time it is assembled. To create a RAID4 WITH metadata devices:

It is possible to create a RAID4 in degraded mode initially. It is necessary to not specify any metadata devices, and "nosync" must added

The reason for doing this is its faster to create a degraded array, populate it, tear it down, and then reassemble the array with the missing metadata devices and data device, so that the parity is only computed once, not twice.

Cache
See Documentation/device-mapper/cache.txt</tt> and Documentation/device-mapper/cache-policies.txt for parameters and usage. This target is intended to speed up access to a slow but large rotational disk by using a faster but smaller SSD as a cache