diff options
Diffstat (limited to 'doc/guix.texi')
| -rw-r--r-- | doc/guix.texi | 633 |
1 files changed, 462 insertions, 171 deletions
diff --git a/doc/guix.texi b/doc/guix.texi index a957930d37..2376cedc68 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -11,6 +11,10 @@ @c Identifier of the OpenPGP key used to sign tarballs and such. @set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 +@set KEY-SERVER pool.sks-keyservers.net + +@c The official substitute server used by default. +@set SUBSTITUTE-SERVER ci.guix.info @copying Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018 Ludovic Courtès@* @@ -31,7 +35,7 @@ Copyright @copyright{} 2016, 2017, 2018 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2017, 2018 Clément Lassieur@* -Copyright @copyright{} 2017 Mathieu Othacehe@* +Copyright @copyright{} 2017, 2018 Mathieu Othacehe@* Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, 2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* @@ -50,6 +54,9 @@ Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright @copyright{} 2018 Gábor Boskovits@* +Copyright @copyright{} 2018 Florian Pelz@* +Copyright @copyright{} 2018 Laura Lazzati@* +Copyright @copyright{} 2018 Alex Vong@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -101,8 +108,9 @@ package management tool written for the GNU system. @c how to join your own translation team and how to report issues with the @c translation. This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de -référence de GNU Guix}). If you would like to translate it in your native -language, consider joining the +référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch +zu GNU Guix}). If you would like to translate it in your native language, +consider joining the @uref{https://translationproject.org/domain/guix-manual.html, Translation Project}. @@ -193,6 +201,7 @@ Utilities * Invoking guix copy:: Copying to and from a remote store. * Invoking guix container:: Process isolation. * Invoking guix weather:: Assessing substitute availability. +* Invoking guix processes:: Listing client processes. Invoking @command{guix build} @@ -351,6 +360,7 @@ configuration in a transactional, reproducible, and stateless fashion (@pxref{System Configuration}). @cindex functional package management +@cindex isolation Under the hood, Guix implements the @dfn{functional package management} discipline pioneered by Nix (@pxref{Acknowledgments}). In Guix, the package build and installation process is seen @@ -384,6 +394,7 @@ garbage collection of packages (@pxref{Features}). @chapter Installation @cindex installing Guix +@cindex official website GNU Guix is available for download from its website at @url{http://www.gnu.org/software/guix/}. This section describes the software requirements of Guix, as well as how to install it and get @@ -395,6 +406,8 @@ instead, you want to install the complete GNU operating system, @pxref{System Installation}. @cindex foreign distro +@cindex directories related to foreign distro + When installed on a running GNU/Linux system---thereafter called a @dfn{foreign distro}---GNU@tie{}Guix complements the available tools without interference. Its data lives exclusively in two directories, @@ -417,6 +430,7 @@ Once installed, Guix can be updated by running @command{guix pull} @section Binary Installation @cindex installing Guix from binaries +@cindex installer script This section describes how to install Guix on an arbitrary system from a self-contained tarball providing binaries for Guix and for all its dependencies. This is often quicker than installing from source, which @@ -451,7 +465,8 @@ If that command fails because you do not have the required public key, then run this command to import it: @example -$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID} +$ gpg --keyserver @value{KEY-SERVER} \ + --recv-keys @value{OPENPGP-SIGNING-KEY-ID} @end example @noindent @@ -487,18 +502,20 @@ archive content is independent of its creation time, thus making it reproducible. @item -Make @code{root}'s profile available under @file{~root/.guix-profile}: +Make the profile available under @file{~root/.config/guix/current}, which is +where @command{guix pull} will install updates (@pxref{Invoking guix pull}): @example -# ln -sf /var/guix/profiles/per-user/root/guix-profile \ - ~root/.guix-profile +# mkdir -p ~root/.config/guix +# ln -sf /var/guix/profiles/per-user/root/current-guix \ + ~root/.config/guix/current @end example Source @file{etc/profile} to augment @code{PATH} and other relevant environment variables: @example -# GUIX_PROFILE="`echo ~root`/.guix-profile" ; \ +# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ source $GUIX_PROFILE/etc/profile @end example @@ -520,8 +537,8 @@ with these commands: @c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html @example -# cp ~root/.guix-profile/lib/systemd/system/guix-daemon.service \ - /etc/systemd/system/ +# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \ + /etc/systemd/system/ # systemctl start guix-daemon && systemctl enable guix-daemon @end example @@ -529,14 +546,16 @@ If your host distro uses the Upstart init system: @example # initctl reload-configuration -# cp ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/ +# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ + /etc/init/ # start guix-daemon @end example Otherwise, you can still start the daemon manually with: @example -# ~root/.guix-profile/bin/guix-daemon --build-users-group=guixbuild +# ~root/.config/guix/current/bin/guix-daemon \ + --build-users-group=guixbuild @end example @item @@ -546,7 +565,7 @@ for instance with: @example # mkdir -p /usr/local/bin # cd /usr/local/bin -# ln -s /var/guix/profiles/per-user/root/guix-profile/bin/guix +# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix @end example It is also a good idea to make the Info version of this manual available @@ -555,7 +574,7 @@ there: @example # mkdir -p /usr/local/share/info # cd /usr/local/share/info -# for i in /var/guix/profiles/per-user/root/guix-profile/share/info/* ; +# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ; do ln -s $i ; done @end example @@ -570,7 +589,8 @@ To use substitutes from @code{hydra.gnu.org} or one of its mirrors (@pxref{Substitutes}), authorize them: @example -# guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub +# guix archive --authorize < \ + ~root/.config/guix/current/share/guix/hydra.gnu.org.pub @end example @item @@ -601,10 +621,11 @@ make guix-binary.@var{system}.tar.xz @end example @noindent -... which, in turn, runs: +...@: which, in turn, runs: @example -guix pack -s @var{system} --localstatedir guix +guix pack -s @var{system} --localstatedir \ + --profile-name=current-guix guix @end example @xref{Invoking guix pack}, for more info on this handy tool. @@ -629,12 +650,13 @@ later, including 2.2.x; (@pxref{Guile Preparations, how to install the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}); @item -@uref{https://notabug.org/civodul/guile-sqlite3, Guile-SQLite3}, version 0.1.0 +@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0 or later; @item @c FIXME: Specify a version number once a release has been made. @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August 2017 or later; +@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}; @item @url{http://zlib.net, zlib}; @item @url{http://www.gnu.org/software/make/, GNU Make}. @end itemize @@ -643,13 +665,6 @@ The following dependencies are optional: @itemize @item -Installing -@url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will -allow you to use the @command{guix import pypi} command (@pxref{Invoking -guix import}). It is of -interest primarily for developers and not for casual users. - -@item @c Note: We need at least 0.10.2 for 'channel-send-eof'. Support for build offloading (@pxref{Daemon Offload Setup}) and @command{guix copy} (@pxref{Invoking guix copy}) depends on @@ -1227,17 +1242,20 @@ etc. This helps achieve reproducible builds (@pxref{Features}). When the daemon performs a build on behalf of the user, it creates a build directory under @file{/tmp} or under the directory specified by -its @code{TMPDIR} environment variable; this directory is shared with -the container for the duration of the build. Be aware that using a -directory other than @file{/tmp} can affect build results---for example, -with a longer directory name, a build process that uses Unix-domain -sockets might hit the name length limitation for @code{sun_path}, which -it would otherwise not hit. +its @code{TMPDIR} environment variable. This directory is shared with +the container for the duration of the build, though within the container, +the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}. The build directory is automatically deleted upon completion, unless the build failed and the client specified @option{--keep-failed} (@pxref{Invoking guix build, @option{--keep-failed}}). +The daemon listens for connections and spawns one sub-process for each session +started by a client (one of the @command{guix} sub-commands.) The +@command{guix processes} command allows you to get an overview of the activity +on your system by viewing each of the active sessions and clients. +@xref{Invoking guix processes}, for more information. + The following command-line options are supported: @table @code @@ -1259,8 +1277,7 @@ remote procedure call (@pxref{The Store}). @anchor{daemon-substitute-urls} Consider @var{urls} the default whitespace-separated list of substitute source URLs. When this option is omitted, -@indicateurl{https://mirror.hydra.gnu.org https://hydra.gnu.org} is used -(@code{mirror.hydra.gnu.org} is a mirror of @code{hydra.gnu.org}). +@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used. This means that substitutes may be downloaded from @var{urls}, as long as they are signed by a trusted signature (@pxref{Substitutes}). @@ -2306,7 +2323,7 @@ also result from derivation builds, can be available as substitutes. @cindex hydra @cindex build farm -The @code{mirror.hydra.gnu.org} server is a front-end to an official build farm +The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official build farm that builds packages from Guix continuously for some architectures, and makes them available as substitutes. This is the default source of substitutes; it can be overridden by passing the @@ -2338,33 +2355,28 @@ other substitute server. @cindex substitutes, authorization thereof @cindex access control list (ACL), for substitutes @cindex ACL (access control list), for substitutes -To allow Guix to download substitutes from @code{hydra.gnu.org} or a +To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} or a mirror thereof, you must add its public key to the access control list (ACL) of archive imports, using the @command{guix archive} command (@pxref{Invoking guix -archive}). Doing so implies that you trust @code{hydra.gnu.org} to not +archive}). Doing so implies that you trust @code{@value{SUBSTITUTE-SERVER}} to not be compromised and to serve genuine substitutes. -The public key for @code{hydra.gnu.org} is installed along with Guix, in -@code{@var{prefix}/share/guix/hydra.gnu.org.pub}, where @var{prefix} is +The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with Guix, in +@code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where @var{prefix} is the installation prefix of Guix. If you installed Guix from source, make sure you checked the GPG signature of @file{guix-@value{VERSION}.tar.gz}, which contains this public key file. Then, you can run something like this: @example -# guix archive --authorize < @var{prefix}/share/guix/hydra.gnu.org.pub +# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub @end example @quotation Note -Similarly, the @file{berlin.guixsd.org.pub} file contains the public key -for the project's new build farm, reachable at -@indicateurl{https://berlin.guixsd.org}. - -As of this writing @code{berlin.guixsd.org} is being upgraded so it can -better scale up, but you might want to give it a try. It is backed by -20 x86_64/i686 build nodes and may be able to provide substitutes more -quickly than @code{mirror.hydra.gnu.org}. +Similarly, the @file{hydra.gnu.org.pub} file contains the public key +of an independent build farm also run by the project, reachable at +@indicateurl{https://mirror.hydra.gnu.org}. @end quotation Once this is in place, the output of a command like @code{guix build} @@ -2394,7 +2406,7 @@ $ guix build emacs --dry-run @end example @noindent -This indicates that substitutes from @code{hydra.gnu.org} are usable and +This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are usable and will be downloaded, when possible, for future builds. @cindex substitutes, how to disable @@ -2486,9 +2498,9 @@ by a server. Today, each individual's control over their own computing is at the mercy of institutions, corporations, and groups with enough power and determination to subvert the computing infrastructure and exploit its -weaknesses. While using @code{hydra.gnu.org} substitutes can be +weaknesses. While using @code{@value{SUBSTITUTE-SERVER}} substitutes can be convenient, we encourage users to also build on their own, or even run -their own build farm, such that @code{hydra.gnu.org} is less of an +their own build farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an interesting target. One way to help is by publishing the software you build using @command{guix publish} so that others have one more choice of server to download substitutes from (@pxref{Invoking guix publish}). @@ -2838,9 +2850,6 @@ The @command{guix pull} command is usually invoked with no arguments, but it supports the following options: @table @code -@item --verbose -Produce verbose output, writing build logs to the standard error output. - @item --url=@var{url} @itemx --commit=@var{commit} @itemx --branch=@var{branch} @@ -2874,6 +2883,14 @@ current generation only. @itemx -p @var{profile} Use @var{profile} instead of @file{~/.config/guix/current}. +@item --dry-run +@itemx -n +Show which channel commit(s) would be used and what would be built or +substituted but do not actually do it. + +@item --verbose +Produce verbose output, writing build logs to the standard error output. + @item --bootstrap Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers. @@ -2989,7 +3006,7 @@ channel(s): @end lisp @noindent -Note that the snippet above is (as always!) Scheme code; we use @code{cons} to +Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to add a channel the list of channels that the variable @code{%default-channels} is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference Manual}). With this file in place, @command{guix pull} builds not only Guix @@ -3020,6 +3037,39 @@ the new and upgraded packages that are listed, some like @code{my-gimp} and @code{my-emacs-with-cool-features} might come from @code{my-personal-packages}, while others come from the Guix default channel. +@cindex dependencies, channels +@cindex meta-data, channels +@subsection Declaring Channel Dependencies + +Channel authors may decide to augment a package collection provided by other +channels. They can declare their channel to be dependent on other channels in +a meta-data file @file{.guix-channel}, which is to be placed in the root of +the channel repository. + +The meta-data file should contain a simple S-expression like this: + +@lisp +(channel + (version 0) + (dependencies + (channel + (name 'some-collection) + (url "https://example.org/first-collection.git")) + (channel + (name 'some-other-collection) + (url "https://example.org/second-collection.git") + (branch "testing")))) +@end lisp + +In the above example this channel is declared to depend on two other channels, +which will both be fetched automatically. The modules provided by the channel +will be compiled in an environment where the modules of all these declared +channels are available. + +For the sake of reliability and maintainability, you should avoid dependencies +on channels that you don't control, and you should aim to keep the number of +dependencies to a minimum. + @subsection Replicating Guix @cindex pinning, channels @@ -3253,8 +3303,17 @@ produce human-readable output; @item channels produce a list of channel specifications that can be passed to @command{guix pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking -guix pull}). +guix pull}); +@item json +@cindex JSON +produce a list of channel specifications in JSON format; +@item recutils +produce a list of channel specifications in Recutils format. @end table + +@item --profile=@var{profile} +@itemx -p @var{profile} +Display information about @var{profile}. @end table @node Invoking guix pack @@ -3387,7 +3446,7 @@ guix pack -R -S /mybin=bin bash @end example @noindent -... you can copy that pack to a machine that lacks Guix, and from your +...@: you can copy that pack to a machine that lacks Guix, and from your home directory as a normal user, run: @example @@ -3459,8 +3518,11 @@ For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin} symlink pointing to the @file{bin} sub-directory of the profile. @item --localstatedir -Include the ``local state directory'', @file{/var/guix}, in the -resulting pack. +@itemx --profile-name=@var{name} +Include the ``local state directory'', @file{/var/guix}, in the resulting +pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}} +profile---by default @var{name} is @code{guix-profile}, which corresponds to +@file{~root/.guix-profile}. @file{/var/guix} contains the store database (@pxref{The Store}) as well as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in @@ -3626,11 +3688,11 @@ Read a single-item archive as served by substitute servers low-level operation needed in only very narrow use cases; see below. For example, the following command extracts the substitute for Emacs -served by @code{hydra.gnu.org} to @file{/tmp/emacs}: +served by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}: @example $ wget -O - \ - https://hydra.gnu.org/nar/@dots{}-emacs-24.5 \ + https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \ | bunzip2 | guix archive -x /tmp/emacs @end example @@ -4376,6 +4438,63 @@ The @code{install} phase installs the binaries, and it also installs the source code and @file{Cargo.toml} file. @end defvr +@cindex Clojure (programming language) +@cindex simple Clojure build system +@defvr {Scheme Variable} clojure-build-system +This variable is exported by @code{(guix build-system clojure)}. It implements +a simple build procedure for @uref{https://clojure.org/, Clojure} packages +using plain old @code{compile} in Clojure. Cross-compilation is not supported +yet. + +It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs. +Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and +@code{#:zip} parameters, respectively. + +A list of source directories, test directories and jar names can be specified +with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names} +parameters, respectively. Compile directory and main class can be specified +with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively. +Other parameters are documented below. + +This build system is an extension of @var{ant-build-system}, but with the +following phases changed: + +@table @code + +@item build +This phase calls @code{compile} in Clojure to compile source files and runs +@command{jar} to create jars from both source files and compiled files +according to the include list and exclude list specified in +@code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude list +has priority over the include list. These lists consist of symbols +representing Clojure libraries or the special keyword @code{#:all} representing +all Clojure libraries found under the source directories. The parameter +@code{#:omit-source?} decides if source should be included into the jars. + +@item check +This phase runs tests according to the include list and exclude list specified +in @code{#:test-include} and @code{#:test-exclude}, respectively. Their +meanings are analogous to that of @code{#:aot-include} and +@code{#:aot-exclude}, except that the special keyword @code{#:all} now +stands for all Clojure libraries found under the test directories. The +parameter @code{#:tests?} decides if tests should be run. + +@item install +This phase installs all jars built previously. +@end table + +Apart from the above, this build system also contains an additional phase: + +@table @code + +@item install-doc +This phase installs all top-level files with base name matching +@var{%doc-regex}. A different regex can be specified with the +@code{#:doc-regex} parameter. All files (recursively) inside the documentation +directories specified in @code{#:doc-dirs} are installed as well. +@end table +@end defvr + @defvr {Scheme Variable} cmake-build-system This variable is exported by @code{(guix build-system cmake)}. It implements the build procedure for packages using the @@ -4684,7 +4803,7 @@ package is installed in its own directory under @defvr {Scheme Variable} font-build-system This variable is exported by @code{(guix build-system font)}. It implements an installation procedure for font packages where upstream -provides pre-compiled TrueType, OpenType, etc. font files that merely +provides pre-compiled TrueType, OpenType, etc.@: font files that merely need to be copied into place. It copies font files to standard locations in the output directory. @end defvr @@ -4965,7 +5084,7 @@ a derivation is the @code{derivation} procedure: [#:system (%current-system)] [#:references-graphs #f] @ [#:allowed-references #f] [#:disallowed-references #f] @ [#:leaked-env-vars #f] [#:local-build? #f] @ - [#:substitutable? #t] + [#:substitutable? #t] [#:properties '()] Build a derivation with the given arguments, and return the resulting @code{<derivation>} object. @@ -5002,6 +5121,9 @@ When @var{substitutable?} is false, declare that substitutes of the derivation's output should not be used (@pxref{Substitutes}). This is useful, for instance, when building packages that capture details of the host CPU instruction set. + +@var{properties} must be an association list describing ``properties'' of the +derivation. It is kept as-is, uninterpreted, in the derivation. @end deffn @noindent @@ -5695,7 +5817,8 @@ information about monads.) [#:leaked-env-vars #f] @ [#:script-name (string-append @var{name} "-builder")] @ [#:deprecation-warnings #f] @ - [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f] + [#:local-build? #f] [#:substitutable? #t] @ + [#:properties '()] [#:guile-for-build #f] Return a derivation @var{name} that runs @var{exp} (a gexp) with @var{guile-for-build} (a derivation) on @var{system}; @var{exp} is stored in a file called @var{script-name}. When @var{target} is true, @@ -6051,6 +6174,7 @@ the Scheme programming interface of Guix in a convenient way. * Invoking guix copy:: Copying to and from a remote store. * Invoking guix container:: Process isolation. * Invoking guix weather:: Assessing substitute availability. +* Invoking guix processes:: Listing client processes. @end menu @node Invoking guix build @@ -6133,6 +6257,10 @@ the end of the build log. This is useful when debugging build issues. @xref{Debugging Build Failures}, for tips and tricks on how to debug build issues. +This option has no effect when connecting to a remote daemon with a +@code{guix://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET} +variable}). + @item --keep-going @itemx -k Keep going when some of the derivations fail to build; return only once @@ -6347,6 +6475,38 @@ must be compatible. If @var{replacement} is somehow incompatible with @var{package}, then the resulting package may be unusable. Use with care! +@item --with-branch=@var{package}=@var{branch} +@cindex Git, using the latest commit +@cindex latest commit, building +Build @var{package} from the latest commit of @var{branch}. The @code{source} +field of @var{package} must be an origin with the @code{git-fetch} method +(@pxref{origin Reference}) or a @code{git-checkout} object; the repository URL +is taken from that @code{source}. + +For instance, the following command builds @code{guile-sqlite3} from the +latest commit of its @code{master} branch, and then builds @code{guix} (which +depends on it) and @code{cuirass} (which depends on @code{guix}) against this +specific @code{guile-sqlite3} build: + +@example +guix build --with-branch=guile-sqlite3=master cuirass +@end example + +@cindex continuous integration +Obviously, since it uses the latest commit of the given branch, the result of +such a command varies over time. Nevertheless it is a convenient way to +rebuild entire software stacks against the latest commit of one or more +packages. This is particularly useful in the context of continuous +integration (CI). + +Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up +consecutive accesses to the same repository. You may want to clean it up once +in a while to save disk space. + +@item --with-commit=@var{package}=@var{commit} +This is similar to @code{--with-branch}, except that it builds from +@var{commit} rather than the tip of a branch. @var{commit} must be a valid +Git commit SHA1 identifier. @end table @node Additional Build Options @@ -6430,7 +6590,7 @@ The following derivations will be built: @item transitive Build the source derivations of all packages, as well of all transitive -inputs to the packages. This can be used e.g. to +inputs to the packages. This can be used e.g.@: to prefetch package source for later offline building. @example @@ -6553,7 +6713,7 @@ but you are actually on an @code{x86_64} machine: @example $ guix build --log-file gdb -s mips64el-linux -https://hydra.gnu.org/log/@dots{}-gdb-7.10 +https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10 @end example You can freely access a huge library of build logs! @@ -6833,12 +6993,11 @@ refresh, @code{--key-download}}. @item pypi @cindex pypi Import metadata from the @uref{https://pypi.python.org/, Python Package -Index}@footnote{This functionality requires Guile-JSON to be installed. -@xref{Requirements}.}. Information is taken from the JSON-formatted -description available at @code{pypi.python.org} and usually includes all -the relevant information, including package dependencies. For maximum -efficiency, it is recommended to install the @command{unzip} utility, so -that the importer can unzip Python wheels and gather data from them. +Index}. Information is taken from the JSON-formatted description +available at @code{pypi.python.org} and usually includes all the relevant +information, including package dependencies. For maximum efficiency, it +is recommended to install the @command{unzip} utility, so that the +importer can unzip Python wheels and gather data from them. The command below imports metadata for the @code{itsdangerous} Python package: @@ -6857,16 +7016,14 @@ in Guix. @item gem @cindex gem -Import metadata from @uref{https://rubygems.org/, -RubyGems}@footnote{This functionality requires Guile-JSON to be -installed. @xref{Requirements}.}. Information is taken from the -JSON-formatted description available at @code{rubygems.org} and includes -most relevant information, including runtime dependencies. There are -some caveats, however. The metadata doesn't distinguish between -synopses and descriptions, so the same string is used for both fields. -Additionally, the details of non-Ruby dependencies required to build -native extensions is unavailable and left as an exercise to the -packager. +Import metadata from @uref{https://rubygems.org/, RubyGems}. Information +is taken from the JSON-formatted description available at +@code{rubygems.org} and includes most relevant information, including +runtime dependencies. There are some caveats, however. The metadata +doesn't distinguish between synopses and descriptions, so the same string +is used for both fields. Additionally, the details of non-Ruby +dependencies required to build native extensions is unavailable and left +as an exercise to the packager. The command below imports metadata for the @code{rails} Ruby package: @@ -6884,9 +7041,7 @@ in Guix. @item cpan @cindex CPAN -Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}@footnote{This -functionality requires Guile-JSON to be installed. -@xref{Requirements}.}. +Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}. Information is taken from the JSON-formatted metadata provided through @uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most relevant information, such as module dependencies. License information @@ -6970,10 +7125,8 @@ guix import texlive --archive=generic ifxetex @item json @cindex JSON, import -Import package metadata from a local JSON file@footnote{This -functionality requires Guile-JSON to be installed. -@xref{Requirements}.}. Consider the following example package -definition in JSON format: +Import package metadata from a local JSON file. Consider the following +example package definition in JSON format: @example @{ @@ -7452,7 +7605,7 @@ Use @var{host} as the OpenPGP key server when importing a public key. The @code{github} updater uses the @uref{https://developer.github.com/v3/, GitHub API} to query for new -releases. When used repeatedly e.g. when refreshing all packages, +releases. When used repeatedly e.g.@: when refreshing all packages, GitHub will eventually refuse to answer any further API requests. By default 60 API requests per hour are allowed, and a full refresh on all GitHub packages in Guix requires more than this. Authentication with @@ -7488,7 +7641,7 @@ Identify inputs that should most likely be native inputs. @itemx source-file-name Probe @code{home-page} and @code{source} URLs and report those that are invalid. Suggest a @code{mirror://} URL when applicable. Check that -the source file name is meaningful, e.g. is not +the source file name is meaningful, e.g.@: is not just a version number or ``git-checkout'', without a declared @code{file-name} (@pxref{origin Reference}). @@ -7751,7 +7904,7 @@ This shows the @emph{reverse} DAG of packages. For example: guix graph --type=reverse-package ocaml @end example -... yields the graph of packages that depend on OCaml. +...@: yields the graph of packages that depend on OCaml. Note that for core packages this can yield huge graphs. If all you want is to know the number of packages that depend on a given package, use @@ -7767,7 +7920,7 @@ For instance, the following command: guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf @end example -... yields this bigger graph: +...@: yields this bigger graph: @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils} @@ -7938,7 +8091,7 @@ fi @end example @noindent -... or to browse the profile: +...@: or to browse the profile: @example $ ls "$GUIX_ENVIRONMENT/bin" @@ -8212,7 +8365,7 @@ When @command{guix publish} runs, it spawns an HTTP server which allows anyone with network access to obtain substitutes from it. This means that any machine running Guix can also act as if it were a build farm, since the HTTP interface is compatible with Hydra, the software behind -the @code{hydra.gnu.org} build farm. +the @code{@value{SUBSTITUTE-SERVER}} build farm. For security, each substitute is signed, allowing recipients to check their authenticity and integrity (@pxref{Substitutes}). Because @@ -8449,20 +8602,20 @@ any given store item. The command output looks like this: @smallexample -$ guix challenge --substitute-urls="https://hydra.gnu.org https://guix.example.org" -updating list of substitutes from 'https://hydra.gnu.org'... 100.0% +$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org" +updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0% updating list of substitutes from 'https://guix.example.org'... 100.0% /gnu/store/@dots{}-openssl-1.0.2d contents differ: local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q + https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim /gnu/store/@dots{}-git-2.5.0 contents differ: local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha - https://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f + https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 /gnu/store/@dots{}-pius-2.1.1 contents differ: local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - https://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax + https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs @dots{} @@ -8482,7 +8635,7 @@ the servers obtained a result different from the local build. @cindex non-determinism, in package builds As an example, @code{guix.example.org} always gets a different answer. -Conversely, @code{hydra.gnu.org} agrees with local builds, except in the +Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, except in the case of Git. This might indicate that the build process of Git is non-deterministic, meaning that its output varies as a function of various things that Guix does not fully control, in spite of building @@ -8496,14 +8649,14 @@ To find out what is wrong with this Git binary, we can do something along these lines (@pxref{Invoking guix archive}): @example -$ wget -q -O - https://hydra.gnu.org/nar/@dots{}-git-2.5.0 \ +$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \ | guix archive -x /tmp/git $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git @end example This command shows the difference between the files resulting from the local build, and the files resulting from the build on -@code{hydra.gnu.org} (@pxref{Overview, Comparing and Merging Files,, +@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging Files,, diffutils, Comparing and Merging Files}). The @command{diff} command works great for text files. When binary files differ, a better option is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps @@ -8518,7 +8671,7 @@ In the meantime, @command{guix challenge} is one tool to help address the problem. If you are writing packages for Guix, you are encouraged to check -whether @code{hydra.gnu.org} and other substitute servers obtain the +whether @code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the same build result as you did with: @example @@ -8751,6 +8904,61 @@ with the @code{-m} option of @command{guix package} (@pxref{Invoking guix package}). @end table +@node Invoking guix processes +@section Invoking @command{guix processes} + +The @command{guix processes} command can be useful to developers and system +administrators, especially on multi-user machines and on build farms: it lists +the current sessions (connections to the daemon), as well as information about +the processes involved@footnote{Remote sessions, when @command{guix-daemon} is +started with @option{--listen} specifying a TCP endpoint, are @emph{not} +listed.}. Here's an example of the information it returns: + +@example +$ sudo guix processes +SessionPID: 19002 +ClientPID: 19090 +ClientCommand: guix environment --ad-hoc python + +SessionPID: 19402 +ClientPID: 19367 +ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{} + +SessionPID: 19444 +ClientPID: 19419 +ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} +LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock +LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock +LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock +ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800 +ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800 +ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800 +@end example + +In this example we see that @command{guix-daemon} has three clients: +@command{guix environment}, @command{guix publish}, and the Cuirass continuous +integration tool; their process identifier (PID) is given by the +@code{ClientPID} field. The @code{SessionPID} field gives the PID of the +@command{guix-daemon} sub-process of this particular session. + +The @code{LockHeld} fields show which store items are currently locked by this +session, which corresponds to store items being built or substituted (the +@code{LockHeld} field is not displayed when @command{guix processes} is not +running as root.) Last, by looking at the @code{ChildProcess} field, we +understand that these three builds are being offloaded (@pxref{Daemon Offload +Setup}). + +The output is in Recutils format so we can use the handy @command{recsel} +command to select sessions of interest (@pxref{Selection Expressions,,, +recutils, GNU recutils manual}). As an example, the command shows the command +line and PID of the client that triggered the build of a Perl package: + +@example +$ sudo guix processes | \ + recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"' +ClientPID: 19419 +ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} +@end example @c ********************************************************************* @node GNU Distribution @@ -8894,7 +9102,7 @@ More and more system services are provided (@pxref{Services}), but some may be missing. @item -More than 7,500 packages are available, but you might +More than 8,500 packages are available, but you might occasionally find that a useful package is missing. @item @@ -8972,7 +9180,8 @@ If that command fails because you do not have the required public key, then run this command to import it: @example -$ gpg --keyserver pgp.mit.edu --recv-keys @value{OPENPGP-SIGNING-KEY-ID} +$ gpg --keyserver @value{KEY-SERVER} \ + --recv-keys @value{OPENPGP-SIGNING-KEY-ID} @end example @noindent @@ -9000,7 +9209,7 @@ its device name. Assuming that the USB stick is known as @file{/dev/sdX}, copy the image with: @example -dd if=guixsd-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX +dd if=guixsd-install-@value{VERSION}.@var{system}.iso of=/dev/sdX sync @end example @@ -9025,7 +9234,7 @@ its device name. Assuming that the DVD drive is known as @file{/dev/srX}, copy the image with: @example -growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.x86_64.iso +growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.iso @end example Access to @file{/dev/srX} usually requires root privileges. @@ -9385,7 +9594,7 @@ system}). We recommend doing that regularly so that your system includes the latest security updates (@pxref{Security Updates}). Join us on @code{#guix} on the Freenode IRC network or on -@file{guix-devel@@gnu.org} to share your experience---good or not so +@email{guix-devel@@gnu.org} to share your experience---good or not so good. @node Installing GuixSD in a VM @@ -9571,9 +9780,9 @@ environment variable---in addition to the per-user profiles provides all the tools one would expect for basic user and administrator tasks---including the GNU Core Utilities, the GNU Networking Utilities, the GNU Zile lightweight text editor, @command{find}, @command{grep}, -etc. The example above adds GNU@tie{}Screen and OpenSSH to those, -taken from the @code{(gnu packages screen)} and @code{(gnu packages ssh)} -modules (@pxref{Package Modules}). The +etc. The example above adds GNU@tie{}Screen to those, +taken from the @code{(gnu packages screen)} +module (@pxref{Package Modules}). The @code{(list package output)} syntax can be used to add a specific output of a package: @@ -9784,7 +9993,7 @@ 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 +A 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}. @@ -10490,11 +10699,14 @@ Start,,, shepherd, The GNU Shepherd Manual}). For example: The above command, run as @code{root}, lists the currently defined services. The @command{herd doc} command shows a synopsis of the given -service: +service and its associated actions: @example # herd doc nscd Run libc's name service cache daemon (nscd). + +# herd doc nscd action invalidate +invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups. @end example The @command{start}, @command{stop}, and @command{restart} sub-commands @@ -10698,7 +10910,7 @@ 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 +(baud rate etc.)@: alone---in the hope that Linux pinned them to the correct values. @item @code{baud-rate} (default: @code{#f}) @@ -10872,6 +11084,10 @@ A gexp denoting the name of the log-in program. The default log-in program is @item @code{login-arguments} (default: @code{'("-p")}) A list of arguments to pass to @command{login}. +@item @code{auto-login} (default: @code{#f}) +When passed a login name, as a string, the specified user will be logged +in automatically without prompting for their login name or password. + @item @code{hardware-acceleration?} (default: #f) Whether to use hardware acceleration. @@ -10888,6 +11104,27 @@ The Kmscon package to use. Return a service that runs the libc name service cache daemon (nscd) with the given @var{config}---an @code{<nscd-configuration>} object. @xref{Name Service Switch}, for an example. + +For convenience, the Shepherd service for nscd provides the following actions: + +@table @code +@item invalidate +@cindex cache invalidation, nscd +@cindex nscd, cache invalidation +This invalidate the given cache. For instance, running: + +@example +herd invalidate nscd hosts +@end example + +@noindent +invalidates the host name lookup cache of nscd. + +@item statistics +Running @command{herd statistics nscd} displays information about nscd usage +and caches. +@end table + @end deffn @defvr {Scheme Variable} %nscd-default-configuration @@ -11024,14 +11261,14 @@ Number of build user accounts to create. @item @code{authorize-key?} (default: @code{#t}) @cindex substitutes, authorization thereof Whether to authorize the substitute keys listed in -@code{authorized-keys}---by default that of @code{hydra.gnu.org} +@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}). @vindex %default-authorized-guix-keys @item @code{authorized-keys} (default: @var{%default-authorized-guix-keys}) The list of authorized key files for archive imports, as a list of string-valued gexps (@pxref{Invoking guix archive}). By default, it -contains that of @code{hydra.gnu.org} (@pxref{Substitutes}). +contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}). @item @code{use-substitutes?} (default: @code{#t}) Whether to use substitutes. @@ -11731,7 +11968,7 @@ Data Type representing the configuration of connman. The connman package to use. @item @code{disable-vpn?} (default: @code{#f}) -When true, enable connman's vpn plugin. +When true, disable connman's vpn plugin. @end table @end deftp @@ -11771,7 +12008,7 @@ List of additional command-line arguments to pass to the daemon. @cindex iptables @defvr {Scheme Variable} iptables-service-type -This is the service type to set up an iptables configuration. iptables is a +This is the service type to set up an iptables configuration. iptables is a packet filtering framework supported by the Linux kernel. This service supports configuring iptables for both IPv4 and IPv6. A simple example configuration rejecting all incoming connections except those to the ssh port @@ -11820,7 +12057,7 @@ objects}). @cindex NTP (Network Time Protocol), service @cindex real time clock @defvr {Scheme Variable} ntp-service-type -This is the type of the service running the the @uref{http://www.ntp.org, +This is the type of the service running the @uref{http://www.ntp.org, Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the system clock synchronized with that of the specified NTP servers. @@ -11980,14 +12217,14 @@ listening to new service requests. @item @code{user} A string containing the user (and, optionally, group) name of the user as whom the server should run. The group name can be specified in a -suffix, separated by a colon or period, i.e. @code{"user"}, +suffix, separated by a colon or period, i.e.@: @code{"user"}, @code{"user:group"} or @code{"user.group"}. @item @code{program} (default: @code{"internal"}) The server program which will serve the requests, or @code{"internal"} if @command{inetd} should use a built-in service. @item @code{arguments} (default: @code{'()}) A list strings or file-like objects, which are the server program's -arguments, starting with the zeroth argument, i.e. the name of the +arguments, starting with the zeroth argument, i.e.@: the name of the program itself. For @command{inetd}'s internal services, this entry must be @code{'()} or @code{'("internal")}. @end table @@ -12253,7 +12490,7 @@ Whether to allow TCP forwarding. Whether to allow gateway ports. @item @code{challenge-response-authentication?} (default: @code{#f}) -Specifies whether challenge response authentication is allowed (e.g. via +Specifies whether challenge response authentication is allowed (e.g.@: via PAM). @item @code{use-pam?} (default: @code{#t}) @@ -12273,7 +12510,7 @@ Specifies whether @command{sshd} should print the date and time of the last user login when a user logs in interactively. @item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))}) -Configures external subsystems (e.g. file transfer daemon). +Configures external subsystems (e.g.@: file transfer daemon). This is a list of two-element lists, each of which containing the subsystem name and a command (with optional arguments) to execute upon @@ -13895,7 +14132,7 @@ Users need to be in the @code{lp} group to access the D-Bus service. @cindex PulseAudio, sound support The @code{(gnu services sound)} module provides a service to configure the -Advanced Linux Sound Architecture (ALSA) system, which making PulseAudio the +Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the preferred ALSA output driver. @deffn {Scheme Variable} alsa-service-type @@ -14272,11 +14509,30 @@ Defaults to @samp{#t}. @end deftypevr +@deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit +Maximum number of simultaneous client connections per process. Once +this number of connections is received, the next incoming connection +will prompt Dovecot to spawn another process. If set to 0, +@code{default-client-limit} is used instead. + +Defaults to @samp{0}. + +@end deftypevr + @deftypevr {@code{service-configuration} parameter} non-negative-integer service-count Number of connections to handle before starting a new process. Typically the only useful values are 0 (unlimited) or 1. 1 is more secure, but 0 is faster. <doc/wiki/LoginProcess.txt>. Defaults to @samp{1}. + +@end deftypevr + +@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit +Maximum number of processes that can exist for this service. If set to +0, @code{default-process-limit} is used instead. + +Defaults to @samp{0}. + @end deftypevr @deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail @@ -14467,14 +14723,14 @@ Defaults to @samp{()}. @end deftypevr @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets -List of login access check sockets (e.g. tcpwrap). +List of login access check sockets (e.g.@: tcpwrap). Defaults to @samp{()}. @end deftypevr @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle? Show more verbose process titles (in ps). Currently shows user name and IP address. Useful for seeing who is actually using the IMAP -processes (e.g. shared mailboxes or if the same uid is used for multiple +processes (e.g.@: shared mailboxes or if the same uid is used for multiple accounts). Defaults to @samp{#f}. @end deftypevr @@ -14483,7 +14739,7 @@ Defaults to @samp{#f}. Should all processes be killed when Dovecot master process shuts down. Setting this to @code{#f} means that Dovecot can be upgraded without forcing existing client connections to close (although that could also -be a problem if the upgrade is e.g. due to a security fix). +be a problem if the upgrade is e.g.@: due to a security fix). Defaults to @samp{#t}. @end deftypevr @@ -14507,14 +14763,14 @@ key=value pairs to always set specific settings. @deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth? Disable LOGIN command and all other plaintext authentications unless SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP -matches the local IP (i.e. you're connecting from the same computer), +matches the local IP (i.e.@: you're connecting from the same computer), the connection is considered secure and plaintext authentication is allowed. See also ssl=required setting. Defaults to @samp{#t}. @end deftypevr @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size -Authentication cache size (e.g. @samp{#e10e6}). 0 means it's disabled. +Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled. Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set for caching to be used. Defaults to @samp{0}. @@ -14570,7 +14826,7 @@ Defaults to @samp{""}. @deftypevr {@code{dovecot-configuration} parameter} string auth-username-format Username formatting before it's looked up from databases. You can -use the standard variables here, e.g. %Lu would lowercase the username, +use the standard variables here, e.g.@: %Lu would lowercase the username, %n would drop away the domain if it was given, or @samp{%n-AT-%d} would change the @samp{@@} into @samp{-AT-}. This translation is done after @samp{auth-username-translation} changes. @@ -14579,7 +14835,7 @@ Defaults to @samp{"%Lu"}. @deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator If you want to allow master users to log in by specifying the master -username within the normal username string (i.e. not using SASL +username within the normal username string (i.e.@: not using SASL mechanism's support for it), you can specify the separator character here. The format is then <username><separator><master username>. UW-IMAP uses @samp{*} as the separator, so that could be a good @@ -14595,7 +14851,7 @@ Defaults to @samp{"anonymous"}. @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count Maximum number of dovecot-auth worker processes. They're used to -execute blocking passdb and userdb queries (e.g. MySQL and PAM). +execute blocking passdb and userdb queries (e.g.@: MySQL and PAM). They're automatically created and destroyed as needed. Defaults to @samp{30}. @end deftypevr @@ -14715,7 +14971,7 @@ In case of password mismatches, log the attempted password. Valid values are no, plain and sha1. sha1 can be useful for detecting brute force password attempts vs. user simply trying the same password over and over again. You can also truncate the value to n chars by appending -":n" (e.g. sha1:6). +":n" (e.g.@: sha1:6). Defaults to @samp{#f}. @end deftypevr @@ -14771,7 +15027,7 @@ Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}. Format to use for logging mail deliveries. You can use variables: @table @code @item %$ -Delivery status message (e.g. @samp{saved to INBOX}) +Delivery status message (e.g.@: @samp{saved to INBOX}) @item %m Message-ID @item %s @@ -14793,7 +15049,7 @@ if the user doesn't yet have any mail, so you should explicitly tell Dovecot the full location. If you're using mbox, giving a path to the INBOX -file (e.g. /var/mail/%u) isn't enough. You'll also need to tell Dovecot +file (e.g.@: /var/mail/%u) isn't enough. You'll also need to tell Dovecot where the other mailboxes are kept. This is called the "root mail directory", and it must be the first path given in the @samp{mail-location} setting. @@ -14844,7 +15100,7 @@ Defaults to @samp{""}. Grant access to these supplementary groups for mail processes. Typically these are used to set up access to shared mailboxes. Note that it may be dangerous to set these if users can create -symlinks (e.g. if "mail" group is set here, ln -s /var/mail ~/mail/var +symlinks (e.g.@: if "mail" group is set here, ln -s /var/mail ~/mail/var could allow a user to delete others' mailboxes, or ln -s /secret/shared/box ~/mail/mybox would allow reading it). Defaults to @samp{""}. @@ -14854,7 +15110,7 @@ Defaults to @samp{""}. Allow full file system access to clients. There's no access checks other than what the operating system does for the active UID/GID. It works with both maildir and mboxes, allowing you to prefix mailboxes -names with e.g. /path/ or ~user/. +names with e.g.@: /path/ or ~user/. Defaults to @samp{#f}. @end deftypevr @@ -14877,7 +15133,7 @@ When to use fsync() or fdatasync() calls: @item optimized Whenever necessary to avoid losing important data @item always -Useful with e.g. NFS when write()s are delayed +Useful with e.g.@: NFS when write()s are delayed @item never Never use it (best performance, but crashes can lose data). @end table @@ -14944,7 +15200,7 @@ Defaults to @samp{50}. @deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs List of directories under which chrooting is allowed for mail -processes (i.e. /var/mail will allow chrooting to /var/mail/foo/bar +processes (i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar too). This setting doesn't affect @samp{login-chroot} @samp{mail-chroot} or auth chroot settings. If this setting is empty, "/./" in home dirs are ignored. WARNING: Never add directories here @@ -14957,10 +15213,10 @@ Defaults to @samp{()}. @deftypevr {@code{dovecot-configuration} parameter} string mail-chroot Default chroot directory for mail processes. This can be overridden for specific users in user database by giving /./ in user's home -directory (e.g. /home/./user chroots into /home). Note that usually +directory (e.g.@: /home/./user chroots into /home). Note that usually there is no real need to do chrooting, Dovecot doesn't allow users to access files outside their mail directory anyway. If your home -directories are prefixed with the chroot directory, append "/." to +directories are prefixed with the chroot directory, append "/."@: to @samp{mail-chroot}. <doc/wiki/Chrooting.txt>. Defaults to @samp{""}. @end deftypevr @@ -14978,7 +15234,7 @@ Defaults to @samp{"/usr/lib/dovecot"}. @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins List of plugins to load for all services. Plugins specific to IMAP, -LDA, etc. are added to this list in their own .conf files. +LDA, etc.@: are added to this list in their own .conf files. Defaults to @samp{()}. @end deftypevr @@ -15101,7 +15357,7 @@ Defaults to @samp{#t}. @end deftypevr @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size -If mbox size is smaller than this (e.g. 100k), don't write index +If mbox size is smaller than this (e.g.@: 100k), don't write index files. If an index file already exists it's still read, just not updated. Defaults to @samp{0}. @@ -15161,7 +15417,7 @@ Defaults to @samp{"sis posix"}. Hash format to use in attachment filenames. You can add any text and variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}}, @code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be -truncated, e.g. @code{%@{sha256:80@}} returns only first 80 bits. +truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits. Defaults to @samp{"%@{sha1@}"}. @end deftypevr @@ -15225,7 +15481,7 @@ Defaults to @samp{""}. PEM encoded trusted certificate authority. Set this only if you intend to use @samp{ssl-verify-client-cert? #t}. The file should contain the CA certificate(s) followed by the matching -CRL(s). (e.g. @samp{ssl-ca </etc/ssl/certs/ca.pem}). +CRL(s). (e.g.@: @samp{ssl-ca </etc/ssl/certs/ca.pem}). Defaults to @samp{""}. @end deftypevr @@ -15269,7 +15525,7 @@ Defaults to @samp{"postmaster@@%d"}. @end deftypevr @deftypevr {@code{dovecot-configuration} parameter} string hostname -Hostname to use in various parts of sent mails (e.g. in Message-Id) +Hostname to use in various parts of sent mails (e.g.@: in Message-Id) and in LMTP replies. Default is the system's real hostname@@domain. Defaults to @samp{""}. @end deftypevr @@ -15362,7 +15618,7 @@ Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} expunged=%@{expunged@} tras @deftypevr {@code{dovecot-configuration} parameter} string imap-capability Override the IMAP CAPABILITY response. If the value begins with '+', -add the given capabilities on top of the defaults (e.g. +XFOO XBAR). +add the given capabilities on top of the defaults (e.g.@: +XFOO XBAR). Defaults to @samp{""}. @end deftypevr @@ -15403,7 +15659,7 @@ adds extra @samp{/} suffixes to mailbox names. This option causes Dovecot to ignore the extra @samp{/} instead of treating it as invalid mailbox name. @item tb-lsub-flags -Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g. mbox). +Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox). This makes Thunderbird realize they aren't selectable and show them greyed out, instead of only later giving "not selectable" popup error. @end table @@ -15895,7 +16151,7 @@ Defaults to @samp{"Prosody Chatrooms"}. @deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation If @samp{#t}, this will only allow admins to create new chatrooms. Otherwise anyone can create a room. The value @samp{"local"} restricts room -creation to users on the service's parent domain. E.g. @samp{user@@example.com} +creation to users on the service's parent domain. E.g.@: @samp{user@@example.com} can create rooms on @samp{rooms.example.com}. The value @samp{"admin"} restricts to service administrators only. Defaults to @samp{#f}. @@ -16104,10 +16360,10 @@ before switching over to opus audio codec. How deep channels can be nested at maximum. @item @code{channelname-regex} (default: @code{#f}) -A string in from of a Qt regular expression that channel names must conform to. +A string in form of a Qt regular expression that channel names must conform to. @item @code{username-regex} (default: @code{#f}) -A string in from of a Qt regular expression that user names must conform to. +A string in form of a Qt regular expression that user names must conform to. @item @code{text-message-length} (default: @code{5000}) Maximum size in bytes that a user can send in one text chat message. @@ -16119,7 +16375,7 @@ Maximum size in bytes that a user can send in one image message. If it is set to @code{#t} clients that use weak password authentification will not be accepted. Users must have completed the certificate wizard to join. -@item @code{remember-channel?} (defualt @code{#f}) +@item @code{remember-channel?} (default: @code{#f}) Should murmur remember the last channel each user was in when they disconnected and put them into the remembered channel when they rejoin. @@ -16144,7 +16400,7 @@ Murmur also stores logs in the database, which are accessible via RPC. The default is 31 days of months, but you can set this setting to 0 to keep logs forever, or -1 to disable logging to the database. -@item @code{obfuscate-ips?} (default @code{#t}) +@item @code{obfuscate-ips?} (default: @code{#t}) Should logged ips be obfuscated to protect the privacy of users. @item @code{ssl-cert} (default: @code{#f}) @@ -16546,7 +16802,7 @@ the nginx web server, and also a fastcgi wrapper daemon. @deffn {Scheme Variable} httpd-service-type Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server (@dfn{httpd}). The value for this service type is a -@code{https-configuration} record. +@code{httpd-configuration} record. A simple example configuration is given below. @@ -16612,6 +16868,10 @@ within the store, for example @code{(file-append mod-wsgi @end table @end deffn +@defvr {Scheme Variable} %default-httpd-modules +A default list of @code{httpd-module} objects. +@end defvr + @deffn {Data Type} httpd-config-file This data type represents a configuration file for the httpd service. @@ -16620,6 +16880,32 @@ This data type represents a configuration file for the httpd service. The modules to load. Additional modules can be added here, or loaded by additional configuration. +For example, in order to handle requests for PHP files, you can use Apache’s +@code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}: + +@example +(service httpd-service-type + (httpd-configuration + (config + (httpd-config-file + (modules (cons* + (httpd-module + (name "proxy_module") + (file "modules/mod_proxy.so")) + (httpd-module + (name "proxy_fcgi_module") + (file "modules/mod_proxy_fcgi.so")) + %default-httpd-modules)) + (extra-config (list "\ +<FilesMatch \\.php$> + SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" +</FilesMatch>")))))) +(service php-fpm-service-type + (php-fpm-configuration + (socket "/var/run/php-fpm.sock") + (socket-group "httpd"))) +@end example + @item @code{server-root} (default: @code{httpd}) The @code{ServerRoot} in the configuration file, defaults to the httpd package. Directives including @code{Include} and @code{LoadModule} are @@ -16883,8 +17169,8 @@ Name for this group of servers. @item @code{servers} Specify the addresses of the servers in the group. The address can be -specified as a IP address (e.g. @samp{127.0.0.1}), domain name -(e.g. @samp{backend1.example.com}) or a path to a UNIX socket using the +specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name +(e.g.@: @samp{backend1.example.com}) or a path to a UNIX socket using the prefix @samp{unix:}. For addresses using an IP address or domain name, the default port is 80, and a different port can be specified explicitly. @@ -16957,7 +17243,7 @@ the name starts with a forward slash, it is interpreted as an absolute directory name. Pass the @code{-n} argument to other Varnish programs to connect to the -named instance, e.g. @command{varnishncsa -n default}. +named instance, e.g.@: @command{varnishncsa -n default}. @item @code{backend} (default: @code{"localhost:8080"}) The backend to use. This option has no effect if @code{vcl} is set. @@ -17080,7 +17366,7 @@ and different php.ini (replaces safe_mode) a special function to finish request & flush all data while continuing to do something time-consuming (video converting, stats processing, etc.) @end itemize -... and much more. +...@: and much more. @defvr {Scheme Variable} php-fpm-service-type A Service type for @code{php-fpm}. @@ -17331,7 +17617,7 @@ 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, the automated periodic renewals, and the deployment -tasks associated with the renewal (e.g. reloading services, copying keys +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 @@ -18571,6 +18857,11 @@ Cuirass jobs. Location of sqlite database which contains the build results and previously added specifications. +@item @code{ttl} (default: @code{(* 30 24 3600)}) +Specifies the time-to-live (TTL) in seconds of garbage collector roots that +are registered for build results. This means that build results are protected +from garbage collection for at least @var{ttl} seconds. + @item @code{port} (default: @code{8081}) Port number used by the HTTP server. @@ -20432,8 +20723,8 @@ Defaults to @samp{"/favicon.ico"}. @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). +verbatim at the bottom of all pages (i.e.@: it replaces the standard +"generated by..."@: message). Defaults to @samp{""}. @@ -21759,10 +22050,10 @@ here is how to use it and customize it further. @cindex initrd @cindex initial RAM disk -@deffn {Monadic Procedure} raw-initrd @var{file-systems} @ +@deffn {Scheme Procedure} raw-initrd @var{file-systems} @ [#:linux-modules '()] [#:mapped-devices '()] @ [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f] -Return a monadic derivation that builds a raw initrd. @var{file-systems} is +Return a derivation that builds a raw initrd. @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{linux-modules} is a list of kernel modules to be loaded at boot time. @@ -21780,10 +22071,10 @@ When @var{volatile-root?} is true, the root file system is writable but any chan to it are lost. @end deffn -@deffn {Monadic Procedure} base-initrd @var{file-systems} @ +@deffn {Scheme Procedure} base-initrd @var{file-systems} @ [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]@ [#:linux-modules '()] -Return a monadic derivation that builds a generic initrd, with kernel +Return as a file-like object 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 @@ -21803,9 +22094,9 @@ program. That gives a lot of flexibility. The @code{expression->initrd} procedure builds such an initrd, given the program to run in that initrd. -@deffn {Monadic Procedure} expression->initrd @var{exp} @ +@deffn {Scheme Procedure} expression->initrd @var{exp} @ [#:guile %guile-static-stripped] [#:name "guile-initrd"] -Return a derivation that builds a Linux initrd (a gzipped cpio archive) +Return as a file-like object a Linux initrd (a gzipped cpio archive) containing @var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All the derivations referenced by @var{exp} are automatically copied to the initrd. @@ -22058,7 +22349,7 @@ This effects all the configuration specified in @var{file}: user accounts, system services, global package list, setuid programs, etc. The command starts system services specified in @var{file} that are not currently running; if a service is currently running this command will -arrange for it to be upgraded the next time it is stopped (eg. by +arrange for it to be upgraded the next time it is stopped (e.g.@: by @code{herd stop X} or @code{herd restart X}). This command creates a new generation whose number is one greater than @@ -23479,7 +23770,7 @@ system}. @cindex substituter Users can obtain the new package definition simply by running @command{guix pull} (@pxref{Invoking guix pull}). When -@code{hydra.gnu.org} is done building the package, installing the +@code{@value{SUBSTITUTE-SERVER}} is done building the package, installing the package automatically downloads binaries from there (@pxref{Substitutes}). The only place where human intervention is needed is to review and apply the patch. @@ -23739,7 +24030,7 @@ packages with the corresponding names. If a project already contains the word @code{python}, we drop this; for instance, the module python-dateutil is packaged under the names @code{python-dateutil} and @code{python2-dateutil}. If the project name -starts with @code{py} (e.g. @code{pytz}), we keep it and prefix it as +starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as described above. @subsubsection Specifying Dependencies @@ -24179,7 +24470,7 @@ to be updated to refer to these binaries on the target platform. That is, the hashes and URLs of the bootstrap tarballs for the new platform must be added alongside those of the currently supported platforms. The bootstrap Guile tarball is treated specially: it is expected to be -available locally, and @file{gnu/local.mk} has rules do download it for +available locally, and @file{gnu/local.mk} has rules to download it for the supported architectures; a rule for the new platform must be added as well. |