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@*
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 Federico Beffa@*
+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
@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.
@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
* 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
* 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.
* 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
* 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.
~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}).
If your host distro uses the systemd init system, this can be achieved
with these commands:
+@c Versions of systemd that supported symlinked service files are not
+@c yet widely deployed, so we should suggest that users copy the service
+@c files into place.
+@c
+@c See this thread for more information:
+@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
+
@example
-# ln -s ~root/.guix-profile/lib/systemd/system/guix-daemon.service \
+# cp ~root/.guix-profile/lib/systemd/system/guix-daemon.service \
/etc/systemd/system/
# systemctl start guix-daemon && systemctl enable guix-daemon
@end example
If your host distro uses the Upstart init system:
@example
-# ln -s ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/
# initctl reload-configuration
+# cp ~root/.guix-profile/lib/upstart/system/guix-daemon.conf /etc/init/
# start guix-daemon
@end example
@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:
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
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
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
* 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
(@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
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
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}
@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
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
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
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
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.
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
@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
@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.
@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}).
@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
@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
* 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
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
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}}).
@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
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}
@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
@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
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}]
@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}
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
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
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
@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:”
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.
@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.
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
@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.
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
* 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
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"]
(operating-system
;; @dots{}
(services (cons* (mcron-service)
- (service rottlog-service-type (rottlog-configuration))
+ (service rottlog-service-type)
%base-services)))
@end lisp
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
@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
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
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
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).
+
+@item @code{use-pam?} (default: @code{#t})
+Enables the Pluggable Authentication Module interface. If set to
+@code{#t}, this will enable PAM authentication using
+@code{challenge-response-authentication?} and
+@code{password-authentication?}, in addition to PAM account and session
+module processing for all authentication types.
+
+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
@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
@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.
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
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
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
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
@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})
@end table
@end deftp
+@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} 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"))))
+@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.
+
+@table @asis
+@item @code{package} (default: @var{exim})
+Package object of the Exim server.
+
+@item @code{config-file} (default: @code{#f})
+File-like object of the Exim configuration file to use. If its value is
+@code{#f} then use the default configuration file from the package
+provided in @code{package}. The resulting configuration file is loaded
+after setting the @code{exim_user} and @code{exim_group} configuration
+variables.
+
+@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
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
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.
@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}.
@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}.
@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.
@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.
@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}.
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.
@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}.
@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}.
@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.
@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.
@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,
@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}.
@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}.
+
+@end deftypevr
+
+@deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode
+Default mode when no power supply can be detected. Alternatives are AC
+and BAT.
+
+Defaults to @samp{"AC"}.
+
+@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{<dicod-configuration>} object, by
names to listen to (@pxref{Server Settings, @code{listen} directive,,
dico, GNU Dico Manual}).
+@item @code{handlers} (default: @var{'()})
+List of @code{<dicod-handler>} objects denoting handlers (module instances).
+
@item @code{databases} (default: @var{(list %dicod-database:gcide)})
List of @code{<dicod-database>} objects denoting dictionaries to be served.
@end table
@end deftp
-@deftp {Data Type} dicod-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{<dicod-handler>} object, otherwise not.
+
+@item @code{options}
+List of strings or gexps representing the arguments for the database
+(@pxref{Databases,,, dico, GNU Dico Manual}).
@end table
@end deftp
@defvr {Scheme Variable} %dicod-database:gcide
A @code{<dicod-database>} object serving the GNU Collaborative International
-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:
@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{<git-daemon-configuration>} object, by default it allows read-only
$ 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
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
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
@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
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
@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
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
@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
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:
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
(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
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:
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.
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{<service-type>} 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}
Return the type of @var{service}---i.e., a @code{<service-type>} 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
@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
@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
* 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.
HCoop / jackhill / guix / guix.git / blobdiff