X-Git-Url: https://git.hcoop.net/jackhill/guix/guix.git/blobdiff_plain/563c5d42c954eacc54151d46a04ae14b9dbb1a10..63657335554eba6c70828b105a19ba7236f6ba2a:/doc/guix.texi diff --git a/doc/guix.texi b/doc/guix.texi index 5aed6771db..0b2742c6d9 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -24,7 +24,7 @@ Copyright @copyright{} 2015, 2016, 2017 Leo Famulari@* Copyright @copyright{} 2015, 2016 Ricardo Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} 2016 Chris Marusich@* -Copyright @copyright{} 2016 Efraim Flashner@* +Copyright @copyright{} 2016, 2017 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright @copyright{} 2016 ng0@* Copyright @copyright{} 2016 Jan Nieuwenhuizen@* @@ -33,7 +33,10 @@ Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2017 Clément Lassieur@* Copyright @copyright{} 2017 Mathieu Othacehe@* Copyright @copyright{} 2017 Federico Beffa@* -Copyright @copyright{} 2017 Carlo Zancanaro +Copyright @copyright{} 2017 Carlo Zancanaro@* +Copyright @copyright{} 2017 Thomas Danckaert@* +Copyright @copyright{} 2017 humanitiesNerd@* +Copyright @copyright{} 2017 Christopher Allan Webber Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -47,7 +50,6 @@ Documentation License''. @direntry * Guix: (guix). Manage installed software and system configuration. * guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages. -* guix build: (guix)Invoking guix build. Building packages. * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space. * guix pull: (guix)Invoking guix pull. Update the list of available packages. * guix system: (guix)Invoking guix system. Manage the operating system configuration. @@ -56,6 +58,8 @@ Documentation License''. @dircategory Software development @direntry * guix environment: (guix)Invoking guix environment. Building development environments with Guix. +* guix build: (guix)Invoking guix build. Building packages. +* guix pack: (guix)Invoking guix pack. Creating binary bundles. @end direntry @titlepage @@ -119,6 +123,7 @@ Package Management * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. +* Invoking guix pack:: Creating software bundles. * Invoking guix archive:: Exporting and importing store files. Programming Interface @@ -162,6 +167,7 @@ GNU Distribution * System Installation:: Installing the whole operating system. * System Configuration:: Configuring the operating system. +* Documentation:: Browsing software user manuals. * Installing Debugging Files:: Feeding the debugger. * Security Updates:: Deploying security fixes quickly. * Package Modules:: Packages from the programmer's viewpoint. @@ -214,6 +220,7 @@ Services * VPN Services:: VPN daemons. * Network File System:: NFS related services. * Continuous Integration:: The Cuirass service. +* Power management Services:: The TLP tool. * Miscellaneous Services:: Other services. Defining Services @@ -229,7 +236,7 @@ Packaging Guidelines * Package Naming:: What's in a name? * Version Numbers:: When the name is not enough. * Synopses and Descriptions:: Helping users find the right package. -* Python Modules:: Taming the snake. +* Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. * Java Packages:: Coffee break. * Fonts:: Fond of fonts. @@ -434,6 +441,14 @@ Make @code{root}'s profile available under @file{~/.guix-profile}: ~root/.guix-profile @end example +Source @file{etc/profile} to augment @code{PATH} and other relevant +environment variables: + +@example +# GUIX_PROFILE=$HOME/.guix-profile \ + source $GUIX_PROFILE/etc/profile +@end example + @item Create the group and user accounts for build users as explained below (@pxref{Build Environment Setup}). @@ -504,11 +519,13 @@ To use substitutes from @code{hydra.gnu.org} or one of its mirrors @example # guix archive --authorize < ~root/.guix-profile/share/guix/hydra.gnu.org.pub @end example + +@item +Each user may need to perform a few additional steps to make their Guix +environment ready for use, @pxref{Application Setup}. @end enumerate -This completes root-level install of Guix. Each user will need to -perform additional steps to make their Guix environment ready for use, -@pxref{Application Setup}. +Voilà, the installation is complete! You can confirm that Guix is working by installing a sample package into the root profile: @@ -530,6 +547,14 @@ by running the following command in the Guix source tree: make guix-binary.@var{system}.tar.xz @end example +@noindent +... which, in turn, runs: + +@example +guix pack -s @var{system} --localstatedir guix +@end example + +@xref{Invoking guix pack}, for more info on this handy tool. @node Requirements @section Requirements @@ -542,23 +567,19 @@ in the Guix source tree for additional details. GNU Guix depends on the following packages: @itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.7 or later; +@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.0.9 or +later, including 2.2.x; @item @url{http://gnupg.org/, GNU libgcrypt}; +@item +@uref{http://gnutls.org/, GnuTLS}, specifically its Guile bindings +(@pxref{Guile Preparations, how to install the GnuTLS bindings for +Guile,, gnutls-guile, GnuTLS-Guile}); @item @url{http://www.gnu.org/software/make/, GNU Make}. @end itemize The following dependencies are optional: @itemize -@item -Installing @uref{http://gnutls.org/, GnuTLS-Guile} will allow you to -access @code{https} URLs for substitutes, which is highly recommended -(@pxref{Substitutes}). It also allows you to access HTTPS URLs with the -@command{guix download} command (@pxref{Invoking guix download}), the -@command{guix import pypi} command, and the @command{guix import cpan} -command. @xref{Guile Preparations, how to install the GnuTLS bindings -for Guile,, gnutls-guile, GnuTLS-Guile}. - @item Installing @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON} will @@ -1410,11 +1431,13 @@ remove software packages, without having to know about their build procedures or dependencies. Guix also goes beyond this obvious set of features. -This chapter describes the main features of Guix, as well as the package -management tools it provides. Along with the command-line interface -described below (@pxref{Invoking guix package, @code{guix package}}), -you may also use Emacs Interface, after installing @code{emacs-guix} -package (run @kbd{M-x guix-help} command to start with it): +This chapter describes the main features of Guix, as well as the +package management tools it provides. Along with the command-line +interface described below (@pxref{Invoking guix package, @code{guix +package}}), you may also use Emacs Interface (@pxref{Top,,, +emacs-guix, The Emacs-Guix Reference Manual}), after installing +@code{emacs-guix} package (run @kbd{M-x guix-help} command to start +with it): @example guix package -i emacs-guix @@ -1427,6 +1450,7 @@ guix package -i emacs-guix * Packages with Multiple Outputs:: Single source package, multiple outputs. * Invoking guix gc:: Running the garbage collector. * Invoking guix pull:: Fetching the latest Guix and distribution. +* Invoking guix pack:: Creating software bundles. * Invoking guix archive:: Exporting and importing store files. @end menu @@ -2003,8 +2027,7 @@ or to client tools such as @command{guix package} (@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). -Substitute URLs can be either HTTP or HTTPS@footnote{For HTTPS access, -the Guile bindings of GnuTLS must be installed. @xref{Requirements}.} +Substitute URLs can be either HTTP or HTTPS. HTTPS is recommended because communications are encrypted; conversely, using HTTP makes all communications visible to an eavesdropper, who could use the information gathered to determine, for instance, whether @@ -2368,13 +2391,13 @@ For example, to download and deploy version 0.12.0 of Guix from the canonical Git repo: @example -guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz +guix pull --url=https://git.savannah.gnu.org/cgit/guix.git/snapshot/v0.12.0.tar.gz @end example It can also be used to deploy arbitrary Git revisions: @example -guix pull --url=http://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz +guix pull --url=https://git.savannah.gnu.org/cgit/guix.git/snapshot/74d862e8a.tar.gz @end example @item --bootstrap @@ -2382,6 +2405,145 @@ Use the bootstrap Guile to build the latest Guix. This option is only useful to Guix developers. @end table +In addition, @command{guix pull} supports all the common build options +(@pxref{Common Build Options}). + +@node Invoking guix pack +@section Invoking @command{guix pack} + +Occasionally you want to pass software to people who are not (yet!) +lucky enough to be using Guix. You'd tell them to run @command{guix +package -i @var{something}}, but that's not possible in this case. This +is where @command{guix pack} comes in. + +@cindex pack +@cindex bundle +@cindex application bundle +@cindex software bundle +The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or +@dfn{software bundle}: it creates a tarball or some other archive +containing the binaries of the software you're interested in, and all +its dependencies. The resulting archive can be used on any machine that +does not have Guix, and people can run the exact same binaries as those +you have with Guix. The pack itself is created in a bit-reproducible +fashion, so anyone can verify that it really contains the build results +that you pretend to be shipping. + +For example, to create a bundle containing Guile, Emacs, Geiser, and all +their dependencies, you can run: + +@example +$ guix pack guile emacs geiser +@dots{} +/gnu/store/@dots{}-pack.tar.gz +@end example + +The result here is a tarball containing a @file{/gnu/store} directory +with all the relevant packages. The resulting tarball contains a +@dfn{profile} with the three packages of interest; the profile is the +same as would be created by @command{guix package -i}. It is this +mechanism that is used to create Guix's own standalone binary tarball +(@pxref{Binary Installation}). + +Users of this pack would have to run +@file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may +find inconvenient. To work around it, you can create, say, a +@file{/opt/gnu/bin} symlink to the profile: + +@example +guix pack -S /opt/gnu/bin=bin guile emacs geiser +@end example + +@noindent +That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy. + +Alternatively, you can produce a pack in the Docker image format using +the following command: + +@example +guix pack -f docker guile emacs geiser +@end example + +@noindent +The result is a tarball that can be passed to the @command{docker load} +command. See the +@uref{https://docs.docker.com/engine/reference/commandline/load/, Docker +documentation} for more information. + +Several command-line options allow you to customize your pack: + +@table @code +@item --format=@var{format} +@itemx -f @var{format} +Produce a pack in the given @var{format}. + +The available formats are: + +@table @code +@item tarball +This is the default format. It produces a tarball containing all the +specifies binaries and symlinks. + +@item docker +This produces a tarball that follows the +@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, +Docker Image Specification}. +@end table + +@item --expression=@var{expr} +@itemx -e @var{expr} +Consider the package @var{expr} evaluates to. + +This has the same purpose as the same-named option in @command{guix +build} (@pxref{Additional Build Options, @code{--expression} in +@command{guix build}}). + +@item --system=@var{system} +@itemx -s @var{system} +Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of +the system type of the build host. + +@item --target=@var{triplet} +@cindex cross-compilation +Cross-build for @var{triplet}, which must be a valid GNU triplet, such +as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU +configuration triplets,, autoconf, Autoconf}). + +@item --compression=@var{tool} +@itemx -C @var{tool} +Compress the resulting tarball using @var{tool}---one of @code{gzip}, +@code{bzip2}, @code{xz}, or @code{lzip}. + +@item --symlink=@var{spec} +@itemx -S @var{spec} +Add the symlinks specified by @var{spec} to the pack. This option can +appear several times. + +@var{spec} has the form @code{@var{source}=@var{target}}, where +@var{source} is the symlink that will be created and @var{target} is the +symlink target. + +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. + +@file{/var/guix} contains the store database (@pxref{The Store}) as well +as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in +the pack means that the store is ``complete'' and manageable by Guix; +not providing it pack means that the store is ``dead'': items cannot be +added to it or removed from it after extraction of the pack. + +One use case for this is the Guix self-contained binary tarball +(@pxref{Binary Installation}). +@end table + +In addition, @command{guix pack} supports all the common build options +(@pxref{Common Build Options}) and all the package transformation +options (@pxref{Package Transformation Options}). + @node Invoking guix archive @section Invoking @command{guix archive} @@ -2441,7 +2603,7 @@ what you should use in this case (@pxref{Invoking guix copy}). @cindex nar, archive format @cindex normalized archive (nar) -By default archives are stored in the ``normalized archive'' or ``nar'' format, which is +Archives are stored in the ``normalized archive'' or ``nar'' format, which is comparable in spirit to `tar', but with differences that make it more appropriate for our purposes. First, rather than recording all Unix metadata for each file, the nar format only mentions @@ -2457,9 +2619,6 @@ verifies the signature and rejects the import in case of an invalid signature or if the signing key is not authorized. @c FIXME: Add xref to daemon doc about signatures. -Optionally, archives can be exported as a Docker image in the tar -archive format using @code{--format=docker}. - The main options are: @table @code @@ -2488,19 +2647,6 @@ Read a list of store file names from the standard input, one per line, and write on the standard output the subset of these files missing from the store. -@item -f -@item --format=@var{FMT} -@cindex docker, export -@cindex export format -Specify the export format. Acceptable arguments are @code{nar} and -@code{docker}. The default is the nar format. When the format is -@code{docker}, recursively export the specified store directory as a -Docker image in tar archive format, as specified in -@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, -version 1.2.0 of the Docker Image Specification}. Using -@code{--format=docker} implies @code{--recursive}. The generated -archive can be loaded by Docker using @command{docker load}. - @item --generate-key[=@var{parameters}] @cindex signing, archives Generate a new key pair for the daemon. This is a prerequisite before @@ -2739,7 +2885,8 @@ unavailable to the build process, possibly leading to a build failure. Once a package definition is in place, the package may actually be built using the @code{guix build} command-line -tool (@pxref{Invoking guix build}). You can easily jump back to the +tool (@pxref{Invoking guix build}), troubleshooting any build failures +you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the package definition using the @command{guix edit} command (@pxref{Invoking guix edit}). @xref{Packaging Guidelines}, for @@ -2823,6 +2970,16 @@ with @var{libressl}. Then we use it to define a @dfn{variant} of the This is exactly what the @option{--with-input} command-line option does (@pxref{Package Transformation Options, @option{--with-input}}). +A more generic procedure to rewrite a package dependency graph is +@code{package-mapping}: it supports arbitrary changes to nodes in the +graph. + +@deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] +Return a procedure that, given a package, applies @var{proc} to all the packages +depended on and returns the resulting package. The procedure stops recursion +when @var{cut?} returns true for a given package. +@end deffn + @menu * package Reference :: The package data type. * origin Reference:: The origin data type. @@ -3171,7 +3328,8 @@ parameters, respectively. When the original package does not provide a suitable Ant build file, the parameter @code{#:jar-name} can be used to generate a minimal Ant build file @file{build.xml} with tasks to build the specified jar -archive. +archive. In this case the parameter @code{#:source-dir} can be used to +specify the source sub-directory, defaulting to ``src''. The parameter @code{#:build-target} can be used to specify the Ant task that should be run during the @code{build} phase. By default the @@ -3303,7 +3461,7 @@ Both phases are executed after the @code{install} phase. @end defvr @defvr {Scheme Variable} ocaml-build-system -This variable is exported by @code{(guix build-sytem ocaml)}. It implements +This variable is exported by @code{(guix build-system ocaml)}. It implements a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists of choosing the correct set of commands to run for each package. OCaml packages can expect many different commands to be run. This build system will @@ -3516,10 +3674,64 @@ accidental modifications. @end quotation The @code{(guix store)} module provides procedures to connect to the -daemon, and to perform RPCs. These are described below. +daemon, and to perform RPCs. These are described below. By default, +@code{open-connection}, and thus all the @command{guix} commands, +connect to the local daemon or to the URI specified by the +@code{GUIX_DAEMON_SOCKET} environment variable. + +@defvr {Environment Variable} GUIX_DAEMON_SOCKET +When set, the value of this variable should be a file name or a URI +designating the daemon endpoint. When it is a file name, it denotes a +Unix-domain socket to connect to. In addition to file names, the +supported URI schemes are: + +@table @code +@item file +@itemx unix +These are for Unix-domain sockets. +@code{file:///var/guix/daemon-socket/socket} is equivalent to +@file{/var/guix/daemon-socket/socket}. + +@item guix +These URIs denote connections over TCP/IP, without encryption nor +authentication of the remote host. The URI must always specify both the +host name and port number: + +@example +guix://master.guix.example.org:1234 +@end example + +This setup is suitable on local networks, such as clusters, where only +trusted nodes may connect to the build daemon at +@code{master.guix.example.org}. + +@item ssh +@cindex SSH access to build daemons +These URIs allow you to connect to a remote daemon over +SSH@footnote{This feature requires Guile-SSH (@pxref{Requirements}).}. +A typical URL might look like this: + +@example +ssh://charlie@@guix.example.org:22 +@end example + +As for @command{guix copy}, the usual OpenSSH client configuration files +are honored (@pxref{Invoking guix copy}). +@end table + +Additional URI schemes may be supported in the future. + +@c XXX: Remove this note when the protocol incurs fewer round trips +@c and when (guix derivations) no longer relies on file system access. +@quotation Note +The ability to connect to remote build daemons is considered +experimental as of @value{VERSION}. Please get in touch with us to +share any problems or suggestions you may have (@pxref{Contributing}). +@end quotation +@end defvr -@deffn {Scheme Procedure} open-connection [@var{file}] [#:reserve-space? #t] -Connect to the daemon over the Unix-domain socket at @var{file}. When +@deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t] +Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When @var{reserve-space?} is true, instruct it to reserve a little bit of extra space on the file system so that the garbage collector can still operate should the disk become full. Return a server object. @@ -3888,8 +4100,15 @@ in this example: @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @ @var{body} ... Bind the variables @var{var} to the monadic values @var{mval} in -@var{body}. The form (@var{var} -> @var{val}) binds @var{var} to the -``normal'' value @var{val}, as per @code{let}. +@var{body}, which is a sequence of expressions. As with the bind +operator, this can be thought of as ``unpacking'' the raw, non-monadic +value ``contained'' in @var{mval} and making @var{var} refer to that +raw, non-monadic value within the scope of the @var{body}. The form +(@var{var} -> @var{val}) binds @var{var} to the ``normal'' value +@var{val}, as per @code{let}. The binding operations occur in sequence +from left to right. The last expression of @var{body} must be a monadic +expression, and its result will become the result of the @code{mlet} or +@code{mlet*} when run in the @var{monad}. @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let} (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). @@ -3897,13 +4116,28 @@ Bind the variables @var{var} to the monadic values @var{mval} in @deffn {Scheme System} mbegin @var{monad} @var{mexp} ... Bind @var{mexp} and the following monadic expressions in sequence, -returning the result of the last expression. +returning the result of the last expression. Every expression in the +sequence must be a monadic expression. This is akin to @code{mlet}, except that the return values of the monadic expressions are ignored. In that sense, it is analogous to @code{begin}, but applied to monadic expressions. @end deffn +@deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ... +When @var{condition} is true, evaluate the sequence of monadic +expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When +@var{condition} is false, return @code{*unspecified*} in the current +monad. Every expression in the sequence must be a monadic expression. +@end deffn + +@deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ... +When @var{condition} is false, evaluate the sequence of monadic +expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When +@var{condition} is true, return @code{*unspecified*} in the current +monad. Every expression in the sequence must be a monadic expression. +@end deffn + @cindex state monad The @code{(guix monads)} module provides the @dfn{state monad}, which allows an additional value---the state---to be @emph{threaded} through @@ -4251,8 +4485,22 @@ of the @code{gexp?} type (see below.) @deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{} Mark the gexps defined in @var{body}@dots{} as requiring @var{modules} -in their execution environment. @var{modules} must be a list of Guile -module names, such as @code{'((guix build utils) (guix build gremlin))}. +in their execution environment. + +Each item in @var{modules} can be the name of a module, such as +@code{(guix build utils)}, or it can be a module name, followed by an +arrow, followed by a file-like object: + +@example +`((guix build utils) + (guix gcrypt) + ((guix config) => ,(scheme-file "config.scm" + #~(define-module @dots{})))) +@end example + +@noindent +In the example above, the first two modules are taken from the search +path, and the last one is created from the given file-like object. This form has @emph{lexical} scope: it has an effect on the gexps directly defined in @var{body}@dots{}, but not on those defined, say, in @@ -4592,6 +4840,7 @@ described in the subsections below. * Common Build Options:: Build options for most commands. * Package Transformation Options:: Creating variants of packages. * Additional Build Options:: Options specific to 'guix build'. +* Debugging Build Failures:: Real life packaging experience @end menu @node Common Build Options @@ -4617,6 +4866,8 @@ the command-line tools. Keep the build tree of failed builds. Thus, if a build fails, its build tree is kept under @file{/tmp}, in a directory whose name is shown at 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. @item --keep-going @itemx -k @@ -4786,15 +5037,15 @@ or @code{guile@@1.8}. For instance, the following command builds Guix, but replaces its dependency on the current stable version of Guile with a dependency on -the development version of Guile, @code{guile-next}: +the legacy version of Guile, @code{guile@@2.0}: @example -guix build --with-input=guile=guile-next guix +guix build --with-input=guile=guile@@2.0 guix @end example This is a recursive, deep replacement. So in this example, both @code{guix} and its dependency @code{guile-json} (which also depends on -@code{guile}) get rebuilt against @code{guile-next}. +@code{guile}) get rebuilt against @code{guile@@2.0}. This is implemented using the @code{package-input-rewriting} Scheme procedure (@pxref{Defining Packages, @code{package-input-rewriting}}). @@ -4936,8 +5187,8 @@ to build packages in a complete 32-bit environment. @item --target=@var{triplet} @cindex cross-compilation Cross-build for @var{triplet}, which must be a valid GNU triplet, such -as @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU -configuration triplets,, configure, GNU Configure and Build System}). +as @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU +configuration triplets,, autoconf, Autoconf}). @anchor{build-check} @item --check @@ -5004,6 +5255,82 @@ https://hydra.gnu.org/log/@dots{}-gdb-7.10 You can freely access a huge library of build logs! @end table +@node Debugging Build Failures +@subsection Debugging Build Failures + +@cindex build failures, debugging +When defining a new package (@pxref{Defining Packages}), you will +probably find yourself spending some time debugging and tweaking the +build until it succeeds. To do that, you need to operate the build +commands yourself in an environment as close as possible to the one the +build daemon uses. + +To that end, the first thing to do is to use the @option{--keep-failed} +or @option{-K} option of @command{guix build}, which will keep the +failed build tree in @file{/tmp} or whatever directory you specified as +@code{TMPDIR} (@pxref{Invoking guix build, @code{--keep-failed}}). + +From there on, you can @command{cd} to the failed build tree and source +the @file{environment-variables} file, which contains all the +environment variable definitions that were in place when the build +failed. So let's say you're debugging a build failure in package +@code{foo}; a typical session would look like this: + +@example +$ guix build foo -K +@dots{} @i{build fails} +$ cd /tmp/guix-build-foo.drv-0 +$ source ./environment-variables +$ cd foo-1.2 +@end example + +Now, you can invoke commands as if you were the daemon (almost) and +troubleshoot your build process. + +Sometimes it happens that, for example, a package's tests pass when you +run them manually but they fail when the daemon runs them. This can +happen because the daemon runs builds in containers where, unlike in our +environment above, network access is missing, @file{/bin/sh} does not +exist, etc. (@pxref{Build Environment Setup}). + +In such cases, you may need to run inspect the build process from within +a container similar to the one the build daemon creates: + +@example +$ guix build -K foo +@dots{} +$ cd /tmp/guix-build-foo.drv-0 +$ guix environment -C foo --ad-hoc strace gdb +[env]# source ./environment-variables +[env]# cd foo-1.2 +@end example + +Here, @command{guix environment -C} creates a container and spawns a new +shell in it (@pxref{Invoking guix environment}). The @command{--ad-hoc +strace gdb} part adds the @command{strace} and @command{gdb} commands to +the container, which would may find handy while debugging. + +To get closer to a container like that used by the build daemon, we can +remove @file{/bin/sh}: + +@example +[env]# rm /bin/sh +@end example + +(Don't worry, this is harmless: this is all happening in the throw-away +container created by @command{guix environment}.) + +The @command{strace} command is probably not in the search path, but we +can run: + +@example +[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check +@end example + +In this way, not only you will have reproduced the environment variables +the daemon uses, you will also be running the build process in a container +similar to the one the daemon uses. + @node Invoking guix edit @section Invoking @command{guix edit} @@ -5612,7 +5939,7 @@ an upgrade. More rebuilds might be required under some circumstances. @example $ guix refresh --list-dependent flex Building the following 120 packages would ensure 213 dependent packages are rebuilt: -hop-2.4.0 geiser-0.4 notmuch-0.18 mu-0.9.9.5 cflow-1.4 idutils-4.6 @dots{} +hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{} @end example The command above lists a set of packages that could be built to check @@ -5871,7 +6198,9 @@ provides a visual representation of the DAG. By default, @uref{http://www.graphviz.org/, Graphviz}, so its output can be passed directly to the @command{dot} command of Graphviz. It can also emit an HTML page with embedded JavaScript code to display a ``chord diagram'' -in a Web browser, using the @uref{https://d3js.org/, d3.js} library. +in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or +emit Cypher queries to construct a graph in a graph database supporting +the @uref{http://www.opencypher.org/, openCypher} query language. The general syntax is: @example @@ -6269,7 +6598,7 @@ home directory is accessible read-only via the @file{/exchange} directory: @example -guix environment --container --expose=$HOME=/exchange guile -- guile +guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile @end example @item --share=@var{source}[=@var{target}] @@ -6283,13 +6612,15 @@ home directory is accessible for both reading and writing via the @file{/exchange} directory: @example -guix environment --container --share=$HOME=/exchange guile -- guile +guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile @end example @end table -It also supports all of the common build options that @command{guix +@command{guix environment} +also supports all of the common build options that @command{guix build} supports (@pxref{Common Build Options}). + @node Invoking guix publish @section Invoking @command{guix publish} @@ -6334,6 +6665,13 @@ archive}), the daemon may download substitutes from it: guix-daemon --substitute-urls=http://example.org:8080 @end example +By default, @command{guix publish} compresses archives on the fly as it +serves them. This ``on-the-fly'' mode is convenient in that it requires +no setup and is immediately available. However, when serving lots of +clients, we recommend using the @option{--cache} option, which enables +caching of the archives before they are sent to clients---see below for +details. + As a bonus, @command{guix publish} also serves as a content-addressed mirror for source files referenced in @code{origin} records (@pxref{origin Reference}). For instance, assuming @command{guix @@ -6371,10 +6709,46 @@ disable compression. The range 1 to 9 corresponds to different gzip compression levels: 1 is the fastest, and 9 is the best (CPU-intensive). The default is 3. -Compression occurs on the fly and the compressed streams are not +Unless @option{--cache} is used, compression occurs on the fly and +the compressed streams are not cached. Thus, to reduce load on the machine that runs @command{guix -publish}, it may be a good idea to choose a low compression level, or to -run @command{guix publish} behind a caching proxy. +publish}, it may be a good idea to choose a low compression level, to +run @command{guix publish} behind a caching proxy, or to use +@option{--cache}. Using @option{--cache} has the advantage that it +allows @command{guix publish} to add @code{Content-Length} HTTP header +to its responses. + +@item --cache=@var{directory} +@itemx -c @var{directory} +Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory} +and only serve archives that are in cache. + +When this option is omitted, archives and meta-data are created +on-the-fly. This can reduce the available bandwidth, especially when +compression is enabled, since this may become CPU-bound. Another +drawback of the default mode is that the length of archives is not known +in advance, so @command{guix publish} does not add a +@code{Content-Length} HTTP header to its responses, which in turn +prevents clients from knowing the amount of data being downloaded. + +Conversely, when @option{--cache} is used, the first request for a store +item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a +background process to @dfn{bake} the archive---computing its +@code{.narinfo} and compressing the archive, if needed. Once the +archive is cached in @var{directory}, subsequent requests succeed and +are served directly from the cache, which guarantees that clients get +the best possible bandwidth. + +The ``baking'' process is performed by worker threads. By default, one +thread per CPU core is created, but this can be customized. See +@option{--workers} below. + +When @option{--ttl} is used, cached entries are automatically deleted +when they have expired. + +@item --workers=@var{N} +When @option{--cache} is used, request the allocation of @var{N} worker +threads to ``bake'' archives. @item --ttl=@var{ttl} Produce @code{Cache-Control} HTTP headers that advertise a time-to-live @@ -6386,6 +6760,29 @@ This allows the user's Guix to keep substitute information in cache for guarantee that the store items it provides will indeed remain available for as long as @var{ttl}. +Additionally, when @option{--cache} is used, cached entries that have +not been accessed for @var{ttl} may be deleted. + +@item --nar-path=@var{path} +Use @var{path} as the prefix for the URLs of ``nar'' files +(@pxref{Invoking guix archive, normalized archives}). + +By default, nars are served at a URL such as +@code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to +change the @code{/nar} part to @var{path}. + +@item --public-key=@var{file} +@itemx --private-key=@var{file} +Use the specific @var{file}s as the public/private key pair used to sign +the store items being published. + +The files must correspond to the same key pair (the private key is used +for signing and the public key is merely advertised in the signature +metadata). They must contain keys in the canonical s-expression format +as produced by @command{guix archive --generate-key} (@pxref{Invoking +guix archive}). By default, @file{/etc/guix/signing-key.pub} and +@file{/etc/guix/signing-key.sec} are used. + @item --repl[=@var{port}] @itemx -r [@var{port}] Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile @@ -6394,9 +6791,9 @@ primarily for debugging a running @command{guix publish} server. @end table Enabling @command{guix publish} on a GuixSD system is a one-liner: just -add a call to @code{guix-publish-service} in the @code{services} field -of the @code{operating-system} declaration (@pxref{guix-publish-service, -@code{guix-publish-service}}). +instantiate a @code{guix-publish-service-type} service in the @code{services} field +of the @code{operating-system} declaration (@pxref{guix-publish-service-type, +@code{guix-publish-service-type}}). If you are instead running Guix on a ``foreign distro'', follow these instructions:” @@ -6718,6 +7115,11 @@ ARMv7-A architecture with hard float, Thumb-2 and NEON, using the EABI hard-float application binary interface (ABI), and Linux-Libre kernel. +@item aarch64-linux +little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is +currently in an experimental stage, with limited support. +@xref{Contributing}, for how to help! + @item mips64el-linux little-endian 64-bit MIPS processors, specifically the Loongson series, n32 ABI, and Linux-Libre kernel. @@ -6733,6 +7135,7 @@ For information on porting to other architectures or kernels, @menu * System Installation:: Installing the whole operating system. * System Configuration:: Configuring the operating system. +* Documentation:: Browsing software user manuals. * Installing Debugging Files:: Feeding the debugger. * Security Updates:: Deploying security fixes quickly. * Package Modules:: Packages from the programmer's viewpoint. @@ -6804,15 +7207,15 @@ get a feel of what that means.) Support for the Logical Volume Manager (LVM) is missing. @item -Few system services are currently supported out-of-the-box -(@pxref{Services}). +More and more system services are provided (@pxref{Services}), but some +may be missing. @item -More than 4,000 packages are available, but you may +More than 5,300 packages are available, but you may occasionally find that a useful package is missing. @item -GNOME, Xfce, and Enlightenment are available (@pxref{Desktop Services}), +GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}), as well as a number of X11 window managers. However, some graphical applications may be missing, as well as KDE. @end itemize @@ -7199,7 +7602,7 @@ guix system init /mnt/etc/config.scm /mnt @noindent This copies all the necessary files and installs GRUB on -@file{/dev/sdX}, unless you pass the @option{--no-grub} option. For +@file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For more information, @pxref{Invoking guix system}. This command may trigger downloads or builds of missing packages, which can take some time. @@ -7364,7 +7767,19 @@ provides all the tools one would expect for basic user and administrator tasks---including the GNU Core Utilities, the GNU Networking Utilities, the GNU Zile lightweight text editor, @command{find}, @command{grep}, etc. The example above adds tcpdump to those, taken from the @code{(gnu -packages admin)} module (@pxref{Package Modules}). +packages admin)} module (@pxref{Package Modules}). The +@code{(list package output)} syntax can be used to add a specific output +of a package: + +@lisp +(use-modules (gnu packages)) +(use-modules (gnu packages dns)) + +(operating-system + ;; ... + (packages (cons (list bind "utils") + %base-packages))) +@end lisp @findex specification->package Referring to packages by variable name, like @var{tcpdump} above, has @@ -8294,6 +8709,7 @@ declaration. * VPN Services:: VPN daemons. * Network File System:: NFS related services. * Continuous Integration:: The Cuirass service. +* Power management Services:: The TLP tool. * Miscellaneous Services:: Other services. @end menu @@ -8850,17 +9266,60 @@ 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 -@anchor{guix-publish-service} -@deffn {Scheme Procedure} guix-publish-service [#:guix @var{guix}] @ - [#:port 80] [#:host "localhost"] -Return a service that runs @command{guix publish} listening on @var{host} -and @var{port} (@pxref{Invoking guix publish}). +@anchor{guix-publish-service-type} +@deffn {Scheme Variable} guix-publish-service-type +This is the service type for @command{guix publish} (@pxref{Invoking +guix publish}). Its value must be a @code{guix-configuration} +object, as described below. This assumes that @file{/etc/guix} already contains a signing key pair as created by @command{guix archive --generate-key} (@pxref{Invoking guix archive}). If that is not the case, the service will fail to start. @end deffn +@deftp {Data Type} guix-publish-configuration +Data type representing the configuration of the @code{guix publish} +service. + +@table @asis +@item @code{guix} (default: @code{guix}) +The Guix package to use. + +@item @code{port} (default: @code{80}) +The TCP port to listen for connections. + +@item @code{host} (default: @code{"localhost"}) +The host (and thus, network interface) to listen to. Use +@code{"0.0.0.0"} to listen on all the network interfaces. + +@item @code{compression-level} (default: @code{3}) +The gzip compression level at which substitutes are compressed. Use +@code{0} to disable compression altogether, and @code{9} to get the best +compression ratio at the expense of increased CPU usage. + +@item @code{nar-path} (default: @code{"nar"}) +The URL path at which ``nars'' can be fetched. @xref{Invoking guix +publish, @code{--nar-path}}, for details. + +@item @code{cache} (default: @code{#f}) +When it is @code{#f}, disable caching and instead generate archives on +demand. Otherwise, this should be the name of a directory---e.g., +@code{"/var/cache/guix/publish"}---where @command{guix publish} caches +archives and meta-data ready to be sent. @xref{Invoking guix publish, +@option{--cache}}, for more information on the tradeoffs involved. + +@item @code{workers} (default: @code{#f}) +When it is an integer, this is the number of worker threads used for +caching; when @code{#f}, the number of processors is used. +@xref{Invoking guix publish, @option{--workers}}, for more information. + +@item @code{ttl} (default: @code{#f}) +When it is an integer, this denotes the @dfn{time-to-live} of the +published archives. @xref{Invoking guix publish, @option{--ttl}}, for +more information. +@end table +@end deftp + @anchor{rngd-service} @deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @ [#:device "/dev/hwrng"] @@ -9015,7 +9474,7 @@ with the default settings. (operating-system ;; @dots{} (services (cons* (mcron-service) - (service rottlog-service-type (rottlog-configuration)) + (service rottlog-service-type) %base-services))) @end lisp @@ -9038,7 +9497,7 @@ The Rottlog package to use. The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,, rottlog, GNU Rot[t]log Manual}). -@item @code{periodic-rotations} (default: @code{`(("weekly" %default-rotatations))}) +@item @code{periodic-rotations} (default: @code{`(("weekly" %default-rotations))}) A list of Rottlog period-name/period-config tuples. For example, taking an example from the Rottlog manual (@pxref{Period @@ -9153,16 +9612,34 @@ NetworkManager will not modify @code{resolv.conf}. @end deftp @cindex Connman -@deffn {Scheme Procedure} connman-service @ - [#:connman @var{connman}] -Return a service that runs @url{https://01.org/connman,Connman}, a network -connection manager. - -This service adds the @var{connman} package to the global profile, providing -several the @command{connmanctl} command to interact with the daemon and -configure networking." +@deffn {Scheme Variable} connman-service-type +This is the service type to run @url{https://01.org/connman,Connman}, +a network connection manager. + +Its value must be an +@code{connman-configuration} record as in this example: + +@example +(service connman-service-type + (connman-configuration + (disable-vpn? #t))) +@end example + +See below for details about @code{connman-configuration}. @end deffn +@deftp {Data Type} connman-configuration +Data Type representing the configuration of connman. + +@table @asis +@item @code{connman} (default: @var{connman}) +The connman package to use. + +@item @code{disable-vpn?} (default: @code{#f}) +When true, enable connman's vpn plugin. +@end table +@end deftp + @cindex WPA Supplicant @defvr {Scheme Variable} wpa-supplicant-service-type This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA @@ -9174,10 +9651,9 @@ The value of this service is the @code{wpa-supplicant} package to use. Thus, it can be instantiated like this: @lisp -(use-modules (gnu services networking) - (gnu packages admin)) +(use-modules (gnu services networking)) -(service wpa-supplicant-service-type wpa-supplicant) +(service wpa-supplicant-service-type) @end lisp @end defvr @@ -9197,6 +9673,99 @@ make an initial adjustment of more than 1,000 seconds. List of host names used as the default NTP servers. @end defvr +@cindex inetd +@deffn {Scheme variable} inetd-service-type +This service runs the @command{inetd} (@pxref{inetd invocation,,, +inetutils, GNU Inetutils}) daemon. @command{inetd} listens for +connections on internet sockets, and lazily starts the specified server +program when a connection is made on one of these sockets. + +The value of this service is an @code{inetd-configuration} object. The +following example configures the @command{inetd} daemon to provide the +built-in @command{echo} service, as well as an smtp service which +forwards smtp traffic over ssh to a server @code{smtp-server} behind a +gateway @code{hostname}: + +@example +(service + inetd-service-type + (inetd-configuration + (entries (list + (inetd-entry + (name "echo") + (socket-type 'stream) + (protocol "tcp") + (wait? #f) + (user "root")) + (inetd-entry + (node "127.0.0.1") + (name "smtp") + (socket-type 'stream) + (protocol "tcp") + (wait? #f) + (user "root") + (program (file-append openssh "/bin/ssh")) + (arguments + '("ssh" "-qT" "-i" "/path/to/ssh_key" + "-W" "smtp-server:25" "user@@hostname"))))) +@end example + +See below for more details about @code{inetd-configuration}. +@end deffn + +@deftp {Data Type} inetd-configuration +Data type representing the configuration of @command{inetd}. + +@table @asis +@item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")}) +The @command{inetd} executable to use. + +@item @code{entries} (default: @code{'()}) +A list of @command{inetd} service entries. Each entry should be created +by the @code{inetd-entry} constructor. +@end table +@end deftp + +@deftp {Data Type} inetd-entry +Data type representing an entry in the @command{inetd} configuration. +Each entry corresponds to a socket where @command{inetd} will listen for +requests. + +@table @asis +@item @code{node} (default: @code{#f}) +Optional string, a comma-separated list of local addresses +@command{inetd} should use when listening for this service. +@xref{Configuration file,,, inetutils, GNU Inetutils} for a complete +description of all options. +@item @code{name} +A string, the name must correspond to an entry in @code{/etc/services}. +@item @code{socket-type} +One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or +@code{'seqpacket}. +@item @code{protocol} +A string, must correspond to an entry in @code{/etc/protocols}. +@item @code{wait?} (default: @code{#t}) +Whether @command{inetd} should wait for the server to exit before +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"}, +@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 +program itself. For @command{inetd}'s internal services, this entry +must be @code{'()} or @code{'("internal")}. +@end table + +@xref{Configuration file,,, inetutils, GNU Inetutils} for a more +detailed discussion of each configuration field. +@end deftp + @cindex Tor @deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}] Return a service to run the @uref{https://torproject.org, Tor} anonymous @@ -9332,19 +9901,11 @@ false, users have to use other authentication method. Authorized public keys are stored in @file{~/.ssh/authorized_keys}. This is used only by protocol version 2. -@item @code{rsa-authentication?} (default: @code{#t}) -When true, users may log in using pure RSA authentication. When false, -users have to use other means of authentication. This is used only by -protocol 1. - @item @code{x11-forwarding?} (default: @code{#f}) When true, forwarding of X11 graphical client connections is enabled---in other words, @command{ssh} options @option{-X} and @option{-Y} will work. -@item @code{protocol-number} (default: @code{2}) -The SSH protocol number to use. - @item @code{challenge-response-authentication?} (default: @code{#f}) Specifies whether challenge response authentication is allowed (e.g. via PAM). @@ -9360,6 +9921,26 @@ Because PAM challenge response authentication usually serves an equivalent role to password authentication, you should disable either @code{challenge-response-authentication?} or @code{password-authentication?}. + +@item @code{print-last-log?} (default: @code{#t}) +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). + +This is a list of two-element lists, each of which containing the +subsystem name and a command (with optional arguments) to execute upon +subsystem request. + +The command @command{internal-sftp} implements an in-process SFTP +server. Alternately, one can specify the @command{sftp-server} command: +@example +(service openssh-service-type + (openssh-configuration + (subsystems + '(("sftp" ,(file-append openssh "/libexec/sftp-server")))))) +@end example @end table @end deftp @@ -9680,9 +10261,10 @@ system, add a @code{cups-service} to the operating system definition: @deffn {Scheme Variable} cups-service-type The service type for the CUPS print server. Its value should be a valid -CUPS configuration (see below). For example: +CUPS configuration (see below). To use the default settings, simply +write: @example -(service cups-service-type (cups-configuration)) +(service cups-service-type) @end example @end deffn @@ -10820,7 +11402,7 @@ Network interface on which to listen. @item @code{port} (default: @code{6379}) Port on which to accept connections on, a value of 0 will disable -listining on a TCP socket. +listening on a TCP socket. @item @code{working-directory} (default: @code{"/var/lib/redis"}) Directory in which to store the database and related files. @@ -10940,8 +11522,9 @@ Defaults to @samp{()}. Available @code{unix-listener-configuration} fields are: -@deftypevr {@code{unix-listener-configuration} parameter} file-name path -The file name on which to listen. +@deftypevr {@code{unix-listener-configuration} parameter} string path +Path to the file, relative to @code{base-dir} field. This is also used as +the section name. @end deftypevr @deftypevr {@code{unix-listener-configuration} parameter} string mode @@ -10962,8 +11545,9 @@ Defaults to @samp{""}. Available @code{fifo-listener-configuration} fields are: -@deftypevr {@code{fifo-listener-configuration} parameter} file-name path -The file name on which to listen. +@deftypevr {@code{fifo-listener-configuration} parameter} string path +Path to the file, relative to @code{base-dir} field. This is also used as +the section name. @end deftypevr @deftypevr {@code{fifo-listener-configuration} parameter} string mode @@ -11051,9 +11635,9 @@ The driver that the passdb should use. Valid values include Defaults to @samp{"pam"}. @end deftypevr -@deftypevr {@code{passdb-configuration} parameter} free-form-args args -A list of key-value args to the passdb driver. -Defaults to @samp{()}. +@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args +Space separated list of arguments to the passdb driver. +Defaults to @samp{""}. @end deftypevr @end deftypevr @@ -11070,9 +11654,9 @@ The driver that the userdb should use. Valid values include Defaults to @samp{"passwd"}. @end deftypevr -@deftypevr {@code{userdb-configuration} parameter} free-form-args args -A list of key-value args to the userdb driver. -Defaults to @samp{()}. +@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args +Space separated list of arguments to the userdb driver. +Defaults to @samp{""}. @end deftypevr @deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields @@ -12208,7 +12792,7 @@ as in this example: @end deffn @deftp {Data Type} opensmtpd-configuration -Data type regresenting the configuration of opensmtpd. +Data type representing the configuration of opensmtpd. @table @asis @item @code{package} (default: @var{opensmtpd}) @@ -12225,19 +12809,26 @@ remote servers. Run @command{man smtpd.conf} for more information. @subsubheading Exim Service +@cindex mail transfer agent (MTA) +@cindex MTA (mail transfer agent) +@cindex SMTP + @deffn {Scheme Variable} exim-service-type -This is the type of the @uref{https://exim.org, Exim} service, whose value -should be an @code{exim-configuration} object as in this example: +This is the type of the @uref{https://exim.org, Exim} mail transfer +agent (MTA), whose value should be an @code{exim-configuration} object +as in this example: @example (service exim-service-type (exim-configuration - (config-file (local-file "./my-exim.conf")) - (aliases '(("postmaster" "bob") - ("bob" "bob@@example.com" "bob@@example2.com"))))) + (config-file (local-file "./my-exim.conf")))) @end example @end deffn +In order to use an @code{exim-service-type} service you must also have a +@code{mail-aliases-service-type} service present in your +@code{operating-system} (even if it has no aliases). + @deftp {Data Type} exim-configuration Data type representing the configuration of exim. @@ -12252,16 +12843,37 @@ provided in @code{package}. The resulting configuration file is loaded after setting the @code{exim_user} and @code{exim_group} configuration variables. -@item @code{aliases} (default: @code{'()}) -List of aliases to use when delivering mail on this system. The -@code{car} of each list is used to match incoming mail, with the -@code{cdr} of each list designating how to deliver it. There may be many -delivery methods provided, in which case the mail is delivered to them -all. - @end table @end deftp +@subsubheading Mail Aliases Service + +@cindex email aliases +@cindex aliases, for email addresses + +@deffn {Scheme Variable} mail-aliases-service-type +This is the type of the service which provides @code{/etc/aliases}, +specifying how to deliver mail to users on this system. + +@example +(service mail-aliases-service-type + '(("postmaster" "bob") + ("bob" "bob@@example.com" "bob@@example2.com"))) +@end example +@end deffn + +The configuration for a @code{mail-aliases-service-type} service is an +association list denoting how to deliver mail that comes to this +system. Each entry is of the form @code{(alias addresses ...)}, with +@code{alias} specifying the local alias and @code{addresses} specifying +where to deliver this user's mail. + +The aliases aren't required to exist as users on the local system. In +the above example, there doesn't need to be a @code{postmaster} entry in +the @code{operating-system}'s @code{user-accounts} in order to deliver +the @code{postmaster} mail to @code{bob} (which subsequently would +deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}). + @node Messaging Services @subsubsection Messaging Services @@ -12805,6 +13417,15 @@ used to specify the list of @dfn{server blocks} required on the host and blocks} to configure. For this to work, use the default value for @var{config-file}. +At startup, @command{nginx} has not yet read its configuration file, so it +uses a default file to log error messages. If it fails to load its +configuration file, that is where error messages are logged. After the +configuration file is loaded, the default error log file changes as per +configuration. In our case, startup error messages can be found in +@file{/var/run/nginx/logs/error.log}, and after configuration in +@file{/var/log/nginx/error.log}. The second location can be changed with the +@var{log-directory} configuration option. + @end deffn @deffn {Scheme Variable} nginx-service-type @@ -12896,19 +13517,19 @@ Both can be run simultaneously. Available @code{openvpn-client-configuration} fields are: -@deftypevr @code{openvpn-client-configuration} parameter package openvpn +@deftypevr {@code{openvpn-client-configuration} parameter} package openvpn The OpenVPN package. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter string pid-file +@deftypevr {@code{openvpn-client-configuration} parameter} string pid-file The OpenVPN pid file. Defaults to @samp{"/var/run/openvpn/openvpn.pid"}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter proto proto +@deftypevr {@code{openvpn-client-configuration} parameter} proto proto The protocol (UDP or TCP) used to open a channel between clients and servers. @@ -12916,21 +13537,21 @@ Defaults to @samp{udp}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter dev dev +@deftypevr {@code{openvpn-client-configuration} parameter} dev dev The device type used to represent the VPN connection. Defaults to @samp{tun}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter string ca +@deftypevr {@code{openvpn-client-configuration} parameter} string ca The certificate authority to check connections against. Defaults to @samp{"/etc/openvpn/ca.crt"}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter string cert +@deftypevr {@code{openvpn-client-configuration} parameter} string cert The certificate of the machine the daemon is running on. It should be signed by the authority given in @code{ca}. @@ -12938,7 +13559,7 @@ Defaults to @samp{"/etc/openvpn/client.crt"}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter string key +@deftypevr {@code{openvpn-client-configuration} parameter} string key The key of the machine the daemon is running on. It must be the key whose certificate is @code{cert}. @@ -12946,21 +13567,21 @@ Defaults to @samp{"/etc/openvpn/client.key"}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter boolean comp-lzo? +@deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo? Whether to use the lzo compression algorithm. Defaults to @samp{#t}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter boolean persist-key? +@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key? Don't re-read key files across SIGUSR1 or --ping-restart. Defaults to @samp{#t}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter boolean persist-tun? +@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun? Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or --ping-restart restarts. @@ -12968,14 +13589,14 @@ Defaults to @samp{#t}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter number verbosity +@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity Verbosity level. Defaults to @samp{3}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter tls-auth-client tls-auth +@deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks. @@ -12983,42 +13604,42 @@ Defaults to @samp{#f}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter key-usage verify-key-usage? +@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage? Whether to check the server certificate has server usage extension. Defaults to @samp{#t}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter bind bind? +@deftypevr {@code{openvpn-client-configuration} parameter} bind bind? Bind to a specific local port number. Defaults to @samp{#f}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter resolv-retry resolv-retry? +@deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry? Retry resolving server address. Defaults to @samp{#t}. @end deftypevr -@deftypevr @code{openvpn-client-configuration} parameter openvpn-remote-list remote +@deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote A list of remote servers to connect to. Defaults to @samp{()}. Available @code{openvpn-remote-configuration} fields are: -@deftypevr @code{openvpn-remote-configuration} parameter string name +@deftypevr {@code{openvpn-remote-configuration} parameter} string name Server name. Defaults to @samp{"my-server"}. @end deftypevr -@deftypevr @code{openvpn-remote-configuration} parameter number port +@deftypevr {@code{openvpn-remote-configuration} parameter} number port Port number the server listens to. Defaults to @samp{1194}. @@ -13032,19 +13653,19 @@ Defaults to @samp{1194}. Available @code{openvpn-server-configuration} fields are: -@deftypevr @code{openvpn-server-configuration} parameter package openvpn +@deftypevr {@code{openvpn-server-configuration} parameter} package openvpn The OpenVPN package. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter string pid-file +@deftypevr {@code{openvpn-server-configuration} parameter} string pid-file The OpenVPN pid file. Defaults to @samp{"/var/run/openvpn/openvpn.pid"}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter proto proto +@deftypevr {@code{openvpn-server-configuration} parameter} proto proto The protocol (UDP or TCP) used to open a channel between clients and servers. @@ -13052,21 +13673,21 @@ Defaults to @samp{udp}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter dev dev +@deftypevr {@code{openvpn-server-configuration} parameter} dev dev The device type used to represent the VPN connection. Defaults to @samp{tun}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter string ca +@deftypevr {@code{openvpn-server-configuration} parameter} string ca The certificate authority to check connections against. Defaults to @samp{"/etc/openvpn/ca.crt"}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter string cert +@deftypevr {@code{openvpn-server-configuration} parameter} string cert The certificate of the machine the daemon is running on. It should be signed by the authority given in @code{ca}. @@ -13074,7 +13695,7 @@ Defaults to @samp{"/etc/openvpn/client.crt"}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter string key +@deftypevr {@code{openvpn-server-configuration} parameter} string key The key of the machine the daemon is running on. It must be the key whose certificate is @code{cert}. @@ -13082,21 +13703,21 @@ Defaults to @samp{"/etc/openvpn/client.key"}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter boolean comp-lzo? +@deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo? Whether to use the lzo compression algorithm. Defaults to @samp{#t}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter boolean persist-key? +@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key? Don't re-read key files across SIGUSR1 or --ping-restart. Defaults to @samp{#t}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter boolean persist-tun? +@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun? Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or --ping-restart restarts. @@ -13104,14 +13725,14 @@ Defaults to @samp{#t}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter number verbosity +@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity Verbosity level. Defaults to @samp{3}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter tls-auth-server tls-auth +@deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks. @@ -13119,56 +13740,56 @@ Defaults to @samp{#f}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter number port +@deftypevr {@code{openvpn-server-configuration} parameter} number port Specifies the port number on which the server listens. Defaults to @samp{1194}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter ip-mask server +@deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server An ip and mask specifying the subnet inside the virtual network. Defaults to @samp{"10.8.0.0 255.255.255.0"}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter cidr6 server-ipv6 +@deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6 A CIDR notation specifying the IPv6 subnet inside the virtual network. Defaults to @samp{#f}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter string dh +@deftypevr {@code{openvpn-server-configuration} parameter} string dh The Diffie-Hellman parameters file. Defaults to @samp{"/etc/openvpn/dh2048.pem"}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter string ifconfig-pool-persist +@deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist The file that records client IPs. Defaults to @samp{"/etc/openvpn/ipp.txt"}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter gateway redirect-gateway? +@deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway? When true, the server will act as a gateway for its clients. Defaults to @samp{#f}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter boolean client-to-client? -When true, clients are alowed to talk to each other inside the VPN. +@deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client? +When true, clients are allowed to talk to each other inside the VPN. Defaults to @samp{#f}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter keepalive keepalive +@deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive Causes ping-like messages to be sent back and forth over the link so that each side knows when the other side has gone down. @code{keepalive} requires a pair. The first element is the period of the ping sending, @@ -13177,43 +13798,43 @@ down. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter number max-clients +@deftypevr {@code{openvpn-server-configuration} parameter} number max-clients The maximum number of clients. Defaults to @samp{100}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter string status +@deftypevr {@code{openvpn-server-configuration} parameter} string status The status file. This file shows a small report on current connection. -It is trunkated and rewritten every minute. +It is truncated and rewritten every minute. Defaults to @samp{"/var/run/openvpn/status"}. @end deftypevr -@deftypevr @code{openvpn-server-configuration} parameter openvpn-ccd-list client-config-dir +@deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir The list of configuration for some clients. Defaults to @samp{()}. Available @code{openvpn-ccd-configuration} fields are: -@deftypevr @code{openvpn-ccd-configuration} parameter string name +@deftypevr {@code{openvpn-ccd-configuration} parameter} string name Client name. Defaults to @samp{"client"}. @end deftypevr -@deftypevr @code{openvpn-ccd-configuration} parameter ip-mask iroute +@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute Client own network Defaults to @samp{#f}. @end deftypevr -@deftypevr @code{openvpn-ccd-configuration} parameter ip-mask ifconfig-push +@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push Client VPN IP. Defaults to @samp{#f}. @@ -13493,62 +14114,591 @@ The Cuirass package to use. @end table @end deftp -@node Miscellaneous Services -@subsubsection Miscellaneous Services +@node Power management Services +@subsubsection Power management Services +@cindex power management with TLP +The @code{(gnu services pm)} module provides a Guix service definition +for the Linux power management tool TLP. -@cindex lirc -@subsubheading Lirc Service +TLP enables various powersaving modes in userspace and kernel. +Contrary to @code{upower-service}, it is not a passive, +monitoring tool, as it will apply custom settings each time a new power +source is detected. More information can be found at +@uref{http://linrunner.de/en/tlp/tlp.html, TLP home page}. -The @code{(gnu services lirc)} module provides the following service. +@deffn {Scheme Variable} tlp-service-type +The service type for the TLP tool. Its value should be a valid +TLP configuration (see below). To use the default settings, simply +write: +@example +(service tlp-service-type) +@end example +@end deffn -@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. +By default TLP does not need much configuration but most TLP parameters +can be tweaked using @code{tlp-configuration}. -Optionally, @var{device}, @var{driver} and @var{config-file} -(configuration file name) may be specified. See @command{lircd} manual -for details. +Each parameter definition is preceded by its type; for example, +@samp{boolean foo} indicates that the @code{foo} parameter +should be specified as a boolean. Types starting with +@code{maybe-} denote parameters that won't show up in TLP config file +when their value is @code{'disabled}. -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{lircd}. -@end deffn +@c The following documentation was initially generated by +@c (generate-tlp-documentation) in (gnu services pm). Manually maintained +@c documentation is better, so we shouldn't hesitate to edit below as +@c needed. However if the change you want to make to this documentation +@c can be done in an automated way, it's probably easier to change +@c (generate-documentation) than to make it below and have to deal with +@c the churn as TLP updates. -@cindex spice -@subsubheading Spice Service +Available @code{tlp-configuration} fields are: -The @code{(gnu services spice)} module provides the following service. +@deftypevr {@code{tlp-configuration} parameter} package tlp +The TLP package. -@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{tlp-configuration} parameter} boolean tlp-enable? +Set to true if you wish to enable TLP. -@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{#t}. -The optional @var{config} argument specifies the configuration for -@command{dicod}, which should be a @code{} 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{tlp-configuration} parameter} string tlp-default-mode +Default mode when no power supply can be detected. Alternatives are AC +and BAT. -@deftp {Data Type} dicod-configuration -Data type representing the configuration of dicod. +Defaults to @samp{"AC"}. -@table @asis -@item @code{dico} (default: @var{dico}) +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac +Number of seconds Linux kernel has to wait after the disk goes idle, +before syncing on AC. + +Defaults to @samp{0}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat +Same as @code{disk-idle-ac} but on BAT mode. + +Defaults to @samp{2}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac +Dirty pages flushing periodicity, expressed in seconds. + +Defaults to @samp{15}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat +Same as @code{max-lost-work-secs-on-ac} but on BAT mode. + +Defaults to @samp{60}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac +CPU frequency scaling governor on AC mode. With intel_pstate driver, +alternatives are powersave and performance. With acpi-cpufreq driver, +alternatives are ondemand, powersave, performance and conservative. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat +Same as @code{cpu-scaling-governor-on-ac} but on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac +Set the min available frequency for the scaling governor on AC. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac +Set the max available frequency for the scaling governor on AC. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat +Set the min available frequency for the scaling governor on BAT. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat +Set the max available frequency for the scaling governor on BAT. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac +Limit the min P-state to control the power dissipation of the CPU, in AC +mode. Values are stated as a percentage of the available performance. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac +Limit the max P-state to control the power dissipation of the CPU, in AC +mode. Values are stated as a percentage of the available performance. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat +Same as @code{cpu-min-perf-on-ac} on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat +Same as @code{cpu-max-perf-on-ac} on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac? +Enable CPU turbo boost feature on AC mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat? +Same as @code{cpu-boost-on-ac?} on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac? +Allow Linux kernel to minimize the number of CPU cores/hyper-threads +used under light load conditions. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat? +Same as @code{sched-powersave-on-ac?} but on BAT mode. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog? +Enable Linux kernel NMI watchdog. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls +For Linux kernels with PHC patch applied, change CPU voltages. An +example value would be @samp{"F:V F:V F:V F:V"}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac +Set CPU performance versus energy saving policy on AC. Alternatives are +performance, normal, powersave. + +Defaults to @samp{"performance"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat +Same as @code{energy-perf-policy-ac} but on BAT mode. + +Defaults to @samp{"powersave"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices +Hard disk devices. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac +Hard disk advanced power management level. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat +Same as @code{disk-apm-bat} but on BAT mode. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac +Hard disk spin down timeout. One value has to be specified for each +declared hard disk. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat +Same as @code{disk-spindown-timeout-on-ac} but on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched +Select IO scheduler for disk devices. One value has to be specified for +each declared hard disk. Example alternatives are cfq, deadline and +noop. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac +SATA aggressive link power management (ALPM) level. Alternatives are +min_power, medium_power, max_performance. + +Defaults to @samp{"max_performance"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat +Same as @code{sata-linkpwr-ac} but on BAT mode. + +Defaults to @samp{"min_power"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist +Exclude specified SATA host devices for link power management. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac? +Enable Runtime Power Management for AHCI controller and disks on AC +mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat? +Same as @code{ahci-runtime-pm-on-ac} on BAT mode. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout +Seconds of inactivity before disk is suspended. + +Defaults to @samp{15}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac +PCI Express Active State Power Management level. Alternatives are +default, performance, powersave. + +Defaults to @samp{"performance"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat +Same as @code{pcie-aspm-ac} but on BAT mode. + +Defaults to @samp{"powersave"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac +Radeon graphics clock speed level. Alternatives are low, mid, high, +auto, default. + +Defaults to @samp{"high"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat +Same as @code{radeon-power-ac} but on BAT mode. + +Defaults to @samp{"low"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac +Radeon dynamic power management method (DPM). Alternatives are battery, +performance. + +Defaults to @samp{"performance"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat +Same as @code{radeon-dpm-state-ac} but on BAT mode. + +Defaults to @samp{"battery"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac +Radeon DPM performance level. Alternatives are auto, low, high. + +Defaults to @samp{"auto"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat +Same as @code{radeon-dpm-perf-ac} but on BAT mode. + +Defaults to @samp{"auto"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac? +Wifi power saving mode. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat? +Same as @code{wifi-power-ac?} but on BAT mode. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable? +Disable wake on LAN. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac +Timeout duration in seconds before activating audio power saving on +Intel HDA and AC97 devices. A value of 0 disables power saving. + +Defaults to @samp{0}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat +Same as @code{sound-powersave-ac} but on BAT mode. + +Defaults to @samp{1}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller? +Disable controller in powersaving mode on Intel HDA devices. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat? +Enable optical drive in UltraBay/MediaBay on BAT mode. Drive can be +powered on again by releasing (and reinserting) the eject lever or by +pressing the disc eject button on newer models. + +Defaults to @samp{#f}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string bay-device +Name of the optical drive device to power off. + +Defaults to @samp{"sr0"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac +Runtime Power Management for PCI(e) bus devices. Alternatives are on +and auto. + +Defaults to @samp{"on"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat +Same as @code{runtime-pm-ac} but on BAT mode. + +Defaults to @samp{"auto"}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all? +Runtime Power Management for all PCI(e) bus devices, except blacklisted +ones. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist +Exclude specified PCI(e) device addresses from Runtime Power Management. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist +Exclude PCI(e) devices assigned to the specified drivers from Runtime +Power Management. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend? +Enable USB autosuspend feature. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist +Exclude specified devices from USB autosuspend. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan? +Exclude WWAN devices from USB autosuspend. + +Defaults to @samp{#t}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist +Include specified devices into USB autosuspend, even if they are already +excluded by the driver or via @code{usb-blacklist-wwan?}. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown? +Enable USB autosuspend before shutdown. + +Defaults to @samp{disabled}. + +@end deftypevr + +@deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup? +Restore radio device state (bluetooth, wifi, wwan) from previous +shutdown on system startup. + +Defaults to @samp{#f}. + +@end deftypevr + + +The @code{(gnu services pm)} module provides an interface to +thermald, a CPU frequency scaling service which helps prevent overheating. + +@defvr {Scheme Variable} thermald-service-type +This is the service type for +@uref{https://01.org/linux-thermal-daemon/, thermald}, the Linux +Thermal Daemon, which is responsible for controlling the thermal state +of processors and preventing overheating. +@end defvr + +@deftp {Data Type} thermald-configuration +Data type representing the configuration of @code{thermald-service-type}. + +@table @asis +@item @code{ignore-cpuid-check?} (default: @code{#f}) +Ignore cpuid check for supported CPU models. + +@item @code{thermald} (default: @var{thermald}) +Package object of thermald. + +@end table +@end deftp + + +@node Miscellaneous Services +@subsubsection Miscellaneous Services + + +@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{} 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")}) @@ -13556,33 +14706,75 @@ 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{} objects denoting handlers (module instances). + @item @code{databases} (default: @var{(list %dicod-database:gcide)}) List of @code{} objects denoting dictionaries to be served. @end table @end deftp -@deftp {Data Type} dicod-database -Data type representing a dictionary database. +@deftp {Data Type} dicod-handler +Data type representing a dictionary handler (module instance). @table @asis @item @code{name} -Name of the database, will be used in DICT commands. +Name of the handler (module instance). -@item @code{module} -Name of the dicod module used by this database +@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{} 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{} object serving the GNU Collaborative International -Dictonary of English using the @code{gcide} package. +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 + @subsubsection Version Control The @code{(gnu services version-control)} module provides the following services: @@ -13592,7 +14784,7 @@ The @code{(gnu services version-control)} module provides the following services @deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)] Return a service that runs @command{git daemon}, a simple TCP server to -expose repositiories over the Git protocol for annoymous access. +expose repositories over the Git protocol for anonymous access. The optional @var{config} argument should be a @code{} object, by default it allows read-only @@ -13740,6 +14932,19 @@ $ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" $ export GIT_SSL_CAINFO="$SSL_CERT_FILE" @end example +As another example, R requires the @code{CURL_CA_BUNDLE} environment +variable to point to a certificate bundle, so you would have to run +something like this: + +@example +$ guix package -i nss-certs +$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" +@end example + +For other applications you may want to look up the required environment +variable in the relevant documentation. + + @node Name Service Switch @subsection Name Service Switch @@ -13891,9 +15096,9 @@ kernel modules that may be needed to achieve that. 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 two ways to build an initrd: the -high-level @code{base-initrd} procedure, and the low-level -@code{expression->initrd} procedure. +system linux-initrd)} module provides three ways to build an initrd: the +high-level @code{base-initrd} procedure and the low-level +@code{raw-initrd} and @code{expression->initrd} procedures. The @code{base-initrd} procedure is intended to cover most common uses. For example, if you want to add a bunch of kernel modules to be loaded @@ -13914,9 +15119,16 @@ The @code{base-initrd} procedure also handles common use cases that involves using the system as a QEMU guest, or as a ``live'' system with volatile root file system. -The initial RAM disk produced by @code{base-initrd} honors several -options passed on the Linux kernel command line (that is, arguments -passed @i{via} the @code{linux} command of GRUB, or the +The @code{base-initrd} procedure is built from @code{raw-initrd} procedure. +Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level, +such as trying to guess which kernel modules and packages should be included +to the initrd. An example use of @code{raw-initrd} is when a user has +a custom Linux kernel configuration and default kernel modules included by +@code{base-initrd} are not available. + +The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd} +honors several options passed on the Linux kernel command line +(that is, arguments passed @i{via} the @code{linux} command of GRUB, or the @code{-append} option of QEMU), notably: @table @code @@ -13955,19 +15167,23 @@ Manual}, for more information on Guile's REPL. @end table Now that you know all the features that initial RAM disks produced by -@code{base-initrd} provide, here is how to use it and customize it -further. +@code{base-initrd} and @code{raw-initrd} provide, +here is how to use it and customize it further. @cindex initrd @cindex initial RAM disk -@deffn {Monadic Procedure} base-initrd @var{file-systems} @ - [#:qemu-networking? #f] [#:virtio? #t] [#:volatile-root? #f] @ - [#:extra-modules '()] [#:mapped-devices '()] -Return a monadic derivation that builds a generic initrd. @var{file-systems} is +@deffn {Monadic 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 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. @var{mapped-devices} is a list of device mappings to realize before @var{file-systems} are mounted (@pxref{Mapped Devices}). +@var{helper-packages} is a list of packages to be copied in the initrd. It may +include @code{e2fsck/static} or other packages needed by the initrd to check +root partition. When @var{qemu-networking?} is true, set up networking with the standard QEMU parameters. When @var{virtio?} is true, load additional modules so that the @@ -13975,6 +15191,18 @@ initrd can be used as a QEMU guest with para-virtualized I/O drivers. When @var{volatile-root?} is true, the root file system is writable but any changes to it are lost. +@end deffn + +@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}. + +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. The initrd is automatically populated with all the kernel modules necessary for @var{file-systems} and for the given options. However, additional kernel @@ -14036,6 +15264,32 @@ The @code{grub-theme} object describing the theme to use. @item @code{grub} (default: @code{grub}) The GRUB package to use. + +@item @code{terminal-outputs} (default: @code{'gfxterm}) +The output terminals used for the GRUB boot menu, as a list of symbols. +These values are accepted: @code{console}, @code{serial}, +@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text}, +@code{morse}, and @code{pkmodem}. This field corresponds to the GRUB +variable GRUB_TERMINAL_OUTPUT (@pxref{Simple configuration,,, grub,GNU +GRUB manual}). + +@item @code{terminal-inputs} (default: @code{'()}) +The input terminals used for the GRUB boot menu, as a list of symbols. +The default is the native platform terminal as determined by GRUB at +run-time. These values are accepted: @code{console}, @code{serial}, +@code{serial_@{0-3@}}, @code{at_keyboard}, and @code{usb_keyboard}. +This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT +(@pxref{Simple configuration,,, grub,GNU GRUB manual}). + +@item @code{serial-unit} (default: @code{#f}) +The serial unit used by GRUB, as an integer from 0 to 3. The default +value is chosen by GRUB at run-time; currently GRUB chooses 0, which +corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}). + +@item @code{serial-speed} (default: @code{#f}) +The speed of the serial interface, as an integer. The default value is +chosen by GRUB at run-time; currently GRUB chooses 9600@tie{}bps +(@pxref{Serial terminal,,, grub,GNU GRUB manual}). @end table @end deftp @@ -14159,7 +15413,7 @@ overwritten. This behavior mirrors that of @command{guix package} It also adds a GRUB menu entry for the new OS configuration, and moves entries for older configurations to a submenu---unless -@option{--no-grub} is passed. +@option{--no-bootloader} is passed. @quotation Note @c The paragraph below refers to the problem discussed at @@ -14239,7 +15493,7 @@ needed for the system to operate correctly---e.g., the @file{/etc}, @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file. This command also installs GRUB on the device specified in -@file{my-os-config}, unless the @option{--no-grub} option was passed. +@file{my-os-config}, unless the @option{--no-bootloader} option was passed. @item vm @cindex virtual machine @@ -14342,6 +15596,11 @@ of the given @var{size}. @var{size} may be a number of bytes, or it may include a unit as a suffix (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}). +@item --root=@var{file} +@itemx -r @var{file} +Make @var{file} a symlink to the result, and register it as a garbage +collector root. + @item --on-error=@var{strategy} Apply @var{strategy} when an error occurs when reading @var{file}. @var{strategy} may be one of the following: @@ -14478,14 +15737,14 @@ which may be insufficient for some operations. The file name of the qcow2 image. @end table -The default @command{run-vm.sh} script that is returned by an invokation of +The default @command{run-vm.sh} script that is returned by an invocation of @command{guix system vm} does not add a @command{-net user} flag by default. To get network access from within the vm add the @code{(dhcp-client-service)} to your system definition and start the VM using @command{`guix system vm config.scm` -net user}. An important caveat of using @command{-net user} for networking is that @command{ping} will not work, because it uses the ICMP protocol. You'll have to use a different command to check for -network connectivity, like for example @command{curl}. +network connectivity, for example @command{guix download}. @subsubsection Connecting Through SSH @@ -14616,11 +15875,12 @@ with a simple example, the service type for the Guix build daemon (extensions (list (service-extension shepherd-root-service-type guix-shepherd-service) (service-extension account-service-type guix-accounts) - (service-extension activation-service-type guix-activation))))) + (service-extension activation-service-type guix-activation))) + (default-value (guix-configuration)))) @end example @noindent -It defines two things: +It defines three things: @enumerate @item @@ -14633,6 +15893,9 @@ service, returns a list of objects to extend the service of that type. Every service type has at least one service extension. The only exception is the @dfn{boot service type}, which is the ultimate service. + +@item +Optionally, a default value for instances of this type. @end enumerate In this example, @var{guix-service-type} extends three services: @@ -14668,7 +15931,13 @@ A service of this type is instantiated like this: The second argument to the @code{service} form is a value representing the parameters of this specific service instance. @xref{guix-configuration-type, @code{guix-configuration}}, for -information about the @code{guix-configuration} data type. +information about the @code{guix-configuration} data type. When the +value is omitted, the default value specified by +@code{guix-service-type} is used: + +@example +(service guix-service-type) +@end example @var{guix-service-type} is quite simple because it extends other services but is not extensible itself. @@ -14731,10 +16000,31 @@ Services}). This section provides a reference on how to manipulate services and service types. This interface is provided by the @code{(gnu services)} module. -@deffn {Scheme Procedure} service @var{type} @var{value} +@deffn {Scheme Procedure} service @var{type} [@var{value}] Return a new service of @var{type}, a @code{} object (see below.) @var{value} can be any object; it represents the parameters of this particular service instance. + +When @var{value} is omitted, the default value specified by @var{type} +is used; if @var{type} does not specify a default value, an error is +raised. + +For instance, this: + +@example +(service openssh-service-type) +@end example + +@noindent +is equivalent to this: + +@example +(service openssh-service-type + (openssh-configuration)) +@end example + +In both cases the result is an instance of @code{openssh-service-type} +with the default configuration. @end deffn @deffn {Scheme Procedure} service? @var{obj} @@ -14745,7 +16035,7 @@ Return true if @var{obj} is a service. Return the type of @var{service}---i.e., a @code{} object. @end deffn -@deffn {Scheme Procedure} service-parameters @var{service} +@deffn {Scheme Procedure} service-value @var{service} Return the value associated with @var{service}. It represents its parameters. @end deffn @@ -15011,6 +16301,70 @@ This service represents PID@tie{}1. @end defvr +@node Documentation +@section Documentation + +@cindex documentation, searching for +@cindex searching for documentation +@cindex Info, documentation format +@cindex man pages +@cindex manual pages +In most cases packages installed with Guix come with documentation. +There are two main documentation formats: ``Info'', a browseable +hypertext format used for GNU software, and ``manual pages'' (or ``man +pages''), the linear documentation format traditionally found on Unix. +Info manuals are accessed with the @command{info} command or with Emacs, +and man pages are accessed using @command{man}. + +You can look for documentation of software installed on your system by +keyword. For example, the following command searches for information +about ``TLS'' in Info manuals: + +@example +$ info -k TLS +"(emacs)Network Security" -- STARTTLS +"(emacs)Network Security" -- TLS +"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags +"(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function +@dots{} +@end example + +@noindent +The command below searches for the same keyword in man pages: + +@example +$ man -k TLS +SSL (7) - OpenSSL SSL/TLS library +certtool (1) - GnuTLS certificate tool +@dots {} +@end example + +These searches are purely local to your computer so you have the +guarantee that documentation you find corresponds to what you have +actually installed, you can access it off-line, and your privacy is +respected. + +Once you have these results, you can view the relevant documentation by +running, say: + +@example +$ info "(gnutls)Core TLS API" +@end example + +@noindent +or: + +@example +$ man certtool +@end example + +Info manuals contain sections and indices as well as hyperlinks like +those found in Web pages. The @command{info} reader (@pxref{Top, Info +reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart +(@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key +bindings to navigate manuals. @xref{Getting Started,,, info, Info: An +Introduction}, for an introduction to Info navigation. + @node Installing Debugging Files @section Installing Debugging Files @@ -15092,9 +16446,9 @@ distribution: @smallexample $ guix lint -c cve -gnu/packages/base.scm:652:2: glibc-2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547 -gnu/packages/gcc.scm:334:2: gcc-4.9.3: probably vulnerable to CVE-2015-5276 -gnu/packages/image.scm:312:2: openjpeg-2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924 +gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547 +gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276 +gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924 @dots{} @end smallexample @@ -15322,7 +16676,7 @@ needed is to review and apply the patch. * Package Naming:: What's in a name? * Version Numbers:: When the name is not enough. * Synopses and Descriptions:: Helping users find the right package. -* Python Modules:: Taming the snake. +* Python Modules:: A touch of British comedy. * Perl Modules:: Little pearls. * Java Packages:: Coffee break. * Fonts:: Fond of fonts.