@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
@copying
-Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017 Ludovic Courtès@*
+Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018 Ludovic Courtès@*
Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
Copyright @copyright{} 2013 Nikita Karetnikov@*
Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
Copyright @copyright{} 2016, 2017 Chris Marusich@*
Copyright @copyright{} 2016, 2017 Efraim Flashner@*
Copyright @copyright{} 2016 John Darrington@*
-Copyright @copyright{} 2016 ng0@*
+Copyright @copyright{} 2016, 2017 ng0@*
Copyright @copyright{} 2016, 2017 Jan Nieuwenhuizen@*
Copyright @copyright{} 2016 Julien Lepiller@*
Copyright @copyright{} 2016 Alex ter Weele@*
Copyright @copyright{} 2017 Tobias Geerinckx-Rice@*
Copyright @copyright{} 2017 George Clemmer@*
Copyright @copyright{} 2017 Andy Wingo@*
-Copyright @copyright{} 2017 Arun Isaac
+Copyright @copyright{} 2017 Arun Isaac@*
+Copyright @copyright{} 2017 nee@*
+Copyright @copyright{} 2018 Rutger Helling
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@c FIXME: Specify a version number once a release has been made.
@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August
2017 or later;
+@item @url{http://zlib.net, zlib};
@item @url{http://www.gnu.org/software/make/, GNU Make}.
@end itemize
version 0.10.2 or later.
@item
-When @url{http://zlib.net, zlib} is available, @command{guix publish}
-can compress build byproducts (@pxref{Invoking guix publish}).
+When @url{http://www.bzip.org, libbz2} is available,
+@command{guix-daemon} can use it to compress build logs.
@end itemize
Unless @code{--disable-daemon} was passed to @command{configure}, the
@itemize
@item @url{http://sqlite.org, SQLite 3};
-@item @url{http://www.bzip.org, libbz2};
@item @url{http://gcc.gnu.org, GCC's g++}, with support for the
C++11 standard.
@end itemize
# guix offload test machines.scm '\.gnu\.org$'
@end example
+@cindex offload status
+To display the current load of all build hosts, run this command on the
+main node:
+
+@example
+# guix offload status
+@end example
+
+
@node Invoking guix-daemon
@section Invoking @command{guix-daemon}
though, when @command{guix-daemon} is running under an unprivileged user
account.
-@item --disable-log-compression
-Disable compression of the build logs.
+@item --log-compression=@var{type}
+Compress build logs according to @var{type}, one of @code{gzip},
+@code{bzip2}, or @code{none}.
Unless @code{--lose-logs} is used, all the build logs are kept in the
@var{localstatedir}. To save space, the daemon automatically compresses
-them with bzip2 by default. This option disables that.
+them with bzip2 by default.
@item --disable-deduplication
@cindex deduplication
When @code{--listen} is omitted, @command{guix-daemon} listens for
connections on the Unix-domain socket located at
-@file{@var{localstatedir}/daemon-socket/socket}.
+@file{@var{localstatedir}/guix/daemon-socket/socket}.
@end table
sub-directories of
@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latter
directory exists because potentially there may exist thousands of Emacs
-packages and storing all their files in a single directory may be not
+packages and storing all their files in a single directory may not be
reliable (because of name conflicts). So we think using a separate
directory for each package is a good idea. It is very similar to how
the Emacs package system organizes the file structure (@pxref{Package
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,,,
+package}}), you may also use the Emacs-Guix 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):
In a multi-user setup, user profiles are stored in a place registered as
a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
to (@pxref{Invoking guix gc}). That directory is normally
-@code{@var{localstatedir}/profiles/per-user/@var{user}}, where
+@code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
@var{localstatedir} is the value passed to @code{configure} as
@code{--localstatedir}, and @var{user} is the user name. The
@file{per-user} directory is created when @command{guix-daemon} is
@cindex hydra
@cindex build farm
-The @code{hydra.gnu.org} server is a front-end to an official build farm
-that builds packages from the GNU distribution continuously for some
+The @code{mirror.hydra.gnu.org} server is a front-end to an official build farm
+that builds packages from Guix continuously for some
architectures, and makes them available as substitutes. This is the
default source of substitutes; it can be overridden by passing the
@option{--substitute-urls} option either to @command{guix-daemon}
# guix archive --authorize < @var{prefix}/share/guix/hydra.gnu.org.pub
@end example
+@quotation Note
+Similarly, the @file{berlin.guixsd.org.pub} file contains the public key
+for the project's new build farm, reachable at
+@indicateurl{https://berlin.guixsd.org}.
+
+As of this writing @code{berlin.guixsd.org} is being upgraded so it can
+better scale up, but you might want to give it a try. It is backed by
+20 x86_64/i686 build nodes and may be able to provide substitutes more
+quickly than @code{mirror.hydra.gnu.org}.
+@end quotation
+
Once this is in place, the output of a command like @code{guix build}
should change from something like:
@example
$ guix build emacs --dry-run
-The following files would be downloaded:
+112.3 MB would be downloaded:
/gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
/gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
/gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
package -i @var{something}}, but that's not possible in this case. This
is where @command{guix pack} comes in.
+@quotation Note
+If you are looking for ways to exchange binaries among machines that
+already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
+publish}, and @ref{Invoking guix archive}.
+@end quotation
+
@cindex pack
@cindex bundle
@cindex application bundle
@cindex @command{guix archive}
@cindex archive
The @command{guix archive} command allows users to @dfn{export} files
-from the store into a single archive, and to later @dfn{import} them.
+from the store into a single archive, and to later @dfn{import} them on
+a machine that runs Guix.
In particular, it allows store files to be transferred from one machine
to the store on another machine.
+@quotation Note
+If you're looking for a way to produce archives in a format suitable for
+tools other than Guix, @pxref{Invoking guix pack}.
+@end quotation
+
@cindex exporting store items
To export store files as an archive to standard output, run:
The user is expected to provide a value for the key @code{#:import-path}
and, in some cases, @code{#:unpack-path}. The
@url{https://golang.org/doc/code.html#ImportPaths, import path}
-corresponds to the filesystem path expected by the package's build
+corresponds to the file system path expected by the package's build
scripts and any referring packages, and provides a unique way to
refer to a Go package. It is typically based on a combination of the
-package source code's remote URI and filesystem hierarchy structure. In
+package source code's remote URI and file system hierarchy structure. In
some cases, you will need to unpack the package's source code to a
different directory structure than the one indicated by the import path,
and @code{#:unpack-path} should be used in such cases.
procedure to perform the build actions they prescribe (@pxref{The
Store}).
+@cindex fixed-output derivations
+Operations such as file downloads and version-control checkouts for
+which the expected content hash is known in advance are modeled as
+@dfn{fixed-output derivations}. Unlike regular derivations, the outputs
+of a fixed-output derivation are independent of its inputs---e.g., a
+source code download produces the same result regardless of the download
+method and tools being used.
+
The @code{(guix derivations)} module provides a representation of
derivations as Scheme objects, along with procedures to create and
otherwise manipulate derivations. The lowest-level primitive to create
@table @code
@item --with-source=@var{source}
-Use @var{source} as the source of the corresponding package.
+@itemx --with-source=@var{package}=@var{source}
+@itemx --with-source=@var{package}@@@var{version}=@var{source}
+Use @var{source} as the source of @var{package}, and @var{version} as
+its version number.
@var{source} must be a file name or a URL, as for @command{guix
download} (@pxref{Invoking guix download}).
-The ``corresponding package'' is taken to be the one specified on the
-command line the name of which matches the base of @var{source}---e.g.,
+When @var{package} is omitted,
+it is taken to be the package name specified on the
+command line that matches the base of @var{source}---e.g.,
if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
-package is @code{guile}. Likewise, the version string is inferred from
+package is @code{guile}.
+
+Likewise, when @var{version} is omitted, the version string is inferred from
@var{source}; in the previous example, it is @code{2.0.10}.
This option allows users to try out versions of packages other than the
@example
$ git clone git://git.sv.gnu.org/guix.git
-$ guix build guix --with-source=./guix
+$ guix build guix --with-source=guix@@1.0=./guix
@end example
@item --with-input=@var{package}=@var{replacement}
Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
the system type of the build host.
+@quotation Note
+The @code{--system} flag is for @emph{native} compilation and must not
+be confused with cross-compilation. See @code{--target} below for
+information on cross-compilation.
+@end quotation
+
An example use of this is on Linux-based systems, which can emulate
different personalities. For instance, passing
-@code{--system=i686-linux} on an @code{x86_64-linux} system allows users
+@code{--system=i686-linux} on an @code{x86_64-linux} system allows you
to build packages in a complete 32-bit environment.
+Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
+is enabled (@pxref{Virtualization Services,
+@code{qemu-binfmt-service-type}}), you can build for any system for
+which a QEMU @code{binfmt_misc} handler is installed.
+
+Builds for a system other than that of the machine you are using can
+also be offloaded to a remote machine of the right architecture.
+@xref{Daemon Offload Setup}, for more information on offloading.
+
@item --target=@var{triplet}
@cindex cross-compilation
Cross-build for @var{triplet}, which must be a valid GNU triplet, such
more on GC roots.
@item --log-file
+@cindex build logs, access
Return the build log file names or URLs for the given
@var{package-or-derivation}, or raise an error if build logs are
missing.
functionality requires Guile-JSON to be installed.
@xref{Requirements}.}.
Information is taken from the JSON-formatted metadata provided through
-@uref{https://api.metacpan.org/, MetaCPAN's API} and includes most
+@uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
relevant information, such as module dependencies. License information
should be checked closely. If Perl is available in the store, then the
@code{corelist} utility will be used to filter core modules out of the
@item cran
@cindex CRAN
@cindex Bioconductor
-Import metadata from @uref{http://cran.r-project.org/, CRAN}, the
+Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
central repository for the @uref{http://r-project.org, GNU@tie{}R
statistical and graphical environment}.
@item elpa
the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
@item cran
-the updater for @uref{http://cran.r-project.org/, CRAN} packages;
+the updater for @uref{https://cran.r-project.org/, CRAN} packages;
@item bioconductor
the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
@item cpan
To select other outputs, two element tuples can be specified:
@example
-guix environment --ad-hoc -e '(list (@ (gnu packages bash) bash) "include")'
+guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
@end example
@item --load=@var{file}
Obviously, these URLs only work for files that are in the store; in
other cases, they return 404 (``Not Found'').
+@cindex build logs, publication
+Build logs are available from @code{/log} URLs like:
+
+@example
+http://example.org/log/gwspk@dots{}-guile-2.2.3
+@end example
+
+@noindent
+When @command{guix-daemon} is configured to save compressed build logs,
+as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
+URLs return the compressed log as-is, with an appropriate
+@code{Content-Type} and/or @code{Content-Encoding} header. We recommend
+running @command{guix-daemon} with @code{--log-compression=gzip} since
+Web browsers can automatically decompress it, which is not the case with
+bzip2 compression.
+
The following options are available:
@table @code
An ISO-9660 installation image that can be written to a USB stick or
burnt to a DVD can be downloaded from
-@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz},
+@indicateurl{ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz},
where @var{system} is one of:
@table @code
authenticity of the image against it, along these lines:
@example
-$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.xz.sig
-$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.xz.sig
+$ wget ftp://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig
+$ gpg --verify guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig
@end example
If that command fails because you do not have the required public key,
Decompress the image using the @command{xz} command:
@example
-xz -d guixsd-install-@value{VERSION}.@var{system}.xz
+xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz
@end example
@item
copy the image with:
@example
-dd if=guixsd-install-@value{VERSION}.x86_64-linux of=/dev/sdX
+dd if=guixsd-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX
sync
@end example
Decompress the image using the @command{xz} command:
@example
-xz -d guixsd-install-@value{VERSION}.@var{system}.xz
+xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz
@end example
@item
copy the image with:
@example
-growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.x86_64
+growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.x86_64.iso
@end example
Access to @file{/dev/srX} usually requires root privileges.
@itemize
@item
-Make sure the @code{grub-configuration} form refers to the target you
-want to install GRUB on. It should mention @code{grub-bootloader} if
+Make sure the @code{bootloader-configuration} form refers to the target
+you want to install GRUB on. It should mention @code{grub-bootloader} if
you are installing GRUB in the legacy way, or @code{grub-efi-bootloader}
for newer UEFI systems. For legacy systems, the @code{target} field
names a device, like @code{/dev/sda}; for UEFI systems it names a path
@example
qemu-system-x86_64 -m 1024 -smp 1 \
-net user -net nic,model=virtio -boot menu=on \
- -drive file=guixsd-install-@value{VERSION}.@var{system} \
+ -drive file=guixsd-install-@value{VERSION}.@var{system}.iso \
-drive file=guixsd.img
@end example
@itemx @code{groups} (default: @var{%base-groups})
List of user accounts and groups. @xref{User Accounts}.
+If the @code{users} list lacks a user account with UID@tie{}0, a
+``root'' account with UID@tie{}0 is automatically added.
+
@item @code{skeletons} (default: @code{(default-skeletons)})
A list target file name/file-like object tuples (@pxref{G-Expressions,
file-like objects}). These are the skeleton files that will be added to
respectively, after which a build process times out. A value of zero
disables the timeout.
+@item @code{log-compression} (default: @code{'bzip2})
+The type of compression used for build logs---one of @code{gzip},
+@code{bzip2}, or @code{none}.
+
@item @code{extra-options} (default: @code{'()})
List of extra command-line options for @command{guix-daemon}.
@end example
@end deffn
-@deffn {Scheme Procedure} urandom-seed-service
+@defvr {Scheme Variable} urandom-seed-service-type
Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
-when rebooting.
-@end deffn
+when rebooting. It also tries to seed @file{/dev/urandom} from
+@file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
+readable.
+@end defvr
@defvr {Scheme Variable} %random-seed-file
This is the name of the file where some random bytes are saved by
@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
[#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}]
+ [#:requirement @code{'(udev)}]
Return a service that starts @var{interface} with address @var{ip}. If
@var{netmask} is true, use it as the network mask. If @var{gateway} is true,
-it must be a string specifying the default network gateway.
+it must be a string specifying the default network gateway. @var{requirement}
+can be used to declare a dependency on another service before configuring the
+interface.
This procedure can be called several times, one for each network
interface of interest. Behind the scenes what it does is extend
project's documentation} for more information.
@end deffn
-@deffn {Scheme Procedure} bitlbee-service [#:bitlbee bitlbee] @
- [#:interface "127.0.0.1"] [#:port 6667] @
- [#:extra-settings ""]
-Return a service that runs @url{http://bitlbee.org,BitlBee}, a daemon that
-acts as a gateway between IRC and chat networks.
-
-The daemon will listen to the interface corresponding to the IP address
-specified in @var{interface}, on @var{port}. @code{127.0.0.1} means that only
-local clients can connect, whereas @code{0.0.0.0} means that connections can
-come from any networking interface.
-
-In addition, @var{extra-settings} specifies a string to append to the
-configuration file.
-@end deffn
-
The @code{(gnu services rsync)} module provides the following services:
You might want an rsync daemon if you have files that you want available
usually useful in the context of a ``desktop'' setup---that is, on a
machine running a graphical display server, possibly with graphical user
interfaces, etc. It also defines services that provide specific desktop
-environments like GNOME and XFCE.
+environments like GNOME, XFCE or MATE.
To simplify things, the module defines a variable containing the set of
services that users typically expect on a machine with a graphical
field of an @code{operating-system} declaration (@pxref{operating-system
Reference, @code{services}}).
-Additionally, the @code{gnome-desktop-service} and
-@code{xfce-desktop-service} procedures can add GNOME and/or XFCE to a
-system. To ``add GNOME'' means that system-level services like the
+Additionally, the @code{gnome-desktop-service},
+@code{xfce-desktop-service} and @code{mate-desktop-service}
+procedures can add GNOME, XFCE and/or MATE to a system.
+To ``add GNOME'' means that system-level services like the
backlight adjustment helpers and the power management utilities are
added to the system, extending @code{polkit} and @code{dbus}
appropriately, allowing GNOME to operate with elevated privileges on a
also gives the Thunar file manager the ability to open a ``root-mode''
file management window, if the user authenticates using the
administrator's password via the standard polkit graphical interface.
+To ``add MATE'' means that @code{polkit} and @code{dbus} are extended
+appropriately, allowing MATE to operate with elevated privileges on a
+limited number of special-purpose system interfaces. Additionally,
+adding a service made by @code{mate-desktop-service} adds the MATE
+metapackage to the system profile.
+
+The desktop environments in Guix use the Xorg display server by
+default. If you'd like to use the newer display server protocol
+called Wayland, you need to use the @code{sddm-service} instead of the
+@code{slim-service} for the graphical login manager. You should then
+select the ``GNOME (Wayland)'' session in SDDM. Currently only GNOME
+has support for Wayland.
@deffn {Scheme Procedure} gnome-desktop-service
Return a service that adds the @code{gnome} package to the system
authenticated with the administrator's password.
@end deffn
-Because the GNOME and XFCE desktop services pull in so many packages,
+@deffn {Scheme Procedure} mate-desktop-service
+Return a service that adds the @code{mate} package to the system
+profile, and extends polkit with the actions from
+@code{mate-settings-daemon}.
+@end deffn
+
+Because the GNOME, XFCE and MATE desktop services pull in so many packages,
the default @code{%desktop-services} variable doesn't include either of
-them by default. To add GNOME or XFCE, just @code{cons} them onto
+them by default. To add GNOME, XFCE or MATE, just @code{cons} them onto
@code{%desktop-services} in the @code{services} field of your
@code{operating-system}:
Defaults to @samp{"15 min"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer director-doveadm-port
-TCP/IP port that accepts doveadm connections (instead of director
-connections) If you enable this, you'll also need to add
-@samp{inet-listener} for the port.
-Defaults to @samp{0}.
-@end deftypevr
-
@deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
How the username is translated before being hashed. Useful values
include %Ln if user can log in with or without @@domain, %Ld if mailboxes
@deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
Log prefix for mail processes. See doc/wiki/Variables.txt for list
of possible variables you can use.
-Defaults to @samp{"\"%s(%u): \""}.
+Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
Maximum dbox file size until it's rotated.
-Defaults to @samp{2000000}.
+Defaults to @samp{10000000}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
Defaults to @samp{"commonName"}.
@end deftypevr
-@deftypevr {@code{dovecot-configuration} parameter} hours ssl-parameters-regenerate
-How often to regenerate the SSL parameters file. Generation is
-quite CPU intensive operation. The value is in hours, 0 disables
-regeneration entirely.
-Defaults to @samp{168}.
-@end deftypevr
-
-@deftypevr {@code{dovecot-configuration} parameter} string ssl-protocols
-SSL protocols to use.
-Defaults to @samp{"!SSLv2"}.
+@deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
+Minimum SSL protocol version to accept.
+Defaults to @samp{"TLSv1"}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
SSL ciphers to use.
-Defaults to @samp{"ALL:!LOW:!SSLv2:!EXP:!aNULL"}.
+Defaults to @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
@item %o
total number of bytes sent to client.
@end table
-Defaults to @samp{"in=%i out=%o"}.
+See @file{doc/wiki/Variables.txt} for a list of all the variables you can use.
+Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} body_bytes=%@{fetch_body_bytes@}"}.
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string imap-capability
@subsubheading Prosody Service
@deffn {Scheme Variable} prosody-service-type
-This is the type for the @uref{http://prosody.im, Prosody XMPP
+This is the type for the @uref{https://prosody.im, Prosody XMPP
communication server}. Its value must be a @code{prosody-configuration}
record as in this example:
@deftypevr {@code{prosody-configuration} parameter} file-name data-path
Location of the Prosody data storage directory. See
-@url{http://prosody.im/doc/configure}.
+@url{https://prosody.im/doc/configure}.
Defaults to @samp{"/var/lib/prosody"}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} file-name-list plugin-paths
Additional plugin directories. They are searched in all the specified
-paths in order. See @url{http://prosody.im/doc/plugins_directory}.
+paths in order. See @url{https://prosody.im/doc/plugins_directory}.
Defaults to @samp{()}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} string-list admins
This is a list of accounts that are admins for the server. Note that you
-must create the accounts separately. See @url{http://prosody.im/doc/admins} and
-@url{http://prosody.im/doc/creating_accounts}.
+must create the accounts separately. See @url{https://prosody.im/doc/admins} and
+@url{https://prosody.im/doc/creating_accounts}.
Example: @code{(admins '("user1@@example.com" "user2@@example.net"))}
Defaults to @samp{()}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
Enable use of libevent for better performance under high load. See
-@url{http://prosody.im/doc/libevent}.
+@url{https://prosody.im/doc/libevent}.
Defaults to @samp{#f}.
@end deftypevr
This is the list of modules Prosody will load on startup. It looks for
@code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
Documentation on modules can be found at:
-@url{http://prosody.im/doc/modules}.
+@url{https://prosody.im/doc/modules}.
Defaults to @samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} file-name groups-file
Path to a text file where the shared groups are defined. If this path is
empty then @samp{mod_groups} does nothing. See
-@url{http://prosody.im/doc/modules/mod_groups}.
+@url{https://prosody.im/doc/modules/mod_groups}.
Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
Disable account creation by default, for security. See
-@url{http://prosody.im/doc/creating_accounts}.
+@url{https://prosody.im/doc/creating_accounts}.
Defaults to @samp{#f}.
@end deftypevr
These are the SSL/TLS-related settings. Most of them are disabled so to
use Prosody's defaults. If you do not completely understand these options, do
not add them to your config, it is easy to lower the security of your server
-using them. See @url{http://prosody.im/doc/advanced_ssl_config}.
+using them. See @url{https://prosody.im/doc/advanced_ssl_config}.
Available @code{ssl-configuration} fields are:
@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
Whether to force all client-to-server connections to be encrypted or not.
-See @url{http://prosody.im/doc/modules/mod_tls}.
+See @url{https://prosody.im/doc/modules/mod_tls}.
Defaults to @samp{#f}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
Whether to force all server-to-server connections to be encrypted or not.
-See @url{http://prosody.im/doc/modules/mod_tls}.
+See @url{https://prosody.im/doc/modules/mod_tls}.
Defaults to @samp{#f}.
@end deftypevr
Whether to require encryption and certificate authentication. This
provides ideal security, but requires servers you communicate with to support
encryption AND present valid, trusted certificates. See
-@url{http://prosody.im/doc/s2s#security}.
+@url{https://prosody.im/doc/s2s#security}.
Defaults to @samp{#f}.
@end deftypevr
Many servers don't support encryption or have invalid or self-signed
certificates. You can list domains here that will not be required to
authenticate using certificates. They will be authenticated using DNS. See
-@url{http://prosody.im/doc/s2s#security}.
+@url{https://prosody.im/doc/s2s#security}.
Defaults to @samp{()}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
Even if you leave @code{s2s-secure-auth?} disabled, you can still require
valid certificates for some domains by specifying a list here. See
-@url{http://prosody.im/doc/s2s#security}.
+@url{https://prosody.im/doc/s2s#security}.
Defaults to @samp{()}.
@end deftypevr
Select the authentication backend to use. The default provider stores
passwords in plaintext and uses Prosody's configured data storage to store the
authentication data. If you do not trust your server please see
-@url{http://prosody.im/doc/modules/mod_auth_internal_hashed} for information
+@url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for information
about using the hashed backend. See also
-@url{http://prosody.im/doc/authentication}
+@url{https://prosody.im/doc/authentication}
Defaults to @samp{"internal_plain"}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} maybe-string log
Set logging options. Advanced logging configuration is not yet supported
-by the GuixSD Prosody Service. See @url{http://prosody.im/doc/logging}.
+by the GuixSD Prosody Service. See @url{https://prosody.im/doc/logging}.
Defaults to @samp{"*syslog"}.
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} file-name pidfile
-File to write pid in. See @url{http://prosody.im/doc/modules/mod_posix}.
+File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}.
Defaults to @samp{"/var/run/prosody/prosody.pid"}.
@end deftypevr
Prosody's configuration. Conversely a server that hosts a single domain would
have just one VirtualHost entry.
-See @url{http://prosody.im/doc/configure#virtual_host_settings}.
+See @url{https://prosody.im/doc/configure#virtual_host_settings}.
Available @code{virtualhost-configuration} fields are:
internal component, you simply fill the hostname field, and the plugin you wish
to use for the component.
-See @url{http://prosody.im/doc/components}.
+See @url{https://prosody.im/doc/components}.
Defaults to @samp{()}.
Available @code{int-component-configuration} fields are:
hosted chatrooms/conferences for XMPP users.
General information on setting up and using multi-user chatrooms can be found
-in the "Chatrooms" documentation (@url{http://prosody.im/doc/chatrooms}),
+in the "Chatrooms" documentation (@url{https://prosody.im/doc/chatrooms}),
which you should read if you are new to XMPP chatrooms.
-See also @url{http://prosody.im/doc/modules/mod_muc}.
+See also @url{https://prosody.im/doc/modules/mod_muc}.
Available @code{mod-muc-configuration} fields are:
@deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
External components use XEP-0114, which most standalone components
support. To add an external component, you simply fill the hostname field. See
-@url{http://prosody.im/doc/components}.
+@url{https://prosody.im/doc/components}.
Defaults to @samp{()}.
Available @code{ext-component-configuration} fields are:
(prosody.cfg.lua "")))
@end example
+@subsubheading BitlBee Service
+
+@cindex IRC (Internet Relay Chat)
+@cindex IRC gateway
+@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC
+interface to a variety of messaging protocols such as XMPP.
+
+@defvr {Scheme Variable} bitlbee-service-type
+This is the service type for the @url{http://bitlbee.org,BitlBee} IRC
+gateway daemon. Its value is a @code{bitlbee-configuration} (see
+below).
+
+To have BitlBee listen on port 6667 on localhost, add this line to your
+services:
+
+@example
+(service bitlbee-service-type)
+@end example
+@end defvr
+
+@deftp {Data Type} bitlbee-configuration
+This is the configuration for BitlBee, with the following fields:
+
+@table @asis
+@item @code{interface} (default: @code{"127.0.0.1"})
+@itemx @code{port} (default: @code{6667})
+Listen on the network interface corresponding to the IP address
+specified in @var{interface}, on @var{port}.
+
+When @var{interface} is @code{127.0.0.1}, only local clients can
+connect; when it is @code{0.0.0.0}, connections can come from any
+networking interface.
+
+@item @code{package} (default: @code{bitlbee})
+The BitlBee package to use.
+
+@item @code{extra-settings} (default: @code{""})
+Configuration snippet added as-is to the BitlBee configuration file.
+@end table
+@end deftp
+
@node Telephony Services
@subsubsection Telephony Services
@end deftp
+@subsubheading Darkstat Service
+@cindex darkstat
+Darkstat is a packet sniffer that captures network traffic, calculates
+statistics about usage, and serves reports over HTTP.
+
+@defvar {Scheme Variable} darkstat-service-type
+This is the service type for the
+@uref{https://unix4lyfe.org/darkstat/, darkstat}
+service, its value must be a @code{darkstat-configuration} record as in
+this example:
+
+@example
+(service darkstat-service-type
+ (darkstat-configuration
+ (interface "eno1")))
+@end example
+@end defvar
+
+@deftp {Data Type} darkstat-configuration
+Data type representing the configuration of @command{darkstat}.
+
+@table @asis
+@item @code{package} (default: @code{darkstat})
+The darkstat package to use.
+
+@item @code{interface}
+Capture traffic on the specified network interface.
+
+@item @code{port} (default: @code{"667"})
+Bind the web interface to the specified port.
+
+@item @code{bind-address} (default: @code{"127.0.0.1"})
+Bind the web interface to the specified address.
+
+@item @code{base} (default: @code{"/"})
+Specify the path of the base URL. This can be useful if
+@command{darkstat} is accessed via a reverse proxy.
+
+@end table
+@end deftp
+
+
@node Kerberos Services
@subsubsection Kerberos Services
@cindex Kerberos
@cindex web
@cindex www
@cindex HTTP
-The @code{(gnu services web)} module provides the nginx web server and
-also a fastcgi wrapper daemon.
+The @code{(gnu services web)} module provides the Apache HTTP Server,
+the nginx web server, and also a fastcgi wrapper daemon.
+
+@subsubheading Apache HTTP Server
+
+@deffn {Scheme Variable} httpd-service-type
+Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
+(@dfn{httpd}). The value for this service type is a
+@code{https-configuration} record.
+
+A simple example configuration is given below.
+
+@example
+(service httpd-service-type
+ (httpd-configuration
+ (config
+ (httpd-config-file
+ (server-name "www.example.com")
+ (document-root "/srv/http/www.example.com")))))
+@end example
+
+Other services can also extend the @code{httpd-service-type} to add to
+the configuration.
+
+@example
+(simple-service 'my-extra-server httpd-service-type
+ (list
+ (httpd-virtualhost
+ "*:80"
+ (list (string-append
+ "ServerName "www.example.com
+ DocumentRoot \"/srv/http/www.example.com\"")))))
+@end example
+@end deffn
+
+The details for the @code{httpd-configuration}, @code{httpd-module},
+@code{httpd-config-file} and @code{httpd-virtualhost} record types are
+given below.
+
+@deffn {Data Type} httpd-configuration
+This data type represents the configuration for the httpd service.
+
+@table @asis
+@item @code{package} (default: @code{httpd})
+The httpd package to use.
+
+@item @code{pid-file} (default: @code{"/var/run/httpd"})
+The pid file used by the shepherd-service.
+
+@item @code{config} (default: @code{(httpd-config-file)})
+The configuration file to use with the httpd service. The default value
+is a @code{httpd-config-file} record, but this can also be a different
+G-expression that generates a file, for example a @code{plain-file}. A
+file outside of the store can also be specified through a string.
+
+@end table
+@end deffn
+
+@deffn {Data Type} httpd-module
+This data type represents a module for the httpd service.
+
+@table @asis
+@item @code{name}
+The name of the module.
+
+@item @code{file}
+The file for the module. This can be relative to the httpd package being
+used, the absolute location of a file, or a G-expression for a file
+within the store, for example @code{(file-append mod-wsgi
+"/modules/mod_wsgi.so")}.
+
+@end table
+@end deffn
+
+@deffn {Data Type} httpd-config-file
+This data type represents a configuration file for the httpd service.
+
+@table @asis
+@item @code{modules} (default: @code{%default-httpd-modules})
+The modules to load. Additional modules can be added here, or loaded by
+additional configuration.
+
+@item @code{server-root} (default: @code{httpd})
+The @code{ServerRoot} in the configuration file, defaults to the httpd
+package. Directives including @code{Include} and @code{LoadModule} are
+taken as relative to the server root.
+
+@item @code{server-name} (default: @code{#f})
+The @code{ServerName} in the configuration file, used to specify the
+request scheme, hostname and port that the server uses to identify
+itself.
+
+This doesn't need to be set in the server config, and can be specifyed
+in virtual hosts. The default is @code{#f} to not specify a
+@code{ServerName}.
+
+@item @code{document-root} (default: @code{"/srv/http"})
+The @code{DocumentRoot} from which files will be served.
+
+@item @code{listen} (default: @code{'("80")})
+The list of values for the @code{Listen} directives in the config
+file. The value should be a list of strings, when each string can
+specify the port number to listen on, and optionally the IP address and
+protocol to use.
+
+@item @code{pid-file} (default: @code{"/var/run/httpd"})
+The @code{PidFile} to use. This should match the @code{pid-file} set in
+the @code{httpd-configuration} so that the Shepherd service is
+configured correctly.
+
+@item @code{error-log} (default: @code{"/var/log/httpd/error_log"})
+The @code{ErrorLog} to which the server will log errors.
+
+@item @code{user} (default: @code{"httpd"})
+The @code{User} which the server will answer requests as.
+
+@item @code{group} (default: @code{"httpd"})
+The @code{Group} which the server will answer requests as.
+
+@item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")})
+A flat list of strings and G-expressions which will be added to the end
+of the configuration file.
+
+Any values which the service is extended with will be appended to this
+list.
+
+@end table
+@end deffn
+
+@deffn {Data Type} httpd-virtualhost
+This data type represents a virtualhost configuration block for the httpd service.
+
+These should be added to the extra-config for the httpd-service.
+
+@example
+(simple-service 'my-extra-server httpd-service-type
+ (list
+ (httpd-virtualhost
+ "*:80"
+ (list (string-append
+ "ServerName "www.example.com
+ DocumentRoot \"/srv/http/www.example.com\"")))))
+@end example
+
+@table @asis
+@item @code{addresses-and-ports}
+The addresses and ports for the @code{VirtualHost} directive.
+
+@item @code{contents}
+The contents of the @code{VirtualHost} directive, this should be a list
+of strings and G-expressions.
+
+@end table
+@end deffn
+
+@subsubheading NGINX
@deffn {Scheme Variable} nginx-service-type
Service type for the @uref{https://nginx.org/,NGinx} web server. The
(server-blocks
(list (nginx-server-configuration
(server-name '("www.example.com"))
- (root "/srv/http/www.example.com")
- (https-port #f)
- (ssl-certificate #f)
- (ssl-certificate-key #f))))))
+ (root "/srv/http/www.example.com"))))))
@end example
In addition to adding server blocks to the service configuration
@example
(simple-service 'my-extra-server nginx-service-type
(list (nginx-server-configuration
- (https-port #f)
- (ssl-certificate #f)
- (ssl-certificate-key #f)
(root "/srv/http/extra-website")
(try-files (list "$uri" "$uri/index.html")))))
@end example
(server-blocks
(list (nginx-server-configuration
(server-name '("www.example.com"))
- (root "/srv/http/www.example.com")
- (https-port #f)
- (ssl-certificate #f)
- (ssl-certificate-key #f))))))
+ (root "/srv/http/www.example.com"))))))
@end example
@item @code{upstream-blocks} (default: @code{'()})
(list (nginx-server-configuration
(server-name '("www.example.com"))
(root "/srv/http/www.example.com")
- (https-port #f)
- (ssl-certificate #f)
- (ssl-certificate-key #f)
(locations
(list
(nginx-location-configuration
not possible to do what is required through the other parts of the
nginx-configuration record.
+@item @code{server-names-hash-bucket-size} (default: @code{#f})
+Bucket size for the server names hash tables, defaults to @code{#f} to
+use the size of the processors cache line.
+
+@item @code{server-names-hash-bucket-max-size} (default: @code{#f})
+Maximum bucket size for the server names hash tables.
+
@end table
@end deffn
This type has the following parameters:
@table @asis
-@item @code{http-port} (default: @code{80})
-Nginx will listen for HTTP connection on this port. Set it at @code{#f} if
-nginx should not listen for HTTP (non secure) connection for this
-@dfn{server block}.
-
-@item @code{https-port} (default: @code{443})
-Nginx will listen for HTTPS connection on this port. Set it at @code{#f} if
-nginx should not listen for HTTPS (secure) connection for this @dfn{server block}.
+@item @code{listen} (default: @code{'("80" "443 ssl")})
+Each @code{listen} directive sets the address and port for IP, or the
+path for a UNIX-domain socket on which the server will accept requests.
+Both address and port, or only address or only port can be specified.
+An address may also be a hostname, for example:
-Note that nginx can listen for HTTP and HTTPS connections in the same
-@dfn{server block}.
+@example
+'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")
+@end example
@item @code{server-name} (default: @code{(list 'default)})
A list of server names this server represents. @code{'default} represents the
A list of files whose existence is checked in the specified order.
@code{nginx} will use the first file it finds to process the request.
-@item @code{ssl-certificate} (default: @code{"/etc/nginx/cert.pem"})
+@item @code{ssl-certificate} (default: @code{#f})
Where to find the certificate for secure connections. Set it to @code{#f} if
you don't have a certificate or you don't want to use HTTPS.
-@item @code{ssl-certificate-key} (default: @code{"/etc/nginx/key.pem"})
+@item @code{ssl-certificate-key} (default: @code{#f})
Where to find the private key for secure connections. Set it to @code{#f} if
you don't have a key or you don't want to use HTTPS.
@item @code{server-tokens?} (default: @code{#f})
Whether the server should add its configuration to response.
+@item @code{raw-content} (default: @code{'()})
+A list of raw lines added to the server block.
+
@end table
@end deftp
@anchor{nginx-location-configuration body}
@item @code{body}
-Body of the location block, specified as a string. This can contain many
+Body of the location block, specified as a list of strings. This can contain
+many
configuration directives. For example, to pass requests to a upstream
server group defined using an @code{nginx-upstream-configuration} block,
-the following directive would be specified in the body @samp{proxy_pass
-http://upstream-name;}.
+the following directive would be specified in the body @samp{(list "proxy_pass
+http://upstream-name;")}.
@end table
@end deftp
@end table
@end deftp
+@cindex php-fpm
+PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation
+with some additional features useful for sites of any size.
+
+These features include:
+@itemize @bullet
+@item Adaptive process spawning
+@item Basic statistics (similar to Apache's mod_status)
+@item Advanced process management with graceful stop/start
+@item Ability to start workers with different uid/gid/chroot/environment
+and different php.ini (replaces safe_mode)
+@item Stdout & stderr logging
+@item Emergency restart in case of accidental opcode cache destruction
+@item Accelerated upload support
+@item Support for a "slowlog"
+@item Enhancements to FastCGI, such as fastcgi_finish_request() -
+a special function to finish request & flush all data while continuing to do
+something time-consuming (video converting, stats processing, etc.)
+@end itemize
+... and much more.
+
+@defvr {Scheme Variable} php-fpm-service-type
+A Service type for @code{php-fpm}.
+@end defvr
+
+@deftp {Data Type} php-fpm-configuration
+Data Type for php-fpm service configuration.
+@table @asis
+@item @code{php} (default: @code{php})
+The php package to use.
+@item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")})
+The address on which to accept FastCGI requests. Valid syntaxes are:
+@table @asis
+@item @code{"ip.add.re.ss:port"}
+Listen on a TCP socket to a specific address on a specific port.
+@item @code{"port"}
+Listen on a TCP socket to all addresses on a specific port.
+@item @code{"/path/to/unix/socket"}
+Listen on a unix socket.
+@end table
+
+@item @code{user} (default: @code{php-fpm})
+User who will own the php worker processes.
+@item @code{group} (default: @code{php-fpm})
+Group of the worker processes.
+@item @code{socket-user} (default: @code{php-fpm})
+User who can speak to the php-fpm socket.
+@item @code{socket-group} (default: @code{php-fpm})
+Group that can speak to the php-fpm socket.
+@item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
+The process id of the php-fpm process is written to this file
+once the service has started.
+@item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")})
+Log for the php-fpm master process.
+@item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
+Detailed settings for the php-fpm process manager.
+Must be either:
+@table @asis
+@item @code{<php-fpm-dynamic-process-manager-configuration>}
+@item @code{<php-fpm-static-process-manager-configuration>}
+@item @code{<php-fpm-on-demand-process-manager-configuration>}
+@end table
+@item @code{display-errors} (default @code{#f})
+Determines wether php errors and warning should be sent to clients
+and displayed in their browsers.
+This is useful for local php development, but a security risk for public sites,
+as error messages can reveal passwords and personal data.
+@item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")})
+This file will log the @code{stderr} outputs of php worker processes.
+Can be set to @code{#f} to disable logging.
+@item @code{file} (default @code{#f})
+An optional override of the whole configuration.
+You can use the @code{mixed-text-file} function or an absolute filepath for it.
+@end table
+@end deftp
+
+@deftp {Data type} php-fpm-dynamic-process-manager-configuration
+Data Type for the @code{dynamic} php-fpm process manager. With the
+@code{dynamic} process manager, spare worker processes are kept around
+based on it's configured limits.
+@table @asis
+@item @code{max-children} (default: @code{5})
+Maximum of worker processes.
+@item @code{start-servers} (default: @code{2})
+How many worker processes should be started on start-up.
+@item @code{min-spare-servers} (default: @code{1})
+How many spare worker processes should be kept around at minimum.
+@item @code{max-spare-servers} (default: @code{3})
+How many spare worker processes should be kept around at maximum.
+@end table
+@end deftp
+
+@deftp {Data type} php-fpm-static-process-manager-configuration
+Data Type for the @code{static} php-fpm process manager. With the
+@code{static} process manager, an unchanging number of worker processes
+are created.
+@table @asis
+@item @code{max-children} (default: @code{5})
+Maximum of worker processes.
+@end table
+@end deftp
+
+@deftp {Data type} php-fpm-on-demand-process-manager-configuration
+Data Type for the @code{on-demand} php-fpm process manager. With the
+@code{on-demand} process manager, worker processes are only created as
+requests arrive.
+@table @asis
+@item @code{max-children} (default: @code{5})
+Maximum of worker processes.
+@item @code{process-idle-timeout} (default: @code{10})
+The time in seconds after which a process with no requests is killed.
+@end table
+@end deftp
+
+
+@deffn {Scheme Procedure} nginx-php-fpm-location @
+ [#:nginx-package nginx] @
+ [socket (string-append "/var/run/php" @
+ (version-major (package-version php)) @
+ "-fpm.sock")]
+A helper function to quickly add php to an @code{nginx-server-configuration}.
+@end deffn
+
+A simple services setup for nginx with php can look like this:
+@example
+(services (cons* (dhcp-client-service)
+ (service php-fpm-service-type)
+ (service nginx-service-type
+ (nginx-server-configuration
+ (server-name '("example.com"))
+ (root "/srv/http/")
+ (locations
+ (list (nginx-php-location)))
+ (https-port #f)
+ (ssl-certificate #f)
+ (ssl-certificate-key #f)))
+ %base-services))
+@end example
+
@node Certificate Services
@subsubsection Certificate Services
(operating-system
;; ...
(services (cons* (service knot-service-type
- (knot-confifguration
+ (knot-configuration
(remotes (list plop-master))
(zones (list master-zone slave-zone))))
;; ...
@item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
The configuration string of the backend. An example for the PKCS#11 is:
@code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
-For the pem backend, the string reprensents a path in the filesystem.
+For the pem backend, the string reprensents a path in the file system.
@end table
@end deftp
@node Virtualization Services
@subsubsection Virtualization services
+
The @code{(gnu services virtualization)} module provides services for
-the libvirt and virtlog daemons.
+the libvirt and virtlog daemons, as well as other virtualization-related
+services.
@subsubheading Libvirt daemon
@code{libvirtd} is the server side daemon component of the libvirt
@end deftypevr
+@subsubheading Transparent Emulation with QEMU
+
+@cindex emulation
+@cindex @code{binfmt_misc}
+@code{qemu-binfmt-service-type} provides support for transparent
+emulation of program binaries built for different architectures---e.g.,
+it allows you to transparently execute an ARMv7 program on an x86_64
+machine. It achieves this by combining the @uref{https://www.qemu.org,
+QEMU} emulator and the @code{binfmt_misc} feature of the kernel Linux.
+
+@defvr {Scheme Variable} qemu-binfmt-service-type
+This is the type of the QEMU/binfmt service for transparent emulation.
+Its value must be a @code{qemu-binfmt-configuration} object, which
+specifies the QEMU package to use as well as the architecture we want to
+emulated:
+
+@example
+(service qemu-binfmt-service-type
+ (qemu-binfmt-configuration
+ (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc"))))
+@end example
+
+In this example, we enable transparent emulation for the ARM and aarch64
+platforms. Running @code{herd stop qemu-binfmt} turns it off, and
+running @code{herd start qemu-binfmt} turns it back on (@pxref{Invoking
+herd, the @command{herd} command,, shepherd, The GNU Shepherd Manual}).
+@end defvr
+
+@deftp {Data Type} qemu-binfmt-configuration
+This is the configuration for the @code{qemu-binfmt} service.
+
+@table @asis
+@item @code{platforms} (default: @code{'()})
+The list of emulated QEMU platforms. Each item must be a @dfn{platform
+object} as returned by @code{lookup-qemu-platforms} (see below).
+
+@item @code{guix-support?} (default: @code{#f})
+When it is true, QEMU and all its dependencies are added to the build
+environment of @command{guix-daemon} (@pxref{Invoking guix-daemon,
+@code{--chroot-directory} option}). This allows the @code{binfmt_misc}
+handlers to be used within the build environment, which in turn means
+that you can transparently build programs for another architecture.
+
+For example, let's suppose you're on an x86_64 machine and you have this
+service:
+
+@example
+(service qemu-binfmt-service-type
+ (qemu-binfmt-configuration
+ (platforms (lookup-qemu-platforms "arm"))
+ (guix-support? #t)))
+@end example
+
+You can run:
+
+@example
+guix build -s armhf-linux inkscape
+@end example
+
+@noindent
+and it will build Inkscape for ARMv7 @emph{as if it were a native
+build}, transparently using QEMU to emulate the ARMv7 CPU. Pretty handy
+if you'd like to test a package build for an architecture you don't have
+access to!
+
+@item @code{qemu} (default: @code{qemu})
+The QEMU package to use.
+@end table
+@end deftp
+
+@deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{}
+Return the list of QEMU platform objects corresponding to
+@var{platforms}@dots{}. @var{platforms} must be a list of strings
+corresponding to platform names, such as @code{"arm"}, @code{"sparc"},
+@code{"mips64el"}, and so on.
+@end deffn
+
+@deffn {Scheme Procedure} qemu-platform? @var{obj}
+Return true if @var{obj} is a platform object.
+@end deffn
+
+@deffn {Scheme Procedure} qemu-platform-name @var{platform}
+Return the name of @var{platform}---a string such as @code{"arm"}.
+@end deffn
@node Version Control Services
@subsubsection Version Control Services
(server-blocks
(list
(nginx-server-configuration
- (http-port #f)
+ (listen '("443 ssl"))
(server-name "git.my-host.org")
(ssl-certificate
"/etc/letsencrypt/live/git.my-host.org/fullchain.pem")
A possibly empty list of @code{menu-entry} objects (see below), denoting
entries to appear in the bootloader menu, in addition to the current
system entry and the entry pointing to previous system generations.
-generations.
@item @code{default-entry} (default: @code{0})
The index of the default boot menu entry. Index 0 is for the entry of the
following:
@table @option
+@item --expression=@var{expr}
+@itemx -e @var{expr}
+Consider the operating-system @var{expr} evaluates to.
+This is an alternative to specifying a file which evaluates to an
+operating system.
+This is used to generate the GuixSD installer @pxref{Building the
+Installation Image}).
+
@item --system=@var{system}
@itemx -s @var{system}
Attempt to build for @var{system} instead of the host system type.
HCoop / jackhill / guix / guix.git / blobdiff