From 510f9d8624fb3440e0ec310826258d13e4f58c32 Mon Sep 17 00:00:00 2001 From: Ludovic Courtès Date: Thu, 18 Sep 2014 19:50:00 +0200 Subject: doc: Document mapped devices. * doc/guix.texi (Mapped Devices): New subsection. --- doc/guix.texi | 64 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 64 insertions(+) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index 1c1a04c75c..1c10bbeb54 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -3040,6 +3040,7 @@ instance to support new system services. @menu * Using the Configuration System:: Customizing your GNU system. * File Systems:: Configuring file system mounts. +* Mapped Devices:: Block device extra processing. * User Accounts:: Specifying user accounts. * Services:: Specifying system services. * Setuid Programs:: Programs running with root privileges. @@ -3245,6 +3246,69 @@ and unmount user-space FUSE file systems. This requires the @code{fuse.ko} kernel module to be loaded. @end defvr +@node Mapped Devices +@subsection Mapped Devices + +@cindex device mapping +@cindex mapped devices +The Linux kernel has a notion of @dfn{device mapping}: a block device, +such as a hard disk partition, can be @dfn{mapped} into another device, +with additional processing over the data that flows through +it@footnote{Note that the GNU@tie{}Hurd makes no difference between the +concept of a ``mapped device'' and that of a file system: both boil down +to @emph{translating} input/output operations made on a file to +operations on its backing store. Thus, the Hurd implements mapped +devices, like file systems, using the generic @dfn{translator} mechanism +(@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A +typical example is encryption device mapping: all writes to the mapped +device are encrypted, and all reads are deciphered, transparently. + +Mapped devices are declared using the @code{mapped-device} form: + +@example +(mapped-device + (source "/dev/sda3") + (target "home") + (type luks-device-mapping)) +@end example + +@noindent +@cindex disk encryption +@cindex LUKS +This example specifies a mapping from @file{/dev/sda3} to +@file{/dev/mapper/home} using LUKS---the +@url{http://code.google.com/p/cryptsetup,Linux Unified Key Setup}, a +standard mechanism for disk encryption. The @file{/dev/mapper/home} +device can then be used as the @code{device} of a @code{file-system} +declaration (@pxref{File Systems}). The @code{mapped-device} form is +detailed below. + +@deftp {Data Type} mapped-device +Objects of this type represent device mappings that will be made when +the system boots up. + +@table @code +@item source +This string specifies the name of the block device to be mapped, such as +@code{"/dev/sda3"}. + +@item target +This string specifies the name of the mapping to be established. For +example, specifying @code{"my-partition"} will lead to the creation of +the @code{"/dev/mapper/my-partition"} device. + +@item type +This must be a @code{mapped-device-kind} object, which specifies how +@var{source} is mapped to @var{target}. +@end table +@end deftp + +@defvr {Scheme Variable} luks-device-mapping +This defines LUKS block device encryption using the @command{cryptsetup} +command, from the same-named package. This relies on the +@code{dm-crypt} Linux kernel module. +@end defvr + @node User Accounts @subsection User Accounts -- cgit v1.2.3