@c Identifier of the OpenPGP key used to sign tarballs and such.
@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
-@set KEY-SERVER pool.sks-keyservers.net
+@set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=15145
@c Base URL for downloads.
@set BASE-URL https://ftp.gnu.org/gnu/guix
Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
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, 2017, 2019 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
Copyright @copyright{} 2018 Oleg Pykhalov@*
Copyright @copyright{} 2018 Mike Gerwitz@*
Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
-Copyright @copyright{} 2018 Gábor Boskovits@*
-Copyright @copyright{} 2018 Florian Pelz@*
+Copyright @copyright{} 2018, 2019 Gábor Boskovits@*
+Copyright @copyright{} 2018, 2019 Florian Pelz@*
Copyright @copyright{} 2018 Laura Lazzati@*
Copyright @copyright{} 2018 Alex Vong@*
+Copyright @copyright{} 2019 Josh Holland@*
+Copyright @copyright{} 2019 Diego Nicola Barbato@*
+Copyright @copyright{} 2019 Ivan Petkov@*
+Copyright @copyright{} 2019 Jakob L. Kreuze@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
* guix pull: (guix)Invoking guix pull. Update the list of available packages.
* guix system: (guix)Invoking guix system. Manage the operating system configuration.
+* guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts.
@end direntry
@dircategory Software development
@c translation.
This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
-Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}), and
-Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}). If you
+Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
+Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and
+Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you
would like to translate it in your native language, consider joining the
@uref{https://translationproject.org/domain/guix-manual.html, Translation
Project}.
* Initial RAM Disk:: Linux-Libre bootstrapping.
* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
+* Invoking guix deploy:: Deploying a system configuration to a remote host.
* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
@cindex Guix System
Guix comes with a distribution of the GNU system consisting entirely of
free software@footnote{The term ``free'' here refers to the
-@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to
+@url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to
users of that software}.}. The
distribution can be installed on its own (@pxref{System Installation}),
but it is also possible to install Guix as a package manager on top of
The distribution provides core GNU packages such as GNU libc, GCC, and
Binutils, as well as many GNU and non-GNU applications. The complete
list of available packages can be browsed
-@url{http://www.gnu.org/software/guix/packages,on-line} or by
+@url{https://www.gnu.org/software/guix/packages,on-line} or by
running @command{guix package} (@pxref{Invoking guix package}):
@example
and Linux-Libre kernel.
@item aarch64-linux
-little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
-currently in an experimental stage, with limited support.
-@xref{Contributing}, for how to help!
+little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
@item mips64el-linux
little-endian 64-bit MIPS processors, specifically the Loongson series,
-n32 ABI, and Linux-Libre kernel.
+n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
+supported; in particular, the project's build farms no longer provide
+substitutes for this architecture.
@end table
then run this command to import it:
@example
-$ gpg --keyserver @value{KEY-SERVER} \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+$ wget @value{OPENPGP-SIGNING-KEY-URL} \
+ -qO - | gpg --import -
@end example
@noindent
and rerun the @code{gpg --verify} command.
+
+Take note that a warning like ``This key is not certified with a trusted
+signature!'' is normal.
+
@c end authentication part
@item
@example
# cd /tmp
# tar --warning=no-timestamp -xf \
- guix-binary-@value{VERSION}.@var{system}.tar.xz
+ /path/to/guix-binary-@value{VERSION}.@var{system}.tar.xz
# mv var/guix /var/ && mv gnu /
@end example
@c files into place.
@c
@c See this thread for more information:
-@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
+@c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
@example
# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
GNU Guix depends on the following packages:
@itemize
-@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
+@item @url{https://gnu.org/software/guile/, GNU Guile}, version 2.2.x;
@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
0.1.0 or later;
@item
-@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings
+@uref{https://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 @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON};
-@item @url{http://zlib.net, zlib};
-@item @url{http://www.gnu.org/software/make/, GNU Make}.
+@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON} 3.x;
+@item @url{https://zlib.net, zlib};
+@item @url{https://www.gnu.org/software/make/, GNU Make}.
@end itemize
The following dependencies are optional:
@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
version 0.10.2 or later.
+@item
+When @url{https://www.nongnu.org/lzip/lzlib.html, lzlib} is available, lzlib
+substitutes can be used and @command{guix publish} can compress substitutes
+with lzlib.
+
@item
When @url{http://www.bzip.org, libbz2} is available,
@command{guix-daemon} can use it to compress build logs.
following packages are also needed:
@itemize
-@item @url{http://gnupg.org/, GNU libgcrypt};
-@item @url{http://sqlite.org, SQLite 3};
-@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
+@item @url{https://gnupg.org/, GNU libgcrypt};
+@item @url{https://sqlite.org, SQLite 3};
+@item @url{https://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize
inadvertently corrupt your store (@pxref{The Store}).
@cindex Nix, compatibility
-When a working installation of @url{http://nixos.org/nix/, the Nix package
+When a working installation of @url{https://nixos.org/nix/, the Nix package
manager} is available, you
can instead configure Guix with @code{--disable-daemon}. In that case,
Nix replaces the three dependencies above.
On a GNU/Linux system, a build user pool may be created like this (using
Bash syntax and the @code{shadow} commands):
-@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
+@c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
@c for why `-G' is needed.
@example
# groupadd --system guixbuild
then run this command to import it:
@example
-$ gpg --keyserver @value{KEY-SERVER} \
- --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
+$ wget @value{OPENPGP-SIGNING-KEY-URL} \
+ -qO - | gpg --import -
@end example
@noindent
and rerun the @code{gpg --verify} command.
+
+Take note that a warning like ``This key is not certified with a trusted
+signature!'' is normal.
+
@c end duplication
This image contains the tools necessary for an installation.
ip a
@end example
-@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
+@c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
Wired interfaces have a name starting with @samp{e}; for example, the
interface corresponding to the first on-board Ethernet controller is
called @samp{eno1}. Wireless interfaces have a name starting with
virtual private server (VPS) rather than on your beloved machine, this
section is for you.
-To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a
+To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a
disk image, follow these steps:
@enumerate
Boot the USB installation image in an VM:
@example
-qemu-system-x86_64 -m 1024 -smp 1 \
+qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
-net user -net nic,model=virtio -boot menu=on \
-drive file=guix-system-install-@value{VERSION}.@var{system}.iso \
-drive file=guixsd.img
@end example
-The ordering of the drives matters.
+The ordering of the drives matters. @code{-enable-kvm} is optional, but
+significantly improves performance, @pxref{Running Guix in a VM}.
In the VM console, quickly press the @kbd{F12} key to enter the boot
menu. Then press the @kbd{2} key and the @kbd{RET} key to validate your
@section Building the Installation Image for ARM Boards
Many ARM boards require a specific variant of the
-@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
+@uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
If you build a disk image and the bootloader is not available otherwise
(on another boot drive etc), it's advisable to build an image that
@node Official Substitute Server
@subsection Official Substitute Server
-@cindex hydra
@cindex build farm
The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm
that builds packages from Guix continuously for some
# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub
@end example
-@quotation Note
-Similarly, the @file{hydra.gnu.org.pub} file contains the public key
-of an independent build farm also run by the project, reachable at
-@indicateurl{https://mirror.hydra.gnu.org}.
-@end quotation
-
Once this is in place, the output of a command like @code{guix build}
should change from something like:
on channels that you don't control, and you should aim to keep the number of
dependencies to a minimum.
+@cindex subdirectory, channels
+@subsection Package Modules in a Sub-directory
+
+As a channel author, you may want to keep your channel modules in a
+sub-directory. If your modules are in the sub-directory @file{guix}, you must
+add a meta-data file @file{.guix-channel} that contains:
+
+@lisp
+(channel
+ (version 0)
+ (directory "guix"))
+@end lisp
+
@subsection Replicating Guix
@cindex pinning, channels
@example
guix archive --export -r $(readlink -f ~/.guix-profile) | \
- ssh the-machine guix-archive --import
+ ssh the-machine guix archive --import
@end example
@noindent
The list of authorized keys is kept in the human-editable file
@file{/etc/guix/acl}. The file contains
-@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
+@url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
s-expressions''} and is structured as an access-control list in the
-@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
+@url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
(SPKI)}.
@item --extract=@var{directory}
and each of the user fields, this is only one useful component of a
broader privacy/anonymity solution---not one in and of itself.
+@item --no-cwd
+For containers, the default behavior is to share the current working
+directory with the isolated container and immediately change to that
+directory within the container. If this is undesirable, @code{--no-cwd}
+will cause the current working directory to @emph{not} be automatically
+shared and will change to the user's home directory within the container
+instead. See also @code{--user}.
+
@item --expose=@var{source}[=@var{target}]
For containers, expose the file system @var{source} from the host system
as the read-only file system @var{target} within the container. If
@noindent
The result is a SquashFS file system image that can either be mounted or
directly be used as a file system container image with the
-@uref{http://singularity.lbl.gov, Singularity container execution
+@uref{https://singularity.lbl.gov, Singularity container execution
environment}, using commands like @command{singularity shell} or
@command{singularity exec}.
run-time overhead every time a system call is made.
@end quotation
+@cindex entry point, for Docker images
+@item --entry-point=@var{command}
+Use @var{command} as the @dfn{entry point} of the resulting pack, if the pack
+format supports it---currently @code{docker} and @code{squashfs} (Singularity)
+support it. @var{command} must be relative to the profile contained in the
+pack.
+
+The entry point specifies the command that tools like @code{docker run} or
+@code{singularity run} automatically start by default. For example, you can
+do:
+
+@example
+guix pack -f docker --entry-point=bin/guile guile
+@end example
+
+The resulting pack can easily be loaded and @code{docker run} with no extra
+arguments will spawn @code{bin/guile}:
+
+@example
+docker load -i pack.tar.gz
+docker run @var{image-id}
+@end example
+
@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.
Recording such ``silent'' metadata in the output thus potentially breaks the
source-to-binary bitwise reproducibility property.
+@item --root=@var{file}
+@itemx -r @var{file}
+@cindex garbage collector root, for packs
+Make @var{file} a symlink to the resulting pack, and register it as a garbage
+collector root.
+
@item --localstatedir
@itemx --profile-name=@var{name}
Include the ``local state directory'', @file{/var/guix}, in the resulting
(inputs `(("gawk" ,gawk)))
(synopsis "Hello, GNU world: An example GNU package")
(description "Guess what GNU Hello prints!")
- (home-page "http://www.gnu.org/software/hello/")
+ (home-page "https://www.gnu.org/software/hello/")
(license gpl3+)))
@end example
@var{target} must be a valid GNU triplet denoting the target hardware
and operating system, such as @code{"mips64el-linux-gnu"}
-(@pxref{Configuration Names, GNU configuration triplets,, configure, GNU
-Configure and Build System}).
+(@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
@end deffn
@cindex package transformations
@defvr {Scheme Variable} ant-build-system
This variable is exported by @code{(guix build-system ant)}. It
implements the build procedure for Java packages that can be built with
-@url{http://ant.apache.org/, Ant build tool}.
+@url{https://ant.apache.org/, Ant build tool}.
It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
provided by the @code{icedtea} package to the set of inputs. Different
supports builds of packages using Cargo, the build tool of the
@uref{https://www.rust-lang.org, Rust programming language}.
-In its @code{configure} phase, this build system replaces dependencies
-specified in the @file{Carto.toml} file with inputs to the Guix package.
-The @code{install} phase installs the binaries, and it also installs the
-source code and @file{Cargo.toml} file.
+It adds @code{rustc} and @code{cargo} to the set of inputs.
+A different Rust package can be specified with the @code{#:rust} parameter.
+
+Regular cargo dependencies should be added to the package definition via the
+@code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
+spec can be a package or a source definition. Note that the spec must
+evaluate to a path to a gzipped tarball which includes a @code{Cargo.toml}
+file at its root, or it will be ignored. Similarly, cargo dev-dependencies
+should be added to the package definition via the
+@code{#:cargo-development-inputs} parameter.
+
+In its @code{configure} phase, this build system will make any source inputs
+specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
+parameters available to cargo. The @code{update-cargo-lock} phase will,
+when there is a @code{Cargo.lock} file, update the @code{Cargo.lock} file
+with the inputs and their versions available at build time. The
+@code{install} phase installs any crate the binaries if they are defined by
+the crate.
@end defvr
@cindex Clojure (programming language)
@defvr {Scheme Variable} cmake-build-system
This variable is exported by @code{(guix build-system cmake)}. It
implements the build procedure for packages using the
-@url{http://www.cmake.org, CMake build tool}.
+@url{https://www.cmake.org, CMake build tool}.
It automatically adds the @code{cmake} package to the set of inputs.
Which package is used can be specified with the @code{#:cmake}
@defvr {Scheme Variable} r-build-system
This variable is exported by @code{(guix build-system r)}. It
-implements the build procedure used by @uref{http://r-project.org, R}
+implements the build procedure used by @uref{https://r-project.org, R}
packages, which essentially is little more than running @code{R CMD
INSTALL --library=/gnu/store/@dots{}} in an environment where
@code{R_LIBS_SITE} contains the paths to all R package inputs. Tests
@end defvr
@defvr {Scheme Variable} rakudo-build-system
-This variable is exported by @code{(guix build-system rakudo)} It
+This variable is exported by @code{(guix build-system rakudo)}. It
implements the build procedure used by @uref{https://rakudo.org/,
Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
@defvr {Scheme Variable} meson-build-system
This variable is exported by @code{(guix build-system meson)}. It
implements the build procedure for packages that use
-@url{http://mesonbuild.com, Meson} as their build system.
+@url{https://mesonbuild.com, Meson} as their build system.
It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
of inputs, and they can be changed with the parameters @code{#:meson}
linux-module-build-system, use the key #:linux to specify it).
@end defvr
+@defvr {Scheme Variable} node-build-system
+This variable is exported by @code{(guix build-system node)}. It
+implements the build procedure used by @uref{http://nodejs.org,
+Node.js}, which implements an approximation of the @code{npm install}
+command, followed by an @code{npm test} command.
+
+Which Node.js package is used to interpret the @code{npm} commands can
+be specified with the @code{#:node} parameter which defaults to
+@code{node}.
+@end defvr
+
Lastly, for packages that do not need anything as sophisticated, a
``trivial'' build system is provided. It is trivial in the sense that
it provides basically no support: it does not pull any implicit inputs,
extra space on the file system so that the garbage collector can still
operate should the disk become full. Return a server object.
-@var{file} defaults to @var{%default-socket-path}, which is the normal
+@var{file} defaults to @code{%default-socket-path}, which is the normal
location given the options that were passed to @command{configure}.
@end deffn
resulting store path.
@end deffn
-@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
-Build @var{derivations} (a list of @code{<derivation>} objects or
-derivation paths), and return when the worker is done building them.
-Return @code{#t} on success.
+@deffn {Scheme Procedure} build-derivations @var{store} @var{derivations} @
+ [@var{mode}]
+Build @var{derivations}, a list of @code{<derivation>} objects, @file{.drv}
+file names, or derivation/output pairs, using the specified
+@var{mode}---@code{(build-mode normal)} by default.
@end deffn
Note that the @code{(guix monads)} module provides a monad as well as
@end deffn
@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
- [#:guile (default-guile)] [#:module-path %load-path]
+ [#:guile (default-guile)] [#:module-path %load-path] @
+ [#:system (%current-system)] [#:target #f]
Return an executable script @var{name} that runs @var{exp} using
@var{guile}, with @var{exp}'s imported modules in its search path.
Look up @var{exp}'s modules in @var{module-path}.
@item --with-commit=@var{package}=@var{commit}
This is similar to @code{--with-branch}, except that it builds from
@var{commit} rather than the tip of a branch. @var{commit} must be a valid
-Git commit SHA1 identifier.
+Git commit SHA1 identifier or a tag.
@end table
@node Additional Build Options
@item --target=@var{triplet}
@cindex cross-compilation
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
-as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
+as @code{"mips64el-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
configuration triplets,, autoconf, Autoconf}).
@anchor{build-check}
@cindex CRAN
@cindex Bioconductor
Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
-central repository for the @uref{http://r-project.org, GNU@tie{}R
+central repository for the @uref{https://r-project.org, GNU@tie{}R
statistical and graphical environment}.
Information is extracted from the @code{DESCRIPTION} file of the package.
@item texlive
@cindex TeX Live
@cindex CTAN
-Import metadata from @uref{http://www.ctan.org/, CTAN}, the
+Import metadata from @uref{https://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}.
"synopsis": "Hello, GNU world: An example GNU package",
"description": "GNU Hello prints a greeting.",
"license": "GPL-3.0+",
- "native-inputs": ["gcc@@6"]
+ "native-inputs": ["gettext"]
@}
@end example
@item nix
Import metadata from a local copy of the source of the
-@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
+@uref{https://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This
relies on the @command{nix-instantiate} command of
-@uref{http://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
+@uref{https://nixos.org/nix/, Nix}.}. Package definitions in Nixpkgs are
typically written in a mixture of Nix-language and Bash code. This
command only imports the high-level package structure that is written in
the Nix language. It normally includes all the basic fields of a
are:
@itemize -
@item
-@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
+@uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
identifier. This is the default.
Packages from @code{elpa.gnu.org} are signed with one of the keys
signatures,, emacs, The GNU Emacs Manual}).
@item
-@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
+@uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
@code{melpa-stable} identifier.
@item
-@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
+@uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa}
identifier.
@end itemize
@item kernel.org
the updater for packages hosted on kernel.org;
@item elpa
-the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
+the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
@item cran
the updater for @uref{https://cran.r-project.org/, CRAN} packages;
@item bioconductor
the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
@item cpan
-the updater for @uref{http://www.cpan.org/, CPAN} packages;
+the updater for @uref{https://www.cpan.org/, CPAN} packages;
@item pypi
the updater for @uref{https://pypi.python.org, PyPI} packages.
@item gem
(cpe-version . "2.3")))
@end example
-@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
+@c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
Some entries in the CVE database do not specify which version of a
package they apply to, and would thus ``stick around'' forever. Package
developers who found CVE alerts and verified they can be ignored can
produced by @command{guix size}}
This option requires that
-@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
+@uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
installed and visible in Guile's module search path. When that is not
the case, @command{guix size} fails as it tries to load it.
mental model of the package DAG, so the @command{guix graph} command
provides a visual representation of the DAG. By default,
@command{guix graph} emits a DAG representation in the input format of
-@uref{http://www.graphviz.org/, Graphviz}, so its output can be passed
+@uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
directly to the @command{dot} command of Graphviz. It can also emit an
HTML page with embedded JavaScript code to display a ``chord diagram''
in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
emit Cypher queries to construct a graph in a graph database supporting
-the @uref{http://www.opencypher.org/, openCypher} query language.
+the @uref{https://www.opencypher.org/, openCypher} query language.
The general syntax is:
@example
When @command{guix publish} runs, it spawns an HTTP server which allows
anyone with network access to obtain substitutes from it. This means
that any machine running Guix can also act as if it were a build farm,
-since the HTTP interface is compatible with Hydra, the software behind
+since the HTTP interface is compatible with Cuirass, the software behind
the @code{@value{SUBSTITUTE-SERVER}} build farm.
For security, each substitute is signed, allowing recipients to check
Change privileges to @var{user} as soon as possible---i.e., once the
server socket is open and the signing key has been read.
-@item --compression[=@var{level}]
-@itemx -C [@var{level}]
-Compress data using the given @var{level}. When @var{level} is zero,
-disable compression. The range 1 to 9 corresponds to different gzip
-compression levels: 1 is the fastest, and 9 is the best (CPU-intensive).
-The default is 3.
+@item --compression[=@var{method}[:@var{level}]]
+@itemx -C [@var{method}[:@var{level}]]
+Compress data using the given @var{method} and @var{level}. @var{method} is
+one of @code{lzip} and @code{gzip}; when @var{method} is omitted, @code{gzip}
+is used.
+
+When @var{level} is zero, disable compression. The range 1 to 9 corresponds
+to different compression levels: 1 is the fastest, and 9 is the best
+(CPU-intensive). The default is 3.
+
+Usually, @code{lzip} compresses noticeably better than @code{gzip} for a small
+increase in CPU usage; see
+@uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip Web
+page}.
Unless @option{--cache} is used, compression occurs on the fly and
the compressed streams are not
allows @command{guix publish} to add @code{Content-Length} HTTP header
to its responses.
+This option can be repeated, in which case every substitute gets compressed
+using all the selected methods, and all of them are advertised. This is
+useful when users may not support all the compression methods: they can select
+the one they support.
+
@item --cache=@var{directory}
@itemx -c @var{directory}
Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
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.
+The general syntax is:
+
+@example
+guix weather @var{options}@dots{} [@var{packages}@dots{}]
+@end example
+
+When @var{packages} is omitted, @command{guix weather} checks the availability
+of substitutes for @emph{all} the packages, or for those specified with
+@option{--manifest}; otherwise it only considers the specified packages. It
+is also possible to query specific system types with @option{--system}. The
+available options are listed below.
@table @code
@item --substitute-urls=@var{urls}
* Initial RAM Disk:: Linux-Libre bootstrapping.
* Bootloader Configuration:: Configuring the boot loader.
* Invoking guix system:: Instantiating a system configuration.
+* Invoking guix deploy:: Deploying a system configuration to a remote host.
* Running Guix in a VM:: How to run Guix System in a virtual machine.
* Defining Services:: Adding new service definitions.
@end menu
The @code{packages} field lists packages that will be globally visible
on the system, for all user accounts---i.e., in every user's @code{PATH}
environment variable---in addition to the per-user profiles
-(@pxref{Invoking guix package}). The @var{%base-packages} variable
+(@pxref{Invoking guix package}). The @code{%base-packages} variable
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},
Reference, @code{modify-services}}) to modify the list.
For example, suppose you want to modify @code{guix-daemon} and Mingetty
-(the console log-in) in the @var{%base-services} list (@pxref{Base
+(the console log-in) in the @code{%base-services} list (@pxref{Base
Services, @code{%base-services}}). To do that, you can write the
following in your operating system declaration:
This changes the configuration---i.e., the service parameters---of the
@code{guix-service-type} instance, and that of all the
-@code{mingetty-service-type} instances in the @var{%base-services} list.
+@code{mingetty-service-type} instances in the @code{%base-services} list.
Observe how this is accomplished: first, we arrange for the original
configuration to be bound to the identifier @code{config} in the
@var{body}, and then we write the @var{body} so that it evaluates to the
as returned by the @command{blkid} command.
@xref{Desktop Services}, for the exact list of services provided by
-@var{%desktop-services}. @xref{X.509 Certificates}, for background
+@code{%desktop-services}. @xref{X.509 Certificates}, for background
information about the @code{nss-certs} package that is used here.
-Again, @var{%desktop-services} is just a list of service objects. If
+Again, @code{%desktop-services} is just a list of service objects. If
you want to remove services from there, you can do so using the
procedures for list filtering (@pxref{SRFI-1 Filtering and
Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the
following expression returns a list that contains all the services in
-@var{%desktop-services} minus the Avahi service:
+@code{%desktop-services} minus the Avahi service:
@example
(remove (lambda (service)
kernel. This field is provided to support low-level customization and
should rarely be needed for casual use. @xref{Initial RAM Disk}.
-@item @code{firmware} (default: @var{%base-firmware})
+@item @code{firmware} (default: @code{%base-firmware})
@cindex firmware
List of firmware packages loadable by the operating system kernel.
also specified. @xref{Mapped Devices} and @ref{File Systems}.
@item @code{users} (default: @code{%base-user-accounts})
-@itemx @code{groups} (default: @var{%base-groups})
+@itemx @code{groups} (default: @code{%base-groups})
List of user accounts and groups. @xref{User Accounts}.
If the @code{users} list lacks a user account with UID@tie{}0, a
(activate-readline)")))
@end example
-@item @code{issue} (default: @var{%default-issue})
+@item @code{issue} (default: @code{%default-issue})
A string denoting the contents of the @file{/etc/issue} file, which is
displayed when users log in on a text console.
-@item @code{packages} (default: @var{%base-packages})
+@item @code{packages} (default: @code{%base-packages})
The set of packages installed in the global profile, which is accessible
at @file{/run/current-system/profile}.
The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
Library Reference Manual}). @xref{Locales}, for more information.
-@item @code{locale-definitions} (default: @var{%default-locale-definitions})
+@item @code{locale-definitions} (default: @code{%default-locale-definitions})
The list of locale definitions to be compiled and that may be used at
run time. @xref{Locales}.
to build the locale definitions. @xref{Locales}, for compatibility
considerations that justify this option.
-@item @code{name-service-switch} (default: @var{%default-nss})
+@item @code{name-service-switch} (default: @code{%default-nss})
Configuration of the libc name service switch (NSS)---a
@code{<name-service-switch>} object. @xref{Name Service Switch}, for
details.
-@item @code{services} (default: @var{%base-services})
+@item @code{services} (default: @code{%base-services})
A list of service objects denoting system services. @xref{Services}.
@cindex essential services
@item @code{charset} (default: @code{"UTF-8"})
The ``character set'' or ``code set'' for that locale,
-@uref{http://www.iana.org/assignments/character-sets, as defined by
+@uref{https://www.iana.org/assignments/character-sets, as defined by
IANA}.
@end table
This is the default value of the @code{services} field of
@code{operating-system} declarations. Usually, when customizing a
-system, you will want to append services to @var{%base-services}, like
+system, you will want to append services to @code{%base-services}, like
this:
@example
@item @code{kill-characters} (default: @code{#f})
This option accepts a string that should be interpreted to mean "ignore
-all previous characters" (also called a "kill" character) when the types
-their login name.
+all previous characters" (also called a "kill" character) when the user
+types their login name.
@item @code{chdir} (default: @code{#f})
This option accepts, as a string, a directory path that will be changed
(@pxref{Substitutes}).
@vindex %default-authorized-guix-keys
-@item @code{authorized-keys} (default: @var{%default-authorized-guix-keys})
+@item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
The list of authorized key files for archive imports, as a list of
string-valued gexps (@pxref{Invoking guix archive}). By default, it
contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}).
@item @code{use-substitutes?} (default: @code{#t})
Whether to use substitutes.
-@item @code{substitute-urls} (default: @var{%default-substitute-urls})
+@item @code{substitute-urls} (default: @code{%default-substitute-urls})
The list of URLs where to look for substitutes by default.
@item @code{max-silent-time} (default: @code{0})
@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
Run @var{udev}, which populates the @file{/dev} directory dynamically.
udev rules can be provided as a list of files through the @var{rules}
-variable. The procedures @var{udev-rule} and @var{file->udev-rule} from
+variable. The procedures @code{udev-rule} and @code{file->udev-rule} from
@code{(gnu services base)} simplify the creation of such rule files.
@end deffn
and paste text.
The value for services of this type must be a @code{gpm-configuration}
-(see below). This service is not part of @var{%base-services}.
+(see below). This service is not part of @code{%base-services}.
@end defvr
@deftp {Data Type} gpm-configuration
@anchor{guix-publish-service-type}
@deffn {Scheme Variable} guix-publish-service-type
This is the service type for @command{guix publish} (@pxref{Invoking
-guix publish}). Its value must be a @code{guix-configuration}
+guix publish}). Its value must be a @code{guix-publish-configuration}
object, as described below.
This assumes that @file{/etc/guix} already contains a signing key pair as
The host (and thus, network interface) to listen to. Use
@code{"0.0.0.0"} to listen on all the network interfaces.
-@item @code{compression-level} (default: @code{3})
-The gzip compression level at which substitutes are compressed. Use
-@code{0} to disable compression altogether, and @code{9} to get the best
-compression ratio at the expense of increased CPU usage.
+@item @code{compression} (default: @code{'(("gzip" 3))})
+This is a list of compression method/level tuple used when compressing
+substitutes. For example, to compress all substitutes with @emph{both} lzip
+at level 7 and gzip at level 9, write:
+
+@example
+'(("lzip" 7) ("gzip" 9))
+@end example
+
+Level 9 achieves the best compression ratio at the expense of increased CPU
+usage, whereas level 1 achieves fast compression.
+
+An empty list disables compression altogether.
@item @code{nar-path} (default: @code{"nar"})
The URL path at which ``nars'' can be fetched. @xref{Invoking guix
The package that provides the DHCP daemon. This package is expected to
provide the daemon at @file{sbin/dhcpd} relative to its output
directory. The default package is the
-@uref{http://www.isc.org/products/DHCP, ISC's DHCP server}.
+@uref{https://www.isc.org/products/DHCP, ISC's DHCP server}.
@item @code{config-file} (default: @code{#f})
The configuration file to use. This is required. It will be passed to
@code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
@end table
@end deftp
+@cindex USB_ModeSwitch
+@cindex Modeswitching
+
+@defvr {Scheme Variable} usb-modeswitch-service-type
+This is the service type for the
+@uref{http://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch} service. The
+value for this service type is a @code{usb-modeswitch-configuration} record.
+
+When plugged in, some USB modems (and other USB devices) initially present
+themselves as a read-only storage medium and not as a modem. They need to be
+@dfn{modeswitched} before they are usable. The USB_ModeSwitch service type
+installs udev rules to automatically modeswitch these devices when they are
+plugged in.
+
+This service is part of @code{%desktop-services} (@pxref{Desktop
+Services}).
+@end defvr
+
+@deftp {Data Type} usb-modeswitch-configuration
+Data type representing the configuration of USB_ModeSwitch.
+
+@table @asis
+@item @code{usb-modeswitch} (default: @code{usb-modeswitch})
+The USB_ModeSwitch package providing the binaries for modeswitching.
+
+@item @code{usb-modeswitch-data} (default: @code{usb-modeswitch-data})
+The package providing the device data and udev rules file used by
+USB_ModeSwitch.
+
+@item @code{config-file} (default: @code{#~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf")})
+Which config file to use for the USB_ModeSwitch dispatcher. By default the
+config file shipped with USB_ModeSwitch is used which disables logging to
+@file{/var/log} among other default settings. If set to @code{#f}, no config
+file is used.
+
+@end table
+@end deftp
+
@cindex NetworkManager
@defvr {Scheme Variable} network-manager-service-type
provided by currently active connections.
@item dnsmasq
-NetworkManager will run @code{dnsmasq} as a local caching nameserver,
-using a "split DNS" configuration if you are connected to a VPN, and
+NetworkManager will run @code{dnsmasq} as a local caching nameserver, using a
+@dfn{conditional forwarding} configuration if you are connected to a VPN, and
then update @code{resolv.conf} to point to the local nameserver.
+With this setting, you can share your network connection. For example when
+you want to share your network connection to another laptop @i{via} an
+Ethernet cable, you can open @command{nm-connection-editor} and configure the
+Wired connection's method for IPv4 and IPv6 to be ``Shared to other computers''
+and reestablish the connection (or reboot).
+
+You can also set up a @dfn{host-to-guest connection} to QEMU VMs
+(@pxref{Installing Guix in a VM}). With a host-to-guest connection, you can
+e.g.@: access a Web server running on the VM (@pxref{Web Services}) from a Web
+browser on your host system, or connect to the VM @i{via} SSH
+(@pxref{Networking Services, @code{openssh-service-type}}). To set up a
+host-to-guest connection, run this command once:
+
+@example
+nmcli connection add type tun \
+ connection.interface-name tap0 \
+ tun.mode tap tun.owner $(id -u) \
+ ipv4.method shared \
+ ipv4.addresses 172.28.112.1/24
+@end example
+
+Then each time you launch your QEMU VM (@pxref{Running Guix in a VM}), pass
+@option{-nic tap,ifname=tap0,script=no,downscript=no} to
+@command{qemu-system-...}.
+
@item none
NetworkManager will not modify @code{resolv.conf}.
@end table
A list of local IP address the ntpd daemon should use for outgoing queries.
@item @code{sensor} (default: @code{'()})
Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
-will listen to each sensor that acutally exists and ignore non-existant ones.
+will listen to each sensor that actually exists and ignore non-existent ones.
See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
information.
@item @code{server} (default: @var{%ntp-servers})
files.
@deffn {Scheme Variable} rsync-service-type
-This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon,
+This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
+The value for this service type is a
@command{rsync-configuration} record as in this example:
@example
@defvr {Scheme Variable} avahi-service-type
This is the service that runs @command{avahi-daemon}, a system-wide
mDNS/DNS-SD responder that allows for service discovery and
-``zero-configuration'' host name lookups (see @uref{http://avahi.org/}).
+``zero-configuration'' host name lookups (see @uref{https://avahi.org/}).
Its value must be a @code{zero-configuration} record---see below.
This service extends the name service cache daemon (nscd) so that it can
@end deftp
@deffn {Scheme Variable} openvswitch-service-type
-This is the type of the @uref{http://www.openvswitch.org, Open vSwitch}
+This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
service, whose value should be an @code{openvswitch-configuration}
object.
@end deffn
Like GDM, SLiM looks for session types described by @file{.desktop} files and
allows users to choose a session from the log-in screen using @kbd{F1}. It
also honors @file{~/.xsession} files.
+
+Unlike GDM, SLiM does not spawn the user session on a different VT after
+logging in, which means that you can only start one graphical session. If you
+want to be able to run multiple graphical sessions at the same time you have
+to add multiple SLiM services to your system services. The following example
+shows how to replace the default GDM service with two SLiM services on tty7
+and tty8.
+
+@lisp
+(use-modules (gnu services)
+ (gnu services desktop)
+ (gnu services xorg)
+ (srfi srfi-1)) ;for 'remove'
+
+(operating-system
+ ;; ...
+ (services (cons* (service slim-service-type (slim-configuration
+ (display ":0")
+ (vt "vt7")))
+ (service slim-service-type (slim-configuration
+ (display ":1")
+ (vt "vt8")))
+ (remove (lambda (service)
+ (eq? (service-kind service) gdm-service-type))
+ %desktop-services))))
+@end lisp
+
@end defvr
@deftp {Data Type} slim-configuration
@item @code{xorg-configuration} (default @code{(xorg-configuration)})
Configuration of the Xorg graphical server.
+@item @code{display} (default @code{":0"})
+The display on which to start the Xorg graphical server.
+
+@item @code{vt} (default @code{"vt7"})
+The VT on which to start the Xorg graphical server.
+
@item @code{xauth} (default: @code{xauth})
The XAuth package to use.
@item @code{default-path} (default "/run/current-system/profile/bin")
Default PATH to use.
-@item @code{minimum-uid} (default 1000)
-Minimum UID to display in SDDM.
+@item @code{minimum-uid} (default: 1000)
+Minimum UID displayed in SDDM and allowed for log-in.
-@item @code{maximum-uid} (default 2000)
-Maximum UID to display in SDDM
+@item @code{maximum-uid} (default: 2000)
+Maximum UID to display in SDDM.
@item @code{remember-last-user?} (default #t)
Remember last user.
@deffn {Scheme Procedure} set-xorg-configuration @var{config} @
[@var{login-manager-service-type}]
Tell the log-in manager (of type @var{login-manager-service-type}) to use
-@var{config}, an <xorg-configuration> record.
+@var{config}, an @code{<xorg-configuration>} record.
Since the Xorg configuration is embedded in the log-in manager's
configuration---e.g., @code{gdm-configuration}---this procedure provides a
@deftypevr {@code{files-configuration} parameter} log-location error-log
Defines the error log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
+error log generation. The value @code{stderr} causes log entries to be
sent to the standard error file when the scheduler is running in the
foreground, or to the system log daemon when run in the background. The
value @code{syslog} causes log entries to be sent to the system log
@deftypevr {@code{files-configuration} parameter} log-location page-log
Defines the page log filename. Specifying a blank filename disables
-access log generation. The value @code{stderr} causes log entries to be
+page log generation. The value @code{stderr} causes log entries to be
sent to the standard error file when the scheduler is running in the
foreground, or to the system log daemon when run in the background. The
value @code{syslog} causes log entries to be sent to the system log
environment and networking:
@defvr {Scheme Variable} %desktop-services
-This is a list of services that builds upon @var{%base-services} and
+This is a list of services that builds upon @code{%base-services} and
adds or adjusts services for a typical ``desktop'' setup.
In particular, it adds a graphical login manager (@pxref{X Window,
@code{gdm-service-type}}), 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}).
+(@pxref{Networking Services, @code{network-manager-service-type}}) with modem
+support (@pxref{Networking Services, @code{modem-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}
+The @code{%desktop-services} variable can be used as the @code{services}
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).
Configuration record for the GNOME desktop environment.
@table @asis
-@item @code{gnome} (default @code{gnome})
+@item @code{gnome} (default: @code{gnome})
The GNOME package to use.
@end table
@end deftp
desktop environment. Its value is an @code{xfce-desktop-configuration} object
(see below.)
-This service that adds the @code{xfce} package to the system profile, and
+This service adds the @code{xfce} package to the system profile, and
extends polkit with the ability for @code{thunar} to manipulate the file
system as root from within a user session, after the user has authenticated
with the administrator's password.
Configuration record for the Xfce desktop environment.
@table @asis
-@item @code{xfce} (default @code{xfce})
+@item @code{xfce} (default: @code{xfce})
The Xfce package to use.
@end table
@end deftp
Configuration record for the MATE desktop environment.
@table @asis
-@item @code{mate} (default @code{mate})
+@item @code{mate} (default: @code{mate})
The MATE package to use.
@end table
@end deftp
@deftp {Data Type} enlightenment-desktop-service-configuration
@table @asis
-@item @code{enlightenment} (default @code{enlightenment})
+@item @code{enlightenment} (default: @code{enlightenment})
The enlightenment package to use.
@end table
@end deftp
Return a service that runs the ``system bus'', using @var{dbus}, with
support for @var{services}.
-@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
+@uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
facility. Its system bus is used to allow system services to communicate
and to be notified of system-wide events.
@deffn {Scheme Procedure} polkit-service @
[#:polkit @var{polkit}]
Return a service that runs the
-@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
+@uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
management service}, which allows system administrators to grant access to
privileged operations in a structured way. By querying the Polkit service, a
privileged system component can know when it should grant additional
@end deffn
@defvr {Scheme Variable} upower-service-type
-Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, a
+Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
system-wide monitor for power consumption and battery levels, with the given
configuration settings.
@end deftp
@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
-Return a service for @uref{http://udisks.freedesktop.org/docs/latest/,
+Return a service for @uref{https://udisks.freedesktop.org/docs/latest/,
UDisks}, a @dfn{disk management} daemon that provides user interfaces with
notifications and ways to mount/unmount disks. Programs that talk to UDisks
include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
Return a service that runs @command{colord}, a system service with a D-Bus
interface to manage the color profiles of input and output devices such as
screens and scanners. It is notably used by the GNOME Color Manager graphical
-tool. See @uref{http://www.freedesktop.org/software/colord/, the colord web
+tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
site} for more information.
@end deffn
Defaults to @samp{#f}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords?
+@deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
In case of password mismatches, log the attempted password. Valid
values are no, plain and sha1. sha1 can be useful for detecting brute
force password attempts vs. user simply trying the same password over
and over again. You can also truncate the value to n chars by appending
":n" (e.g.@: sha1:6).
-Defaults to @samp{#f}.
+Defaults to @samp{"no"}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
@item @code{package} (default: @var{opensmtpd})
Package object of the OpenSMTPD SMTP server.
-@item @code{config-file} (default: @var{%default-opensmtpd-file})
+@item @code{config-file} (default: @code{%default-opensmtpd-file})
File-like object of the OpenSMTPD configuration file to use. By default
it listens on the loopback network interface, and allows for mail from
users and daemons on the local machine, as well as permitting email to
@end table
@end deftp
+@subsubheading Getmail service
+
+@cindex IMAP
+@cindex POP
+
+@deffn {Scheme Variable} getmail-service-type
+This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail}
+mail retriever, whose value should be an @code{getmail-configuration}.
+@end deffn
+
+Available @code{getmail-configuration} fields are:
+
+@deftypevr {@code{getmail-configuration} parameter} symbol name
+A symbol to identify the getmail service.
+
+Defaults to @samp{"unset"}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration} parameter} package package
+The getmail package to use.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration} parameter} string user
+The user to run getmail as.
+
+Defaults to @samp{"getmail"}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration} parameter} string group
+The group to run getmail as.
+
+Defaults to @samp{"getmail"}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration} parameter} string directory
+The getmail directory to use.
+
+Defaults to @samp{"/var/lib/getmail/default"}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration} parameter} getmail-configuration-file rcfile
+The getmail configuration file to use.
+
+Available @code{getmail-configuration-file} fields are:
+
+@deftypevr {@code{getmail-configuration-file} parameter} getmail-retriever-configuration retriever
+What mail account to retrieve mail from, and how to access that account.
+
+Available @code{getmail-retriever-configuration} fields are:
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} string type
+The type of mail retriever to use. Valid values include @samp{passwd}
+and @samp{static}.
+
+Defaults to @samp{"SimpleIMAPSSLRetriever"}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} string server
+Space separated list of arguments to the userdb driver.
+
+Defaults to @samp{unset}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} string username
+Space separated list of arguments to the userdb driver.
+
+Defaults to @samp{unset}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
+Space separated list of arguments to the userdb driver.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} string password
+Override fields from passwd.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} list password-command
+Override fields from passwd.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
+PEM-formatted key file to use for the TLS negotiation
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
+PEM-formatted certificate file to use for the TLS negotiation
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
+CA certificates to use
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
+Extra retriever parameters
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration-file} parameter} getmail-destination-configuration destination
+What to do with retrieved messages.
+
+Available @code{getmail-destination-configuration} fields are:
+
+@deftypevr {@code{getmail-destination-configuration} parameter} string type
+The type of mail destination. Valid values include @samp{Maildir},
+@samp{Mboxrd} and @samp{MDA_external}.
+
+Defaults to @samp{unset}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-destination-configuration} parameter} string-or-filelike path
+The path option for the mail destination. The behaviour depends on the
+chosen type.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-destination-configuration} parameter} parameter-alist extra-parameters
+Extra destination parameters
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration-file} parameter} getmail-options-configuration options
+Configure getmail.
+
+Available @code{getmail-options-configuration} fields are:
+
+@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer verbose
+If set to @samp{0}, getmail will only print warnings and errors. A
+value of @samp{1} means that messages will be printed about retrieving
+and deleting messages. If set to @samp{2}, getmail will print messages
+about each of it's actions.
+
+Defaults to @samp{1}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} boolean read-all
+If true, getmail will retrieve all available messages. Otherwise it
+will only retrieve messages it hasn't seen previously.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} boolean delete
+If set to true, messages will be deleted from the server after
+retrieving and successfully delivering them. Otherwise, messages will
+be left on the server.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-after
+Getmail will delete messages this number of days after seeing them, if
+they have not been delivered. This means messages will be left on the
+server this number of days after delivering them. A value of @samp{0}
+disabled this feature.
+
+Defaults to @samp{0}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-bigger-than
+Delete messages larger than this of bytes after retrieving them, even if
+the delete and delete-after options are disabled. A value of @samp{0}
+disables this feature.
+
+Defaults to @samp{0}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-bytes-per-session
+Retrieve messages totalling up to this number of bytes before closing
+the session with the server. A value of @samp{0} disables this feature.
+
+Defaults to @samp{0}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-message-size
+Don't retrieve messages larger than this number of bytes. A value of
+@samp{0} disables this feature.
+
+Defaults to @samp{0}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} boolean delivered-to
+If true, getmail will add a Delivered-To header to messages.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} boolean received
+If set, getmail adds a Received header to the messages.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} string message-log
+Getmail will record a log of its actions to the named file. A value of
+@samp{""} disables this feature.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-syslog
+If true, getmail will record a log of its actions using the system
+logger.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-verbose
+If true, getmail will log information about messages not retrieved and
+the reason for not retrieving them, as well as starting and ending
+information lines.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-options-configuration} parameter} parameter-alist extra-parameters
+Extra options to include.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@end deftypevr
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration} parameter} list idle
+A list of mailboxes that getmail should wait on the server for new mail
+notifications. This depends on the server supporting the IDLE
+extension.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{getmail-configuration} parameter} list environment-variables
+Environment variables to set for getmail.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
@subsubheading Mail Aliases Service
@cindex email aliases
@cindex IRC (Internet Relay Chat)
@cindex IRC gateway
-@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC
+@url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC
interface to a variety of messaging protocols such as XMPP.
@defvr {Scheme Variable} bitlbee-service-type
-This is the service type for the @url{http://bitlbee.org,BitlBee} IRC
+This is the service type for the @url{https://bitlbee.org,BitlBee} IRC
gateway daemon. Its value is a @code{bitlbee-configuration} (see
below).
Maximum size in bytes that a user can send in one image message.
@item @code{cert-required?} (default: @code{#f})
-If it is set to @code{#t} clients that use weak password authentification
+If it is set to @code{#t} clients that use weak password authentication
will not be accepted. Users must have completed the certificate wizard to join.
@item @code{remember-channel?} (default: @code{#f})
The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
Only the most commonly used ones are described here.
For a full list, and more detailed explanation of each, see the MIT
-@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
+@uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
documentation.
@end defvr
@deftp {Data Type} pam-krb5-configuration
-Data type representing the configuration of the Kerberos 5 PAM module
+Data type representing the configuration of the Kerberos 5 PAM module.
This type has the following parameters:
@table @asis
@item @code{pam-krb5} (default: @code{pam-krb5})
@end table
@end deftp
+@subsubheading Patchwork
+@cindex Patchwork
+Patchwork is a patch tracking system. It can collect patches sent to a
+mailing list, and display them in a web interface.
+
+@defvr {Scheme Variable} patchwork-service-type
+Service type for Patchwork.
+@end defvr
+
+The following example is an example of a minimal service for Patchwork, for
+the @code{patchwork.example.com} domain.
+
+@example
+(service patchwork-service-type
+ (patchwork-configuration
+ (domain "patchwork.example.com")
+ (settings-module
+ (patchwork-settings-module
+ (allowed-hosts (list domain))
+ (default-from-email "patchwork@@patchwork.example.com")))
+ (getmail-retriever-config
+ (getmail-retriever-configuration
+ (type "SimpleIMAPSSLRetriever")
+ (server "imap.example.com")
+ (port 993)
+ (username "patchwork")
+ (password-command
+ (list (file-append coreutils "/bin/cat")
+ "/etc/getmail-patchwork-imap-password"))
+ (extra-parameters
+ '((mailboxes . ("Patches"))))))))
+
+@end example
+
+There are three records for configuring the Patchwork service. The
+@code{<patchwork-configuration>} relates to the configuration for Patchwork
+within the HTTPD service.
+
+The @code{settings-module} field within the @code{<patchwork-configuration>}
+record can be populated with the @code{<patchwork-settings-module>} record,
+which describes a settings module that is generated within the Guix store.
+
+For the @code{database-configuration} field within the
+@code{<patchwork-settings-module>}, the
+@code{<patchwork-database-configuration>} must be used.
+
+@deftp {Data Type} patchwork-configuration
+Data type representing the Patchwork service configuration. This type has the
+following parameters:
+
+@table @asis
+@item @code{patchwork} (default: @code{patchwork})
+The Patchwork package to use.
+
+@item @code{domain}
+The domain to use for Patchwork, this is used in the HTTPD service virtual
+host.
+
+@item @code{settings-module}
+The settings module to use for Patchwork. As a Django application, Patchwork
+is configured with a Python module containing the settings. This can either be
+an instance of the @code{<patchwork-settings-module>} record, any other record
+that represents the settings in the store, or a directory outside of the
+store.
+
+@item @code{static-path} (default: @code{"/static/"})
+The path under which the HTTPD service should serve the static files.
+
+@item @code{getmail-retriever-config}
+The getmail-retriever-configuration record value to use with
+Patchwork. Getmail will be configured with this value, the messages will be
+delivered to Patchwork.
+
+@end table
+@end deftp
+
+@deftp {Data Type} patchwork-settings-module
+Data type representing a settings module for Patchwork. Some of these
+settings relate directly to Patchwork, but others relate to Django, the web
+framework used by Patchwork, or the Django Rest Framework library. This type
+has the following parameters:
+
+@table @asis
+@item @code{database-configuration} (default: @code{(patchwork-database-configuration)})
+The database connection settings used for Patchwork. See the
+@code{<patchwork-database-configuration>} record type for more information.
+
+@item @code{secret-key-file} (default: @code{"/etc/patchwork/django-secret-key"})
+Patchwork, as a Django web application uses a secret key for cryptographically
+signing values. This file should contain a unique unpredictable value.
+
+If this file does not exist, it will be created and populated with a random
+value by the patchwork-setup shepherd service.
+
+This setting relates to Django.
+
+@item @code{allowed-hosts}
+A list of valid hosts for this Patchwork service. This should at least include
+the domain specified in the @code{<patchwork-configuration>} record.
+
+This is a Django setting.
+
+@item @code{default-from-email}
+The email address from which Patchwork should send email by default.
+
+This is a Patchwork setting.
+
+@item @code{static-url} (default: @code{#f})
+The URL to use when serving static assets. It can be part of a URL, or a full
+URL, but must end in a @code{/}.
+
+If the default value is used, the @code{static-path} value from the
+@code{<patchwork-configuration>} record will be used.
+
+This is a Django setting.
+
+@item @code{admins} (default: @code{'()})
+Email addresses to send the details of errors that occur. Each value should
+be a list containing two elements, the name and then the email address.
+
+This is a Django setting.
+
+@item @code{debug?} (default: @code{#f})
+Whether to run Patchwork in debug mode. If set to @code{#t}, detailed error
+messages will be shown.
+
+This is a Django setting.
+
+@item @code{enable-rest-api?} (default: @code{#t})
+Whether to enable the Patchwork REST API.
+
+This is a Patchwork setting.
+
+@item @code{enable-xmlrpc?} (default: @code{#t})
+Whether to enable the XML RPC API.
+
+This is a Patchwork setting.
+
+@item @code{force-https-links?} (default: @code{#t})
+Whether to use HTTPS links on Patchwork pages.
+
+This is a Patchwork setting.
+
+@item @code{extra-settings} (default: @code{""})
+Extra code to place at the end of the Patchwork settings module.
+
+@end table
+@end deftp
+
+@deftp {Data Type} patchwork-database-configuration
+Data type representing the database configuration for Patchwork.
+
+@table @asis
+@item @code{engine} (default: @code{"django.db.backends.postgresql_psycopg2"})
+The database engine to use.
+
+@item @code{name} (default: @code{"patchwork"})
+The name of the database to use.
+
+@item @code{user} (default: @code{"httpd"})
+The user to connect to the database as.
+
+@item @code{password} (default: @code{""})
+The password to use when connecting to the database.
+
+@item @code{host} (default: @code{""})
+The host to make the database connection to.
+
+@item @code{port} (default: @code{""})
+The port on which to connect to the database.
+
+@end table
+@end deftp
+
@subsubheading FastCGI
@cindex fastcgi
@cindex fcgiwrap
@subsubheading Hpcguix-web
@cindex hpcguix-web
-The @uref{hpcguix-web, https://github.com/UMCUGenetics/hpcguix-web/}
+The @uref{https://github.com/UMCUGenetics/hpcguix-web/, hpcguix-web}
program is a customizable web interface to browse Guix packages,
initially designed for users of high-performance computing (HPC)
clusters.
key configuration in @file{/etc/knot/secrets.conf} and add this file
to the @code{includes} list.
+One can generate a secret tsig key (for nsupdate and zone transfers with the
+keymgr command from the knot package. Note that the package is not automatically
+installed by the service. The following example shows how to generate a new
+tsig key:
+
+@example
+keymgr -t mysecret > /etc/knot/secrets.conf
+chmod 600 /etc/knot/secrets.conf
+@end example
+
+Also note that the generated key will be named @var{mysecret}, so it is the
+name that needs to be used in the @var{key} field of the
+@code{knot-acl-configuration} record and in other places that need to refer
+to that key.
+
It can also be used to add configuration not supported by this interface.
@item @code{listen-v4} (default: @code{"0.0.0.0"})
The @code{(gnu services vpn)} module provides services related to
@dfn{virtual private networks} (VPNs). It provides a @emph{client} service for
-your machine to connect to a VPN, and a @emph{servire} service for your machine
+your machine to connect to a VPN, and a @emph{server} service for your machine
to host a VPN. Both services use @uref{https://openvpn.net/, OpenVPN}.
@deffn {Scheme Procedure} openvpn-client-service @
@item @code{port} (default: @code{8081})
Port number used by the HTTP server.
-@item --listen=@var{host}
+@item @code{host} (default: @code{"localhost"})
Listen on the network interface for @var{host}. The default is to
accept connections from localhost.
Contrary to @code{upower-service}, it is not a passive,
monitoring tool, as it will apply custom settings each time a new power
source is detected. More information can be found at
-@uref{http://linrunner.de/en/tlp/tlp.html, TLP home page}.
+@uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
@deffn {Scheme Variable} tlp-service-type
The service type for the TLP tool. Its value should be a valid
@deftypevr {@code{libvirt-configuration} parameter} string log-outputs
Logging outputs.
-An output is one of the places to save logging information The format
+An output is one of the places to save logging information. The format
for an output can be:
@table @code
@end deftp
The @code{git://} protocol lacks authentication. When you pull from a
-repository fetched via @code{git://}, you don't know that the data you
-receive was modified is really coming from the specified host, and you
-have your connection is subject to eavesdropping. It's better to use an
-authenticated and encrypted transport, such as @code{https}. Although Git allows you
+repository fetched via @code{git://}, you don't know whether the data you
+receive was modified or is even coming from the specified host, and your
+connection is subject to eavesdropping. It's better to use an authenticated
+and encrypted transport, such as @code{https}. Although Git allows you
to serve repositories using unsophisticated file-based web servers,
there is a faster protocol implemented by the @code{git-http-backend}
program. This program is the back-end of a proper Git web service. It
@cindex Gitolite service
@cindex Git, hosting
-@uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
+@uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
repositories on a central server.
Gitolite can handle multiple repositories and users, and supports flexible
The @code{(gnu services spice)} module provides the following service.
@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
-Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a daemon
+Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon
that enables sharing the clipboard with a vm and setting the guest display
resolution when the graphical console window resizes.
@end deffn
@cindex Docker
@subsubheading Docker Service
-The @code{(gnu services docker)} module provides the following service.
+The @code{(gnu services docker)} module provides the following services.
@defvr {Scheme Variable} docker-service-type
-This is the type of the service that runs @url{http://www.docker.com,Docker},
+This is the type of the service that runs @url{https://www.docker.com,Docker},
a daemon that can execute application bundles (sometimes referred to as
``containers'') in isolated environments.
@end table
@end deftp
+@cindex Audit
+@subsubheading Auditd Service
+
+The @code{(gnu services auditd)} module provides the following service.
+
+@defvr {Scheme Variable} auditd-service-type
+
+This is the type of the service that runs
+@url{https://people.redhat.com/sgrubb/audit/,auditd},
+a daemon that tracks security-relevant information on your system.
+
+Examples of things that can be tracked:
+
+@enumerate
+@item
+File accesses
+@item
+System calls
+@item
+Invoked commands
+@item
+Failed login attempts
+@item
+Firewall filtering
+@item
+Network access
+@end enumerate
+
+@command{auditctl} from the @code{audit} package can be used in order
+to add or remove events to be tracked (until the next reboot).
+In order to permanently track events, put the command line arguments
+of auditctl into @file{/etc/audit/audit.rules}.
+@command{aureport} from the @code{audit} package can be used in order
+to view a report of all recorded events.
+The audit daemon usually logs into the directory @file{/var/log/audit}.
+
+@end defvr
+
+@deftp {Data Type} auditd-configuration
+This is the data type representing the configuration of auditd.
+
+@table @asis
+
+@item @code{audit} (default: @code{audit})
+The audit package to use.
+
+@end table
+@end deftp
+
+@defvr {Scheme Variable} singularity-service-type
+This is the type of the service that allows you to run
+@url{https://www.sylabs.io/singularity/, Singularity}, a Docker-style tool to
+create and run application bundles (aka. ``containers''). The value for this
+service is the Singularity package to use.
+
+The service does not install a daemon; instead, it installs helper programs as
+setuid-root (@pxref{Setuid Programs}) such that unprivileged users can invoke
+@command{singularity run} and similar commands.
+@end defvr
+
+@cindex Nix
+@subsubheading Nix service
+
+The @code{(gnu services nix)} module provides the following service.
+
+@defvr {Scheme Variable} nix-service-type
+
+This is the type of the service that runs build daemon of the
+@url{https://nixos.org/nix/, Nix} package manager. Here is an example showing
+how to use it:
+
+@example
+(use-modules (gnu))
+(use-service-modules nix)
+(use-package-modules package-management)
+
+(operating-system
+ ;; @dots{}
+ (packages (append (list nix)
+ %base-packages))
+
+ (services (append (list (service nix-service-type))
+ %base-services)))
+@end example
+
+After @command{guix system reconfigure} configure Nix for your user:
+
+@itemize
+@item Add a Nix channel and update it. See
+@url{https://nixos.org/nix/manual/, Nix Package Manager Guide}.
+
+@item Create a symlink to your profile and activate Nix profile:
+@end itemize
+
+@example
+$ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile
+$ source /run/current-system/profile/etc/profile.d/nix.sh
+@end example
+
+@end defvr
+
@node Setuid Programs
@section Setuid Programs
@code{nss-certs}, which is a set of CA certificates provided as part of
Mozilla's Network Security Services.
-Note that it is @emph{not} part of @var{%base-packages}, so you need to
+Note that it is @emph{not} part of @code{%base-packages}, so you need to
explicitly add it. The @file{/etc/ssl/certs} directory, which is where
most applications and libraries look for certificates by default, points
to the certificates installed globally.
Note that, in this case, in addition to setting the
@code{name-service-switch} of the @code{operating-system} declaration,
you also need to use @code{avahi-service-type} (@pxref{Networking Services,
-@code{avahi-service-type}}), or @var{%desktop-services}, which includes it
+@code{avahi-service-type}}), or @code{%desktop-services}, which includes it
(@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible
to the name service cache daemon (@pxref{Base Services,
@code{nscd-service}}).
Available bootloaders are described in @code{(gnu bootloader @dots{})}
modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
of bootloaders for a wide range of ARM and AArch64 systems, using the
-@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
+@uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
@item @code{target}
This is a string denoting the target onto which to install the
is provided, some bootloaders might use a default theme, that's true
for GRUB.
-@item @code{terminal-outputs} (default: @code{'gfxterm})
+@item @code{terminal-outputs} (default: @code{'(gfxterm)})
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},
@quotation Note
@c The paragraph below refers to the problem discussed at
-@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
+@c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
It is highly recommended to run @command{guix pull} once before you run
@command{guix system reconfigure} for the first time (@pxref{Invoking
guix pull}). Failing to do that you would see an older version of Guix
Docker container using commands like the following:
@example
-image_id="$(docker load < guix-system-docker-image.tar.gz)"
-docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\
- --entrypoint /var/guix/profiles/system/profile/bin/guile \\
- $image_id /var/guix/profiles/system/boot
+image_id="`docker load < guix-system-docker-image.tar.gz`"
+container_id="`docker create $image_id`"
+docker start $container_id
@end example
This command starts a new Docker container from the specified image. It
will boot the Guix system in the usual manner, which means it will
start any services you have defined in the operating system
-configuration. Depending on what you run in the Docker container, it
+configuration. You can get an interactive shell running in the container
+using @command{docker exec}:
+
+@example
+docker exec -ti $container_id /run/current-system/profile/bin/bash --login
+@end example
+
+Depending on what you run in the Docker container, it
may be necessary to give the container additional permissions. For
example, if you intend to build software using Guix inside of the Docker
container, you may need to pass the @option{--privileged} option to
-@code{docker run}.
+@code{docker create}.
@item container
Return a script to run the operating system declared in @var{file}
of the image size as a function of the size of the system declared in
@var{file}.
+@item --network
+@itemx -N
+For the @code{container} action, allow containers to access the host network,
+that is, do not create a network namespace.
+
@item --root=@var{file}
@itemx -r @var{file}
Make @var{file} a symlink to the result, and register it as a garbage
@end table
+@node Invoking guix deploy
+@section Invoking @code{guix deploy}
+
+We've already seen @code{operating-system} declarations used to manage a
+machine's configuration locally. Suppose you need to configure multiple
+machines, though---perhaps you're managing a service on the web that's
+comprised of several servers. @command{guix deploy} enables you to use those
+same @code{operating-system} declarations to manage multiple remote hosts at
+once as a logical ``deployment''.
+
+@quotation Note
+The functionality described in this section is still under development
+and is subject to change. Get in touch with us on
+@email{guix-devel@@gnu.org}!
+@end quotation
+
+@example
+guix deploy @var{file}
+@end example
+
+Such an invocation will deploy the machines that the code within @var{file}
+evaluates to. As an example, @var{file} might contain a definition like this:
+
+@example
+;; This is a Guix deployment of a "bare bones" setup, with
+;; no X11 display server, to a machine with an SSH daemon
+;; listening on localhost:2222. A configuration such as this
+;; may be appropriate for virtual machine with ports
+;; forwarded to the host's loopback interface.
+
+(use-service-modules networking ssh)
+(use-package-modules bootloaders)
+
+(define %system
+ (operating-system
+ (host-name "gnu-deployed")
+ (timezone "Etc/UTC")
+ (bootloader (bootloader-configuration
+ (bootloader grub-bootloader)
+ (target "/dev/vda")
+ (terminal-outputs '(console))))
+ (file-systems (cons (file-system
+ (mount-point "/")
+ (device "/dev/vda1")
+ (type "ext4"))
+ %base-file-systems))
+ (services
+ (append (list (service dhcp-client-service-type)
+ (service openssh-service-type
+ (openssh-configuration
+ (permit-root-login #t)
+ (allow-empty-passwords? #t))))
+ %base-services))))
+
+(list (machine
+ (operating-system %system)
+ (environment managed-host-environment-type)
+ (configuration (machine-ssh-configuration
+ (host-name "localhost")
+ (identity "./id_rsa")
+ (port 2222)))))
+@end example
+
+The file should evaluate to a list of @var{machine} objects. This example,
+upon being deployed, will create a new generation on the remote system
+realizing the @code{operating-system} declaration @var{%system}.
+@var{environment} and @var{configuration} specify how the machine should be
+provisioned---that is, how the computing resources should be created and
+managed. The above example does not create any resources, as a
+@code{'managed-host} is a machine that is already running the Guix system and
+available over the network. This is a particularly simple case; a more
+complex deployment may involve, for example, starting virtual machines through
+a Virtual Private Server (VPS) provider. In such a case, a different
+@var{environment} type would be used.
+
+Do note that you first need to generate a key pair on the coordinator machine
+to allow the daemon to export signed archives of files from the store
+(@pxref{Invoking guix archive}).
+
+@example
+# guix archive --generate-key
+@end example
+
+@noindent
+Each target machine must authorize the key of the master machine so that it
+accepts store items it receives from the coordinator:
+
+@example
+# guix archive --authorize < coordinator-public-key.txt
+@end example
+
+@deftp {Data Type} machine
+This is the data type representing a single machine in a heterogeneous Guix
+deployment.
+
+@table @asis
+@item @code{operating-system}
+The object of the operating system configuration to deploy.
+
+@item @code{environment}
+An @code{environment-type} describing how the machine should be provisioned.
+At the moment, the only supported value is
+@code{managed-host-environment-type}.
+
+@item @code{configuration} (default: @code{#f})
+An object describing the configuration for the machine's @code{environment}.
+If the @code{environment} has a default configuration, @code{#f} maybe used.
+If @code{#f} is used for an environment with no default configuration,
+however, an error will be thrown.
+@end table
+@end deftp
+
+@deftp {Data Type} machine-ssh-configuration
+This is the data type representing the SSH client parameters for a machine
+with an @code{environment} of @code{managed-host-environment-type}.
+
+@table @asis
+@item @code{host-name}
+@item @code{port} (default: @code{22})
+@item @code{user} (default: @code{"root"})
+@item @code{identity} (default: @code{#f})
+If specified, the path to the SSH private key to use to authenticate with the
+remote host.
+@end table
+@end deftp
+
@node Running Guix in a VM
@section Running Guix in a Virtual Machine
@cindex virtual machine
To run Guix in a virtual machine (VM), one can use the pre-built Guix VM image
distributed at
-@indicateurl{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.@var{system}.xz}
+@url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.xz}.
This image is a compressed image in QCOW format. You will first need to
decompress with @command{xz -d}, and then you can pass it to an emulator such
as QEMU (see below for details).
Instead of using this pre-built image, one can also build their own virtual
machine image using @command{guix system vm-image} (@pxref{Invoking guix
system}). The returned image is in qcow2 format, which the
-@uref{http://qemu.org/, QEMU emulator} can efficiently use.
+@uref{https://qemu.org/, QEMU emulator} can efficiently use.
@cindex QEMU
If you built your own image, you must copy it out of the store
@example
$ qemu-system-x86_64 \
-net user -net nic,model=virtio \
- -enable-kvm -m 512 \
+ -enable-kvm -m 1024 \
-device virtio-blk,drive=myhd \
-drive if=none,file=/tmp/qemu-image,id=myhd
@end example
shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the
@code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.
-@item @code{requirements} (default: @code{'()})
+@item @code{requirement} (default: @code{'()})
List of symbols denoting the Shepherd services this one depends on.
@cindex one-shot services, for the Shepherd
herd @var{action} @var{service} [@var{arguments}@dots{}]
@end example
+@item @code{auto-start?} (default: @code{#t})
+Whether this service should be started automatically by the Shepherd. If it
+is @code{#f} the service has to be started manually with @code{herd start}.
+
@item @code{documentation}
A documentation string, as shown when running:
@xref{Invoking guix lint}, for more information.
-@quotation Note
-As of version @value{VERSION}, the feature described below is considered
-``beta''.
-@end quotation
-
Guix follows a functional
package management discipline (@pxref{Introduction}), which implies
that, when a package is changed, @emph{every package that depends on it}
@image{images/bootstrap-packages,6in,,Dependency graph of the early packages}
-@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
+@c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
The first tool that gets built with the bootstrap binaries is
GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite
for all the following packages. From there Findutils and Diffutils get
@node Acknowledgments
@chapter Acknowledgments
-Guix is based on the @uref{http://nixos.org/nix/, Nix package manager},
+Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
which was designed and
implemented by Eelco Dolstra, with contributions from other people (see
the @file{nix/AUTHORS} file in Guix.) Nix pioneered functional package
HCoop / jackhill / guix / guix.git / blobdiff