Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@*
Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo Wurmus@*
Copyright @copyright{} 2016 Ben Woodcroft@*
-Copyright @copyright{} 2016, 2017 Chris Marusich@*
-Copyright @copyright{} 2016, 2017 Efraim Flashner@*
+Copyright @copyright{} 2016, 2017, 2018 Chris Marusich@*
+Copyright @copyright{} 2016, 2017, 2018 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
-Copyright @copyright{} 2016, 2017 ng0@*
+Copyright @copyright{} 2016, 2017 Nils Gillmann@*
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, 2018 Clément Lassieur@*
Copyright @copyright{} 2017 Mathieu Othacehe@*
Copyright @copyright{} 2017 Federico Beffa@*
Copyright @copyright{} 2017 Carlo Zancanaro@*
Copyright @copyright{} 2017 Andy Wingo@*
Copyright @copyright{} 2017, 2018 Arun Isaac@*
Copyright @copyright{} 2017 nee@*
-Copyright @copyright{} 2018 Rutger Helling
+Copyright @copyright{} 2018 Rutger Helling@*
+Copyright @copyright{} 2018 Oleg Pykhalov@*
+Copyright @copyright{} 2018 Mike Gerwitz@*
+Copyright @copyright{} 2018 Pierre-Antoine Rouby
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
+* Sound Services:: ALSA and Pulseaudio services.
* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
@c end authentication part
@item
-As @code{root}, run:
+Now, you need to become the @code{root} user. Depending on your distribution,
+you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run:
@example
# cd /tmp
reproducible.
@item
-Make @code{root}'s profile available under @file{~/.guix-profile}:
+Make @code{root}'s profile available under @file{~root/.guix-profile}:
@example
# ln -sf /var/guix/profiles/per-user/root/guix-profile \
environment variables:
@example
-# GUIX_PROFILE=$HOME/.guix-profile ; \
+# GUIX_PROFILE="`echo ~root`/.guix-profile" ; \
source $GUIX_PROFILE/etc/profile
@end example
GNU Guix depends on the following packages:
@itemize
-@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.9 or
+@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.13 or
later, including 2.2.x;
@item @url{http://gnupg.org/, GNU libgcrypt};
@item
To be able to use such full names for the TrueType fonts installed in
your Guix profile, you need to extend the font path of the X server:
+@c Note: 'xset' does not accept symlinks so the trick below arranges to
+@c get at the real directory. See <https://bugs.gnu.org/30655>.
@example
-xset +fp ~/.guix-profile/share/fonts/truetype
+xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))
@end example
@cindex @code{xlsfonts}
@itemx -p @var{profile}
Use @var{profile} instead of the user's default profile.
+@cindex collisions, in a profile
+@cindex colliding packages in profiles
+@cindex profile collisions
+@item --allow-collisions
+Allow colliding packages in the new profile. Use at your own risk!
+
+By default, @command{guix package} reports as an error @dfn{collisions}
+in the profile. Collisions happen when two or more different versions
+or variants of a given package end up in the profile.
+
@item --verbose
Produce verbose output. In particular, emit the build log of the
environment on the standard error port.
of an element. @xref{Invoking guix graph}, for a tool to visualize
the graph of references.
+@item --derivers
+@cindex derivation
+Return the derivation(s) leading to the given store items
+(@pxref{Derivations}).
+
+For example, this command:
+
+@example
+guix gc --derivers `guix package -I ^emacs$ | cut -f4`
+@end example
+
+@noindent
+returns the @file{.drv} file(s) leading to the @code{emacs} package
+installed in your profile.
+
+Note that there may be zero matching @file{.drv} files, for instance
+because these files have been garbage-collected. There can also be more
+than one matching @file{.drv} due to fixed-output derivations.
@end table
Lastly, the following options allow you to check the integrity of the
effect is limited to the user who run @command{guix pull}. For
instance, when user @code{root} runs @command{guix pull}, this has no
effect on the version of Guix that user @code{alice} sees, and vice
-versa@footnote{Under the hood, @command{guix pull} updates the
-@file{~/.config/guix/latest} symbolic link to point to the latest Guix,
-and the @command{guix} command loads code from there. Currently, the
-only way to roll back an invocation of @command{guix pull} is to
-manually update this symlink to point to the previous Guix.}.
+versa.
+
+The result of running @command{guix pull} is a @dfn{profile} available
+under @file{~/.config/guix/current} containing the latest Guix. Thus,
+make sure to add it to the beginning of your search path so that you use
+the latest version, and similarly for the Info manual
+(@pxref{Documentation}):
+
+@example
+export PATH="$HOME/.config/guix/current/bin:$PATH"
+export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
+@end example
+
+This @code{~/.config/guix/current} profile works like any other profile
+created by @command{guix package} (@pxref{Invoking guix package}). That
+is, you can list generations, roll back to the previous
+generation---i.e., the previous Guix---and so on:
+
+@example
+$ guix package -p ~/.config/guix/current -l
+Generation 1 May 25 2018 10:06:41
+ guix 221951a out /gnu/store/i4dfk7vw5k112s49jrhl6hwsfnh6wr7l-guix-221951af4
+
+Generation 2 May 27 2018 19:07:47
+ + guix 2fbae00 out /gnu/store/44cv9hyvxg34xf5kblf5dz57hc52y4bm-guix-2fbae006f
+ - guix 221951a out /gnu/store/i4dfk7vw5k112s49jrhl6hwsfnh6wr7l-guix-221951af4
+
+Generation 3 May 30 2018 16:11:39 (current)
+ + guix a076f19 out /gnu/store/332czkicwwg6lc3x4aqbw5q2mq12s7fj-guix-a076f1990
+ - guix 2fbae00 out /gnu/store/44cv9hyvxg34xf5kblf5dz57hc52y4bm-guix-2fbae006f
+$ guix package -p ~/.config/guix/current --roll-back
+switched from generation 3 to 2
+@end example
The @command{guix pull} command is usually invoked with no arguments,
but it supports the following options:
@noindent
That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
+@cindex relocatable binaries, with @command{guix pack}
+What if the recipient of your pack does not have root privileges on
+their machine, and thus cannot unpack it in the root file system? In
+that case, you will want to use the @code{--relocatable} option (see
+below). This option produces @dfn{relocatable binaries}, meaning they
+they can be placed anywhere in the file system hierarchy: in the example
+above, users can unpack your tarball in their home directory and
+directly run @file{./opt/gnu/bin/guile}.
+
+@cindex Docker, build an image with guix pack
Alternatively, you can produce a pack in the Docker image format using
the following command:
@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
documentation} for more information.
+@cindex Singularity, build an image with guix pack
+@cindex SquashFS, build an image with guix pack
+Yet another option is to produce a SquashFS image with the following
+command:
+
+@example
+guix pack -f squashfs guile emacs geiser
+@end example
+
+@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
+environment}, using commands like @command{singularity shell} or
+@command{singularity exec}.
+
Several command-line options allow you to customize your pack:
@table @code
This produces a tarball that follows the
@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
Docker Image Specification}.
+
+@item squashfs
+This produces a SquashFS image containing all the specified binaries and
+symlinks, as well as empty mount points for virtual file systems like
+procfs.
@end table
+@item --relocatable
+@itemx -R
+Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
+anywhere in the file system hierarchy and run from there. For example,
+if you create a pack containing Bash with:
+
+@example
+guix pack -R -S /mybin=bin bash
+@end example
+
+@noindent
+... you can copy that pack to a machine that lacks Guix, and from your
+home directory as a normal user, run:
+
+@example
+tar xf pack.tar.gz
+./mybin/sh
+@end example
+
+@noindent
+In that shell, if you type @code{ls /gnu/store}, you'll notice that
+@file{/gnu/store} shows up and contains all the dependencies of
+@code{bash}, even though the machine actually lacks @file{/gnu/store}
+altogether! That is probably the simplest way to deploy Guix-built
+software on a non-Guix machine.
+
+There's a gotcha though: this technique relies on the @dfn{user
+namespace} feature of the kernel Linux, which allows unprivileged users
+to mount or change root. Old versions of Linux did not support it, and
+some GNU/Linux distributions turn it off; on these systems, programs
+from the pack @emph{will fail to run}, unless they are unpacked in the
+root file system.
+
@item --expression=@var{expr}
@itemx -e @var{expr}
Consider the package @var{expr} evaluates to.
build} (@pxref{Additional Build Options, @code{--expression} in
@command{guix build}}).
+@item --manifest=@var{file}
+@itemx -m @var{file}
+Use the packages contained in the manifest object returned by the Scheme
+code in @var{file}.
+
+This has a similar purpose as the same-named option in @command{guix
+package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
+same manifest files. It allows you to define a collection of packages
+once and use it both for creating profiles and for creating archives
+for use on machines that do not have Guix installed. Note that you can
+specify @emph{either} a manifest file @emph{or} a list of packages,
+but not both.
+
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
One use case for this is the Guix self-contained binary tarball
(@pxref{Binary Installation}).
+
+@item --bootstrap
+Use the bootstrap binaries to build the pack. This option is only
+useful to Guix developers.
@end table
In addition, @command{guix pack} supports all the common build options
@end defvr
+@defvr {Scheme Variable} android-ndk-build-system
+@cindex Android distribution
+@cindex Android NDK build system
+This variable is exported by @code{(guix build-system android-ndk)}. It
+implements a build procedure for Android NDK (native development kit)
+packages using a Guix-specific build process.
+
+The build system assumes that packages install their public interface
+(header) files to the subdirectory "include" of the "out" output and
+their libraries to the subdirectory "lib" of the "out" output.
+
+It's also assumed that the union of all the dependencies of a package
+has no conflicting files.
+
+For the time being, cross-compilation is not supported - so right now
+the libraries and header files are assumed to be host tools.
+
+@end defvr
+
@defvr {Scheme Variable} asdf-build-system/source
@defvrx {Scheme Variable} asdf-build-system/sbcl
@defvrx {Scheme Variable} asdf-build-system/ecl
@dots{})))
@end example
+@cindex extensions, for gexps
+@findex with-extensions
+In the same vein, sometimes you want to import not just pure-Scheme
+modules, but also ``extensions'' such as Guile bindings to C libraries
+or other ``full-blown'' packages. Say you need the @code{guile-json}
+package available on the build side, here's how you would do it:
+
+@example
+(use-modules (gnu packages guile)) ;for 'guile-json'
+
+(with-extensions (list guile-json)
+ (gexp->derivation "something-with-json"
+ #~(begin
+ (use-modules (json))
+ @dots{})))
+@end example
+
The syntactic form to construct gexps is summarized below.
@deffn {Scheme Syntax} #~@var{exp}
procedures called from @var{body}@dots{}.
@end deffn
+@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
+Mark the gexps defined in @var{body}@dots{} as requiring
+@var{extensions} in their build and execution environment.
+@var{extensions} is typically a list of package objects such as those
+defined in the @code{(gnu packages guile)} module.
+
+Concretely, the packages listed in @var{extensions} are added to the
+load path while compiling imported modules in @var{body}@dots{}; they
+are also added to the load path of the gexp returned by
+@var{body}@dots{}.
+@end deffn
+
@deffn {Scheme Procedure} gexp? @var{obj}
Return @code{#t} if @var{obj} is a G-expression.
@end deffn
[#:hash #f] [#:hash-algo #f] @
[#:recursive? #f] [#:env-vars '()] [#:modules '()] @
[#:module-path @var{%load-path}] @
+ [#:effective-version "2.2"] @
[#:references-graphs #f] [#:allowed-references #f] @
[#:disallowed-references #f] @
[#:leaked-env-vars #f] @
the load path during the execution of @var{exp}---e.g., @code{((guix
build utils) (guix build gnu-build-system))}.
+@var{effective-version} determines the string to use when adding extensions of
+@var{exp} (see @code{with-extensions}) to the search path---e.g., @code{"2.2"}.
+
@var{graft?} determines whether packages referred to by @var{exp} should be grafted when
applicable.
This is the declarative counterpart of @code{gexp->derivation}.
@end deffn
-@deffn {Monadic Procedure} gexp->script @var{name} @var{exp}
+@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
+ [#:guile (default-guile)] [#:module-path %load-path]
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}.
The example below builds a script that simply invokes the @command{ls}
command:
@end deffn
@deffn {Scheme Procedure} program-file @var{name} @var{exp} @
- [#:guile #f]
+ [#:guile #f] [#:module-path %load-path]
Return an object representing the executable store item @var{name} that
runs @var{gexp}. @var{guile} is the Guile package used to execute that
-script.
+script. Imported modules of @var{gexp} are looked up in @var{module-path}.
This is the declarative counterpart of @code{gexp->script}.
@end deffn
@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
- [#:set-load-path? #t]
+ [#:set-load-path? #t] [#:module-path %load-path] @
+ [#:splice? #f] @
+ [#:guile (default-guile)]
Return a derivation that builds a file @var{name} containing @var{exp}.
+When @var{splice?} is true, @var{exp} is considered to be a list of
+expressions that will be spliced in the resulting file.
+
When @var{set-load-path?} is true, emit code in the resulting file to
set @code{%load-path} and @code{%load-compiled-path} to honor
-@var{exp}'s imported modules.
+@var{exp}'s imported modules. Look up @var{exp}'s modules in
+@var{module-path}.
The resulting file holds references to all the dependencies of @var{exp}
or a subset thereof.
@end deffn
-@deffn {Scheme Procedure} scheme-file @var{name} @var{exp}
+@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f]
Return an object representing the Scheme file @var{name} that contains
@var{exp}.
An example use of this is on Linux-based systems, which can emulate
different personalities. For instance, passing
-@code{--system=i686-linux} on an @code{x86_64-linux} system allows you
+@code{--system=i686-linux} on an @code{x86_64-linux} system or
+@code{--system=armhf-linux} on an @code{aarch64-linux} system allows you
to build packages in a complete 32-bit environment.
+@quotation Note
+Building for an @code{armhf-linux} system is unconditionally enabled on
+@code{aarch64-linux} machines, although certain aarch64 chipsets do not
+allow for this functionality, notably the ThunderX.
+@end quotation
+
Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
is enabled (@pxref{Virtualization Services,
@code{qemu-binfmt-service-type}}), you can build for any system for
@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
identifier.
@end itemize
+
+@item --recursive
+@itemx -r
+Traverse the dependency graph of the given upstream package recursively
+and generate package expressions for all those packages that are not yet
+in Guix.
@end table
@item crate
Package developers can specify in package recipes the
@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)}
-name and version of the package when they differ from the name that Guix
-uses, as in this example:
+name and version of the package when they differ from the name or version
+that Guix uses, as in this example:
@example
(package
(name "grub")
;; @dots{}
;; CPE calls this package "grub2".
- (properties '((cpe-name . "grub2"))))
+ (properties '((cpe-name . "grub2")
+ (cpe-version . "2.3")))
+@end example
+
+@c See <http://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
+declare them as in this example:
+
+@example
+(package
+ (name "t1lib")
+ ;; @dots{}
+ ;; These CVEs no longer apply and can be safely ignored.
+ (properties `((lint-hidden-cve . ("CVE-2011-0433"
+ "CVE-2011-1553"
+ "CVE-2011-1554"
+ "CVE-2011-5244")))))
@end example
@item formatting
with Multiple Outputs}). Such are the typical issues that
@command{guix size} can highlight.
-The command can be passed a package specification such as @code{gcc@@4.8}
+The command can be passed one or more package specifications
+such as @code{gcc@@4.8}
or @code{guile:debug}, or a file name in the store. Consider this
example:
@example
$ guix size coreutils
store item total self
-/gnu/store/@dots{}-coreutils-8.23 70.0 13.9 19.8%
-/gnu/store/@dots{}-gmp-6.0.0a 55.3 2.5 3.6%
-/gnu/store/@dots{}-acl-2.2.52 53.7 0.5 0.7%
-/gnu/store/@dots{}-attr-2.4.46 53.2 0.3 0.5%
-/gnu/store/@dots{}-gcc-4.8.4-lib 52.9 15.7 22.4%
-/gnu/store/@dots{}-glibc-2.21 37.2 37.2 53.1%
+/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
+/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
+/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
+/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
+/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
+/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
+/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
+/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
+total: 78.9 MiB
@end example
@cindex closure
itself to the space occupied by all the items listed here.
In this example, we see that the closure of Coreutils weighs in at
-70@tie{}MiB, half of which is taken by libc. (That libc represents a
-large fraction of the closure is not a problem @i{per se} because it is
-always available on the system anyway.)
-
-When the package passed to @command{guix size} is available in the
-store, @command{guix size} queries the daemon to determine its
+79@tie{}MiB, most of which is taken by libc and GCC's run-time support
+libraries. (That libc and GCC's libraries represent a large fraction of
+the closure is not a problem @i{per se} because they are always available
+on the system anyway.)
+
+When the package(s) passed to @command{guix size} are available in the
+store@footnote{More precisely, @command{guix size} looks for the
+@emph{ungrafted} variant of the given package(s), as returned by
+@code{guix build @var{package} --no-grafts}. @xref{Security Updates},
+for information on grafts.}, @command{guix size} queries the daemon to determine its
dependencies, and measures its size in the store, similar to @command{du
-ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
Coreutils}).
-When the given package is @emph{not} in the store, @command{guix size}
+When the given packages are @emph{not} in the store, @command{guix size}
reports information based on the available substitutes
(@pxref{Substitutes}). This makes it possible it to profile disk usage of
store items that are not even on disk, only available remotely.
@example
guix graph -t derivation `guix system build -d my-config.scm`
@end example
+
+@item module
+This is the graph of @dfn{package modules} (@pxref{Package Modules}).
+For example, the following command shows the graph for the package
+module that defines the @code{guile} package:
+
+@example
+guix graph -t module guile | dot -Tpdf > module-graph.pdf
+@end example
@end table
All the types above correspond to @emph{build-time dependencies}. The
@verbatiminclude environment-gdb.scm
@end example
+@item --manifest=@var{file}
+@itemx -m @var{file}
+Create an environment for the packages contained in the manifest object
+returned by the Scheme code in @var{file}.
+
+This is similar to the same-named option in @command{guix package}
+(@pxref{profile-manifest, @option{--manifest}}) and uses the same
+manifest files.
+
@item --ad-hoc
Include all specified packages in the resulting environment, as if an
@i{ad hoc} package were defined with them as inputs. This option is
@cindex container
Run @var{command} within an isolated container. The current working
directory outside the container is mapped inside the container.
-Additionally, a dummy home directory is created that matches the current
-user's home directory, and @file{/etc/passwd} is configured accordingly.
-The spawned process runs as the current user outside the container, but
-has root privileges in the context of the container.
+Additionally, unless overridden with @code{--user}, a dummy home
+directory is created that matches the current user's home directory, and
+@file{/etc/passwd} is configured accordingly. The spawned process runs
+as the current user outside the container, but has root privileges in
+the context of the container.
@item --network
@itemx -N
Containers created without this flag only have access to the loopback
device.
+@item --link-profile
+@itemx -P
+For containers, link the environment profile to
+@file{~/.guix-profile} within the container. This is equivalent to
+running the command @command{ln -s $GUIX_ENVIRONMENT ~/.guix-profile}
+within the container. Linking will fail and abort the environment if
+the directory already exists, which will certainly be the case if
+@command{guix environment} was invoked in the user's home directory.
+
+Certain packages are configured to look in
+@code{~/.guix-profile} for configuration files and data;@footnote{For
+example, the @code{fontconfig} package inspects
+@file{~/.guix-profile/share/fonts} for additional fonts.}
+@code{--link-profile} allows these programs to behave as expected within
+the environment.
+
+@item --user=@var{user}
+@itemx -u @var{user}
+For containers, use the username @var{user} in place of the current
+user. The generated @file{/etc/passwd} entry within the container will
+contain the name @var{user}; the home directory will be
+@file{/home/USER}; and no user GECOS data will be copied. @var{user}
+need not exist on the system.
+
+Additionally, any shared or exposed path (see @code{--share} and
+@code{--expose} respectively) whose target is within the current user's
+home directory will be remapped relative to @file{/home/USER}; this
+includes the automatic mapping of the current working directory.
+
+@example
+# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
+cd $HOME/wd
+guix environment --container --user=foo \
+ --expose=$HOME/test \
+ --expose=/tmp/target=$HOME/target
+@end example
+
+While this will limit the leaking of user identity through home paths
+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 --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
19,824.2 MiB on disk (uncompressed)
0.030 seconds per request (182.9 seconds in total)
33.5 requests per second
+
+ 9.8% (342 out of 3,470) of the missing items are queued
+ 867 queued builds
+ x86_64-linux: 518 (59.7%)
+ i686-linux: 221 (25.5%)
+ aarch64-linux: 128 (14.8%)
+ build rate: 23.41 builds per hour
+ x86_64-linux: 11.16 builds per hour
+ i686-linux: 6.03 builds per hour
+ aarch64-linux: 6.41 builds per hour
@end example
+@cindex continuous integration, statistics
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.
+the server's throughput. The second part gives continuous integration
+(CI) statistics, if the server supports it.
To achieve that, @command{guix weather} queries over HTTP(S) meta-data
(@dfn{narinfos}) for all the relevant store items. Like @command{guix
To configure wireless networking, you can create a configuration file
for the @command{wpa_supplicant} configuration tool (its location is not
important) using one of the available text editors such as
-@command{zile}:
+@command{nano}:
@example
-zile wpa_supplicant.conf
+nano wpa_supplicant.conf
@end example
As an example, the following stanza can go to this file and will work
Next, you have to edit a file and
provide the declaration of the operating system to be installed. To
-that end, the installation system comes with three text editors: GNU nano
-(@pxref{Top,,, nano, GNU nano Manual}), GNU Zile (an Emacs clone), and
+that end, the installation system comes with three text editors. We
+recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
+supports syntax highlighting and parentheses matching; other editors
+include GNU Zile (an Emacs clone), and
nvi (a clone of the original BSD @command{vi} editor).
We strongly recommend storing that file on the target root file system, say,
as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
@example
# mkdir /mnt/etc
# cp /etc/configuration/desktop.scm /mnt/etc/config.scm
-# zile /mnt/etc/config.scm
+# nano /mnt/etc/config.scm
@end example
You should pay attention to what your configuration file contains, and
@item @code{bootloader}
The system bootloader configuration object. @xref{Bootloader Configuration}.
-@item @code{initrd} (default: @code{base-initrd})
+@item @code{initrd-modules} (default: @code{%base-initrd-modules})
@cindex initrd
@cindex initial RAM disk
-A two-argument monadic procedure that returns an initial RAM disk for
-the Linux kernel. @xref{Initial RAM Disk}.
+The list of Linux kernel modules that need to be available in the
+initial RAM disk. @xref{Initial RAM Disk}.
+
+@item @code{initrd} (default: @code{base-initrd})
+A monadic procedure that returns an initial RAM disk for the Linux
+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})
@cindex firmware
This designates the place where the file system is to be mounted.
@item @code{device}
-This names the ``source'' of the file system. By default it is the name
-of a node under @file{/dev}, but its meaning depends on the @code{title}
-field described below.
+This names the ``source'' of the file system. It can be one of three
+things: a file system label, a file system UUID, or the name of a
+@file{/dev} node. Labels and UUIDs offer a way to refer to file
+systems without having to hard-code their actual device
+name@footnote{Note that, while it is tempting to use
+@file{/dev/disk/by-uuid} and similar device names to achieve the same
+result, this is not recommended: These special device nodes are created
+by the udev daemon and may be unavailable at the time the device is
+mounted.}.
-@item @code{title} (default: @code{'device})
-This is a symbol that specifies how the @code{device} field is to be
-interpreted.
+@findex file-system-label
+File system labels are created using the @code{file-system-label}
+procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
+plain strings. Here's an example of a file system referred to by its
+label, as shown by the @command{e2label} command:
-When it is the symbol @code{device}, then the @code{device} field is
-interpreted as a file name; when it is @code{label}, then @code{device}
-is interpreted as a file system label name; when it is @code{uuid},
-@code{device} is interpreted as a file system unique identifier (UUID).
+@example
+(file-system
+ (mount-point "/home")
+ (type "ext4")
+ (device (file-system-label "my-home")))
+@end example
-UUIDs may be converted from their string representation (as shown by the
+@findex uuid
+UUIDs are converted from their string representation (as shown by the
@command{tune2fs -l} command) using the @code{uuid} form@footnote{The
@code{uuid} form expects 16-byte UUIDs as defined in
@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
(file-system
(mount-point "/home")
(type "ext4")
- (title 'uuid)
(device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
@end example
-The @code{label} and @code{uuid} options offer a way to refer to file
-systems without having to hard-code their actual device
-name@footnote{Note that, while it is tempting to use
-@file{/dev/disk/by-uuid} and similar device names to achieve the same
-result, this is not recommended: These special device nodes are created
-by the udev daemon and may be unavailable at the time the device is
-mounted.}.
-
-However, when the source of a file system is a mapped device (@pxref{Mapped
+When the source of a file system is a mapped device (@pxref{Mapped
Devices}), its @code{device} field @emph{must} refer to the mapped
-device name---e.g., @file{/dev/mapper/root-partition}---and consequently
-@code{title} must be set to @code{'device}. This is required so that
+device name---e.g., @file{"/dev/mapper/root-partition"}.
+This is required so that
the system knows that mounting the file system depends on having the
corresponding device mapping established.
* X Window:: Graphical display.
* Printing Services:: Local and remote printer support.
* Desktop Services:: D-Bus and desktop services.
+* Sound Services:: ALSA and Pulseaudio services.
* Database Services:: SQL databases, key-value stores, etc.
* Mail Services:: IMAP, POP3, SMTP, and all that.
* Messaging Services:: Messaging services.
@item @code{tty}
The name of the console this agetty runs on, as a string---e.g.,
-@code{"ttyS0"}. This argument is mandatory.
+@code{"ttyS0"}. This argument is optional, it will default to
+a reasonable default serial port used by the kernel Linux.
+
+For this, if there is a value for an option @code{agetty.tty} in the kernel
+command line, agetty will extract the device name of the serial port
+from it and use that.
+
+If not and if there is a value for an option @code{console} with a tty in
+the Linux command line, agetty will extract the device name of the
+serial port from it and use that.
+
+In both cases, agetty will leave the other serial device settings
+(baud rate etc.) alone---in the hope that Linux pinned them to the
+correct values.
@item @code{baud-rate} (default: @code{#f})
A string containing a comma-separated list of one or more baud rates, in
@cindex mouse
@cindex gpm
-@deffn {Scheme Procedure} gpm-service [#:gpm @var{gpm}] @
- [#:options]
-Run @var{gpm}, the general-purpose mouse daemon, with the given
-command-line @var{options}. GPM allows users to use the mouse in the console,
-notably to select, copy, and paste text. The default value of @var{options}
-uses the @code{ps2} protocol, which works for both USB and PS/2 mice.
-
-This service is not part of @var{%base-services}.
-@end deffn
+@defvr {Scheme Variable} gpm-service-type
+This is the type of the service that runs GPM, the @dfn{general-purpose
+mouse daemon}, which provides mouse support to the Linux console. GPM
+allows users to use the mouse in the console, notably to select, copy,
+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}.
+@end defvr
+
+@deftp {Data Type} gpm-configuration
+Data type representing the configuration of GPM.
+
+@table @asis
+@item @code{options} (default: @code{%default-gpm-options})
+Command-line options passed to @command{gpm}. The default set of
+options instruct @command{gpm} to listen to mouse events on
+@file{/dev/input/mice}. @xref{Command Line,,, gpm, gpm manual}, for
+more information.
+
+@item @code{gpm} (default: @code{gpm})
+The GPM package to use.
+
+@end table
+@end deftp
@anchor{guix-publish-service-type}
@deffn {Scheme Variable} guix-publish-service-type
@cindex session limits
@cindex ulimit
@cindex priority
+@cindex realtime
+@cindex jackd
@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
Return a service that installs a configuration file for the
for more information on mcron job specifications. Below is the
reference of the mcron service.
-@deffn {Scheme Procedure} mcron-service @var{jobs} [#:mcron @var{mcron2}]
+@deffn {Scheme Procedure} mcron-service @var{jobs} [#:mcron @var{mcron}]
Return an mcron service running @var{mcron} that schedules @var{jobs}, a
list of gexps denoting mcron job specifications.
Data type representing the configuration of mcron.
@table @asis
-@item @code{mcron} (default: @var{mcron2})
+@item @code{mcron} (default: @var{mcron})
The mcron package to use.
@item @code{jobs}
Protocol (DHCP) client, on all the non-loopback network interfaces.
@end deffn
+@deffn {Scheme Procedure} dhcpd-service-type
+This type defines a service that runs a DHCP daemon. To create a
+service of this type, you must supply a @code{<dhcpd-configuration>}.
+For example:
+
+@example
+(service dhcpd-service-type
+ (dhcpd-configuration
+ (config-file (local-file "my-dhcpd.conf"))
+ (interfaces '("enp0s25"))))
+@end example
+@end deffn
+
+@deftp {Data Type} dhcpd-configuration
+@table @asis
+@item @code{package} (default: @code{isc-dhcp})
+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}.
+@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''
+object (@pxref{G-Expressions, file-like objects}). See @code{man
+dhcpd.conf} for details on the configuration file syntax.
+@item @code{version} (default: @code{"4"})
+The DHCP version to use. The ISC DHCP server supports the values ``4'',
+``6'', and ``4o6''. These correspond to the @code{dhcpd} program
+options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for
+details.
+@item @code{run-directory} (default: @code{"/run/dhcpd"})
+The run directory to use. At service activation time, this directory
+will be created if it does not exist.
+@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
+The PID file to use. This corresponds to the @code{-pf} option of
+@code{dhcpd}. See @code{man dhcpd} for details.
+@item @code{interfaces} (default: @code{'()})
+The names of the network interfaces on which dhcpd should listen for
+broadcasts. If this list is not empty, then its elements (which must be
+strings) will be appended to the @code{dhcpd} invocation when starting
+the daemon. It may not be necessary to explicitly specify any
+interfaces here; see @code{man dhcpd} for details.
+@end table
+@end deftp
+
@defvr {Scheme Variable} static-networking-service-type
This is the type for statically-configured network interfaces.
@c TODO Document <static-networking> data structures.
and @command{wicd-curses} user interfaces.
@end deffn
+@cindex ModemManager
+
+@defvr {Scheme Variable} modem-manager-service-type
+This is the service type for the
+@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
+service. The value for this service type is a
+@code{modem-manager-configuration} record.
+
+This service is part of @code{%desktop-services} (@pxref{Desktop
+Services}).
+@end defvr
+
+@deftp {Data Type} modem-manager-configuration
+Data type representing the configuration of ModemManager.
+
+@table @asis
+@item @code{modem-manager} (default: @code{modem-manager})
+The ModemManager package to use.
+
+@end table
+@end deftp
+
@cindex NetworkManager
@defvr {Scheme Variable} network-manager-service-type
List of host names used as the default NTP servers.
@end defvr
+@cindex OpenNTPD
+@deffn {Scheme Procedure} openntpd-service-type
+Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
+by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system
+clock synchronized with that of the given servers.
+
+@example
+(service
+ openntpd-service-type
+ (openntpd-configuration
+ (listen-on '("127.0.0.1" "::1"))
+ (sensor '("udcf0 correction 70000"))
+ (constraint-from '("www.gnu.org"))
+ (constraints-from '("https://www.google.com/"))
+ (allow-large-adjustment? #t)))
+
+@end example
+@end deffn
+
+@deftp {Data Type} openntpd-configuration
+@table @asis
+@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
+The openntpd executable to use.
+@item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
+A list of local IP addresses or hostnames the ntpd daemon should listen on.
+@item @code{query-from} (default: @code{'()})
+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.
+See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
+information.
+@item @code{server} (default: @var{%ntp-servers})
+Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
+@item @code{servers} (default: @code{'()})
+Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
+@item @code{constraint-from} (default: @code{'()})
+@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
+This time information is not used for precision but acts as an authenticated
+constraint, thereby reducing the impact of unauthenticated NTP
+man-in-the-middle attacks.
+Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide
+a constraint.
+@item @code{constraints-from} (default: @code{'()})
+As with constraint from, specify a list of URLs, IP addresses or hostnames of
+HTTPS servers to provide a constraint. Should the hostname resolve to multiple
+IP addresses, @code{ntpd} will calculate a median constraint from all of them.
+@item @code{allow-large-adjustment?} (default: @code{#f})
+Determines if @code{ntpd} is allowed to make an initial adjustment of more
+than 180 seconds.
+@end table
+@end deftp
+
@cindex inetd
@deffn {Scheme variable} inetd-service-type
This service runs the @command{inetd} (@pxref{inetd invocation,,,
`(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
@end example
+@item @code{accepted-environment} (default: @code{'()})
+List of strings describing which environment variables may be exported.
+
+Each string gets on its own line. See the @code{AcceptEnv} option in
+@code{man sshd_config}.
+
+This example allows ssh-clients to export the @code{COLORTERM} variable.
+It is set by terminal emulators, which support colors. You can use it in
+your shell's ressource file to enable colors for the prompt and commands
+if this variable is set.
+
+@example
+(service openssh-service-type
+ (openssh-configuration
+ (accepted-environment '("COLORTERM"))))
+@end example
+
@item @code{authorized-keys} (default: @code{'()})
@cindex authorized keys, SSH
@cindex SSH authorized keys
The Shepherd package used when invoking @command{halt} and
@command{reboot}.
+@item @code{sessreg} (default: @code{sessreg})
+The sessreg package used in order to register the session.
+
@item @code{slim} (default: @code{slim})
The SLiM package to use.
@end table
@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
Script to run before stopping xorg-server.
-@item @code{xsession-command} (default: @code{xinitr })
+@item @code{xsession-command} (default: @code{xinitrc})
Script to run before starting a X session.
@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
Last, @var{extra-config} is a list of strings or objects appended to the
configuration file. It is used to pass extra text to be
added verbatim to the configuration file.
+
+@cindex keymap
+@cindex keyboard layout
+This procedure is especially useful to configure a different keyboard layout
+than the default US keymap. For instance, to use the ``bépo'' keymap by
+default on the display manager:
+
+@example
+(define bepo-evdev
+ "Section \"InputClass\"
+ Identifier \"evdev keyboard catchall\"
+ Driver \"evdev\"
+ MatchIsKeyboard \"on\"
+ Option \"xkb_layout\" \"fr\"
+ Option \"xkb_variant\" \"bepo\"
+EndSection")
+
+(operating-system
+ ...
+ (services
+ (modify-services %desktop-services
+ (slim-service-type config =>
+ (slim-configuration
+ (inherit config)
+ (startx (xorg-start-command
+ #:configuration-file
+ (xorg-configuration-file
+ #:extra-config
+ (list bepo-evdev)))))))))
+@end example
+
+The @code{MatchIsKeyboard} line specifies that we only apply the configuration
+to keyboards. Without this line, other devices such as touchpad may not work
+correctly because they will be attached to the wrong driver. In this example,
+the user typically used @code{setxkbmap fr bepo} to set their favorite keymap
+once logged in. The first argument corresponds to the layout, while the second
+argument corresponds to the variant. The @code{xkb_variant} line can be omitted
+to select the default variant.
@end deffn
@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
Reference, @code{services}}).
Additionally, the @code{gnome-desktop-service},
-@code{xfce-desktop-service} and @code{mate-desktop-service}
-procedures can add GNOME, XFCE and/or MATE to a system.
-To ``add GNOME'' means that system-level services like the
-backlight adjustment helpers and the power management utilities are
-added to the system, extending @code{polkit} and @code{dbus}
+@code{xfce-desktop-service}, @code{mate-desktop-service} and
+@code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, MATE
+and/or Enlightenment to a system. To ``add GNOME'' means that system-level
+services like the backlight adjustment helpers and the power management
+utilities are added to the system, extending @code{polkit} and @code{dbus}
appropriately, allowing GNOME to operate with elevated privileges on a
limited number of special-purpose system interfaces. Additionally,
adding a service made by @code{gnome-desktop-service} adds the GNOME
appropriately, allowing MATE to operate with elevated privileges on a
limited number of special-purpose system interfaces. Additionally,
adding a service made by @code{mate-desktop-service} adds the MATE
-metapackage to the system profile.
+metapackage to the system profile. ``Adding ENLIGHTENMENT'' means that
+@code{dbus} is extended appropriately, and several of Enlightenment's binaries
+are set as setuid, allowing Enlightenment's screen locker and other
+functionality to work as expetected.
The desktop environments in Guix use the Xorg display server by
default. If you'd like to use the newer display server protocol
called Wayland, you need to use the @code{sddm-service} instead of the
@code{slim-service} for the graphical login manager. You should then
-select the ``GNOME (Wayland)'' session in SDDM. Currently only GNOME
-has support for Wayland.
+select the ``GNOME (Wayland)'' session in SDDM. Alternatively you can
+also try starting GNOME on Wayland manually from a TTY with the
+command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
+gnome-session``. Currently only GNOME has support for Wayland.
@deffn {Scheme Procedure} gnome-desktop-service
Return a service that adds the @code{gnome} package to the system
@code{mate-settings-daemon}.
@end deffn
+@deffn {Scheme Procedure} enlightenment-desktop-service-type
+Return a service that adds the @code{enlightenment} package to the system
+profile, and extends dbus with actions from @code{efl}.
+@end deffn
+
+@deftp {Data Type} enlightenment-desktop-service-configuration
+@table @asis
+@item @code{enlightenment} (default @code{enlightenment})
+The enlightenment package to use.
+@end table
+@end deftp
+
Because the GNOME, XFCE and MATE desktop services pull in so many packages,
-the default @code{%desktop-services} variable doesn't include either of
+the default @code{%desktop-services} variable doesn't include any of
them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:
Users need to be in the @code{lp} group to access the D-Bus service.
@end deffn
+@node Sound Services
+@subsubsection Sound Services
+
+@cindex sound support
+@cindex ALSA
+@cindex PulseAudio, sound support
+
+The @code{(gnu services sound)} module provides an
+@code{alsa-service-type} service to generate an ALSA
+@file{/etc/asound.conf} configuration file. This configuration file is
+what allows applications that produce sound using ALSA to be correctly
+handled.
+
+@deffn {Scheme Variable} alsa-service-type
+This is the type for the @uref{https://alsa-project.org/, ALSA},
+@command{alsa-configuration} record as in this example:
+
+@example
+(service alsa-service-type)
+@end example
+
+See below for details about @code{alsa-configuration}.
+@end deffn
+
+@deftp {Data Type} alsa-configuration
+Data type representing the configuration for @code{alsa-service}.
+
+@table @asis
+@item @code{pulseaudio?} (default: @var{#t})
+Whether ALSA applications should transparently be made to use the
+@uref{http://www.pulseaudio.org/, PulseAudio} sound server.
+
+Using PulseAudio allows you to run several sound-producing applications
+at the same time and to individual control them @i{via}
+@command{pavucontrol}, among other things.
+
+@item @code{extra-options} (default: @var{""})
+String to append to the @file{asound.conf} file.
+
+@end table
+@end deftp
+
@node Database Services
@subsubsection Database Services
have an old @code{prosody.cfg.lua} file that you want to port over from
some other system; see the end for more details.
+The @code{file-object} type designates either a file-like object
+(@pxref{G-Expressions, file-like objects}) or a file name.
+
@c The following documentation was initially generated by
@c (generate-documentation) in (gnu services messaging). Manually maintained
@c documentation is better, so we shouldn't hesitate to edit below as
Defaults to @samp{"/var/lib/prosody"}.
@end deftypevr
-@deftypevr {@code{prosody-configuration} parameter} file-name-list plugin-paths
+@deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
Additional plugin directories. They are searched in all the specified
paths in order. See @url{https://prosody.im/doc/plugins_directory}.
Defaults to @samp{()}.
Defaults to @samp{()}.
@end deftypevr
-@deftypevr {@code{prosody-configuration} parameter} file-name groups-file
+@deftypevr {@code{prosody-configuration} parameter} file-object groups-file
Path to a text file where the shared groups are defined. If this path is
empty then @samp{mod_groups} does nothing. See
@url{https://prosody.im/doc/modules/mod_groups}.
Path to your certificate file.
@end deftypevr
-@deftypevr {@code{ssl-configuration} parameter} file-name capath
+@deftypevr {@code{ssl-configuration} parameter} file-object capath
Path to directory containing root certificates that you wish Prosody to
trust when verifying the certificates of remote servers.
Defaults to @samp{"/etc/ssl/certs"}.
@end deftypevr
-@deftypevr {@code{ssl-configuration} parameter} maybe-file-name cafile
+@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
Path to a file containing root certificates that you wish Prosody to trust.
Similar to @code{capath} but with all certificates concatenated together.
@end deftypevr
(prosody.cfg.lua "")))
@end example
+@c end of Prosody auto-generated documentation
+
@subsubheading BitlBee Service
@cindex IRC (Internet Relay Chat)
@item @code{package} (default: @code{bitlbee})
The BitlBee package to use.
+@item @code{plugins} (default: @code{'()})
+List of plugin packages to use---e.g., @code{bitlbee-discord}.
+
@item @code{extra-settings} (default: @code{""})
Configuration snippet added as-is to the BitlBee configuration file.
@end table
@item @code{<php-fpm-on-demand-process-manager-configuration>}
@end table
@item @code{display-errors} (default @code{#f})
-Determines wether php errors and warning should be sent to clients
+Determines whether php errors and warning should be sent to clients
and displayed in their browsers.
This is useful for local php development, but a security risk for public sites,
as error messages can reveal passwords and personal data.
%base-services))
@end example
+@cindex cat-avatar-generator
+The cat avatar generator is a simple service to demonstrate the use of php-fpm
+in @code{Nginx}. It is used to generate cat avatar from a seed, for instance
+the hash of a user's email address.
+
+@deffn {Scheme Procedure} cat-avatar-generator-serice @
+ [#:cache-dir "/var/cache/cat-avatar-generator"] @
+ [#:package cat-avatar-generator] @
+ [#:configuration (nginx-server-configuration)]
+Returns an nginx-server-configuration that inherits @code{configuration}. It
+extends the nginx configuration to add a server block that serves @code{package},
+a version of cat-avatar-generator. During execution, cat-avatar-generator will
+be able to use @code{cache-dir} as its cache directory.
+@end deffn
+
+A simple setup for cat-avatar-generator can look like this:
+@example
+(services (cons* (cat-avatar-generator-service
+ #:configuration
+ (nginx-server-configuration
+ (server-name '("example.com"))))
+ ...
+ %base-services))
+@end example
+
+@subsubheading Hpcguix-web
+
+@cindex hpcguix-web
+The @uref{hpcguix-web, https://github.com/UMCUGenetics/hpcguix-web/}
+program is a customizable web interface to browse Guix packages,
+initially designed for users of high-performance computing (HPC)
+clusters.
+
+@defvr {Scheme Variable} hpcguix-web-service-type
+The service type for @code{hpcguix-web}.
+@end defvr
+
+@deftp {Data Type} hpcguix-web-configuration
+Data type for the hpcguix-web service configuration.
+
+@table @asis
+@item @code{specs}
+A gexp (@pxref{G-Expressions}) specifying the hpcguix-web service
+configuration. The main items available in this spec are:
+
+@table @asis
+@item @code{title-prefix} (default: @code{"hpcguix | "})
+The page title prefix.
+
+@item @code{guix-command} (default: @code{"guix"})
+The @command{guix} command.
+
+@item @code{package-filter-proc} (default: @code{(const #t)})
+A procedure specifying how to filter packages that are displayed.
+
+@item @code{package-page-extension-proc} (default: @code{(const '())})
+Extension package for @code{hpcguix-web}.
+
+@item @code{menu} (default: @code{'()})
+Additional entry in page @code{menu}.
+@end table
+
+See the hpcguix-web repository for a
+@uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
+complete example}.
+
+@item @code{package} (default: @code{hpcguix-web})
+The hpcguix-web package to use.
+@end table
+@end deftp
+
+A typical hpcguix-web service declaration looks like this:
+
+@example
+(service hpcguix-web-service-type
+ (hpcguix-web-configuration
+ (specs
+ #~(define site-config
+ (hpcweb-configuration
+ (title-prefix "Guix-HPC - ")
+ (menu '(("/about" "ABOUT"))))))))
+@end example
+
@node Certificate Services
@subsubsection Certificate Services
The certbot service automates this process: the initial key
generation, the initial certification request to the Let's Encrypt
service, the web server challenge/response integration, writing the
-certificate to disk, and the automated periodic renewals.
+certificate to disk, the automated periodic renewals, and the deployment
+tasks associated with the renewal (e.g. reloading services, copying keys
+with different permissions).
+
+Certbot is run twice a day, at a random minute within the hour. It
+won't do anything until your certificates are due for renewal or
+revoked, but running it regularly would give your service a chance of
+staying online in case a Let's Encrypt-initiated revocation happened for
+some reason.
+
+By using this service, you agree to the ACME Subscriber Agreement, which
+can be found there:
+@url{https://acme-v01.api.letsencrypt.org/directory}.
@defvr {Scheme Variable} certbot-service-type
-A service type for the @code{certbot} Let's Encrypt client.
+A service type for the @code{certbot} Let's Encrypt client. Its value
+must be a @code{certbot-configuration} record as in this example:
+
+@example
+(define %nginx-deploy-hook
+ (program-file
+ "nginx-deploy-hook"
+ #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read)))
+ (kill pid SIGHUP))))
+
+(service certbot-service-type
+ (certbot-configuration
+ (email "foo@@example.net")
+ (certificates
+ (list
+ (certificate-configuration
+ (domains '("example.net" "www.example.net"))
+ (deploy-hook %nginx-deploy-hook))
+ (certificate-configuration
+ (domains '("bar.example.net")))))))
+@end example
+
+See below for details about @code{certbot-configuration}.
@end defvr
@deftp {Data Type} certbot-configuration
-Data type representing the configuration of the @code{certbot} serice.
+Data type representing the configuration of the @code{certbot} service.
This type has the following parameters:
@table @asis
The directory from which to serve the Let's Encrypt challenge/response
files.
-@item @code{hosts} (default: @code{()})
-A list of hosts for which to generate certificates and request
-signatures.
+@item @code{certificates} (default: @code{()})
+A list of @code{certificates-configuration}s for which to generate
+certificates and request signatures. Each certificate has a @code{name}
+and several @code{domains}.
+
+@item @code{email}
+Mandatory email used for registration, recovery contact, and important
+account notifications.
+
+@item @code{rsa-key-size} (default: @code{2048})
+Size of the RSA key.
@item @code{default-location} (default: @i{see below})
The default @code{nginx-location-configuration}. Because @code{certbot}
needs to be able to serve challenges and responses, it needs to be able
to run a web server. It does so by extending the @code{nginx} web
service with an @code{nginx-server-configuration} listening on the
-@var{hosts} on port 80, and which has a
+@var{domains} on port 80, and which has a
@code{nginx-location-configuration} for the @code{/.well-known/} URI
path subspace used by Let's Encrypt. @xref{Web Services}, for more on
these nginx configuration data types.
@code{nginx-server-configuration}s.
By default, the @code{default-location} will issue a redirect from
-@code{http://@var{host}/...} to @code{https://@var{host}/...}, leaving
+@code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving
you to define what to serve on your site via @code{https}.
Pass @code{#f} to not issue a default location.
@end table
@end deftp
-The public key and its signatures will be written to
-@code{/etc/letsencrypt/live/@var{host}/fullchain.pem}, for each
-@var{host} in the configuration. The private key is written to
-@code{/etc/letsencrypt/live/@var{host}/privkey.pem}.
+@deftp {Data Type} certificate-configuration
+Data type representing the configuration of a certificate.
+This type has the following parameters:
+@table @asis
+@item @code{name} (default: @i{see below})
+This name is used by Certbot for housekeeping and in file paths; it
+doesn't affect the content of the certificate itself. To see
+certificate names, run @code{certbot certificates}.
+
+Its default is the first provided domain.
+
+@item @code{domains} (default: @code{()})
+The first domain provided will be the subject CN of the certificate, and
+all domains will be Subject Alternative Names on the certificate.
+
+@item @code{deploy-hook} (default: @code{#f})
+Command to be run in a shell once for each successfully issued
+certificate. For this command, the shell variable
+@code{$RENEWED_LINEAGE} will point to the config live subdirectory (for
+example, @samp{"/etc/letsencrypt/live/example.com"}) containing the new
+certificates and keys; the shell variable @code{$RENEWED_DOMAINS} will
+contain a space-delimited list of renewed certificate domains (for
+example, @samp{"example.com www.example.com"}.
+
+@end table
+@end deftp
+For each @code{certificate-configuration}, the certificate is saved to
+@code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is
+saved to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}.
@node DNS Services
@subsubsection DNS Services
@cindex DNS (domain name system)
The @code{(gnu services dns)} module provides services related to the
@dfn{domain name system} (DNS). It provides a server service for hosting
an @emph{authoritative} DNS server for multiple zones, slave or master.
-This service uses @uref{https://www.knot-dns.cz/, Knot DNS}.
+This service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a
+caching and forwarding DNS server for the LAN, which uses
+@uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}.
+
+@subsubheading Knot Service
An example configuration of an authoritative server for two zones, one master
and one slave, is:
@end table
@end deftp
+@subsubheading Dnsmasq Service
+
+@deffn {Scheme Variable} dnsmasq-service-type
+This is the type of the dnsmasq service, whose value should be an
+@code{dnsmasq-configuration} object as in this example:
+
+@example
+(service dnsmasq-service-type
+ (dnsmasq-configuration
+ (no-resolv? #t)
+ (servers '("192.168.1.1"))))
+@end example
+@end deffn
+
+@deftp {Data Type} dnsmasq-configuration
+Data type representing the configuration of dnsmasq.
+
+@table @asis
+@item @code{package} (default: @var{dnsmasq})
+Package object of the dnsmasq server.
+
+@item @code{no-hosts?} (default: @code{#f})
+When true, don't read the hostnames in /etc/hosts.
+
+@item @code{port} (default: @code{53})
+The port to listen on. Setting this to zero completely disables DNS
+funtion, leaving only DHCP and/or TFTP.
+
+@item @code{local-service?} (default: @code{#t})
+Accept DNS queries only from hosts whose address is on a local subnet,
+ie a subnet for which an interface exists on the server.
+
+@item @code{listen-addresses} (default: @code{'()})
+Listen on the given IP addresses.
+
+@item @code{resolv-file} (default: @code{"/etc/resolv.conf"})
+The file to read the IP address of the upstream nameservers from.
+
+@item @code{no-resolv?} (default: @code{#f})
+When true, don't read @var{resolv-file}.
+
+@item @code{servers} (default: @code{'()})
+Specify IP address of upstream servers directly.
+
+@item @code{cache-size} (default: @code{150})
+Set the size of dnsmasq's cache. Setting the cache size to zero
+disables caching.
+
+@item @code{negative-cache?} (default: @code{#t})
+When false, disable negative caching.
+
+@end table
+@end deftp
@node VPN Services
@subsubsection VPN Services
@subsubsection Version Control Services
The @code{(gnu services version-control)} module provides a service to
-allow remote access to local Git repositories. There are two options:
+allow remote access to local Git repositories. There are three options:
the @code{git-daemon-service}, which provides access to repositories via
-the @code{git://} unsecured TCP-based protocol, or extending the
+the @code{git://} unsecured TCP-based protocol, extending the
@code{nginx} web server to proxy some requests to
-@code{git-http-backend}.
+@code{git-http-backend}, or providing a web interface with
+@code{cgit-service-type}.
@deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)]
system services. @xref{Web Services}.
@end deffn
-@node Game Services
-@subsubsection Game Services
+@subsubheading Cgit Service
-@subsubheading The Battle for Wesnoth Service
-@cindex wesnothd
-@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn
-based tactical strategy game, with several single player campaigns, and
-multiplayer games (both networked and local).
+@cindex Cgit service
+@cindex Git, web interface
+@uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
+repositories written in C.
-@defvar {Scheme Variable} wesnothd-service-type
-Service type for the wesnothd service. Its value must be a
-@code{wesnothd-configuration} object. To run wesnothd in the default
-configuration, instantiate it as:
+The following example will configure the service with default values.
+By default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
@example
-(service wesnothd-service-type)
+(service cgit-service-type)
@end example
-@end defvar
-@deftp {Data Type} wesnothd-configuration
-Data type representing the configuration of @command{wesnothd}.
+The @code{file-object} type designates either a file-like object
+(@pxref{G-Expressions, file-like objects}) or a string.
-@table @asis
-@item @code{package} (default: @code{wesnoth-server})
-The wesnoth server package to use.
+@c %start of fragment
-@item @code{port} (default: @code{15000})
-The port to bind the server to.
-@end table
-@end deftp
+Available @code{cgit-configuration} fields are:
-@node Miscellaneous Services
-@subsubsection Miscellaneous Services
+@deftypevr {@code{cgit-configuration} parameter} package package
+The CGIT package.
-@cindex sysctl
-@subsubheading System Control Service
+@end deftypevr
-The @code{(gnu services sysctl)} provides a service to configure kernel
-parameters at boot.
+@deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx
+NGINX configuration.
-@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:
+@end deftypevr
-@example
-(service sysctl-service-type
- (sysctl-configuration
- (settings '(("net.ipv4.ip_forward" . "1")))))
-@end example
-@end defvr
+@deftypevr {@code{cgit-configuration} parameter} file-object about-filter
+Specifies a command which will be invoked to format the content of about
+pages (both top-level and for each repository).
-@deftp {Data Type} sysctl-configuration
-The data type representing the configuration of @command{sysctl}.
+Defaults to @samp{""}.
-@table @asis
-@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
-The @command{sysctl} executable to use.
+@end deftypevr
-@item @code{settings} (default: @code{'()})
-An association list specifies kernel parameters and their values.
-@end table
-@end deftp
+@deftypevr {@code{cgit-configuration} parameter} string agefile
+Specifies a path, relative to each repository path, which can be used to
+specify the date and time of the youngest commit in the repository.
-@cindex lirc
-@subsubheading Lirc Service
+Defaults to @samp{""}.
-The @code{(gnu services lirc)} module provides the following service.
+@end deftypevr
-@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
- [#:device #f] [#:driver #f] [#:config-file #f] @
- [#:extra-options '()]
-Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
-decodes infrared signals from remote controls.
+@deftypevr {@code{cgit-configuration} parameter} file-object auth-filter
+Specifies a command that will be invoked for authenticating repository
+access.
-Optionally, @var{device}, @var{driver} and @var{config-file}
-(configuration file name) may be specified. See @command{lircd} manual
-for details.
+Defaults to @samp{""}.
-Finally, @var{extra-options} is a list of additional command-line options
-passed to @command{lircd}.
-@end deffn
+@end deftypevr
-@cindex spice
-@subsubheading Spice Service
+@deftypevr {@code{cgit-configuration} parameter} string branch-sort
+Flag which, when set to @samp{age}, enables date ordering in the branch
+ref list, and when set @samp{name} enables ordering by branch name.
-The @code{(gnu services spice)} module provides the following service.
+Defaults to @samp{"name"}.
-@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
-Returns a service that runs @url{http://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
+@end deftypevr
-@subsubsection Dictionary Services
-@cindex dictionary
-The @code{(gnu services dict)} module provides the following service:
+@deftypevr {@code{cgit-configuration} parameter} string cache-root
+Path used to store the cgit cache entries.
-@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
-Return a service that runs the @command{dicod} daemon, an implementation
-of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
+Defaults to @samp{"/var/cache/cgit"}.
-The optional @var{config} argument specifies the configuration for
-@command{dicod}, which should be a @code{<dicod-configuration>} object, by
-default it serves the GNU Collaborative International Dictonary of English.
+@end deftypevr
-You can add @command{open localhost} to your @file{~/.dico} file to make
-@code{localhost} the default server for @command{dico} client
-(@pxref{Initialization File,,, dico, GNU Dico Manual}).
-@end deffn
+@deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl
+Number which specifies the time-to-live, in minutes, for the cached
+version of repository pages accessed with a fixed SHA1.
-@deftp {Data Type} dicod-configuration
-Data type representing the configuration of dicod.
+Defaults to @samp{-1}.
-@table @asis
-@item @code{dico} (default: @var{dico})
-Package object of the GNU Dico dictionary server.
+@end deftypevr
-@item @code{interfaces} (default: @var{'("localhost")})
-This is the list of IP addresses and ports and possibly socket file
-names to listen to (@pxref{Server Settings, @code{listen} directive,,
-dico, GNU Dico Manual}).
+@deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl
+Number which specifies the time-to-live, in minutes, for the cached
+version of repository pages accessed without a fixed SHA1.
-@item @code{handlers} (default: @var{'()})
-List of @code{<dicod-handler>} objects denoting handlers (module instances).
+Defaults to @samp{5}.
-@item @code{databases} (default: @var{(list %dicod-database:gcide)})
-List of @code{<dicod-database>} objects denoting dictionaries to be served.
-@end table
-@end deftp
+@end deftypevr
-@deftp {Data Type} dicod-handler
-Data type representing a dictionary handler (module instance).
+@deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl
+Number which specifies the time-to-live, in minutes, for the cached
+version of the repository summary page.
-@table @asis
-@item @code{name}
-Name of the handler (module instance).
+Defaults to @samp{5}.
-@item @code{module} (default: @var{#f})
-Name of the dicod module of the handler (instance). If it is @code{#f},
-the module has the same name as the handler.
-(@pxref{Modules,,, dico, GNU Dico Manual}).
+@end deftypevr
-@item @code{options}
-List of strings or gexps representing the arguments for the module handler
-@end table
-@end deftp
+@deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl
+Number which specifies the time-to-live, in minutes, for the cached
+version of the repository index page.
-@deftp {Data Type} dicod-database
-Data type representing a dictionary database.
+Defaults to @samp{5}.
-@table @asis
-@item @code{name}
-Name of the database, will be used in DICT commands.
+@end deftypevr
-@item @code{handler}
-Name of the dicod handler (module instance) used by this database
-(@pxref{Handlers,,, dico, GNU Dico Manual}).
+@deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl
+Number which specifies the time-to-live, in minutes, for the result of
+scanning a path for Git repositories.
-@item @code{complex?} (default: @var{#f})
-Whether the database configuration complex. The complex configuration
-will need a corresponding @code{<dicod-handler>} object, otherwise not.
+Defaults to @samp{15}.
-@item @code{options}
-List of strings or gexps representing the arguments for the database
-(@pxref{Databases,,, dico, GNU Dico Manual}).
-@end table
-@end deftp
+@end deftypevr
-@defvr {Scheme Variable} %dicod-database:gcide
-A @code{<dicod-database>} object serving the GNU Collaborative International
-Dictionary of English using the @code{gcide} package.
-@end defvr
+@deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl
+Number which specifies the time-to-live, in minutes, for the cached
+version of the repository about page.
-The following is an example @code{dicod-service} configuration.
+Defaults to @samp{15}.
-@example
-(dicod-service #:config
- (dicod-configuration
- (handlers (list (dicod-handler
- (name "wordnet")
- (module "dictorg")
- (options
- (list #~(string-append "dbdir=" #$wordnet))))))
- (databases (list (dicod-database
- (name "wordnet")
- (complex? #t)
- (handler "wordnet")
- (options '("database=wn")))
- %dicod-database:gcide))))
-@end example
+@end deftypevr
+@deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl
+Number which specifies the time-to-live, in minutes, for the cached
+version of snapshots.
-@subsubheading Cgit Service
+Defaults to @samp{5}.
-@cindex Cgit service
-@cindex Git, web interface
-@uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
-repositories written in C.
+@end deftypevr
-The following example will configure the service with default values.
-By default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
+@deftypevr {@code{cgit-configuration} parameter} integer cache-size
+The maximum number of entries in the cgit cache. When set to @samp{0},
+caching is disabled.
-@example
-(service cgit-service-type)
-@end example
+Defaults to @samp{0}.
-@deftp {Data Type} cgit-configuration
-Data type representing the configuration of Cgit.
-This type has the following parameters:
+@end deftypevr
-@table @asis
-@item @code{config-file} (default: @code{(cgit-configuration-file)})
-The configuration file to use for Cgit. This can be set to a
-@dfn{cgit-configuration-file} record value, or any gexp
-(@pxref{G-Expressions}).
+@deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort?
+Sort items in the repo list case sensitively.
-For example, to instead use a local file, the @code{local-file} function
-can be used:
+Defaults to @samp{#t}.
-@example
-(service cgit-service-type
- (cgit-configuration
- (config-file (local-file "./my-cgitrc.conf"))))
-@end example
+@end deftypevr
-@item @code{package} (default: @code{cgit})
-The Cgit package to use.
+@deftypevr {@code{cgit-configuration} parameter} list clone-prefix
+List of common prefixes which, when combined with a repository URL,
+generates valid clone URLs for the repository.
-@end table
-@end deftp
+Defaults to @samp{()}.
-@deftp {Data Type} cgit-configuration-file
-Data type representing the configuration options for Cgit.
-This type has the following parameters:
+@end deftypevr
-@table @asis
-@item @code{css} (default: @code{"/share/cgit/cgit.css"})
-URL which specifies the css document to include in all Cgit pages.
+@deftypevr {@code{cgit-configuration} parameter} list clone-url
+List of @code{clone-url} templates.
-@item @code{logo} (default: @code{"/share/cgit/cgit.png"})
-URL which specifies the source of an image which will be used as a logo
-on all Cgit pages.
+Defaults to @samp{()}.
-@item @code{virtual-root} (default: @code{"/"})
-URL which, if specified, will be used as root for all Cgit links.
+@end deftypevr
-@item @code{repository-directory} (default: @code{"/srv/git"})
-Name of the directory to scan for repositories.
+@deftypevr {@code{cgit-configuration} parameter} file-object commit-filter
+Command which will be invoked to format commit messages.
-@item @code{robots} (default: @code{(list "noindex" "nofollow")})
-Text used as content for the ``robots'' meta-tag.
+Defaults to @samp{""}.
-@end table
-@end deftp
+@end deftypevr
-@node Setuid Programs
-@subsection Setuid Programs
+@deftypevr {@code{cgit-configuration} parameter} string commit-sort
+Flag which, when set to @samp{date}, enables strict date ordering in the
+commit log, and when set to @samp{topo} enables strict topological
+ordering.
-@cindex setuid programs
-Some programs need to run with ``root'' privileges, even when they are
-launched by unprivileged users. A notorious example is the
-@command{passwd} program, which users can run to change their
-password, and which needs to access the @file{/etc/passwd} and
-@file{/etc/shadow} files---something normally restricted to root, for
-obvious security reasons. To address that, these executables are
-@dfn{setuid-root}, meaning that they always run with root privileges
-(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
-for more info about the setuid mechanism.)
+Defaults to @samp{"git log"}.
-The store itself @emph{cannot} contain setuid programs: that would be a
-security issue since any user on the system can write derivations that
-populate the store (@pxref{The Store}). Thus, a different mechanism is
-used: instead of changing the setuid bit directly on files that are in
-the store, we let the system administrator @emph{declare} which programs
-should be setuid root.
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object css
+URL which specifies the css document to include in all cgit pages.
+
+Defaults to @samp{"/share/cgit/cgit.css"}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object email-filter
+Specifies a command which will be invoked to format names and email
+address of committers, authors, and taggers, as represented in various
+places throughout the cgit interface.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean embedded?
+Flag which, when set to @samp{#t}, will make cgit generate a HTML
+fragment suitable for embedding in other HTML pages.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph?
+Flag which, when set to @samp{#t}, will make cgit print an ASCII-art
+commit history graph to the left of the commit messages in the
+repository log page.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides?
+Flag which, when set to @samp{#t}, allows all filter settings to be
+overridden in repository-specific cgitrc files.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links?
+Flag which, when set to @samp{#t}, allows users to follow a file in the
+log view.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone?
+If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git
+clones.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links?
+Flag which, when set to @samp{#t}, will make cgit generate extra links
+"summary", "commit", "tree" for each repo in the repository index.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner?
+Flag which, when set to @samp{#t}, will make cgit display the owner of
+each repo in the repository index.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount?
+Flag which, when set to @samp{#t}, will make cgit print the number of
+modified files for each commit on the repository log page.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount?
+Flag which, when set to @samp{#t}, will make cgit print the number of
+added and removed lines for each commit on the repository log page.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches?
+Flag which, when set to @code{#t}, will make cgit display remote
+branches in the summary and refs views.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links?
+Flag which, when set to @code{1}, will make cgit use the subject of the
+parent commit as link text when generating links to parent commits in
+commit view.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving?
+Flag which, when set to @samp{#t}, will make cgit use the subject of the
+parent commit as link text when generating links to parent commits in
+commit view.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers?
+Flag which, when set to @samp{#t}, will make cgit generate linenumber
+links for plaintext blobs printed in the tree view.
+
+Defaults to @samp{#t}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config?
+Flag which, when set to @samp{#f}, will allow cgit to use Git config to
+set any repo specific settings.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object favicon
+URL used as link to a shortcut icon for cgit.
+
+Defaults to @samp{"/favicon.ico"}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string footer
+The content of the file specified with this option will be included
+verbatim at the bottom of all pages (i.e. it replaces the standard
+"generated by..." message).
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string head-include
+The content of the file specified with this option will be included
+verbatim in the HTML HEAD section on all pages.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string header
+The content of the file specified with this option will be included
+verbatim at the top of all pages.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object include
+Name of a configfile to include before the rest of the current config-
+file is parsed.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string index-header
+The content of the file specified with this option will be included
+verbatim above the repository index.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string index-info
+The content of the file specified with this option will be included
+verbatim below the heading on the repository index page.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean local-time?
+Flag which, if set to @samp{#t}, makes cgit print commit and tag times
+in the servers timezone.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object logo
+URL which specifies the source of an image which will be used as a logo
+on all cgit pages.
+
+Defaults to @samp{"/share/cgit/cgit.png"}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string logo-link
+URL loaded when clicking on the cgit logo image.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object owner-filter
+Command which will be invoked to format the Owner column of the main
+page.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer max-atom-items
+Number of items to display in atom feeds view.
+
+Defaults to @samp{10}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer max-commit-count
+Number of entries to list per page in "log" view.
+
+Defaults to @samp{50}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer max-message-length
+Number of commit message characters to display in "log" view.
+
+Defaults to @samp{80}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer max-repo-count
+Specifies the number of entries to list per page on the repository index
+page.
+
+Defaults to @samp{50}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length
+Specifies the maximum number of repo description characters to display
+on the repository index page.
+
+Defaults to @samp{80}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer max-blob-size
+Specifies the maximum size of a blob to display HTML for in KBytes.
+
+Defaults to @samp{0}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string max-stats
+Maximum statistics period. Valid values are @samp{week},@samp{month},
+@samp{quarter} and @samp{year}.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype
+Mimetype for the specified filename extension.
+
+Defaults to @samp{((gif "image/gif") (html "text/html") (jpg
+"image/jpeg") (jpeg "image/jpeg") (pdf "application/pdf") (png
+"image/png") (svg "image/svg+xml"))}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file
+Specifies the file to use for automatic mimetype lookup.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string module-link
+Text which will be used as the formatstring for a hyperlink when a
+submodule is printed in a directory listing.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean nocache?
+If set to the value @samp{#t} caching will be disabled.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean noplainemail?
+If set to @samp{#t} showing full author email addresses will be
+disabled.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean noheader?
+Flag which, when set to @samp{#t}, will make cgit omit the standard
+header on all pages.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} project-list project-list
+A list of subdirectories inside of @code{repository-directory}, relative
+to it, that should loaded as Git repositories. An empty list means that
+all subdirectories will be loaded.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object readme
+Text which will be used as default value for @code{cgit-repo-readme}.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix?
+If set to @code{#t} and @code{repository-directory} is enabled, if any
+repositories are found with a suffix of @code{.git}, this suffix will be
+removed for the URL and name.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer renamelimit
+Maximum number of files to consider when detecting renames.
+
+Defaults to @samp{-1}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string repository-sort
+The way in which repositories in each section are sorted.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} robots-list robots
+Text used as content for the @code{robots} meta-tag.
+
+Defaults to @samp{("noindex" "nofollow")}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string root-desc
+Text printed below the heading on the repository index page.
+
+Defaults to @samp{"a fast webinterface for the git dscm"}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string root-readme
+The content of the file specified with this option will be included
+verbatim below thef "about" link on the repository index page.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string root-title
+Text printed as heading on the repository index page.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path
+If set to @samp{#t} and repository-directory is enabled,
+repository-directory will recurse into directories whose name starts
+with a period. Otherwise, repository-directory will stay away from such
+directories, considered as "hidden". Note that this does not apply to
+the ".git" directory in non-bare repos.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} list snapshots
+Text which specifies the default set of snapshot formats that cgit
+generates links for.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory
+Name of the directory to scan for repositories (represents
+@code{scan-path}).
+
+Defaults to @samp{"/srv/git"}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string section
+The name of the current repository section - all repositories defined
+after this option will inherit the current section name.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string section-sort
+Flag which, when set to @samp{1}, will sort the sections on the
+repository listing by name.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer section-from-path
+A number which, if defined prior to repository-directory, specifies how
+many path elements from each repo path to use as a default section name.
+
+Defaults to @samp{0}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs?
+If set to @samp{#t} shows side-by-side diffs instead of unidiffs per
+default.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} file-object source-filter
+Specifies a command which will be invoked to format plaintext blobs in
+the tree view.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer summary-branches
+Specifies the number of branches to display in the repository "summary"
+view.
+
+Defaults to @samp{10}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer summary-log
+Specifies the number of log entries to display in the repository
+"summary" view.
+
+Defaults to @samp{10}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} integer summary-tags
+Specifies the number of tags to display in the repository "summary"
+view.
+
+Defaults to @samp{10}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string strict-export
+Filename which, if specified, needs to be present within the repository
+for cgit to allow access to that repository.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} string virtual-root
+URL which, if specified, will be used as root for all cgit links.
+
+Defaults to @samp{"/"}.
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories
+A list of @dfn{cgit-repo} records to use with config.
+
+Defaults to @samp{()}.
+
+Available @code{repository-cgit-configuration} fields are:
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots
+A mask of snapshot formats for this repo that cgit generates links for,
+restricted by the global @code{snapshots} setting.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter
+Override the default @code{source-filter}.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string url
+The relative URL used to access the repository.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter
+Override the default @code{about-filter}.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort
+Flag which, when set to @samp{age}, enables date ordering in the branch
+ref list, and when set to @samp{name} enables ordering by branch name.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url
+A list of URLs which can be used to clone repo.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter
+Override the default @code{commit-filter}.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort
+Flag which, when set to @samp{date}, enables strict date ordering in the
+commit log, and when set to @samp{topo} enables strict topological
+ordering.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch
+The name of the default branch for this repository. If no such branch
+exists in the repository, the first branch name (when sorted) is used as
+default instead. By default branch pointed to by HEAD, or "master" if
+there is no suitable HEAD.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc
+The value to show as repository description.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage
+The value to show as repository homepage.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter
+Override the default @code{email-filter}.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean enable-commit-graph?
+A flag which can be used to disable the global setting
+@code{enable-commit-graph?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean enable-log-filecount?
+A flag which can be used to disable the global setting
+@code{enable-log-filecount?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean enable-log-linecount?
+A flag which can be used to disable the global setting
+@code{enable-log-linecount?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean enable-remote-branches?
+Flag which, when set to @code{#t}, will make cgit display remote
+branches in the summary and refs views.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean enable-subject-links?
+A flag which can be used to override the global setting
+@code{enable-subject-links?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean enable-html-serving?
+A flag which can be used to override the global setting
+@code{enable-html-serving?}.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide?
+Flag which, when set to @code{#t}, hides the repository from the
+repository index.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore?
+Flag which, when set to @samp{#t}, ignores the repository.
+
+Defaults to @samp{#f}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo
+URL which specifies the source of an image which will be used as a logo
+on this repo’s pages.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link
+URL loaded when clicking on the cgit logo image.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter
+Override the default @code{owner-filter}.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link
+Text which will be used as the formatstring for a hyperlink when a
+submodule is printed in a directory listing. The arguments for the
+formatstring are the path and SHA1 of the submodule commit.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path
+Text which will be used as the formatstring for a hyperlink when a
+submodule with the specified subdirectory path is printed in a directory
+listing.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats
+Override the default maximum statistics period.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string name
+The value to show as repository name.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner
+A value used to identify the owner of the repository.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string path
+An absolute path to the repository directory.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme
+A path (relative to repo) which specifies a file to include verbatim as
+the "About" page for this repo.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-string section
+The name of the current repository section - all repositories defined
+after this option will inherit the current section name.
+
+Defaults to @samp{""}.
+
+@end deftypevr
+
+@deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options
+Extra options will be appended to cgitrc file.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+@end deftypevr
+
+@deftypevr {@code{cgit-configuration} parameter} list extra-options
+Extra options will be appended to cgitrc file.
+
+Defaults to @samp{()}.
+
+@end deftypevr
+
+
+@c %end of fragment
+
+However, it could be that you just want to get a @code{cgitrc} up and
+running. In that case, you can pass an @code{opaque-cgit-configuration}
+as a record to @code{cgit-service-type}. As its name indicates, an
+opaque configuration does not have easy reflective capabilities.
+
+Available @code{opaque-cgit-configuration} fields are:
+
+@deftypevr {@code{opaque-cgit-configuration} parameter} package cgit
+The cgit package.
+@end deftypevr
+
+@deftypevr {@code{opaque-cgit-configuration} parameter} string string
+The contents of the @code{cgitrc}, as a string.
+@end deftypevr
+
+For example, if your @code{cgitrc} is just the empty string, you
+could instantiate a cgit service like this:
+
+@example
+(service cgit-service-type
+ (opaque-cgit-configuration
+ (cgitrc "")))
+@end example
+
+
+@node Game Services
+@subsubsection Game Services
+
+@subsubheading The Battle for Wesnoth Service
+@cindex wesnothd
+@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn
+based tactical strategy game, with several single player campaigns, and
+multiplayer games (both networked and local).
+
+@defvar {Scheme Variable} wesnothd-service-type
+Service type for the wesnothd service. Its value must be a
+@code{wesnothd-configuration} object. To run wesnothd in the default
+configuration, instantiate it as:
+
+@example
+(service wesnothd-service-type)
+@end example
+@end defvar
+
+@deftp {Data Type} wesnothd-configuration
+Data type representing the configuration of @command{wesnothd}.
+
+@table @asis
+@item @code{package} (default: @code{wesnoth-server})
+The wesnoth server package to use.
+
+@item @code{port} (default: @code{15000})
+The port to bind the server to.
+@end table
+@end deftp
+
+@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
+
+The @code{(gnu services lirc)} module provides the following service.
+
+@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
+ [#:device #f] [#:driver #f] [#:config-file #f] @
+ [#:extra-options '()]
+Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
+decodes infrared signals from remote controls.
+
+Optionally, @var{device}, @var{driver} and @var{config-file}
+(configuration file name) may be specified. See @command{lircd} manual
+for details.
+
+Finally, @var{extra-options} is a list of additional command-line options
+passed to @command{lircd}.
+@end deffn
+
+@cindex spice
+@subsubheading Spice Service
+
+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
+that enables sharing the clipboard with a vm and setting the guest display
+resolution when the graphical console window resizes.
+@end deffn
+
+@subsubsection Dictionary Services
+@cindex dictionary
+The @code{(gnu services dict)} module provides the following service:
+
+@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
+Return a service that runs the @command{dicod} daemon, an implementation
+of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
+
+The optional @var{config} argument specifies the configuration for
+@command{dicod}, which should be a @code{<dicod-configuration>} object, by
+default it serves the GNU Collaborative International Dictonary of English.
+
+You can add @command{open localhost} to your @file{~/.dico} file to make
+@code{localhost} the default server for @command{dico} client
+(@pxref{Initialization File,,, dico, GNU Dico Manual}).
+@end deffn
+
+@deftp {Data Type} dicod-configuration
+Data type representing the configuration of dicod.
+
+@table @asis
+@item @code{dico} (default: @var{dico})
+Package object of the GNU Dico dictionary server.
+
+@item @code{interfaces} (default: @var{'("localhost")})
+This is the list of IP addresses and ports and possibly socket file
+names to listen to (@pxref{Server Settings, @code{listen} directive,,
+dico, GNU Dico Manual}).
+
+@item @code{handlers} (default: @var{'()})
+List of @code{<dicod-handler>} objects denoting handlers (module instances).
+
+@item @code{databases} (default: @var{(list %dicod-database:gcide)})
+List of @code{<dicod-database>} objects denoting dictionaries to be served.
+@end table
+@end deftp
+
+@deftp {Data Type} dicod-handler
+Data type representing a dictionary handler (module instance).
+
+@table @asis
+@item @code{name}
+Name of the handler (module instance).
+
+@item @code{module} (default: @var{#f})
+Name of the dicod module of the handler (instance). If it is @code{#f},
+the module has the same name as the handler.
+(@pxref{Modules,,, dico, GNU Dico Manual}).
+
+@item @code{options}
+List of strings or gexps representing the arguments for the module handler
+@end table
+@end deftp
+
+@deftp {Data Type} dicod-database
+Data type representing a dictionary database.
+
+@table @asis
+@item @code{name}
+Name of the database, will be used in DICT commands.
+
+@item @code{handler}
+Name of the dicod handler (module instance) used by this database
+(@pxref{Handlers,,, dico, GNU Dico Manual}).
+
+@item @code{complex?} (default: @var{#f})
+Whether the database configuration complex. The complex configuration
+will need a corresponding @code{<dicod-handler>} object, otherwise not.
+
+@item @code{options}
+List of strings or gexps representing the arguments for the database
+(@pxref{Databases,,, dico, GNU Dico Manual}).
+@end table
+@end deftp
+
+@defvr {Scheme Variable} %dicod-database:gcide
+A @code{<dicod-database>} object serving the GNU Collaborative International
+Dictionary of English using the @code{gcide} package.
+@end defvr
+
+The following is an example @code{dicod-service} configuration.
+
+@example
+(dicod-service #:config
+ (dicod-configuration
+ (handlers (list (dicod-handler
+ (name "wordnet")
+ (module "dictorg")
+ (options
+ (list #~(string-append "dbdir=" #$wordnet))))))
+ (databases (list (dicod-database
+ (name "wordnet")
+ (complex? #t)
+ (handler "wordnet")
+ (options '("database=wn")))
+ %dicod-database:gcide))))
+@end example
+
+@node Setuid Programs
+@subsection Setuid Programs
+
+@cindex setuid programs
+Some programs need to run with ``root'' privileges, even when they are
+launched by unprivileged users. A notorious example is the
+@command{passwd} program, which users can run to change their
+password, and which needs to access the @file{/etc/passwd} and
+@file{/etc/shadow} files---something normally restricted to root, for
+obvious security reasons. To address that, these executables are
+@dfn{setuid-root}, meaning that they always run with root privileges
+(@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
+for more info about the setuid mechanism.)
+
+The store itself @emph{cannot} contain setuid programs: that would be a
+security issue since any user on the system can write derivations that
+populate the store (@pxref{The Store}). Thus, a different mechanism is
+used: instead of changing the setuid bit directly on files that are in
+the store, we let the system administrator @emph{declare} which programs
+should be setuid root.
The @code{setuid-programs} field of an @code{operating-system}
declaration contains a list of G-expressions denoting the names of
responsible for mounting the real root file system, and for loading any
kernel modules that may be needed to achieve that.
-The @code{initrd} field of an @code{operating-system} declaration allows
+The @code{initrd-modules} field of an @code{operating-system}
+declaration allows you to specify Linux-libre kernel modules that must
+be available in the initrd. In particular, this is where you would list
+modules needed to actually drive the hard disk where your root partition
+is---although the default value of @code{initrd-modules} should cover
+most use cases. For example, assuming you need the @code{megaraid_sas}
+module in addition to the default modules to be able to access your root
+file system, you would write:
+
+@example
+(operating-system
+ ;; @dots{}
+ (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
+@end example
+
+@defvr {Scheme Variable} %base-initrd-modules
+This is the list of kernel modules included in the initrd by default.
+@end defvr
+
+Furthermore, if you need lower-level customization, the @code{initrd}
+field of an @code{operating-system} declaration allows
you to specify which initrd you would like to use. The @code{(gnu
system linux-initrd)} module provides three ways to build an initrd: the
high-level @code{base-initrd} procedure and the low-level
@example
(initrd (lambda (file-systems . rest)
- ;; Create a standard initrd that has modules "foo.ko"
- ;; and "bar.ko", as well as their dependencies, in
- ;; addition to the modules available by default.
+ ;; Create a standard initrd but set up networking
+ ;; with the parameters QEMU expects by default.
(apply base-initrd file-systems
- #:extra-modules '("foo" "bar")
+ #:qemu-networking? #t
rest)))
@end example
@deffn {Monadic Procedure} base-initrd @var{file-systems} @
[#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]@
- [#:virtio? #t] [#:extra-modules '()]
-Return a monadic derivation that builds a generic initrd. @var{file-systems} is
-a list of file systems to be mounted by the initrd like for @code{raw-initrd}.
-@var{mapped-devices}, @var{qemu-networking?} and @var{volatile-root?}
-also behaves as in @code{raw-initrd}.
+ [#:linux-modules '()]
+Return a monadic derivation that builds a generic initrd, with kernel
+modules taken from @var{linux}. @var{file-systems} is a list of file-systems to be
+mounted by the initrd, possibly in addition to the root file system specified
+on the kernel command line via @code{--root}. @var{mapped-devices} is a list of device
+mappings to realize before @var{file-systems} are mounted.
-When @var{virtio?} is true, load additional modules so that the
-initrd can be used as a QEMU guest with para-virtualized I/O drivers.
+@var{qemu-networking?} and @var{volatile-root?} behaves as in @code{raw-initrd}.
The initrd is automatically populated with all the kernel modules necessary
-for @var{file-systems} and for the given options. However, additional kernel
-modules can be listed in @var{extra-modules}. They will be added to the initrd, and
+for @var{file-systems} and for the given options. Additional kernel
+modules can be listed in @var{linux-modules}. They will be added to the initrd, and
loaded at boot time in the order in which they appear.
@end deffn
be created. The @code{--image-size} option can be used to specify the
size of the image.
+@cindex System images, creation in various formats
+@cindex Creating system images in various formats
@item vm-image
@itemx disk-image
-Return a virtual machine or disk image of the operating system declared
-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.
+@itemx docker-image
+Return a virtual machine, disk image, or Docker image of the operating
+system declared 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. Docker images are built to contain exactly what they need, so
+the @option{--image-size} option is ignored in the case of
+@code{docker-image}.
You can specify the root file system type by using the
@option{--file-system-type} option. It defaults to @code{ext4}.
# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
@end example
+When using @code{docker-image}, a Docker image is produced. Guix builds
+the image from scratch, not from a pre-existing Docker base image. As a
+result, it contains @emph{exactly} what you define in the operating
+system configuration file. You can then load the image and launch a
+Docker container using commands like the following:
+
+@example
+image_id="$(docker load < guixsd-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
+@end example
+
+This command starts a new Docker container from the specified image. It
+will boot the GuixSD 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
+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}.
+
@item container
Return a script to run the operating system declared in @var{file}
within a container. Containers are a set of lightweight isolation
Make @var{file} a symlink to the result, and register it as a garbage
collector root.
+@item --skip-checks
+Skip pre-installation safety checks.
+
+By default, @command{guix system init} and @command{guix system
+reconfigure} perform safety checks: they make sure the file systems that
+appear in the @code{operating-system} declaration actually exist
+(@pxref{File Systems}), and that any Linux kernel modules that may be
+needed at boot time are listed in @code{initrd-modules} (@pxref{Initial
+RAM Disk}). Passing this option skips these tests altogether.
+
@item --on-error=@var{strategy}
Apply @var{strategy} when an error occurs when reading @var{file}.
@var{strategy} may be one of the following:
Otherwise, it must be a one-argument procedure. The procedure is called
by @code{fold-services} and is passed a list of values collected from
-extensions. It must return a value that is a valid parameter value for
-the service instance.
+extensions. It may return any single value.
@item @code{extend} (default: @code{#f})
If this is @code{#f}, services of this type cannot be extended.
Otherwise, it must be a two-argument procedure: @code{fold-services}
-calls it, passing it the initial value of the service as the first argument
-and the result of applying @code{compose} to the extension values as the
-second argument.
+calls it, passing it the initial value of the service as the first
+argument and the result of applying @code{compose} to the extension
+values as the second argument. It must return a value that is a valid
+parameter value for the service instance.
@end table
@xref{Service Types and Services}, for examples.
HCoop / jackhill / guix / guix.git / blobdiff