11.5 Mapped Devices

The Linux kernel has a notion of device mapping: a block device, such as a hard disk partition, can be mapped into another device, usually in /dev/mapper/, with additional processing over the data that flows through it³¹. A typical example is encryption device mapping: all writes to the mapped device are encrypted, and all reads are deciphered, transparently. Guix extends this notion by considering any device or set of devices that are transformed in some way to create a new device; for instance, RAID devices are obtained by assembling several other devices, such as hard disks or partitions, into a new one that behaves as one partition.

Mapped devices are declared using the mapped-device form, defined as follows; for examples, see below.

Data Type: mapped-device

Objects of this type represent device mappings that will be made when the system boots up.

source

This is either a string specifying the name of the block device to be mapped, such as "/dev/sda3", or a list of such strings when several devices need to be assembled for creating a new one. In case of LVM this is a string specifying name of the volume group to be mapped.

target

This string specifies the name of the resulting mapped device. For kernel mappers such as encrypted devices of type luks-device-mapping, specifying "my-partition" leads to the creation of the "/dev/mapper/my-partition" device. For RAID devices of type raid-device-mapping, the full device name such as "/dev/md0" needs to be given. LVM logical volumes of type lvm-device-mapping need to be specified as "VGNAME-LVNAME".

targets

This list of strings specifies names of the resulting mapped devices in case there are several. The format is identical to target.

type

This must be a mapped-device-kind object, which specifies how source is mapped to target.

Variable: luks-device-mapping

This defines LUKS block device encryption using the cryptsetup command from the package with the same name. It relies on the dm-crypt Linux kernel module.

Procedure: luks-device-mapping-with-options [#:key-file]

Return a luks-device-mapping object, which defines LUKS block device encryption using the cryptsetup command from the package with the same name. It relies on the dm-crypt Linux kernel module.

If key-file is provided, unlocking is first attempted using that key file. This has an advantage of not requiring a password entry, so it can be used (for example) to unlock RAID arrays automatically on boot. If key file unlock fails, password unlock is attempted as well. Key file is not stored in the store and needs to be available at the given location at the time of the unlock attempt.

;; Following definition would be equivalent to running:
;;   cryptsetup open --key-file /crypto.key /dev/sdb1 data
(mapped-device
 (source "/dev/sdb1)
 (target "data)
 (type (luks-device-mapping-with-options
        #:key-file "/crypto.key")))

Variable: raid-device-mapping

This defines a RAID device, which is assembled using the mdadm command from the package with the same name. It requires a Linux kernel module for the appropriate RAID level to be loaded, such as raid456 for RAID-4, RAID-5 or RAID-6, or raid10 for RAID-10.

Variable: lvm-device-mapping

This defines one or more logical volumes for the Linux Logical Volume Manager (LVM). The volume group is activated by the vgchange command from the lvm2 package.

The following example specifies a mapping from /dev/sda3 to /dev/mapper/home using LUKS—the Linux Unified Key Setup, a standard mechanism for disk encryption. The /dev/mapper/home device can then be used as the device of a file-system declaration (see File Systems).

(mapped-device
  (source "/dev/sda3")
  (target "home")
  (type luks-device-mapping))

Alternatively, to become independent of device numbering, one may obtain the LUKS UUID (unique identifier) of the source device by a command like:

cryptsetup luksUUID /dev/sda3

and use it as follows:

(mapped-device
  (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
  (target "home")
  (type luks-device-mapping))

It is also desirable to encrypt swap space, since swap space may contain sensitive data. One way to accomplish that is to use a swap file in a file system on a device mapped via LUKS encryption. In this way, the swap file is encrypted because the entire device is encrypted. See Swap Space, or See Disk Partitioning, for an example.

A RAID device formed of the partitions /dev/sda1 and /dev/sdb1 may be declared as follows:

(mapped-device
  (source (list "/dev/sda1" "/dev/sdb1"))
  (target "/dev/md0")
  (type raid-device-mapping))

The /dev/md0 device can then be used as the device of a file-system declaration (see File Systems). Note that the RAID level need not be given; it is chosen during the initial creation and formatting of the RAID device and is determined automatically later.

LVM logical volumes “alpha” and “beta” from volume group “vg0” can be declared as follows:

(mapped-device
  (source "vg0")
  (targets (list "vg0-alpha" "vg0-beta"))
  (type lvm-device-mapping))

Devices /dev/mapper/vg0-alpha and /dev/mapper/vg0-beta can then be used as the device of a file-system declaration (see File Systems).