diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 716 |
1 files changed, 659 insertions, 57 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index 99c10d8dc7..4b06b32232 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -144,6 +144,7 @@ Utilities * Invoking guix environment:: Setting up development environments. * Invoking guix publish:: Sharing substitutes. * Invoking guix challenge:: Challenging substitute servers. +* Invoking guix container:: Process isolation. GNU Distribution @@ -233,7 +234,8 @@ software packages, etc. @cindex functional package management The term @dfn{functional} refers to a specific package management -discipline. In Guix, the package build and installation process is seen +discipline pioneered by Nix (@pxref{Acknowledgments}). +In Guix, the package build and installation process is seen as a function, in the mathematical sense. That function takes inputs, such as build scripts, a compiler, and libraries, and returns an installed package. As a pure function, its result depends @@ -364,6 +366,10 @@ On hosts using the systemd init system, drop @file{~root/.guix-profile/lib/systemd/system/guix-daemon.service} in @file{/etc/systemd/system}. +Likewise, on hosts using the Upstart init system, drop +@file{~root/.guix-profile/lib/upstart/system/guix-daemon.conf} in +@file{/etc/init}. + @item Make the @command{guix} command available to other users on the machine, for instance with: @@ -552,7 +558,10 @@ parallel, as specified by the @option{--max-jobs} option following command@footnote{If your machine uses the systemd init system, dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service} file in @file{/etc/systemd/system} will ensure that -@command{guix-daemon} is automatically started.}: +@command{guix-daemon} is automatically started. Similarly, if your +machine uses the Upstart init system, drop the +@file{@var{prefix}/lib/upstart/system/guix-daemon.conf} +file in @file{/etc/init}.}: @example # guix-daemon --build-users-group=guixbuild @@ -591,6 +600,14 @@ user @file{nobody}; a writable @file{/tmp} directory. @end itemize +You can influence the directory where the daemon stores build trees +@i{via} the @code{TMPDIR} environment variable. However, the build tree +within the chroot is always @file{/tmp/nix-build-@var{name}.drv-0}, +where @var{name} is the derivation name---e.g., @code{coreutils-8.24}. +This way, the value of @code{TMPDIR} does not leak inside build +environments, which avoids discrepancies in cases where build processes +capture the name of their build tree. + If you are installing Guix as an unprivileged user, it is still possible to run @command{guix-daemon} provided you pass @code{--disable-chroot}. However, build processes will not be isolated from one another, and not @@ -998,6 +1015,17 @@ to display fonts, you will have to install fonts with Guix as well. Essential font packages include @code{gs-fonts}, @code{font-dejavu}, and @code{font-gnu-freefont-ttf}. +To display text written in Chinese languages, Japanese, or Korean in +graphical applications, consider installing +@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former +has multiple outputs, one per language family (@pxref{Packages with +Multiple Outputs}). For instance, the following command installs fonts +for Chinese languages: + +@example +guix package -i font-adobe-source-han-sans:cn +@end example + @c TODO What else? @c ********************************************************************* @@ -1345,6 +1373,20 @@ meaning that the returned environment variable definitions will either be exact settings, or prefixes or suffixes of the current value of these variables. When omitted, @var{kind} defaults to @code{exact}. +This option can also be used to compute the @emph{combined} search paths +of several profiles. Consider this example: + +@example +$ guix package -p foo -i guile +$ guix package -p bar -i guile-json +$ guix package -p foo -p bar --search-paths +@end example + +The last command above reports about the @code{GUILE_LOAD_PATH} +variable, even though, taken individually, neither @file{foo} nor +@file{bar} would lead to that recommendation. + + @item --profile=@var{profile} @itemx -p @var{profile} Use @var{profile} instead of the user's default profile. @@ -1604,7 +1646,10 @@ a diverse set of independent package builds, we can strengthen the integrity of our systems. The @command{guix challenge} command aims to help users assess substitute servers, and to assist developers in finding out about non-deterministic package builds (@pxref{Invoking guix -challenge}). +challenge}). Similarly, the @option{--check} option of @command{guix +build} allows users to check whether previously-installed substitutes +are genuine by rebuilding them locally (@pxref{build-check, +@command{guix build --check}}). In the future, we want Guix to have support to publish and retrieve binaries to/from other users, in a peer-to-peer fashion. If you would @@ -1812,7 +1857,9 @@ On completion, @command{guix package} will use packages and package versions from this just-retrieved copy of Guix. Not only that, but all the Guix commands and Scheme modules will also be taken from that latest version. New @command{guix} sub-commands added by the update also -become available. +become available@footnote{Under the hood, @command{guix pull} updates +the @file{~/.config/guix/latest} symbolic link to point to the latest +Guix, and the @command{guix} command loads code from there.}. The @command{guix pull} command is usually invoked with no arguments, but it supports the following options: @@ -3582,6 +3629,7 @@ programming interface of Guix in a convenient way. * Invoking guix environment:: Setting up development environments. * Invoking guix publish:: Sharing substitutes. * Invoking guix challenge:: Challenging substitute servers. +* Invoking guix container:: Process isolation. @end menu @node Invoking guix build @@ -3615,6 +3663,19 @@ The @var{options} may be zero or more of the following: @table @code +@item --file=@var{file} +@itemx -f @var{file} + +Build the package or derivation that the code within @var{file} +evaluates to. + +As an example, @var{file} might contain a package definition like this +(@pxref{Defining Packages}): + +@example +@verbatiminclude package-hello.scm +@end example + @item --expression=@var{expr} @itemx -e @var{expr} Build the package or derivation @var{expr} evaluates to. @@ -3736,6 +3797,19 @@ $ git clone git://git.sv.gnu.org/guix.git $ guix build guix --with-source=./guix @end example +@anchor{build-check} +@item --check +@cindex determinism, checking +@cindex reproducibility, checking +Rebuild @var{package-or-derivation}, which are already available in the +store, and raise an error if the build results are not bit-for-bit +identical. + +This mechanism allows you to check whether previously-installed +substitutes are genuine (@pxref{Substitutes}), or whether a package's +build result is deterministic. @xref{Invoking guix challenge}, for more +background information and tools. + @item --no-grafts Do not ``graft'' packages. In practice, this means that package updates available as grafts are not applied. @xref{Security Updates}, for more @@ -3826,6 +3900,20 @@ Do not use substitutes for build products. That is, always build things locally instead of allowing downloads of pre-built binaries (@pxref{Substitutes}). +@item --rounds=@var{n} +Build each derivation @var{n} times in a row, and raise an error if +consecutive build results are not bit-for-bit identical. + +This is a useful way to detect non-deterministic builds processes. +Non-deterministic build processes are a problem because they make it +practically impossible for users to @emph{verify} whether third-party +binaries are genuine. @xref{Invoking guix challenge}, for more. + +Note that, currently, the differing build results are not kept around, +so you will have to manually investigate in case of an error---e.g., by +stashing one of the build results with @code{guix archive --export}, +then rebuilding, and finally comparing the two results. + @item --no-build-hook Do not attempt to offload builds @i{via} the daemon's ``build hook'' (@pxref{Daemon Offload Setup}). That is, always build things locally @@ -3897,8 +3985,9 @@ guix edit gcc-4.8 vim @end example @noindent -launches the program specified in the @code{EDITOR} environment variable -to edit the recipe of GCC@tie{}4.8.4 and that of Vim. +launches the program specified in the @code{VISUAL} or in the +@code{EDITOR} environment variable to edit the recipe of GCC@tie{}4.8.4 +and that of Vim. If you are using Emacs, note that the Emacs user interface provides similar functionality in the ``package info'' and ``package list'' @@ -4112,6 +4201,15 @@ package definition. When importing a GNU package, the synopsis and descriptions are replaced by their canonical upstream variant. +Usually, you will first need to do: + +@example +export NIX_REMOTE=daemon +@end example + +@noindent +so that @command{nix-instantiate} does not try to open the Nix database. + As an example, the command below imports the package definition of LibreOffice (more precisely, it imports the definition of the package bound to the @code{libreoffice} top-level attribute): @@ -4233,6 +4331,19 @@ The following options are supported: @table @code +@item --expression=@var{expr} +@itemx -e @var{expr} +Consider the package @var{expr} evaluates to. + +This is useful to precisely refer to a package, as in this example: + +@example +guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)' +@end example + +This command lists the dependents of the ``final'' libc (essentially all +the packages.) + @item --update @itemx -u Update distribution source files (package recipes) in place. This is @@ -4263,23 +4374,27 @@ inconvenient. @item --type=@var{updater} @itemx -t @var{updater} -Select only packages handled by @var{updater}. Currently, @var{updater} -may be one of: +Select only packages handled by @var{updater} (may be a comma-separated +list of updaters). Currently, @var{updater} may be one of: @table @code @item gnu the updater for GNU packages; +@item gnome +the updater for GNOME packages; @item elpa the updater for @uref{http://elpa.gnu.org/, ELPA} packages; @item cran -the updater fro @uref{http://cran.r-project.org/, CRAN} packages. +the updater for @uref{http://cran.r-project.org/, CRAN} packages; +@item pypi +the updater for @uref{https://pypi.python.org, PyPI} packages. @end table For instance, the following commands only checks for updates of Emacs packages hosted at @code{elpa.gnu.org} and updates of CRAN packages: @example -$ guix refresh -t elpa -t cran +$ guix refresh --type=elpa,cran gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0 gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9 @end example @@ -4305,6 +4420,10 @@ be used when passing @command{guix refresh} one or more package names: @table @code +@item --list-updaters +@itemx -L +List available updaters and exit (see @option{--type} above.) + @item --list-dependent @itemx -l List top-level dependent packages that would need to be rebuilt as a @@ -4380,6 +4499,12 @@ invalid. Check that the source file name is meaningful, e.g. is not just a version number or ``git-checkout'', and should not have a @code{file-name} declared (@pxref{origin Reference}). +@item cve +Report known vulnerabilities found in the Common Vulnerabilities and +Exposures (CVE) database +@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US +NIST}. + @item formatting Warn about obvious source code formatting issues: trailing white space, use of tabulations, etc. @@ -4559,6 +4684,9 @@ here, for conciseness. Similar to @code{bag-emerged}, but this time including all the bootstrap dependencies. +@item bag-with-origins +Similar to @code{bag}, but also showing origins and their dependencies. + @item derivations This is the most detailed representation: It shows the DAG of derivations (@pxref{Derivations}) and plain store items. Compared to @@ -4681,12 +4809,43 @@ NumPy: guix environment --ad-hoc python2-numpy python-2.7 -- python @end example +Furthermore, one might want the dependencies of a package and also some +additional packages that are not build-time or runtime dependencies, but +are useful when developing nonetheless. Because of this, the +@code{--ad-hoc} flag is positional. Packages appearing before +@code{--ad-hoc} are interpreted as packages whose dependencies will be +added to the environment. Packages appearing after are interpreted as +packages that will be added to the environment directly. For example, +the following command creates a Guix development environment that +additionally includes Git and strace: + +@example +guix environment guix --ad-hoc git strace +@end example + +Sometimes it is desirable to isolate the environment as much as +possible, for maximal purity and reproducibility. In particular, when +using Guix on a host distro that is not GuixSD, it is desirable to +prevent access to @file{/usr/bin} and other system-wide resources from +the development environment. For example, the following command spawns +a Guile REPL in a ``container'' where only the store and the current +working directory are mounted: + +@example +guix environment --ad-hoc --container guile -- guile +@end example + +@quotation Note +The @code{--container} option requires Linux-libre 3.19 or newer. +@end quotation + The available options are summarized below. @table @code @item --expression=@var{expr} @itemx -e @var{expr} -Create an environment for the package that @var{expr} evaluates to. +Create an environment for the package or list of packages that +@var{expr} evaluates to. For example, running: @@ -4697,10 +4856,18 @@ guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' starts a shell with the environment for this specific variant of the PETSc package. +Running: + +@example +guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' +@end example + +starts a shell with all the GuixSD base packages available. + @item --load=@var{file} @itemx -l @var{file} -Create an environment for the package that the code within @var{file} -evaluates to. +Create an environment for the package or list of packages that the code +within @var{file} evaluates to. As an example, @var{file} might contain a definition like this (@pxref{Defining Packages}): @@ -4729,6 +4896,12 @@ Note that this example implicitly asks for the default output of specific output---e.g., @code{glib:bin} asks for the @code{bin} output of @code{glib} (@pxref{Packages with Multiple Outputs}). +This option may be composed with the default behavior of @command{guix +environment}. Packages appearing before @code{--ad-hoc} are interpreted +as packages whose dependencies will be added to the environment, the +default behavior. Packages appearing after are interpreted as packages +that will be added to the environment directly. + @item --pure Unset existing environment variables when building the new environment. This has the effect of creating an environment in which search paths @@ -4741,6 +4914,49 @@ environment. @item --system=@var{system} @itemx -s @var{system} Attempt to build for @var{system}---e.g., @code{i686-linux}. + +@item --container +@itemx -C +@cindex container +Run @var{command} within an isolated container. The current working +directory outside the container is mapped inside the +container. Additionally, the spawned process runs as the current user +outside the container, but has root privileges in the context of the +container. + +@item --network +@itemx -N +For containers, share the network namespace with the host system. +Containers created without this flag only have access to the loopback +device. + +@item --expose=@var{source}[=@var{target}] +For containers, expose the file system @var{source} from the host system +as the read-only file system @var{target} within the container. If +@var{target} is not specified, @var{source} is used as the target mount +point in the container. + +The example below spawns a Guile REPL in a container in which the user's +home directory is accessible read-only via the @file{/exchange} +directory: + +@example +guix environment --container --expose=$HOME=/exchange guile -- guile +@end example + +@item --share=@var{source}[=@var{target}] +For containers, share the file system @var{source} from the host system +as the writable file system @var{target} within the container. If +@var{target} is not specified, @var{source} is used as the target mount +point in the container. + +The example below spawns a Guile REPL in a container in which the user's +home directory is accessible for both reading and writing via the +@file{/exchange} directory: + +@example +guix environment --container --share=$HOME=/exchange guile -- guile +@end example @end table It also supports all of the common build options that @command{guix @@ -4765,6 +4981,10 @@ their authenticity and integrity (@pxref{Substitutes}). Because readable by the system administrator, it must be started as root; the @code{--user} option makes it drop root privileges early on. +The signing key pair must be generated before @command{guix publish} is +launched, using @command{guix archive --generate-key} (@pxref{Invoking +guix archive}). + The general syntax is: @example @@ -4808,6 +5028,11 @@ Reference Manual}) on @var{port} (37146 by default). This is used primarily for debugging a running @command{guix publish} server. @end table +Enabling @command{guix publish} on a GuixSD system is a one-liner: just +add a call to @code{guix-publish-service} in the @code{services} field +of the @code{operating-system} declaration (@pxref{guix-publish-service, +@code{guix-publish-service}}). + @node Invoking guix challenge @section Invoking @command{guix challenge} @@ -4882,7 +5107,7 @@ these lines (@pxref{Invoking guix archive}): @example $ wget -q -O - http://hydra.gnu.org/nar/@dots{}-git-2.5.0 \ | guix archive -x /tmp/git -$ diff -ur /gnu/store/@dots{}-git.2.5.0 /tmp/git +$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git @end example This command shows the difference between the files resulting from the @@ -4930,6 +5155,60 @@ URLs to compare to. @end table +@node Invoking guix container +@section Invoking @command{guix container} +@cindex container + +@quotation Note +As of version @value{VERSION}, this tool is experimental. The interface +is subject to radical change in the future. +@end quotation + +The purpose of @command{guix container} is to manipulate processes +running within an isolated environment, commonly known as a +``container'', typically created by the @command{guix environment} +(@pxref{Invoking guix environment}) and @command{guix system container} +(@pxref{Invoking guix system}) commands. + +The general syntax is: + +@example +guix container @var{action} @var{options}@dots{} +@end example + +@var{action} specifies the operation to perform with a container, and +@var{options} specifies the context-specific arguments for the action. + +The following actions are available: + +@table @code +@item exec +Execute a command within the context of a running container. + +The syntax is: + +@example +guix container exec @var{pid} @var{program} @var{arguments}@dots{} +@end example + +@var{pid} specifies the process ID of the running container. +@var{program} specifies an executable file name within the container's +root file system. @var{arguments} are the additional options that will +be passed to @var{program}. + +The following command launches an interactive login shell inside a +GuixSD container, started by @command{guix system container}, and whose +process ID is 9001: + +@example +guix container exec 9001 /run/current-system/profile/bin/bash --login +@end example + +Note that the @var{pid} cannot be the parent process of a container. It +must be the container's PID 1 or one of its child processes. + +@end table + @c ********************************************************************* @node GNU Distribution @chapter GNU Distribution @@ -5111,21 +5390,28 @@ Once you have successfully booted the image on the USB stick, you should end up with a root prompt. Several console TTYs are configured and can be used to run commands as root. TTY2 shows this documentation, browsable using the Info reader commands (@pxref{Help,,, info, Info: An -Introduction}). +Introduction}). The installation system runs the GPM mouse daemon, +which allows you to select text with the left mouse button and to paste +it with the middle button. To install the system, you would: @enumerate @item -Configure the network, by running @command{ifconfig eno1 up && dhclient -eno1} (to get an automatically assigned IP address from the wired +Configure the network, by running: + +@example +ifconfig eno1 up && dhclient eno1 +@end example + +to get an automatically assigned IP address from the wired network interface controller@footnote{ @c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 The name @code{eno1} is for the first on-board Ethernet controller. The interface name for an Ethernet controller that is in the first slot of the first PCI bus, for instance, would be @code{enp1s0}. Use -@command{ifconfig -a} to list all the available network interfaces.}), +@command{ifconfig -a} to list all the available network interfaces.}, or using the @command{ifconfig} command. The system automatically loads drivers for your network interface @@ -5135,14 +5421,25 @@ Setting up network access is almost always a requirement because the image does not contain all the software and tools that may be needed. @item -Unless this has already been done, you must partition and format the -target partitions. +Unless this has already been done, you must partition, and then format +the target partition. Preferably, assign partitions a label so that you can easily and reliably refer to them in @code{file-system} declarations (@pxref{File Systems}). This is typically done using the @code{-L} option of @command{mkfs.ext4} and related commands. +@c FIXME: Uncomment this once GRUB fully supports encrypted roots. +@c A typical command sequence may be: +@c +@c @example +@c # fdisk /dev/sdX +@c @dots{} Create partitions etc.@dots{} +@c # cryptsetup luksFormat /dev/sdX1 +@c # cryptsetup open --type luks /dev/sdX1 my-partition +@c # mkfs.ext4 -L my-root /dev/mapper/my-partition +@c @end example + The installation image includes Parted (@pxref{Overview,,, parted, GNU Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk encryption, and e2fsprogs, the suite of tools to manipulate @@ -5283,24 +5580,68 @@ addition to the per-user profiles (@pxref{Invoking guix package}). The for basic user and administrator tasks---including the GNU Core Utilities, the GNU Networking Utilities, the GNU Zile lightweight text editor, @command{find}, @command{grep}, etc. The example above adds -Emacs to those, taken from the @code{(gnu packages emacs)} module +tcpdump to those, taken from the @code{(gnu packages admin)} module (@pxref{Package Modules}). +@findex specification->package +Referring to packages by variable name, like @var{tcpdump} above, has +the advantage of being unambiguous; it also allows typos and such to be +diagnosed right away as ``unbound variables''. The downside is that one +needs to know which module defines which package, and to augment the +@code{use-package-modules} line accordingly. To avoid that, one can use +the @code{specification->package} procedure of the @code{(gnu packages)} +module, which returns the best package for a given name or name and +version: + +@lisp +(use-modules (gnu packages)) + +(operating-system + ;; ... + (packages (append (map specification->package + '("tcpdump" "htop" "gnupg-2.0")) + %base-packages))) +@end lisp + @vindex %base-services The @code{services} field lists @dfn{system services} to be made available when the system starts (@pxref{Services}). The @code{operating-system} declaration above specifies that, in addition to the basic services, we want the @command{lshd} secure shell -daemon listening on port 2222, and allowing remote @code{root} logins -(@pxref{Invoking lshd,,, lsh, GNU lsh Manual}). Under the hood, +daemon listening on port 2222 (@pxref{Networking Services, +@code{lsh-service}}). Under the hood, @code{lsh-service} arranges so that @code{lshd} is started with the right command-line options, possibly with supporting configuration files -generated as needed (@pxref{Defining Services}). @xref{operating-system -Reference}, for details about the available @code{operating-system} -fields. +generated as needed (@pxref{Defining Services}). + +@cindex customization, of services +@findex modify-services +Occasionally, instead of using the base services as is, you will want to +customize them. For instance, to change the configuration of +@code{guix-daemon} and Mingetty (the console log-in), you may write the +following instead of @var{%base-services}: + +@lisp +(modify-services %base-services + (guix-service-type config => + (guix-configuration + (inherit config) + (use-substitutes? #f) + (extra-options '("--gc-keep-outputs")))) + (mingetty-service-type config => + (mingetty-configuration + (inherit config) + (motd (plain-file "motd" "Hi there!"))))) +@end lisp + +@noindent +The effect here is to change the options passed to @command{guix-daemon} +when it is started, as well as the ``message of the day'' that appears +when logging in at the console. @xref{Service Reference, +@code{modify-services}}, for more on that. The configuration for a typical ``desktop'' usage, with the X11 display -server, a desktop environment, network management, an SSH server, and +server, a desktop environment, network management, power management, and more, would look like this: @lisp @@ -5310,13 +5651,30 @@ more, would look like this: @xref{Desktop Services}, for the exact list of services provided by @var{%desktop-services}. @xref{X.509 Certificates}, for background information about the @code{nss-certs} package that is used here. +@xref{operating-system Reference}, for details about all the available +@code{operating-system} fields. Assuming the above snippet is stored in the @file{my-system-config.scm} file, the @command{guix system reconfigure my-system-config.scm} command instantiates that configuration, and makes it the default GRUB boot -entry (@pxref{Invoking guix system}). The normal way to change the -system's configuration is by updating this file and re-running the -@command{guix system} command. +entry (@pxref{Invoking guix system}). + +The normal way to change the system's configuration is by updating this +file and re-running @command{guix system reconfigure}. One should never +have to touch files in @command{/etc} or to run commands that modify the +system state such as @command{useradd} or @command{grub-install}. In +fact, you must avoid that since that would not only void your warranty +but also prevent you from rolling back to previous versions of your +system, should you ever need to. + +@cindex roll-back, of the operating system +Speaking of roll-back, each time you run @command{guix system +reconfigure}, a new @dfn{generation} of the system is created---without +modifying or deleting previous generations. Old system generations get +an entry in the GRUB boot menu, allowing you to boot them in case +something went wrong with the latest generation. Reassuring, no? The +@command{guix system list-generations} command lists the system +generations available on disk. At the Scheme level, the bulk of an @code{operating-system} declaration is instantiated with the following monadic procedure (@pxref{The Store @@ -5428,13 +5786,18 @@ Library Reference Manual}). @xref{Locales}, for more information. The list of locale definitions to be compiled and that may be used at run time. @xref{Locales}. +@item @code{locale-libcs} (default: @code{(list @var{glibc})}) +The list of GNU@tie{}libc packages whose locale data and tools are used +to build the locale definitions. @xref{Locales}, for compatibility +considerations that justify this option. + @item @code{name-service-switch} (default: @var{%default-nss}) Configuration of libc's name service switch (NSS)---a @code{<name-service-switch>} object. @xref{Name Service Switch}, for details. @item @code{services} (default: @var{%base-services}) -A list of monadic values denoting system services. @xref{Services}. +A list of service objects denoting system services. @xref{Services}. @item @code{pam-services} (default: @code{(base-pam-services)}) @cindex PAM @@ -5886,6 +6249,57 @@ instance it has @code{uk_UA.utf8} but @emph{not}, say, @code{uk_UA.UTF-8}. @end defvr +@subsubsection Locale Data Compatibility Considerations + +@cindex incompatibility, of locale data +@code{operating-system} declarations provide a @code{locale-libcs} field +to specify the GNU@tie{}libc packages that are used to compile locale +declarations (@pxref{operating-system Reference}). ``Why would I +care?'', you may ask. Well, it turns out that the binary format of +locale data is occasionally incompatible from one libc version to +another. + +@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html> +@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>. +For instance, a program linked against libc version 2.21 is unable to +read locale data produced with libc 2.22; worse, that program +@emph{aborts} instead of simply ignoring the incompatible locale +data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip +the incompatible locale data, which is already an improvement.}. +Similarly, a program linked against libc 2.22 can read most, but not +all, the locale data from libc 2.21 (specifically, @code{LC_COLLATE} +data is incompatible); thus calls to @code{setlocale} may fail, but +programs will not abort. + +The ``problem'' in GuixSD is that users have a lot of freedom: They can +choose whether and when to upgrade software in their profiles, and might +be using a libc version different from the one the system administrator +used to build the system-wide locale data. + +Fortunately, unprivileged users can also install their own locale data +and define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath, +@code{GUIX_LOCPATH} and locale packages}). + +Still, it is best if the system-wide locale data at +@file{/run/current-system/locale} is built for all the libc versions +actually in use on the system, so that all the programs can access +it---this is especially crucial on a multi-user system. To do that, the +administrator can specify several libc packages in the +@code{locale-libcs} field of @code{operating-system}: + +@example +(use-package-modules base) + +(operating-system + ;; @dots{} + (locale-libcs (list glibc-2.21 (canonical-package glibc)))) +@end example + +This example would lead to a system containing locale definitions for +both libc 2.21 and the current version of libc in +@file{/run/current-system/locale}. + + @node Services @subsection Services @@ -5949,8 +6363,8 @@ services that one expects from the system. The services exported by this module are listed below. @defvr {Scheme Variable} %base-services -This variable contains a list of basic services@footnote{Technically, -this is a list of monadic services. @xref{The Store Monad}.} one would +This variable contains a list of basic services (@pxref{Service Types +and Services}, for more information on service objects) one would expect from the system: a login service (mingetty) on each tty, syslogd, libc's name service cache daemon (nscd), the udev device manager, and more. @@ -6130,6 +6544,9 @@ Whether to authorize the substitute key for @code{hydra.gnu.org} @item @code{use-substitutes?} (default: @code{#t}) Whether to use substitutes. +@item @code{substitute-urls} (default: @var{%default-substitute-urls}) +The list of URLs where to look for substitutes by default. + @item @code{extra-options} (default: @code{'()}) List of extra command-line options for @command{guix-daemon}. @@ -6154,6 +6571,27 @@ Return a service to load console keymap from @var{file} using @command{loadkeys} command. @end deffn +@deffn {Scheme Procedure} gpm-service-type [#:gpm @var{gpm}] @ + [#:options] +Run @var{gpm}, the general-purpose mouse daemon, with the given +command-line @var{options}. GPM allows users to use the mouse in the console, +notably to select, copy, and paste text. The default value of @var{options} +uses the @code{ps2} protocol, which works for both USB and PS/2 mice. + +This service is not part of @var{%base-services}. +@end deffn + +@anchor{guix-publish-service} +@deffn {Scheme Procedure} guix-publish-service [#:guix @var{guix}] @ + [#:port 80] [#:host "localhost"] +Return a service that runs @command{guix publish} listening on @var{host} +and @var{port} (@pxref{Invoking guix publish}). + +This assumes that @file{/etc/guix} already contains a signing key pair as +created by @command{guix archive --generate-key} (@pxref{Invoking guix +archive}). If that is not the case, the service will fail to start. +@end deffn + @node Networking Services @subsubsection Networking Services @@ -6175,9 +6613,15 @@ gateway. @end deffn @cindex wicd +@cindex network management @deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] -Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a -network manager that aims to simplify wired and wireless networking. +Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network +management daemon that aims to simplify wired and wireless networking. + +This service adds the @var{wicd} package to the global profile, providing +several commands to interact with the daemon and configure networking: +@command{wicd-client}, a graphical user interface, and the @command{wicd-cli} +and @command{wicd-curses} user interfaces. @end deffn @deffn {Scheme Procedure} ntp-service [#:ntp @var{ntp}] @ @@ -6191,11 +6635,34 @@ keep the system clock synchronized with that of @var{servers}. List of host names used as the default NTP servers. @end defvr -@deffn {Scheme Procedure} tor-service [#:tor tor] -Return a service to run the @uref{https://torproject.org,Tor} daemon. +@deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}] +Return a service to run the @uref{https://torproject.org, Tor} anonymous +networking daemon. + +The daemon runs as the @code{tor} unprivileged user. It is passed +@var{config-file}, a file-like object, with an additional @code{User tor} line +and lines for hidden services added via @code{tor-hidden-service}. Run +@command{man tor} for information about the configuration file. +@end deffn + +@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping} +Define a new Tor @dfn{hidden service} called @var{name} and implementing +@var{mapping}. @var{mapping} is a list of port/host tuples, such as: -The daemon runs with the default settings (in particular the default exit -policy) as the @code{tor} unprivileged user. +@example + '((22 \"127.0.0.1:22\") + (80 \"127.0.0.1:8080\")) +@end example + +In this example, port 22 of the hidden service is mapped to local port 22, and +port 80 is mapped to local port 8080. + +This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where +the @file{hostname} file contains the @code{.onion} host name for the hidden +service. + +See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor +project's documentation} for more information. @end deffn @deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @ @@ -6291,7 +6758,9 @@ mDNS/DNS-SD responder that allows for service discovery and "zero-configuration" host name lookups (see @uref{http://avahi.org/}), and extends the name service cache daemon (nscd) so that it can resolve @code{.local} host names using -@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. +@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. Additionally, +add the @var{avahi} package to the system profile so that commands such as +@command{avahi-browse} are directly usable. If @var{host-name} is different from @code{#f}, use that as the host name to publish for this machine; otherwise, use the machine's actual host name. @@ -6379,6 +6848,19 @@ Last, @var{extra-config} is a list of strings or objects appended to the verbatim to the configuration file. @end deffn +@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{name}] +Add @var{package}, a package for a screen-locker or screen-saver whose +command is @var{program}, to the set of setuid programs and add a PAM entry +for it. For example: + +@lisp +(screen-locker-service xlockmore "xlock") +@end lisp + +makes the good ol' XlockMore usable. +@end deffn + + @node Desktop Services @subsubsection Desktop Services @@ -6396,7 +6878,8 @@ This is a list of services that builds upon @var{%base-services} and adds or adjust services for a typical ``desktop'' setup. In particular, it adds a graphical login manager (@pxref{X Window, -@code{slim-service}}), a network management tool (@pxref{Networking +@code{slim-service}}), screen lockers, +a network management tool (@pxref{Networking Services, @code{wicd-service}}), energy and color management services, the @code{elogind} login and seat manager, the Polkit privilege service, the GeoClue location service, an NTP client (@pxref{Networking @@ -6498,12 +6981,13 @@ their default values are: @deffn {Scheme Procedure} polkit-service @ [#:polkit @var{polkit}] -Return a service that runs the Polkit privilege manager. -@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit} allows -system administrators to grant access to privileged operations in a -structured way. For example, polkit rules can allow a logged-in user -whose session is active to shut down the machine, if there are no other -users active. +Return a service that runs the +@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege +management service}, which allows system administrators to grant access to +privileged operations in a structured way. By querying the Polkit service, a +privileged system component can know when it should grant additional +capabilities to ordinary users. For example, an ordinary user can be granted +the capability to suspend the system if the user is logged in locally. @end deffn @deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @ @@ -6525,6 +7009,13 @@ levels, with the given configuration settings. It implements the GNOME. @end deffn +@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}] +Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, +UDisks}, a @dfn{disk management} daemon that provides user interfaces with +notifications and ways to mount/unmount disks. Programs that talk to UDisks +include the @command{udisksctl} command, part of UDisks, and GNOME Disks. +@end deffn + @deffn {Scheme Procedure} colord-service [#:colord @var{colord}] Return a service that runs @command{colord}, a system service with a D-Bus interface to manage the color profiles of input and output devices such as @@ -7022,7 +7513,7 @@ supported: @item reconfigure Build the operating system described in @var{file}, activate it, and switch to it@footnote{This action is usable only on systems already -running GNU.}. +running GuixSD.}. This effects all the configuration specified in @var{file}: user accounts, system services, global package list, setuid programs, etc. @@ -7064,6 +7555,7 @@ This command also installs GRUB on the device specified in @item vm @cindex virtual machine @cindex VM +@anchor{guix system vm} Build a virtual machine that contain the operating system declared in @var{file}, and return a script to run that virtual machine (VM). Arguments given to the script are passed as is to QEMU. @@ -7112,6 +7604,31 @@ using the following command: # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc @end example +@item container +Return a script to run the operating system declared in @var{file} +within a container. Containers are a set of lightweight isolation +mechanisms provided by the kernel Linux-libre. Containers are +substantially less resource-demanding than full virtual machines since +the kernel, shared objects, and other resources can be shared with the +host system; this also means they provide thinner isolation. + +Currently, the script must be run as root in order to support more than +a single user and group. The container shares its store with the host +system. + +As with the @code{vm} action (@pxref{guix system vm}), additional file +systems to be shared between the host and container can be specified +using the @option{--share} and @option{--expose} options: + +@example +guix system container my-config.scm \ + --expose=$HOME --share=$HOME/tmp=/exchange +@end example + +@quotation Note +This option requires Linux-libre 3.19 or newer. +@end quotation + @end table @var{options} can contain any of the common build options provided by @@ -7162,6 +7679,30 @@ KVM kernel module should be loaded, and the @file{/dev/kvm} device node must exist and be readable and writable by the user and by the daemon's build users. +Once you have built, configured, re-configured, and re-re-configured +your GuixSD installation, you may find it useful to list the operating +system generations available on disk---and that you can choose from the +GRUB boot menu: + +@table @code + +@item list-generations +List a summary of each generation of the operating system available on +disk, in a human-readable way. This is similar to the +@option{--list-generations} option of @command{guix package} +(@pxref{Invoking guix package}). + +Optionally, one can specify a pattern, with the same syntax that is used +in @command{guix package --list-generations}, to restrict the list of +generations displayed. For instance, the following command displays +generations up to 10-day old: + +@example +$ guix system list-generations 10d +@end example + +@end table + The @command{guix system} command has even more to offer! The following sub-commands allow you to visualize how your system services relate to each other: @@ -7243,8 +7784,11 @@ as arrows, a typical system might provide something like this: @image{images/service-graph,,5in,Typical service extension graph.} -At the bottom, we see the @dfn{boot service}, which produces the boot -script that is executed at boot time from the initial RAM disk. +@cindex system service +At the bottom, we see the @dfn{system service}, which produces the +directory containing everything to run and boot the system, as returned +by the @command{guix system build} command. @xref{Service Reference}, +to learn about the other service types shown here. @xref{system-extension-graph, the @command{guix system extension-graph} command}, for information on how to generate this representation for a particular operating system definition. @@ -7424,6 +7968,41 @@ Here is an example of how a service is created and manipulated: @result{} #t @end example +The @code{modify-services} form provides a handy way to change the +parameters of some of the services of a list such as +@var{%base-services} (@pxref{Base Services, @code{%base-services}}). Of +course, you could always use standard list combinators such as +@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, +guile, GNU Guile Reference Manual}); @code{modify-services} simply +provides a more concise form for this common pattern. + +@deffn {Scheme Syntax} modify-services @var{services} @ + (@var{type} @var{variable} => @var{body}) @dots{} + +Modify the services listed in @var{services} according to the given +clauses. Each clause has the form: + +@example +(@var{type} @var{variable} => @var{body}) +@end example + +where @var{type} is a service type, such as @var{guix-service-type}, and +@var{variable} is an identifier that is bound within @var{body} to the +value of the service of that @var{type}. @xref{Using the Configuration +System}, for an example. + +This is a shorthand for: + +@example +(map (lambda (service) @dots{}) @var{services}) +@end example +@end deffn + +Next comes the programming interface for service types. This is +something you want to know when writing new service definitions, but not +necessarily when simply looking for ways to customize your +@code{operating-system} declaration. + @deftp {Data Type} service-type @cindex service type This is the representation of a @dfn{service type} (@pxref{Service Types @@ -7472,12 +8051,14 @@ Return true if @var{obj} is a service extension. At the core of the service abstraction lies the @code{fold-services} procedure, which is responsible for ``compiling'' a list of services -down to a single boot script. In essence, it propagates service -extensions down the service graph, updating each node parameters on the -way, until it reaches the root node. +down to a single directory that contains everything needed to boot and +run the system---the directory shown by the @command{guix system build} +command (@pxref{Invoking guix system}). In essence, it propagates +service extensions down the service graph, updating each node parameters +on the way, until it reaches the root node. @deffn {Scheme Procedure} fold-services @var{services} @ - [#:target-type @var{boot-service-type}] + [#:target-type @var{system-service-type}] Fold @var{services} by propagating their extensions down to the root of type @var{target-type}; return the root service adjusted accordingly. @end deffn @@ -7485,9 +8066,14 @@ type @var{target-type}; return the root service adjusted accordingly. Lastly, the @code{(gnu services)} module also defines several essential service types, some of which are listed below. +@defvr {Scheme Variable} system-service-type +This is the root of the service graph. It produces the system directory +as returned by the @command{guix system build} command. +@end defvr + @defvr {Scheme Variable} boot-service-type -The type of the ``boot service'', which is the root of the service -graph. +The type of the ``boot service'', which produces the @dfn{boot script}. +The boot script is what the initial RAM disk runs when booting. @end defvr @defvr {Scheme Variable} etc-service-type @@ -7508,6 +8094,12 @@ executable file names, passed as gexps, and adds them to the set of setuid-root programs on the system (@pxref{Setuid Programs}). @end defvr +@defvr {Scheme Variable} profile-service-type +Type of the service that populates the @dfn{system profile}---i.e., the +programs under @file{/run/current-system/profile}. Other services can +extend it by passing it lists of packages to add to the system profile. +@end defvr + @node dmd Services @subsubsection dmd Services @@ -7570,6 +8162,15 @@ deco doc @var{service-name} where @var{service-name} is one of the symbols in @var{provision} (@pxref{Invoking deco,,, dmd, GNU dmd Manual}). + +@item @code{modules} (default: @var{%default-modules}) +This is the list of modules that must be in scope when @code{start} and +@code{stop} are evaluated. + +@item @code{imported-modules} (default: @var{%default-imported-modules}) +This is the list of modules to import in the execution environment of +dmd. + @end table @end deftp @@ -8245,7 +8846,8 @@ reason. @node Acknowledgments @chapter Acknowledgments -Guix is based on the Nix package manager, which was designed and +Guix is based on the @uref{http://nixos.org/nix/, Nix package manager}, +which was designed and implemented by Eelco Dolstra, with contributions from other people (see the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package management, and promoted unprecedented features, such as transactional |