Copyright @copyright{} 2017 Christopher Allan Webber@*
Copyright @copyright{} 2017, 2018 Marius Bakke@*
Copyright @copyright{} 2017 Hartmut Goebel@*
-Copyright @copyright{} 2017 Maxim Cournoyer@*
+Copyright @copyright{} 2017, 2019 Maxim Cournoyer@*
Copyright @copyright{} 2017, 2018, 2019 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2019 Diego Nicola Barbato@*
Copyright @copyright{} 2019 Ivan Petkov@*
Copyright @copyright{} 2019 Jakob L. Kreuze@*
+Copyright @copyright{} 2019 Kyle Andrews@*
+Copyright @copyright{} 2019 Alex Griffin@*
+Copyright @copyright{} 2019 Guillaume Le Vaillant@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Channels:: Customizing the package collection.
+* Invoking guix time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix archive:: Exporting and importing store files.
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
+* PAM Mount Service:: Service to mount volumes when logging in.
* Miscellaneous Services:: Other services.
Defining Services
* Setting Up the Daemon:: Preparing the build daemon's environment.
* Invoking guix-daemon:: Running the build daemon.
* Application Setup:: Application-specific setup.
+* Upgrading Guix:: Upgrading Guix and its build daemon.
@end menu
@node Binary Installation
be sure to specify the same state directory as the existing installation
using the @code{--localstatedir} option of the @command{configure}
script (@pxref{Directory Variables, @code{localstatedir},, standards,
-GNU Coding Standards}). The @command{configure} script protects against
-unintended misconfiguration of @var{localstatedir} so you do not
+GNU Coding Standards}). Usually, this @var{localstatedir} option is
+set to the value @file{/var}. The @command{configure} script protects
+against unintended misconfiguration of @var{localstatedir} so you do not
inadvertently corrupt your store (@pxref{The Store}).
-@cindex Nix, compatibility
-When a working installation of @url{https://nixos.org/nix/, the Nix package
-manager} is available, you
-can instead configure Guix with @code{--disable-daemon}. In that case,
-Nix replaces the three dependencies above.
-
-Guix is compatible with Nix, so it is possible to share the same store
-between both. To do so, you must pass @command{configure} not only the
-same @code{--with-store-dir} value, but also the same
-@code{--localstatedir} value. The latter is essential because it
-specifies where the database that stores metadata about the store is
-located, among other things. The default values for Nix are
-@code{--with-store-dir=/nix/store} and @code{--localstatedir=/nix/var}.
-Note that @code{--disable-daemon} is not required if
-your goal is to share the store with Nix.
-
@node Running the Test Suite
@section Running the Test Suite
This means that substitutes may be downloaded from @var{urls}, as long
as they are signed by a trusted signature (@pxref{Substitutes}).
-@cindex build hook
-@item --no-build-hook
-Do not use the @dfn{build hook}.
-
-The build hook is a helper program that the daemon can start and to
-which it submits build requests. This mechanism is used to offload
-builds to other machines (@pxref{Daemon Offload Setup}).
+@cindex offloading
+@item --no-offload
+Do not use offload builds to other machines (@pxref{Daemon Offload
+Setup}). That is, always build things locally instead of offloading
+builds to remote machines.
@item --cache-failures
Cache build failures. By default, only successful builds are cached.
After installing fonts you may have to refresh the font cache to use
them in applications. The same applies when applications installed via
Guix do not seem to find fonts. To force rebuilding of the font cache
-run @code{fc-cache -f}. The @code{fc-cache} command is provided by the
-@code{fontconfig} package.
+run @code{fc-cache -rv}. The @code{fc-cache} command is provided by
+the @code{fontconfig} package.
@subsection X.509 Certificates
wrapper to refuse to link against libraries not in the store by setting the
@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
+@node Upgrading Guix
+@section Upgrading Guix
+
+@cindex Upgrading Guix, on a foreign distro
+
+To upgrade Guix, run:
+
+@example
+guix pull
+@end example
+
+@xref{Invoking guix pull}, for more information.
+
+@cindex upgrading Guix for the root user, on a foreign distro
+@cindex upgrading the Guix daemon, on a foreign distro
+@cindex @command{guix pull} for the root user, on a foreign distro
+
+On a foreign distro, you can upgrade the build daemon by running:
+
+@example
+sudo -i guix pull
+@end example
+
+@noindent
+followed by (assuming your distro uses the systemd service management
+tool):
+
+@example
+systemctl restart guix-daemon.service
+@end example
+
+On Guix System, upgrading the daemon is achieved by reconfiguring the
+system (@pxref{Invoking guix system, @code{guix system reconfigure}}).
+
@c TODO What else?
@c *********************************************************************
@dots{} or, using the GNU/Linux-specific @command{ip} command:
@example
-ip a
+ip address
@end example
@c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
ifconfig @var{interface} up
@end example
+@noindent
+@dots{} or, using the GNU/Linux-specific @command{ip} command:
+
+@example
+ip link set @var{interface} up
+@end example
+
@item Wireless connection
@cindex wireless
@cindex WiFi
qcow2-formatted disk image, use the @command{qemu-img} command:
@example
-qemu-img create -f qcow2 guixsd.img 50G
+qemu-img create -f qcow2 guix-system.img 50G
@end example
The resulting file will be much smaller than 50 GB (typically less than
@example
qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
- -net user -net nic,model=virtio -boot menu=on \
- -drive file=guix-system-install-@value{VERSION}.@var{system}.iso \
- -drive file=guixsd.img
+ -net user -net nic,model=virtio -boot menu=on,order=d \
+ -drive file=guix-system.img \
+ -drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso
@end example
-The ordering of the drives matters. @code{-enable-kvm} is optional, but
-significantly improves performance, @pxref{Running Guix in a VM}.
-
-In the VM console, quickly press the @kbd{F12} key to enter the boot
-menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your
-selection.
+@code{-enable-kvm} is optional, but significantly improves performance,
+@pxref{Running Guix in a VM}.
@item
You're now root in the VM, proceed with the installation process.
@end enumerate
Once installation is complete, you can boot the system that's on your
-@file{guixsd.img} image. @xref{Running Guix in a VM}, for how to do
+@file{guix-system.img} image. @xref{Running Guix in a VM}, for how to do
that.
@node Building the Installation Image
* Invoking guix gc:: Running the garbage collector.
* Invoking guix pull:: Fetching the latest Guix and distribution.
* Channels:: Customizing the package collection.
+* Invoking guix time-machine:: Running an older revision of Guix.
* Inferiors:: Interacting with another revision of Guix.
* Invoking guix describe:: Display information about your Guix revision.
* Invoking guix archive:: Exporting and importing store files.
@item
@command{guix remove} is an alias for @command{guix package -r},
@item
-and @command{guix upgrade} is an alias for @command{guix package -u}.
+@command{guix upgrade} is an alias for @command{guix package -u},
+@item
+and @command{guix show} is an alias for @command{guix package --show=}.
@end itemize
These aliases are less expressive than @command{guix package} and provide
(@pxref{Defining Packages}):
@lisp
-@verbatiminclude package-hello.scm
+@include package-hello.scm
@end lisp
Developers may find it useful to include such a @file{guix.scm} file
@cindex profile declaration
@cindex profile manifest
Create a new generation of the profile from the manifest object
-returned by the Scheme code in @var{file}.
+returned by the Scheme code in @var{file}. This option can be repeated
+several times, in which case the manifests are concatenated.
This allows you to @emph{declare} the profile's contents rather than
constructing it through a sequence of @code{--install} and similar
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
+@var{profile} must be the name of a file that will be created upon
+completion. Concretely, @var{profile} will be a mere symbolic link
+(``symlink'') pointing to the actual profile where packages are
+installed:
+
+@example
+$ guix install hello -p ~/code/my-profile
+@dots{}
+$ ~/code/my-profile/bin/hello
+Hello, world!
+@end example
+
+All it takes to get rid of the profile is to remove this symlink and its
+siblings that point to specific generations:
+
+@example
+$ rm ~/code/my-profile ~/code/my-profile-*-link
+@end example
+
+@item --list-profiles
+List all the user's profiles:
+
+@example
+$ guix package --list-profiles
+/home/charlie/.guix-profile
+/home/charlie/code/my-profile
+/home/charlie/code/devel-profile
+/home/charlie/tmp/test
+@end example
+
+When running as root, list all the profiles of all the users.
+
@cindex collisions, in a profile
@cindex colliding packages in profiles
@cindex profile collisions
@end example
You may also specify the full name of a package to only get details about a
-specific version of it:
+specific version of it (this time using the @command{guix show} alias):
@example
-$ guix package --show=python@@3.4 | recsel -p name,version
+$ guix show python@@3.4 | recsel -p name,version
name: python
version: 3.4.3
@end example
@uref{https://git-scm.com, Git} repository, by default the official
GNU@tie{}Guix repository, though this can be customized.
+Specifically, @command{guix pull} downloads code from the @dfn{channels}
+(@pxref{Channels}) specified by one of the followings, in this order:
+
+@enumerate
+@item
+the @option{--channels} option;
+@item
+the user's @file{~/.config/guix/channels.scm} file;
+@item
+the system-wide @file{/etc/guix/channels.scm} file;
+@item
+the built-in default channels specified in the @code{%default-channels}
+variable.
+@end enumerate
+
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
@xref{Invoking guix describe, @command{guix describe}}, for other ways to
describe the current status of Guix.
-This @code{~/.config/guix/current} profile works like any other profile
-created by @command{guix package} (@pxref{Invoking guix package}). That
+This @code{~/.config/guix/current} profile works exactly like the profiles
+created by @command{guix package} (@pxref{Invoking guix package}). That
is, you can list generations, roll back to the previous
generation---i.e., the previous Guix---and so on:
+@example
+$ guix pull --roll-back
+switched from generation 3 to 2
+$ guix pull --delete-generations=1
+deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
+@end example
+
+You can also use @command{guix package} (@pxref{Invoking guix package})
+to manage the profile by naming it explicitly:
@example
$ guix package -p ~/.config/guix/current --roll-back
switched from generation 3 to 2
@item --channels=@var{file}
@itemx -C @var{file}
Read the list of channels from @var{file} instead of
-@file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code that
+@file{~/.config/guix/channels.scm} or @file{/etc/guix/channels.scm}.
+@var{file} must contain Scheme code that
evaluates to a list of channel objects. @xref{Channels}, for more
information.
+@cindex channel news
@item --news
@itemx -N
-Display the list of packages added or upgraded since the previous generation.
+Display the list of packages added or upgraded since the previous
+generation, as well as, occasionally, news written by channel authors
+for their users (@pxref{Channels, Writing Channel News}).
-This is the same information as displayed upon @command{guix pull} completion,
-but without ellipses; it is also similar to the output of @command{guix pull
--l} for the last generation (see below).
+The package information is the same as displayed upon @command{guix
+pull} completion, but without ellipses; it is also similar to the output
+of @command{guix pull -l} for the last generation (see below).
@item --list-generations[=@var{pattern}]
@itemx -l [@var{pattern}]
The syntax of @var{pattern} is the same as with @code{guix package
--list-generations} (@pxref{Invoking guix package}).
+@item --roll-back
+@cindex rolling back
+@cindex undoing transactions
+@cindex transactions, undoing
+Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e.,
+undo the last transaction.
+
+@item --switch-generation=@var{pattern}
+@itemx -S @var{pattern}
+@cindex generations
+Switch to a particular generation defined by @var{pattern}.
+
+@var{pattern} may be either a generation number or a number prefixed
+with ``+'' or ``-''. The latter means: move forward/backward by a
+specified number of generations. For example, if you want to return to
+the latest generation after @code{--roll-back}, use
+@code{--switch-generation=+1}.
+
+@item --delete-generations[=@var{pattern}]
+@itemx -d [@var{pattern}]
+When @var{pattern} is omitted, delete all generations except the current
+one.
+
+This command accepts the same patterns as @option{--list-generations}.
+When @var{pattern} is specified, delete the matching generations. When
+@var{pattern} specifies a duration, generations @emph{older} than the
+specified duration match. For instance, @code{--delete-generations=1m}
+deletes generations that are more than one month old.
+
+If the current generation matches, it is @emph{not} deleted.
+
+Note that deleting generations prevents rolling back to them.
+Consequently, this command must be used with care.
+
@xref{Invoking guix describe}, for a way to display information about the
current generation only.
(directory "guix"))
@end lisp
+@cindex news, for channels
+@subsection Writing Channel News
+
+Channel authors may occasionally want to communicate to their users
+information about important changes in the channel. You'd send them all
+an email, but that's not convenient.
+
+Instead, channels can provide a @dfn{news file}; when the channel users
+run @command{guix pull}, that news file is automatically read and
+@command{guix pull --news} can display the announcements that correspond
+to the new commits that have been pulled, if any.
+
+To do that, channel authors must first declare the name of the news file
+in their @file{.guix-channel} file:
+
+@lisp
+(channel
+ (version 0)
+ (news-file "etc/news.txt"))
+@end lisp
+
+The news file itself, @file{etc/news.txt} in this example, must look
+something like this:
+
+@lisp
+(channel-news
+ (version 0)
+ (entry (tag "the-bug-fix")
+ (title (en "Fixed terrible bug")
+ (fr "Oh la la"))
+ (body (en "@@emph@{Good news@}! It's fixed!")
+ (eo "Certe ĝi pli bone funkcias nun!")))
+ (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
+ (title (en "Added a great package")
+ (ca "Què vol dir guix?"))
+ (body (en "Don't miss the @@code@{hello@} package!"))))
+@end lisp
+
+The file consists of a list of @dfn{news entries}. Each entry is
+associated with a commit or tag: it describes changes made in this
+commit, possibly in preceding commits as well. Users see entries only
+the first time they obtain the commit the entry refers to.
+
+The @code{title} field should be a one-line summary while @code{body}
+can be arbitrarily long, and both can contain Texinfo markup
+(@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are
+a list of language tag/message tuples, which allows @command{guix pull}
+to display news in the language that corresponds to the user's locale.
+
+If you want to translate news using a gettext-based workflow, you can
+extract translatable strings with @command{xgettext} (@pxref{xgettext
+Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming
+you write news entries in English first, the command below creates a PO
+file containing the strings to translate:
+
+@example
+xgettext -o news.po -l scheme -ken etc/news.scm
+@end example
+
+To sum up, yes, you could use your channel as a blog. But beware, this
+is @emph{not quite} what your users might expect.
+
@subsection Replicating Guix
@cindex pinning, channels
@end lisp
The @command{guix describe --format=channels} command can even generate this
-list of channels directly (@pxref{Invoking guix describe}).
+list of channels directly (@pxref{Invoking guix describe}). The resulting
+file can be used with the -C options of @command{guix pull}
+(@pxref{Invoking guix pull}) or @command{guix time-machine}
+(@pxref{Invoking guix time-machine}).
At this point the two machines run the @emph{exact same Guix}, with access to
the @emph{exact same packages}. The output of @command{guix build gimp} on
will---some sort of ``meta reproducibility'' capabilities, if you will.
@xref{Inferiors}, for another way to take advantage of these super powers.
+@node Invoking guix time-machine
+@section Invoking @command{guix time-machine}
+
+@cindex @command{guix time-machine}
+@cindex pinning, channels
+@cindex replicating Guix
+@cindex reproducibility, of Guix
+
+The @command{guix time-machine} command provides access to other
+revisions of Guix, for example to install older versions of packages,
+or to reproduce a computation in an identical environment. The revision
+of Guix to be used is defined by a commit or by a channel
+description file created by @command{guix describe}
+(@pxref{Invoking guix describe}).
+
+The general syntax is:
+
+@example
+guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
+@end example
+
+where @var{command} and @var{arg}@dots{} are passed unmodified to the
+@command{guix} command if the specified revision. The @var{options} that define
+this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
+
+@table @code
+@item --url=@var{url}
+@itemx --commit=@var{commit}
+@itemx --branch=@var{branch}
+Use the @code{guix} channel from the specified @var{url}, at the
+given @var{commit} (a valid Git commit ID represented as a hexadecimal
+string), or @var{branch}.
+
+@item --channels=@var{file}
+@itemx -C @var{file}
+Read the list of channels from @var{file}. @var{file} must contain
+Scheme code that evaluates to a list of channel objects.
+@xref{Channels} for more information.
+@end table
+
+As for @command{guix pull}, the absence of any options means that the
+the latest commit on the master branch will be used. The command
+
+@example
+guix time-machine -- build hello
+@end example
+
+will thus build the package @code{hello} as defined in the master branch,
+which is in general a newer revison of Guix than you have installed.
+Time travel works in both directions!
+
+Note that @command{guix time-machine} can trigger builds of channels and
+their dependencies, and these are controlled by the standard build
+options (@pxref{Common Build Options}).
+
@node Inferiors
@section Inferiors
@item --manifest=@var{file}
@itemx -m @var{file}
Create an environment for the packages contained in the manifest object
-returned by the Scheme code in @var{file}.
+returned by the Scheme code in @var{file}. This option can be repeated
+several times, in which case the manifests are concatenated.
This is similar to the same-named option in @command{guix package}
(@pxref{profile-manifest, @option{--manifest}}) and uses the same
@item docker
This produces a tarball that follows the
@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
-Docker Image Specification}.
+Docker Image Specification}. The ``repository name'' as it appears in
+the output of the @command{docker images} command is computed from
+package names passed on the command line or in the manifest file.
@item squashfs
This produces a SquashFS image containing all the specified binaries and
@item --manifest=@var{file}
@itemx -m @var{file}
Use the packages contained in the manifest object returned by the Scheme
-code in @var{file}.
+code in @var{file}. This option can be repeated several times, in which
+case the manifests are concatenated.
This has a similar purpose as the same-named option in @command{guix
package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
One use case for this is the Guix self-contained binary tarball
(@pxref{Binary Installation}).
+@item --derivation
+@itemx -d
+Print the name of the derivation that builds the pack.
+
@item --bootstrap
Use the bootstrap binaries to build the pack. This option is only
useful to Guix developers.
The list of systems supported by the package, as strings of the form
@code{architecture-kernel}, for example @code{"x86_64-linux"}.
-@item @code{maintainers} (default: @code{'()})
-The list of maintainers of the package, as @code{maintainer} objects.
-
@item @code{location} (default: source location of the @code{package} form)
The source location of the package. It is useful to override this when
inheriting from another package, in which case this field is not
For packages requiring shared library dependencies, you may need to write the
@file{/deps/deps.jl} file manually. It's usually a line of @code{const
-variable = /gnu/store/libary.so} for each dependency, plus a void function
+variable = /gnu/store/library.so} for each dependency, plus a void function
@code{check_deps() = nothing}.
Some older packages that aren't using @file{Package.toml} yet, will require
the package.
Additional flags to be passed to @code{scons} can be specified with the
-@code{#:scons-flags} parameter. The version of Python used to run SCons
-can be specified by selecting the appropriate SCons package with the
-@code{#:scons} parameter.
+@code{#:scons-flags} parameter. The default build and install targets
+can be overridden with @code{#:build-targets} and
+@code{#:install-targets} respectively. The version of Python used to
+run SCons can be specified by selecting the appropriate SCons package
+with the @code{#:scons} parameter.
@end defvr
@defvr {Scheme Variable} haskell-build-system
@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
[#:recursive? #f] [#:select? (const #t)]
-Return an object representing local file @var{file} to add to the store; this
-object can be used in a gexp. If @var{file} is a relative file name, it is looked
-up relative to the source file where this form appears. @var{file} will be added to
-the store under @var{name}--by default the base name of @var{file}.
+Return an object representing local file @var{file} to add to the store;
+this object can be used in a gexp. If @var{file} is a literal string
+denoting a relative file name, it is looked up relative to the source
+file where it appears; if @var{file} is not a literal string, it is
+looked up relative to the current working directory at run time.
+@var{file} will be added to the store under @var{name}--by default the
+base name of @var{file}.
When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
designates a flat file and @var{recursive?} is true, its contents are added, and its
@xref{Debugging Build Failures}, for tips and tricks on how to debug
build issues.
-This option has no effect when connecting to a remote daemon with a
-@code{guix://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET}
-variable}).
+This option implies @option{--no-offload}, and it has no effect when
+connecting to a remote daemon with a @code{guix://} URI (@pxref{The
+Store, the @code{GUIX_DAEMON_SOCKET} variable}).
@item --keep-going
@itemx -k
(@pxref{Invoking guix archive}), then rebuilding, and finally comparing
the two results.
-@item --no-build-hook
-Do not attempt to offload builds @i{via} the ``build hook'' of the daemon
-(@pxref{Daemon Offload Setup}). That is, always build things locally
-instead of offloading builds to remote machines.
+@item --no-offload
+Do not use offload builds to other machines (@pxref{Daemon Offload
+Setup}). That is, always build things locally instead of offloading
+builds to remote machines.
@item --max-silent-time=@var{seconds}
When the build or substitution process remains silent for more than
(@pxref{Defining Packages}):
@lisp
-@verbatiminclude package-hello.scm
+@include package-hello.scm
@end lisp
@item --expression=@var{expr}
code snippets specified in the package @code{origin} (@pxref{Defining
Packages}).
+Note that @command{guix build -S} compiles the sources only of the
+specified packages. They do not include the sources of statically
+linked dependencies and by themselves are insufficient for reproducing
+the packages.
+
@item --sources
Fetch and return the source of @var{package-or-derivation} and all their
dependencies, recursively. This is a handy way to obtain a local copy
@item crate
@cindex crate
Import metadata from the crates.io Rust package repository
-@uref{https://crates.io, crates.io}.
+@uref{https://crates.io, crates.io}, as in this example:
+
+@example
+guix import crate blake2-rfc
+@end example
+
+The crate importer also allows you to specify a version string:
+
+@example
+guix import crate constant-time-eq@@0.1.0
+@end example
+
+Additional options include:
+
+@table @code
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
+@end table
@item opam
@cindex OPAM
@cindex CVE, Common Vulnerabilities and Exposures
Report known vulnerabilities found in the Common Vulnerabilities and
Exposures (CVE) databases of the current and past year
-@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US
+@uref{https://nvd.nist.gov/vuln/data-feeds, published by the US
NIST}.
To view information about a particular vulnerability, visit pages such as:
@code{CVE-2015-7554}.
Package developers can specify in package recipes the
-@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)}
+@uref{https://nvd.nist.gov/products/cpe,Common Platform Enumeration (CPE)}
name and version of the package when they differ from the name or version
that Guix uses, as in this example:
;; @dots{}
;; CPE calls this package "grub2".
(properties '((cpe-name . "grub2")
- (cpe-version . "2.3")))
+ (cpe-version . "2.3"))))
@end lisp
@c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
are some architecture-dependent bits that this option allows you to visualize.
@end table
+On top of that, @command{guix graph} supports all the usual package
+transformation options (@pxref{Package Transformation Options}). This
+makes it easy to view the effect of a graph-rewriting transformation
+such as @option{--with-input}. For example, the command below outputs
+the graph of @code{git} once @code{openssl} has been replaced by
+@code{libressl} everywhere in the graph:
+
+@example
+guix graph git --with-input=openssl=libressl
+@end example
+So many possibilities, so much fun!
@node Invoking guix publish
@section Invoking @command{guix publish}
@code{guix-publish-service-type}}).
If you are instead running Guix on a ``foreign distro'', follow these
-instructions:”
+instructions:
@itemize
@item
ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
@end example
-
@node System Configuration
@chapter System Configuration
* Virtualization Services:: Virtualization services.
* Version Control Services:: Providing remote access to Git repositories.
* Game Services:: Game servers.
+* PAM Mount Service:: Service to mount volumes when logging in.
+* Guix Services:: Services relating specifically to Guix.
* Miscellaneous Services:: Other services.
@end menu
@lisp
(use-modules (guix download) ;for url-fetch
(guix packages) ;for origin
- ;; @dots{})
+ @dots{})
(define %android-udev-rules
(file->udev-rule
@lisp
(use-modules (gnu packages android) ;for android-udev-rules
(gnu system shadow) ;for user-group
- ;; @dots{})
+ @dots{})
(operating-system
;; @dots{}
;; @dots{}
(supplementary-groups
'("adbusers" ;for adb
- "wheel" "netdev" "audio" "video"))
- ;; @dots{})))
+ "wheel" "netdev" "audio" "video")))))
(groups (cons (user-group (system? #t) (name "adbusers"))
%base-groups))
@end table
@end deftp
+@cindex nftables
+@defvr {Scheme Variable} nftables-service-type
+This is the service type to set up a nftables configuration. nftables is a
+netfilter project that aims to replace the existing iptables, ip6tables,
+arptables and ebtables framework. It provides a new packet filtering
+framework, a new user-space utility @command{nft}, and a compatibility layer
+for iptables. This service comes with a default ruleset
+@code{%default-nftables-ruleset} that rejecting all incomming connections
+except those to the ssh port 22. To use it, simply write:
+
+@lisp
+(service nftables-service-type)
+@end lisp
+@end defvr
+
+@deftp {Data Type} nftables-configuration
+The data type representing the configuration of nftables.
+
+@table @asis
+@item @code{package} (default: @code{nftables})
+The nftables package that provides @command{nft}.
+@item @code{ruleset} (default: @code{%default-nftables-ruleset})
+The nftables ruleset to use. This may be any ``file-like'' object
+(@pxref{G-Expressions, file-like objects}).
+@end table
+@end deftp
+
@cindex NTP (Network Time Protocol), service
+@cindex ntpd, service for the Network Time Protocol daemon
@cindex real time clock
@defvr {Scheme Variable} ntp-service-type
This is the type of the service running the @uref{http://www.ntp.org,
@table @asis
@item @code{servers} (default: @code{%ntp-servers})
-This is the list of servers (host names) with which @command{ntpd} will be
-synchronized.
+This is the list of servers (@code{<ntp-server>} records) with which
+@command{ntpd} will be synchronized. See the @code{ntp-server} data type
+definition below.
-@item @code{allow-large-adjustment?} (default: @code{#f})
+@item @code{allow-large-adjustment?} (default: @code{#t})
This determines whether @command{ntpd} is allowed to make an initial
adjustment of more than 1,000 seconds.
@uref{https://www.ntppool.org/en/, NTP Pool Project}.
@end defvr
+@deftp {Data Type} ntp-server
+The data type representing the configuration of a NTP server.
+
+@table @asis
+@item @code{type} (default: @code{'server})
+The type of the NTP server, given as a symbol. One of @code{'pool},
+@code{'server}, @code{'peer}, @code{'broadcast} or @code{'manycastclient}.
+
+@item @code{address}
+The address of the server, as a string.
+
+@item @code{options}
+NTPD options to use with that specific server, given as a list of option names
+and/or of option names and values tuples. The following example define a server
+to use with the options @option{iburst} and @option{prefer}, as well as
+@option{version} 3 and a @option{maxpoll} time of 16 seconds.
+
+@example
+(ntp-server
+ (type 'server)
+ (address "some.ntp.server.org")
+ (options `(iburst (version 3) (maxpoll 16) prefer))))
+@end example
+@end table
+@end deftp
+
@cindex OpenNTPD
@deffn {Scheme Procedure} openntpd-service-type
Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
@end lisp
@end deffn
+@defvr {Scheme Variable} %openntpd-servers
+This variable is a list of the server addresses defined in
+@var{%ntp-servers}.
+@end defvr
+
@deftp {Data Type} openntpd-configuration
@table @asis
@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
will listen to each sensor that actually exists and ignore non-existent ones.
See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
information.
-@item @code{server} (default: @var{%ntp-servers})
+@item @code{server} (default: @code{'()})
Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
-@item @code{servers} (default: @code{'()})
+@item @code{servers} (default: @var{%openntp-servers})
Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
@item @code{constraint-from} (default: @code{'()})
@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
(program (file-append openssh "/bin/ssh"))
(arguments
'("ssh" "-qT" "-i" "/path/to/ssh_key"
- "-W" "smtp-server:25" "user@@hostname")))))
+ "-W" "smtp-server:25" "user@@hostname")))))))
@end lisp
See below for more details about @code{inetd-configuration}.
@end table
@end deftp
+@defvr {Scheme Variable} pagekite-service-type
+This is the service type for the @uref{https://pagekite.net, PageKite} service,
+a tunneling solution for making localhost servers publicly visible, even from
+behind NAT or restrictive firewalls. The value for this service type is a
+@code{pagekite-configuration} record.
+
+Here's an example exposing the local HTTP and SSH daemons:
+
+@lisp
+(service pagekite-service-type
+ (pagekite-configuration
+ (kites '("http:@@kitename:localhost:80:@@kitesecret"
+ "raw/22:@@kitename:localhost:22:@@kitesecret"))
+ (extra-file "/etc/pagekite.rc")))
+@end lisp
+@end defvr
+
+@deftp {Data Type} pagekite-configuration
+Data type representing the configuration of PageKite.
+
+@table @asis
+@item @code{package} (default: @var{pagekite})
+Package object of PageKite.
+
+@item @code{kitename} (default: @code{#f})
+PageKite name for authenticating to the frontend server.
+
+@item @code{kitesecret} (default: @code{#f})
+Shared secret for authenticating to the frontend server. You should probably
+put this inside @code{extra-file} instead.
+
+@item @code{frontend} (default: @code{#f})
+Connect to the named PageKite frontend server instead of the
+@uref{https://pagekite.net,,pagekite.net} service.
+
+@item @code{kites} (default: @code{'("http:@@kitename:localhost:80:@@kitesecret")})
+List of service kites to use. Exposes HTTP on port 80 by default. The format
+is @code{proto:kitename:host:port:secret}.
+
+@item @code{extra-file} (default: @code{#f})
+Extra configuration file to read, which you are expected to create manually.
+Use this to add additional options and manage shared secrets out-of-band.
+
+@end table
+@end deftp
+
@node X Window
@subsection X Window
When @code{auto-login?} is true, GDM logs in directly as
@code{default-user}.
+@item @code{debug?} (default: @code{#f})
+When true, GDM writes debug messages to its log.
+
@item @code{gnome-shell-assets} (default: ...)
List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.
@cindex login manager
@cindex X11 login
-@deffn {Scheme Procedure} sddm-service config
-Return a service that spawns the SDDM graphical login manager for config of
-type @code{<sddm-configuration>}.
+@defvr {Scheme Variable} sddm-service-type
+This is the type of the service to run the
+@uref{https://github.com/sddm/sddm,SSDM display manager}. Its value
+must be a @code{sddm-configuration} record (see below).
-@example
- (sddm-service (sddm-configuration
- (auto-login-user "Alice")
- (auto-login-session "xfce.desktop")))
-@end example
-@end deffn
+Here's an example use:
+
+@lisp
+(service sddm-service-type
+ (sddm-configuration
+ (auto-login-user "alice")
+ (auto-login-session "xfce.desktop")))
+@end lisp
+@end defvr
+
+@deftp {Data Type} sddm-configuration
+This data type represents the configuration of the SDDM login manager.
+The available fields are:
+
+@table @asis
+@item @code{sddm} (default: @code{sddm})
+The SDDM package to use.
+
+@item @code{display-server} (default: @code{"x11"})
+This must be either @code{"x11"} or @code{"wayland"}.
+
+@c FIXME: Add more fields.
+
+@item @code{auto-login-user} (default: @code{""})
+If non-empty, this is the user account under which to log in
+automatically.
+
+@item @code{auto-login-session} (default: @code{""})
+If non-empty, this is the @file{.desktop} file name to use as the
+auto-login session.
+@end table
+@end deftp
@cindex Xorg, configuration
@deftp {Data Type} xorg-configuration
the capability to suspend the system if the user is logged in locally.
@end deffn
+@defvr {Scheme Variable} polkit-wheel-service
+Service that adds the @code{wheel} group as admins to the Polkit
+service. This makes it so that users in the @code{wheel} group are queried
+for their own passwords when performing administrative actions instead of
+@code{root}'s, similar to the behaviour used by @code{sudo}.
+@end defvr
+
@defvr {Scheme Variable} upower-service-type
Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
system-wide monitor for power consumption and battery levels, with the given
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
+@deffn {Scheme Variable} colord-service-type
+This is the type of the 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
screens and scanners. It is notably used by the GNOME Color Manager graphical
tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-after
Getmail will delete messages this number of days after seeing them, if
-they have not been delivered. This means messages will be left on the
+they have been delivered. This means messages will be left on the
server this number of days after delivering them. A value of @samp{0}
disabled this feature.
the configuration.
@lisp
-(simple-service 'my-extra-server httpd-service-type
+(simple-service 'www.example.com-server httpd-service-type
(list
(httpd-virtualhost
"*:80"
- (list (string-append
- "ServerName "www.example.com
- DocumentRoot \"/srv/http/www.example.com\"")))))
+ (list (string-join '("ServerName www.example.com"
+ "DocumentRoot /srv/http/www.example.com")
+ "\n")))))
@end lisp
@end deffn
These should be added to the extra-config for the httpd-service.
@lisp
-(simple-service 'my-extra-server httpd-service-type
+(simple-service 'www.example.com-server httpd-service-type
(list
(httpd-virtualhost
"*:80"
- (list (string-append
- "ServerName "www.example.com
- DocumentRoot \"/srv/http/www.example.com\"")))))
+ (list (string-join '("ServerName www.example.com"
+ "DocumentRoot /srv/http/www.example.com")
+ "\n")))))
@end lisp
@table @asis
@item @code{server-names-hash-bucket-max-size} (default: @code{#f})
Maximum bucket size for the server names hash tables.
+@item @code{modules} (default: @code{'()})
+List of nginx dynamic modules to load. This should be a list of file
+names of loadable modules, as in this example:
+
+@lisp
+(modules
+ (list
+ (file-append nginx-accept-language-module "\
+/etc/nginx/modules/ngx_http_accept_language_module.so")))
+@end lisp
+
@item @code{extra-content} (default: @code{""})
Extra content for the @code{http} block. Should be string or a string
valued G-expression.
@lisp
(define %gnu-mirror
- (plain-file
- "gnu.vcl"
- "vcl 4.1;
-backend gnu @{ .host = "www.gnu.org"; @}"))
+ (plain-file "gnu.vcl"
+ "vcl 4.1;
+backend gnu @{ .host = \"www.gnu.org\"; @}"))
(operating-system
- ...
+ ;; @dots{}
(services (cons (service varnish-service-type
(varnish-configuration
(listen '(":80"))
It is possible to configure a FastCGI-backed web service to pass HTTP
authentication information from the front-end to the back-end, and to
allow @code{fcgiwrap} to run the back-end process as a corresponding
-local user. To enable this capability on the back-end., run
+local user. To enable this capability on the back-end, run
@code{fcgiwrap} as the @code{root} user and group. Note that this
capability also has to be configured on the front-end as well.
@end table
Group of the worker processes.
@item @code{socket-user} (default: @code{php-fpm})
User who can speak to the php-fpm socket.
-@item @code{socket-group} (default: @code{php-fpm})
+@item @code{socket-group} (default: @code{nginx})
Group that can speak to the php-fpm socket.
@item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
The process id of the php-fpm process is written to this file
Log for the php-fpm master process.
@item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
Detailed settings for the php-fpm process manager.
-Must be either:
+Must be one of:
@table @asis
@item @code{<php-fpm-dynamic-process-manager-configuration>}
@item @code{<php-fpm-static-process-manager-configuration>}
(server-name '("example.com"))
(root "/srv/http/")
(locations
- (list (nginx-php-location)))
+ (list (nginx-php-fpm-location)))
(listen '("80"))
(ssl-certificate #f)
(ssl-certificate-key #f)))
The challenge type that has to be run by certbot. If @code{#f} is specified,
default to the HTTP challenge. If a value is specified, defaults to the
manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and
-the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}).
+the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}),
+and gives Let's Encrypt permission to log the public IP address of the
+requesting machine.
@item @code{authentication-hook} (default: @code{#f})
Command to be run in a shell once for each certificate challenge to be
@end table
@end deftp
+@subsubheading Knot Resolver Service
+
+@deffn {Scheme Variable} knot-resolver-service-type
+This this the type of the knot resolver service, whose value should be
+an @code{knot-resolver-configuration} object as in this example:
+
+@lisp
+(service knot-resolver-service-type
+ (knot-resolver-configuration
+ (kresd-config-file (plain-file "kresd.conf" "
+net.listen('192.168.0.1', 5353)
+user('knot-resolver', 'knot-resolver')
+modules = @{ 'hints > iterate', 'stats', 'predict' @}
+cache.size = 100 * MB
+"))))
+@end lisp
+
+For more information, refer its @url{https://knot-resolver.readthedocs.org/en/stable/daemon.html#configuration, manual}.
+@end deffn
+
+@deftp {Data Type} knot-resolver-configuration
+Data type representing the configuration of knot-resolver.
+
+@table @asis
+@item @code{package} (default: @var{knot-resolver})
+Package object of the knot DNS resolver.
+
+@item @code{kresd-config-file} (default: %kresd.conf)
+File-like object of the kresd configuration file to use, by default it
+will listen on @code{127.0.0.1} and @code{::1}.
+
+@item @code{garbage-collection-interval} (default: 1000)
+Number of milliseconds for @code{kres-cache-gc} to periodically trim the cache.
+
+@end table
+@end deftp
+
+
@subsubheading Dnsmasq Service
@deffn {Scheme Variable} dnsmasq-service-type
The address that mpd will bind to. To use a Unix domain socket,
an absolute path can be specified here.
+@item @code{outputs} (default: @code{"(list (mpd-output))"})
+The audio outputs that MPD can use. By default this is a single output using pulseaudio.
+
@end table
@end deftp
+@deftp {Data Type} mpd-output
+Data type representing an @command{mpd} audio output.
+
+@table @asis
+@item @code{name} (default: @code{"MPD"})
+The name of the audio output.
+
+@item @code{type} (default: @code{"pulse"})
+The type of audio output.
+
+@item @code{enabled?} (default: @code{#t})
+Specifies whether this audio output is enabled when MPD is started. By
+default, all audio outputs are enabled. This is just the default
+setting when there is no state file; with a state file, the previous
+state is restored.
+
+@item @code{tags?} (default: @code{#t})
+If set to @code{#f}, then MPD will not send tags to this output. This
+is only useful for output plugins that can receive tags, for example the
+@code{httpd} output plugin.
+
+@item @code{always-on?} (default: @code{#f})
+If set to @code{#t}, then MPD attempts to keep this audio output always
+open. This may be useful for streaming servers, when you don’t want to
+disconnect all listeners even when playback is accidentally stopped.
+
+@item @code{mixer-type}
+This field accepts a symbol that specifies which mixer should be used
+for this audio output: the @code{hardware} mixer, the @code{software}
+mixer, the @code{null} mixer (allows setting the volume, but with no
+effect; this can be used as a trick to implement an external mixer
+External Mixer) or no mixer (@code{none}).
+
+@item @code{extra-options} (default: @code{'()"})
+An association list of option symbols to string values to be appended to
+the audio output configuration.
+
+@end table
+@end deftp
+
+The following example shows a configuration of @code{mpd} that provides
+an HTTP audio streaming output.
+
+@lisp
+(service mpd-service-type
+ (mpd-configuration
+ (outputs
+ (list (mpd-output
+ (name "streaming")
+ (type "httpd")
+ (mixer-type 'null)
+ (extra-options
+ `((encoder . "vorbis")
+ (port . "8080"))))))))
+@end lisp
+
+
@node Virtualization Services
@subsection Virtualization services
@end table
@end deftp
+
+@node PAM Mount Service
+@subsection PAM Mount Service
+@cindex pam-mount
+
+The @code{(gnu services pam-mount)} module provides a service allowing
+users to mount volumes when they log in. It should be able to mount any
+volume format supported by the system.
+
+@defvar {Scheme Variable} pam-mount-service-type
+Service type for PAM Mount support.
+@end defvar
+
+@deftp {Data Type} pam-mount-configuration
+Data type representing the configuration of PAM Mount.
+
+It takes the following parameters:
+
+@table @asis
+@item @code{rules}
+The configuration rules that will be used to generate
+@file{/etc/security/pam_mount.conf.xml}.
+
+The configuration rules are SXML elements (@pxref{SXML,,, guile, GNU
+Guile Reference Manual}), and the the default ones don't mount anything
+for anyone at login:
+
+@lisp
+`((debug (@@ (enable "0")))
+ (mntoptions (@@ (allow ,(string-join
+ '("nosuid" "nodev" "loop"
+ "encryption" "fsck" "nonempty"
+ "allow_root" "allow_other")
+ ","))))
+ (mntoptions (@@ (require "nosuid,nodev")))
+ (logout (@@ (wait "0")
+ (hup "0")
+ (term "no")
+ (kill "no")))
+ (mkmountpoint (@@ (enable "1")
+ (remove "true"))))
+@end lisp
+
+Some @code{volume} elements must be added to automatically mount volumes
+at login. Here's an example allowing the user @code{alice} to mount her
+encrypted @code{HOME} directory and allowing the user @code{bob} to mount
+the partition where he stores his data:
+
+@lisp
+(define pam-mount-rules
+`((debug (@@ (enable "0")))
+ (volume (@@ (user "alice")
+ (fstype "crypt")
+ (path "/dev/sda2")
+ (mountpoint "/home/alice")))
+ (volume (@@ (user "bob")
+ (fstype "auto")
+ (path "/dev/sdb3")
+ (mountpoint "/home/bob/data")
+ (options "defaults,autodefrag,compress")))
+ (mntoptions (@@ (allow ,(string-join
+ '("nosuid" "nodev" "loop"
+ "encryption" "fsck" "nonempty"
+ "allow_root" "allow_other")
+ ","))))
+ (mntoptions (@@ (require "nosuid,nodev")))
+ (logout (@@ (wait "0")
+ (hup "0")
+ (term "no")
+ (kill "no")))
+ (mkmountpoint (@@ (enable "1")
+ (remove "true")))))
+
+(service pam-mount-service-type
+ (pam-mount-configuration
+ (rules pam-mount-rules)))
+@end lisp
+
+The complete list of possible options can be found in the man page for
+@uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html, pam_mount.conf}.
+@end table
+@end deftp
+
+
+@node Guix Services
+@subsection Guix Services
+
+@subsubheading Guix Data Service
+The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores
+and provides data about GNU Guix. This includes information about
+packages, derivations and lint warnings.
+
+The data is stored in a PostgreSQL database, and available through a web
+interface.
+
+@defvar {Scheme Variable} guix-data-service-type
+Service type for the Guix Data Service. Its value must be a
+@code{guix-data-service-configuration} object. The service optionally
+extends the getmail service, as the guix-commits mailing list is used to
+find out about changes in the Guix git repository.
+@end defvar
+
+@deftp {Data Type} guix-data-service-configuration
+Data type representing the configuration of the Guix Data Service.
+
+@table @asis
+@item @code{package} (default: @code{guix-data-service})
+The Guix Data Service package to use.
+
+@item @code{user} (default: @code{"guix-data-service"})
+The system user to run the service as.
+
+@item @code{group} (default: @code{"guix-data-service"})
+The system group to run the service as.
+
+@item @code{port} (default: @code{8765})
+The port to bind the web service to.
+
+@item @code{host} (default: @code{"127.0.0.1"})
+The host to bind the web service to.
+
+@item @code{getmail-idle-mailboxes} (default: @code{#f})
+If set, this is the list of mailboxes that the getmail service will be
+configured to listen to.
+
+@item @code{commits-getmail-retriever-configuration} (default: @code{#f})
+If set, this is the @code{getmail-retriever-configuration} object with
+which to configure getmail to fetch mail from the guix-commits mailing
+list.
+
+@end table
+@end deftp
+
+
@node Miscellaneous Services
@subsection Miscellaneous Services
@item @code{device} (default: @code{"/dev/ttyS0"})
The device file to connect to the device.
+@item @code{baud-rate} (default: @code{#f})
+Baud rate to use for the serial connection.
+Should be a number or @code{#f}.
+
@item @code{log-file} (default: @code{#f})
If true, this must be the name of a file to log messages to.
@end table
@item @code{environment}
An @code{environment-type} describing how the machine should be provisioned.
-At the moment, the only supported value is
-@code{managed-host-environment-type}.
@item @code{configuration} (default: @code{#f})
An object describing the configuration for the machine's @code{environment}.
-If the @code{environment} has a default configuration, @code{#f} maybe used.
+If the @code{environment} has a default configuration, @code{#f} may be used.
If @code{#f} is used for an environment with no default configuration,
however, an error will be thrown.
@end table
@item @code{build-locally?} (default: @code{#t})
If false, system derivations will be built on the machine being deployed to.
@item @code{system}
-The Nix system type describing the architecture of the machine being deployed
-to. This should look something like ``x86_64-linux''.
+The system type describing the architecture of the machine being deployed
+to---e.g., @code{"x86_64-linux"}.
@item @code{authorize?} (default: @code{#t})
If true, the coordinator's signing key will be added to the remote's ACL
keyring.
@end table
@end deftp
+@deftp {Data Type} digital-ocean-configuration
+This is the data type describing the Droplet that should be created for a
+machine with an @code{environment} of @code{digital-ocean-environment-type}.
+
+@table @asis
+@item @code{ssh-key}
+The path to the SSH private key to use to authenticate with the remote
+host. In the future, this field may not exist.
+@item @code{tags}
+A list of string ``tags'' that uniquely identify the machine. Must be given
+such that no two machines in the deployment have the same set of tags.
+@item @code{region}
+A Digital Ocean region slug, such as @code{"nyc3"}.
+@item @code{size}
+A Digital Ocean size slug, such as @code{"s-1vcpu-1gb"}
+@item @code{enable-ipv6?}
+Whether or not the droplet should be created with IPv6 networking.
+@end table
+@end deftp
+
@node Running Guix in a VM
@section Running Guix in a Virtual Machine
These bootstrap binaries are ``taken for granted'', though we can also
re-create them if needed (more on that later).
-@unnumberedsec Preparing to Use the Bootstrap Binaries
+For @code{i686-linux} and @code{x86_64-linux} the Guix bootstrap process is
+more elaborate, @pxref{Reduced Binary Seed Bootstrap}.
+
+@menu
+* Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
+* Preparing to Use the Bootstrap Binaries:: Building that what matters most.
+@end menu
+
+@node Reduced Binary Seed Bootstrap
+@section The Reduced Binary Seed Bootstrap
+
+Guix---like other GNU/Linux distributions---is traditionally bootstrapped from
+a set of bootstrap binaries: Bourne shell, command-line tools provided by GNU
+Coreutils, Awk, Findutils, `sed', and `grep' and Guile, GCC, Binutils, and the
+GNU C Library (@pxref{Bootstrapping}). Usually, these bootstrap binaries are
+``taken for granted.''
+
+Taking these binaries for granted means that we consider them to be a correct
+and trustworthy `seed' for building the complete system. Therein lies a
+problem: the current combined size of these bootstrap binaries is about 250MB
+(@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditing or even inspecting
+these is next to impossible.
+
+For @code{i686-linux} and @code{x86_64-linux}, Guix now features a ``Reduced
+Binary Seed'' bootstrap @footnote{We would like to say: ``Full Source
+Bootstrap'' and while we are working towards that goal it would be hyperbole
+to use that term for what we do now.}.
+
+The Reduced Binary Seed bootstrap removes the most critical tools---from a
+trust perspective---from the bootstrap binaries: GCC, Binutils and the GNU C
+Library are replaced by: @code{bootstrap-mescc-tools} (a tiny assembler and
+linker) and @code{bootstrap-mes} (a small Scheme Interpreter and a C compiler
+written in Scheme and the Mes C Library, built for TinyCC and for GCC). Using
+these new binary seeds and a new set of
+@c
+packages@footnote{@c
+nyacc-boot,
+mes-boot,
+tcc-boot0,
+tcc-boot,
+make-mesboot0,
+diffutils-mesboot,
+binutils-mesboot0,
+gcc-core-mesboot,
+mesboot-headers,
+glibc-mesboot0,
+gcc-mesboot0,
+binutils-mesboot,
+make-mesboot,
+gcc-mesboot1,
+gcc-mesboot1-wrapper,
+glibc-headers-mesboot,
+glibc-mesboot,
+gcc-mesboot,
+and
+gcc-mesboot-wrapper.
+}
+@c
+the ``missing'' Binutils, GCC, and the GNU C Library are built from source.
+From here on the more traditional bootstrap process resumes. This approach
+has reduced the bootstrap binaries in size to about 130MB. Work is ongoing to
+reduce this further. If you are interested, join us on @code{#bootstrappable}
+on the Freenode IRC network.
+
+@c ./pre-inst-env guix graph --type=bag -e '(begin (use-modules (guix packages)) (%current-system "i686-linux") (@@ (gnu packages commencement) gcc-mesboot))' > doc/images/gcc-mesboot-bag-graph.dot
+@c dot -T png doc/images/gcc-mesboot-bag-graph.dot > doc/images/gcc-mesboot-bag-graph.png
+
+Below is the generated dependency graph for @code{gcc-mesboot}, the bootstrap
+compiler used to build the rest of GuixSD.
+
+@image{images/gcc-mesboot-bag-graph,6in,,Dependency graph of the gcc-mesboot}
+
+@node Preparing to Use the Bootstrap Binaries
+@section Preparing to Use the Bootstrap Binaries
@c As of Emacs 24.3, Info-mode displays the image, but since it's a
@c large image, it's hard to scroll. Oh well.
@example
guix graph -t derivation \
-e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
- | dot -Tps > t.ps
+ | dot -Tps > gcc.ps
+@end example
+
+or, for the Reduced Binary Seed bootstrap
+
+@example
+guix graph -t derivation \
+ -e '(@@@@ (gnu packages bootstrap) %bootstrap-mes)' \
+ | dot -Tps > mes.ps
@end example
At this level of detail, things are
corresponds to the @code{#:modules} argument of
@code{build-expression->derivation} (@pxref{Derivations}).
-Finally, the various tarballs are unpacked by the
-derivations @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv},
-etc., at which point we have a working C tool chain.
-
+Finally, the various tarballs are unpacked by the derivations
+@code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, or
+@code{bootstrap-mes-0.drv} and @code{bootstrap-mescc-tools-0.drv}, at which
+point we have a working C tool chain.
@unnumberedsec Building the Build Tools
automated way to produce them, should an update occur, and this is what
the @code{(gnu packages make-bootstrap)} module provides.
-The following command builds the tarballs containing the bootstrap
-binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture
-of Coreutils and other basic command-line tools):
+The following command builds the tarballs containing the bootstrap binaries
+(Binutils, GCC, glibc, for the traditional bootstrap and linux-libre-headers,
+bootstrap-mescc-tools, bootstrap-mes for the Reduced Binary Seed bootstrap,
+and Guile, and a tarball containing a mixture of Coreutils and other basic
+command-line tools):
@example
guix build bootstrap-tarballs
@unnumberedsec Reducing the Set of Bootstrap Binaries
-Our bootstrap binaries currently include GCC, Guile, etc. That's a lot
-of binary code! Why is that a problem? It's a problem because these
-big chunks of binary code are practically non-auditable, which makes it
-hard to establish what source code produced them. Every unauditable
-binary also leaves us vulnerable to compiler backdoors as described by
-Ken Thompson in the 1984 paper @emph{Reflections on Trusting Trust}.
+Our traditional bootstrap includes GCC, GNU Libc, Guile, etc. That's a lot of
+binary code! Why is that a problem? It's a problem because these big chunks
+of binary code are practically non-auditable, which makes it hard to establish
+what source code produced them. Every unauditable binary also leaves us
+vulnerable to compiler backdoors as described by Ken Thompson in the 1984
+paper @emph{Reflections on Trusting Trust}.
This is mitigated by the fact that our bootstrap binaries were generated
from an earlier Guix revision. Nevertheless it lacks the level of
on-going projects to do that. One of these is about replacing the
bootstrap GCC with a sequence of assemblers, interpreters, and compilers
of increasing complexity, which could be built from source starting from
-a simple and auditable assembler. Your help is welcome!
-
+a simple and auditable assembler.
+
+Our first major achievement is the replacement of of GCC, the GNU C Library
+and Binutils by MesCC-Tools (a simple hex linker and macro assembler) and Mes
+(@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, a Scheme interpreter
+and C compiler in Scheme). Neither MesCC-Tools nor Mes can be fully
+bootstrapped yet and thus we inject them as binary seeds. We call this the
+Reduced Binary Seed bootstrap, as it has halved the size of our bootstrap
+binaries! Also, it has eliminated the C compiler binary; i686-linux and
+x86_64-linux Guix packages are now bootstrapped without any binary C compiler.
+
+Work is ongoing to make MesCC-Tools and Mes fully bootstrappable and we are
+also looking at any other bootstrap binaries. Your help is welcome!
@node Porting
@chapter Porting to a New Platform
HCoop / jackhill / guix / guix.git / blobdiff