summaryrefslogtreecommitdiff
path: root/doc
diff options
context:
space:
mode:
authorAndreas Enge <andreas@enge.fr>2016-07-28 11:08:55 +0200
committerAndreas Enge <andreas@enge.fr>2016-07-28 11:08:55 +0200
commite309c7561043361afe63cc9435e620323f870a61 (patch)
treecd6fe073ba840bb68f446933ece44b45d8eb5ec7 /doc
parent1bb163b0dd07c8f2cfd7e91f1e428075cd3d5ed2 (diff)
parente335b82c4eba13fe873db2d680d399469931c10f (diff)
Merge remote-tracking branch 'origin/master' into core-updates
Diffstat (limited to 'doc')
-rw-r--r--doc/guix.texi158
1 files changed, 114 insertions, 44 deletions
diff --git a/doc/guix.texi b/doc/guix.texi
index dd2004dd63..de996907fe 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -9,6 +9,9 @@
@include version.texi
+@c Identifier of the OpenPGP key used to sign tarballs and such.
+@set OPENPGP-SIGNING-KEY-ID 090B11993D9AEBB5
+
@copying
Copyright @copyright{} 2012, 2013, 2014, 2015, 2016 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
@@ -21,7 +24,8 @@ Copyright @copyright{} 2015, 2016 Leo Famulari@*
Copyright @copyright{} 2015, 2016 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016 Chris Marusich@*
-Copyright @copyright{} 2016 Efraim Flashner
+Copyright @copyright{} 2016 Efraim Flashner@*
+Copyright @copyright{} 2016 ng0
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -373,6 +377,7 @@ Download the binary tarball from
where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
already running the kernel Linux, and so on.
+@c The following is somewhat duplicated in ``System Installation''.
Make sure to download the associated @file{.sig} file and to verify the
authenticity of the tarball against it, along these lines:
@@ -385,11 +390,12 @@ If that command fails because you do not have the required public key,
then run this command to import it:
@example
-$ gpg --keyserver pgp.mit.edu --recv-keys 090B11993D9AEBB5
+$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
@end example
@noindent
and rerun the @code{gpg --verify} command.
+@c end authentication part
@item
As @code{root}, run:
@@ -5450,7 +5456,8 @@ details on Bash start-up files.}.
@vindex GUIX_ENVIRONMENT
@command{guix environment} defines the @code{GUIX_ENVIRONMENT}
-variable in the shell it spawns. This allows users to, say, define a
+variable in the shell it spawns; its value is the file name of the
+profile of this environment. This allows users to, say, define a
specific prompt for development environments in their @file{.bashrc}
(@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
@@ -5461,6 +5468,13 @@ then
fi
@end example
+@noindent
+... or to browse the profile:
+
+@example
+$ ls "$GUIX_ENVIRONMENT/bin"
+@end example
+
Additionally, more than one package may be specified, in which case the
union of the inputs for the given packages are used. For example, the
command below spawns a shell where all of the dependencies of both Guile
@@ -6133,6 +6147,26 @@ for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
for a 32-bit GNU/Linux system on Intel-compatible CPUs.
@end table
+@c start duplication of authentication part from ``Binary Installation''
+Make sure to download the associated @file{.sig} file and to verify the
+authenticity of the image against it, along these lines:
+
+@example
+$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
+$ gpg --verify guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
+@end example
+
+If that command fails because you do not have the required public key,
+then run this command to import it:
+
+@example
+$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+@end example
+
+@noindent
+and rerun the @code{gpg --verify} command.
+@c end duplication
+
This image contains a single partition with the tools necessary for an
installation. It is meant to be copied @emph{as is} to a large-enough
USB stick.
@@ -6972,6 +7006,7 @@ and unmount user-space FUSE file systems. This requires the
@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,
+usually in @code{/dev/mapper/},
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
@@ -6981,42 +7016,14 @@ 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.
+Guix extends this notion by considering any device or set of devices that
+are @dfn{transformed} in some way to create a new device; for instance,
+RAID devices are obtained by @dfn{assembling} several other devices, such
+as hard disks or partitions, into a new one that behaves as one partition.
+Other examples, not yet implemented, are LVM logical volumes.
-Mapped devices are declared using the @code{mapped-device} form:
-
-@example
-(mapped-device
- (source "/dev/sda3")
- (target "home")
- (type luks-device-mapping))
-@end example
-
-Or, better yet, like this:
-
-@example
-(mapped-device
- (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
- (target "home")
- (type luks-device-mapping))
-@end example
-
-@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. In the second example, the UUID
-(unique identifier) is the LUKS UUID returned for the device by a
-command like:
-
-@example
-cryptsetup luksUUID /dev/sdx9
-@end example
-
-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.
+Mapped devices are declared using the @code{mapped-device} form,
+defined as follows; for examples, see below.
@deftp {Data Type} mapped-device
Objects of this type represent device mappings that will be made when
@@ -7024,13 +7031,17 @@ 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"}.
+This is either a string specifying the name of the block device to be mapped,
+such as @code{"/dev/sda3"}, or a list of such strings when several devices
+need to be assembled for creating a new one.
@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
+This string specifies the name of the resulting mapped device. For
+kernel mappers such as encrypted devices of type @code{luks-device-mapping},
+specifying @code{"my-partition"} leads to the creation of
the @code{"/dev/mapper/my-partition"} device.
+For RAID devices of type @code{raid-device-mapping}, the full device name
+such as @code{"/dev/md0"} needs to be given.
@item type
This must be a @code{mapped-device-kind} object, which specifies how
@@ -7044,6 +7055,64 @@ command from the package with the same name. It relies on the
@code{dm-crypt} Linux kernel module.
@end defvr
+@defvr {Scheme Variable} raid-device-mapping
+This defines a RAID device, which is assembled using the @code{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 @code{raid456}
+for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
+@end defvr
+
+@cindex disk encryption
+@cindex LUKS
+The following 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}).
+
+@example
+(mapped-device
+ (source "/dev/sda3")
+ (target "home")
+ (type luks-device-mapping))
+@end example
+
+Alternatively, to become independent of device numbering, one may obtain
+the LUKS UUID (@dfn{unique identifier}) of the source device by a
+command like:
+
+@example
+cryptsetup luksUUID /dev/sda3
+@end example
+
+and use it as follows:
+
+@example
+(mapped-device
+ (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
+ (target "home")
+ (type luks-device-mapping))
+@end example
+
+A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
+may be declared as follows:
+
+@example
+(mapped-device
+ (source (list "/dev/sda1" "/dev/sdb1"))
+ (target "/dev/md0")
+ (type raid-device-mapping))
+@end example
+
+The @file{/dev/md0} device can then be used as the @code{device} of a
+@code{file-system} declaration (@pxref{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.
+
+
@node User Accounts
@subsection User Accounts
@@ -11477,9 +11546,10 @@ definition may look like this:
@example
(define my-package
- (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7"))
+ (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
+ (revision "1")) ;Guix package revision
(package
- (version (string-append "0.9-1."
+ (version (string-append "0.9-" revision "."
(string-take commit 7)))
(source (origin
(method git-fetch)