Copyright @copyright{} 2014 Pierre-Antoine Rault@*
Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@*
-Copyright @copyright{} 2015, 2016 Ricardo Wurmus@*
+Copyright @copyright{} 2015, 2016, 2017 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016 Chris Marusich@*
Copyright @copyright{} 2016, 2017 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
Copyright @copyright{} 2016 ng0@*
-Copyright @copyright{} 2016 Jan Nieuwenhuizen@*
+Copyright @copyright{} 2016, 2017 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2017 Clément Lassieur@*
Copyright @copyright{} 2017 Thomas Danckaert@*
Copyright @copyright{} 2017 humanitiesNerd@*
Copyright @copyright{} 2017 Christopher Allan Webber@*
-Copyright @copyright{} 2017 Marius Bakke
+Copyright @copyright{} 2017 Marius Bakke@*
+Copyright @copyright{} 2017 Hartmut Goebel@*
+Copyright @copyright{} 2017 Maxim Cournoyer@*
+Copyright @copyright{} 2017 Tobias Geerinckx-Rice
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
Defining Packages
-* package Reference:: The package data type.
+* package Reference :: The package data type.
* origin Reference:: The origin data type.
Utilities
* Invoking guix challenge:: Challenging substitute servers.
* Invoking guix copy:: Copying to and from a remote store.
* Invoking guix container:: Process isolation.
+* Invoking guix weather:: Assessing substitute availability.
Invoking @command{guix build}
* Common Build Options:: Build options for most commands.
* Package Transformation Options:: Creating variants of packages.
* Additional Build Options:: Options specific to 'guix build'.
+* Debugging Build Failures:: Real life packaging experience.
GNU Distribution
* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
-* GRUB Configuration:: Configuring the boot loader.
+* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
* Defining Services:: Adding new service definitions.
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
-* Database Services:: SQL databases.
+* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
+* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
* Web Services:: Web servers.
* DNS Services:: DNS daemons.
* Network File System:: NFS related services.
* Continuous Integration:: The Cuirass service.
* Power management Services:: The TLP tool.
+* Audio Services:: The MPD.
+* Virtualization Services:: Virtualization services.
* Miscellaneous Services:: Other services.
Defining Services
@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings
(@pxref{Guile Preparations, how to install the GnuTLS bindings for
Guile,, gnutls-guile, GnuTLS-Guile});
+@item
+@c FIXME: Specify a version number once a release has been made.
+@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August
+2017 or later;
@item @url{http://www.gnu.org/software/make/, GNU Make}.
@end itemize
@item @code{port} (default: @code{22})
Port number of SSH server on the machine.
-@item @code{private-key} (default: @file{~/.ssh/id_rsa})
+@item @code{private-key} (default: @file{~root/.ssh/id_rsa})
The SSH private key file to use when connecting to the machine, in
OpenSSH format.
+Note that the default value is the private key @emph{of the root
+account}. Make sure it exists if you use the default.
+
@item @code{compression} (default: @code{"zlib@@openssh.com,zlib"})
@itemx @code{compression-level} (default: @code{3})
The SSH-level compression methods and compression level requested.
architecture/kernel pair found at configure time, such as
@code{x86_64-linux}.
-@item --listen=@var{socket}
-Listen for connections on @var{socket}, the file name of a Unix-domain
-socket. The default socket is
-@file{@var{localstatedir}/daemon-socket/socket}. This option is only
-useful in exceptional circumstances, such as if you need to run several
-daemons on the same machine.
+@item --listen=@var{endpoint}
+Listen for connections on @var{endpoint}. @var{endpoint} is interpreted
+as the file name of a Unix-domain socket if it starts with
+@code{/} (slash sign). Otherwise, @var{endpoint} is interpreted as a
+host name or host name and port to listen to. Here are a few examples:
+
+@table @code
+@item --listen=/gnu/var/daemon
+Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
+creating it if needed.
+
+@item --listen=localhost
+@cindex daemon, remote access
+@cindex remote access to the daemon
+@cindex daemon, cluster setup
+@cindex clusters, daemon setup
+Listen for TCP connections on the network interface corresponding to
+@code{localhost}, on port 44146.
+
+@item --listen=128.0.0.42:1234
+Listen for TCP connections on the network interface corresponding to
+@code{128.0.0.42}, on port 1234.
+@end table
+
+This option can be repeated multiple times, in which case
+@command{guix-daemon} accepts connections on all the specified
+endpoints. Users can tell client commands what endpoint to connect to
+by setting the @code{GUIX_DAEMON_SOCKET} environment variable
+(@pxref{The Store, @code{GUIX_DAEMON_SOCKET}}).
+
+@quotation Note
+The daemon protocol is @emph{unauthenticated and unencrypted}. Using
+@code{--listen=@var{host}} is suitable on local networks, such as
+clusters, where only trusted nodes may connect to the build daemon. In
+other cases where remote access to the daemon is needed, we recommend
+using Unix-domain sockets along with SSH.
+@end quotation
+
+When @code{--listen} is omitted, @command{guix-daemon} listens for
+connections on the Unix-domain socket located at
+@file{@var{localstatedir}/daemon-socket/socket}.
@end table
After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
to make sure your TrueType fonts are listed there.
+@cindex @code{fc-cache}
+@cindex font cache
+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.
+
@subsection X.509 Certificates
@cindex @code{nss-certs}
with Guix, you can do so by running Emacs with @code{--no-site-file}
option (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
+@subsection The GCC toolchain
+
+@cindex GCC
+@cindex ld-wrapper
+
+Guix offers individual compiler packages such as @code{gcc} but if you
+are in need of a complete toolchain for compiling and linking source
+code what you really want is the @code{gcc-toolchain} package. This
+package provides a complete GCC toolchain for C/C++ development,
+including GCC itself, the GNU C Library (headers and binaries, plus
+debugging symbols in the @code{debug} output), Binutils, and a linker
+wrapper.
+
+@cindex attempt to use impure library, error message
+
+The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
+passed to the linker, add corresponding @code{-rpath} arguments, and
+invoke the actual linker with this new set of arguments. By default,
+the linker wrapper refuses to link to libraries outside the store to
+ensure ``purity''. This can be annoying when using the toolchain to
+link with local libraries. To allow references to libraries outside the
+store you need to define the environment variable
+@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES}.
+
@c TODO What else?
@c *********************************************************************
(list guile-2.0 "debug")))
@end example
-@findex specification->package+output
+@findex specifications->manifest
In this example we have to know which modules define the @code{emacs}
and @code{guile-2.0} variables to provide the right
@code{use-package-modules} line, which can be cumbersome. We can
instead provide regular package specifications and let
-@code{specification->package-output} look up the corresponding package
+@code{specifications->manifest} look up the corresponding package
objects, like this:
@example
-(packages->manifest
- (map (compose list specification->package+output)
- '("emacs" "guile@@2.0" "guile@@2.0:debug")))
+(specifications->manifest
+ '("emacs" "guile@@2.2" "guile@@2.2:debug"))
@end example
@item --roll-back
@itemx -s @var{regexp}
@cindex searching for packages
List the available packages whose name, synopsis, or description matches
-@var{regexp}. Print all the metadata of matching packages in
+@var{regexp}, sorted by relevance. Print all the metadata of matching packages in
@code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
GNU recutils manual}).
command, for instance:
@example
-$ guix package -s malloc | recsel -p name,version
+$ guix package -s malloc | recsel -p name,version,relevance
+name: jemalloc
+version: 4.5.0
+relevance: 6
+
name: glibc
-version: 2.17
+version: 2.25
+relevance: 1
name: libgc
-version: 7.2alpha6
+version: 7.6.0
+relevance: 1
@end example
Similarly, to show the name of all the packages available under the
@cindex security
@cindex digital signatures
@cindex substitutes, authorization thereof
+@cindex access control list (ACL), for substitutes
+@cindex ACL (access control list), for substitutes
To allow Guix to download substitutes from @code{hydra.gnu.org} or a
mirror thereof, you
must add its public key to the access control list (ACL) of archive
This indicates that substitutes from @code{hydra.gnu.org} are usable and
will be downloaded, when possible, for future builds.
-Guix ignores substitutes that are not signed, or that are not signed by
-one of the keys listed in the ACL. It also detects and raises an error
-when attempting to use a substitute that has been tampered with.
+Guix detects and raises an error when attempting to use a substitute
+that has been tampered with. Likewise, it ignores substitutes that are
+not signed, or that are not signed by one of the keys listed in the ACL.
+
+There is one exception though: if an unauthorized server provides
+substitutes that are @emph{bit-for-bit identical} to those provided by
+an authorized server, then the unauthorized server becomes eligible for
+downloads. For example, assume we have chosen two substitute servers
+with this option:
+
+@example
+--substitute-urls="https://a.example.org https://b.example.org"
+@end example
+
+@noindent
+@cindex reproducible builds
+If the ACL contains only the key for @code{b.example.org}, and if
+@code{a.example.org} happens to serve the @emph{exact same} substitutes,
+then Guix will download substitutes from @code{a.example.org} because it
+comes first in the list and can be considered a mirror of
+@code{b.example.org}. In practice, independent build machines usually
+produce the same binaries, thanks to bit-reproducible builds (see
+below).
@vindex http_proxy
Substitutes are downloaded over HTTP or HTTPS.
is what we care about (whereas X.509 certificates are about
authenticating bindings between domain names and public keys.)
+You can get statistics on the substitutes provided by a server using the
+@command{guix weather} command (@pxref{Invoking guix weather}).
+
The substitute mechanism can be disabled globally by running
@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking
guix-daemon}). It can also be disabled temporarily by passing the
is achieved by running @code{guix package --delete-generations}
(@pxref{Invoking guix package}).
+Our recommendation is to run a garbage collection periodically, or when
+you are short on disk space. For instance, to guarantee that at least
+5@tie{}GB are available on your disk, simply run:
+
+@example
+guix gc -F 5G
+@end example
+
+It is perfectly safe to run as a non-interactive periodic job
+(@pxref{Scheduled Job Execution}, for how to set up such a job on
+GuixSD). Running @command{guix gc} with no arguments will collect as
+much garbage as it can, but that is often inconvenient: you may find
+yourself having to rebuild or re-download software that is ``dead'' from
+the GC viewpoint but that is necessary to build other pieces of
+software---e.g., the compiler tool chain.
+
The @command{guix gc} command has three modes of operation: it can be
used to garbage-collect any dead files (the default), to delete specific
files (the @code{--delete} option), to print garbage-collector
the distribution currently available on your local machine. To update
that distribution, along with the Guix tools, you must run @command{guix
pull}: the command downloads the latest Guix source code and package
-descriptions, and deploys it.
+descriptions, and deploys it. Source code is downloaded from a
+@uref{https://git-scm.com, Git} repository.
On completion, @command{guix package} will use packages and package
versions from this just-retrieved copy of Guix. Not only that, but all
Produce verbose output, writing build logs to the standard error output.
@item --url=@var{url}
-Download the source tarball of Guix from @var{url}.
+Download Guix from the Git repository at @var{url}.
-By default, the tarball is taken from its canonical address at
+By default, the source is taken from its canonical Git repository at
@code{gnu.org}, for the stable branch of Guix.
-With some Git servers, this can be used to deploy any version of Guix.
-For example, to download and deploy version 0.12.0 of Guix from the
-canonical Git repo:
-
-@example
-guix pull --url=https://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz
-@end example
-
-It can also be used to deploy arbitrary Git revisions:
+@item --commit=@var{commit}
+Deploy @var{commit}, a valid Git commit ID represented as a hexadecimal
+string.
-@example
-guix pull --url=https://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz
-@end example
+@item --branch=@var{branch}
+Deploy the tip of @var{branch}, the name of a Git branch available on
+the repository at @var{url}.
@item --bootstrap
Use the bootstrap Guile to build the latest Guix. This option is only
@table @code
@item tarball
This is the default format. It produces a tarball containing all the
-specifies binaries and symlinks.
+specified binaries and symlinks.
@item docker
This produces a tarball that follows the
@item --compression=@var{tool}
@itemx -C @var{tool}
Compress the resulting tarball using @var{tool}---one of @code{gzip},
-@code{bzip2}, @code{xz}, or @code{lzip}.
+@code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression.
@item --symlink=@var{spec}
@itemx -S @var{spec}
file name explicitly because the default is not very descriptive.
@item @code{patches} (default: @code{'()})
-A list of file names containing patches to be applied to the source.
+A list of file names, origins, or file-like objects (@pxref{G-Expressions,
+file-like objects}) pointing to patches to be applied to the source.
This list of patches must be unconditional. In particular, it cannot
depend on the value of @code{%current-system} or
Both phases are executed after the @code{install} phase.
@end defvr
+@defvr {Scheme Variable} minify-build-system
+This variable is exported by @code{(guix build-system minify)}. It
+implements a minification procedure for simple JavaScript packages.
+
+It adds @code{uglify-js} to the set of inputs and uses it to compress
+all JavaScript files in the @file{src} directory. A different minifier
+package can be specified with the @code{#:uglify-js} parameter, but it
+is expected that the package writes the minified code to the standard
+output.
+
+When the input JavaScript files are not all located in the @file{src}
+directory, the parameter @code{#:javascript-files} can be used to
+specify a list of file names to feed to the minifier.
+@end defvr
+
@defvr {Scheme Variable} ocaml-build-system
This variable is exported by @code{(guix build-system ocaml)}. It implements
a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
@code{tools::testInstalledPackage}.
@end defvr
+@defvr {Scheme Variable} texlive-build-system
+This variable is exported by @code{(guix build-system texlive)}. It is
+used to build TeX packages in batch mode with a specified engine. The
+build system sets the @code{TEXINPUTS} variable to find all TeX source
+files in the inputs.
+
+By default it runs @code{luatex} on all files ending on @code{ins}. A
+different engine and format can be specified with the
+@code{#:tex-format} argument. Different build targets can be specified
+with the @code{#:build-targets} argument, which expects a list of file
+names. The build system adds only @code{texlive-bin} and
+@code{texlive-latex-base} (both from @code{(gnu packages tex}) to the
+inputs. Both can be overridden with the arguments @code{#:texlive-bin}
+and @code{#:texlive-latex-base}, respectively.
+
+The @code{#:tex-directory} parameter tells the build system where to
+install the built files under the texmf tree.
+@end defvr
+
@defvr {Scheme Variable} ruby-build-system
This variable is exported by @code{(guix build-system ruby)}. It
implements the RubyGems build procedure used by Ruby packages, which
@file{/var/guix/daemon-socket/socket}.
@item guix
+@cindex daemon, remote access
+@cindex remote access to the daemon
+@cindex daemon, cluster setup
+@cindex clusters, daemon setup
These URIs denote connections over TCP/IP, without encryption nor
-authentication of the remote host. The URI must always specify both the
-host name and port number:
+authentication of the remote host. The URI must specify the host name
+and optionally a port number (by default port 44146 is used):
@example
guix://master.guix.example.org:1234
trusted nodes may connect to the build daemon at
@code{master.guix.example.org}.
+The @code{--listen} option of @command{guix-daemon} can be used to
+instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
+@code{--listen}}).
+
@item ssh
@cindex SSH access to build daemons
These URIs allow you to connect to a remote daemon over
* Invoking guix challenge:: Challenging substitute servers.
* Invoking guix copy:: Copying to and from a remote store.
* Invoking guix container:: Process isolation.
+* Invoking guix weather:: Assessing substitute availability.
@end menu
@node Invoking guix build
* Common Build Options:: Build options for most commands.
* Package Transformation Options:: Creating variants of packages.
* Additional Build Options:: Options specific to 'guix build'.
-* Debugging Build Failures:: Real life packaging experience
+* Debugging Build Failures:: Real life packaging experience.
@end menu
@node Common Build Options
$ guix build -K foo
@dots{}
$ cd /tmp/guix-build-foo.drv-0
-$ guix environment -C foo --ad-hoc strace gdb
+$ guix environment --no-grafts -C foo --ad-hoc strace gdb
[env]# source ./environment-variables
[env]# cd foo-1.2
@end example
Here, @command{guix environment -C} creates a container and spawns a new
shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc
strace gdb} part adds the @command{strace} and @command{gdb} commands to
-the container, which would may find handy while debugging.
+the container, which would may find handy while debugging. The
+@option{--no-grafts} option makes sure we get the exact same
+environment, with ungrafted packages (@pxref{Security Updates}, for more
+info on grafts).
To get closer to a container like that used by the build daemon, we can
remove @file{/bin/sh}:
guix import cran --archive=bioconductor GenomicRanges
@end example
+@item texlive
+@cindex TeX Live
+@cindex CTAN
+Import metadata from @uref{http://www.ctan.org/, CTAN}, the
+comprehensive TeX archive network for TeX packages that are part of the
+@uref{https://www.tug.org/texlive/, TeX Live distribution}.
+
+Information about the package is obtained through the XML API provided
+by CTAN, while the source code is downloaded from the SVN repository of
+the Tex Live project. This is done because the CTAN does not keep
+versioned archives.
+
+The command command below imports metadata for the @code{fontspec}
+TeX package:
+
+@example
+guix import texlive fontspec
+@end example
+
+When @code{--archive=DIRECTORY} is added, the source code is downloaded
+not from the @file{latex} sub-directory of the @file{texmf-dist/source}
+tree in the TeX Live SVN repository, but from the specified sibling
+directory under the same root.
+
+The command below imports metadata for the @code{ifxetex} package from
+CTAN while fetching the sources from the directory
+@file{texmf/source/generic}:
+
+@example
+guix import texlive --archive=generic ifxetex
+@end example
+
@item nix
Import metadata from a local copy of the source of the
@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
Use substitute information from @var{urls}.
@xref{client-substitute-urls, the same option for @code{guix build}}.
+@item --sort=@var{key}
+Sort lines according to @var{key}, one of the following options:
+
+@table @code
+@item self
+the size of each item (the default);
+@item closure
+the total size of the item's closure.
+@end table
+
@item --map-file=@var{file}
Write a graphical map of disk usage in PNG format to @var{file}.
no setup and is immediately available. However, when serving lots of
clients, we recommend using the @option{--cache} option, which enables
caching of the archives before they are sent to clients---see below for
-details.
+details. The @command{guix weather} command provides a handy way to
+check what a server provides (@pxref{Invoking guix weather}).
As a bonus, @command{guix publish} also serves as a content-addressed
mirror for source files referenced in @code{origin} records
for as long as @var{ttl}.
Additionally, when @option{--cache} is used, cached entries that have
-not been accessed for @var{ttl} may be deleted.
+not been accessed for @var{ttl} and that no longer have a corresponding
+item in the store, may be deleted.
@item --nar-path=@var{path}
Use @var{path} as the prefix for the URLs of ``nar'' files
@end table
+@node Invoking guix weather
+@section Invoking @command{guix weather}
+
+Occasionally you're grumpy because substitutes are lacking and you end
+up building packages by yourself (@pxref{Substitutes}). The
+@command{guix weather} command reports on substitute availability on the
+specified servers so you can have an idea of whether you'll be grumpy
+today. It can sometimes be useful info as a user, but it is primarily
+useful to people running @command{guix publish} (@pxref{Invoking guix
+publish}).
+
+@cindex statistics, for substitutes
+@cindex availability of substitutes
+@cindex substitute availability
+@cindex weather, substitute availability
+Here's a sample run:
+
+@example
+$ guix weather --substitute-urls=https://guix.example.org
+computing 5,872 package derivations for x86_64-linux...
+looking for 6,128 store items on https://guix.example.org..
+updating list of substitutes from 'https://guix.example.org'... 100.0%
+https://guix.example.org
+ 43.4% substitutes available (2,658 out of 6,128)
+ 7,032.5 MiB of nars (compressed)
+ 19,824.2 MiB on disk (uncompressed)
+ 0.030 seconds per request (182.9 seconds in total)
+ 33.5 requests per second
+@end example
+
+As you can see, it reports the fraction of all the packages for which
+substitutes are available on the server---regardless of whether
+substitutes are enabled, and regardless of whether this server's signing
+key is authorized. It also reports the size of the compressed archives
+(``nars'') provided by the server, the size the corresponding store
+items occupy in the store (assuming deduplication is turned off), and
+the server's throughput.
+
+To achieve that, @command{guix weather} queries over HTTP(S) meta-data
+(@dfn{narinfos}) for all the relevant store items. Like @command{guix
+challenge}, it ignores signatures on those substitutes, which is
+innocuous since the command only gathers statistics and cannot install
+those substitutes.
+
+Among other things, it is possible to query specific system types and
+specific package sets. The available options are listed below.
+
+@table @code
+@item --substitute-urls=@var{urls}
+@var{urls} is the space-separated list of substitute server URLs to
+query. When this option is omitted, the default set of substitute
+servers is queried.
+
+@item --system=@var{system}
+@itemx -s @var{system}
+Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
+option can be repeated, in which case @command{guix weather} will query
+substitutes for several system types.
+
+@item --manifest=@var{file}
+Instead of querying substitutes for all the packages, only ask for those
+specified in @var{file}. @var{file} must contain a @dfn{manifest}, as
+with the @code{-m} option of @command{guix package} (@pxref{Invoking
+guix package}).
+@end table
+
+
@c *********************************************************************
@node GNU Distribution
@chapter GNU Distribution
* Limitations:: What you can expect.
* Hardware Considerations:: Supported hardware.
* USB Stick Installation:: Preparing the installation medium.
+* DVD Installation:: Preparing the installation medium.
* Preparing for Installation:: Networking, partitioning, etc.
* Proceeding with the Installation:: The real thing.
* Installing GuixSD in a VM:: GuixSD playground.
@subsection USB Stick Installation
An installation image for USB sticks can be downloaded from
-@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz},
+@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz},
where @var{system} is one of:
@table @code
authenticity of the image against it, along these lines:
@example
-$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
-$ gpg --verify guixsd-usb-install-@value{VERSION}.@var{system}.xz.sig
+$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz.sig
+$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.xz.sig
@end example
If that command fails because you do not have the required public key,
and rerun the @code{gpg --verify} command.
@c end duplication
-This image contains a single partition with the tools necessary for an
-installation. It is meant to be copied @emph{as is} to a large-enough
-USB stick.
+This image contains the tools necessary for an installation.
+It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
To copy the image to a USB stick, follow these steps:
Decompress the image using the @command{xz} command:
@example
-xz -d guixsd-usb-install-@value{VERSION}.@var{system}.xz
+xz -d guixsd-install-@value{VERSION}.@var{system}.xz
@end example
@item
copy the image with:
@example
-dd if=guixsd-usb-install-@value{VERSION}.x86_64 of=/dev/sdX
+dd if=guixsd-install-@value{VERSION}.x86_64 of=/dev/sdX
sync
@end example
@xref{Installing GuixSD in a VM}, if, instead, you would like to install
GuixSD in a virtual machine (VM).
+@node DVD Installation
+@subsection DVD Installation
+
+An installation image for DVDs can be downloaded from
+@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz},
+where @var{system} is one of:
+
+@table @code
+@item x86_64-linux
+for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
+
+@item i686-linux
+for a 32-bit GNU/Linux system on Intel-compatible CPUs.
+@end table
+
+@c start duplication of authentication part from ``Binary Installation''
+Make sure to download the associated @file{.sig} file and to verify the
+authenticity of the image against it, along these lines:
+
+@example
+$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz.sig
+$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.xz.sig
+@end example
+
+If that command fails because you do not have the required public key,
+then run this command to import it:
+
+@example
+$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+@end example
+
+@noindent
+and rerun the @code{gpg --verify} command.
+@c end duplication
+
+This image contains the tools necessary for an installation.
+It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
+
+To copy the image to a DVD, follow these steps:
+
+@enumerate
+@item
+Decompress the image using the @command{xz} command:
+
+@example
+xz -d guixsd-install-@value{VERSION}.@var{system}.xz
+@end example
+
+@item
+Insert a blank DVD into your machine, and determine
+its device name. Assuming that the DVD drive is known as @file{/dev/srX},
+copy the image with:
+
+@example
+growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.x86_64
+@end example
+
+Access to @file{/dev/srX} usually requires root privileges.
+@end enumerate
+
+Once this is done, you should be able to reboot the system and boot from
+the DVD. The latter usually requires you to get in the BIOS or
+UEFI boot menu, where you can choose to boot from the DVD.
+
+@xref{Installing GuixSD in a VM}, if, instead, you would like to install
+GuixSD in a virtual machine (VM).
+
@node Preparing for Installation
@subsection Preparing for Installation
-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,
+Once you have successfully booted your computer using the installation medium,
+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{Top,,, info-stnd,
Stand-alone GNU Info}). The installation system runs the GPM mouse
daemon, which allows you to select text with the left mouse button and
@itemize
@item
-Make sure the @code{grub-configuration} form refers to the device you
-want to install GRUB on. You also need to specify the @code{grub-efi}
-package if you wish to use native UEFI boot.
+Make sure the @code{grub-configuration} form refers to the target you
+want to install GRUB on. It should mention @code{grub-bootloader} if
+you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
+for newer UEFI systems. For legacy systems, the @code{target} field
+names a device, like @code{/dev/sda}; for UEFI systems it names a path
+to a mounted EFI partition, like @code{/boot/efi}, and do make sure the
+path is actually mounted.
@item
Be sure that your partition labels match the value of their respective
qcow2-formatted disk image, use the @command{qemu-img} command:
@example
-qemu-img create -f qcow2 guixsd.img 5G
+qemu-img create -f qcow2 guixsd.img 50G
@end example
-This will create a 5GB file.
+The resulting file will be much smaller than 50 GB (typically less than
+1 MB), but it will grow as the virtualized storage device is filled up.
@item
Boot the USB installation image in an VM:
@example
qemu-system-x86_64 -m 1024 -smp 1 \
-net user -net nic,model=virtio -boot menu=on \
- -drive file=guixsd-usb-install-@value{VERSION}.@var{system} \
+ -drive file=guixsd-install-@value{VERSION}.@var{system} \
-drive file=guixsd.img
@end example
The installation image described above was built using the @command{guix
system} command, specifically:
-@c FIXME: 1G is too much; see <http://bugs.gnu.org/23077>.
@example
-guix system disk-image --image-size=1G gnu/system/install.scm
+guix system disk-image gnu/system/install.scm
@end example
Have a look at @file{gnu/system/install.scm} in the source tree,
* X.509 Certificates:: Authenticating HTTPS servers.
* Name Service Switch:: Configuring libc's name service switch.
* Initial RAM Disk:: Linux-Libre bootstrapping.
-* GRUB Configuration:: Configuring the boot loader.
+* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
* Running GuixSD in a VM:: How to run GuixSD in a virtual machine.
* Defining Services:: Adding new service definitions.
provides all the tools one would expect 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 tcpdump to those, taken from the @code{(gnu
-packages admin)} module (@pxref{Package Modules}). The
+etc. The example above adds GNU@tie{}Screen and OpenSSH to those,
+taken from the @code{(gnu packages screen)} and @code{(gnu packages ssh)}
+modules (@pxref{Package Modules}). The
@code{(list package output)} syntax can be used to add a specific output
of a package:
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
+an entry in the bootloader 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. It is also possible to roll back the
the command-line of the kernel---e.g., @code{("console=ttyS0")}.
@item @code{bootloader}
-The system bootloader configuration object. @xref{GRUB Configuration}.
+The system bootloader configuration object. @xref{Bootloader Configuration}.
@item @code{initrd} (default: @code{base-initrd})
@cindex initrd
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
-* Database Services:: SQL databases.
+* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
+* Monitoring Services:: Monitoring services.
* Kerberos Services:: Kerberos services.
* Web Services:: Web servers.
* DNS Services:: DNS daemons.
* Network File System:: NFS related services.
* Continuous Integration:: The Cuirass service.
* Power management Services:: The TLP tool.
+* Audio Services:: The MPD.
+* Virtualization Services:: Virtualization services.
* Miscellaneous Services:: Other services.
@end menu
@item @code{substitute-urls} (default: @var{%default-substitute-urls})
The list of URLs where to look for substitutes by default.
+@item @code{max-silent-time} (default: @code{0})
+@itemx @code{timeout} (default: @code{0})
+The number of seconds of silence and the number of seconds of activity,
+respectively, after which a build process times out. A value of zero
+disables the timeout.
+
@item @code{extra-options} (default: @code{'()})
List of extra command-line options for @command{guix-daemon}.
log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
The example below defines an operating system that provides log rotation
-with the default settings.
+with the default settings, for commonly encountered log files.
@lisp
(use-modules (guix) (gnu))
This is the type of the Rottlog service, whose value is a
@code{rottlog-configuration} object.
+Other services can extend this one with new @code{log-rotation} objects
+(see below), thereby augmenting the set of files to be rotated.
+
This service type can define mcron jobs (@pxref{Scheduled Job
Execution}) to run the rottlog service.
@end defvr
The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
rottlog, GNU Rot[t]log Manual}).
-@item @code{periodic-rotations} (default: @code{`(("weekly" %default-rotations))})
-A list of Rottlog period-name/period-config tuples.
+@item @code{rotations} (default: @code{%default-rotations})
+A list of @code{log-rotation} objects as defined below.
+
+@item @code{jobs}
+This is a list of gexps where each gexp corresponds to an mcron job
+specification (@pxref{Scheduled Job Execution}).
+@end table
+@end deftp
+
+@deftp {Data Type} log-rotation
+Data type representing the rotation of a group of log files.
-For example, taking an example from the Rottlog manual (@pxref{Period
-Related File Examples,,, rottlog, GNU Rot[t]log Manual}), a valid tuple
-might be:
+Taking an example from the Rottlog manual (@pxref{Period Related File
+Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be
+defined like this:
@example
-("daily" ,(plain-file "daily"
- "\
- /var/log/apache/* @{
- storedir apache-archives
- rotate 6
- notifempty
- nocompress
- @}"))
+(log-rotation
+ (frequency 'daily)
+ (files '("/var/log/apache/*"))
+ (options '("storedir apache-archives"
+ "rotate 6"
+ "notifempty"
+ "nocompress")))
@end example
-@item @code{jobs}
-This is a list of gexps where each gexp corresponds to an mcron job
-specification (@pxref{Scheduled Job Execution}).
+The list of fields is as follows:
+
+@table @asis
+@item @code{frequency} (default: @code{'weekly})
+The log rotation frequency, a symbol.
+
+@item @code{files}
+The list of files or file glob patterns to rotate.
+
+@item @code{options} (default: @code{'()})
+The list of rottlog options for this rotation (@pxref{Configuration
+parameters,,, rottlog, GNU Rot[t]lg Manual}).
+
+@item @code{post-rotate} (default: @code{#f})
+Either @code{#f} or a gexp to execute once the rotation has completed.
@end table
@end deftp
@defvr {Scheme Variable} %default-rotations
Specifies weekly rotation of @var{%rotated-files} and
-@code{"/var/log/shepherd.log"}.
+a couple of other files.
@end defvr
@defvr {Scheme Variable} %rotated-files
@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
service. The value for this service type is a
@code{network-manager-configuration} record.
+
+This service is part of @code{%desktop-services} (@pxref{Desktop
+Services}).
@end defvr
@deftp {Data Type} network-manager-configuration
(service openssh-service-type
(openssh-configuration
(x11-forwarding? #t)
- (permit-root-login 'without-password)))
+ (permit-root-login 'without-password)
+ (authorized-keys
+ `(("alice" ,(local-file "alice.pub"))
+ ("bob" ,(local-file "bob.pub"))))))
@end example
See below for details about @code{openssh-configuration}.
+
+This service can be extended with extra authorized keys, as in this
+example:
+
+@example
+(service-extension openssh-service-type
+ (const `(("charlie"
+ ,(local-file "charlie.pub")))))
+@end example
@end deffn
@deftp {Data Type} openssh-configuration
(service openssh-service-type
(openssh-configuration
(subsystems
- '(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
+ `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
+@end example
+
+@item @code{authorized-keys} (default: @code{'()})
+@cindex authorized keys, SSH
+@cindex SSH authorized keys
+This is the list of authorized keys. Each element of the list is a user
+name followed by one or more file-like objects that represent SSH public
+keys. For example:
+
+@example
+(openssh-configuration
+ (authorized-keys
+ `(("rekado" ,(local-file "rekado.pub"))
+ ("chris" ,(local-file "chris.pub"))
+ ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
@end example
+
+@noindent
+registers the specified public keys for user accounts @code{rekado},
+@code{chris}, and @code{root}.
+
+Additional authorized keys can be specified @i{via}
+@code{service-extension}.
+
+Note that this does @emph{not} interfere with the use of
+@file{~/.ssh/authorized_keys}.
@end table
@end deftp
adds or adjusts services for a typical ``desktop'' setup.
In particular, it adds a graphical login manager (@pxref{X Window,
-@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
-Services}), the Avahi daemon, and has the name service switch service
-configured to be able to use @code{nss-mdns} (@pxref{Name Service
-Switch, mDNS}).
+@code{slim-service}}), screen lockers, a network management tool
+(@pxref{Networking Services, @code{network-manager-service-type}}), energy and color
+management services, the @code{elogind} login and seat manager, the
+Polkit privilege service, the GeoClue location service, the
+AccountsService daemon that allows authorized users change system
+passwords, an NTP client (@pxref{Networking Services}), the Avahi
+daemon, and has the name service switch service configured to be able to
+use @code{nss-mdns} (@pxref{Name Service Switch, mDNS}).
@end defvr
The @var{%desktop-services} variable can be used as the @code{services}
@deffn {Scheme Procedure} elogind-service [#:config @var{config}]
Return a service that runs the @code{elogind} login and
-seat management daemon. @uref{https://github.com/andywingo/elogind,
+seat management daemon. @uref{https://github.com/elogind/elogind,
Elogind} exposes a D-Bus interface that can be used to know which users
are logged in, know what kind of sessions they have open, suspend the
system, inhibit system suspend, reboot the system, and other tasks.
@end table
@end deffn
+@deffn {Scheme Procedure} accountsservice-service @
+ [#:accountsservice @var{accountsservice}]
+Return a service that runs AccountsService, a system service that can
+list available accounts, change their passwords, and so on.
+AccountsService integrates with PolicyKit to enable unprivileged users
+to acquire the capability to modify their system configuration.
+@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
+accountsservice web site} for more information.
+
+The @var{accountsservice} keyword argument is the @code{accountsservice}
+package to expose as a service.
+@end deffn
+
@deffn {Scheme Procedure} polkit-service @
[#:polkit @var{polkit}]
Return a service that runs the
web site} for more information.
@end deffn
-@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}]
-Return a service that runs the @command{bluetoothd} daemon, which manages
-all the Bluetooth devices and provides a number of D-Bus interfaces.
+@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
+ [@w{#:auto-enable? #f}]
+Return a service that runs the @command{bluetoothd} daemon, which
+manages all the Bluetooth devices and provides a number of D-Bus
+interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
+powered automatically at boot, which can be useful when using a
+bluetooth keyboard or mouse.
Users need to be in the @code{lp} group to access the D-Bus service.
@end deffn
@end table
@end deftp
+@defvr {Scheme Variable} memcached-service-type
+This is the service type for the @uref{https://memcached.org/,
+Memcached} service, which provides a distributed in memory cache. The
+value for the service type is a @code{memcached-configuration} object.
+@end defvr
+
+@example
+(service memcached-service-type)
+@end example
+
+@deftp {Data Type} memcached-configuration
+Data type representing the configuration of memcached.
+
+@table @asis
+@item @code{memcached} (default: @code{memcached})
+The Memcached package to use.
+
+@item @code{interfaces} (default: @code{'("0.0.0.0")})
+Network interfaces on which to listen.
+
+@item @code{tcp-port} (default: @code{11211})
+Port on which to accept connections on,
+
+@item @code{udp-port} (default: @code{11211})
+Port on which to accept UDP connections on, a value of 0 will disable
+listening on a UDP socket.
+
+@item @code{additional-options} (default: @code{'()})
+Additional command line options to pass to @code{memcached}.
+@end table
+@end deftp
+
@defvr {Scheme Variable} redis-service-type
This is the service type for the @uref{https://redis.io/, Redis}
key/value store, whose value is a @code{redis-configuration} object.
(prosody.cfg.lua "")))
@end example
+@node Monitoring Services
+@subsubsection Monitoring Services
+
+@subsubheading Tailon Service
+
+@uref{https://tailon.readthedocs.io/, Tailon} is a web application for
+viewing and searching log files.
+
+The following example will configure the service with default values.
+By default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
+
+@example
+(service tailon-service-type)
+@end example
+
+The following example customises more of the Tailon configuration,
+adding @command{sed} to the list of allowed commands.
+
+@example
+(service tailon-service-type
+ (tailon-configuration
+ (config-file
+ (tailon-configuration-file
+ (allowed-commands '("tail" "grep" "awk" "sed"))))))
+@end example
+
+
+@deftp {Data Type} tailon-configuration
+Data type representing the configuration of Tailon.
+This type has the following parameters:
+
+@table @asis
+@item @code{config-file} (default: @code{(tailon-configuration-file)})
+The configuration file to use for Tailon. This can be set to a
+@dfn{tailon-configuration-file} record value, or any gexp
+(@pxref{G-Expressions}).
+
+For example, to instead use a local file, the @code{local-file} function
+can be used:
+
+@example
+(service tailon-service-type
+ (tailon-configuration
+ (config-file (local-file "./my-tailon.conf"))))
+@end example
+
+@item @code{package} (default: @code{tailon})
+The tailon package to use.
+
+@end table
+@end deftp
+
+@deftp {Data Type} tailon-configuration-file
+Data type representing the configuration options for Tailon.
+This type has the following parameters:
+
+@table @asis
+@item @code{files} (default: @code{(list "/var/log")})
+List of files to display. The list can include strings for a single file
+or directory, or a list, where the first item is the name of a
+subsection, and the remaining items are the files or directories in that
+subsection.
+
+@item @code{bind} (default: @code{"localhost:8080"})
+Address and port to which Tailon should bind on.
+
+@item @code{relative-root} (default: @code{#f})
+URL path to use for Tailon, set to @code{#f} to not use a path.
+
+@item @code{allow-transfers?} (default: @code{#t})
+Allow downloading the log files in the web interface.
+
+@item @code{follow-names?} (default: @code{#t})
+Allow tailing of not-yet existent files.
+
+@item @code{tail-lines} (default: @code{200})
+Number of lines to read initially from each file.
+
+@item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
+Commands to allow running. By default, @code{sed} is disabled.
+
+@item @code{debug?} (default: @code{#f})
+Set @code{debug?} to @code{#t} to show debug messages.
+
+@item @code{wrap-lines} (default: @code{#t})
+Initial line wrapping state in the web interface. Set to @code{#t} to
+initially wrap lines (the default), or to @code{#f} to initially not
+wrap lines.
+
+@item @code{http-auth} (default: @code{#f})
+HTTP authentication type to use. Set to @code{#f} to disable
+authentication (the default). Supported values are @code{"digest"} or
+@code{"basic"}.
+
+@item @code{users} (default: @code{#f})
+If HTTP authentication is enabled (see @code{http-auth}), access will be
+restricted to the credentials provided here. To configure users, use a
+list of pairs, where the first element of the pair is the username, and
+the 2nd element of the pair is the password.
+
+@example
+(tailon-configuration-file
+ (http-auth "basic")
+ (users '(("user1" . "password1")
+ ("user2" . "password2"))))
+@end example
+
+@end table
+@end deftp
+
+
@node Kerberos Services
@subsubsection Kerberos Services
@cindex Kerberos
@cindex web
@cindex www
@cindex HTTP
-The @code{(gnu services web)} module provides the following service:
-
-@deffn {Scheme Procedure} nginx-service [#:nginx nginx] @
- [#:log-directory ``/var/log/nginx''] @
- [#:run-directory ``/var/run/nginx''] @
- [#:server-list '()] @
- [#:upstream-list '()] @
- [#:config-file @code{#f}]
-
-Return a service that runs @var{nginx}, the nginx web server.
-
-The nginx daemon loads its runtime configuration from @var{config-file}.
-Log files are written to @var{log-directory} and temporary runtime data
-files are written to @var{run-directory}. For proper operation, these
-arguments should match what is in @var{config-file} to ensure that the
-directories are created when the service is activated.
-
-As an alternative to using a @var{config-file}, @var{server-list} can be
-used to specify the list of @dfn{server blocks} required on the host and
-@var{upstream-list} can be used to specify a list of @dfn{upstream
-blocks} to configure. For this to work, use the default value for
-@var{config-file}.
-
-At startup, @command{nginx} has not yet read its configuration file, so it
-uses a default file to log error messages. If it fails to load its
-configuration file, that is where error messages are logged. After the
-configuration file is loaded, the default error log file changes as per
-configuration. In our case, startup error messages can be found in
-@file{/var/run/nginx/logs/error.log}, and after configuration in
-@file{/var/log/nginx/error.log}. The second location can be changed with the
-@var{log-directory} configuration option.
-
-@end deffn
+The @code{(gnu services web)} module provides the nginx web server and
+also a fastcgi wrapper daemon.
@deffn {Scheme Variable} nginx-service-type
-This is type for the nginx web server.
+Service type for the @uref{https://nginx.org/,NGinx} web server. The
+value for this service type is a @code{<nginx-configuration>} record.
+
+A simple example configuration is given below.
+
+@example
+(service nginx-service-type
+ (nginx-configuration
+ (server-blocks
+ (list (nginx-server-configuration
+ (server-name '("www.example.com"))
+ (root "/srv/http/www.example.com")
+ (https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f))))))
+@end example
-This service can be extended to add server blocks in addition to the
-default one, as in this example:
+In addition to adding server blocks to the service configuration
+directly, this service can be extended by other services to add server
+blocks, as in this example:
@example
(simple-service 'my-extra-server nginx-service-type
(list (nginx-server-configuration
(https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f)
(root "/srv/http/extra-website"))))
@end example
@end deffn
+At startup, @command{nginx} has not yet read its configuration file, so
+it uses a default file to log error messages. If it fails to load its
+configuration file, that is where error messages are logged. After the
+configuration file is loaded, the default error log file changes as per
+configuration. In our case, startup error messages can be found in
+@file{/var/run/nginx/logs/error.log}, and after configuration in
+@file{/var/log/nginx/error.log}. The second location can be changed
+with the @var{log-directory} configuration option.
+
+@deffn {Data Type} nginx-configuration
+This data type represents the configuration for NGinx. Some
+configuration can be done through this and the other provided record
+types, or alternatively, a config file can be provided.
+
+@table @asis
+@item @code{nginx} (default: @code{nginx})
+The nginx package to use.
+
+@item @code{log-directory} (default: @code{"/var/log/nginx"})
+The directory to which NGinx will write log files.
+
+@item @code{run-directory} (default: @code{"/var/run/nginx"})
+The directory in which NGinx will create a pid file, and write temporary
+files.
+
+@item @code{server-blocks} (default: @code{'()})
+A list of @dfn{server blocks} to create in the generated configuration
+file, the elements should be of type
+@code{<nginx-server-configuration>}.
+
+The following example would setup NGinx to serve @code{www.example.com}
+from the @code{/srv/http/www.example.com} directory, without using
+HTTPS.
+@example
+(service nginx-service-type
+ (nginx-configuration
+ (server-blocks
+ (list (nginx-server-configuration
+ (server-name '("www.example.com"))
+ (root "/srv/http/www.example.com")
+ (https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f))))))
+@end example
+
+@item @code{upstream-blocks} (default: @code{'()})
+A list of @dfn{upstream blocks} to create in the generated configuration
+file, the elements should be of type
+@code{<nginx-upstream-configuration>}.
+
+Configuring upstreams through the @code{upstream-blocks} can be useful
+when combined with @code{locations} in the
+@code{<nginx-server-configuration>} records. The following example
+creates a server configuration with one location configuration, that
+will proxy requests to a upstream configuration, which will handle
+requests with two servers.
+
+@example
+(service
+ nginx-service-type
+ (nginx-configuration
+ (server-blocks
+ (list (nginx-server-configuration
+ (server-name '("www.example.com"))
+ (root "/srv/http/www.example.com")
+ (https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f)
+ (locations
+ (list
+ (nginx-location-configuration
+ (uri "/path1")
+ (body '("proxy_pass http://server-proxy;"))))))))
+ (upstream-blocks
+ (list (nginx-upstream-configuration
+ (name "server-proxy")
+ (servers (list "server1.example.com"
+ "server2.example.com")))))))
+@end example
+
+@item @code{file} (default: @code{#f})
+If a configuration @var{file} is provided, this will be used, rather than
+generating a configuration file from the provided @code{log-directory},
+@code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For
+proper operation, these arguments should match what is in @var{file} to ensure
+that the directories are created when the service is activated.
+
+This can be useful if you have an existing configuration file, or it's
+not possible to do what is required through the other parts of the
+nginx-configuration record.
+
+@end table
+@end deffn
+
@deftp {Data Type} nginx-server-configuration
Data type representing the configuration of an nginx server block.
This type has the following parameters:
@end table
@end deftp
+@cindex fastcgi
+@cindex fcgiwrap
+FastCGI is an interface between the front-end and the back-end of a web
+service. It is a somewhat legacy facility; new web services should
+generally just talk HTTP between the front-end and the back-end.
+However there are a number of back-end services such as PHP or the
+optimized HTTP Git repository access that use FastCGI, so we have
+support for it in Guix.
+
+To use FastCGI, you configure the front-end web server (e.g., nginx) to
+dispatch some subset of its requests to the fastcgi backend, which
+listens on a local TCP or UNIX socket. There is an intermediary
+@code{fcgiwrap} program that sits between the actual backend process and
+the web server. The front-end indicates which backend program to run,
+passing that information to the @code{fcgiwrap} process.
+
+@defvr {Scheme Variable} fcgiwrap-service-type
+A service type for the @code{fcgiwrap} FastCGI proxy.
+@end defvr
+
+@deftp {Data Type} fcgiwrap-configuration
+Data type representing the configuration of the @code{fcgiwrap} serice.
+This type has the following parameters:
+@table @asis
+@item @code{package} (default: @code{fcgiwrap})
+The fcgiwrap package to use.
+
+@item @code{socket} (default: @code{tcp:127.0.0.1:9000})
+The socket on which the @code{fcgiwrap} process should listen, as a
+string. Valid @var{socket} values include
+@code{unix:@var{/path/to/unix/socket}},
+@code{tcp:@var{dot.ted.qu.ad}:@var{port}} and
+@code{tcp6:[@var{ipv6_addr}]:port}.
+
+@item @code{user} (default: @code{fcgiwrap})
+@itemx @code{group} (default: @code{fcgiwrap})
+The user and group names, as strings, under which to run the
+@code{fcgiwrap} process. The @code{fastcgi} service will ensure that if
+the user asks for the specific user or group names @code{fcgiwrap} that
+the corresponding user and/or group is present on the system.
+
+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
+@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
+@end deftp
+
@node DNS Services
@subsubsection DNS Services
both slaves and resolvers, it is mandatory that it @emph{never} decreases.
Always increment it when you make a change in your zone.
-@item @code{refresh} (default: @code{"2d"})
-The frequency at which slaves will do a zone transfer. This value can be
-a number of seconds or a number of some unit between:
-@itemize
-@item m: minute
-@item h: hour
-@item d: day
-@item w: week
-@end itemize
+@item @code{refresh} (default: @code{(* 2 24 3600)})
+The frequency at which slaves will do a zone transfer. This value is a number
+of seconds. It can be computed by multiplications or with
+@code{(string->duration)}.
-@item @code{retry} (default: @code{"15m"})
+@item @code{retry} (default: @code{(* 15 60)})
The period after which a slave will retry to contact its master when it fails
to do so a first time.
-@item @code{expiry} (default: @code{"2w"})
+@item @code{expiry} (default: @code{(* 14 24 3600)})
Default TTL of records. Existing records are considered correct for at most
this amount of time. After this period, resolvers will invalidate their cache
and check again that it still exists.
-@item @code{nx} (default: @code{"1h"})
+@item @code{nx} (default: @code{3600})
Default TTL of inexistant records. This delay is usually short because you want
your new domains to reach everyone quickly.
The TTL value for DNSKEY records added into zone apex. The special
@code{'default} value means same as the zone SOA TTL.
-@item @code{zsk-lifetime} (default: @code{"30d"})
+@item @code{zsk-lifetime} (default: @code{(* 30 24 3600)})
The period between ZSK publication and the next rollover initiation.
-@item @code{propagation-delay} (default: @code{"1d"})
+@item @code{propagation-delay} (default: @code{(* 24 3600)})
An extra delay added for each key rollover step. This value should be high
enough to cover propagation of data from the master server to all slaves.
-@item @code{rrsig-lifetime} (default: @code{"14d"})
+@item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)})
A validity period of newly issued signatures.
-@item @code{rrsig-refresh} (default: @code{"7d"})
+@item @code{rrsig-refresh} (default: @code{(* 7 24 3600)})
A period how long before a signature expiration the signature will be refreshed.
@item @code{nsec3?} (default: @code{#f})
The length of a salt field in octets, which is appended to the original owner
name before hashing.
-@item @code{nsec3-salt-lifetime} (default: @code{"30d"})
+@item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)})
The validity period of newly issued salt field.
@end table
(#:branch . "master"))))
(service cuirass-service-type
(cuirass-configuration
- (specifications #~(list #$spec)))))
+ (specifications #~(list '#$spec)))))
@end example
While information related to build jobs is located directly in the
Location of sqlite database which contains the build results and previously
added specifications.
-@item @code{port} (default: @code{8080})
+@item @code{port} (default: @code{8081})
Port number used by the HTTP server.
@item @code{specifications} (default: @code{#~'()})
@item @code{one-shot?} (default: @code{#f})
Only evaluate specifications and build derivations once.
+@item @code{fallback?} (default: @code{#f})
+When substituting a pre-built binary fails, fall back to building
+packages locally.
+
@item @code{load-path} (default: @code{'()})
This allows users to define their own packages and make them visible to
cuirass as in @command{guix build} command.
@end table
@end deftp
+@node Audio Services
+@subsubsection Audio Services
+
+The @code{(gnu services audio)} module provides a service to start MPD
+(the Music Player Daemon).
+
+@cindex mpd
+@subsubheading Music Player Daemon
+
+The Music Player Daemon (MPD) is a service that can play music while
+being controlled from the local machine or over the network by a variety
+of clients.
+
+The following example shows how one might run @code{mpd} as user
+@code{"bob"} on port @code{6666}. It uses pulseaudio for output.
+
+@example
+(service mpd-service-type
+ (mpd-configuration
+ (user "bob")
+ (port "6666")))
+@end example
+
+@defvr {Scheme Variable} mpd-service-type
+The service type for @command{mpd}
+@end defvr
+
+@deftp {Data Type} mpd-configuration
+Data type representing the configuration of @command{mpd}.
+
+@table @asis
+@item @code{user} (default: @code{"mpd"})
+The user to run mpd as.
+
+@item @code{music-dir} (default: @code{"~/Music"})
+The directory to scan for music files.
+
+@item @code{playlist-dir} (default: @code{"~/.mpd/playlists"})
+The directory to store playlists.
+
+@item @code{port} (default: @code{"6600"})
+The port to run mpd on.
+
+@item @code{address} (default: @code{"any"})
+The address that mpd will bind to. To use a Unix domain socket,
+an absolute path can be specified here.
+
+@end table
+@end deftp
+
+@node Virtualization Services
+@subsubsection Virtualization services
+The @code{(gnu services virtualization)} module provides services for
+the libvirt and virtlog daemons.
+
+@subsubheading Libvirt daemon
+@code{libvirtd} is the server side daemon component of the libvirt
+virtualization management system. This daemon runs on host servers
+and performs required management tasks for virtualized guests.
+
+@deffn {Scheme Variable} libvirt-service-type
+This is the type of the @uref{https://libvirt.org, libvirt daemon}.
+Its value must be a @code{libvirt-configuration}.
+
+@example
+(service libvirt-service-type
+ (libvirt-configuration
+ (unix-sock-group "libvirt")
+ (tls-port "16555")))
+@end example
+@end deffn
+
+@c Auto-generated with (generate-libvirt-documentation)
+Available @code{libvirt-configuration} fields are:
+
+@deftypevr {@code{libvirt-configuration} parameter} package libvirt
+Libvirt package.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls?
+Flag listening for secure TLS connections on the public TCP/IP port.
+must set @code{listen} for this to have any effect.
+
+It is necessary to setup a CA and issue server certificates before using
+this capability.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp?
+Listen for unencrypted TCP connections on the public TCP/IP port. must
+set @code{listen} for this to have any effect.
+
+Using the TCP socket requires SASL authentication by default. Only SASL
+mechanisms which support data encryption are allowed. This is
+DIGEST_MD5 and GSSAPI (Kerberos5)
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string tls-port
+Port for accepting secure TLS connections This can be a port number, or
+service name
+
+Defaults to @samp{"16514"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string tcp-port
+Port for accepting insecure TCP connections This can be a port number,
+or service name
+
+Defaults to @samp{"16509"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string listen-addr
+IP address or hostname used for client connections.
+
+Defaults to @samp{"0.0.0.0"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv?
+Flag toggling mDNS advertisement of the libvirt service.
+
+Alternatively can disable for all services on a host by stopping the
+Avahi daemon.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string mdns-name
+Default mDNS advertisement name. This must be unique on the immediate
+broadcast network.
+
+Defaults to @samp{"Virtualization Host <hostname>"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group
+UNIX domain socket group ownership. This can be used to allow a
+'trusted' set of users access to management capabilities without
+becoming root.
+
+Defaults to @samp{"root"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms
+UNIX socket permissions for the R/O socket. This is used for monitoring
+VM status only.
+
+Defaults to @samp{"0777"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms
+UNIX socket permissions for the R/W socket. Default allows only root.
+If PolicyKit is enabled on the socket, the default will change to allow
+everyone (eg, 0777)
+
+Defaults to @samp{"0770"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms
+UNIX socket permissions for the admin socket. Default allows only owner
+(root), do not change it unless you are sure to whom you are exposing
+the access to.
+
+Defaults to @samp{"0777"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir
+The directory in which sockets will be found/created.
+
+Defaults to @samp{"/var/run/libvirt"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro
+Authentication scheme for UNIX read-only sockets. By default socket
+permissions allow anyone to connect
+
+Defaults to @samp{"polkit"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw
+Authentication scheme for UNIX read-write sockets. By default socket
+permissions only allow root. If PolicyKit support was compiled into
+libvirt, the default will be to use 'polkit' auth.
+
+Defaults to @samp{"polkit"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string auth-tcp
+Authentication scheme for TCP sockets. If you don't enable SASL, then
+all TCP traffic is cleartext. Don't do this outside of a dev/test
+scenario.
+
+Defaults to @samp{"sasl"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string auth-tls
+Authentication scheme for TLS sockets. TLS sockets already have
+encryption provided by the TLS layer, and limited authentication is done
+by certificates.
+
+It is possible to make use of any SASL authentication mechanism as well,
+by using 'sasl' for this option
+
+Defaults to @samp{"none"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers
+API access control scheme.
+
+By default an authenticated user is allowed access to all APIs. Access
+drivers can place restrictions on this.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string key-file
+Server key file path. If set to an empty string, then no private key is
+loaded.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string cert-file
+Server key file path. If set to an empty string, then no certificate is
+loaded.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string ca-file
+Server key file path. If set to an empty string, then no CA certificate
+is loaded.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string crl-file
+Certificate revocation list path. If set to an empty string, then no
+CRL is loaded.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert
+Disable verification of our own server certificates.
+
+When libvirtd starts it performs some sanity checks against its own
+certificates.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert
+Disable verification of client certificates.
+
+Client certificate verification is the primary authentication mechanism.
+Any client which does not present a certificate signed by the CA will be
+rejected.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list
+Whitelist of allowed x509 Distinguished Name.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames
+Whitelist of allowed SASL usernames. The format for username depends on
+the SASL authentication mechanism.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string tls-priority
+Override the compile time default TLS priority string. The default is
+usually "NORMAL" unless overridden at build time. Only set this is it
+is desired for libvirt to deviate from the global default settings.
+
+Defaults to @samp{"NORMAL"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-clients
+Maximum number of concurrent client connections to allow over all
+sockets combined.
+
+Defaults to @samp{5000}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients
+Maximum length of queue of connections waiting to be accepted by the
+daemon. Note, that some protocols supporting retransmission may obey
+this so that a later reattempt at connection succeeds.
+
+Defaults to @samp{1000}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients
+Maximum length of queue of accepted but not yet authenticated clients.
+Set this to zero to turn this feature off
+
+Defaults to @samp{20}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer min-workers
+Number of workers to start up initially.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-workers
+Maximum number of worker threads.
+
+If the number of active clients exceeds @code{min-workers}, then more
+threads are spawned, up to max_workers limit. Typically you'd want
+max_workers to equal maximum number of clients allowed.
+
+Defaults to @samp{20}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer prio-workers
+Number of priority workers. If all workers from above pool are stuck,
+some calls marked as high priority (notably domainDestroy) can be
+executed in this pool.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-requests
+Total global limit on concurrent RPC calls.
+
+Defaults to @samp{20}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests
+Limit on concurrent requests from a single client connection. To avoid
+one client monopolizing the server this should be a small fraction of
+the global max_requests and max_workers parameter.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers
+Same as @code{min-workers} but for the admin interface.
+
+Defaults to @samp{1}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers
+Same as @code{max-workers} but for the admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients
+Same as @code{max-clients} but for the admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients
+Same as @code{max-queued-clients} but for the admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests
+Same as @code{max-client-requests} but for the admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer log-level
+Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
+
+Defaults to @samp{3}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string log-filters
+Logging filters.
+
+A filter allows to select a different logging level for a given category
+of logs The format for a filter is one of:
+
+@itemize @bullet
+@item
+x:name
+
+@item
+x:+name
+
+@end itemize
+
+where @code{name} is a string which is matched against the category
+given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
+file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
+be a substring of the full category name, in order to match multiple
+similar categories), the optional "+" prefix tells libvirt to log stack
+trace for each message matching name, and @code{x} is the minimal level
+where matching messages should be logged:
+
+@itemize @bullet
+@item
+1: DEBUG
+
+@item
+2: INFO
+
+@item
+3: WARNING
+
+@item
+4: ERROR
+
+@end itemize
+
+Multiple filters can be defined in a single filters statement, they just
+need to be separated by spaces.
+
+Defaults to @samp{"3:remote 4:event"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string log-outputs
+Logging outputs.
+
+An output is one of the places to save logging information The format
+for an output can be:
+
+@table @code
+@item x:stderr
+output goes to stderr
+
+@item x:syslog:name
+use syslog for the output and use the given name as the ident
+
+@item x:file:file_path
+output to a file, with the given filepath
+
+@item x:journald
+output to journald logging system
+
+@end table
+
+In all case the x prefix is the minimal level, acting as a filter
+
+@itemize @bullet
+@item
+1: DEBUG
+
+@item
+2: INFO
+
+@item
+3: WARNING
+
+@item
+4: ERROR
+
+@end itemize
+
+Multiple outputs can be defined, they just need to be separated by
+spaces.
+
+Defaults to @samp{"3:stderr"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer audit-level
+Allows usage of the auditing subsystem to be altered
+
+@itemize @bullet
+@item
+0: disable all auditing
+
+@item
+1: enable auditing, only if enabled on host
+
+@item
+2: enable auditing, and exit if disabled on host.
+
+@end itemize
+
+Defaults to @samp{1}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging
+Send audit messages via libvirt logging infrastructure.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid
+Host UUID. UUID must not have all digits be the same.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source
+Source to read host UUID.
+
+@itemize @bullet
+@item
+@code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid}
+
+@item
+@code{machine-id}: fetch the UUID from @code{/etc/machine-id}
+
+@end itemize
+
+If @code{dmidecode} does not provide a valid UUID a temporary UUID will
+be generated.
+
+Defaults to @samp{"smbios"}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval
+A keepalive message is sent to a client after @code{keepalive_interval}
+seconds of inactivity to check if the client is still responding. If
+set to -1, libvirtd will never send keepalive requests; however clients
+can still send them and the daemon will send responses.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count
+Maximum number of keepalive messages that are allowed to be sent to the
+client without getting any response before the connection is considered
+broken.
+
+In other words, the connection is automatically closed approximately
+after @code{keepalive_interval * (keepalive_count + 1)} seconds since
+the last message received from the client. When @code{keepalive-count}
+is set to 0, connections will be automatically closed after
+@code{keepalive-interval} seconds of inactivity without sending any
+keepalive messages.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval
+Same as above but for admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count
+Same as above but for admin interface.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout
+Timeout for Open vSwitch calls.
+
+The @code{ovs-vsctl} utility is used for the configuration and its
+timeout option is set by default to 5 seconds to avoid potential
+infinite waits blocking libvirt.
+
+Defaults to @samp{5}.
+
+@end deftypevr
+
+@c %end of autogenerated docs
+
+@subsubheading Virtlog daemon
+The virtlogd service is a server side daemon component of libvirt that is
+used to manage logs from virtual machine consoles.
+
+This daemon is not used directly by libvirt client applications, rather it
+is called on their behalf by @code{libvirtd}. By maintaining the logs in a
+standalone daemon, the main @code{libvirtd} daemon can be restarted without
+risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec()
+itself upon receiving @code{SIGUSR1}, to allow live upgrades without downtime.
+
+@deffn {Scheme Variable} virtlog-service-type
+This is the type of the virtlog daemon.
+Its value must be a @code{virtlog-configuration}.
+
+@example
+(service virtlog-service-type
+ (virtlog-configuration
+ (max-clients 1000)))
+@end example
+@end deffn
+
+@deftypevr {@code{virtlog-configuration} parameter} integer log-level
+Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
+
+Defaults to @samp{3}.
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} string log-filters
+Logging filters.
+
+A filter allows to select a different logging level for a given category
+of logs The format for a filter is one of:
+
+@itemize @bullet
+@item
+x:name
+
+@item
+x:+name
+
+@end itemize
+
+where @code{name} is a string which is matched against the category
+given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
+file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
+be a substring of the full category name, in order to match multiple
+similar categories), the optional "+" prefix tells libvirt to log stack
+trace for each message matching name, and @code{x} is the minimal level
+where matching messages should be logged:
+
+@itemize @bullet
+@item
+1: DEBUG
+
+@item
+2: INFO
+
+@item
+3: WARNING
+
+@item
+4: ERROR
+
+@end itemize
+
+Multiple filters can be defined in a single filters statement, they just
+need to be separated by spaces.
+
+Defaults to @samp{"3:remote 4:event"}.
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} string log-outputs
+Logging outputs.
+
+An output is one of the places to save logging information The format
+for an output can be:
+
+@table @code
+@item x:stderr
+output goes to stderr
+
+@item x:syslog:name
+use syslog for the output and use the given name as the ident
+
+@item x:file:file_path
+output to a file, with the given filepath
+
+@item x:journald
+output to journald logging system
+
+@end table
+
+In all case the x prefix is the minimal level, acting as a filter
+
+@itemize @bullet
+@item
+1: DEBUG
+
+@item
+2: INFO
+
+@item
+3: WARNING
+
+@item
+4: ERROR
+
+@end itemize
+
+Multiple outputs can be defined, they just need to be separated by
+spaces.
+
+Defaults to @samp{"3:stderr"}.
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} integer max-clients
+Maximum number of concurrent client connections to allow over all
+sockets combined.
+
+Defaults to @samp{1024}.
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} integer max-size
+Maximum file size before rolling over.
+
+Defaults to @samp{2MB}
+
+@end deftypevr
+
+@deftypevr {@code{virtlog-configuration} parameter} integer max-backups
+Maximum number of backup files to keep.
+
+Defaults to @samp{3}
+
+@end deftypevr
+
@node Miscellaneous Services
@subsubsection Miscellaneous Services
+@cindex sysctl
+@subsubheading System Control Service
+
+The @code{(gnu services sysctl)} provides a service to configure kernel
+parameters at boot.
+
+@defvr {Scheme Variable} sysctl-service-type
+The service type for @command{sysctl}, which modifies kernel parameters
+under @file{/proc/sys/}. To enable IPv4 forwarding, it can be
+instantiated as:
+
+@example
+(service sysctl-service-type
+ (sysctl-configuration
+ (settings '(("net.ipv4.ip_forward" . "1")))))
+@end example
+@end defvr
+
+@deftp {Data Type} sysctl-configuration
+The data type representing the configuration of @command{sysctl}.
+
+@table @asis
+@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
+The @command{sysctl} executable to use.
+
+@item @code{settings} (default: @code{'()})
+An association list specifies kernel parameters and their values.
+@end table
+@end deftp
@cindex lirc
@subsubheading Lirc Service
automatically copied to the initrd.
@end deffn
-@node GRUB Configuration
-@subsection GRUB Configuration
+@node Bootloader Configuration
+@subsection Bootloader Configuration
-@cindex GRUB
+@cindex bootloader
@cindex boot loader
-The operating system uses GNU@tie{}GRUB as its boot loader
-(@pxref{Overview, overview of GRUB,, grub, GNU GRUB Manual}). It is
-configured using a @code{grub-configuration} declaration. This data type
-is exported by the @code{(gnu system grub)} module and described below.
+The operating system supports multiple bootloaders. The bootloader is
+configured using @code{bootloader-configuration} declaration. All the
+fields of this structure are bootloader agnostic except for one field,
+@code{bootloader} that indicates the bootloader to be configured and
+installed.
-@deftp {Data Type} grub-configuration
-The type of a GRUB configuration declaration.
+Some of the bootloaders do not honor every field of
+@code{bootloader-configuration}. For instance, the extlinux
+bootloader does not support themes and thus ignores the @code{theme}
+field.
+
+@deftp {Data Type} bootloader-configuration
+The type of a bootloader configuration declaration.
@table @asis
-@item @code{device}
-This is a string denoting the boot device. It must be a device name
-understood by the @command{grub-install} command, such as
-@code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
-GNU GRUB Manual}).
+@item @code{bootloader}
+@cindex EFI, bootloader
+@cindex UEFI, bootloader
+@cindex BIOS, bootloader
+The bootloader to use, as a @code{bootloader} object. For now
+@code{grub-bootloader}, @code{grub-efi-bootloader},
+@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported.
+@code{grub-efi-bootloader} allows to boot on modern systems using the
+@dfn{Unified Extensible Firmware Interface} (UEFI).
+
+Available bootloaders are described in @code{(gnu bootloader @dots{})}
+modules.
+
+@item @code{target}
+This is a string denoting the target onto which to install the
+bootloader. The exact interpretation depends on the bootloader in
+question; for @code{grub-bootloader}, for example, it should be a device
+name understood by the bootloader @command{installer} command, such as
+@code{/dev/sda} or @code{(hd0)} (for GRUB, @pxref{Invoking
+grub-install,,, grub, GNU GRUB Manual}). For
+@code{grub-efi-bootloader}, it should be the path to a mounted EFI file
+system.
@item @code{menu-entries} (default: @code{()})
A possibly empty list of @code{menu-entry} objects (see below), denoting
-entries to appear in the GRUB boot menu, in addition to the current
+entries to appear in the bootloader menu, in addition to the current
system entry and the entry pointing to previous system generations.
+generations.
@item @code{default-entry} (default: @code{0})
The index of the default boot menu entry. Index 0 is for the entry of the
The number of seconds to wait for keyboard input before booting. Set to
0 to boot immediately, and to -1 to wait indefinitely.
-@item @code{theme} (default: @var{%default-theme})
-The @code{grub-theme} object describing the theme to use.
-
-@item @code{grub} (default: @code{grub})
-@cindex EFI, bootloader
-@cindex UEFI, bootloader
-@cindex BIOS, bootloader
-The GRUB package to use. Currently either @code{grub}, for ``legacy''
-x86 BIOS systems, or @code{grub-efi}, for modern systems using the
-@dfn{Unified Extensible Firmware Interface} (UEFI).
+@item @code{theme} (default: @var{#f})
+The bootloader theme object describing the theme to use. If no theme
+is provided, some bootloaders might use a default theme, that's true
+for GRUB.
@item @code{terminal-outputs} (default: @code{'gfxterm})
-The output terminals used for the GRUB boot menu, as a list of symbols.
-These values are accepted: @code{console}, @code{serial},
-@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text},
-@code{morse}, and @code{pkmodem}. This field corresponds to the GRUB
-variable GRUB_TERMINAL_OUTPUT (@pxref{Simple configuration,,, grub,GNU
-GRUB manual}).
+The output terminals used for the bootloader boot menu, as a list of
+symbols. GRUB accepts the values: @code{console}, @code{serial},
+@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
+@code{mda_text}, @code{morse}, and @code{pkmodem}. This field
+corresponds to the GRUB variable GRUB_TERMINAL_OUTPUT (@pxref{Simple
+configuration,,, grub,GNU GRUB manual}).
@item @code{terminal-inputs} (default: @code{'()})
-The input terminals used for the GRUB boot menu, as a list of symbols.
-The default is the native platform terminal as determined by GRUB at
-run-time. These values are accepted: @code{console}, @code{serial},
-@code{serial_@{0-3@}}, @code{at_keyboard}, and @code{usb_keyboard}.
-This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT
-(@pxref{Simple configuration,,, grub,GNU GRUB manual}).
+The input terminals used for the bootloader boot menu, as a list of
+symbols. For GRUB, the default is the native platform terminal as
+determined at run-time. GRUB accepts the values: @code{console},
+@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
+@code{usb_keyboard}. This field corresponds to the GRUB variable
+GRUB_TERMINAL_INPUT (@pxref{Simple configuration,,, grub,GNU GRUB
+manual}).
@item @code{serial-unit} (default: @code{#f})
-The serial unit used by GRUB, as an integer from 0 to 3. The default
-value is chosen by GRUB at run-time; currently GRUB chooses 0, which
+The serial unit used by the bootloader, as an integer from 0 to 3.
+For GRUB it is choosen at run-time; currently GRUB chooses 0, which
corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
@item @code{serial-speed} (default: @code{#f})
-The speed of the serial interface, as an integer. The default value is
-chosen by GRUB at run-time; currently GRUB chooses 9600@tie{}bps
-(@pxref{Serial terminal,,, grub,GNU GRUB manual}).
+The speed of the serial interface, as an integer. For GRUB, the
+default value is chosen at run-time; currently GRUB chooses
+9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
@end table
@end deftp
Details below.
@deftp {Data Type} menu-entry
-The type of an entry in the GRUB boot menu.
+The type of an entry in the bootloader menu.
@table @asis
(file-append linux-libre "/bzImage")
@end example
-It is also possible to specify a device explicitly in the file path
-using GRUB's device naming convention (@pxref{Naming convention,,, grub,
-GNU GRUB manual}), for example:
+For GRUB, it is also possible to specify a device explicitly in the
+file path using GRUB's device naming convention (@pxref{Naming
+convention,,, grub, GNU GRUB manual}), for example:
@example
"(hd0,msdos1)/boot/vmlinuz"
@item @code{initrd}
A G-Expression or string denoting the file name of the initial RAM disk
to use (@pxref{G-Expressions}).
-
@item @code{device} (default: @code{#f})
-The device where the kernel and initrd are to be found---i.e., the GRUB
+The device where the kernel and initrd are to be found---i.e., for GRUB,
@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
This may be a file system label (a string), a file system UUID (a
-bytevector, @pxref{File Systems}), or @code{#f}, in which case GRUB will
-search the device containing the file specified by the @code{linux}
-field (@pxref{search,,, grub, GNU GRUB manual}). It must @emph{not} be
-an OS device name such as @file{/dev/sda1}.
-
-@item @code{device-mount-point} (default: @code{"/"})
-The mount point of the above device on the system. You probably do not
-need to change the default value. GuixSD uses it to strip the prefix of
-store file names for systems where @file{/gnu} or @file{/gnu/store} is
-on a separate partition.
+bytevector, @pxref{File Systems}), or @code{#f}, in which case
+the bootloader will search the device containing the file specified by
+the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It
+must @emph{not} be an OS device name such as @file{/dev/sda1}.
@end table
@end deftp
@c FIXME: Write documentation once it's stable.
-Themes are created using the @code{grub-theme} form, which is not
-documented yet.
+Fow now only GRUB has theme support. GRUB themes are created using
+the @code{grub-theme} form, which is not documented yet.
@defvr {Scheme Variable} %default-theme
-This is the default GRUB theme used by the operating system, with a
-fancy background image displaying the GNU and Guix logos.
+This is the default GRUB theme used by the operating system if no
+@code{theme} field is specified in @code{bootloader-configuration}
+record.
+
+It comes with a fancy background image displaying the GNU and Guix
+logos.
@end defvr
overwritten. This behavior mirrors that of @command{guix package}
(@pxref{Invoking guix package}).
-It also adds a GRUB menu entry for the new OS configuration, and moves
-entries for older configurations to a submenu---unless
-@option{--no-bootloader} is passed.
+It also adds a bootloader menu entry for the new OS configuration,
+---unless @option{--no-bootloader} is passed. For GRUB, it moves
+entries for older configurations to a submenu, allowing you to choose
+an older system generation at boot time should you need it.
@quotation Note
@c The paragraph below refers to the problem discussed at
@item switch-generation
@cindex generations
Switch to an existing system generation. This action atomically
-switches the system profile to the specified system generation. It also
-rearranges the system's existing GRUB menu entries. It makes the menu
-entry for the specified system generation the default, and it moves the
-entries for the other generations to a submenu. The next time the
-system boots, it will use the specified system generation.
+switches the system profile to the specified system generation. It
+also rearranges the system's existing bootloader menu entries. It
+makes the menu entry for the specified system generation the default,
+and it moves the entries for the other generatiors to a submenu, if
+supported by the bootloader being used. The next time the system
+boots, it will use the specified system generation.
+
+The bootloader itself is not being reinstalled when using this
+command. Thus, the installed bootloader is used with an updated
+configuration file.
The target generation can be specified explicitly by its generation
number. For example, the following invocation would switch to system
@end example
Currently, the effect of invoking this action is @emph{only} to switch
-the system profile to an existing generation and rearrange the GRUB menu
-entries. To actually start using the target system generation, you must
-reboot after running this action. In the future, it will be updated to
-do the same things as @command{reconfigure}, like activating and
-deactivating services.
+the system profile to an existing generation and rearrange the
+bootloader menu entries. To actually start using the target system
+generation, you must reboot after running this action. In the future,
+it will be updated to do the same things as @command{reconfigure},
+like activating and deactivating services.
This action will fail if the specified generation does not exist.
needed for the system to operate correctly---e.g., the @file{/etc},
@file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
-This command also installs GRUB on the device specified in
-@file{my-os-config}, unless the @option{--no-bootloader} option was passed.
+This command also installs bootloader on the target specified in
+@file{my-os-config}, unless the @option{--no-bootloader} option was
+passed.
@item vm
@cindex virtual machine
@anchor{guix system vm}
Build a virtual machine that contains the operating system declared in
@var{file}, and return a script to run that virtual machine (VM).
-Arguments given to the script are passed to QEMU.
+Arguments given to the script are passed to QEMU as in the example
+below, which enables networking and requests 1@tie{}GiB of RAM for the
+emulated machine:
+
+@example
+$ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user
+@end example
The VM shares its store with the host system.
@item vm-image
@itemx disk-image
Return a virtual machine or disk image of the operating system declared
-in @var{file} that stands alone. Use the @option{--image-size} option
-to specify the size of the image.
+in @var{file} that stands alone. By default, @command{guix system}
+estimates the size of the image needed to store the system, but you can
+use the @option{--image-size} option to specify a value.
+
+You can specify the root file system type by using the
+@option{--file-system-type} option. It defaults to @code{ext4}.
When using @code{vm-image}, the returned image is in qcow2 format, which
the QEMU emulator can efficiently use. @xref{Running GuixSD in a VM},
Return the derivation file name of the given operating system without
building anything.
+@item --file-system-type=@var{type}
+@itemx -t @var{type}
+For the @code{disk-image} action, create a file system of the given
+@var{type} on the image.
+
+When this option is omitted, @command{guix system} uses @code{ext4}.
+
+@cindex ISO-9660 format
+@cindex CD image format
+@cindex DVD image format
+@code{--file-system-type=iso9660} produces an ISO-9660 image, suitable
+for burning on CDs and DVDs.
+
@item --image-size=@var{size}
For the @code{vm-image} and @code{disk-image} actions, create an image
of the given @var{size}. @var{size} may be a number of bytes, or it may
include a unit as a suffix (@pxref{Block size, size specifications,,
coreutils, GNU Coreutils}).
+When this option is omitted, @command{guix system} computes an estimate
+of the image size as a function of the size of the system declared in
+@var{file}.
+
@item --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
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:
+bootloader boot menu:
@table @code
HCoop / jackhill / guix / guix.git / blobdiff