diff options
Diffstat (limited to 'doc/guix.zh_CN.texi')
| -rw-r--r-- | doc/guix.zh_CN.texi | 25352 |
1 files changed, 0 insertions, 25352 deletions
diff --git a/doc/guix.zh_CN.texi b/doc/guix.zh_CN.texi deleted file mode 100644 index 993220fdc0..0000000000 --- a/doc/guix.zh_CN.texi +++ /dev/null @@ -1,25352 +0,0 @@ -\input texinfo -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c -*-texinfo-*- - -@c %**start of header -@setfilename guix.zh_CN.info -@documentencoding UTF-8 -@settitle GNU Guix参考手册 -@c %**end of header - -@include version-zh_CN.texi - -@c Identifier of the OpenPGP key used to sign tarballs and such. -@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 -@set KEY-SERVER pool.sks-keyservers.net - -@c The official substitute server used by default. -@set SUBSTITUTE-SERVER ci.guix.zh_CN.info - -@copying -Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 -Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* -Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, -2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* -Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} -2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017 -Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo -Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} -2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018, -2019 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* -Copyright @copyright{} 2016, 2017 ng0@* Copyright @copyright{} 2016, 2017, -2018, 2019 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* -Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, -2017, 2018, 2019 Christopher Baines@* Copyright @copyright{} 2017, 2018 -Clément Lassieur@* Copyright @copyright{} 2017, 2018 Mathieu Othacehe@* -Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, -2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* -Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017 -Christopher Allan Webber@* Copyright @copyright{} 2017, 2018 Marius Bakke@* -Copyright @copyright{} 2017 Hartmut Goebel@* Copyright @copyright{} 2017 -Maxim Cournoyer@* Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@* -Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 -Andy Wingo@* Copyright @copyright{} 2017, 2018, 2019 Arun Isaac@* Copyright -@copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@* -Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike -Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright -@copyright{} 2018 Gábor Boskovits@* Copyright @copyright{} 2018 Florian -Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{} -2018 Alex Vong@* - -Permission is granted to copy, distribute and/or modify this document under -the terms of the GNU Free Documentation License, Version 1.3 or any later -version published by the Free Software Foundation; with no Invariant -Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the -license is included in the section entitled ``GNU Free Documentation -License''. -@end copying - -@dircategory System administration -@direntry -* Guix: (guix). Manage installed software and system - configuration. -* guix package: (guix)Invoking guix package. Installing, removing, and - upgrading 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. -@end direntry - -@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 -@title GNU Guix参考手册 -@subtitle Using the GNU Guix Functional Package Manager -@author The GNU Guix Developers - -@page -@vskip 0pt plus 1filll -Edition @value{EDITION} @* @value{UPDATED} @* - -@insertcopying -@end titlepage - -@contents - -@c ********************************************************************* -@node Top -@top GNU Guix - -This document describes GNU Guix version @value{VERSION}, a functional -package management tool written for the GNU system. - -@c TRANSLATORS: You can replace the following paragraph with information on -@c how to join your own translation team and how to report issues with the -@c translation. -This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de -référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch -zu GNU Guix}). If you would like to translate it in your native language, -consider joining the -@uref{https://translationproject.org/domain/guix-manual.html, Translation -Project}. - -@menu -* Introduction:: What is Guix about? -* Installation:: Installing Guix. -* System Installation:: Installing the whole operating system. -* Package Management:: Package installation, upgrade, etc. -* Development:: Guix-aided software development. -* Programming Interface:: Using Guix in Scheme. -* Utilities:: Package management commands. -* System Configuration:: Configuring the operating system. -* Documentation:: Browsing software user manuals. -* Installing Debugging Files:: Feeding the debugger. -* Security Updates:: Deploying security fixes quickly. -* Bootstrapping:: GNU/Linux built from scratch. -* Porting:: Targeting another platform or kernel. -* 贡献:: Your help needed! - -* Acknowledgments:: Thanks! -* GNU Free Documentation License:: The license of this manual. -* Concept Index:: Concepts. -* Programming Index:: Data types, functions, and variables. - -@detailmenu - --- The Detailed Node Listing --- - - - -Introduction - - - -* Managing Software the Guix Way:: What's special. -* GNU Distribution:: The packages and tools. - -Installation - - - -* Binary Installation:: Getting Guix running in no time! -* Requirements:: Software needed to build and run Guix. -* Running the Test Suite:: Testing Guix. -* Setting Up the Daemon:: Preparing the build daemon's environment. -* Invoking guix-daemon:: Running the build daemon. -* Application Setup:: Application-specific setup. - -Setting Up the Daemon - - - -* Build Environment Setup:: Preparing the isolated build environment. -* Daemon Offload Setup:: Offloading builds to remote machines. -* SELinux Support:: Using an SELinux policy for the daemon. - -System Installation - - - -* Limitations:: What you can expect. -* Hardware Considerations:: Supported hardware. -* USB Stick and DVD Installation:: Preparing the installation medium. -* Preparing for Installation:: Networking, partitioning, etc. -* Guided Graphical Installation:: Easy graphical installation. -* Manual Installation:: Manual installation for wizards. -* After System Installation:: When installation succeeded. -* Installing Guix in a VM:: Guix System playground. -* Building the Installation Image:: How this comes to be. - -Manual Installation - - - -* Keyboard Layout and Networking and Partitioning:: Initial setup. -* Proceeding with the Installation:: Installing. - -Package Management - - - -* Features:: How Guix will make your life brighter. -* Invoking guix package:: Package installation, removal, etc. -* Substitutes:: Downloading pre-built binaries. -* 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. -* Channels:: Customizing the package collection. -* Inferiors:: Interacting with another revision of Guix. -* Invoking guix describe:: Display information about your Guix revision. -* Invoking guix archive:: Exporting and importing store files. - -Substitutes - - - -* Official Substitute Server:: One particular source of substitutes. -* Substitute Server Authorization:: How to enable or disable substitutes. -* Substitute Authentication:: How Guix verifies substitutes. -* Proxy Settings:: How to get substitutes via proxy. -* Substitution Failure:: What happens when substitution fails. -* On Trusting Binaries:: How can you trust that binary blob? - -Development - - - -* Invoking guix environment:: Setting up development environments. -* Invoking guix pack:: Creating software bundles. - -Programming Interface - - - -* Package Modules:: Packages from the programmer's viewpoint. -* Defining Packages:: Defining new packages. -* Build Systems:: Specifying how packages are built. -* The Store:: Manipulating the package store. -* Derivations:: Low-level interface to package derivations. -* The Store Monad:: Purely functional interface to the store. -* G-Expressions:: Manipulating build expressions. -* Invoking guix repl:: Fiddling with Guix interactively. - -Defining Packages - - - -* package Reference:: The package data type. -* origin Reference:: The origin data type. - -Utilities - - - -* Invoking guix build:: Building packages from the command line. -* Invoking guix edit:: Editing package definitions. -* Invoking guix download:: Downloading a file and printing its hash. -* Invoking guix hash:: Computing the cryptographic hash of a file. -* Invoking guix import:: Importing package definitions. -* Invoking guix refresh:: Updating package definitions. -* Invoking guix lint:: Finding errors in package definitions. -* Invoking guix size:: Profiling disk usage. -* Invoking guix graph:: Visualizing the graph of packages. -* Invoking guix publish:: Sharing substitutes. -* Invoking guix challenge:: Challenging substitute servers. -* Invoking guix copy:: Copying to and from a remote store. -* Invoking guix container:: Process isolation. -* Invoking guix weather:: Assessing substitute availability. -* Invoking guix processes:: Listing client processes. - -Invoking @command{guix build} - - - -* 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. - -System Configuration - - - -* Using the Configuration System:: Customizing your GNU system. -* operating-system Reference:: Detail of operating-system declarations. -* File Systems:: Configuring file system mounts. -* Mapped Devices:: Block device extra processing. -* User Accounts:: Specifying user accounts. -* Keyboard Layout:: How the system interprets key strokes. -* Locales:: Language and cultural convention settings. -* Services:: Specifying system services. -* Setuid Programs:: Programs running with root privileges. -* X.509 Certificates:: Authenticating HTTPS servers. -* Name Service Switch:: Configuring libc's name service switch. -* Initial RAM Disk:: Linux-Libre bootstrapping. -* Bootloader Configuration:: Configuring the boot loader. -* Invoking guix system:: Instantiating a system configuration. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* Defining Services:: Adding new service definitions. - -Services - - - -* Base Services:: Essential system services. -* Scheduled Job Execution:: The mcron service. -* Log Rotation:: The rottlog service. -* Networking Services:: Network setup, SSH daemon, etc. -* X Window:: Graphical display. -* Printing Services:: Local and remote printer support. -* Desktop Services:: D-Bus and desktop services. -* Sound Services:: ALSA and Pulseaudio services. -* Database Services:: SQL databases, key-value stores, etc. -* Mail Services:: IMAP, POP3, SMTP, and all that. -* Messaging Services:: Messaging services. -* Telephony Services:: Telephony services. -* Monitoring Services:: Monitoring services. -* Kerberos Services:: Kerberos services. -* Web Services:: Web servers. -* Certificate Services:: TLS certificates via Let's Encrypt. -* DNS Services:: DNS daemons. -* VPN Services:: VPN daemons. -* Network File System:: NFS related services. -* Continuous Integration:: The Cuirass service. -* Power Management Services:: Extending battery life. -* Audio Services:: The MPD. -* Virtualization Services:: Virtualization services. -* Version Control Services:: Providing remote access to Git repositories. -* Game Services:: Game servers. -* Miscellaneous Services:: Other services. - -Defining Services - - - -* Service Composition:: The model for composing services. -* Service Types and Services:: Types and services. -* Service Reference:: API reference. -* Shepherd Services:: A particular type of service. - -@end detailmenu -@end menu - -@c ********************************************************************* -@node Introduction -@chapter Introduction - -@cindex purpose -GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' using -the international phonetic alphabet (IPA).} is a package management tool for -and distribution of the GNU system. Guix makes it easy for unprivileged -users to install, upgrade, or remove software packages, to roll back to a -previous package set, to build packages from source, and generally assists -with the creation and maintenance of software environments. - -@cindex Guix System -@cindex GuixSD, now Guix System -@cindex Guix System Distribution, now Guix System -You can install GNU@tie{}Guix on top of an existing GNU/Linux system where -it complements the available tools without interference -(@pxref{Installation}), or you can use it as a standalone operating system -distribution, @dfn{Guix@tie{}System}@footnote{We used to refer to Guix -System as ``Guix System Distribution'' or ``GuixSD''. We now consider it -makes more sense to group everything under the ``Guix'' banner since, after -all, Guix System is readily available through the @command{guix system} -command, even if you're using a different distro underneath!}. @xref{GNU -Distribution}. - -@menu -* Managing Software the Guix Way:: What's special. -* GNU Distribution:: The packages and tools. -@end menu - -@node Managing Software the Guix Way -@section Managing Software the Guix Way - -@cindex user interfaces -Guix provides a command-line package management interface (@pxref{Package -Management}), tools to help with software development (@pxref{Development}), -command-line utilities for more advanced usage, (@pxref{Utilities}), as well -as Scheme programming interfaces (@pxref{Programming Interface}). -@cindex build daemon -Its @dfn{build daemon} is responsible for building packages on behalf of -users (@pxref{Setting Up the Daemon}) and for downloading pre-built binaries -from authorized sources (@pxref{Substitutes}). - -@cindex extensibility of the distribution -@cindex customization, of packages -Guix includes package definitions for many GNU and non-GNU packages, all of -which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the user's -computing freedom}. It is @emph{extensible}: users can write their own -package definitions (@pxref{Defining Packages}) and make them available as -independent package modules (@pxref{Package Modules}). It is also -@emph{customizable}: users can @emph{derive} specialized package definitions -from existing ones, including from the command line (@pxref{Package -Transformation Options}). - -@cindex functional package management -@cindex isolation -Under the hood, Guix implements the @dfn{functional package management} -discipline pioneered by Nix (@pxref{Acknowledgments}). In Guix, the package -build and installation process is seen as a @emph{function}, in the -mathematical sense. That function takes inputs, such as build scripts, a -compiler, and libraries, and returns an installed package. As a pure -function, its result depends solely on its inputs---for instance, it cannot -refer to software or scripts that were not explicitly passed as inputs. A -build function always produces the same result when passed a given set of -inputs. It cannot alter the environment of the running system in any way; -for instance, it cannot create, modify, or delete files outside of its build -and installation directories. This is achieved by running build processes -in isolated environments (or @dfn{containers}), where only their explicit -inputs are visible. - -@cindex store -The result of package build functions is @dfn{cached} in the file system, in -a special directory called @dfn{the store} (@pxref{The Store}). Each -package is installed in a directory of its own in the store---by default -under @file{/gnu/store}. The directory name contains a hash of all the -inputs used to build that package; thus, changing an input yields a -different directory name. - -This approach is the foundation for the salient features of Guix: support -for transactional package upgrade and rollback, per-user installation, and -garbage collection of packages (@pxref{Features}). - - -@node GNU Distribution -@section GNU Distribution - -@cindex Guix System -Guix comes with a distribution of the GNU system consisting entirely of free -software@footnote{The term ``free'' here refers to the -@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to users of -that software}.}. The distribution can be installed on its own -(@pxref{System Installation}), but it is also possible to install Guix as a -package manager on top of an installed GNU/Linux system -(@pxref{Installation}). When we need to distinguish between the two, we -refer to the standalone distribution as Guix@tie{}System. - -The distribution provides core GNU packages such as GNU libc, GCC, and -Binutils, as well as many GNU and non-GNU applications. The complete list -of available packages can be browsed -@url{http://www.gnu.org/software/guix/packages,on-line} or by running -@command{guix package} (@pxref{Invoking guix package}): - -@example -guix package --list-available -@end example - -Our goal is to provide a practical 100% free software distribution of -Linux-based and other variants of GNU, with a focus on the promotion and -tight integration of GNU components, and an emphasis on programs and tools -that help users exert that freedom. - -Packages are currently available on the following platforms: - -@table @code - -@item x86_64-linux -Intel/AMD @code{x86_64} architecture, Linux-Libre kernel; - -@item i686-linux -Intel 32-bit architecture (IA32), Linux-Libre kernel; - -@item armhf-linux -ARMv7-A architecture with hard float, Thumb-2 and NEON, using the EABI -hard-float application binary interface (ABI), and Linux-Libre kernel. - -@item aarch64-linux -little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is -currently in an experimental stage, with limited support. -@xref{贡献}, for how to help! - -@item mips64el-linux -little-endian 64-bit MIPS processors, specifically the Loongson series, n32 -ABI, and Linux-Libre kernel. - -@end table - -With Guix@tie{}System, you @emph{declare} all aspects of the operating -system configuration and Guix takes care of instantiating the configuration -in a transactional, reproducible, and stateless fashion (@pxref{System -Configuration}). Guix System uses the Linux-libre kernel, the Shepherd -initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd -Manual}), the well-known GNU utilities and tool chain, as well as the -graphical environment or system services of your choice. - -Guix System is available on all the above platforms except -@code{mips64el-linux}. - -@noindent -For information on porting to other architectures or kernels, -@pxref{Porting}. - -Building this distribution is a cooperative effort, and you are invited to -join! @xref{贡献}, for information about how you can help. - - -@c ********************************************************************* -@node Installation -@chapter Installation - -@cindex installing Guix - -@quotation Note -We recommend the use of this -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -shell installer script} to install Guix on top of a running GNU/Linux -system, thereafter called a @dfn{foreign distro}.@footnote{This section is -concerned with the installation of the package manager, which can be done on -top of a running GNU/Linux system. If, instead, you want to install the -complete GNU operating system, @pxref{System Installation}.} The script -automates the download, installation, and initial configuration of Guix. It -should be run as the root user. -@end quotation - -@cindex foreign distro -@cindex directories related to foreign distro -When installed on a foreign distro, GNU@tie{}Guix complements the available -tools without interference. Its data lives exclusively in two directories, -usually @file{/gnu/store} and @file{/var/guix}; other files on your system, -such as @file{/etc}, are left untouched. - -Once installed, Guix can be updated by running @command{guix pull} -(@pxref{Invoking guix pull}). - -If you prefer to perform the installation steps manually or want to tweak -them, you may find the following subsections useful. They describe the -software requirements of Guix, as well as how to install it manually and get -ready to use it. - -@menu -* Binary Installation:: Getting Guix running in no time! -* Requirements:: Software needed to build and run Guix. -* Running the Test Suite:: Testing Guix. -* Setting Up the Daemon:: Preparing the build daemon's environment. -* Invoking guix-daemon:: Running the build daemon. -* Application Setup:: Application-specific setup. -@end menu - -@node Binary Installation -@section Binary Installation - -@cindex installing Guix from binaries -@cindex installer script -This section describes how to install Guix on an arbitrary system from a -self-contained tarball providing binaries for Guix and for all its -dependencies. This is often quicker than installing from source, which is -described in the next sections. The only requirement is to have -GNU@tie{}tar and Xz. - -Installing goes along these lines: - -@enumerate -@item -@cindex downloading Guix binary -Download the binary tarball from -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz}, -where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine -already running the kernel Linux, and so on. - -@c The following is somewhat duplicated in ``System Installation''. -Make sure to download the associated @file{.sig} file and to verify the -authenticity of the tarball against it, along these lines: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig -$ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig -@end example - -If that command fails because you do not have the required public key, then -run this command to import it: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end authentication part -and rerun the @code{gpg --verify} command. - -@item -Now, you need to become the @code{root} user. Depending on your -distribution, you may have to run @code{su -} or @code{sudo -i}. As -@code{root}, run: - -@example -# cd /tmp -# tar --warning=no-timestamp -xf \ - guix-binary-@value{VERSION}.@var{system}.tar.xz -# mv var/guix /var/ && mv gnu / -@end example - -This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}. -The latter contains a ready-to-use profile for @code{root} (see next step.) - -Do @emph{not} unpack the tarball on a working Guix system since that would -overwrite its own essential files. - -The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does not -emit warnings about ``implausibly old time stamps'' (such warnings were -triggered by GNU@tie{}tar 1.26 and older; recent versions are fine.) They -stem from the fact that all the files in the archive have their modification -time set to zero (which means January 1st, 1970.) This is done on purpose -to make sure the archive content is independent of its creation time, thus -making it reproducible. - -@item -Make the profile available under @file{~root/.config/guix/current}, which is -where @command{guix pull} will install updates (@pxref{Invoking guix pull}): - -@example -# mkdir -p ~root/.config/guix -# ln -sf /var/guix/profiles/per-user/root/current-guix \ - ~root/.config/guix/current -@end example - -Source @file{etc/profile} to augment @code{PATH} and other relevant -environment variables: - -@example -# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ - source $GUIX_PROFILE/etc/profile -@end example - -@item -Create the group and user accounts for build users as explained below -(@pxref{Build Environment Setup}). - -@item -Run the daemon, and set it to automatically start on boot. - -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 -# cp ~root/.config/guix/current/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 -# initctl reload-configuration -# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ - /etc/init/ -# start guix-daemon -@end example - -Otherwise, you can still start the daemon manually with: - -@example -# ~root/.config/guix/current/bin/guix-daemon \ - --build-users-group=guixbuild -@end example - -@item -Make the @command{guix} command available to other users on the machine, for -instance with: - -@example -# mkdir -p /usr/local/bin -# cd /usr/local/bin -# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix -@end example - -It is also a good idea to make the Info version of this manual available -there: - -@example -# mkdir -p /usr/local/share/info -# cd /usr/local/share/info -# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ; - do ln -s $i ; done -@end example - -That way, assuming @file{/usr/local/share/info} is in the search path, -running @command{info guix} will open this manual (@pxref{Other Info -Directories,,, texinfo, GNU Texinfo}, for more details on changing the Info -search path.) - -@item -@cindex substitutes, authorization thereof -To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its -mirrors (@pxref{Substitutes}), authorize them: - -@example -# guix archive --authorize < \ - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.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 - -Voilà, the installation is complete! - -You can confirm that Guix is working by installing a sample package into the -root profile: - -@example -# guix package -i hello -@end example - -The @code{guix} package must remain available in @code{root}'s profile, or -it would become subject to garbage collection---in which case you would find -yourself badly handicapped by the lack of the @command{guix} command. In -other words, do not remove @code{guix} by running @code{guix package -r -guix}. - -The binary installation tarball can be (re)produced and verified simply by -running the following command in the Guix source tree: - -@example -make guix-binary.@var{system}.tar.xz -@end example - -@noindent -...@: which, in turn, runs: - -@example -guix pack -s @var{system} --localstatedir \ - --profile-name=current-guix guix -@end example - -@xref{Invoking guix pack}, for more info on this handy tool. - -@node Requirements -@section Requirements - -This section lists requirements when building Guix from source. The build -procedure for Guix is the same as for other GNU software, and is not covered -here. Please see the files @file{README} and @file{INSTALL} in the Guix -source tree for additional details. - -@cindex official website -GNU Guix is available for download from its website at -@url{https://www.gnu.org/software/guix/}. - -GNU Guix depends on the following packages: - -@itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x; -@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version -0.1.0 or later; -@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 -@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, -version 0.1.0 or later; -@item -@c FIXME: Specify a version number once a release has been made. -@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, from August 2017 -or later; -@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}; -@item @url{http://zlib.net, zlib}; -@item @url{http://www.gnu.org/software/make/, GNU Make}. -@end itemize - -The following dependencies are optional: - -@itemize -@item -@c Note: We need at least 0.10.2 for 'channel-send-eof'. -Support for build offloading (@pxref{Daemon Offload Setup}) and -@command{guix copy} (@pxref{Invoking guix copy}) depends on -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, version -0.10.2 or later. - -@item -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 -following packages are also needed: - -@itemize -@item @url{http://gnupg.org/, GNU libgcrypt}; -@item @url{http://sqlite.org, SQLite 3}; -@item @url{http://gcc.gnu.org, GCC's g++}, with support for the -C++11 standard. -@end itemize - -@cindex state directory -When configuring Guix on a system that already has a Guix installation, be -sure to specify the same state directory as the existing installation using -the @code{--localstatedir} option of the @command{configure} script -(@pxref{Directory Variables, @code{localstatedir},, standards, GNU Coding -Standards}). The @command{configure} script protects against unintended -misconfiguration of @var{localstatedir} so you do not inadvertently corrupt -your store (@pxref{The Store}). - -@cindex Nix, compatibility -When a working installation of @url{http://nixos.org/nix/, the Nix package -manager} is available, you can instead configure Guix with -@code{--disable-daemon}. In that case, Nix replaces the three dependencies -above. - -Guix is compatible with Nix, so it is possible to share the same store -between both. To do so, you must pass @command{configure} not only the same -@code{--with-store-dir} value, but also the same @code{--localstatedir} -value. The latter is essential because it specifies where the database that -stores metadata about the store is located, among other things. The default -values for Nix are @code{--with-store-dir=/nix/store} and -@code{--localstatedir=/nix/var}. Note that @code{--disable-daemon} is not -required if your goal is to share the store with Nix. - -@node Running the Test Suite -@section Running the Test Suite - -@cindex test suite -After a successful @command{configure} and @code{make} run, it is a good -idea to run the test suite. It can help catch issues with the setup or -environment, or bugs in Guix itself---and really, reporting test failures is -a good way to help improve the software. To run the test suite, type: - -@example -make check -@end example - -Test cases can run in parallel: you can use the @code{-j} option of -GNU@tie{}make to speed things up. The first run may take a few minutes on a -recent machine; subsequent runs will be faster because the store that is -created for test purposes will already have various things in cache. - -It is also possible to run a subset of the tests by defining the -@code{TESTS} makefile variable as in this example: - -@example -make check TESTS="tests/store.scm tests/cpio.scm" -@end example - -By default, tests results are displayed at a file level. In order to see -the details of every individual test cases, it is possible to define the -@code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example: - -@example -make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" -@end example - -Upon failure, please email @email{bug-guix@@gnu.org} and attach the -@file{test-suite.log} file. Please specify the Guix version being used as -well as version numbers of the dependencies (@pxref{Requirements}) in your -message. - -Guix also comes with a whole-system test suite that tests complete Guix -System instances. It can only run on systems where Guix is already -installed, using: - -@example -make check-system -@end example - -@noindent -or, again, by defining @code{TESTS} to select a subset of tests to run: - -@example -make check-system TESTS="basic mcron" -@end example - -These system tests are defined in the @code{(gnu tests @dots{})} modules. -They work by running the operating systems under test with lightweight -instrumentation in a virtual machine (VM). They can be computationally -intensive or rather cheap, depending on whether substitutes are available -for their dependencies (@pxref{Substitutes}). Some of them require a lot of -storage space to hold VM images. - -Again in case of test failures, please send @email{bug-guix@@gnu.org} all -the details. - -@node Setting Up the Daemon -@section Setting Up the Daemon - -@cindex daemon -Operations such as building a package or running the garbage collector are -all performed by a specialized process, the @dfn{build daemon}, on behalf of -clients. Only the daemon may access the store and its associated database. -Thus, any operation that manipulates the store goes through the daemon. For -instance, command-line tools such as @command{guix package} and -@command{guix build} communicate with the daemon (@i{via} remote procedure -calls) to instruct it what to do. - -The following sections explain how to prepare the build daemon's -environment. See also @ref{Substitutes}, for information on how to allow -the daemon to download pre-built binaries. - -@menu -* Build Environment Setup:: Preparing the isolated build environment. -* Daemon Offload Setup:: Offloading builds to remote machines. -* SELinux Support:: Using an SELinux policy for the daemon. -@end menu - -@node Build Environment Setup -@subsection Build Environment Setup - -@cindex build environment -In a standard multi-user setup, Guix and its daemon---the -@command{guix-daemon} program---are installed by the system administrator; -@file{/gnu/store} is owned by @code{root} and @command{guix-daemon} runs as -@code{root}. Unprivileged users may use Guix tools to build packages or -otherwise access the store, and the daemon will do it on their behalf, -ensuring that the store is kept in a consistent state, and allowing built -packages to be shared among users. - -@cindex build users -When @command{guix-daemon} runs as @code{root}, you may not want package -build processes themselves to run as @code{root} too, for obvious security -reasons. To avoid that, a special pool of @dfn{build users} should be -created for use by build processes started by the daemon. These build users -need not have a shell and a home directory: they will just be used when the -daemon drops @code{root} privileges in build processes. Having several such -users allows the daemon to launch distinct build processes under separate -UIDs, which guarantees that they do not interfere with each other---an -essential feature since builds are regarded as pure functions -(@pxref{Introduction}). - -On a GNU/Linux system, a build user pool may be created like this (using -Bash syntax and the @code{shadow} commands): - -@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html -@c for why `-G' is needed. -@example -# groupadd --system guixbuild -# for i in `seq -w 1 10`; - do - useradd -g guixbuild -G guixbuild \ - -d /var/empty -s `which nologin` \ - -c "Guix build user $i" --system \ - guixbuilder$i; - done -@end example - -@noindent -The number of build users determines how many build jobs may run in -parallel, as specified by the @option{--max-jobs} option (@pxref{Invoking -guix-daemon, @option{--max-jobs}}). To use @command{guix system vm} and -related commands, you may need to add the build users to the @code{kvm} -group so they can access @file{/dev/kvm}, using @code{-G guixbuild,kvm} -instead of @code{-G guixbuild} (@pxref{Invoking guix system}). - -The @code{guix-daemon} program may then be run as @code{root} with the -following command@footnote{If your machine uses the systemd init system, -dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service} file -in @file{/etc/systemd/system} will ensure that @command{guix-daemon} is -automatically started. Similarly, if your machine uses the Upstart init -system, drop the @file{@var{prefix}/lib/upstart/system/guix-daemon.conf} -file in @file{/etc/init}.}: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@cindex chroot -@noindent -This way, the daemon starts build processes in a chroot, under one of the -@code{guixbuilder} users. On GNU/Linux, by default, the chroot environment -contains nothing but: - -@c Keep this list in sync with libstore/build.cc! ----------------------- -@itemize -@item -a minimal @code{/dev} directory, created mostly independently from the host -@code{/dev}@footnote{``Mostly'', because while the set of files that appear -in the chroot's @code{/dev} is fixed, most of these files can only be -created if the host has them.}; - -@item -the @code{/proc} directory; it only shows the processes of the container -since a separate PID name space is used; - -@item -@file{/etc/passwd} with an entry for the current user and an entry for user -@file{nobody}; - -@item -@file{/etc/group} with an entry for the user's group; - -@item -@file{/etc/hosts} with an entry that maps @code{localhost} to -@code{127.0.0.1}; - -@item -a writable @file{/tmp} directory. -@end itemize - -You can influence the directory where the daemon stores build trees @i{via} -the @code{TMPDIR} environment variable. However, the build tree within the -chroot is always called @file{/tmp/guix-build-@var{name}.drv-0}, where -@var{name} is the derivation name---e.g., @code{coreutils-8.24}. This way, -the value of @code{TMPDIR} does not leak inside build environments, which -avoids discrepancies in cases where build processes capture the name of -their build tree. - -@vindex http_proxy -The daemon also honors the @code{http_proxy} environment variable for HTTP -downloads it performs, be it for fixed-output derivations -(@pxref{Derivations}) or for substitutes (@pxref{Substitutes}). - -If you are installing Guix as an unprivileged user, it is still possible to -run @command{guix-daemon} provided you pass @code{--disable-chroot}. -However, build processes will not be isolated from one another, and not from -the rest of the system. Thus, build processes may interfere with each -other, and may access programs, libraries, and other files available on the -system---making it much harder to view them as @emph{pure} functions. - - -@node Daemon Offload Setup -@subsection Using the Offload Facility - -@cindex offloading -@cindex build hook -When desired, the build daemon can @dfn{offload} derivation builds to other -machines running Guix, using the @code{offload} @dfn{build -hook}@footnote{This feature is available only when -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is present.}. -When that feature is enabled, a list of user-specified build machines is -read from @file{/etc/guix/machines.scm}; every time a build is requested, -for instance via @code{guix build}, the daemon attempts to offload it to one -of the machines that satisfy the constraints of the derivation, in -particular its system type---e.g., @file{x86_64-linux}. Missing -prerequisites for the build are copied over SSH to the target machine, which -then proceeds with the build; upon success the output(s) of the build are -copied back to the initial machine. - -The @file{/etc/guix/machines.scm} file typically looks like this: - -@example -(list (build-machine - (name "eightysix.example.org") - (system "x86_64-linux") - (host-key "ssh-ed25519 AAAAC3Nza@dots{}") - (user "bob") - (speed 2.)) ;incredibly fast! - - (build-machine - (name "meeps.example.org") - (system "mips64el-linux") - (host-key "ssh-rsa AAAAB3Nza@dots{}") - (user "alice") - (private-key - (string-append (getenv "HOME") - "/.ssh/identity-for-guix")))) -@end example - -@noindent -In the example above we specify a list of two build machines, one for the -@code{x86_64} architecture and one for the @code{mips64el} architecture. - -In fact, this file is---not surprisingly!---a Scheme file that is evaluated -when the @code{offload} hook is started. Its return value must be a list of -@code{build-machine} objects. While this example shows a fixed list of -build machines, one could imagine, say, using DNS-SD to return a list of -potential build machines discovered in the local network -(@pxref{Introduction, Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme -Programs}). The @code{build-machine} data type is detailed below. - -@deftp {Data Type} build-machine -This data type represents build machines to which the daemon may offload -builds. The important fields are: - -@table @code - -@item name -The host name of the remote machine. - -@item system -The system type of the remote machine---e.g., @code{"x86_64-linux"}. - -@item user -The user account to use when connecting to the remote machine over SSH. -Note that the SSH key pair must @emph{not} be passphrase-protected, to allow -non-interactive logins. - -@item host-key -This must be the machine's SSH @dfn{public host key} in OpenSSH format. -This is used to authenticate the machine when we connect to it. It is a -long string that looks like this: - -@example -ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org -@end example - -If the machine is running the OpenSSH daemon, @command{sshd}, the host key -can be found in a file such as @file{/etc/ssh/ssh_host_ed25519_key.pub}. - -If the machine is running the SSH daemon of GNU@tie{}lsh, @command{lshd}, -the host key is in @file{/etc/lsh/host-key.pub} or a similar file. It can -be converted to the OpenSSH format using @command{lsh-export-key} -(@pxref{Converting keys,,, lsh, LSH Manual}): - -@example -$ lsh-export-key --openssh < /etc/lsh/host-key.pub -ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{} -@end example - -@end table - -A number of optional fields may be specified: - -@table @asis - -@item @code{port} (default: @code{22}) -Port number of SSH server on the machine. - -@item @code{private-key} (default: @file{~root/.ssh/id_rsa}) -The SSH private key file to use when connecting to the machine, in OpenSSH -format. This key must not be protected with a passphrase. - -Note that the default value is the private key @emph{of the root account}. -Make sure it exists if you use the default. - -@item @code{compression} (default: @code{"zlib@@openssh.com,zlib"}) -@itemx @code{compression-level} (default: @code{3}) -The SSH-level compression methods and compression level requested. - -Note that offloading relies on SSH compression to reduce bandwidth usage -when transferring files to and from build machines. - -@item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"}) -File name of the Unix-domain socket @command{guix-daemon} is listening to on -that machine. - -@item @code{parallel-builds} (default: @code{1}) -The number of builds that may run in parallel on the machine. - -@item @code{speed} (default: @code{1.0}) -A ``relative speed factor''. The offload scheduler will tend to prefer -machines with a higher speed factor. - -@item @code{features} (default: @code{'()}) -A list of strings denoting specific features supported by the machine. An -example is @code{"kvm"} for machines that have the KVM Linux modules and -corresponding hardware support. Derivations can request features by name, -and they will be scheduled on matching build machines. - -@end table -@end deftp - -The @command{guix} command must be in the search path on the build -machines. You can check whether this is the case by running: - -@example -ssh build-machine guix repl --version -@end example - -There is one last thing to do once @file{machines.scm} is in place. As -explained above, when offloading, files are transferred back and forth -between the machine stores. For this to work, you first need to generate a -key pair on each machine to allow the daemon to export signed archives of -files from the store (@pxref{Invoking guix archive}): - -@example -# guix archive --generate-key -@end example - -@noindent -Each build machine must authorize the key of the master machine so that it -accepts store items it receives from the master: - -@example -# guix archive --authorize < master-public-key.txt -@end example - -@noindent -Likewise, the master machine must authorize the key of each build machine. - -All the fuss with keys is here to express pairwise mutual trust relations -between the master and the build machines. Concretely, when the master -receives files from a build machine (and @i{vice versa}), its build daemon -can make sure they are genuine, have not been tampered with, and that they -are signed by an authorized key. - -@cindex offload test -To test whether your setup is operational, run this command on the master -node: - -@example -# guix offload test -@end example - -This will attempt to connect to each of the build machines specified in -@file{/etc/guix/machines.scm}, make sure Guile and the Guix modules are -available on each machine, attempt to export to the machine and import from -it, and report any error in the process. - -If you want to test a different machine file, just specify it on the command -line: - -@example -# guix offload test machines-qualif.scm -@end example - -Last, you can test the subset of the machines whose name matches a regular -expression like this: - -@example -# 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 SELinux Support -@subsection SELinux Support - -@cindex SELinux, daemon policy -@cindex mandatory access control, SELinux -@cindex security, guix-daemon -Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that can -be installed on a system where SELinux is enabled, in order to label Guix -files and to specify the expected behavior of the daemon. Since Guix System -does not provide an SELinux base policy, the daemon policy cannot be used on -Guix System. - -@subsubsection Installing the SELinux policy -@cindex SELinux, policy installation -To install the policy run this command as root: - -@example -semodule -i etc/guix-daemon.cil -@end example - -Then relabel the file system with @code{restorecon} or by a different -mechanism provided by your system. - -Once the policy is installed, the file system has been relabeled, and the -daemon has been restarted, it should be running in the @code{guix_daemon_t} -context. You can confirm this with the following command: - -@example -ps -Zax | grep guix-daemon -@end example - -Monitor the SELinux log files as you run a command like @code{guix build -hello} to convince yourself that SELinux permits all necessary operations. - -@subsubsection Limitations -@cindex SELinux, limitations - -This policy is not perfect. Here is a list of limitations or quirks that -should be considered when deploying the provided SELinux policy for the Guix -daemon. - -@enumerate -@item -@code{guix_daemon_socket_t} isn’t actually used. None of the socket -operations involve contexts that have anything to do with -@code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label, but -it would be preferrable to define socket rules for only this label. - -@item -@code{guix gc} cannot access arbitrary links to profiles. By design, the -file label of the destination of a symlink is independent of the file label -of the link itself. Although all profiles under $localstatedir are -labelled, the links to these profiles inherit the label of the directory -they are in. For links in the user’s home directory this will be -@code{user_home_t}. But for links from the root user’s home directory, or -@file{/tmp}, or the HTTP server’s working directory, etc, this won’t work. -@code{guix gc} would be prevented from reading and following these links. - -@item -The daemon’s feature to listen for TCP connections might no longer work. -This might require extra rules, because SELinux treats network sockets -differently from files. - -@item -Currently all files with a name matching the regular expression -@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the -label @code{guix_daemon_exec_t}; this means that @emph{any} file with that -name in any profile would be permitted to run in the @code{guix_daemon_t} -domain. This is not ideal. An attacker could build a package that provides -this executable and convince a user to install and run it, which lifts it -into the @code{guix_daemon_t} domain. At that point SELinux could not -prevent it from accessing files that are allowed for processes in that -domain. - -We could generate a much more restrictive policy at installation time, so -that only the @emph{exact} file name of the currently installed -@code{guix-daemon} executable would be labelled with -@code{guix_daemon_exec_t}, instead of using a broad regular expression. The -downside is that root would have to install or upgrade the policy at -installation time whenever the Guix package that provides the effectively -running @code{guix-daemon} executable is upgraded. -@end enumerate - -@node Invoking guix-daemon -@section Invoking @command{guix-daemon} - -The @command{guix-daemon} program implements all the functionality to access -the store. This includes launching build processes, running the garbage -collector, querying the availability of a build result, etc. It is normally -run as @code{root} like this: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@noindent -For details on how to set it up, @pxref{Setting Up the Daemon}. - -@cindex chroot -@cindex container, build environment -@cindex build environment -@cindex reproducible builds -By default, @command{guix-daemon} launches build processes under different -UIDs, taken from the build group specified with @code{--build-users-group}. -In addition, each build process is run in a chroot environment that only -contains the subset of the store that the build process depends on, as -specified by its derivation (@pxref{Programming Interface, derivation}), -plus a set of specific system directories. By default, the latter contains -@file{/dev} and @file{/dev/pts}. Furthermore, on GNU/Linux, the build -environment is a @dfn{container}: in addition to having its own file system -tree, it has a separate mount name space, its own PID name space, network -name space, etc. This helps achieve reproducible builds (@pxref{Features}). - -When the daemon performs a build on behalf of the user, it creates a build -directory under @file{/tmp} or under the directory specified by its -@code{TMPDIR} environment variable. This directory is shared with the -container for the duration of the build, though within the container, the -build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}. - -The build directory is automatically deleted upon completion, unless the -build failed and the client specified @option{--keep-failed} -(@pxref{Invoking guix build, @option{--keep-failed}}). - -The daemon listens for connections and spawns one sub-process for each -session started by a client (one of the @command{guix} sub-commands.) The -@command{guix processes} command allows you to get an overview of the -activity on your system by viewing each of the active sessions and clients. -@xref{Invoking guix processes}, for more information. - -The following command-line options are supported: - -@table @code -@item --build-users-group=@var{group} -Take users from @var{group} to run build processes (@pxref{Setting Up the -Daemon, build users}). - -@item --no-substitutes -@cindex substitutes -Do not use substitutes for build products. That is, always build things -locally instead of allowing downloads of pre-built binaries -(@pxref{Substitutes}). - -When the daemon runs with @code{--no-substitutes}, clients can still -explicitly enable substitution @i{via} the @code{set-build-options} remote -procedure call (@pxref{The Store}). - -@item --substitute-urls=@var{urls} -@anchor{daemon-substitute-urls} -Consider @var{urls} the default whitespace-separated list of substitute -source URLs. When this option is omitted, -@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used. - -This means that substitutes may be downloaded from @var{urls}, as long as -they are signed by a trusted signature (@pxref{Substitutes}). - -@cindex build hook -@item --no-build-hook -Do not use the @dfn{build hook}. - -The build hook is a helper program that the daemon can start and to which it -submits build requests. This mechanism is used to offload builds to other -machines (@pxref{Daemon Offload Setup}). - -@item --cache-failures -Cache build failures. By default, only successful builds are cached. - -When this option is used, @command{guix gc --list-failures} can be used to -query the set of store items marked as failed; @command{guix gc ---clear-failures} removes store items from the set of cached failures. -@xref{Invoking guix gc}. - -@item --cores=@var{n} -@itemx -c @var{n} -Use @var{n} CPU cores to build each derivation; @code{0} means as many as -available. - -The default value is @code{0}, but it may be overridden by clients, such as -the @code{--cores} option of @command{guix build} (@pxref{Invoking guix -build}). - -The effect is to define the @code{NIX_BUILD_CORES} environment variable in -the build process, which can then use it to exploit internal -parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Allow at most @var{n} build jobs in parallel. The default value is -@code{1}. Setting it to @code{0} means that no builds will be performed -locally; instead, the daemon will offload builds (@pxref{Daemon Offload -Setup}), or simply fail. - -@item --max-silent-time=@var{seconds} -When the build or substitution process remains silent for more than -@var{seconds}, terminate it and report a build failure. - -The default value is @code{0}, which disables the timeout. - -The value specified here can be overridden by clients (@pxref{Common Build -Options, @code{--max-silent-time}}). - -@item --timeout=@var{seconds} -Likewise, when the build or substitution process lasts for more than -@var{seconds}, terminate it and report a build failure. - -The default value is @code{0}, which disables the timeout. - -The value specified here can be overridden by clients (@pxref{Common Build -Options, @code{--timeout}}). - -@item --rounds=@var{N} -Build each derivation @var{n} times in a row, and raise an error if -consecutive build results are not bit-for-bit identical. Note that this -setting can be overridden by clients such as @command{guix build} -(@pxref{Invoking guix build}). - -When used in conjunction with @option{--keep-failed}, the differing output -is kept in the store, under @file{/gnu/store/@dots{}-check}. This makes it -easy to look for differences between the two results. - -@item --debug -Produce debugging output. - -This is useful to debug daemon start-up issues, but then it may be -overridden by clients, for example the @code{--verbosity} option of -@command{guix build} (@pxref{Invoking guix build}). - -@item --chroot-directory=@var{dir} -Add @var{dir} to the build chroot. - -Doing this may change the result of build processes---for instance if they -use optional dependencies found in @var{dir} when it is available, and not -otherwise. For that reason, it is not recommended to do so. Instead, make -sure that each derivation declares all the inputs that it needs. - -@item --disable-chroot -Disable chroot builds. - -Using this option is not recommended since, again, it would allow build -processes to gain access to undeclared dependencies. It is necessary, -though, when @command{guix-daemon} is running under an unprivileged user -account. - -@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. - -@item --disable-deduplication -@cindex deduplication -Disable automatic file ``deduplication'' in the store. - -By default, files added to the store are automatically ``deduplicated'': if -a newly added file is identical to another one found in the store, the -daemon makes the new file a hard link to the other file. This can -noticeably reduce disk usage, at the expense of slightly increased -input/output load at the end of a build process. This option disables this -optimization. - -@item --gc-keep-outputs[=yes|no] -Tell whether the garbage collector (GC) must keep outputs of live -derivations. - -@cindex GC roots -@cindex garbage collector roots -When set to ``yes'', the GC will keep the outputs of any live derivation -available in the store---the @code{.drv} files. The default is ``no'', -meaning that derivation outputs are kept only if they are reachable from a -GC root. @xref{Invoking guix gc}, for more on GC roots. - -@item --gc-keep-derivations[=yes|no] -Tell whether the garbage collector (GC) must keep derivations corresponding -to live outputs. - -When set to ``yes'', as is the case by default, the GC keeps -derivations---i.e., @code{.drv} files---as long as at least one of their -outputs is live. This allows users to keep track of the origins of items in -their store. Setting it to ``no'' saves a bit of disk space. - -In this way, setting @code{--gc-keep-derivations} to ``yes'' causes liveness -to flow from outputs to derivations, and setting @code{--gc-keep-outputs} to -``yes'' causes liveness to flow from derivations to outputs. When both are -set to ``yes'', the effect is to keep all the build prerequisites (the -sources, compiler, libraries, and other build-time tools) of live objects in -the store, regardless of whether these prerequisites are reachable from a GC -root. This is convenient for developers since it saves rebuilds or -downloads. - -@item --impersonate-linux-2.6 -On Linux-based systems, impersonate Linux 2.6. This means that the kernel's -@code{uname} system call will report 2.6 as the release number. - -This might be helpful to build programs that (usually wrongfully) depend on -the kernel version number. - -@item --lose-logs -Do not keep build logs. By default they are kept under -@code{@var{localstatedir}/guix/log}. - -@item --system=@var{system} -Assume @var{system} as the current system type. By default it is the -architecture/kernel pair found at configure time, such as -@code{x86_64-linux}. - -@item --listen=@var{endpoint} -Listen for connections on @var{endpoint}. @var{endpoint} is interpreted as -the file name of a Unix-domain socket if it starts with @code{/} (slash -sign). Otherwise, @var{endpoint} is interpreted as a host name or host name -and port to listen to. Here are a few examples: - -@table @code -@item --listen=/gnu/var/daemon -Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket, -creating it if needed. - -@item --listen=localhost -@cindex daemon, remote access -@cindex remote access to the daemon -@cindex daemon, cluster setup -@cindex clusters, daemon setup -Listen for TCP connections on the network interface corresponding to -@code{localhost}, on port 44146. - -@item --listen=128.0.0.42:1234 -Listen for TCP connections on the network interface corresponding to -@code{128.0.0.42}, on port 1234. -@end table - -This option can be repeated multiple times, in which case -@command{guix-daemon} accepts connections on all the specified endpoints. -Users can tell client commands what endpoint to connect to by setting the -@code{GUIX_DAEMON_SOCKET} environment variable (@pxref{The Store, -@code{GUIX_DAEMON_SOCKET}}). - -@quotation Note -The daemon protocol is @emph{unauthenticated and unencrypted}. Using -@code{--listen=@var{host}} is suitable on local networks, such as clusters, -where only trusted nodes may connect to the build daemon. In other cases -where remote access to the daemon is needed, we recommend using Unix-domain -sockets along with SSH. -@end quotation - -When @code{--listen} is omitted, @command{guix-daemon} listens for -connections on the Unix-domain socket located at -@file{@var{localstatedir}/guix/daemon-socket/socket}. -@end table - - -@node Application Setup -@section Application Setup - -@cindex foreign distro -When using Guix on top of GNU/Linux distribution other than Guix System---a -so-called @dfn{foreign distro}---a few additional steps are needed to get -everything in place. Here are some of them. - -@subsection Locales - -@anchor{locales-and-locpath} -@cindex locales, when not on Guix System -@vindex LOCPATH -@vindex GUIX_LOCPATH -Packages installed @i{via} Guix will not use the locale data of the host -system. Instead, you must first install one of the locale packages -available with Guix and then define the @code{GUIX_LOCPATH} environment -variable: - -@example -$ guix package -i glibc-locales -$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale -@end example - -Note that the @code{glibc-locales} package contains data for all the locales -supported by the GNU@tie{}libc and weighs in at around 110@tie{}MiB. -Alternatively, the @code{glibc-utf8-locales} is smaller but limited to a few -UTF-8 locales. - -The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH} -(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library Reference -Manual}). There are two important differences though: - -@enumerate -@item -@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc -provided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you to -make sure the programs of the foreign distro will not end up loading -incompatible locale data. - -@item -libc suffixes each entry of @code{GUIX_LOCPATH} with @code{/X.Y}, where -@code{X.Y} is the libc version---e.g., @code{2.22}. This means that, should -your Guix profile contain a mixture of programs linked against different -libc version, each libc version will only try to load locale data in the -right format. -@end enumerate - -This is important because the locale data format used by different libc -versions may be incompatible. - -@subsection Name Service Switch - -@cindex name service switch, glibc -@cindex NSS (name service switch), glibc -@cindex nscd (name service caching daemon) -@cindex name service caching daemon (nscd) -When using Guix on a foreign distro, we @emph{strongly recommend} that the -system run the GNU C library's @dfn{name service cache daemon}, -@command{nscd}, which should be listening on the @file{/var/run/nscd/socket} -socket. Failing to do that, applications installed with Guix may fail to -look up host names or user accounts, or may even crash. The next paragraphs -explain why. - -@cindex @file{nsswitch.conf} -The GNU C library implements a @dfn{name service switch} (NSS), which is an -extensible mechanism for ``name lookups'' in general: host name resolution, -user accounts, and more (@pxref{Name Service Switch,,, libc, The GNU C -Library Reference Manual}). - -@cindex Network information service (NIS) -@cindex NIS (Network information service) -Being extensible, the NSS supports @dfn{plugins}, which provide new name -lookup implementations: for example, the @code{nss-mdns} plugin allow -resolution of @code{.local} host names, the @code{nis} plugin allows user -account lookup using the Network information service (NIS), and so on. -These extra ``lookup services'' are configured system-wide in -@file{/etc/nsswitch.conf}, and all the programs running on the system honor -those settings (@pxref{NSS Configuration File,,, libc, The GNU C Reference -Manual}). - -When they perform a name lookup---for instance by calling the -@code{getaddrinfo} function in C---applications first try to connect to the -nscd; on success, nscd performs name lookups on their behalf. If the nscd -is not running, then they perform the name lookup by themselves, by loading -the name lookup services into their own address space and running it. These -name lookup services---the @file{libnss_*.so} files---are @code{dlopen}'d, -but they may come from the host system's C library, rather than from the C -library the application is linked against (the C library coming from Guix). - -And this is where the problem is: if your application is linked against -Guix's C library (say, glibc 2.24) and tries to load NSS plugins from -another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will -likely crash or have its name lookups fail unexpectedly. - -Running @command{nscd} on the system, among other advantages, eliminates -this binary incompatibility problem because those @code{libnss_*.so} files -are loaded in the @command{nscd} process, not in applications themselves. - -@subsection X11 Fonts - -@cindex fonts -The majority of graphical applications use Fontconfig to locate and load -fonts and perform X11-client-side rendering. The @code{fontconfig} package -in Guix looks for fonts in @file{$HOME/.guix-profile} by default. Thus, to -allow graphical applications installed with Guix to display fonts, you have -to install fonts with Guix as well. Essential font packages include -@code{gs-fonts}, @code{font-dejavu}, and @code{font-gnu-freefont-ttf}. - -To display text written in Chinese languages, Japanese, or Korean in -graphical applications, consider installing -@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former has -multiple outputs, one per language family (@pxref{Packages with Multiple -Outputs}). For instance, the following command installs fonts for Chinese -languages: - -@example -guix package -i font-adobe-source-han-sans:cn -@end example - -@cindex @code{xterm} -Older programs such as @command{xterm} do not use Fontconfig and instead -rely on server-side font rendering. Such programs require to specify a full -name of a font using XLFD (X Logical Font Description), like this: - -@example --*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 -@end example - -To be able to use such full names for the TrueType fonts installed in your -Guix profile, you need to extend the font path of the X server: - -@c Note: 'xset' does not accept symlinks so the trick below arranges to -@c get at the real directory. See <https://bugs.gnu.org/30655>. -@example -xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)) -@end example - -@cindex @code{xlsfonts} -After that, you can run @code{xlsfonts} (from @code{xlsfonts} package) to -make sure your TrueType fonts are listed there. - -@cindex @code{fc-cache} -@cindex font cache -After installing fonts you may have to refresh the font cache to use them in -applications. The same applies when applications installed via Guix do not -seem to find fonts. To force rebuilding of the font cache run -@code{fc-cache -f}. The @code{fc-cache} command is provided by the -@code{fontconfig} package. - -@subsection X.509 Certificates - -@cindex @code{nss-certs} -The @code{nss-certs} package provides X.509 certificates, which allow -programs to authenticate Web servers accessed over HTTPS. - -When using Guix on a foreign distro, you can install this package and define -the relevant environment variables so that packages know where to look for -certificates. @xref{X.509 Certificates}, for detailed information. - -@subsection Emacs Packages - -@cindex @code{emacs} -When you install Emacs packages with Guix, the elisp files may be placed -either in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or in -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 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 Files,,, -emacs, The GNU Emacs Manual}). - -By default, Emacs (installed with Guix) ``knows'' where these packages are -placed, so you do not need to perform any configuration. If, for some -reason, you want to avoid auto-loading Emacs packages installed with Guix, -you can do so by running Emacs with @code{--no-site-file} option -(@pxref{Init File,,, emacs, The GNU Emacs Manual}). - -@subsection The GCC toolchain - -@cindex GCC -@cindex ld-wrapper - -Guix offers individual compiler packages such as @code{gcc} but if you are -in need of a complete toolchain for compiling and linking source code what -you really want is the @code{gcc-toolchain} package. This package provides -a complete GCC toolchain for C/C++ development, including GCC itself, the -GNU C Library (headers and binaries, plus debugging symbols in the -@code{debug} output), Binutils, and a linker wrapper. - -The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches -passed to the linker, add corresponding @code{-rpath} arguments, and invoke -the actual linker with this new set of arguments. You can instruct the -wrapper to refuse to link against libraries not in the store by setting the -@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. - -@c TODO What else? - -@c ********************************************************************* -@node System Installation -@chapter System Installation - -@cindex installing Guix System -@cindex Guix System, installation -This section explains how to install Guix System on a machine. Guix, as a -package manager, can also be installed on top of a running GNU/Linux system, -@pxref{Installation}. - -@ifinfo -@quotation Note -@c This paragraph is for people reading this from tty2 of the -@c installation image. -You are reading this documentation with an Info reader. For details on how -to use it, hit the @key{RET} key (``return'' or ``enter'') on the link that -follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU Info}. Hit -@kbd{l} afterwards to come back here. - -Alternately, run @command{info info} in another tty to keep the manual -available. -@end quotation -@end ifinfo - -@menu -* Limitations:: What you can expect. -* Hardware Considerations:: Supported hardware. -* USB Stick and DVD Installation:: Preparing the installation medium. -* Preparing for Installation:: Networking, partitioning, etc. -* Guided Graphical Installation:: Easy graphical installation. -* Manual Installation:: Manual installation for wizards. -* After System Installation:: When installation succeeded. -* Installing Guix in a VM:: Guix System playground. -* Building the Installation Image:: How this comes to be. -@end menu - -@node Limitations -@section Limitations - -We consider Guix System to be ready for a wide range of ``desktop'' and -server use cases. The reliability guarantees it provides---transactional -upgrades and rollbacks, reproducibility---make it a solid foundation. - -Nevertheless, before you proceed with the installation, be aware of the -following noteworthy limitations applicable to version @value{VERSION}: - -@itemize -@item -Support for the Logical Volume Manager (LVM) is missing. - -@item -More and more system services are provided (@pxref{Services}), but some may -be missing. - -@item -GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop -Services}), as well as a number of X11 window managers. However, KDE is -currently missing. -@end itemize - -More than a disclaimer, this is an invitation to report issues (and success -stories!), and to join us in improving it. @xref{贡献}, for more -info. - - -@node Hardware Considerations -@section Hardware Considerations - -@cindex hardware support on Guix System -GNU@tie{}Guix focuses on respecting the user's computing freedom. It builds -around the kernel Linux-libre, which means that only hardware for which free -software drivers and firmware exist is supported. Nowadays, a wide range of -off-the-shelf hardware is supported on GNU/Linux-libre---from keyboards to -graphics cards to scanners and Ethernet controllers. Unfortunately, there -are still areas where hardware vendors deny users control over their own -computing, and such hardware is not supported on Guix System. - -@cindex WiFi, hardware support -One of the main areas where free drivers or firmware are lacking is WiFi -devices. WiFi devices known to work include those using Atheros chips -(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre -driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core -Revision 5), which corresponds to the @code{b43-open} Linux-libre driver. -Free firmware exists for both and is available out-of-the-box on Guix -System, as part of @code{%base-firmware} (@pxref{operating-system Reference, -@code{firmware}}). - -@cindex RYF, Respects Your Freedom -The @uref{https://www.fsf.org/, Free Software Foundation} runs -@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a -certification program for hardware products that respect your freedom and -your privacy and ensure that you have control over your device. We -encourage you to check the list of RYF-certified devices. - -Another useful resource is the @uref{https://www.h-node.org/, H-Node} web -site. It contains a catalog of hardware devices with information about -their support in GNU/Linux. - - -@node USB Stick and DVD Installation -@section USB Stick and DVD Installation - -An ISO-9660 installation image that can be written to a USB stick or burnt -to a DVD can be downloaded from -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz}, -where @var{system} is one of: - -@table @code -@item x86_64-linux -for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs; - -@item i686-linux -for a 32-bit GNU/Linux system on Intel-compatible CPUs. -@end table - -@c start duplication of authentication part from ``Binary Installation'' -Make sure to download the associated @file{.sig} file and to verify the -authenticity of the image against it, along these lines: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig -$ gpg --verify guix-system-install-@value{VERSION}.@var{system}.iso.xz.sig -@end example - -If that command fails because you do not have the required public key, then -run this command to import it: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end duplication -and rerun the @code{gpg --verify} command. - -This image contains the tools necessary for an installation. It is meant to -be copied @emph{as is} to a large-enough USB stick or DVD. - -@unnumberedsubsec Copying to a USB Stick - -To copy the image to a USB stick, follow these steps: - -@enumerate -@item -Decompress the image using the @command{xz} command: - -@example -xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz -@end example - -@item -Insert a USB stick of 1@tie{}GiB or more into your machine, and determine -its device name. Assuming that the USB stick is known as @file{/dev/sdX}, -copy the image with: - -@example -dd if=guix-system-install-@value{VERSION}.@var{system}.iso of=/dev/sdX -sync -@end example - -Access to @file{/dev/sdX} usually requires root privileges. -@end enumerate - -@unnumberedsubsec Burning on a DVD - -To copy the image to a DVD, follow these steps: - -@enumerate -@item -Decompress the image using the @command{xz} command: - -@example -xz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz -@end example - -@item -Insert a blank DVD into your machine, and determine its device name. -Assuming that the DVD drive is known as @file{/dev/srX}, copy the image -with: - -@example -growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.@var{system}.iso -@end example - -Access to @file{/dev/srX} usually requires root privileges. -@end enumerate - -@unnumberedsubsec Booting - -Once this is done, you should be able to reboot the system and boot from the -USB stick or DVD. The latter usually requires you to get in the BIOS or -UEFI boot menu, where you can choose to boot from the USB stick. - -@xref{Installing Guix in a VM}, if, instead, you would like to install Guix -System in a virtual machine (VM). - - -@node Preparing for Installation -@section Preparing for Installation - -Once you have booted, you can use the guided graphical installer, which -makes it easy to get started (@pxref{Guided Graphical Installation}). -Alternately, if you are already familiar with GNU/Linux and if you want more -control than what the graphical installer provides, you can choose the -``manual'' installation process (@pxref{Manual Installation}). - -The graphical installer is available on TTY1. You can obtain root shells on -TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2 -shows this documentation and you can reach it with @kbd{ctrl-alt-f2}. -Documentation is browsable using the Info reader commands (@pxref{Top,,, -info-stnd, Stand-alone GNU Info}). The installation system runs the GPM -mouse daemon, which allows you to select text with the left mouse button and -to paste it with the middle button. - -@quotation Note -Installation requires access to the Internet so that any missing -dependencies of your system configuration can be downloaded. See the -``Networking'' section below. -@end quotation - -@node Guided Graphical Installation -@section Guided Graphical Installation - -The graphical installer is a text-based user interface. It will guide you, -with dialog boxes, through the steps needed to install GNU@tie{}Guix System. - -The first dialog boxes allow you to set up the system as you use it during -the installation: you can choose the language, keyboard layout, and set up -networking, which will be used during the installation. The image below -shows the networking dialog. - -@image{images/installer-network,5in,, networking setup with the graphical -installer} - -Later steps allow you to partition your hard disk, as shown in the image -below, to choose whether or not to use encrypted file systems, to enter the -host name and root password, and to create an additional account, among -other things. - -@image{images/installer-partitions,5in,, partitioning with the graphical -installer} - -Note that, at any time, the installer allows you to exit the current -installation step and resume at a previous step, as show in the image below. - -@image{images/installer-resume,5in,, resuming the installation process} - -Once you're done, the installer produces an operating system configuration -and displays it (@pxref{Using the Configuration System}). At that point you -can hit ``OK'' and installation will proceed. On success, you can reboot -into the new system and enjoy. @xref{After System Installation}, for what's -next! - - -@node Manual Installation -@section Manual Installation - -This section describes how you would ``manually'' install GNU@tie{}Guix -System on your machine. This option requires familiarity with GNU/Linux, -with the shell, and with common administration tools. If you think this is -not for you, consider using the guided graphical installer (@pxref{Guided -Graphical Installation}). - -The installation system provides root shells on TTYs 3 to 6; press -@kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them. It includes -many common tools needed to install the system. But it is also a full-blown -Guix System, which means that you can install additional packages, should -you need it, using @command{guix package} (@pxref{Invoking guix package}). - -@menu -* Keyboard Layout and Networking and Partitioning:: Initial setup. -* Proceeding with the Installation:: Installing. -@end menu - -@node Keyboard Layout and Networking and Partitioning -@subsection Keyboard Layout, Networking, and Partitioning - -Before you can install the system, you may want to adjust the keyboard -layout, set up networking, and partition your target hard disk. This -section will guide you through this. - -@subsubsection Keyboard Layout - -@cindex keyboard layout -The installation image uses the US qwerty keyboard layout. If you want to -change it, you can use the @command{loadkeys} command. For example, the -following command selects the Dvorak keyboard layout: - -@example -loadkeys dvorak -@end example - -See the files under @file{/run/current-system/profile/share/keymaps} for a -list of available keyboard layouts. Run @command{man loadkeys} for more -information. - -@subsubsection Networking - -Run the following command to see what your network interfaces are called: - -@example -ifconfig -a -@end example - -@noindent -@dots{} or, using the GNU/Linux-specific @command{ip} command: - -@example -ip a -@end example - -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 -Wired interfaces have a name starting with @samp{e}; for example, the -interface corresponding to the first on-board Ethernet controller is called -@samp{eno1}. Wireless interfaces have a name starting with @samp{w}, like -@samp{w1p2s0}. - -@table @asis -@item Wired connection -To configure a wired network run the following command, substituting -@var{interface} with the name of the wired interface you want to use. - -@example -ifconfig @var{interface} up -@end example - -@item Wireless connection -@cindex wireless -@cindex WiFi -To configure wireless networking, you can create a configuration file for -the @command{wpa_supplicant} configuration tool (its location is not -important) using one of the available text editors such as @command{nano}: - -@example -nano wpa_supplicant.conf -@end example - -As an example, the following stanza can go to this file and will work for -many wireless networks, provided you give the actual SSID and passphrase for -the network you are connecting to: - -@example -network=@{ - ssid="@var{my-ssid}" - key_mgmt=WPA-PSK - psk="the network's secret passphrase" -@} -@end example - -Start the wireless service and run it in the background with the following -command (substitute @var{interface} with the name of the network interface -you want to use): - -@example -wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B -@end example - -Run @command{man wpa_supplicant} for more information. -@end table - -@cindex DHCP -At this point, you need to acquire an IP address. On a network where IP -addresses are automatically assigned @i{via} DHCP, you can run: - -@example -dhclient -v @var{interface} -@end example - -Try to ping a server to see if networking is up and running: - -@example -ping -c 3 gnu.org -@end example - -Setting up network access is almost always a requirement because the image -does not contain all the software and tools that may be needed. - -@cindex installing over SSH -If you want to, you can continue the installation remotely by starting an -SSH server: - -@example -herd start ssh-daemon -@end example - -Make sure to either set a password with @command{passwd}, or configure -OpenSSH public key authentication before logging in. - -@subsubsection Disk Partitioning - -Unless this has already been done, the next step is to partition, and then -format the target partition(s). - -The installation image includes several partitioning tools, including Parted -(@pxref{Overview,,, parted, GNU Parted User Manual}), @command{fdisk}, and -@command{cfdisk}. Run it and set up your disk with the partition layout you -want: - -@example -cfdisk -@end example - -If your disk uses the GUID Partition Table (GPT) format and you plan to -install BIOS-based GRUB (which is the default), make sure a BIOS Boot -Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB manual}). - -@cindex EFI, installation -@cindex UEFI, installation -@cindex ESP, EFI system partition -If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System -Partition} (ESP) is required. This partition can be mounted at -@file{/boot/efi} for instance and must have the @code{esp} flag set. E.g., -for @command{parted}: - -@example -parted /dev/sda set 1 esp on -@end example - -@quotation Note -@vindex grub-bootloader -@vindex grub-efi-bootloader -Unsure whether to use EFI- or BIOS-based GRUB? If the directory -@file{/sys/firmware/efi} exists in the installation image, then you should -probably perform an EFI installation, using @code{grub-efi-bootloader}. -Otherwise you should use the BIOS-based GRUB, known as -@code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on -bootloaders. -@end quotation - -Once you are done partitioning the target hard disk drive, you have to -create a file system on the relevant partition(s)@footnote{Currently Guix -System only supports ext4 and btrfs file systems. In particular, code that -reads file system UUIDs and labels only works for these file system -types.}. For the ESP, if you have one and assuming it is @file{/dev/sda1}, -run: - -@example -mkfs.fat -F32 /dev/sda1 -@end example - -Preferably, assign file systems a label so that you can easily and reliably -refer to them in @code{file-system} declarations (@pxref{File Systems}). -This is typically done using the @code{-L} option of @command{mkfs.ext4} and -related commands. So, assuming the target root partition lives at -@file{/dev/sda2}, a file system with the label @code{my-root} can be created -with: - -@example -mkfs.ext4 -L my-root /dev/sda2 -@end example - -@cindex encrypted disk -If you are instead planning to encrypt the root partition, you can use the -Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html, -@uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}}, -@code{man cryptsetup}} for more information.) Assuming you want to store -the root partition on @file{/dev/sda2}, the command sequence would be along -these lines: - -@example -cryptsetup luksFormat /dev/sda2 -cryptsetup open --type luks /dev/sda2 my-partition -mkfs.ext4 -L my-root /dev/mapper/my-partition -@end example - -Once that is done, mount the target file system under @file{/mnt} with a -command like (again, assuming @code{my-root} is the label of the root file -system): - -@example -mount LABEL=my-root /mnt -@end example - -Also mount any other file systems you would like to use on the target system -relative to this path. If you have opted for @file{/boot/efi} as an EFI -mount point for example, mount it at @file{/mnt/boot/efi} now so it is found -by @code{guix system init} afterwards. - -Finally, if you plan to use one or more swap partitions (@pxref{Memory -Concepts, swap space,, libc, The GNU C Library Reference Manual}), make sure -to initialize them with @command{mkswap}. Assuming you have one swap -partition on @file{/dev/sda3}, you would run: - -@example -mkswap /dev/sda3 -swapon /dev/sda3 -@end example - -Alternatively, you may use a swap file. For example, assuming that in the -new system you want to use the file @file{/swapfile} as a swap file, you -would run@footnote{This example will work for many types of file systems -(e.g., ext4). However, for copy-on-write file systems (e.g., btrfs), the -required steps may be different. For details, see the manual pages for -@command{mkswap} and @command{swapon}.}: - -@example -# This is 10 GiB of swap space. Adjust "count" to change the size. -dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240 -# For security, make the file readable and writable only by root. -chmod 600 /mnt/swapfile -mkswap /mnt/swapfile -swapon /mnt/swapfile -@end example - -Note that if you have encrypted the root partition and created a swap file -in its file system as described above, then the encryption also protects the -swap file, just like any other file in that file system. - -@node Proceeding with the Installation -@subsection Proceeding with the Installation - -With the target partitions ready and the target root mounted on @file{/mnt}, -we're ready to go. First, run: - -@example -herd start cow-store /mnt -@end example - -This makes @file{/gnu/store} copy-on-write, such that packages added to it -during the installation phase are written to the target disk on @file{/mnt} -rather than kept in memory. This is necessary because the first phase of -the @command{guix system init} command (see below) entails downloads or -builds to @file{/gnu/store} which, initially, is an in-memory file system. - -Next, you have to edit a file and provide the declaration of the operating -system to be installed. To that end, the installation system comes with -three text editors. We recommend GNU nano (@pxref{Top,,, nano, GNU nano -Manual}), which supports syntax highlighting and parentheses matching; other -editors include GNU Zile (an Emacs clone), and nvi (a clone of the original -BSD @command{vi} editor). We strongly recommend storing that file on the -target root file system, say, as @file{/mnt/etc/config.scm}. Failing to do -that, you will have lost your configuration file once you have rebooted into -the newly-installed system. - -@xref{Using the Configuration System}, for an overview of the configuration -file. The example configurations discussed in that section are available -under @file{/etc/configuration} in the installation image. Thus, to get -started with a system configuration providing a graphical display server (a -``desktop'' system), you can run something along these lines: - -@example -# mkdir /mnt/etc -# cp /etc/configuration/desktop.scm /mnt/etc/config.scm -# nano /mnt/etc/config.scm -@end example - -You should pay attention to what your configuration file contains, and in -particular: - -@itemize -@item -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 to a mounted -EFI partition, like @code{/boot/efi}; do make sure the path is currently -mounted and a @code{file-system} entry is specified in your configuration. - -@item -Be sure that your file system labels match the value of their respective -@code{device} fields in your @code{file-system} configuration, assuming your -@code{file-system} configuration uses the @code{file-system-label} procedure -in its @code{device} field. - -@item -If there are encrypted or RAID partitions, make sure to add a -@code{mapped-devices} field to describe them (@pxref{Mapped Devices}). -@end itemize - -Once you are done preparing the configuration file, the new system must be -initialized (remember that the target root file system is mounted under -@file{/mnt}): - -@example -guix system init /mnt/etc/config.scm /mnt -@end example - -@noindent -This copies all the necessary files and installs GRUB on @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. - -Once that command has completed---and hopefully succeeded!---you can run -@command{reboot} and boot into the new system. The @code{root} password in -the new system is initially empty; other users' passwords need to be -initialized by running the @command{passwd} command as @code{root}, unless -your configuration specifies otherwise (@pxref{user-account-password, user -account passwords}). @xref{After System Installation}, for what's next! - - -@node After System Installation -@section After System Installation - -Success, you've now booted into Guix System! From then on, you can update -the system whenever you want by running, say: - -@example -guix pull -sudo guix system reconfigure /etc/config.scm -@end example - -@noindent -This builds a new system generation with the latest packages and services -(@pxref{Invoking guix system}). We recommend doing that regularly so that -your system includes the latest security updates (@pxref{Security Updates}). - -@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. -@quotation Note -@cindex sudo vs. @command{guix pull} -Note that @command{sudo guix} runs your user's @command{guix} command and -@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To -explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. -@end quotation - -Join us on @code{#guix} on the Freenode IRC network or on -@email{guix-devel@@gnu.org} to share your experience! - - -@node Installing Guix in a VM -@section Installing Guix in a Virtual Machine - -@cindex virtual machine, Guix System installation -@cindex virtual private server (VPS) -@cindex VPS (virtual private server) -If you'd like to install Guix System in a virtual machine (VM) or on a -virtual private server (VPS) rather than on your beloved machine, this -section is for you. - -To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a -disk image, follow these steps: - -@enumerate -@item -First, retrieve and decompress the Guix system installation image as -described previously (@pxref{USB Stick and DVD Installation}). - -@item -Create a disk image that will hold the installed system. To make a -qcow2-formatted disk image, use the @command{qemu-img} command: - -@example -qemu-img create -f qcow2 guixsd.img 50G -@end example - -The resulting file will be much smaller than 50 GB (typically less than 1 -MB), but it will grow as the virtualized storage device is filled up. - -@item -Boot the USB installation image in an VM: - -@example -qemu-system-x86_64 -m 1024 -smp 1 \ - -net user -net nic,model=virtio -boot menu=on \ - -drive file=guix-system-install-@value{VERSION}.@var{system}.iso \ - -drive file=guixsd.img -@end example - -The ordering of the drives matters. - -In the VM console, quickly press the @kbd{F12} key to enter the boot menu. -Then press the @kbd{2} key and the @kbd{RET} key to validate your selection. - -@item -You're now root in the VM, proceed with the installation process. -@xref{Preparing for Installation}, and follow the instructions. -@end enumerate - -Once installation is complete, you can boot the system that's on your -@file{guixsd.img} image. @xref{Running Guix in a VM}, for how to do that. - -@node Building the Installation Image -@section Building the Installation Image - -@cindex installation image -The installation image described above was built using the @command{guix -system} command, specifically: - -@example -guix system disk-image --file-system-type=iso9660 \ - gnu/system/install.scm -@end example - -Have a look at @file{gnu/system/install.scm} in the source tree, and see -also @ref{Invoking guix system} for more information about the installation -image. - -@section Building the Installation Image for ARM Boards - -Many ARM boards require a specific variant of the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader. - -If you build a disk image and the bootloader is not available otherwise (on -another boot drive etc), it's advisable to build an image that includes the -bootloader, specifically: - -@example -guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")' -@end example - -@code{A20-OLinuXino-Lime2} is the name of the board. If you specify an -invalid board, a list of possible boards will be printed. - -@c ********************************************************************* -@node Package Management -@chapter Package Management - -@cindex packages -The purpose of GNU Guix is to allow users to easily install, upgrade, and -remove software packages, without having to know about their build -procedures or dependencies. Guix also goes beyond this obvious set of -features. - -This chapter describes the main features of Guix, as well as the package -management tools it provides. Along with the command-line interface -described below (@pxref{Invoking guix package, @code{guix package}}), you -may also use 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): - -@example -guix package -i emacs-guix -@end example - -@menu -* Features:: How Guix will make your life brighter. -* Invoking guix package:: Package installation, removal, etc. -* Substitutes:: Downloading pre-built binaries. -* 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. -* Channels:: Customizing the package collection. -* Inferiors:: Interacting with another revision of Guix. -* Invoking guix describe:: Display information about your Guix revision. -* Invoking guix archive:: Exporting and importing store files. -@end menu - -@node Features -@section Features - -When using Guix, each package ends up in the @dfn{package store}, in its own -directory---something that resembles @file{/gnu/store/xxx-package-1.2}, -where @code{xxx} is a base32 string. - -Instead of referring to these directories, users have their own -@dfn{profile}, which points to the packages that they actually want to use. -These profiles are stored within each user's home directory, at -@code{$HOME/.guix-profile}. - -For example, @code{alice} installs GCC 4.7.2. As a result, -@file{/home/alice/.guix-profile/bin/gcc} points to -@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine, -@code{bob} had already installed GCC 4.8.0. The profile of @code{bob} -simply continues to point to -@file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC -coexist on the same system without any interference. - -The @command{guix package} command is the central tool to manage packages -(@pxref{Invoking guix package}). It operates on the per-user profiles, and -can be used @emph{with normal user privileges}. - -@cindex transactions -The command provides the obvious install, remove, and upgrade operations. -Each invocation is actually a @emph{transaction}: either the specified -operation succeeds, or nothing happens. Thus, if the @command{guix package} -process is terminated during the transaction, or if a power outage occurs -during the transaction, then the user's profile remains in its previous -state, and remains usable. - -In addition, any package transaction may be @emph{rolled back}. So, if, for -example, an upgrade installs a new version of a package that turns out to -have a serious bug, users may roll back to the previous instance of their -profile, which was known to work well. Similarly, the global system -configuration on Guix is subject to transactional upgrades and roll-back -(@pxref{Using the Configuration System}). - -All packages in the package store may be @emph{garbage-collected}. Guix can -determine which packages are still referenced by user profiles, and remove -those that are provably no longer referenced (@pxref{Invoking guix gc}). -Users may also explicitly remove old generations of their profile so that -the packages they refer to can be collected. - -@cindex reproducibility -@cindex reproducible builds -Guix takes a @dfn{purely functional} approach to package management, as -described in the introduction (@pxref{Introduction}). Each -@file{/gnu/store} package directory name contains a hash of all the inputs -that were used to build that package---compiler, libraries, build scripts, -etc. This direct correspondence allows users to make sure a given package -installation matches the current state of their distribution. It also helps -maximize @dfn{build reproducibility}: thanks to the isolated build -environments that are used, a given build is likely to yield bit-identical -files when performed on different machines (@pxref{Invoking guix-daemon, -container}). - -@cindex substitutes -This foundation allows Guix to support @dfn{transparent binary/source -deployment}. When a pre-built binary for a @file{/gnu/store} item is -available from an external source---a @dfn{substitute}, Guix just downloads -it and unpacks it; otherwise, it builds the package from source, locally -(@pxref{Substitutes}). Because build results are usually bit-for-bit -reproducible, users do not have to trust servers that provide substitutes: -they can force a local build and @emph{challenge} providers (@pxref{Invoking -guix challenge}). - -Control over the build environment is a feature that is also useful for -developers. The @command{guix environment} command allows developers of a -package to quickly set up the right development environment for their -package, without having to manually install the dependencies of the package -into their profile (@pxref{Invoking guix environment}). - -@cindex replication, of software environments -@cindex provenance tracking, of software artifacts -All of Guix and its package definitions is version-controlled, and -@command{guix pull} allows you to ``travel in time'' on the history of Guix -itself (@pxref{Invoking guix pull}). This makes it possible to replicate a -Guix instance on a different machine or at a later point in time, which in -turn allows you to @emph{replicate complete software environments}, while -retaining precise @dfn{provenance tracking} of the software. - -@node Invoking guix package -@section Invoking @command{guix package} - -@cindex installing packages -@cindex removing packages -@cindex package installation -@cindex package removal -The @command{guix package} command is the tool that allows users to install, -upgrade, and remove packages, as well as rolling back to previous -configurations. It operates only on the user's own profile, and works with -normal user privileges (@pxref{Features}). Its syntax is: - -@example -guix package @var{options} -@end example -@cindex transactions -Primarily, @var{options} specifies the operations to be performed during the -transaction. Upon completion, a new profile is created, but previous -@dfn{generations} of the profile remain available, should the user want to -roll back. - -For example, to remove @code{lua} and install @code{guile} and -@code{guile-cairo} in a single transaction: - -@example -guix package -r lua -i guile guile-cairo -@end example - -@command{guix package} also supports a @dfn{declarative approach} whereby -the user specifies the exact set of packages to be available and passes it -@i{via} the @option{--manifest} option (@pxref{profile-manifest, -@option{--manifest}}). - -@cindex profile -For each user, a symlink to the user's default profile is automatically -created in @file{$HOME/.guix-profile}. This symlink always points to the -current generation of the user's default profile. Thus, users can add -@file{$HOME/.guix-profile/bin} to their @code{PATH} environment variable, -and so on. -@cindex search paths -If you are not using the Guix System Distribution, consider adding the -following lines to your @file{~/.bash_profile} (@pxref{Bash Startup Files,,, -bash, The GNU Bash Reference Manual}) so that newly-spawned shells get all -the right environment variable definitions: - -@example -GUIX_PROFILE="$HOME/.guix-profile" ; \ -source "$HOME/.guix-profile/etc/profile" -@end example - -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}/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 started, -and the @var{user} sub-directory is created by @command{guix package}. - -The @var{options} can be among the following: - -@table @code - -@item --install=@var{package} @dots{} -@itemx -i @var{package} @dots{} -Install the specified @var{package}s. - -Each @var{package} may specify either a simple package name, such as -@code{guile}, or a package name followed by an at-sign and version number, -such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter case, -the newest version prefixed by @code{1.8} is selected.) - -If no version number is specified, the newest available version will be -selected. In addition, @var{package} may contain a colon, followed by the -name of one of the outputs of the package, as in @code{gcc:doc} or -@code{binutils@@2.22:lib} (@pxref{Packages with Multiple Outputs}). -Packages with a corresponding name (and optionally version) are searched for -among the GNU distribution modules (@pxref{Package Modules}). - -@cindex propagated inputs -Sometimes packages have @dfn{propagated inputs}: these are dependencies that -automatically get installed along with the required package -(@pxref{package-propagated-inputs, @code{propagated-inputs} in -@code{package} objects}, for information about propagated inputs in package -definitions). - -@anchor{package-cmd-propagated-inputs} -An example is the GNU MPC library: its C header files refer to those of the -GNU MPFR library, which in turn refer to those of the GMP library. Thus, -when installing MPC, the MPFR and GMP libraries also get installed in the -profile; removing MPC also removes MPFR and GMP---unless they had also been -explicitly installed by the user. - -Besides, packages sometimes rely on the definition of environment variables -for their search paths (see explanation of @code{--search-paths} below). -Any missing or possibly incorrect environment variable definitions are -reported here. - -@item --install-from-expression=@var{exp} -@itemx -e @var{exp} -Install the package @var{exp} evaluates to. - -@var{exp} must be a Scheme expression that evaluates to a @code{<package>} -object. This option is notably useful to disambiguate between same-named -variants of a package, with expressions such as @code{(@@ (gnu packages -base) guile-final)}. - -Note that this option installs the first output of the specified package, -which may be insufficient when needing a specific output of a -multiple-output package. - -@item --install-from-file=@var{file} -@itemx -f @var{file} -Install the package that the code within @var{file} evaluates to. - -As an example, @var{file} might contain a definition like this -(@pxref{Defining Packages}): - -@example -@verbatiminclude package-hello.scm -@end example - -Developers may find it useful to include such a @file{guix.scm} file in the -root of their project source tree that can be used to test development -snapshots and create reproducible development environments (@pxref{Invoking -guix environment}). - -@item --remove=@var{package} @dots{} -@itemx -r @var{package} @dots{} -Remove the specified @var{package}s. - -As for @code{--install}, each @var{package} may specify a version number -and/or output name in addition to the package name. For instance, @code{-r -glibc:debug} would remove the @code{debug} output of @code{glibc}. - -@item --upgrade[=@var{regexp} @dots{}] -@itemx -u [@var{regexp} @dots{}] -@cindex upgrading packages -Upgrade all the installed packages. If one or more @var{regexp}s are -specified, upgrade only installed packages whose name matches a -@var{regexp}. Also see the @code{--do-not-upgrade} option below. - -Note that this upgrades package to the latest version of packages found in -the distribution currently installed. To update your distribution, you -should regularly run @command{guix pull} (@pxref{Invoking guix pull}). - -@item --do-not-upgrade[=@var{regexp} @dots{}] -When used together with the @code{--upgrade} option, do @emph{not} upgrade -any packages whose name matches a @var{regexp}. For example, to upgrade all -packages in the current profile except those containing the substring -``emacs'': - -@example -$ guix package --upgrade . --do-not-upgrade emacs -@end example - -@item @anchor{profile-manifest}--manifest=@var{file} -@itemx -m @var{file} -@cindex profile declaration -@cindex profile manifest -Create a new generation of the profile from the manifest object returned by -the Scheme code in @var{file}. - -This allows you to @emph{declare} the profile's contents rather than -constructing it through a sequence of @code{--install} and similar -commands. The advantage is that @var{file} can be put under version -control, copied to different machines to reproduce the same profile, and so -on. - -@c FIXME: Add reference to (guix profile) documentation when available. -@var{file} must return a @dfn{manifest} object, which is roughly a list of -packages: - -@findex packages->manifest -@example -(use-package-modules guile emacs) - -(packages->manifest - (list emacs - guile-2.0 - ;; Use a specific package output. - (list guile-2.0 "debug"))) -@end example - -@findex specifications->manifest -In this example we have to know which modules define the @code{emacs} and -@code{guile-2.0} variables to provide the right @code{use-package-modules} -line, which can be cumbersome. We can instead provide regular package -specifications and let @code{specifications->manifest} look up the -corresponding package objects, like this: - -@example -(specifications->manifest - '("emacs" "guile@@2.2" "guile@@2.2:debug")) -@end example - -@item --roll-back -@cindex rolling back -@cindex undoing transactions -@cindex transactions, undoing -Roll back to the previous @dfn{generation} of the profile---i.e., undo the -last transaction. - -When combined with options such as @code{--install}, roll back occurs before -any other actions. - -When rolling back from the first generation that actually contains installed -packages, the profile is made to point to the @dfn{zeroth generation}, which -contains no files apart from its own metadata. - -After having rolled back, installing, removing, or upgrading packages -overwrites previous future generations. Thus, the history of the -generations in a profile is always linear. - -@item --switch-generation=@var{pattern} -@itemx -S @var{pattern} -@cindex generations -Switch to a particular generation defined by @var{pattern}. - -@var{pattern} may be either a generation number or a number prefixed with -``+'' or ``-''. The latter means: move forward/backward by a specified -number of generations. For example, if you want to return to the latest -generation after @code{--roll-back}, use @code{--switch-generation=+1}. - -The difference between @code{--roll-back} and @code{--switch-generation=-1} -is that @code{--switch-generation} will not make a zeroth generation, so if -a specified generation does not exist, the current generation will not be -changed. - -@item --search-paths[=@var{kind}] -@cindex search paths -Report environment variable definitions, in Bash syntax, that may be needed -in order to use the set of installed packages. These environment variables -are used to specify @dfn{search paths} for files used by some of the -installed packages. - -For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH} environment -variables to be defined so it can look for headers and libraries in the -user's profile (@pxref{Environment Variables,,, gcc, Using the GNU Compiler -Collection (GCC)}). If GCC and, say, the C library are installed in the -profile, then @code{--search-paths} will suggest setting these variables to -@code{@var{profile}/include} and @code{@var{profile}/lib}, respectively. - -The typical use case is to define these environment variables in the shell: - -@example -$ eval `guix package --search-paths` -@end example - -@var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix}, -meaning that the returned environment variable definitions will either be -exact settings, or prefixes or suffixes of the current value of these -variables. When omitted, @var{kind} defaults to @code{exact}. - -This option can also be used to compute the @emph{combined} search paths of -several profiles. Consider this example: - -@example -$ guix package -p foo -i guile -$ guix package -p bar -i guile-json -$ guix package -p foo -p bar --search-paths -@end example - -The last command above reports about the @code{GUILE_LOAD_PATH} variable, -even though, taken individually, neither @file{foo} nor @file{bar} would -lead to that recommendation. - - -@item --profile=@var{profile} -@itemx -p @var{profile} -Use @var{profile} instead of the user's default profile. - -@cindex collisions, in a profile -@cindex colliding packages in profiles -@cindex profile collisions -@item --allow-collisions -Allow colliding packages in the new profile. Use at your own risk! - -By default, @command{guix package} reports as an error @dfn{collisions} in -the profile. Collisions happen when two or more different versions or -variants of a given package end up in the profile. - -@item --bootstrap -Use the bootstrap Guile to build the profile. This option is only useful to -distribution developers. - -@end table - -In addition to these actions, @command{guix package} supports the following -options to query the current state of a profile, or the availability of -packages: - -@table @option - -@item --search=@var{regexp} -@itemx -s @var{regexp} -@cindex searching for packages -List the available packages whose name, synopsis, or description matches -@var{regexp} (in a case-insensitive fashion), sorted by relevance. Print -all the metadata of matching packages in @code{recutils} format (@pxref{Top, -GNU recutils databases,, recutils, GNU recutils manual}). - -This allows specific fields to be extracted using the @command{recsel} -command, for instance: - -@example -$ guix package -s malloc | recsel -p name,version,relevance -name: jemalloc -version: 4.5.0 -relevance: 6 - -name: glibc -version: 2.25 -relevance: 1 - -name: libgc -version: 7.6.0 -relevance: 1 -@end example - -Similarly, to show the name of all the packages available under the terms of -the GNU@tie{}LGPL version 3: - -@example -$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' -name: elfutils - -name: gmp -@dots{} -@end example - -It is also possible to refine search results using several @code{-s} flags. -For example, the following command returns a list of board games: - -@example -$ guix package -s '\<board\>' -s game | recsel -p name -name: gnubg -@dots{} -@end example - -If we were to omit @code{-s game}, we would also get software packages that -deal with printed circuit boards; removing the angle brackets around -@code{board} would further add packages that have to do with keyboards. - -And now for a more elaborate example. The following command searches for -cryptographic libraries, filters out Haskell, Perl, Python, and Ruby -libraries, and prints the name and synopsis of the matching packages: - -@example -$ guix package -s crypto -s library | \ - recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis -@end example - -@noindent -@xref{Selection Expressions,,, recutils, GNU recutils manual}, for more -information on @dfn{selection expressions} for @code{recsel -e}. - -@item --show=@var{package} -Show details about @var{package}, taken from the list of available packages, -in @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, -GNU recutils manual}). - -@example -$ guix package --show=python | recsel -p name,version -name: python -version: 2.7.6 - -name: python -version: 3.3.5 -@end example - -You may also specify the full name of a package to only get details about a -specific version of it: -@example -$ guix package --show=python@@3.4 | recsel -p name,version -name: python -version: 3.4.3 -@end example - - - -@item --list-installed[=@var{regexp}] -@itemx -I [@var{regexp}] -List the currently installed packages in the specified profile, with the -most recently installed packages shown last. When @var{regexp} is -specified, list only installed packages whose name matches @var{regexp}. - -For each installed package, print the following items, separated by tabs: -the package name, its version string, the part of the package that is -installed (for instance, @code{out} for the default output, @code{include} -for its headers, etc.), and the path of this package in the store. - -@item --list-available[=@var{regexp}] -@itemx -A [@var{regexp}] -List packages currently available in the distribution for this system -(@pxref{GNU Distribution}). When @var{regexp} is specified, list only -installed packages whose name matches @var{regexp}. - -For each package, print the following items separated by tabs: its name, its -version string, the parts of the package (@pxref{Packages with Multiple -Outputs}), and the source location of its definition. - -@item --list-generations[=@var{pattern}] -@itemx -l [@var{pattern}] -@cindex generations -Return a list of generations along with their creation dates; for each -generation, show the installed packages, with the most recently installed -packages shown last. Note that the zeroth generation is never shown. - -For each installed package, print the following items, separated by tabs: -the name of a package, its version string, the part of the package that is -installed (@pxref{Packages with Multiple Outputs}), and the location of this -package in the store. - -When @var{pattern} is used, the command returns only matching generations. -Valid patterns include: - -@itemize -@item @emph{Integers and comma-separated integers}. Both patterns denote -generation numbers. For instance, @code{--list-generations=1} returns the -first one. - -And @code{--list-generations=1,8,2} outputs three generations in the -specified order. Neither spaces nor trailing commas are allowed. - -@item @emph{Ranges}. @code{--list-generations=2..9} prints the -specified generations and everything in between. Note that the start of a -range must be smaller than its end. - -It is also possible to omit the endpoint. For example, -@code{--list-generations=2..}, returns all generations starting from the -second one. - -@item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks, -or months by passing an integer along with the first letter of the -duration. For example, @code{--list-generations=20d} lists generations that -are up to 20 days old. -@end itemize - -@item --delete-generations[=@var{pattern}] -@itemx -d [@var{pattern}] -When @var{pattern} is omitted, delete all generations except the current -one. - -This command accepts the same patterns as @option{--list-generations}. When -@var{pattern} is specified, delete the matching generations. When -@var{pattern} specifies a duration, generations @emph{older} than the -specified duration match. For instance, @code{--delete-generations=1m} -deletes generations that are more than one month old. - -If the current generation matches, it is @emph{not} deleted. Also, the -zeroth generation is never deleted. - -Note that deleting generations prevents rolling back to them. Consequently, -this command must be used with care. - -@end table - -Finally, since @command{guix package} may actually start build processes, it -supports all the common build options (@pxref{Common Build Options}). It -also supports package transformation options, such as @option{--with-source} -(@pxref{Package Transformation Options}). However, note that package -transformations are lost when upgrading; to preserve transformations across -upgrades, you should define your own package variant in a Guile module and -add it to @code{GUIX_PACKAGE_PATH} (@pxref{Defining Packages}). - -@node Substitutes -@section Substitutes - -@cindex substitutes -@cindex pre-built binaries -Guix supports transparent source/binary deployment, which means that it can -either build things locally, or download pre-built items from a server, or -both. We call these pre-built items @dfn{substitutes}---they are -substitutes for local build results. In many cases, downloading a -substitute is much faster than building things locally. - -Substitutes can be anything resulting from a derivation build -(@pxref{Derivations}). Of course, in the common case, they are pre-built -package binaries, but source tarballs, for instance, which also result from -derivation builds, can be available as substitutes. - -@menu -* Official Substitute Server:: One particular source of substitutes. -* Substitute Server Authorization:: How to enable or disable substitutes. -* Substitute Authentication:: How Guix verifies substitutes. -* Proxy Settings:: How to get substitutes via proxy. -* Substitution Failure:: What happens when substitution fails. -* On Trusting Binaries:: How can you trust that binary blob? -@end menu - -@node Official Substitute Server -@subsection Official Substitute Server - -@cindex hydra -@cindex build farm -The @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an official -build farm that builds packages from Guix continuously for some -architectures, and makes them available as substitutes. This is the default -source of substitutes; it can be overridden by passing the -@option{--substitute-urls} option either to @command{guix-daemon} -(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) or -to client tools such as @command{guix package} -(@pxref{client-substitute-urls,, client @option{--substitute-urls} option}). - -Substitute URLs can be either HTTP or HTTPS. 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 your system has unpatched -security vulnerabilities. - -Substitutes from the official build farm are enabled by default when using -the Guix System Distribution (@pxref{GNU Distribution}). However, they are -disabled by default when using Guix on a foreign distribution, unless you -have explicitly enabled them via one of the recommended installation steps -(@pxref{Installation}). The following paragraphs describe how to enable or -disable substitutes for the official build farm; the same procedure can also -be used to enable substitutes for any other substitute server. - -@node Substitute Server Authorization -@subsection Substitute Server Authorization - -@cindex security -@cindex substitutes, authorization thereof -@cindex access control list (ACL), for substitutes -@cindex ACL (access control list), for substitutes -To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} -or a mirror thereof, you must add its public key to the access control list -(ACL) of archive imports, using the @command{guix archive} command -(@pxref{Invoking guix archive}). Doing so implies that you trust -@code{@value{SUBSTITUTE-SERVER}} to not be compromised and to serve genuine -substitutes. - -The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with -Guix, in @code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where -@var{prefix} is the installation prefix of Guix. If you installed Guix from -source, make sure you checked the GPG signature of -@file{guix-@value{VERSION}.tar.gz}, which contains this public key file. -Then, you can run something like this: - -@example -# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@quotation Note -Similarly, the @file{hydra.gnu.org.pub} file contains the public key of an -independent build farm also run by the project, reachable at -@indicateurl{https://mirror.hydra.gnu.org}. -@end quotation - -Once this is in place, the output of a command like @code{guix build} should -change from something like: - -@example -$ guix build emacs --dry-run -The following derivations would be built: - /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv - /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv - /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv - /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv -@dots{} -@end example - -@noindent -to something like: - -@example -$ guix build emacs --dry-run -112.3 MB would be downloaded: - /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3 - /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d - /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16 - /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7 -@dots{} -@end example - -@noindent -This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are -usable and will be downloaded, when possible, for future builds. - -@cindex substitutes, how to disable -The substitute mechanism can be disabled globally by running -@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invoking -guix-daemon}). It can also be disabled temporarily by passing the -@code{--no-substitutes} option to @command{guix package}, @command{guix -build}, and other command-line tools. - -@node Substitute Authentication -@subsection Substitute Authentication - -@cindex digital signatures -Guix detects and raises an error when attempting to use a substitute that -has been tampered with. Likewise, it ignores substitutes that are not -signed, or that are not signed by one of the keys listed in the ACL. - -There is one exception though: if an unauthorized server provides -substitutes that are @emph{bit-for-bit identical} to those provided by an -authorized server, then the unauthorized server becomes eligible for -downloads. For example, assume we have chosen two substitute servers with -this option: - -@example ---substitute-urls="https://a.example.org https://b.example.org" -@end example - -@noindent -@cindex reproducible builds -If the ACL contains only the key for @code{b.example.org}, and if -@code{a.example.org} happens to serve the @emph{exact same} substitutes, -then Guix will download substitutes from @code{a.example.org} because it -comes first in the list and can be considered a mirror of -@code{b.example.org}. In practice, independent build machines usually -produce the same binaries, thanks to bit-reproducible builds (see below). - -When using HTTPS, the server's X.509 certificate is @emph{not} validated (in -other words, the server is not authenticated), contrary to what HTTPS -clients such as Web browsers usually do. This is because Guix authenticates -substitute information itself, as explained above, which is what we care -about (whereas X.509 certificates are about authenticating bindings between -domain names and public keys.) - -@node Proxy Settings -@subsection Proxy Settings - -@vindex http_proxy -Substitutes are downloaded over HTTP or HTTPS. The @code{http_proxy} -environment variable can be set in the environment of @command{guix-daemon} -and is honored for downloads of substitutes. Note that the value of -@code{http_proxy} in the environment where @command{guix build}, -@command{guix package}, and other client commands are run has -@emph{absolutely no effect}. - -@node Substitution Failure -@subsection Substitution Failure - -Even when a substitute for a derivation is available, sometimes the -substitution attempt will fail. This can happen for a variety of reasons: -the substitute server might be offline, the substitute may recently have -been deleted, the connection might have been interrupted, etc. - -When substitutes are enabled and a substitute for a derivation is available, -but the substitution attempt fails, Guix will attempt to build the -derivation locally depending on whether or not @code{--fallback} was given -(@pxref{fallback-option,, common build option @code{--fallback}}). -Specifically, if @code{--fallback} was omitted, then no local build will be -performed, and the derivation is considered to have failed. However, if -@code{--fallback} was given, then Guix will attempt to build the derivation -locally, and the success or failure of the derivation depends on the success -or failure of the local build. Note that when substitutes are disabled or -no substitute is available for the derivation in question, a local build -will @emph{always} be performed, regardless of whether or not -@code{--fallback} was given. - -To get an idea of how many substitutes are available right now, you can try -running the @command{guix weather} command (@pxref{Invoking guix weather}). -This command provides statistics on the substitutes provided by a server. - -@node On Trusting Binaries -@subsection On Trusting Binaries - -@cindex trust, of pre-built binaries -Today, each individual's control over their own computing is at the mercy of -institutions, corporations, and groups with enough power and determination -to subvert the computing infrastructure and exploit its weaknesses. While -using @code{@value{SUBSTITUTE-SERVER}} substitutes can be convenient, we -encourage users to also build on their own, or even run their own build -farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an interesting -target. One way to help is by publishing the software you build using -@command{guix publish} so that others have one more choice of server to -download substitutes from (@pxref{Invoking guix publish}). - -Guix has the foundations to maximize build reproducibility -(@pxref{Features}). In most cases, independent builds of a given package or -derivation should yield bit-identical results. Thus, through a diverse set -of independent package builds, we can strengthen the integrity of our -systems. The @command{guix challenge} command aims to help users assess -substitute servers, and to assist developers in finding out about -non-deterministic package builds (@pxref{Invoking guix challenge}). -Similarly, the @option{--check} option of @command{guix build} allows users -to check whether previously-installed substitutes are genuine by rebuilding -them locally (@pxref{build-check, @command{guix build --check}}). - -In the future, we want Guix to have support to publish and retrieve binaries -to/from other users, in a peer-to-peer fashion. If you would like to -discuss this project, join us on @email{guix-devel@@gnu.org}. - -@node Packages with Multiple Outputs -@section Packages with Multiple Outputs - -@cindex multiple-output packages -@cindex package outputs -@cindex outputs - -Often, packages defined in Guix have a single @dfn{output}---i.e., the -source package leads to exactly one directory in the store. When running -@command{guix package -i glibc}, one installs the default output of the GNU -libc package; the default output is called @code{out}, but its name can be -omitted as shown in this command. In this particular case, the default -output of @code{glibc} contains all the C header files, shared libraries, -static libraries, Info documentation, and other supporting files. - -Sometimes it is more appropriate to separate the various types of files -produced from a single source package into separate outputs. For instance, -the GLib C library (used by GTK+ and related packages) installs more than -20 MiB of reference documentation as HTML pages. To save space for users -who do not need it, the documentation goes to a separate output, called -@code{doc}. To install the main GLib output, which contains everything but -the documentation, one would run: - -@example -guix package -i glib -@end example - -@cindex documentation -The command to install its documentation is: - -@example -guix package -i glib:doc -@end example - -Some packages install programs with different ``dependency footprints''. -For instance, the WordNet package installs both command-line tools and -graphical user interfaces (GUIs). The former depend solely on the C -library, whereas the latter depend on Tcl/Tk and the underlying X -libraries. In this case, we leave the command-line tools in the default -output, whereas the GUIs are in a separate output. This allows users who do -not need the GUIs to save space. The @command{guix size} command can help -find out about such situations (@pxref{Invoking guix size}). @command{guix -graph} can also be helpful (@pxref{Invoking guix graph}). - -There are several such multiple-output packages in the GNU distribution. -Other conventional output names include @code{lib} for libraries and -possibly header files, @code{bin} for stand-alone programs, and @code{debug} -for debugging information (@pxref{Installing Debugging Files}). The outputs -of a packages are listed in the third column of the output of @command{guix -package --list-available} (@pxref{Invoking guix package}). - - -@node Invoking guix gc -@section Invoking @command{guix gc} - -@cindex garbage collector -@cindex disk space -Packages that are installed, but not used, may be @dfn{garbage-collected}. -The @command{guix gc} command allows users to explicitly run the garbage -collector to reclaim space from the @file{/gnu/store} directory. It is the -@emph{only} way to remove files from @file{/gnu/store}---removing files or -directories manually may break it beyond repair! - -@cindex GC roots -@cindex garbage collector roots -The garbage collector has a set of known @dfn{roots}: any file under -@file{/gnu/store} reachable from a root is considered @dfn{live} and cannot -be deleted; any other file is considered @dfn{dead} and may be deleted. The -set of garbage collector roots (``GC roots'' for short) includes default -user profiles; by default, the symlinks under @file{/var/guix/gcroots} -represent these GC roots. New GC roots can be added with @command{guix -build --root}, for example (@pxref{Invoking guix build}). The @command{guix -gc --list-roots} command lists them. - -Prior to running @code{guix gc --collect-garbage} to make space, it is often -useful to remove old generations from user profiles; that way, old package -builds referenced by those generations can be reclaimed. This is achieved -by running @code{guix package --delete-generations} (@pxref{Invoking guix -package}). - -Our recommendation is to run a garbage collection periodically, or when you -are short on disk space. For instance, to guarantee that at least 5@tie{}GB -are available on your disk, simply run: - -@example -guix gc -F 5G -@end example - -It is perfectly safe to run as a non-interactive periodic job -(@pxref{Scheduled Job Execution}, for how to set up such a job). Running -@command{guix gc} with no arguments will collect as much garbage as it can, -but that is often inconvenient: you may find yourself having to rebuild or -re-download software that is ``dead'' from the GC viewpoint but that is -necessary to build other pieces of software---e.g., the compiler tool chain. - -The @command{guix gc} command has three modes of operation: it can be used -to garbage-collect any dead files (the default), to delete specific files -(the @code{--delete} option), to print garbage-collector information, or for -more advanced queries. The garbage collection options are as follows: - -@table @code -@item --collect-garbage[=@var{min}] -@itemx -C [@var{min}] -Collect garbage---i.e., unreachable @file{/gnu/store} files and -sub-directories. This is the default operation when no option is specified. - -When @var{min} is given, stop once @var{min} bytes have been collected. -@var{min} may be a number of bytes, or it may include a unit as a suffix, -such as @code{MiB} for mebibytes and @code{GB} for gigabytes (@pxref{Block -size, size specifications,, coreutils, GNU Coreutils}). - -When @var{min} is omitted, collect all the garbage. - -@item --free-space=@var{free} -@itemx -F @var{free} -Collect garbage until @var{free} space is available under @file{/gnu/store}, -if possible; @var{free} denotes storage space, such as @code{500MiB}, as -described above. - -When @var{free} or more is already available in @file{/gnu/store}, do -nothing and exit immediately. - -@item --delete-generations[=@var{duration}] -@itemx -d [@var{duration}] -Before starting the garbage collection process, delete all the generations -older than @var{duration}, for all the user profiles; when run as root, this -applies to all the profiles @emph{of all the users}. - -For example, this command deletes all the generations of all your profiles -that are older than 2 months (except generations that are current), and then -proceeds to free space until at least 10 GiB are available: - -@example -guix gc -d 2m -F 10G -@end example - -@item --delete -@itemx -D -Attempt to delete all the store files and directories specified as -arguments. This fails if some of the files are not in the store, or if they -are still live. - -@item --list-failures -List store items corresponding to cached build failures. - -This prints nothing unless the daemon was started with -@option{--cache-failures} (@pxref{Invoking guix-daemon, -@option{--cache-failures}}). - -@item --list-roots -List the GC roots owned by the user; when run as root, list @emph{all} the -GC roots. - -@item --clear-failures -Remove the specified store items from the failed-build cache. - -Again, this option only makes sense when the daemon is started with -@option{--cache-failures}. Otherwise, it does nothing. - -@item --list-dead -Show the list of dead files and directories still present in the -store---i.e., files and directories no longer reachable from any root. - -@item --list-live -Show the list of live store files and directories. - -@end table - -In addition, the references among existing store files can be queried: - -@table @code - -@item --references -@itemx --referrers -@cindex package dependencies -List the references (respectively, the referrers) of store files given as -arguments. - -@item --requisites -@itemx -R -@cindex closure -List the requisites of the store files passed as arguments. Requisites -include the store files themselves, their references, and the references of -these, recursively. In other words, the returned list is the -@dfn{transitive closure} of the store files. - -@xref{Invoking guix size}, for a tool to profile the size of the closure of -an element. @xref{Invoking guix graph}, for a tool to visualize the graph -of references. - -@item --derivers -@cindex derivation -Return the derivation(s) leading to the given store items -(@pxref{Derivations}). - -For example, this command: - -@example -guix gc --derivers `guix package -I ^emacs$ | cut -f4` -@end example - -@noindent -returns the @file{.drv} file(s) leading to the @code{emacs} package -installed in your profile. - -Note that there may be zero matching @file{.drv} files, for instance because -these files have been garbage-collected. There can also be more than one -matching @file{.drv} due to fixed-output derivations. -@end table - -Lastly, the following options allow you to check the integrity of the store -and to control disk usage. - -@table @option - -@item --verify[=@var{options}] -@cindex integrity, of the store -@cindex integrity checking -Verify the integrity of the store. - -By default, make sure that all the store items marked as valid in the -database of the daemon actually exist in @file{/gnu/store}. - -When provided, @var{options} must be a comma-separated list containing one -or more of @code{contents} and @code{repair}. - -When passing @option{--verify=contents}, the daemon computes the content -hash of each store item and compares it against its hash in the database. -Hash mismatches are reported as data corruptions. Because it traverses -@emph{all the files in the store}, this command can take a long time, -especially on systems with a slow disk drive. - -@cindex repairing the store -@cindex corruption, recovering from -Using @option{--verify=repair} or @option{--verify=contents,repair} causes -the daemon to try to repair corrupt store items by fetching substitutes for -them (@pxref{Substitutes}). Because repairing is not atomic, and thus -potentially dangerous, it is available only to the system administrator. A -lightweight alternative, when you know exactly which items in the store are -corrupt, is @command{guix build --repair} (@pxref{Invoking guix build}). - -@item --optimize -@cindex deduplication -Optimize the store by hard-linking identical files---this is -@dfn{deduplication}. - -The daemon performs deduplication after each successful build or archive -import, unless it was started with @code{--disable-deduplication} -(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus, this -option is primarily useful when the daemon was running with -@code{--disable-deduplication}. - -@end table - -@node Invoking guix pull -@section Invoking @command{guix pull} - -@cindex upgrading Guix -@cindex updating Guix -@cindex @command{guix pull} -@cindex pull -Packages are installed or upgraded to the latest version available in the -distribution currently available on your local machine. To update that -distribution, along with the Guix tools, you must run @command{guix pull}: -the command downloads the latest Guix source code and package descriptions, -and deploys it. Source code is downloaded from a @uref{https://git-scm.com, -Git} repository, by default the official GNU@tie{}Guix repository, though -this can be customized. - -On completion, @command{guix package} will use packages and package versions -from this just-retrieved copy of Guix. Not only that, but all the Guix -commands and Scheme modules will also be taken from that latest version. -New @command{guix} sub-commands added by the update also become available. - -Any user can update their Guix copy using @command{guix pull}, and the -effect is limited to the user who run @command{guix pull}. For instance, -when user @code{root} runs @command{guix pull}, this has no effect on the -version of Guix that user @code{alice} sees, and vice versa. - -The result of running @command{guix pull} is a @dfn{profile} available under -@file{~/.config/guix/current} containing the latest Guix. Thus, make sure -to add it to the beginning of your search path so that you use the latest -version, and similarly for the Info manual (@pxref{Documentation}): - -@example -export PATH="$HOME/.config/guix/current/bin:$PATH" -export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH" -@end example - -The @code{--list-generations} or @code{-l} option lists past generations -produced by @command{guix pull}, along with details about their provenance: - -@example -$ guix pull -l -Generation 1 Jun 10 2018 00:18:18 - guix 65956ad - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: origin/master - commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe - -Generation 2 Jun 11 2018 11:02:49 - guix e0cc7f6 - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: origin/master - commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d - 2 new packages: keepalived, libnfnetlink - 6 packages upgraded: emacs-nix-mode@@2.0.4, - guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac, - heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4 - -Generation 3 Jun 13 2018 23:31:07 (current) - guix 844cc1c - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: origin/master - commit: 844cc1c8f394f03b404c5bb3aee086922373490c - 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{} - 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{} -@end example - -@xref{Invoking guix describe, @command{guix describe}}, for other ways to -describe the current status of Guix. - -This @code{~/.config/guix/current} profile works like any other profile -created by @command{guix package} (@pxref{Invoking guix package}). That is, -you can list generations, roll back to the previous generation---i.e., the -previous Guix---and so on: - -@example -$ guix package -p ~/.config/guix/current --roll-back -switched from generation 3 to 2 -$ guix package -p ~/.config/guix/current --delete-generations=1 -deleting /var/guix/profiles/per-user/charlie/current-guix-1-link -@end example - -The @command{guix pull} command is usually invoked with no arguments, but it -supports the following options: - -@table @code -@item --url=@var{url} -@itemx --commit=@var{commit} -@itemx --branch=@var{branch} -Download code for the @code{guix} channel from the specified @var{url}, at -the given @var{commit} (a valid Git commit ID represented as a hexadecimal -string), or @var{branch}. - -@cindex @file{channels.scm}, configuration file -@cindex configuration file for channels -These options are provided for convenience, but you can also specify your -configuration in the @file{~/.config/guix/channels.scm} file or using the -@option{--channels} option (see below). - -@item --channels=@var{file} -@itemx -C @var{file} -Read the list of channels from @var{file} instead of -@file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code -that evaluates to a list of channel objects. @xref{Channels}, for more -information. - -@item --news -@itemx -N -Display the list of packages added or upgraded since the previous -generation. - -This is the same information as displayed upon @command{guix pull} -completion, but without ellipses; it is also similar to the output of -@command{guix pull -l} for the last generation (see below). - -@item --list-generations[=@var{pattern}] -@itemx -l [@var{pattern}] -List all the generations of @file{~/.config/guix/current} or, if -@var{pattern} is provided, the subset of generations that match -@var{pattern}. The syntax of @var{pattern} is the same as with @code{guix -package --list-generations} (@pxref{Invoking guix package}). - -@xref{Invoking guix describe}, for a way to display information about the -current generation only. - -@item --profile=@var{profile} -@itemx -p @var{profile} -Use @var{profile} instead of @file{~/.config/guix/current}. - -@item --dry-run -@itemx -n -Show which channel commit(s) would be used and what would be built or -substituted but do not actually do it. - -@item --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 --verbose -Produce verbose output, writing build logs to the standard error output. - -@item --bootstrap -Use the bootstrap Guile to build the latest Guix. This option is only -useful to Guix developers. -@end table - -The @dfn{channel} mechanism allows you to instruct @command{guix pull} which -repository and branch to pull from, as well as @emph{additional} -repositories containing package modules that should be deployed. -@xref{Channels}, for more information. - -In addition, @command{guix pull} supports all the common build options -(@pxref{Common Build Options}). - -@node Channels -@section Channels - -@cindex channels -@cindex @file{channels.scm}, configuration file -@cindex configuration file for channels -@cindex @command{guix pull}, configuration file -@cindex configuration of @command{guix pull} -Guix and its package collection are updated by running @command{guix pull} -(@pxref{Invoking guix pull}). By default @command{guix pull} downloads and -deploys Guix itself from the official GNU@tie{}Guix repository. This can be -customized by defining @dfn{channels} in the -@file{~/.config/guix/channels.scm} file. A channel specifies a URL and -branch of a Git repository to be deployed, and @command{guix pull} can be -instructed to pull from one or more channels. In other words, channels can -be used to @emph{customize} and to @emph{extend} Guix, as we will see below. - -@subsection Using a Custom Guix Channel - -The channel called @code{guix} specifies where Guix itself---its -command-line tools as well as its package collection---should be -downloaded. For instance, suppose you want to update from your own copy of -the Guix repository at @code{example.org}, and specifically the -@code{super-hacks} branch, you can write in -@code{~/.config/guix/channels.scm} this specification: - -@lisp -;; Tell 'guix pull' to use my own repo. -(list (channel - (name 'guix) - (url "https://example.org/my-guix.git") - (branch "super-hacks"))) -@end lisp - -@noindent -From there on, @command{guix pull} will fetch code from the -@code{super-hacks} branch of the repository at @code{example.org}. - -@subsection Specifying Additional Channels - -@cindex extending the package collection (channels) -@cindex personal packages (channels) -@cindex channels, for personal packages -You can also specify @emph{additional channels} to pull from. Let's say you -have a bunch of custom package variants or personal packages that you think -would make little sense to contribute to the Guix project, but would like to -have these packages transparently available to you at the command line. You -would first write modules containing those package definitions -(@pxref{Package Modules}), maintain them in a Git repository, and then you -and anyone else can use it as an additional channel to get packages from. -Neat, no? - -@c What follows stems from discussions at -@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as -@c earlier discussions on guix-devel@gnu.org. -@quotation Warning -Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and -publish your personal channel to the world, we would like to share a few -words of caution: - -@itemize -@item -Before publishing a channel, please consider contributing your package -definitions to Guix proper (@pxref{贡献}). Guix as a project is -open to free software of all sorts, and packages in Guix proper are readily -available to all Guix users and benefit from the project's quality assurance -process. - -@item -When you maintain package definitions outside Guix, we, Guix developers, -consider that @emph{the compatibility burden is on you}. Remember that -package modules and package definitions are just Scheme code that uses -various programming interfaces (APIs). We want to remain free to change -these APIs to keep improving Guix, possibly in ways that break your -channel. We never change APIs gratuitously, but we will @emph{not} commit -to freezing APIs either. - -@item -Corollary: if you're using an external channel and that channel breaks, -please @emph{report the issue to the channel authors}, not to the Guix -project. -@end itemize - -You've been warned! Having said this, we believe external channels are a -practical way to exert your freedom to augment Guix' package collection and -to share your improvements, which are basic tenets of -@uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please -email us at @email{guix-devel@@gnu.org} if you'd like to discuss this. -@end quotation - -To use a channel, write @code{~/.config/guix/channels.scm} to instruct -@command{guix pull} to pull from it @emph{in addition} to the default Guix -channel(s): - -@vindex %default-channels -@lisp -;; Add my personal packages to those Guix provides. -(cons (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git")) - %default-channels) -@end lisp - -@noindent -Note that the snippet above is (as always!)@: Scheme code; we use -@code{cons} to add a channel the list of channels that the variable -@code{%default-channels} is bound to (@pxref{Pairs, @code{cons} and lists,, -guile, GNU Guile Reference Manual}). With this file in place, @command{guix -pull} builds not only Guix but also the package modules from your own -repository. The result in @file{~/.config/guix/current} is the union of -Guix with your own package modules: - -@example -$ guix pull --list-generations -@dots{} -Generation 19 Aug 27 2018 16:20:48 - guix d894ab8 - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: master - commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300 - my-personal-packages dd3df5e - repository URL: https://example.org/personal-packages.git - branch: master - commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb - 11 new packages: my-gimp, my-emacs-with-cool-features, @dots{} - 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{} -@end example - -@noindent -The output of @command{guix pull} above shows that Generation@tie{}19 -includes both Guix and packages from the @code{my-personal-packages} -channel. Among the new and upgraded packages that are listed, some like -@code{my-gimp} and @code{my-emacs-with-cool-features} might come from -@code{my-personal-packages}, while others come from the Guix default -channel. - -To create a channel, create a Git repository containing your own package -modules and make it available. The repository can contain anything, but a -useful channel will contain Guile modules that export packages. Once you -start using a channel, Guix will behave as if the root directory of that -channel's Git repository has been added to the Guile load path (@pxref{Load -Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel -contains a file at @file{my-packages/my-tools.scm} that defines a Guile -module, then the module will be available under the name @code{(my-packages -my-tools)}, and you will be able to use it like any other module -(@pxref{Modules,,, guile, GNU Guile Reference Manual}). - -@cindex dependencies, channels -@cindex meta-data, channels -@subsection Declaring Channel Dependencies - -Channel authors may decide to augment a package collection provided by other -channels. They can declare their channel to be dependent on other channels -in a meta-data file @file{.guix-channel}, which is to be placed in the root -of the channel repository. - -The meta-data file should contain a simple S-expression like this: - -@lisp -(channel - (version 0) - (dependencies - (channel - (name some-collection) - (url "https://example.org/first-collection.git")) - (channel - (name some-other-collection) - (url "https://example.org/second-collection.git") - (branch "testing")))) -@end lisp - -In the above example this channel is declared to depend on two other -channels, which will both be fetched automatically. The modules provided by -the channel will be compiled in an environment where the modules of all -these declared channels are available. - -For the sake of reliability and maintainability, you should avoid -dependencies on channels that you don't control, and you should aim to keep -the number of dependencies to a minimum. - -@subsection Replicating Guix - -@cindex pinning, channels -@cindex replicating Guix -@cindex reproducibility, of Guix -The @command{guix pull --list-generations} output above shows precisely -which commits were used to build this instance of Guix. We can thus -replicate it, say, on another machine, by providing a channel specification -in @file{~/.config/guix/channels.scm} that is ``pinned'' to these commits: - -@lisp -;; Deploy specific commits of my channels of interest. -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300")) - (channel - (name 'my-personal-packages) - (url "https://example.org/personal-packages.git") - (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb"))) -@end lisp - -The @command{guix describe --format=channels} command can even generate this -list of channels directly (@pxref{Invoking guix describe}). - -At this point the two machines run the @emph{exact same Guix}, with access -to the @emph{exact same packages}. The output of @command{guix build gimp} -on one machine will be exactly the same, bit for bit, as the output of the -same command on the other machine. It also means both machines have access -to all the source code of Guix and, transitively, to all the source code of -every package it defines. - -This gives you super powers, allowing you to track the provenance of binary -artifacts with very fine grain, and to reproduce software environments at -will---some sort of ``meta reproducibility'' capabilities, if you will. -@xref{Inferiors}, for another way to take advantage of these super powers. - -@node Inferiors -@section Inferiors - -@c TODO: Remove this once we're more confident about API stability. -@quotation Note -The functionality described here is a ``technology preview'' as of version -@value{VERSION}. As such, the interface is subject to change. -@end quotation - -@cindex inferiors -@cindex composition of Guix revisions -Sometimes you might need to mix packages from the revision of Guix you're -currently running with packages available in a different revision of Guix. -Guix @dfn{inferiors} allow you to achieve that by composing different Guix -revisions in arbitrary ways. - -@cindex inferior packages -Technically, an ``inferior'' is essentially a separate Guix process -connected to your main Guix process through a REPL (@pxref{Invoking guix -repl}). The @code{(guix inferior)} module allows you to create inferiors -and to communicate with them. It also provides a high-level interface to -browse and manipulate the packages that an inferior provides---@dfn{inferior -packages}. - -When combined with channels (@pxref{Channels}), inferiors provide a simple -way to interact with a separate revision of Guix. For example, let's assume -you want to install in your profile the current @code{guile} package, along -with the @code{guile-json} as it existed in an older revision of -Guix---perhaps because the newer @code{guile-json} has an incompatible API -and you want to run your code against the old API@. To do that, you could -write a manifest for use by @code{guix package --manifest} (@pxref{Invoking -guix package}); in that manifest, you would create an inferior for that old -Guix revision you care about, and you would look up the @code{guile-json} -package in the inferior: - -@lisp -(use-modules (guix inferior) (guix channels) - (srfi srfi-1)) ;for 'first' - -(define channels - ;; This is the old revision from which we want to - ;; extract guile-json. - (list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "65956ad3526ba09e1f7a40722c96c6ef7c0936fe")))) - -(define inferior - ;; An inferior representing the above revision. - (inferior-for-channels channels)) - -;; Now create a manifest with the current "guile" package -;; and the old "guile-json" package. -(packages->manifest - (list (first (lookup-inferior-packages inferior "guile-json")) - (specification->package "guile"))) -@end lisp - -On its first run, @command{guix package --manifest} might have to build the -channel you specified before it can create the inferior; subsequent runs -will be much faster because the Guix revision will be cached. - -The @code{(guix inferior)} module provides the following procedures to open -an inferior: - -@deffn {Scheme Procedure} inferior-for-channels @var{channels} @ - [#:cache-directory] [#:ttl] Return an inferior for @var{channels}, a list of -channels. Use the cache at @var{cache-directory}, where entries can be -reclaimed after @var{ttl} seconds. This procedure opens a new connection to -the build daemon. - -As a side effect, this procedure may build or substitute binaries for -@var{channels}, which can take time. -@end deffn - -@deffn {Scheme Procedure} open-inferior @var{directory} @ - [#:command "bin/guix"] Open the inferior Guix in @var{directory}, running -@code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} -if the inferior could not be launched. -@end deffn - -@cindex inferior packages -The procedures listed below allow you to obtain and manipulate inferior -packages. - -@deffn {Scheme Procedure} inferior-packages @var{inferior} -Return the list of packages known to @var{inferior}. -@end deffn - -@deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @ - [@var{version}] Return the sorted list of inferior packages matching -@var{name} in @var{inferior}, with highest version numbers first. If -@var{version} is true, return only packages with a version number prefixed -by @var{version}. -@end deffn - -@deffn {Scheme Procedure} inferior-package? @var{obj} -Return true if @var{obj} is an inferior package. -@end deffn - -@deffn {Scheme Procedure} inferior-package-name @var{package} -@deffnx {Scheme Procedure} inferior-package-version @var{package} -@deffnx {Scheme Procedure} inferior-package-synopsis @var{package} -@deffnx {Scheme Procedure} inferior-package-description @var{package} -@deffnx {Scheme Procedure} inferior-package-home-page @var{package} -@deffnx {Scheme Procedure} inferior-package-location @var{package} -@deffnx {Scheme Procedure} inferior-package-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-native-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package} -@deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package} -@deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package} -@deffnx {Scheme Procedure} inferior-package-search-paths @var{package} -These procedures are the counterpart of package record accessors -(@pxref{package Reference}). Most of them work by querying the inferior -@var{package} comes from, so the inferior must still be live when you call -these procedures. -@end deffn - -Inferior packages can be used transparently like any other package or -file-like object in G-expressions (@pxref{G-Expressions}). They are also -transparently handled by the @code{packages->manifest} procedure, which is -commonly use in manifests (@pxref{Invoking guix package, the -@option{--manifest} option of @command{guix package}}). Thus you can insert -an inferior package pretty much anywhere you would insert a regular package: -in manifests, in the @code{packages} field of your @code{operating-system} -declaration, and so on. - -@node Invoking guix describe -@section Invoking @command{guix describe} - -@cindex reproducibility -@cindex replicating Guix -Often you may want to answer questions like: ``Which revision of Guix am I -using?'' or ``Which channels am I using?'' This is useful information in -many situations: if you want to @emph{replicate} an environment on a -different machine or user account, if you want to report a bug or to -determine what change in the channels you are using caused it, or if you -want to record your system state for reproducibility purposes. The -@command{guix describe} command answers these questions. - -When run from a @command{guix pull}ed @command{guix}, @command{guix -describe} displays the channel(s) that it was built from, including their -repository URL and commit IDs (@pxref{Channels}): - -@example -$ guix describe -Generation 10 Sep 03 2018 17:32:44 (current) - guix e0fa68c - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: master - commit: e0fa68c7718fffd33d81af415279d6ddb518f727 -@end example - -If you're familiar with the Git version control system, this is similar in -spirit to @command{git describe}; the output is also similar to that of -@command{guix pull --list-generations}, but limited to the current -generation (@pxref{Invoking guix pull, the @option{--list-generations} -option}). Because the Git commit ID shown above unambiguously refers to a -snapshot of Guix, this information is all it takes to describe the revision -of Guix you're using, and also to replicate it. - -To make it easier to replicate Guix, @command{guix describe} can also be -asked to return a list of channels instead of the human-readable description -above: - -@example -$ guix describe -f channels -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "e0fa68c7718fffd33d81af415279d6ddb518f727"))) -@end example - -@noindent -You can save this to a file and feed it to @command{guix pull -C} on some -other machine or at a later point in time, which will instantiate @emph{this -exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}). -From there on, since you're able to deploy the same revision of Guix, you -can just as well @emph{replicate a complete software environment}. We -humbly think that this is @emph{awesome}, and we hope you'll like it too! - -The details of the options supported by @command{guix describe} are as -follows: - -@table @code -@item --format=@var{format} -@itemx -f @var{format} -Produce output in the specified @var{format}, one of: - -@table @code -@item human -produce human-readable output; -@item channels -produce a list of channel specifications that can be passed to @command{guix -pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking -guix pull}); -@item json -@cindex JSON -produce a list of channel specifications in JSON format; -@item recutils -produce a list of channel specifications in Recutils format. -@end table - -@item --profile=@var{profile} -@itemx -p @var{profile} -Display information about @var{profile}. -@end table - -@node Invoking guix archive -@section Invoking @command{guix archive} - -@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 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: - -@example -guix archive --export @var{options} @var{specifications}... -@end example - -@var{specifications} may be either store file names or package -specifications, as for @command{guix package} (@pxref{Invoking guix -package}). For instance, the following command creates an archive -containing the @code{gui} output of the @code{git} package and the main -output of @code{emacs}: - -@example -guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar -@end example - -If the specified packages are not built yet, @command{guix archive} -automatically builds them. The build process may be controlled with the -common build options (@pxref{Common Build Options}). - -To transfer the @code{emacs} package to a machine connected over SSH, one -would run: - -@example -guix archive --export -r emacs | ssh the-machine guix archive --import -@end example - -@noindent -Similarly, a complete user profile may be transferred from one machine to -another like this: - -@example -guix archive --export -r $(readlink -f ~/.guix-profile) | \ - ssh the-machine guix-archive --import -@end example - -@noindent -However, note that, in both examples, all of @code{emacs} and the profile as -well as all of their dependencies are transferred (due to @code{-r}), -regardless of what is already available in the store on the target machine. -The @code{--missing} option can help figure out which items are missing from -the target store. The @command{guix copy} command simplifies and optimizes -this whole process, so this is probably what you should use in this case -(@pxref{Invoking guix copy}). - -@cindex nar, archive format -@cindex normalized archive (nar) -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 the file type (regular, -directory, or symbolic link); Unix permissions and owner/group are -dismissed. Second, the order in which directory entries are stored always -follows the order of file names according to the C locale collation order. -This makes archive production fully deterministic. - -@c FIXME: Add xref to daemon doc about signatures. -When exporting, the daemon digitally signs the contents of the archive, and -that digital signature is appended. When importing, the daemon verifies the -signature and rejects the import in case of an invalid signature or if the -signing key is not authorized. - -The main options are: - -@table @code -@item --export -Export the specified store files or packages (see below.) Write the -resulting archive to the standard output. - -Dependencies are @emph{not} included in the output, unless -@code{--recursive} is passed. - -@item -r -@itemx --recursive -When combined with @code{--export}, this instructs @command{guix archive} to -include dependencies of the given items in the archive. Thus, the resulting -archive is self-contained: it contains the closure of the exported store -items. - -@item --import -Read an archive from the standard input, and import the files listed therein -into the store. Abort if the archive has an invalid digital signature, or -if it is signed by a public key not among the authorized keys (see -@code{--authorize} below.) - -@item --missing -Read a list of store file names from the standard input, one per line, and -write on the standard output the subset of these files missing from the -store. - -@item --generate-key[=@var{parameters}] -@cindex signing, archives -Generate a new key pair for the daemon. This is a prerequisite before -archives can be exported with @code{--export}. Note that this operation -usually takes time, because it needs to gather enough entropy to generate -the key pair. - -The generated key pair is typically stored under @file{/etc/guix}, in -@file{signing-key.pub} (public key) and @file{signing-key.sec} (private key, -which must be kept secret.) When @var{parameters} is omitted, an ECDSA key -using the Ed25519 curve is generated, or, for Libgcrypt versions before -1.6.0, it is a 4096-bit RSA key. Alternatively, @var{parameters} can -specify @code{genkey} parameters suitable for Libgcrypt (@pxref{General -public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The Libgcrypt -Reference Manual}). - -@item --authorize -@cindex authorizing, archives -Authorize imports signed by the public key passed on standard input. The -public key must be in ``s-expression advanced format''---i.e., the same -format as the @file{signing-key.pub} file. - -The list of authorized keys is kept in the human-editable file -@file{/etc/guix/acl}. The file contains -@url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format -s-expressions''} and is structured as an access-control list in the -@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure -(SPKI)}. - -@item --extract=@var{directory} -@itemx -x @var{directory} -Read a single-item archive as served by substitute servers -(@pxref{Substitutes}) and extract it to @var{directory}. This is a -low-level operation needed in only very narrow use cases; see below. - -For example, the following command extracts the substitute for Emacs served -by @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}: - -@example -$ wget -O - \ - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \ - | bunzip2 | guix archive -x /tmp/emacs -@end example - -Single-item archives are different from multiple-item archives produced by -@command{guix archive --export}; they contain a single store item, and they -do @emph{not} embed a signature. Thus this operation does @emph{no} -signature verification and its output should be considered unsafe. - -The primary purpose of this operation is to facilitate inspection of archive -contents coming from possibly untrusted substitute servers. - -@end table - - -@c ********************************************************************* -@node Development -@chapter Development - -@cindex software development -If you are a software developer, Guix provides tools that you should find -helpful---independently of the language you're developing in. This is what -this chapter is about. - -The @command{guix environment} command provides a convenient way to set up -@dfn{development environments} containing all the dependencies and tools -necessary to work on the software package of your choice. The @command{guix -pack} command allows you to create @dfn{application bundles} that can be -easily distributed to users who do not run Guix. - -@menu -* Invoking guix environment:: Setting up development environments. -* Invoking guix pack:: Creating software bundles. -@end menu - -@node Invoking guix environment -@section Invoking @command{guix environment} - -@cindex reproducible build environments -@cindex development environments -@cindex @command{guix environment} -@cindex environment, package build environment -The purpose of @command{guix environment} is to assist hackers in creating -reproducible development environments without polluting their package -profile. The @command{guix environment} tool takes one or more packages, -builds all of their inputs, and creates a shell environment to use them. - -The general syntax is: - -@example -guix environment @var{options} @var{package}@dots{} -@end example - -The following example spawns a new shell set up for the development of -GNU@tie{}Guile: - -@example -guix environment guile -@end example - -If the needed dependencies are not built yet, @command{guix environment} -automatically builds them. The environment of the new shell is an augmented -version of the environment that @command{guix environment} was run in. It -contains the necessary search paths for building the given package added to -the existing environment variables. To create a ``pure'' environment, in -which the original environment variables have been unset, use the -@code{--pure} option@footnote{Users sometimes wrongfully augment environment -variables such as @code{PATH} in their @file{~/.bashrc} file. As a -consequence, when @code{guix environment} launches it, Bash may read -@file{~/.bashrc}, thereby introducing ``impurities'' in these environment -variables. It is an error to define such environment variables in -@file{.bashrc}; instead, they should be defined in @file{.bash_profile}, -which is sourced only by log-in shells. @xref{Bash Startup Files,,, bash, -The GNU Bash Reference Manual}, for details on Bash start-up files.}. - -@vindex GUIX_ENVIRONMENT -@command{guix environment} defines the @code{GUIX_ENVIRONMENT} variable in -the shell it spawns; its value is the file name of the profile of this -environment. This allows users to, say, define a specific prompt for -development environments in their @file{.bashrc} (@pxref{Bash Startup -Files,,, bash, The GNU Bash Reference Manual}): - -@example -if [ -n "$GUIX_ENVIRONMENT" ] -then - export PS1="\u@@\h \w [dev]\$ " -fi -@end example - -@noindent -...@: or to browse the profile: - -@example -$ ls "$GUIX_ENVIRONMENT/bin" -@end example - -Additionally, more than one package may be specified, in which case the -union of the inputs for the given packages are used. For example, the -command below spawns a shell where all of the dependencies of both Guile and -Emacs are available: - -@example -guix environment guile emacs -@end example - -Sometimes an interactive shell session is not desired. An arbitrary command -may be invoked by placing the @code{--} token to separate the command from -the rest of the arguments: - -@example -guix environment guile -- make -j4 -@end example - -In other situations, it is more convenient to specify the list of packages -needed in the environment. For example, the following command runs -@command{python} from an environment containing Python@tie{}2.7 and NumPy: - -@example -guix environment --ad-hoc python2-numpy python-2.7 -- python -@end example - -Furthermore, one might want the dependencies of a package and also some -additional packages that are not build-time or runtime dependencies, but are -useful when developing nonetheless. Because of this, the @code{--ad-hoc} -flag is positional. Packages appearing before @code{--ad-hoc} are -interpreted as packages whose dependencies will be added to the -environment. Packages appearing after are interpreted as packages that will -be added to the environment directly. For example, the following command -creates a Guix development environment that additionally includes Git and -strace: - -@example -guix environment guix --ad-hoc git strace -@end example - -Sometimes it is desirable to isolate the environment as much as possible, -for maximal purity and reproducibility. In particular, when using Guix on a -host distro that is not Guix System, it is desirable to prevent access to -@file{/usr/bin} and other system-wide resources from the development -environment. For example, the following command spawns a Guile REPL in a -``container'' where only the store and the current working directory are -mounted: - -@example -guix environment --ad-hoc --container guile -- guile -@end example - -@quotation Note -The @code{--container} option requires Linux-libre 3.19 or newer. -@end quotation - -The available options are summarized below. - -@table @code -@item --root=@var{file} -@itemx -r @var{file} -@cindex persistent environment -@cindex garbage collector root, for environments -Make @var{file} a symlink to the profile for this environment, and register -it as a garbage collector root. - -This is useful if you want to protect your environment from garbage -collection, to make it ``persistent''. - -When this option is omitted, the environment is protected from garbage -collection only for the duration of the @command{guix environment} session. -This means that next time you recreate the same environment, you could have -to rebuild or re-download packages. @xref{Invoking guix gc}, for more on GC -roots. - -@item --expression=@var{expr} -@itemx -e @var{expr} -Create an environment for the package or list of packages that @var{expr} -evaluates to. - -For example, running: - -@example -guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' -@end example - -starts a shell with the environment for this specific variant of the PETSc -package. - -Running: - -@example -guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' -@end example - -starts a shell with all the base system packages available. - -The above commands only use the default output of the given packages. To -select other outputs, two element tuples can be specified: - -@example -guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")' -@end example - -@item --load=@var{file} -@itemx -l @var{file} -Create an environment for the package or list of packages that the code -within @var{file} evaluates to. - -As an example, @var{file} might contain a definition like this -(@pxref{Defining Packages}): - -@example -@verbatiminclude environment-gdb.scm -@end example - -@item --manifest=@var{file} -@itemx -m @var{file} -Create an environment for the packages contained in the manifest object -returned by the Scheme code in @var{file}. - -This is similar to the same-named option in @command{guix package} -(@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest -files. - -@item --ad-hoc -Include all specified packages in the resulting environment, as if an @i{ad -hoc} package were defined with them as inputs. This option is useful for -quickly creating an environment without having to write a package expression -to contain the desired inputs. - -For instance, the command: - -@example -guix environment --ad-hoc guile guile-sdl -- guile -@end example - -runs @command{guile} in an environment where Guile and Guile-SDL are -available. - -Note that this example implicitly asks for the default output of -@code{guile} and @code{guile-sdl}, but it is possible to ask for a specific -output---e.g., @code{glib:bin} asks for the @code{bin} output of @code{glib} -(@pxref{Packages with Multiple Outputs}). - -This option may be composed with the default behavior of @command{guix -environment}. Packages appearing before @code{--ad-hoc} are interpreted as -packages whose dependencies will be added to the environment, the default -behavior. Packages appearing after are interpreted as packages that will be -added to the environment directly. - -@item --pure -Unset existing environment variables when building the new environment, -except those specified with @option{--preserve} (see below.) This has the -effect of creating an environment in which search paths only contain package -inputs. - -@item --preserve=@var{regexp} -@itemx -E @var{regexp} -When used alongside @option{--pure}, preserve the environment variables -matching @var{regexp}---in other words, put them on a ``white list'' of -environment variables that must be preserved. This option can be repeated -several times. - -@example -guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ - -- mpirun @dots{} -@end example - -This example runs @command{mpirun} in a context where the only environment -variables defined are @code{PATH}, environment variables whose name starts -with @code{SLURM}, as well as the usual ``precious'' variables (@code{HOME}, -@code{USER}, etc.) - -@item --search-paths -Display the environment variable definitions that make up the environment. - -@item --system=@var{system} -@itemx -s @var{system} -Attempt to build for @var{system}---e.g., @code{i686-linux}. - -@item --container -@itemx -C -@cindex container -Run @var{command} within an isolated container. The current working -directory outside the container is mapped inside the container. -Additionally, unless overridden with @code{--user}, a dummy home directory -is created that matches the current user's home directory, and -@file{/etc/passwd} is configured accordingly. - -The spawned process runs as the current user outside the container. Inside -the container, it has the same UID and GID as the current user, unless -@option{--user} is passed (see below.) - -@item --network -@itemx -N -For containers, share the network namespace with the host system. -Containers created without this flag only have access to the loopback -device. - -@item --link-profile -@itemx -P -For containers, link the environment profile to @file{~/.guix-profile} -within the container. This is equivalent to running the command @command{ln --s $GUIX_ENVIRONMENT ~/.guix-profile} within the container. Linking will -fail and abort the environment if the directory already exists, which will -certainly be the case if @command{guix environment} was invoked in the -user's home directory. - -Certain packages are configured to look in @code{~/.guix-profile} for -configuration files and data;@footnote{For example, the @code{fontconfig} -package inspects @file{~/.guix-profile/share/fonts} for additional fonts.} -@code{--link-profile} allows these programs to behave as expected within the -environment. - -@item --user=@var{user} -@itemx -u @var{user} -For containers, use the username @var{user} in place of the current user. -The generated @file{/etc/passwd} entry within the container will contain the -name @var{user}, the home directory will be @file{/home/@var{user}}, and no -user GECOS data will be copied. Furthermore, the UID and GID inside the -container are 1000. @var{user} need not exist on the system. - -Additionally, any shared or exposed path (see @code{--share} and -@code{--expose} respectively) whose target is within the current user's home -directory will be remapped relative to @file{/home/USER}; this includes the -automatic mapping of the current working directory. - -@example -# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target -cd $HOME/wd -guix environment --container --user=foo \ - --expose=$HOME/test \ - --expose=/tmp/target=$HOME/target -@end example - -While this will limit the leaking of user identity through home paths and -each of the user fields, this is only one useful component of a broader -privacy/anonymity solution---not one in and of itself. - -@item --expose=@var{source}[=@var{target}] -For containers, expose the file system @var{source} from the host system as -the read-only file system @var{target} within the container. If -@var{target} is not specified, @var{source} is used as the target mount -point in the container. - -The example below spawns a Guile REPL in a container in which the user's -home directory is accessible read-only via the @file{/exchange} directory: - -@example -guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile -@end example - -@item --share=@var{source}[=@var{target}] -For containers, share the file system @var{source} from the host system as -the writable file system @var{target} within the container. If @var{target} -is not specified, @var{source} is used as the target mount point in the -container. - -The example below spawns a Guile REPL in a container in which the user's -home directory is accessible for both reading and writing via the -@file{/exchange} directory: - -@example -guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile -@end example -@end table - -@command{guix environment} also supports all of the common build options -that @command{guix build} supports (@pxref{Common Build Options}) as well as -package transformation options (@pxref{Package Transformation 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. - -@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 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. - -@cindex relocatable binaries, with @command{guix pack} -What if the recipient of your pack does not have root privileges on their -machine, and thus cannot unpack it in the root file system? In that case, -you will want to use the @code{--relocatable} option (see below). This -option produces @dfn{relocatable binaries}, meaning they they can be placed -anywhere in the file system hierarchy: in the example above, users can -unpack your tarball in their home directory and directly run -@file{./opt/gnu/bin/guile}. - -@cindex Docker, build an image with guix pack -Alternatively, you can produce a pack in the Docker image format using the -following command: - -@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. - -@cindex Singularity, build an image with guix pack -@cindex SquashFS, build an image with guix pack -Yet another option is to produce a SquashFS image with the following -command: - -@example -guix pack -f squashfs guile emacs geiser -@end example - -@noindent -The result is a SquashFS file system image that can either be mounted or -directly be used as a file system container image with the -@uref{http://singularity.lbl.gov, Singularity container execution -environment}, using commands like @command{singularity shell} or -@command{singularity exec}. - -Several command-line options allow you to customize your pack: - -@table @code -@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 -specified 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}. - -@item squashfs -This produces a SquashFS image containing all the specified binaries and -symlinks, as well as empty mount points for virtual file systems like -procfs. -@end table - -@cindex relocatable binaries -@item --relocatable -@itemx -R -Produce @dfn{relocatable binaries}---i.e., binaries that can be placed -anywhere in the file system hierarchy and run from there. - -When this option is passed once, the resulting binaries require support for -@dfn{user namespaces} in the kernel Linux; when passed -@emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds -PRoot support, can be thought of as the abbreviation of ``Really -Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to PRoot -if user namespaces are unavailable, and essentially work anywhere---see -below for the implications. - -For example, if you create a pack containing Bash with: - -@example -guix pack -RR -S /mybin=bin bash -@end example - -@noindent -...@: you can copy that pack to a machine that lacks Guix, and from your -home directory as a normal user, run: - -@example -tar xf pack.tar.gz -./mybin/sh -@end example - -@noindent -In that shell, if you type @code{ls /gnu/store}, you'll notice that -@file{/gnu/store} shows up and contains all the dependencies of @code{bash}, -even though the machine actually lacks @file{/gnu/store} altogether! That is -probably the simplest way to deploy Guix-built software on a non-Guix -machine. - -@quotation Note -By default, relocatable binaries rely on the @dfn{user namespace} feature of -the kernel Linux, which allows unprivileged users to mount or change root. -Old versions of Linux did not support it, and some GNU/Linux distributions -turn it off. - -To produce relocatable binaries that work even in the absence of user -namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In -that case, binaries will try user namespace support and fall back to PRoot -if user namespaces are not supported. - -The @uref{https://proot-me.github.io/, PRoot} program provides the necessary -support for file system virtualization. It achieves that by using the -@code{ptrace} system call on the running program. This approach has the -advantage to work without requiring special kernel support, but it incurs -run-time overhead every time a system call is made. -@end quotation - -@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 --manifest=@var{file} -@itemx -m @var{file} -Use the packages contained in the manifest object returned by the Scheme -code in @var{file}. - -This has a similar purpose as the same-named option in @command{guix -package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same -manifest files. It allows you to define a collection of packages once and -use it both for creating profiles and for creating archives for use on -machines that do not have Guix installed. Note that you can specify -@emph{either} a manifest file @emph{or} a list of packages, but not both. - -@item --system=@var{system} -@itemx -s @var{system} -Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of 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}, @code{lzip}, or @code{none} for no compression. - -@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 --save-provenance -Save provenance information for the packages passed on the command line. -Provenance information includes the URL and commit of the channels in use -(@pxref{Channels}). - -Provenance information is saved in the -@file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the -usual package metadata---the name and version of each package, their -propagated inputs, and so on. It is useful information to the recipient of -the pack, who then knows how the pack was (supposedly) obtained. - -This option is not enabled by default because, like timestamps, provenance -information contributes nothing to the build process. In other words, there -is an infinity of channel URLs and commit IDs that can lead to the same -pack. Recording such ``silent'' metadata in the output thus potentially -breaks the source-to-binary bitwise reproducibility property. - -@item --localstatedir -@itemx --profile-name=@var{name} -Include the ``local state directory'', @file{/var/guix}, in the resulting -pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}} -profile---by default @var{name} is @code{guix-profile}, which corresponds to -@file{~root/.guix-profile}. - -@file{/var/guix} contains the store database (@pxref{The Store}) as well as -garbage-collector roots (@pxref{Invoking guix gc}). Providing it in 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}). - -@item --bootstrap -Use the bootstrap binaries to build the pack. This option is only useful to -Guix developers. -@end table - -In addition, @command{guix pack} supports all the common build options -(@pxref{Common Build Options}) and all the package transformation options -(@pxref{Package Transformation Options}). - - -@c ********************************************************************* -@node Programming Interface -@chapter Programming Interface - -GNU Guix provides several Scheme programming interfaces (APIs) to define, -build, and query packages. The first interface allows users to write -high-level package definitions. These definitions refer to familiar -packaging concepts, such as the name and version of a package, its build -system, and its dependencies. These definitions can then be turned into -concrete build actions. - -Build actions are performed by the Guix daemon, on behalf of users. In a -standard setup, the daemon has write access to the store---the -@file{/gnu/store} directory---whereas users do not. The recommended setup -also has the daemon perform builds in chroots, under a specific build users, -to minimize interference with the rest of the system. - -@cindex derivation -Lower-level APIs are available to interact with the daemon and the store. -To instruct the daemon to perform a build action, users actually provide it -with a @dfn{derivation}. A derivation is a low-level representation of the -build actions to be taken, and the environment in which they should -occur---derivations are to package definitions what assembly is to C -programs. The term ``derivation'' comes from the fact that build results -@emph{derive} from them. - -This chapter describes all these APIs in turn, starting from high-level -package definitions. - -@menu -* Package Modules:: Packages from the programmer's viewpoint. -* Defining Packages:: Defining new packages. -* Build Systems:: Specifying how packages are built. -* The Store:: Manipulating the package store. -* Derivations:: Low-level interface to package derivations. -* The Store Monad:: Purely functional interface to the store. -* G-Expressions:: Manipulating build expressions. -* Invoking guix repl:: Fiddling with Guix interactively. -@end menu - -@node Package Modules -@section Package Modules - -From a programming viewpoint, the package definitions of the GNU -distribution are provided by Guile modules in the @code{(gnu packages -@dots{})} name space@footnote{Note that packages under the @code{(gnu -packages @dots{})} module name space are not necessarily ``GNU packages''. -This module naming scheme follows the usual Guile module naming convention: -@code{gnu} means that these modules are distributed as part of the GNU -system, and @code{packages} identifies modules that define packages.} -(@pxref{Modules, Guile modules,, guile, GNU Guile Reference Manual}). For -instance, the @code{(gnu packages emacs)} module exports a variable named -@code{emacs}, which is bound to a @code{<package>} object (@pxref{Defining -Packages}). - -The @code{(gnu packages @dots{})} module name space is automatically scanned -for packages by the command-line tools. For instance, when running -@code{guix package -i emacs}, all the @code{(gnu packages @dots{})} modules -are scanned until one that exports a package object whose name is -@code{emacs} is found. This package search facility is implemented in the -@code{(gnu packages)} module. - -@cindex customization, of packages -@cindex package module search path -Users can store package definitions in modules with different names---e.g., -@code{(my-packages emacs)}@footnote{Note that the file name and module name -must match. For instance, the @code{(my-packages emacs)} module must be -stored in a @file{my-packages/emacs.scm} file relative to the load path -specified with @option{--load-path} or @code{GUIX_PACKAGE_PATH}. -@xref{Modules and the File System,,, guile, GNU Guile Reference Manual}, for -details.}. There are two ways to make these package definitions visible to -the user interfaces: - -@enumerate -@item -By adding the directory containing your package modules to the search path -with the @code{-L} flag of @command{guix package} and other commands -(@pxref{Common Build Options}), or by setting the @code{GUIX_PACKAGE_PATH} -environment variable described below. - -@item -By defining a @dfn{channel} and configuring @command{guix pull} so that it -pulls from it. A channel is essentially a Git repository containing package -modules. @xref{Channels}, for more information on how to define and use -channels. -@end enumerate - -@code{GUIX_PACKAGE_PATH} works similarly to other search path variables: - -@defvr {Environment Variable} GUIX_PACKAGE_PATH -This is a colon-separated list of directories to search for additional -package modules. Directories listed in this variable take precedence over -the own modules of the distribution. -@end defvr - -The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: each -package is built based solely on other packages in the distribution. The -root of this dependency graph is a small set of @dfn{bootstrap binaries}, -provided by the @code{(gnu packages bootstrap)} module. For more -information on bootstrapping, @pxref{Bootstrapping}. - -@node Defining Packages -@section Defining Packages - -The high-level interface to package definitions is implemented in the -@code{(guix packages)} and @code{(guix build-system)} modules. As an -example, the package definition, or @dfn{recipe}, for the GNU Hello package -looks like this: - -@example -(define-module (gnu packages hello) - #:use-module (guix packages) - #:use-module (guix download) - #:use-module (guix build-system gnu) - #:use-module (guix licenses) - #:use-module (gnu packages gawk)) - -(define-public hello - (package - (name "hello") - (version "2.10") - (source (origin - (method url-fetch) - (uri (string-append "mirror://gnu/hello/hello-" version - ".tar.gz")) - (sha256 - (base32 - "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) - (build-system gnu-build-system) - (arguments '(#:configure-flags '("--enable-silent-rules"))) - (inputs `(("gawk" ,gawk))) - (synopsis "Hello, GNU world: An example GNU package") - (description "Guess what GNU Hello prints!") - (home-page "http://www.gnu.org/software/hello/") - (license gpl3+))) -@end example - -@noindent -Without being a Scheme expert, the reader may have guessed the meaning of -the various fields here. This expression binds the variable @code{hello} to -a @code{<package>} object, which is essentially a record (@pxref{SRFI-9, -Scheme records,, guile, GNU Guile Reference Manual}). This package object -can be inspected using procedures found in the @code{(guix packages)} -module; for instance, @code{(package-name hello)} -returns---surprise!---@code{"hello"}. - -With luck, you may be able to import part or all of the definition of the -package you are interested in from another repository, using the @code{guix -import} command (@pxref{Invoking guix import}). - -In the example above, @var{hello} is defined in a module of its own, -@code{(gnu packages hello)}. Technically, this is not strictly necessary, -but it is convenient to do so: all the packages defined in modules under -@code{(gnu packages @dots{})} are automatically known to the command-line -tools (@pxref{Package Modules}). - -There are a few points worth noting in the above package definition: - -@itemize -@item -The @code{source} field of the package is an @code{<origin>} object -(@pxref{origin Reference}, for the complete reference). Here, the -@code{url-fetch} method from @code{(guix download)} is used, meaning that -the source is a file to be downloaded over FTP or HTTP. - -The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of the -GNU mirrors defined in @code{(guix download)}. - -The @code{sha256} field specifies the expected SHA256 hash of the file being -downloaded. It is mandatory, and allows Guix to check the integrity of the -file. The @code{(base32 @dots{})} form introduces the base32 representation -of the hash. You can obtain this information with @code{guix download} -(@pxref{Invoking guix download}) and @code{guix hash} (@pxref{Invoking guix -hash}). - -@cindex patches -When needed, the @code{origin} form can also have a @code{patches} field -listing patches to be applied, and a @code{snippet} field giving a Scheme -expression to modify the source code. - -@item -@cindex GNU Build System -The @code{build-system} field specifies the procedure to build the package -(@pxref{Build Systems}). Here, @var{gnu-build-system} represents the -familiar GNU Build System, where packages may be configured, built, and -installed with the usual @code{./configure && make && make check && make -install} command sequence. - -@item -The @code{arguments} field specifies options for the build system -(@pxref{Build Systems}). Here it is interpreted by @var{gnu-build-system} -as a request run @file{configure} with the @code{--enable-silent-rules} -flag. - -@cindex quote -@cindex quoting -@findex ' -@findex quote -What about these quote (@code{'}) characters? They are Scheme syntax to -introduce a literal list; @code{'} is synonymous with @code{quote}. -@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual}, for -details. Here the value of the @code{arguments} field is a list of -arguments passed to the build system down the road, as with @code{apply} -(@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). - -The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword} -(@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and -@code{#:configure-flags} is a keyword used to pass a keyword argument to the -build system (@pxref{Coding With Keywords,,, guile, GNU Guile Reference -Manual}). - -@item -The @code{inputs} field specifies inputs to the build process---i.e., -build-time or run-time dependencies of the package. Here, we define an -input called @code{"gawk"} whose value is that of the @var{gawk} variable; -@var{gawk} is itself bound to a @code{<package>} object. - -@cindex backquote (quasiquote) -@findex ` -@findex quasiquote -@cindex comma (unquote) -@findex , -@findex unquote -@findex ,@@ -@findex unquote-splicing -Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows us -to introduce a literal list in the @code{inputs} field, while @code{,} (a -comma, synonymous with @code{unquote}) allows us to insert a value in that -list (@pxref{Expression Syntax, unquote,, guile, GNU Guile Reference -Manual}). - -Note that GCC, Coreutils, Bash, and other essential tools do not need to be -specified as inputs here. Instead, @var{gnu-build-system} takes care of -ensuring that they are present (@pxref{Build Systems}). - -However, any other dependencies need to be specified in the @code{inputs} -field. Any dependency not specified here will simply be unavailable to the -build process, possibly leading to a build failure. -@end itemize - -@xref{package Reference}, for a full description of possible fields. - -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}), -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{打包指导}, for more information on how to test package definitions, and -@ref{Invoking guix lint}, for information on how to check a definition for -style conformance. -@vindex GUIX_PACKAGE_PATH -Lastly, @pxref{Channels}, for information on how to extend the distribution -by adding your own package definitions in a ``channel''. - -Finally, updating the package definition to a new upstream version can be -partly automated by the @command{guix refresh} command (@pxref{Invoking guix -refresh}). - -Behind the scenes, a derivation corresponding to the @code{<package>} object -is first computed by the @code{package-derivation} procedure. That -derivation is stored in a @code{.drv} file under @file{/gnu/store}. The -build actions it prescribes may then be realized by using the -@code{build-derivations} procedure (@pxref{The Store}). - -@deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}] -Return the @code{<derivation>} object of @var{package} for @var{system} -(@pxref{Derivations}). - -@var{package} must be a valid @code{<package>} object, and @var{system} must -be a string denoting the target system type---e.g., @code{"x86_64-linux"} -for an x86_64 Linux-based GNU system. @var{store} must be a connection to -the daemon, which operates on the store (@pxref{The Store}). -@end deffn - -@noindent -@cindex cross-compilation -Similarly, it is possible to compute a derivation that cross-builds a -package for some other system: - -@deffn {Scheme Procedure} package-cross-derivation @var{store} @ - @var{package} @var{target} [@var{system}] Return the @code{<derivation>} -object of @var{package} cross-built from @var{system} to @var{target}. - -@var{target} must be a valid GNU triplet denoting the target hardware and -operating system, such as @code{"mips64el-linux-gnu"} (@pxref{Configuration -Names, GNU configuration triplets,, configure, GNU Configure and Build -System}). -@end deffn - -@cindex package transformations -@cindex input rewriting -@cindex dependency tree rewriting -Packages can be manipulated in arbitrary ways. An example of a useful -transformation is @dfn{input rewriting}, whereby the dependency tree of a -package is rewritten by replacing specific inputs by others: - -@deffn {Scheme Procedure} package-input-rewriting @var{replacements} @ - [@var{rewrite-name}] Return a procedure that, when passed a package, -replaces its direct and indirect dependencies (but not its implicit inputs) -according to @var{replacements}. @var{replacements} is a list of package -pairs; the first element of each pair is the package to replace, and the -second one is the replacement. - -Optionally, @var{rewrite-name} is a one-argument procedure that takes the -name of a package and returns its new name after rewrite. -@end deffn - -@noindent -Consider this example: - -@example -(define libressl-instead-of-openssl - ;; This is a procedure to replace OPENSSL by LIBRESSL, - ;; recursively. - (package-input-rewriting `((,openssl . ,libressl)))) - -(define git-with-libressl - (libressl-instead-of-openssl git)) -@end example - -@noindent -Here we first define a rewriting procedure that replaces @var{openssl} with -@var{libressl}. Then we use it to define a @dfn{variant} of the @var{git} -package that uses @var{libressl} instead of @var{openssl}. This is exactly -what the @option{--with-input} command-line option does (@pxref{Package -Transformation Options, @option{--with-input}}). - -The following variant of @code{package-input-rewriting} can match packages -to be replaced by name rather than by identity. - -@deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} -Return a procedure that, given a package, applies the given -@var{replacements} to all the package graph (excluding implicit inputs). -@var{replacements} is a list of spec/procedures pair; each spec is a package -specification such as @code{"gcc"} or @code{"guile@@2"}, and each procedure -takes a matching package and returns a replacement for that package. -@end deffn - -The example above could be rewritten this way: - -@example -(define libressl-instead-of-openssl - ;; Replace all the packages called "openssl" with LibreSSL. - (package-input-rewriting/spec `(("openssl" . ,(const libressl))))) -@end example - -The key difference here is that, this time, packages are matched by spec and -not by identity. In other words, any package in the graph that is called -@code{openssl} will be replaced. - -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. -@end menu - - -@node package Reference -@subsection @code{package} Reference - -This section summarizes all the options available in @code{package} -declarations (@pxref{Defining Packages}). - -@deftp {Data Type} package -This is the data type representing a package recipe. - -@table @asis -@item @code{name} -The name of the package, as a string. - -@item @code{version} -The version of the package, as a string. - -@item @code{source} -An object telling how the source code for the package should be acquired. -Most of the time, this is an @code{origin} object, which denotes a file -fetched from the Internet (@pxref{origin Reference}). It can also be any -other ``file-like'' object such as a @code{local-file}, which denotes a file -from the local file system (@pxref{G-Expressions, @code{local-file}}). - -@item @code{build-system} -The build system that should be used to build the package (@pxref{Build -Systems}). - -@item @code{arguments} (default: @code{'()}) -The arguments that should be passed to the build system. This is a list, -typically containing sequential keyword-value pairs. - -@item @code{inputs} (default: @code{'()}) -@itemx @code{native-inputs} (default: @code{'()}) -@itemx @code{propagated-inputs} (default: @code{'()}) -@cindex inputs, of packages -These fields list dependencies of the package. Each one is a list of -tuples, where each tuple has a label for the input (a string) as its first -element, a package, origin, or derivation as its second element, and -optionally the name of the output thereof that should be used, which -defaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for more -on package outputs). For example, the list below specifies three inputs: - -@example -`(("libffi" ,libffi) - ("libunistring" ,libunistring) - ("glib:bin" ,glib "bin")) ;the "bin" output of Glib -@end example - -@cindex cross compilation, package dependencies -The distinction between @code{native-inputs} and @code{inputs} is necessary -when considering cross-compilation. When cross-compiling, dependencies -listed in @code{inputs} are built for the @emph{target} architecture; -conversely, dependencies listed in @code{native-inputs} are built for the -architecture of the @emph{build} machine. - -@code{native-inputs} is typically used to list tools needed at build time, -but not at run time, such as Autoconf, Automake, pkg-config, Gettext, or -Bison. @command{guix lint} can report likely mistakes in this area -(@pxref{Invoking guix lint}). - -@anchor{package-propagated-inputs} -Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the -specified packages will be automatically installed alongside the package -they belong to (@pxref{package-cmd-propagated-inputs, @command{guix -package}}, for information on how @command{guix package} deals with -propagated inputs.) - -For example this is necessary when a C/C++ library needs headers of another -library to compile, or when a pkg-config file refers to another one @i{via} -its @code{Requires} field. - -Another example where @code{propagated-inputs} is useful is for languages -that lack a facility to record the run-time search path akin to the -@code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and more. -To ensure that libraries written in those languages can find library code -they depend on at run time, run-time dependencies must be listed in -@code{propagated-inputs} rather than @code{inputs}. - -@item @code{outputs} (default: @code{'("out")}) -The list of output names of the package. @xref{Packages with Multiple -Outputs}, for typical uses of additional outputs. - -@item @code{native-search-paths} (default: @code{'()}) -@itemx @code{search-paths} (default: @code{'()}) -A list of @code{search-path-specification} objects describing search-path -environment variables honored by the package. - -@item @code{replacement} (default: @code{#f}) -This must be either @code{#f} or a package object that will be used as a -@dfn{replacement} for this package. @xref{Security Updates, grafts}, for -details. - -@item @code{synopsis} -A one-line description of the package. - -@item @code{description} -A more elaborate description of the package. - -@item @code{license} -@cindex license, of packages -The license of the package; a value from @code{(guix licenses)}, or a list -of such values. - -@item @code{home-page} -The URL to the home-page of the package, as a string. - -@item @code{supported-systems} (default: @var{%supported-systems}) -The list of systems supported by the package, as strings of the form -@code{architecture-kernel}, for example @code{"x86_64-linux"}. - -@item @code{maintainers} (default: @code{'()}) -The list of maintainers of the package, as @code{maintainer} objects. - -@item @code{location} (default: source location of the @code{package} form) -The source location of the package. It is useful to override this when -inheriting from another package, in which case this field is not -automatically corrected. -@end table -@end deftp - -@deffn {Scheme Syntax} this-package -When used in the @emph{lexical scope} of a package field definition, this -identifier resolves to the package being defined. - -The example below shows how to add a package as a native input of itself -when cross-compiling: - -@example -(package - (name "guile") - ;; ... - - ;; When cross-compiled, Guile, for example, depends on - ;; a native version of itself. Add it here. - (native-inputs (if (%current-target-system) - `(("self" ,this-package)) - '()))) -@end example - -It is an error to refer to @code{this-package} outside a package definition. -@end deffn - -@node origin Reference -@subsection @code{origin} Reference - -This section summarizes all the options available in @code{origin} -declarations (@pxref{Defining Packages}). - -@deftp {Data Type} origin -This is the data type representing a source code origin. - -@table @asis -@item @code{uri} -An object containing the URI of the source. The object type depends on the -@code{method} (see below). For example, when using the @var{url-fetch} -method of @code{(guix download)}, the valid @code{uri} values are: a URL -represented as a string, or a list thereof. - -@item @code{method} -A procedure that handles the URI. - -Examples include: - -@table @asis -@item @var{url-fetch} from @code{(guix download)} -download a file from the HTTP, HTTPS, or FTP URL specified in the @code{uri} -field; - -@vindex git-fetch -@item @var{git-fetch} from @code{(guix git-download)} -clone the Git version control repository, and check out the revision -specified in the @code{uri} field as a @code{git-reference} object; a -@code{git-reference} looks like this: - -@example -(git-reference - (url "git://git.debian.org/git/pkg-shadow/shadow") - (commit "v4.1.5.1")) -@end example -@end table - -@item @code{sha256} -A bytevector containing the SHA-256 hash of the source. Typically the -@code{base32} form is used here to generate the bytevector from a base-32 -string. - -You can obtain this information using @code{guix download} (@pxref{Invoking -guix download}) or @code{guix hash} (@pxref{Invoking guix hash}). - -@item @code{file-name} (default: @code{#f}) -The file name under which the source code should be saved. When this is -@code{#f}, a sensible default value will be used in most cases. In case the -source is fetched from a URL, the file name from the URL will be used. For -version control checkouts, it is recommended to provide the file name -explicitly because the default is not very descriptive. - -@item @code{patches} (default: @code{'()}) -A list of file names, origins, or file-like objects (@pxref{G-Expressions, -file-like objects}) pointing to patches to be applied to the source. - -This list of patches must be unconditional. In particular, it cannot depend -on the value of @code{%current-system} or @code{%current-target-system}. - -@item @code{snippet} (default: @code{#f}) -A G-expression (@pxref{G-Expressions}) or S-expression that will be run in -the source directory. This is a convenient way to modify the source, -sometimes more convenient than a patch. - -@item @code{patch-flags} (default: @code{'("-p1")}) -A list of command-line flags that should be passed to the @code{patch} -command. - -@item @code{patch-inputs} (default: @code{#f}) -Input packages or derivations to the patching process. When this is -@code{#f}, the usual set of inputs necessary for patching are provided, such -as GNU@tie{}Patch. - -@item @code{modules} (default: @code{'()}) -A list of Guile modules that should be loaded during the patching process -and while running the code in the @code{snippet} field. - -@item @code{patch-guile} (default: @code{#f}) -The Guile package that should be used in the patching process. When this is -@code{#f}, a sensible default is used. -@end table -@end deftp - - -@node Build Systems -@section Build Systems - -@cindex build system -Each package definition specifies a @dfn{build system} and arguments for -that build system (@pxref{Defining Packages}). This @code{build-system} -field represents the build procedure of the package, as well as implicit -dependencies of that build procedure. - -Build systems are @code{<build-system>} objects. The interface to create -and manipulate them is provided by the @code{(guix build-system)} module, -and actual build systems are exported by specific modules. - -@cindex bag (low-level package representation) -Under the hood, build systems first compile package objects to @dfn{bags}. -A @dfn{bag} is like a package, but with less ornamentation---in other words, -a bag is a lower-level representation of a package, which includes all the -inputs of that package, including some that were implicitly added by the -build system. This intermediate representation is then compiled to a -derivation (@pxref{Derivations}). - -Build systems accept an optional list of @dfn{arguments}. In package -definitions, these are passed @i{via} the @code{arguments} field -(@pxref{Defining Packages}). They are typically keyword arguments -(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU Guile -Reference Manual}). The value of these arguments is usually evaluated in -the @dfn{build stratum}---i.e., by a Guile process launched by the daemon -(@pxref{Derivations}). - -The main build system is @var{gnu-build-system}, which implements the -standard build procedure for GNU and many other packages. It is provided by -the @code{(guix build-system gnu)} module. - -@defvr {Scheme Variable} gnu-build-system -@var{gnu-build-system} represents the GNU Build System, and variants thereof -(@pxref{Configuration, configuration and makefile conventions,, standards, -GNU Coding Standards}). - -@cindex build phases -In a nutshell, packages using it are configured, built, and installed with -the usual @code{./configure && make && make check && make install} command -sequence. In practice, a few additional steps are often needed. All these -steps are split up in separate @dfn{phases}, notably@footnote{Please see the -@code{(guix build gnu-build-system)} modules for more details about the -build phases.}: - -@table @code -@item unpack -Unpack the source tarball, and change the current directory to the extracted -source tree. If the source is actually a directory, copy it to the build -tree, and enter that directory. - -@item patch-source-shebangs -Patch shebangs encountered in source files so they refer to the right store -file names. For instance, this changes @code{#!/bin/sh} to -@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}. - -@item configure -Run the @file{configure} script with a number of default options, such as -@code{--prefix=/gnu/store/@dots{}}, as well as the options specified by the -@code{#:configure-flags} argument. - -@item build -Run @code{make} with the list of flags specified with @code{#:make-flags}. -If the @code{#:parallel-build?} argument is true (the default), build with -@code{make -j}. - -@item check -Run @code{make check}, or some other target specified with -@code{#:test-target}, unless @code{#:tests? #f} is passed. If the -@code{#:parallel-tests?} argument is true (the default), run @code{make -check -j}. - -@item install -Run @code{make install} with the flags listed in @code{#:make-flags}. - -@item patch-shebangs -Patch shebangs on the installed executable files. - -@item strip -Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} is -false), copying them to the @code{debug} output when available -(@pxref{Installing Debugging Files}). -@end table - -@vindex %standard-phases -The build-side module @code{(guix build gnu-build-system)} defines -@var{%standard-phases} as the default list of build phases. -@var{%standard-phases} is a list of symbol/procedure pairs, where the -procedure implements the actual phase. - -The list of phases used for a particular package can be changed with the -@code{#:phases} parameter. For instance, passing: - -@example -#:phases (modify-phases %standard-phases (delete 'configure)) -@end example - -means that all the phases described above will be used, except the -@code{configure} phase. - -In addition, this build system ensures that the ``standard'' environment for -GNU packages is available. This includes tools such as GCC, libc, -Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix -build-system gnu)} module for a complete list). We call these the -@dfn{implicit inputs} of a package, because package definitions do not have -to mention them. -@end defvr - -Other @code{<build-system>} objects are defined to support other conventions -and tools used by free software packages. They inherit most of -@var{gnu-build-system}, and differ mainly in the set of inputs implicitly -added to the build process, and in the list of phases executed. Some of -these build systems are listed below. - -@defvr {Scheme Variable} ant-build-system -This variable is exported by @code{(guix build-system ant)}. It implements -the build procedure for Java packages that can be built with -@url{http://ant.apache.org/, Ant build tool}. - -It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as provided -by the @code{icedtea} package to the set of inputs. Different packages can -be specified with the @code{#:ant} and @code{#:jdk} parameters, -respectively. - -When the original package does not provide a suitable Ant build file, the -parameter @code{#:jar-name} can be used to generate a minimal Ant build file -@file{build.xml} with tasks to build the specified jar archive. In this -case the parameter @code{#:source-dir} can be used to specify the source -sub-directory, defaulting to ``src''. - -The @code{#:main-class} parameter can be used with the minimal ant buildfile -to specify the main class of the resulting jar. This makes the jar file -executable. The @code{#:test-include} parameter can be used to specify the -list of junit tests to run. It defaults to @code{(list "**/*Test.java")}. -The @code{#:test-exclude} can be used to disable some tests. It defaults to -@code{(list "**/Abstract*.java")}, because abstract classes cannot be run as -tests. - -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 ``jar'' task -will be run. - -@end defvr - -@defvr {Scheme Variable} android-ndk-build-system -@cindex Android distribution -@cindex Android NDK build system -This variable is exported by @code{(guix build-system android-ndk)}. It -implements a build procedure for Android NDK (native development kit) -packages using a Guix-specific build process. - -The build system assumes that packages install their public interface -(header) files to the subdirectory "include" of the "out" output and their -libraries to the subdirectory "lib" of the "out" output. - -It's also assumed that the union of all the dependencies of a package has no -conflicting files. - -For the time being, cross-compilation is not supported - so right now the -libraries and header files are assumed to be host tools. - -@end defvr - -@defvr {Scheme Variable} asdf-build-system/source -@defvrx {Scheme Variable} asdf-build-system/sbcl -@defvrx {Scheme Variable} asdf-build-system/ecl - -These variables, exported by @code{(guix build-system asdf)}, implement -build procedures for Common Lisp packages using -@url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system -definition facility for Common Lisp programs and libraries. - -The @code{asdf-build-system/source} system installs the packages in source -form, and can be loaded using any common lisp implementation, via ASDF. The -others, such as @code{asdf-build-system/sbcl}, install binary systems in the -format which a particular implementation understands. These build systems -can also be used to produce executable programs, or lisp images which -contain a set of packages pre-loaded. - -The build system uses naming conventions. For binary packages, the package -name should be prefixed with the lisp implementation, such as @code{sbcl-} -for @code{asdf-build-system/sbcl}. - -Additionally, the corresponding source package should be labeled using the -same convention as python packages (see @ref{Python模块}), using the -@code{cl-} prefix. - -For binary packages, each system should be defined as a Guix package. If -one package @code{origin} contains several systems, package variants can be -created in order to build all the systems. Source packages, which use -@code{asdf-build-system/source}, may contain several systems. - -In order to create executable programs and images, the build-side procedures -@code{build-program} and @code{build-image} can be used. They should be -called in a build phase after the @code{create-symlinks} phase, so that the -system which was just built can be used within the resulting image. -@code{build-program} requires a list of Common Lisp expressions to be passed -as the @code{#:entry-program} argument. - -If the system is not defined within its own @code{.asd} file of the same -name, then the @code{#:asd-file} parameter should be used to specify which -file the system is defined in. Furthermore, if the package defines a system -for its tests in a separate file, it will be loaded before the tests are run -if it is specified by the @code{#:test-asd-file} parameter. If it is not -set, the files @code{<system>-tests.asd}, @code{<system>-test.asd}, -@code{tests.asd}, and @code{test.asd} will be tried if they exist. - -If for some reason the package must be named in a different way than the -naming conventions suggest, the @code{#:asd-system-name} parameter can be -used to specify the name of the system. - -@end defvr - -@defvr {Scheme Variable} cargo-build-system -@cindex Rust programming language -@cindex Cargo (Rust build system) -This variable is exported by @code{(guix build-system cargo)}. It supports -builds of packages using Cargo, the build tool of the -@uref{https://www.rust-lang.org, Rust programming language}. - -In its @code{configure} phase, this build system replaces dependencies -specified in the @file{Carto.toml} file with inputs to the Guix package. -The @code{install} phase installs the binaries, and it also installs the -source code and @file{Cargo.toml} file. -@end defvr - -@cindex Clojure (programming language) -@cindex simple Clojure build system -@defvr {Scheme Variable} clojure-build-system -This variable is exported by @code{(guix build-system clojure)}. It -implements a simple build procedure for @uref{https://clojure.org/, Clojure} -packages using plain old @code{compile} in Clojure. Cross-compilation is -not supported yet. - -It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs. -Different packages can be specified with the @code{#:clojure}, @code{#:jdk} -and @code{#:zip} parameters, respectively. - -A list of source directories, test directories and jar names can be -specified with the @code{#:source-dirs}, @code{#:test-dirs} and -@code{#:jar-names} parameters, respectively. Compile directory and main -class can be specified with the @code{#:compile-dir} and @code{#:main-class} -parameters, respectively. Other parameters are documented below. - -This build system is an extension of @var{ant-build-system}, but with the -following phases changed: - -@table @code - -@item build -This phase calls @code{compile} in Clojure to compile source files and runs -@command{jar} to create jars from both source files and compiled files -according to the include list and exclude list specified in -@code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude -list has priority over the include list. These lists consist of symbols -representing Clojure libraries or the special keyword @code{#:all} -representing all Clojure libraries found under the source directories. The -parameter @code{#:omit-source?} decides if source should be included into -the jars. - -@item check -This phase runs tests according to the include list and exclude list -specified in @code{#:test-include} and @code{#:test-exclude}, respectively. -Their meanings are analogous to that of @code{#:aot-include} and -@code{#:aot-exclude}, except that the special keyword @code{#:all} now -stands for all Clojure libraries found under the test directories. The -parameter @code{#:tests?} decides if tests should be run. - -@item install -This phase installs all jars built previously. -@end table - -Apart from the above, this build system also contains an additional phase: - -@table @code - -@item install-doc -This phase installs all top-level files with base name matching -@var{%doc-regex}. A different regex can be specified with the -@code{#:doc-regex} parameter. All files (recursively) inside the -documentation directories specified in @code{#:doc-dirs} are installed as -well. -@end table -@end defvr - -@defvr {Scheme Variable} cmake-build-system -This variable is exported by @code{(guix build-system cmake)}. It -implements the build procedure for packages using the -@url{http://www.cmake.org, CMake build tool}. - -It automatically adds the @code{cmake} package to the set of inputs. Which -package is used can be specified with the @code{#:cmake} parameter. - -The @code{#:configure-flags} parameter is taken as a list of flags passed to -the @command{cmake} command. The @code{#:build-type} parameter specifies in -abstract terms the flags passed to the compiler; it defaults to -@code{"RelWithDebInfo"} (short for ``release mode with debugging -information''), which roughly means that code is compiled with @code{-O2 --g}, as is the case for Autoconf-based packages by default. -@end defvr - -@defvr {Scheme Variable} dune-build-system -This variable is exported by @code{(guix build-system dune)}. It supports -builds of packages using @uref{https://dune.build/, Dune}, a build tool for -the OCaml programming language. It is implemented as an extension of the -@code{ocaml-build-system} which is described below. As such, the -@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build -system. - -It automatically adds the @code{dune} package to the set of inputs. Which -package is used can be specified with the @code{#:dune} parameter. - -There is no @code{configure} phase because dune packages typically don't -need to be configured. The @code{#:build-flags} parameter is taken as a -list of flags passed to the @code{dune} command during the build. - -The @code{#:jbuild?} parameter can be passed to use the @code{jbuild} -command instead of the more recent @code{dune} command while building a -package. Its default value is @code{#f}. - -The @code{#:package} parameter can be passed to specify a package name, -which is useful when a package contains multiple packages and you want to -build only one of them. This is equivalent to passing the @code{-p} -argument to @code{dune}. -@end defvr - -@defvr {Scheme Variable} go-build-system -This variable is exported by @code{(guix build-system go)}. It implements a -build procedure for Go packages using the standard -@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, Go -build mechanisms}. - -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 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 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. - -Packages that provide Go libraries should install their source code into the -built output. The key @code{#:install-source?}, which defaults to -@code{#t}, controls whether or not the source code is installed. It can be -set to @code{#f} for packages that only provide executable files. -@end defvr - -@defvr {Scheme Variable} glib-or-gtk-build-system -This variable is exported by @code{(guix build-system glib-or-gtk)}. It is -intended for use with packages making use of GLib or GTK+. - -This build system adds the following two phases to the ones defined by -@var{gnu-build-system}: - -@table @code -@item glib-or-gtk-wrap -The phase @code{glib-or-gtk-wrap} ensures that programs in @file{bin/} are -able to find GLib ``schemas'' and -@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+ -modules}. This is achieved by wrapping the programs in launch scripts that -appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH} environment -variables. - -It is possible to exclude specific package outputs from that wrapping -process by listing their names in the -@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful when -an output is known not to contain any GLib or GTK+ binaries, and where -wrapping would gratuitously add a dependency of that output on GLib and -GTK+. - -@item glib-or-gtk-compile-schemas -The phase @code{glib-or-gtk-compile-schemas} makes sure that all -@uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html, -GSettings schemas} of GLib are compiled. Compilation is performed by the -@command{glib-compile-schemas} program. It is provided by the package -@code{glib:bin} which is automatically imported by the build system. The -@code{glib} package providing @command{glib-compile-schemas} can be -specified with the @code{#:glib} parameter. -@end table - -Both phases are executed after the @code{install} phase. -@end defvr - -@defvr {Scheme Variable} guile-build-system -This build system is for Guile packages that consist exclusively of Scheme -code and that are so lean that they don't even have a makefile, let alone a -@file{configure} script. It compiles Scheme code using @command{guild -compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and -installs the @file{.scm} and @file{.go} files in the right place. It also -installs documentation. - -This build system supports cross-compilation by using the @code{--target} -option of @command{guild compile}. - -Packages built with @code{guile-build-system} must provide a Guile package -in their @code{native-inputs} field. -@end defvr - -@defvr {Scheme Variable} minify-build-system -This variable is exported by @code{(guix build-system minify)}. It -implements a minification procedure for simple JavaScript packages. - -It adds @code{uglify-js} to the set of inputs and uses it to compress all -JavaScript files in the @file{src} directory. A different minifier package -can be specified with the @code{#:uglify-js} parameter, but it is expected -that the package writes the minified code to the standard output. - -When the input JavaScript files are not all located in the @file{src} -directory, the parameter @code{#:javascript-files} can be used to specify a -list of file names to feed to the minifier. -@end defvr - -@defvr {Scheme Variable} ocaml-build-system -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 try some of them. - -When the package has a @file{setup.ml} file present at the top-level, it -will run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and -@code{ocaml setup.ml -install}. The build system will assume that this file -was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will -take care of setting the prefix and enabling tests if they are not -disabled. You can pass configure and build flags with the -@code{#:configure-flags} and @code{#:build-flags}. The @code{#:test-flags} -key can be passed to change the set of flags used to enable tests. The -@code{#:use-make?} key can be used to bypass this system in the build and -install phases. - -When the package has a @file{configure} file, it is assumed that it is a -hand-made configure script that requires a different argument format than in -the @code{gnu-build-system}. You can add more flags with the -@code{#:configure-flags} key. - -When the package has a @file{Makefile} file (or @code{#:use-make?} is -@code{#t}), it will be used and more flags can be passed to the build and -install phases with the @code{#:make-flags} key. - -Finally, some packages do not have these files and use a somewhat standard -location for its build system. In that case, the build system will run -@code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of -providing the path to the required findlib module. Additional flags can be -passed via the @code{#:build-flags} key. Install is taken care of by -@command{opam-installer}. In this case, the @code{opam} package must be -added to the @code{native-inputs} field of the package definition. - -Note that most OCaml packages assume they will be installed in the same -directory as OCaml, which is not what we want in guix. In particular, they -will install @file{.so} files in their module's directory, which is usually -fine because it is in the OCaml compiler directory. In guix though, these -libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This -variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where -@file{.so} libraries should be installed. -@end defvr - -@defvr {Scheme Variable} python-build-system -This variable is exported by @code{(guix build-system python)}. It -implements the more or less standard build procedure used by Python -packages, which consists in running @code{python setup.py build} and then -@code{python setup.py install --prefix=/gnu/store/@dots{}}. - -For packages that install stand-alone Python programs under @code{bin/}, it -takes care of wrapping these programs so that their @code{PYTHONPATH} -environment variable points to all the Python libraries they depend on. - -Which Python package is used to perform the build can be specified with the -@code{#:python} parameter. This is a useful way to force a package to be -built for a specific version of the Python interpreter, which might be -necessary if the package is only compatible with a single interpreter -version. - -By default guix calls @code{setup.py} under control of @code{setuptools}, -much like @command{pip} does. Some packages are not compatible with -setuptools (and pip), thus you can disable this by setting the -@code{#:use-setuptools} parameter to @code{#f}. -@end defvr - -@defvr {Scheme Variable} perl-build-system -This variable is exported by @code{(guix build-system perl)}. It implements -the standard build procedure for Perl packages, which either consists in -running @code{perl Build.PL --prefix=/gnu/store/@dots{}}, followed by -@code{Build} and @code{Build install}; or in running @code{perl Makefile.PL -PREFIX=/gnu/store/@dots{}}, followed by @code{make} and @code{make install}, -depending on which of @code{Build.PL} or @code{Makefile.PL} is present in -the package distribution. Preference is given to the former if both -@code{Build.PL} and @code{Makefile.PL} exist in the package distribution. -This preference can be reversed by specifying @code{#t} for the -@code{#:make-maker?} parameter. - -The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation -passes flags specified by the @code{#:make-maker-flags} or -@code{#:module-build-flags} parameter, respectively. - -Which Perl package is used can be specified with @code{#:perl}. -@end defvr - -@defvr {Scheme Variable} r-build-system -This variable is exported by @code{(guix build-system r)}. It implements -the build procedure used by @uref{http://r-project.org, R} packages, which -essentially is little more than running @code{R CMD INSTALL ---library=/gnu/store/@dots{}} in an environment where @code{R_LIBS_SITE} -contains the paths to all R package inputs. Tests are run after -installation using the R function @code{tools::testInstalledPackage}. -@end defvr - -@defvr {Scheme Variable} rakudo-build-system -This variable is exported by @code{(guix build-system rakudo)} It implements -the build procedure used by @uref{https://rakudo.org/, Rakudo} for -@uref{https://perl6.org/, Perl6} packages. It installs the package to -@code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and installs the -binaries, library files and the resources, as well as wrap the files under -the @code{bin/} directory. Tests can be skipped by passing @code{#f} to the -@code{tests?} parameter. - -Which rakudo package is used can be specified with @code{rakudo}. Which -perl6-tap-harness package used for the tests can be specified with -@code{#:prove6} or removed by passing @code{#f} to the @code{with-prove6?} -parameter. Which perl6-zef package used for tests and installing can be -specified with @code{#:zef} or removed by passing @code{#f} to the -@code{with-zef?} parameter. -@end defvr - -@defvr {Scheme Variable} texlive-build-system -This variable is exported by @code{(guix build-system texlive)}. It is used -to build TeX packages in batch mode with a specified engine. The build -system sets the @code{TEXINPUTS} variable to find all TeX source files in -the inputs. - -By default it runs @code{luatex} on all files ending on @code{ins}. A -different engine and format can be specified with the @code{#:tex-format} -argument. Different build targets can be specified with the -@code{#:build-targets} argument, which expects a list of file names. The -build system adds only @code{texlive-bin} and @code{texlive-latex-base} -(both from @code{(gnu packages tex}) to the inputs. Both can be overridden -with the arguments @code{#:texlive-bin} and @code{#:texlive-latex-base}, -respectively. - -The @code{#:tex-directory} parameter tells the build system where to install -the built files under the texmf tree. -@end defvr - -@defvr {Scheme Variable} ruby-build-system -This variable is exported by @code{(guix build-system ruby)}. It implements -the RubyGems build procedure used by Ruby packages, which involves running -@code{gem build} followed by @code{gem install}. - -The @code{source} field of a package that uses this build system typically -references a gem archive, since this is the format that Ruby developers use -when releasing their software. The build system unpacks the gem archive, -potentially patches the source, runs the test suite, repackages the gem, and -installs it. Additionally, directories and tarballs may be referenced to -allow building unreleased gems from Git or a traditional source release -tarball. - -Which Ruby package is used can be specified with the @code{#:ruby} -parameter. A list of additional flags to be passed to the @command{gem} -command can be specified with the @code{#:gem-flags} parameter. -@end defvr - -@defvr {Scheme Variable} waf-build-system -This variable is exported by @code{(guix build-system waf)}. It implements -a build procedure around the @code{waf} script. The common -phases---@code{configure}, @code{build}, and @code{install}---are -implemented by passing their names as arguments to the @code{waf} script. - -The @code{waf} script is executed by the Python interpreter. Which Python -package is used to run the script can be specified with the @code{#:python} -parameter. -@end defvr - -@defvr {Scheme Variable} scons-build-system -This variable is exported by @code{(guix build-system scons)}. It -implements the build procedure used by the SCons software construction -tool. This build system runs @code{scons} to build the package, @code{scons -test} to run tests, and then @code{scons install} to install the package. - -Additional flags to be passed to @code{scons} can be specified with the -@code{#:scons-flags} parameter. The version of Python used to run SCons can -be specified by selecting the appropriate SCons package with the -@code{#:scons} parameter. -@end defvr - -@defvr {Scheme Variable} haskell-build-system -This variable is exported by @code{(guix build-system haskell)}. It -implements the Cabal build procedure used by Haskell packages, which -involves running @code{runhaskell Setup.hs configure ---prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}. Instead -of installing the package by running @code{runhaskell Setup.hs install}, to -avoid trying to register libraries in the read-only compiler store -directory, the build system uses @code{runhaskell Setup.hs copy}, followed -by @code{runhaskell Setup.hs register}. In addition, the build system -generates the package documentation by running @code{runhaskell Setup.hs -haddock}, unless @code{#:haddock? #f} is passed. Optional Haddock -parameters can be passed with the help of the @code{#:haddock-flags} -parameter. If the file @code{Setup.hs} is not found, the build system looks -for @code{Setup.lhs} instead. - -Which Haskell compiler is used can be specified with the @code{#:haskell} -parameter which defaults to @code{ghc}. -@end defvr - -@defvr {Scheme Variable} dub-build-system -This variable is exported by @code{(guix build-system dub)}. It implements -the Dub build procedure used by D packages, which involves running @code{dub -build} and @code{dub run}. Installation is done by copying the files -manually. - -Which D compiler is used can be specified with the @code{#:ldc} parameter -which defaults to @code{ldc}. -@end defvr - -@defvr {Scheme Variable} emacs-build-system -This variable is exported by @code{(guix build-system emacs)}. It -implements an installation procedure similar to the packaging system of -Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -It first creates the @code{@var{package}-autoloads.el} file, then it byte -compiles all Emacs Lisp files. Differently from the Emacs packaging system, -the Info documentation files are moved to the standard documentation -directory and the @file{dir} file is deleted. Each package is installed in -its own directory under @file{share/emacs/site-lisp/guix.d}. -@end defvr - -@defvr {Scheme Variable} font-build-system -This variable is exported by @code{(guix build-system font)}. It implements -an installation procedure for font packages where upstream provides -pre-compiled TrueType, OpenType, etc.@: font files that merely need to be -copied into place. It copies font files to standard locations in the output -directory. -@end defvr - -@defvr {Scheme Variable} meson-build-system -This variable is exported by @code{(guix build-system meson)}. It -implements the build procedure for packages that use -@url{http://mesonbuild.com, Meson} as their build system. - -It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set of -inputs, and they can be changed with the parameters @code{#:meson} and -@code{#:ninja} if needed. The default Meson is @code{meson-for-build}, -which is special because it doesn't clear the @code{RUNPATH} of binaries and -libraries when they are installed. - -This build system is an extension of @var{gnu-build-system}, but with the -following phases changed to some specific for Meson: - -@table @code - -@item configure -The phase runs @code{meson} with the flags specified in -@code{#:configure-flags}. The flag @code{--build-type} is always set to -@code{plain} unless something else is specified in @code{#:build-type}. - -@item build -The phase runs @code{ninja} to build the package in parallel by default, but -this can be changed with @code{#:parallel-build?}. - -@item check -The phase runs @code{ninja} with the target specified in -@code{#:test-target}, which is @code{"test"} by default. - -@item install -The phase runs @code{ninja install} and can not be changed. -@end table - -Apart from that, the build system also adds the following phases: - -@table @code - -@item fix-runpath -This phase ensures that all binaries can find the libraries they need. It -searches for required libraries in subdirectories of the package being -built, and adds those to @code{RUNPATH} where needed. It also removes -references to libraries left over from the build phase by -@code{meson-for-build}, such as test dependencies, that aren't actually -required for the program to run. - -@item glib-or-gtk-wrap -This phase is the phase provided by @code{glib-or-gtk-build-system}, and it -is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}. - -@item glib-or-gtk-compile-schemas -This phase is the phase provided by @code{glib-or-gtk-build-system}, and it -is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}. -@end table -@end defvr - -@defvr {Scheme Variable} linux-module-build-system -@var{linux-module-build-system} allows building Linux kernel modules. - -@cindex build phases -This build system is an extension of @var{gnu-build-system}, but with the -following phases changed: - -@table @code - -@item configure -This phase configures the environment so that the Linux kernel's Makefile -can be used to build the external kernel module. - -@item build -This phase uses the Linux kernel's Makefile in order to build the external -kernel module. - -@item install -This phase uses the Linux kernel's Makefile in order to install the external -kernel module. -@end table - -It is possible and useful to specify the Linux kernel to use for building -the module (in the "arguments" form of a package using the -linux-module-build-system, use the key #:linux to specify it). -@end defvr - -Lastly, for packages that do not need anything as sophisticated, a -``trivial'' build system is provided. It is trivial in the sense that it -provides basically no support: it does not pull any implicit inputs, and -does not have a notion of build phases. - -@defvr {Scheme Variable} trivial-build-system -This variable is exported by @code{(guix build-system trivial)}. - -This build system requires a @code{#:builder} argument. This argument must -be a Scheme expression that builds the package output(s)---as with -@code{build-expression->derivation} (@pxref{Derivations, -@code{build-expression->derivation}}). -@end defvr - -@node The Store -@section The Store - -@cindex store -@cindex store items -@cindex store paths - -Conceptually, the @dfn{store} is the place where derivations that have been -built successfully are stored---by default, @file{/gnu/store}. -Sub-directories in the store are referred to as @dfn{store items} or -sometimes @dfn{store paths}. The store has an associated database that -contains information such as the store paths referred to by each store path, -and the list of @emph{valid} store items---results of successful builds. -This database resides in @file{@var{localstatedir}/guix/db}, where -@var{localstatedir} is the state directory specified @i{via} -@option{--localstatedir} at configure time, usually @file{/var}. - -The store is @emph{always} accessed by the daemon on behalf of its clients -(@pxref{Invoking guix-daemon}). To manipulate the store, clients connect to -the daemon over a Unix-domain socket, send requests to it, and read the -result---these are remote procedure calls, or RPCs. - -@quotation Note -Users must @emph{never} modify files under @file{/gnu/store} directly. This -would lead to inconsistencies and break the immutability assumptions of -Guix's functional model (@pxref{Introduction}). - -@xref{Invoking guix gc, @command{guix gc --verify}}, for information on how -to check the integrity of the store and attempt recovery from accidental -modifications. -@end quotation - -The @code{(guix store)} module provides procedures to connect to the 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 -@cindex daemon, remote access -@cindex remote access to the daemon -@cindex daemon, cluster setup -@cindex clusters, daemon setup -These URIs denote connections over TCP/IP, without encryption nor -authentication of the remote host. The URI must specify the host name and -optionally a port number (by default port 44146 is used): - -@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}. - -The @code{--listen} option of @command{guix-daemon} can be used to instruct -it to listen for TCP connections (@pxref{Invoking guix-daemon, -@code{--listen}}). - -@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{贡献}). -@end quotation -@end defvr - -@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. - -@var{file} defaults to @var{%default-socket-path}, which is the normal -location given the options that were passed to @command{configure}. -@end deffn - -@deffn {Scheme Procedure} close-connection @var{server} -Close the connection to @var{server}. -@end deffn - -@defvr {Scheme Variable} current-build-output-port -This variable is bound to a SRFI-39 parameter, which refers to the port -where build and error logs sent by the daemon should be written. -@end defvr - -Procedures that make RPCs all take a server object as their first argument. - -@deffn {Scheme Procedure} valid-path? @var{server} @var{path} -@cindex invalid store items -Return @code{#t} when @var{path} designates a valid store item and @code{#f} -otherwise (an invalid item may exist on disk but still be invalid, for -instance because it is the result of an aborted or failed build.) - -A @code{&store-protocol-error} condition is raised if @var{path} is not -prefixed by the store directory (@file{/gnu/store}). -@end deffn - -@deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}] -Add @var{text} under file @var{name} in the store, and return its store -path. @var{references} is the list of store paths referred to by the -resulting store path. -@end deffn - -@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations} -Build @var{derivations} (a list of @code{<derivation>} objects or derivation -paths), and return when the worker is done building them. Return @code{#t} -on success. -@end deffn - -Note that the @code{(guix monads)} module provides a monad as well as -monadic versions of the above procedures, with the goal of making it more -convenient to work with code that accesses the store (@pxref{The Store -Monad}). - -@c FIXME -@i{This section is currently incomplete.} - -@node Derivations -@section Derivations - -@cindex derivations -Low-level build actions and the environment in which they are performed are -represented by @dfn{derivations}. A derivation contains the following -pieces of information: - -@itemize -@item -The outputs of the derivation---derivations produce at least one file or -directory in the store, but may produce more. - -@item -@cindex build-time dependencies -@cindex dependencies, build-time -The inputs of the derivations---i.e., its build-time dependencies---which -may be other derivations or plain files in the store (patches, build -scripts, etc.) - -@item -The system type targeted by the derivation---e.g., @code{x86_64-linux}. - -@item -The file name of a build script in the store, along with the arguments to be -passed. - -@item -A list of environment variables to be defined. - -@end itemize - -@cindex derivation path -Derivations allow clients of the daemon to communicate build actions to the -store. They exist in two forms: as an in-memory representation, both on the -client- and daemon-side, and as files in the store whose name end in -@code{.drv}---these files are referred to as @dfn{derivation paths}. -Derivations paths can be passed to the @code{build-derivations} 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. - -@cindex references -@cindex run-time dependencies -@cindex dependencies, run-time -The outputs of derivations---i.e., the build results---have a set of -@dfn{references}, as reported by the @code{references} RPC or the -@command{guix gc --references} command (@pxref{Invoking guix gc}). -References are the set of run-time dependencies of the build results. -References are a subset of the inputs of the derivation; this subset is -automatically computed by the build daemon by scanning all the files in the -outputs. - -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 a derivation -is the @code{derivation} procedure: - -@deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @ - @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? -#f] [#:inputs '()] [#:env-vars '()] @ [#:system (%current-system)] -[#:references-graphs #f] @ [#:allowed-references #f] -[#:disallowed-references #f] @ [#:leaked-env-vars #f] [#:local-build? #f] @ -[#:substitutable? #t] [#:properties '()] Build a derivation with the given -arguments, and return the resulting @code{<derivation>} object. - -When @var{hash} and @var{hash-algo} are given, a @dfn{fixed-output -derivation} is created---i.e., one whose result is known in advance, such as -a file download. If, in addition, @var{recursive?} is true, then that fixed -output may be an executable file or a directory and @var{hash} must be the -hash of an archive containing this output. - -When @var{references-graphs} is true, it must be a list of file name/store -path pairs. In that case, the reference graph of each store path is -exported in the build environment in the corresponding file, in a simple -text format. - -When @var{allowed-references} is true, it must be a list of store items or -outputs that the derivation's output may refer to. Likewise, -@var{disallowed-references}, if true, must be a list of things the outputs -may @emph{not} refer to. - -When @var{leaked-env-vars} is true, it must be a list of strings denoting -environment variables that are allowed to ``leak'' from the daemon's -environment to the build environment. This is only applicable to -fixed-output derivations---i.e., when @var{hash} is true. The main use is -to allow variables such as @code{http_proxy} to be passed to derivations -that download files. - -When @var{local-build?} is true, declare that the derivation is not a good -candidate for offloading and should rather be built locally (@pxref{Daemon -Offload Setup}). This is the case for small derivations where the costs of -data transfers would outweigh the benefits. - -When @var{substitutable?} is false, declare that substitutes of the -derivation's output should not be used (@pxref{Substitutes}). This is -useful, for instance, when building packages that capture details of the -host CPU instruction set. - -@var{properties} must be an association list describing ``properties'' of -the derivation. It is kept as-is, uninterpreted, in the derivation. -@end deffn - -@noindent -Here's an example with a shell script as its builder, assuming @var{store} -is an open connection to the daemon, and @var{bash} points to a Bash -executable in the store: - -@lisp -(use-modules (guix utils) - (guix store) - (guix derivations)) - -(let ((builder ; add the Bash script to the store - (add-text-to-store store "my-builder.sh" - "echo hello world > $out\n" '()))) - (derivation store "foo" - bash `("-e" ,builder) - #:inputs `((,bash) (,builder)) - #:env-vars '(("HOME" . "/homeless")))) -@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo> -@end lisp - -As can be guessed, this primitive is cumbersome to use directly. A better -approach is to write build scripts in Scheme, of course! The best course of -action for that is to write the build code as a ``G-expression'', and to -pass it to @code{gexp->derivation}. For more information, -@pxref{G-Expressions}. - -Once upon a time, @code{gexp->derivation} did not exist and constructing -derivations with build code written in Scheme was achieved with -@code{build-expression->derivation}, documented below. This procedure is -now deprecated in favor of the much nicer @code{gexp->derivation}. - -@deffn {Scheme Procedure} build-expression->derivation @var{store} @ - @var{name} @var{exp} @ [#:system (%current-system)] [#:inputs '()] @ -[#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f] -[#:env-vars '()] [#:modules '()] @ [#:references-graphs #f] -[#:allowed-references #f] @ [#:disallowed-references #f] @ [#:local-build? -#f] [#:substitutable? #t] [#:guile-for-build #f] Return a derivation that -executes Scheme expression @var{exp} as a builder for derivation -@var{name}. @var{inputs} must be a list of @code{(name drv-path sub-drv)} -tuples; when @var{sub-drv} is omitted, @code{"out"} is assumed. -@var{modules} is a list of names of Guile modules from the current search -path to be copied in the store, compiled, and made available in the load -path during the execution of @var{exp}---e.g., @code{((guix build utils) -(guix build gnu-build-system))}. - -@var{exp} is evaluated in an environment where @code{%outputs} is bound to a -list of output/path pairs, and where @code{%build-inputs} is bound to a list -of string/output-path pairs made from @var{inputs}. Optionally, -@var{env-vars} is a list of string pairs specifying the name and value of -environment variables visible to the builder. The builder terminates by -passing the result of @var{exp} to @code{exit}; thus, when @var{exp} returns -@code{#f}, the build is considered to have failed. - -@var{exp} is built using @var{guile-for-build} (a derivation). When -@var{guile-for-build} is omitted or is @code{#f}, the value of the -@code{%guile-for-build} fluid is used instead. - -See the @code{derivation} procedure for the meaning of -@var{references-graphs}, @var{allowed-references}, -@var{disallowed-references}, @var{local-build?}, and @var{substitutable?}. -@end deffn - -@noindent -Here's an example of a single-output derivation that creates a directory -containing one file: - -@lisp -(let ((builder '(let ((out (assoc-ref %outputs "out"))) - (mkdir out) ; create /gnu/store/@dots{}-goo - (call-with-output-file (string-append out "/test") - (lambda (p) - (display '(hello guix) p)))))) - (build-expression->derivation store "goo" builder)) - -@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}> -@end lisp - - -@node The Store Monad -@section The Store Monad - -@cindex monad - -The procedures that operate on the store described in the previous sections -all take an open connection to the build daemon as their first argument. -Although the underlying model is functional, they either have side effects -or depend on the current state of the store. - -The former is inconvenient: the connection to the build daemon has to be -carried around in all those functions, making it impossible to compose -functions that do not take that parameter with functions that do. The -latter can be problematic: since store operations have side effects and/or -depend on external state, they have to be properly sequenced. - -@cindex monadic values -@cindex monadic functions -This is where the @code{(guix monads)} module comes in. This module -provides a framework for working with @dfn{monads}, and a particularly -useful monad for our uses, the @dfn{store monad}. Monads are a construct -that allows two things: associating ``context'' with values (in our case, -the context is the store), and building sequences of computations (here -computations include accesses to the store). Values in a monad---values -that carry this additional context---are called @dfn{monadic values}; -procedures that return such values are called @dfn{monadic procedures}. - -Consider this ``normal'' procedure: - -@example -(define (sh-symlink store) - ;; Return a derivation that symlinks the 'bash' executable. - (let* ((drv (package-derivation store bash)) - (out (derivation->output-path drv)) - (sh (string-append out "/bin/bash"))) - (build-expression->derivation store "sh" - `(symlink ,sh %output)))) -@end example - -Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten as a -monadic function: - -@example -(define (sh-symlink) - ;; Same, but return a monadic value. - (mlet %store-monad ((drv (package->derivation bash))) - (gexp->derivation "sh" - #~(symlink (string-append #$drv "/bin/bash") - #$output)))) -@end example - -There are several things to note in the second version: the @code{store} -parameter is now implicit and is ``threaded'' in the calls to the -@code{package->derivation} and @code{gexp->derivation} monadic procedures, -and the monadic value returned by @code{package->derivation} is @dfn{bound} -using @code{mlet} instead of plain @code{let}. - -As it turns out, the call to @code{package->derivation} can even be omitted -since it will take place implicitly, as we will see later -(@pxref{G-Expressions}): - -@example -(define (sh-symlink) - (gexp->derivation "sh" - #~(symlink (string-append #$bash "/bin/bash") - #$output))) -@end example - -@c See -@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/> -@c for the funny quote. -Calling the monadic @code{sh-symlink} has no effect. As someone once said, -``you exit a monad like you exit a building on fire: by running''. So, to -exit the monad and get the desired effect, one must use -@code{run-with-store}: - -@example -(run-with-store (open-connection) (sh-symlink)) -@result{} /gnu/store/...-sh-symlink -@end example - -Note that the @code{(guix monad-repl)} module extends the Guile REPL with -new ``meta-commands'' to make it easier to deal with monadic procedures: -@code{run-in-store}, and @code{enter-store-monad}. The former is used to -``run'' a single monadic value through the store: - -@example -scheme@@(guile-user)> ,run-in-store (package->derivation hello) -$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> -@end example - -The latter enters a recursive REPL, where all the return values are -automatically run through the store: - -@example -scheme@@(guile-user)> ,enter-store-monad -store-monad@@(guile-user) [1]> (package->derivation hello) -$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> -store-monad@@(guile-user) [1]> (text-file "foo" "Hello!") -$3 = "/gnu/store/@dots{}-foo" -store-monad@@(guile-user) [1]> ,q -scheme@@(guile-user)> -@end example - -@noindent -Note that non-monadic values cannot be returned in the @code{store-monad} -REPL. - -The main syntactic forms to deal with monads in general are provided by the -@code{(guix monads)} module and are described below. - -@deffn {Scheme Syntax} with-monad @var{monad} @var{body} ... -Evaluate any @code{>>=} or @code{return} forms in @var{body} as being in -@var{monad}. -@end deffn - -@deffn {Scheme Syntax} return @var{val} -Return a monadic value that encapsulates @var{val}. -@end deffn - -@deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ... -@dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic -procedures @var{mproc}@dots{}@footnote{This operation is commonly referred -to as ``bind'', but that name denotes an unrelated procedure in Guile. Thus -we use this somewhat cryptic symbol inherited from the Haskell language.}. -There can be one @var{mproc} or several of them, as in this example: - -@example -(run-with-state - (with-monad %state-monad - (>>= (return 1) - (lambda (x) (return (+ 1 x))) - (lambda (x) (return (* 2 x))))) - 'some-state) - -@result{} 4 -@result{} some-state -@end example -@end deffn - -@deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @ - @var{body} ... -@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}, 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}). -@end deffn - -@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. 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 monadic -procedure calls. - -@defvr {Scheme Variable} %state-monad -The state monad. Procedures in the state monad can access and change the -state that is threaded. - -Consider the example below. The @code{square} procedure returns a value in -the state monad. It returns the square of its argument, but also increments -the current state value: - -@example -(define (square x) - (mlet %state-monad ((count (current-state))) - (mbegin %state-monad - (set-current-state (+ 1 count)) - (return (* x x))))) - -(run-with-state (sequence %state-monad (map square (iota 3))) 0) -@result{} (0 1 4) -@result{} 3 -@end example - -When ``run'' through @var{%state-monad}, we obtain that additional state -value, which is the number of @code{square} calls. -@end defvr - -@deffn {Monadic Procedure} current-state -Return the current state as a monadic value. -@end deffn - -@deffn {Monadic Procedure} set-current-state @var{value} -Set the current state to @var{value} and return the previous state as a -monadic value. -@end deffn - -@deffn {Monadic Procedure} state-push @var{value} -Push @var{value} to the current state, which is assumed to be a list, and -return the previous state as a monadic value. -@end deffn - -@deffn {Monadic Procedure} state-pop -Pop a value from the current state and return it as a monadic value. The -state is assumed to be a list. -@end deffn - -@deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}] -Run monadic value @var{mval} starting with @var{state} as the initial -state. Return two values: the resulting value, and the resulting state. -@end deffn - -The main interface to the store monad, provided by the @code{(guix store)} -module, is as follows. - -@defvr {Scheme Variable} %store-monad -The store monad---an alias for @var{%state-monad}. - -Values in the store monad encapsulate accesses to the store. When its -effect is needed, a value of the store monad must be ``evaluated'' by -passing it to the @code{run-with-store} procedure (see below.) -@end defvr - -@deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)] -Run @var{mval}, a monadic value in the store monad, in @var{store}, an open -store connection. -@end deffn - -@deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}] -Return as a monadic value the absolute file name in the store of the file -containing @var{text}, a string. @var{references} is a list of store items -that the resulting text file refers to; it defaults to the empty list. -@end deffn - -@deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}] -Return as a monadic value the absolute file name in the store of the file -containing @var{data}, a bytevector. @var{references} is a list of store -items that the resulting binary file refers to; it defaults to the empty -list. -@end deffn - -@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @ - [#:recursive? #t] [#:select? (const #t)] Return the name of @var{file} once -interned in the store. Use @var{name} as its store name, or the basename of -@var{file} if @var{name} is omitted. - -When @var{recursive?} is true, the contents of @var{file} are added -recursively; if @var{file} designates a flat file and @var{recursive?} is -true, its contents are added, and its permission bits are kept. - -When @var{recursive?} is true, call @code{(@var{select?} @var{file} -@var{stat})} for each directory entry, where @var{file} is the entry's -absolute file name and @var{stat} is the result of @code{lstat}; exclude -entries for which @var{select?} does not return true. - -The example below adds a file to the store, under two different names: - -@example -(run-with-store (open-connection) - (mlet %store-monad ((a (interned-file "README")) - (b (interned-file "README" "LEGU-MIN"))) - (return (list a b)))) - -@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN") -@end example - -@end deffn - -The @code{(guix packages)} module exports the following package-related -monadic procedures: - -@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @ - [#:system (%current-system)] [#:target #f] @ [#:output "out"] Return as a -monadic value in the absolute file name of @var{file} within the -@var{output} directory of @var{package}. When @var{file} is omitted, return -the name of the @var{output} directory of @var{package}. When @var{target} -is true, use it as a cross-compilation target triplet. -@end deffn - -@deffn {Monadic Procedure} package->derivation @var{package} [@var{system}] -@deffnx {Monadic Procedure} package->cross-derivation @var{package} @ - @var{target} [@var{system}] Monadic version of @code{package-derivation} and -@code{package-cross-derivation} (@pxref{Defining Packages}). -@end deffn - - -@node G-Expressions -@section G-Expressions - -@cindex G-expression -@cindex build code quoting -So we have ``derivations'', which represent a sequence of build actions to -be performed to produce an item in the store (@pxref{Derivations}). These -build actions are performed when asking the daemon to actually build the -derivations; they are run by the daemon in a container (@pxref{Invoking -guix-daemon}). - -@cindex strata of code -It should come as no surprise that we like to write these build actions in -Scheme. When we do that, we end up with two @dfn{strata} of Scheme -code@footnote{The term @dfn{stratum} in this context was coined by Manuel -Serrano et al.@: in the context of their work on Hop. Oleg Kiselyov, who -has written insightful -@url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code on -this topic}, refers to this kind of code generation as @dfn{staging}.}: the -``host code''---code that defines packages, talks to the daemon, etc.---and -the ``build code''---code that actually performs build actions, such as -making directories, invoking @command{make}, etc. - -To describe a derivation and its build actions, one typically needs to embed -build code inside host code. It boils down to manipulating build code as -data, and the homoiconicity of Scheme---code has a direct representation as -data---comes in handy for that. But we need more than the normal -@code{quasiquote} mechanism in Scheme to construct build expressions. - -The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of -S-expressions adapted to build expressions. G-expressions, or @dfn{gexps}, -consist essentially of three syntactic forms: @code{gexp}, @code{ungexp}, -and @code{ungexp-splicing} (or simply: @code{#~}, @code{#$}, and -@code{#$@@}), which are comparable to @code{quasiquote}, @code{unquote}, and -@code{unquote-splicing}, respectively (@pxref{Expression Syntax, -@code{quasiquote},, guile, GNU Guile Reference Manual}). However, there are -major differences: - -@itemize -@item -Gexps are meant to be written to a file and run or manipulated by other -processes. - -@item -When a high-level object such as a package or derivation is unquoted inside -a gexp, the result is as if its output file name had been introduced. - -@item -Gexps carry information about the packages or derivations they refer to, and -these dependencies are automatically added as inputs to the build processes -that use them. -@end itemize - -@cindex lowering, of high-level objects in gexps -This mechanism is not limited to package and derivation objects: -@dfn{compilers} able to ``lower'' other high-level objects to derivations or -files in the store can be defined, such that these objects can also be -inserted into gexps. For example, a useful type of high-level objects that -can be inserted in a gexp is ``file-like objects'', which make it easy to -add files to the store and to refer to them in derivations and such (see -@code{local-file} and @code{plain-file} below.) - -To illustrate the idea, here is an example of a gexp: - -@example -(define build-exp - #~(begin - (mkdir #$output) - (chdir #$output) - (symlink (string-append #$coreutils "/bin/ls") - "list-files"))) -@end example - -This gexp can be passed to @code{gexp->derivation}; we obtain a derivation -that builds a directory containing exactly one symlink to -@file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}: - -@example -(gexp->derivation "the-thing" build-exp) -@end example - -As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string -is substituted to the reference to the @var{coreutils} package in the actual -build code, and @var{coreutils} is automatically made an input to the -derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp -output)}) is replaced by a string containing the directory name of the -output of the derivation. - -@cindex cross compilation -In a cross-compilation context, it is useful to distinguish between -references to the @emph{native} build of a package---that can run on the -host---versus references to cross builds of a package. To that end, the -@code{#+} plays the same role as @code{#$}, but is a reference to a native -package build: - -@example -(gexp->derivation "vi" - #~(begin - (mkdir #$output) - (system* (string-append #+coreutils "/bin/ln") - "-s" - (string-append #$emacs "/bin/emacs") - (string-append #$output "/bin/vi"))) - #:target "mips64el-linux-gnu") -@end example - -@noindent -In the example above, the native build of @var{coreutils} is used, so that -@command{ln} can actually run on the host; but then the cross-compiled build -of @var{emacs} is referenced. - -@cindex imported modules, for gexps -@findex with-imported-modules -Another gexp feature is @dfn{imported modules}: sometimes you want to be -able to use certain Guile modules from the ``host environment'' in the gexp, -so those modules should be imported in the ``build environment''. The -@code{with-imported-modules} form allows you to express that: - -@example -(let ((build (with-imported-modules '((guix build utils)) - #~(begin - (use-modules (guix build utils)) - (mkdir-p (string-append #$output "/bin")))))) - (gexp->derivation "empty-dir" - #~(begin - #$build - (display "success!\n") - #t))) -@end example - -@noindent -In this example, the @code{(guix build utils)} module is automatically -pulled into the isolated build environment of our gexp, such that -@code{(use-modules (guix build utils))} works as expected. - -@cindex module closure -@findex source-module-closure -Usually you want the @emph{closure} of the module to be imported---i.e., the -module itself and all the modules it depends on---rather than just the -module; failing to do that, attempts to use the module will fail because of -missing dependent modules. The @code{source-module-closure} procedure -computes the closure of a module by looking at its source file headers, -which comes in handy in this case: - -@example -(use-modules (guix modules)) ;for 'source-module-closure' - -(with-imported-modules (source-module-closure - '((guix build utils) - (gnu build vm))) - (gexp->derivation "something-with-vms" - #~(begin - (use-modules (guix build utils) - (gnu build vm)) - @dots{}))) -@end example - -@cindex extensions, for gexps -@findex with-extensions -In the same vein, sometimes you want to import not just pure-Scheme modules, -but also ``extensions'' such as Guile bindings to C libraries or other -``full-blown'' packages. Say you need the @code{guile-json} package -available on the build side, here's how you would do it: - -@example -(use-modules (gnu packages guile)) ;for 'guile-json' - -(with-extensions (list guile-json) - (gexp->derivation "something-with-json" - #~(begin - (use-modules (json)) - @dots{}))) -@end example - -The syntactic form to construct gexps is summarized below. - -@deffn {Scheme Syntax} #~@var{exp} -@deffnx {Scheme Syntax} (gexp @var{exp}) -Return a G-expression containing @var{exp}. @var{exp} may contain one or -more of the following forms: - -@table @code -@item #$@var{obj} -@itemx (ungexp @var{obj}) -Introduce a reference to @var{obj}. @var{obj} may have one of the supported -types, for example a package or a derivation, in which case the -@code{ungexp} form is replaced by its output file name---e.g., -@code{"/gnu/store/@dots{}-coreutils-8.22}. - -If @var{obj} is a list, it is traversed and references to supported objects -are substituted similarly. - -If @var{obj} is another gexp, its contents are inserted and its dependencies -are added to those of the containing gexp. - -If @var{obj} is another kind of object, it is inserted as is. - -@item #$@var{obj}:@var{output} -@itemx (ungexp @var{obj} @var{output}) -This is like the form above, but referring explicitly to the @var{output} of -@var{obj}---this is useful when @var{obj} produces multiple outputs -(@pxref{Packages with Multiple Outputs}). - -@item #+@var{obj} -@itemx #+@var{obj}:output -@itemx (ungexp-native @var{obj}) -@itemx (ungexp-native @var{obj} @var{output}) -Same as @code{ungexp}, but produces a reference to the @emph{native} build -of @var{obj} when used in a cross compilation context. - -@item #$output[:@var{output}] -@itemx (ungexp output [@var{output}]) -Insert a reference to derivation output @var{output}, or to the main output -when @var{output} is omitted. - -This only makes sense for gexps passed to @code{gexp->derivation}. - -@item #$@@@var{lst} -@itemx (ungexp-splicing @var{lst}) -Like the above, but splices the contents of @var{lst} inside the containing -list. - -@item #+@@@var{lst} -@itemx (ungexp-native-splicing @var{lst}) -Like the above, but refers to native builds of the objects listed in -@var{lst}. - -@end table - -G-expressions created by @code{gexp} or @code{#~} are run-time objects of -the @code{gexp?} type (see below.) -@end deffn - -@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. - -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 procedures -called from @var{body}@dots{}. -@end deffn - -@deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{} -Mark the gexps defined in @var{body}@dots{} as requiring @var{extensions} in -their build and execution environment. @var{extensions} is typically a list -of package objects such as those defined in the @code{(gnu packages guile)} -module. - -Concretely, the packages listed in @var{extensions} are added to the load -path while compiling imported modules in @var{body}@dots{}; they are also -added to the load path of the gexp returned by @var{body}@dots{}. -@end deffn - -@deffn {Scheme Procedure} gexp? @var{obj} -Return @code{#t} if @var{obj} is a G-expression. -@end deffn - -G-expressions are meant to be written to disk, either as code building some -derivation, or as plain files in the store. The monadic procedures below -allow you to do that (@pxref{The Store Monad}, for more information about -monads.) - -@deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @ - [#:system (%current-system)] [#:target #f] [#:graft? #t] @ [#:hash #f] -[#:hash-algo #f] @ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ -[#:module-path @var{%load-path}] @ [#:effective-version "2.2"] @ -[#:references-graphs #f] [#:allowed-references #f] @ -[#:disallowed-references #f] @ [#:leaked-env-vars #f] @ [#:script-name -(string-append @var{name} "-builder")] @ [#:deprecation-warnings #f] @ -[#:local-build? #f] [#:substitutable? #t] @ [#:properties '()] -[#:guile-for-build #f] Return a derivation @var{name} that runs @var{exp} (a -gexp) with @var{guile-for-build} (a derivation) on @var{system}; @var{exp} -is stored in a file called @var{script-name}. When @var{target} is true, it -is used as the cross-compilation target triplet for packages referred to by -@var{exp}. - -@var{modules} is deprecated in favor of @code{with-imported-modules}. Its -meaning is to make @var{modules} available in the evaluation context of -@var{exp}; @var{modules} is a list of names of Guile modules searched in -@var{module-path} to be copied in the store, compiled, and made available in -the load path during the execution of @var{exp}---e.g., @code{((guix build -utils) (guix build gnu-build-system))}. - -@var{effective-version} determines the string to use when adding extensions -of @var{exp} (see @code{with-extensions}) to the search path---e.g., -@code{"2.2"}. - -@var{graft?} determines whether packages referred to by @var{exp} should be -grafted when applicable. - -When @var{references-graphs} is true, it must be a list of tuples of one of -the following forms: - -@example -(@var{file-name} @var{package}) -(@var{file-name} @var{package} @var{output}) -(@var{file-name} @var{derivation}) -(@var{file-name} @var{derivation} @var{output}) -(@var{file-name} @var{store-item}) -@end example - -The right-hand-side of each element of @var{references-graphs} is -automatically made an input of the build process of @var{exp}. In the build -environment, each @var{file-name} contains the reference graph of the -corresponding item, in a simple text format. - -@var{allowed-references} must be either @code{#f} or a list of output names -and packages. In the latter case, the list denotes store items that the -result is allowed to refer to. Any reference to another store item will -lead to a build error. Similarly for @var{disallowed-references}, which can -list items that must not be referenced by the outputs. - -@var{deprecation-warnings} determines whether to show deprecation warnings -while compiling modules. It can be @code{#f}, @code{#t}, or -@code{'detailed}. - -The other arguments are as for @code{derivation} (@pxref{Derivations}). -@end deffn - -@cindex file-like objects -The @code{local-file}, @code{plain-file}, @code{computed-file}, -@code{program-file}, and @code{scheme-file} procedures below return -@dfn{file-like objects}. That is, when unquoted in a G-expression, these -objects lead to a file in the store. Consider this G-expression: - -@example -#~(system* #$(file-append glibc "/sbin/nscd") "-f" - #$(local-file "/tmp/my-nscd.conf")) -@end example - -The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it to -the store. Once expanded, for instance @i{via} @code{gexp->derivation}, the -G-expression refers to that copy under @file{/gnu/store}; thus, modifying or -removing the file in @file{/tmp} does not have any effect on what the -G-expression does. @code{plain-file} can be used similarly; it differs in -that the file content is directly passed as a string. - -@deffn {Scheme Procedure} local-file @var{file} [@var{name}] @ - [#:recursive? #f] [#:select? (const #t)] Return an object representing local -file @var{file} to add to the store; this object can be used in a gexp. If -@var{file} is a relative file name, it is looked up relative to the source -file where this form appears. @var{file} will be added to the store under -@var{name}--by default the base name of @var{file}. - -When @var{recursive?} is true, the contents of @var{file} are added -recursively; if @var{file} designates a flat file and @var{recursive?} is -true, its contents are added, and its permission bits are kept. - -When @var{recursive?} is true, call @code{(@var{select?} @var{file} -@var{stat})} for each directory entry, where @var{file} is the entry's -absolute file name and @var{stat} is the result of @code{lstat}; exclude -entries for which @var{select?} does not return true. - -This is the declarative counterpart of the @code{interned-file} monadic -procedure (@pxref{The Store Monad, @code{interned-file}}). -@end deffn - -@deffn {Scheme Procedure} plain-file @var{name} @var{content} -Return an object representing a text file called @var{name} with the given -@var{content} (a string or a bytevector) to be added to the store. - -This is the declarative counterpart of @code{text-file}. -@end deffn - -@deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @ - [#:options '(#:local-build? #t)] Return an object representing the store -item @var{name}, a file or directory computed by @var{gexp}. @var{options} -is a list of additional arguments to pass to @code{gexp->derivation}. - -This is the declarative counterpart of @code{gexp->derivation}. -@end deffn - -@deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @ - [#:guile (default-guile)] [#:module-path %load-path] Return an executable -script @var{name} that runs @var{exp} using @var{guile}, with @var{exp}'s -imported modules in its search path. Look up @var{exp}'s modules in -@var{module-path}. - -The example below builds a script that simply invokes the @command{ls} -command: - -@example -(use-modules (guix gexp) (gnu packages base)) - -(gexp->script "list-files" - #~(execl #$(file-append coreutils "/bin/ls") - "ls")) -@end example - -When ``running'' it through the store (@pxref{The Store Monad, -@code{run-with-store}}), we obtain a derivation that produces an executable -file @file{/gnu/store/@dots{}-list-files} along these lines: - -@example -#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds -!# -(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls") -@end example -@end deffn - -@deffn {Scheme Procedure} program-file @var{name} @var{exp} @ - [#:guile #f] [#:module-path %load-path] Return an object representing the -executable store item @var{name} that runs @var{gexp}. @var{guile} is the -Guile package used to execute that script. Imported modules of @var{gexp} -are looked up in @var{module-path}. - -This is the declarative counterpart of @code{gexp->script}. -@end deffn - -@deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @ - [#:set-load-path? #t] [#:module-path %load-path] @ [#:splice? #f] @ [#:guile -(default-guile)] Return a derivation that builds a file @var{name} -containing @var{exp}. When @var{splice?} is true, @var{exp} is considered -to be a list of expressions that will be spliced in the resulting file. - -When @var{set-load-path?} is true, emit code in the resulting file to set -@code{%load-path} and @code{%load-compiled-path} to honor @var{exp}'s -imported modules. Look up @var{exp}'s modules in @var{module-path}. - -The resulting file holds references to all the dependencies of @var{exp} or -a subset thereof. -@end deffn - -@deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f] -Return an object representing the Scheme file @var{name} that contains -@var{exp}. - -This is the declarative counterpart of @code{gexp->file}. -@end deffn - -@deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{} -Return as a monadic value a derivation that builds a text file containing -all of @var{text}. @var{text} may list, in addition to strings, objects of -any type that can be used in a gexp: packages, derivations, local file -objects, etc. The resulting store file holds references to all these. - -This variant should be preferred over @code{text-file} anytime the file to -create will reference items from the store. This is typically the case when -building a configuration file that embeds store file names, like this: - -@example -(define (profile.sh) - ;; Return the name of a shell script in the store that - ;; initializes the 'PATH' environment variable. - (text-file* "profile.sh" - "export PATH=" coreutils "/bin:" - grep "/bin:" sed "/bin\n")) -@end example - -In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file -will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby -preventing them from being garbage-collected during its lifetime. -@end deffn - -@deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{} -Return an object representing store file @var{name} containing @var{text}. -@var{text} is a sequence of strings and file-like objects, as in: - -@example -(mixed-text-file "profile" - "export PATH=" coreutils "/bin:" grep "/bin") -@end example - -This is the declarative counterpart of @code{text-file*}. -@end deffn - -@deffn {Scheme Procedure} file-union @var{name} @var{files} -Return a @code{<computed-file>} that builds a directory containing all of -@var{files}. Each item in @var{files} must be a two-element list where the -first element is the file name to use in the new directory, and the second -element is a gexp denoting the target file. Here's an example: - -@example -(file-union "etc" - `(("hosts" ,(plain-file "hosts" - "127.0.0.1 localhost")) - ("bashrc" ,(plain-file "bashrc" - "alias ls='ls --color=auto'")))) -@end example - -This yields an @code{etc} directory containing these two files. -@end deffn - -@deffn {Scheme Procedure} directory-union @var{name} @var{things} -Return a directory that is the union of @var{things}, where @var{things} is -a list of file-like objects denoting directories. For example: - -@example -(directory-union "guile+emacs" (list guile emacs)) -@end example - -yields a directory that is the union of the @code{guile} and @code{emacs} -packages. -@end deffn - -@deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{} -Return a file-like object that expands to the concatenation of @var{obj} and -@var{suffix}, where @var{obj} is a lowerable object and each @var{suffix} is -a string. - -As an example, consider this gexp: - -@example -(gexp->script "run-uname" - #~(system* #$(file-append coreutils - "/bin/uname"))) -@end example - -The same effect could be achieved with: - -@example -(gexp->script "run-uname" - #~(system* (string-append #$coreutils - "/bin/uname"))) -@end example - -There is one difference though: in the @code{file-append} case, the -resulting script contains the absolute file name as a string, whereas in the -second case, the resulting script contains a @code{(string-append @dots{})} -expression to construct the file name @emph{at run time}. -@end deffn - - -Of course, in addition to gexps embedded in ``host'' code, there are also -modules containing build tools. To make it clear that they are meant to be -used in the build stratum, these modules are kept in the @code{(guix build -@dots{})} name space. - -@cindex lowering, of high-level objects in gexps -Internally, high-level objects are @dfn{lowered}, using their compiler, to -either derivations or store items. For instance, lowering a package yields -a derivation, and lowering a @code{plain-file} yields a store item. This is -achieved using the @code{lower-object} monadic procedure. - -@deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @ - [#:target #f] Return as a value in @var{%store-monad} the derivation or -store item corresponding to @var{obj} for @var{system}, cross-compiling for -@var{target} if @var{target} is true. @var{obj} must be an object that has -an associated gexp compiler, such as a @code{<package>}. -@end deffn - -@node Invoking guix repl -@section Invoking @command{guix repl} - -@cindex REPL, read-eval-print loop -The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop} -(REPL) for interactive programming (@pxref{Using Guile Interactively,,, -guile, GNU Guile Reference Manual}). Compared to just launching the -@command{guile} command, @command{guix repl} guarantees that all the Guix -modules and all its dependencies are available in the search path. You can -use it this way: - -@example -$ guix repl -scheme@@(guile-user)> ,use (gnu packages base) -scheme@@(guile-user)> coreutils -$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300> -@end example - -@cindex inferiors -In addition, @command{guix repl} implements a simple machine-readable REPL -protocol for use by @code{(guix inferior)}, a facility to interact with -@dfn{inferiors}, separate processes running a potentially different revision -of Guix. - -The available options are as follows: - -@table @code -@item --type=@var{type} -@itemx -t @var{type} -Start a REPL of the given @var{TYPE}, which can be one of the following: - -@table @code -@item guile -This is default, and it spawns a standard full-featured Guile REPL. -@item machine -Spawn a REPL that uses the machine-readable protocol. This is the protocol -that the @code{(guix inferior)} module speaks. -@end table - -@item --listen=@var{endpoint} -By default, @command{guix repl} reads from standard input and writes to -standard output. When this option is passed, it will instead listen for -connections on @var{endpoint}. Here are examples of valid options: - -@table @code -@item --listen=tcp:37146 -Accept connections on localhost on port 37146. - -@item --listen=unix:/tmp/socket -Accept connections on the Unix-domain socket @file{/tmp/socket}. -@end table -@end table - -@c ********************************************************************* -@node Utilities -@chapter Utilities - -This section describes Guix command-line utilities. Some of them are -primarily targeted at developers and users who write new package -definitions, while others are more generally useful. They complement the -Scheme programming interface of Guix in a convenient way. - -@menu -* Invoking guix build:: Building packages from the command line. -* Invoking guix edit:: Editing package definitions. -* Invoking guix download:: Downloading a file and printing its hash. -* Invoking guix hash:: Computing the cryptographic hash of a file. -* Invoking guix import:: Importing package definitions. -* Invoking guix refresh:: Updating package definitions. -* Invoking guix lint:: Finding errors in package definitions. -* Invoking guix size:: Profiling disk usage. -* Invoking guix graph:: Visualizing the graph of packages. -* Invoking guix publish:: Sharing substitutes. -* Invoking guix challenge:: Challenging substitute servers. -* Invoking guix copy:: Copying to and from a remote store. -* Invoking guix container:: Process isolation. -* Invoking guix weather:: Assessing substitute availability. -* Invoking guix processes:: Listing client processes. -@end menu - -@node Invoking guix build -@section Invoking @command{guix build} - -@cindex package building -@cindex @command{guix build} -The @command{guix build} command builds packages or derivations and their -dependencies, and prints the resulting store paths. Note that it does not -modify the user's profile---this is the job of the @command{guix package} -command (@pxref{Invoking guix package}). Thus, it is mainly useful for -distribution developers. - -The general syntax is: - -@example -guix build @var{options} @var{package-or-derivation}@dots{} -@end example - -As an example, the following command builds the latest versions of Emacs and -of Guile, displays their build logs, and finally displays the resulting -directories: - -@example -guix build emacs guile -@end example - -Similarly, the following command builds all the available packages: - -@example -guix build --quiet --keep-going \ - `guix package -A | cut -f1,2 --output-delimiter=@@` -@end example - -@var{package-or-derivation} may be either the name of a package found in the -software distribution such as @code{coreutils} or @code{coreutils@@8.20}, or -a derivation such as @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the -former case, a package with the corresponding name (and optionally version) -is searched for among the GNU distribution modules (@pxref{Package -Modules}). - -Alternatively, the @code{--expression} option may be used to specify a -Scheme expression that evaluates to a package; this is useful when -disambiguating among several same-named packages or package variants is -needed. - -There may be zero or more @var{options}. The available options are -described in the subsections below. - -@menu -* 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 -@subsection Common Build Options - -A number of options that control the build process are common to -@command{guix build} and other commands that can spawn builds, such as -@command{guix package} or @command{guix archive}. These are the following: - -@table @code - -@item --load-path=@var{directory} -@itemx -L @var{directory} -Add @var{directory} to the front of the package module search path -(@pxref{Package Modules}). - -This allows users to define their own packages and make them visible to the -command-line tools. - -@item --keep-failed -@itemx -K -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. - -This option has no effect when connecting to a remote daemon with a -@code{guix://} URI (@pxref{The Store, the @code{GUIX_DAEMON_SOCKET} -variable}). - -@item --keep-going -@itemx -k -Keep going when some of the derivations fail to build; return only once all -the builds have either completed or failed. - -The default behavior is to stop as soon as one of the specified derivations -has failed. - -@item --dry-run -@itemx -n -Do not build the derivations. - -@anchor{fallback-option} -@item --fallback -When substituting a pre-built binary fails, fall back to building packages -locally (@pxref{Substitution Failure}). - -@item --substitute-urls=@var{urls} -@anchor{client-substitute-urls} -Consider @var{urls} the whitespace-separated list of substitute source URLs, -overriding the default list of URLs of @command{guix-daemon} -(@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}). - -This means that substitutes may be downloaded from @var{urls}, provided they -are signed by a key authorized by the system administrator -(@pxref{Substitutes}). - -When @var{urls} is the empty string, substitutes are effectively disabled. - -@item --no-substitutes -Do not use substitutes for build products. That is, always build things -locally instead of allowing downloads of pre-built binaries -(@pxref{Substitutes}). - -@item --no-grafts -Do not ``graft'' packages. In practice, this means that package updates -available as grafts are not applied. @xref{Security Updates}, for more -information on grafts. - -@item --rounds=@var{n} -Build each derivation @var{n} times in a row, and raise an error if -consecutive build results are not bit-for-bit identical. - -This is a useful way to detect non-deterministic builds processes. -Non-deterministic build processes are a problem because they make it -practically impossible for users to @emph{verify} whether third-party -binaries are genuine. @xref{Invoking guix challenge}, for more. - -Note that, currently, the differing build results are not kept around, so -you will have to manually investigate in case of an error---e.g., by -stashing one of the build results with @code{guix archive --export} -(@pxref{Invoking guix archive}), then rebuilding, and finally comparing the -two results. - -@item --no-build-hook -Do not attempt to offload builds @i{via} the ``build hook'' of the daemon -(@pxref{Daemon Offload Setup}). That is, always build things locally -instead of offloading builds to remote machines. - -@item --max-silent-time=@var{seconds} -When the build or substitution process remains silent for more than -@var{seconds}, terminate it and report a build failure. - -By default, the daemon's setting is honored (@pxref{Invoking guix-daemon, -@code{--max-silent-time}}). - -@item --timeout=@var{seconds} -Likewise, when the build or substitution process lasts for more than -@var{seconds}, terminate it and report a build failure. - -By default, the daemon's setting is honored (@pxref{Invoking guix-daemon, -@code{--timeout}}). - -@c Note: This option is actually not part of %standard-build-options but -@c most programs honor it. -@cindex verbosity, of the command-line tools -@cindex build logs, verbosity -@item -v @var{level} -@itemx --verbosity=@var{level} -Use the given verbosity @var{level}, an integer. Choosing 0 means that no -output is produced, 1 is for quiet output, and 2 shows all the build log -output on standard error. - -@item --cores=@var{n} -@itemx -c @var{n} -Allow the use of up to @var{n} CPU cores for the build. The special value -@code{0} means to use as many CPU cores as available. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Allow at most @var{n} build jobs in parallel. @xref{Invoking guix-daemon, -@code{--max-jobs}}, for details about this option and the equivalent -@command{guix-daemon} option. - -@item --debug=@var{level} -Produce debugging output coming from the build daemon. @var{level} must be -an integer between 0 and 5; higher means more verbose output. Setting a -level of 4 or more may be helpful when debugging setup issues with the build -daemon. - -@end table - -Behind the scenes, @command{guix build} is essentially an interface to the -@code{package-derivation} procedure of the @code{(guix packages)} module, -and to the @code{build-derivations} procedure of the @code{(guix -derivations)} module. - -In addition to options explicitly passed on the command line, @command{guix -build} and other @command{guix} commands that support building honor the -@code{GUIX_BUILD_OPTIONS} environment variable. - -@defvr {Environment Variable} GUIX_BUILD_OPTIONS -Users can define this variable to a list of command line options that will -automatically be used by @command{guix build} and other @command{guix} -commands that can perform builds, as in the example below: - -@example -$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar" -@end example - -These options are parsed independently, and the result is appended to the -parsed command-line options. -@end defvr - - -@node Package Transformation Options -@subsection Package Transformation Options - -@cindex package variants -Another set of command-line options supported by @command{guix build} and -also @command{guix package} are @dfn{package transformation options}. These -are options that make it possible to define @dfn{package variants}---for -instance, packages built from different source code. This is a convenient -way to create customized packages on the fly without having to type in the -definitions of package variants (@pxref{Defining Packages}). - -@table @code - -@item --with-source=@var{source} -@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}). - -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, 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 one -provided by the distribution. The example below downloads -@file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for the -@code{ed} package: - -@example -guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz -@end example - -As a developer, @code{--with-source} makes it easy to test release -candidates: - -@example -guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz -@end example - -@dots{} or to build from a checkout in a pristine environment: - -@example -$ git clone git://git.sv.gnu.org/guix.git -$ guix build guix --with-source=guix@@1.0=./guix -@end example - -@item --with-input=@var{package}=@var{replacement} -Replace dependency on @var{package} by a dependency on @var{replacement}. -@var{package} must be a package name, and @var{replacement} must be a -package specification such as @code{guile} or @code{guile@@1.8}. - -For instance, the following command builds Guix, but replaces its dependency -on the current stable version of Guile with a dependency on the legacy -version of Guile, @code{guile@@2.0}: - -@example -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@@2.0}. - -This is implemented using the @code{package-input-rewriting} Scheme -procedure (@pxref{Defining Packages, @code{package-input-rewriting}}). - -@item --with-graft=@var{package}=@var{replacement} -This is similar to @code{--with-input} but with an important difference: -instead of rebuilding the whole dependency chain, @var{replacement} is built -and then @dfn{grafted} onto the binaries that were initially referring to -@var{package}. @xref{Security Updates}, for more information on grafts. - -For example, the command below grafts version 3.5.4 of GnuTLS onto Wget and -all its dependencies, replacing references to the version of GnuTLS they -currently refer to: - -@example -guix build --with-graft=gnutls=gnutls@@3.5.4 wget -@end example - -This has the advantage of being much faster than rebuilding everything. But -there is a caveat: it works if and only if @var{package} and -@var{replacement} are strictly compatible---for example, if they provide a -library, the application binary interface (ABI) of those libraries must be -compatible. If @var{replacement} is somehow incompatible with -@var{package}, then the resulting package may be unusable. Use with care! - -@item --with-git-url=@var{package}=@var{url} -@cindex Git, using the latest commit -@cindex latest commit, building -Build @var{package} from the latest commit of the @code{master} branch of -the Git repository at @var{url}. Git sub-modules of the repository are -fetched, recursively. - -For example, the following command builds the NumPy Python library against -the latest commit of the master branch of Python itself: - -@example -guix build python-numpy \ - --with-git-url=python=https://github.com/python/cpython -@end example - -This option can also be combined with @code{--with-branch} or -@code{--with-commit} (see below). - -@cindex continuous integration -Obviously, since it uses the latest commit of the given branch, the result -of such a command varies over time. Nevertheless it is a convenient way to -rebuild entire software stacks against the latest commit of one or more -packages. This is particularly useful in the context of continuous -integration (CI). - -Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed -up consecutive accesses to the same repository. You may want to clean it up -once in a while to save disk space. - -@item --with-branch=@var{package}=@var{branch} -Build @var{package} from the latest commit of @var{branch}. If the -@code{source} field of @var{package} is an origin with the @code{git-fetch} -method (@pxref{origin Reference}) or a @code{git-checkout} object, the -repository URL is taken from that @code{source}. Otherwise you have to use -@code{--with-git-url} to specify the URL of the Git repository. - -For instance, the following command builds @code{guile-sqlite3} from the -latest commit of its @code{master} branch, and then builds @code{guix} -(which depends on it) and @code{cuirass} (which depends on @code{guix}) -against this specific @code{guile-sqlite3} build: - -@example -guix build --with-branch=guile-sqlite3=master cuirass -@end example - -@item --with-commit=@var{package}=@var{commit} -This is similar to @code{--with-branch}, except that it builds from -@var{commit} rather than the tip of a branch. @var{commit} must be a valid -Git commit SHA1 identifier. -@end table - -@node Additional Build Options -@subsection Additional Build Options - -The command-line options presented below are specific to @command{guix -build}. - -@table @code - -@item --quiet -@itemx -q -Build quietly, without displaying the build log; this is equivalent to -@code{--verbosity=0}. Upon completion, the build log is kept in @file{/var} -(or similar) and can always be retrieved using the @option{--log-file} -option. - -@item --file=@var{file} -@itemx -f @var{file} -Build the package, derivation, or other file-like object that the code -within @var{file} evaluates to (@pxref{G-Expressions, file-like objects}). - -As an example, @var{file} might contain a package definition like this -(@pxref{Defining Packages}): - -@example -@verbatiminclude package-hello.scm -@end example - -@item --expression=@var{expr} -@itemx -e @var{expr} -Build the package or derivation @var{expr} evaluates to. - -For example, @var{expr} may be @code{(@@ (gnu packages guile) guile-1.8)}, -which unambiguously designates this specific variant of version 1.8 of -Guile. - -Alternatively, @var{expr} may be a G-expression, in which case it is used as -a build program passed to @code{gexp->derivation} (@pxref{G-Expressions}). - -Lastly, @var{expr} may refer to a zero-argument monadic procedure -(@pxref{The Store Monad}). The procedure must return a derivation as a -monadic value, which is then passed through @code{run-with-store}. - -@item --source -@itemx -S -Build the source derivations of the packages, rather than the packages -themselves. - -For instance, @code{guix build -S gcc} returns something like -@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC source -tarball. - -The returned source tarball is the result of applying any patches and code -snippets specified in the package @code{origin} (@pxref{Defining Packages}). - -@item --sources -Fetch and return the source of @var{package-or-derivation} and all their -dependencies, recursively. This is a handy way to obtain a local copy of -all the source code needed to build @var{packages}, allowing you to -eventually build them even without network access. It is an extension of -the @code{--source} option and can accept one of the following optional -argument values: - -@table @code -@item package -This value causes the @code{--sources} option to behave in the same way as -the @code{--source} option. - -@item all -Build the source derivations of all packages, including any source that -might be listed as @code{inputs}. This is the default value. - -@example -$ guix build --sources tzdata -The following derivations will be built: - /gnu/store/@dots{}-tzdata2015b.tar.gz.drv - /gnu/store/@dots{}-tzcode2015b.tar.gz.drv -@end example - -@item transitive -Build the source derivations of all packages, as well of all transitive -inputs to the packages. This can be used e.g.@: to prefetch package source -for later offline building. - -@example -$ guix build --sources=transitive tzdata -The following derivations will be built: - /gnu/store/@dots{}-tzcode2015b.tar.gz.drv - /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv - /gnu/store/@dots{}-grep-2.21.tar.xz.drv - /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv - /gnu/store/@dots{}-make-4.1.tar.xz.drv - /gnu/store/@dots{}-bash-4.3.tar.xz.drv -@dots{} -@end example - -@end table - -@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. The @command{guix build} command allows you -to repeat this option several times, in which case it builds for all the -specified systems; other commands ignore extraneous @option{-s} options. - -@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 or @code{--system=armhf-linux} on an -@code{aarch64-linux} system allows you to build packages in a complete -32-bit environment. - -@quotation Note -Building for an @code{armhf-linux} system is unconditionally enabled on -@code{aarch64-linux} machines, although certain aarch64 chipsets do not -allow for this functionality, notably the ThunderX. -@end quotation - -Similarly, when transparent emulation with QEMU and @code{binfmt_misc} is -enabled (@pxref{Virtualization Services, @code{qemu-binfmt-service-type}}), -you can build for any system for 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 as -@code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU -configuration triplets,, autoconf, Autoconf}). - -@anchor{build-check} -@item --check -@cindex determinism, checking -@cindex reproducibility, checking -Rebuild @var{package-or-derivation}, which are already available in the -store, and raise an error if the build results are not bit-for-bit -identical. - -This mechanism allows you to check whether previously installed substitutes -are genuine (@pxref{Substitutes}), or whether the build result of a package -is deterministic. @xref{Invoking guix challenge}, for more background -information and tools. - -When used in conjunction with @option{--keep-failed}, the differing output -is kept in the store, under @file{/gnu/store/@dots{}-check}. This makes it -easy to look for differences between the two results. - -@item --repair -@cindex repairing store items -@cindex corruption, recovering from -Attempt to repair the specified store items, if they are corrupt, by -re-downloading or rebuilding them. - -This operation is not atomic and thus restricted to @code{root}. - -@item --derivations -@itemx -d -Return the derivation paths, not the output paths, of the given packages. - -@item --root=@var{file} -@itemx -r @var{file} -@cindex GC roots, adding -@cindex garbage collector roots, adding -Make @var{file} a symlink to the result, and register it as a garbage -collector root. - -Consequently, the results of this @command{guix build} invocation are -protected from garbage collection until @var{file} is removed. When that -option is omitted, build results are eligible for garbage collection as soon -as the build completes. @xref{Invoking guix gc}, for 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. - -This works regardless of how packages or derivations are specified. For -instance, the following invocations are equivalent: - -@example -guix build --log-file `guix build -d guile` -guix build --log-file `guix build guile` -guix build --log-file guile -guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)' -@end example - -If a log is unavailable locally, and unless @code{--no-substitutes} is -passed, the command looks for a corresponding log on one of the substitute -servers (as specified with @code{--substitute-urls}.) - -So for instance, imagine you want to see the build log of GDB on MIPS, but -you are actually on an @code{x86_64} machine: - -@example -$ guix build --log-file gdb -s mips64el-linux -https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10 -@end example - -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 --no-grafts -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. The -@option{--no-grafts} option makes sure we get the exact same environment, -with ungrafted packages (@pxref{Security Updates}, for more info on grafts). - -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} - -@cindex @command{guix edit} -@cindex package definition, editing -So many packages, so many source files! The @command{guix edit} command -facilitates the life of users and packagers by pointing their editor at the -source file containing the definition of the specified packages. For -instance: - -@example -guix edit gcc@@4.9 vim -@end example - -@noindent -launches the program specified in the @code{VISUAL} or in the @code{EDITOR} -environment variable to view the recipe of GCC@tie{}4.9.3 and that of Vim. - -If you are using a Guix Git checkout (@pxref{从Git编译}), or have -created your own packages on @code{GUIX_PACKAGE_PATH} (@pxref{Package -Modules}), you will be able to edit the package recipes. In other cases, -you will be able to examine the read-only recipes for packages currently in -the store. - - -@node Invoking guix download -@section Invoking @command{guix download} - -@cindex @command{guix download} -@cindex downloading package sources -When writing a package definition, developers typically need to download a -source tarball, compute its SHA256 hash, and write that hash in the package -definition (@pxref{Defining Packages}). The @command{guix download} tool -helps with this task: it downloads a file from the given URI, adds it to the -store, and prints both its file name in the store and its SHA256 hash. - -The fact that the downloaded file is added to the store saves bandwidth: -when the developer eventually tries to build the newly defined package with -@command{guix build}, the source tarball will not have to be downloaded -again because it is already in the store. It is also a convenient way to -temporarily stash files, which may be deleted eventually (@pxref{Invoking -guix gc}). - -The @command{guix download} command supports the same URIs as used in -package definitions. In particular, it supports @code{mirror://} URIs. -@code{https} URIs (HTTP over TLS) are supported @emph{provided} the Guile -bindings for GnuTLS are available in the user's environment; when they are -not available, an error is raised. @xref{Guile Preparations, how to install -the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, for more -information. - -@command{guix download} verifies HTTPS server certificates by loading the -certificates of X.509 authorities from the directory pointed to by the -@code{SSL_CERT_DIR} environment variable (@pxref{X.509 Certificates}), -unless @option{--no-check-certificate} is used. - -The following options are available: - -@table @code -@item --format=@var{fmt} -@itemx -f @var{fmt} -Write the hash in the format specified by @var{fmt}. For more information -on the valid values for @var{fmt}, @pxref{Invoking guix hash}. - -@item --no-check-certificate -Do not validate the X.509 certificates of HTTPS servers. - -When using this option, you have @emph{absolutely no guarantee} that you are -communicating with the authentic server responsible for the given URL, which -makes you vulnerable to ``man-in-the-middle'' attacks. - -@item --output=@var{file} -@itemx -o @var{file} -Save the downloaded file to @var{file} instead of adding it to the store. -@end table - -@node Invoking guix hash -@section Invoking @command{guix hash} - -@cindex @command{guix hash} -The @command{guix hash} command computes the SHA256 hash of a file. It is -primarily a convenience tool for anyone contributing to the distribution: it -computes the cryptographic hash of a file, which can be used in the -definition of a package (@pxref{Defining Packages}). - -The general syntax is: - -@example -guix hash @var{option} @var{file} -@end example - -When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the -hash of data read from standard input. @command{guix hash} has the -following options: - -@table @code - -@item --format=@var{fmt} -@itemx -f @var{fmt} -Write the hash in the format specified by @var{fmt}. - -Supported formats: @code{nix-base32}, @code{base32}, @code{base16} -(@code{hex} and @code{hexadecimal} can be used as well). - -If the @option{--format} option is not specified, @command{guix hash} will -output the hash in @code{nix-base32}. This representation is used in the -definitions of packages. - -@item --recursive -@itemx -r -Compute the hash on @var{file} recursively. - -@c FIXME: Replace xref above with xref to an ``Archive'' section when -@c it exists. -In this case, the hash is computed on an archive containing @var{file}, -including its children if it is a directory. Some of the metadata of -@var{file} is part of the archive; for instance, when @var{file} is a -regular file, the hash is different depending on whether @var{file} is -executable or not. Metadata such as time stamps has no impact on the hash -(@pxref{Invoking guix archive}). - -@item --exclude-vcs -@itemx -x -When combined with @option{--recursive}, exclude version control system -directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.) - -@vindex git-fetch -As an example, here is how you would compute the hash of a Git checkout, -which is useful when using the @code{git-fetch} method (@pxref{origin -Reference}): - -@example -$ git clone http://example.org/foo.git -$ cd foo -$ guix hash -rx . -@end example -@end table - -@node Invoking guix import -@section Invoking @command{guix import} - -@cindex importing packages -@cindex package import -@cindex package conversion -@cindex Invoking @command{guix import} -The @command{guix import} command is useful for people who would like to add -a package to the distribution with as little work as possible---a legitimate -demand. The command knows of a few repositories from which it can -``import'' package metadata. The result is a package definition, or a -template thereof, in the format we know (@pxref{Defining Packages}). - -The general syntax is: - -@example -guix import @var{importer} @var{options}@dots{} -@end example - -@var{importer} specifies the source from which to import package metadata, -and @var{options} specifies a package identifier and other options specific -to @var{importer}. Currently, the available ``importers'' are: - -@table @code -@item gnu -Import metadata for the given GNU package. This provides a template for the -latest version of that GNU package, including the hash of its source -tarball, and its canonical synopsis and description. - -Additional information such as the package dependencies and its license -needs to be figured out manually. - -For example, the following command returns a package definition for -GNU@tie{}Hello: - -@example -guix import gnu hello -@end example - -Specific command-line options are: - -@table @code -@item --key-download=@var{policy} -As for @code{guix refresh}, specify the policy to handle missing OpenPGP -keys when verifying the package signature. @xref{Invoking guix refresh, -@code{--key-download}}. -@end table - -@item pypi -@cindex pypi -Import metadata from the @uref{https://pypi.python.org/, Python Package -Index}. Information is taken from the JSON-formatted description available -at @code{pypi.python.org} and usually includes all the relevant information, -including package dependencies. For maximum efficiency, it is recommended -to install the @command{unzip} utility, so that the importer can unzip -Python wheels and gather data from them. - -The command below imports metadata for the @code{itsdangerous} Python -package: - -@example -guix import pypi itsdangerous -@end example - -@table @code -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -@item gem -@cindex gem -Import metadata from @uref{https://rubygems.org/, RubyGems}. Information is -taken from the JSON-formatted description available at @code{rubygems.org} -and includes most relevant information, including runtime dependencies. -There are some caveats, however. The metadata doesn't distinguish between -synopses and descriptions, so the same string is used for both fields. -Additionally, the details of non-Ruby dependencies required to build native -extensions is unavailable and left as an exercise to the packager. - -The command below imports metadata for the @code{rails} Ruby package: - -@example -guix import gem rails -@end example - -@table @code -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -@item cpan -@cindex CPAN -Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}. -Information is taken from the JSON-formatted metadata provided through -@uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most -relevant information, such as module dependencies. License information -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 list -of dependencies. - -The command command below imports metadata for the @code{Acme::Boolean} Perl -module: - -@example -guix import cpan Acme::Boolean -@end example - -@item cran -@cindex CRAN -@cindex Bioconductor -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}. - -Information is extracted from the @code{DESCRIPTION} file of the package. - -The command command below imports metadata for the @code{Cairo} R package: - -@example -guix import cran Cairo -@end example - -When @code{--recursive} is added, the importer will traverse the dependency -graph of the given upstream package recursively and generate package -expressions for all those packages that are not yet in Guix. - -When @code{--archive=bioconductor} is added, metadata is imported from -@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R -packages for for the analysis and comprehension of high-throughput genomic -data in bioinformatics. - -Information is extracted from the @code{DESCRIPTION} file of a package -published on the web interface of the Bioconductor SVN repository. - -The command below imports metadata for the @code{GenomicRanges} R package: - -@example -guix import cran --archive=bioconductor GenomicRanges -@end example - -@item texlive -@cindex TeX Live -@cindex CTAN -Import metadata from @uref{http://www.ctan.org/, CTAN}, the comprehensive -TeX archive network for TeX packages that are part of the -@uref{https://www.tug.org/texlive/, TeX Live distribution}. - -Information about the package is obtained through the XML API provided by -CTAN, while the source code is downloaded from the SVN repository of the Tex -Live project. This is done because the CTAN does not keep versioned -archives. - -The command command below imports metadata for the @code{fontspec} TeX -package: - -@example -guix import texlive fontspec -@end example - -When @code{--archive=DIRECTORY} is added, the source code is downloaded not -from the @file{latex} sub-directory of the @file{texmf-dist/source} tree in -the TeX Live SVN repository, but from the specified sibling directory under -the same root. - -The command below imports metadata for the @code{ifxetex} package from CTAN -while fetching the sources from the directory @file{texmf/source/generic}: - -@example -guix import texlive --archive=generic ifxetex -@end example - -@item json -@cindex JSON, import -Import package metadata from a local JSON file. Consider the following -example package definition in JSON format: - -@example -@{ - "name": "hello", - "version": "2.10", - "source": "mirror://gnu/hello/hello-2.10.tar.gz", - "build-system": "gnu", - "home-page": "https://www.gnu.org/software/hello/", - "synopsis": "Hello, GNU world: An example GNU package", - "description": "GNU Hello prints a greeting.", - "license": "GPL-3.0+", - "native-inputs": ["gcc@@6"] -@} -@end example - -The field names are the same as for the @code{<package>} record -(@xref{Defining Packages}). References to other packages are provided as -JSON lists of quoted package specification strings such as @code{guile} or -@code{guile@@2.0}. - -The importer also supports a more explicit source definition using the -common fields for @code{<origin>} records: - -@example -@{ - @dots{} - "source": @{ - "method": "url-fetch", - "uri": "mirror://gnu/hello/hello-2.10.tar.gz", - "sha256": @{ - "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i" - @} - @} - @dots{} -@} -@end example - -The command below reads metadata from the JSON file @code{hello.json} and -outputs a package expression: - -@example -guix import json hello.json -@end example - -@item nix -Import metadata from a local copy of the source of the -@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This relies -on the @command{nix-instantiate} command of @uref{http://nixos.org/nix/, -Nix}.}. Package definitions in Nixpkgs are typically written in a mixture -of Nix-language and Bash code. This command only imports the high-level -package structure that is written in the Nix language. It normally includes -all the basic fields of a package definition. - -When importing a GNU package, the synopsis and descriptions are replaced by -their canonical upstream variant. - -Usually, you will first need to do: - -@example -export NIX_REMOTE=daemon -@end example - -@noindent -so that @command{nix-instantiate} does not try to open the Nix database. - -As an example, the command below imports the package definition of -LibreOffice (more precisely, it imports the definition of the package bound -to the @code{libreoffice} top-level attribute): - -@example -guix import nix ~/path/to/nixpkgs libreoffice -@end example - -@item hackage -@cindex hackage -Import metadata from the Haskell community's central package archive -@uref{https://hackage.haskell.org/, Hackage}. Information is taken from -Cabal files and includes all the relevant information, including package -dependencies. - -Specific command-line options are: - -@table @code -@item --stdin -@itemx -s -Read a Cabal file from standard input. -@item --no-test-dependencies -@itemx -t -Do not include dependencies required only by the test suites. -@item --cabal-environment=@var{alist} -@itemx -e @var{alist} -@var{alist} is a Scheme alist defining the environment in which the Cabal -conditionals are evaluated. The accepted keys are: @code{os}, @code{arch}, -@code{impl} and a string representing the name of a flag. The value -associated with a flag has to be either the symbol @code{true} or -@code{false}. The value associated with other keys has to conform to the -Cabal file format definition. The default value associated with the keys -@code{os}, @code{arch} and @code{impl} is @samp{linux}, @samp{x86_64} and -@samp{ghc}, respectively. -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -The command below imports metadata for the latest version of the @code{HTTP} -Haskell package without including test dependencies and specifying the value -of the flag @samp{network-uri} as @code{false}: - -@example -guix import hackage -t -e "'((\"network-uri\" . false))" HTTP -@end example - -A specific package version may optionally be specified by following the -package name by an at-sign and a version number as in the following example: - -@example -guix import hackage mtl@@2.1.3.1 -@end example - -@item stackage -@cindex stackage -The @code{stackage} importer is a wrapper around the @code{hackage} one. It -takes a package name, looks up the package version included in a long-term -support (LTS) @uref{https://www.stackage.org, Stackage} release and uses the -@code{hackage} importer to retrieve its metadata. Note that it is up to you -to select an LTS release compatible with the GHC compiler used by Guix. - -Specific command-line options are: - -@table @code -@item --no-test-dependencies -@itemx -t -Do not include dependencies required only by the test suites. -@item --lts-version=@var{version} -@itemx -l @var{version} -@var{version} is the desired LTS release version. If omitted the latest -release is used. -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -The command below imports metadata for the @code{HTTP} Haskell package -included in the LTS Stackage release version 7.18: - -@example -guix import stackage --lts-version=7.18 HTTP -@end example - -@item elpa -@cindex elpa -Import metadata from an Emacs Lisp Package Archive (ELPA) package repository -(@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -Specific command-line options are: - -@table @code -@item --archive=@var{repo} -@itemx -a @var{repo} -@var{repo} identifies the archive repository from which to retrieve the -information. Currently the supported repositories and their identifiers -are: -@itemize - -@item -@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} -identifier. This is the default. - -Packages from @code{elpa.gnu.org} are signed with one of the keys contained -in the GnuPG keyring at @file{share/emacs/25.1/etc/package-keyring.gpg} (or -similar) in the @code{emacs} package (@pxref{Package Installation, ELPA -package signatures,, emacs, The GNU Emacs Manual}). - -@item -@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the -@code{melpa-stable} identifier. - -@item -@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa} -identifier. -@end itemize - -@item --recursive -@itemx -r -Traverse the dependency graph of the given upstream package recursively and -generate package expressions for all those packages that are not yet in -Guix. -@end table - -@item crate -@cindex crate -Import metadata from the crates.io Rust package repository -@uref{https://crates.io, crates.io}. - -@item opam -@cindex OPAM -@cindex OCaml -Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package -repository used by the OCaml community. -@end table - -The structure of the @command{guix import} code is modular. It would be -useful to have more importers for other package formats, and your help is -welcome here (@pxref{贡献}). - -@node Invoking guix refresh -@section Invoking @command{guix refresh} - -@cindex @command{guix refresh} -The primary audience of the @command{guix refresh} command is developers of -the GNU software distribution. By default, it reports any packages provided -by the distribution that are outdated compared to the latest upstream -version, like this: - -@example -$ guix refresh -gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1 -gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0 -@end example - -Alternately, one can specify packages to consider, in which case a warning -is emitted for packages that lack an updater: - -@example -$ guix refresh coreutils guile guile-ssh -gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh -gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13 -@end example - -@command{guix refresh} browses the upstream repository of each package and -determines the highest version number of the releases therein. The command -knows how to update specific types of packages: GNU packages, ELPA packages, -etc.---see the documentation for @option{--type} below. There are many -packages, though, for which it lacks a method to determine whether a new -upstream release is available. However, the mechanism is extensible, so -feel free to get in touch with us to add a new method! - -@table @code - -@item --recursive -Consider the packages specified, and all the packages upon which they -depend. - -@example -$ guix refresh --recursive coreutils -gnu/packages/acl.scm:35:2: warning: no updater for acl -gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4 -gnu/packages/xml.scm:68:2: warning: no updater for expat -gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp -@dots{} -@end example - -@end table - -Sometimes the upstream name differs from the package name used in Guix, and -@command{guix refresh} needs a little help. Most updaters honor the -@code{upstream-name} property in package definitions, which can be used to -that effect: - -@example -(define-public network-manager - (package - (name "network-manager") - ;; @dots{} - (properties '((upstream-name . "NetworkManager"))))) -@end example - -When passed @code{--update}, it modifies distribution source files to update -the version numbers and source tarball hashes of those package recipes -(@pxref{Defining Packages}). This is achieved by downloading each package's -latest source tarball and its associated OpenPGP signature, authenticating -the downloaded tarball against its signature using @command{gpg}, and -finally computing its hash. When the public key used to sign the tarball is -missing from the user's keyring, an attempt is made to automatically -retrieve it from a public key server; when this is successful, the key is -added to the user's keyring; otherwise, @command{guix refresh} reports an -error. - -The following options are supported: - -@table @code - -@item --expression=@var{expr} -@itemx -e @var{expr} -Consider the package @var{expr} evaluates to. - -This is useful to precisely refer to a package, as in this example: - -@example -guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)' -@end example - -This command lists the dependents of the ``final'' libc (essentially all the -packages.) - -@item --update -@itemx -u -Update distribution source files (package recipes) in place. This is -usually run from a checkout of the Guix source tree (@pxref{在安装之前运行Guix}): - -@example -$ ./pre-inst-env guix refresh -s non-core -u -@end example - -@xref{Defining Packages}, for more information on package definitions. - -@item --select=[@var{subset}] -@itemx -s @var{subset} -Select all the packages in @var{subset}, one of @code{core} or -@code{non-core}. - -The @code{core} subset refers to all the packages at the core of the -distribution---i.e., packages that are used to build ``everything else''. -This includes GCC, libc, Binutils, Bash, etc. Usually, changing one of -these packages in the distribution entails a rebuild of all the others. -Thus, such updates are an inconvenience to users in terms of build time or -bandwidth used to achieve the upgrade. - -The @code{non-core} subset refers to the remaining packages. It is -typically useful in cases where an update of the core packages would be -inconvenient. - -@item --manifest=@var{file} -@itemx -m @var{file} -Select all the packages from the manifest in @var{file}. This is useful to -check if any packages of the user manifest can be updated. - -@item --type=@var{updater} -@itemx -t @var{updater} -Select only packages handled by @var{updater} (may be a comma-separated list -of updaters). Currently, @var{updater} may be one of: - -@table @code -@item gnu -the updater for GNU packages; -@item gnome -the updater for GNOME packages; -@item kde -the updater for KDE packages; -@item xorg -the updater for X.org packages; -@item kernel.org -the updater for packages hosted on kernel.org; -@item elpa -the updater for @uref{http://elpa.gnu.org/, ELPA} packages; -@item cran -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 -the updater for @uref{http://www.cpan.org/, CPAN} packages; -@item pypi -the updater for @uref{https://pypi.python.org, PyPI} packages. -@item gem -the updater for @uref{https://rubygems.org, RubyGems} packages. -@item github -the updater for @uref{https://github.com, GitHub} packages. -@item hackage -the updater for @uref{https://hackage.haskell.org, Hackage} packages. -@item stackage -the updater for @uref{https://www.stackage.org, Stackage} packages. -@item crate -the updater for @uref{https://crates.io, Crates} packages. -@item launchpad -the updater for @uref{https://launchpad.net, Launchpad} packages. -@end table - -For instance, the following command only checks for updates of Emacs -packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages: - -@example -$ guix refresh --type=elpa,cran -gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0 -gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9 -@end example - -@end table - -In addition, @command{guix refresh} can be passed one or more package names, -as in this example: - -@example -$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8 -@end example - -@noindent -The command above specifically updates the @code{emacs} and @code{idutils} -packages. The @code{--select} option would have no effect in this case. - -When considering whether to upgrade a package, it is sometimes convenient to -know which packages would be affected by the upgrade and should be checked -for compatibility. For this the following option may be used when passing -@command{guix refresh} one or more package names: - -@table @code - -@item --list-updaters -@itemx -L -List available updaters and exit (see @option{--type} above.) - -For each updater, display the fraction of packages it covers; at the end, -display the fraction of packages covered by all these updaters. - -@item --list-dependent -@itemx -l -List top-level dependent packages that would need to be rebuilt as a result -of upgrading one or more packages. - -@xref{Invoking guix graph, the @code{reverse-package} type of @command{guix -graph}}, for information on how to visualize the list of dependents of a -package. - -@end table - -Be aware that the @code{--list-dependent} option only @emph{approximates} -the rebuilds that would be required as a result of an upgrade. More -rebuilds might be required under some circumstances. - -@example -$ guix refresh --list-dependent flex -Building the following 120 packages would ensure 213 dependent packages are rebuilt: -hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{} -@end example - -The command above lists a set of packages that could be built to check for -compatibility with an upgraded @code{flex} package. - -@table @code - -@item --list-transitive -List all the packages which one or more packages depend upon. - -@example -$ guix refresh --list-transitive flex -flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6 -bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{} -@end example - -@end table - -The command above lists a set of packages which, when changed, would cause -@code{flex} to be rebuilt. - -The following options can be used to customize GnuPG operation: - -@table @code - -@item --gpg=@var{command} -Use @var{command} as the GnuPG 2.x command. @var{command} is searched for -in @code{$PATH}. - -@item --keyring=@var{file} -Use @var{file} as the keyring for upstream keys. @var{file} must be in the -@dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx} -and the GNU@tie{}Privacy Guard (GPG) can manipulate these files -(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, -for information on a tool to manipulate keybox files). - -When this option is omitted, @command{guix refresh} uses -@file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream -signing keys. OpenPGP signatures are checked against keys from this -keyring; missing keys are downloaded to this keyring as well (see -@option{--key-download} below.) - -You can export keys from your default GPG keyring into a keybox file using -commands like this one: - -@example -gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx -@end example - -Likewise, you can fetch keys to a specific keybox file like this: - -@example -gpg --no-default-keyring --keyring mykeyring.kbx \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU -Privacy Guard}, for more information on GPG's @option{--keyring} option. - -@item --key-download=@var{policy} -Handle missing OpenPGP keys according to @var{policy}, which may be one of: - -@table @code -@item always -Always download missing OpenPGP keys from the key server, and add them to -the user's GnuPG keyring. - -@item never -Never try to download missing OpenPGP keys. Instead just bail out. - -@item interactive -When a package signed with an unknown OpenPGP key is encountered, ask the -user whether to download it or not. This is the default behavior. -@end table - -@item --key-server=@var{host} -Use @var{host} as the OpenPGP key server when importing a public key. - -@end table - -The @code{github} updater uses the @uref{https://developer.github.com/v3/, -GitHub API} to query for new releases. When used repeatedly e.g.@: when -refreshing all packages, GitHub will eventually refuse to answer any further -API requests. By default 60 API requests per hour are allowed, and a full -refresh on all GitHub packages in Guix requires more than this. -Authentication with GitHub through the use of an API token alleviates these -limits. To use an API token, set the environment variable -@code{GUIX_GITHUB_TOKEN} to a token procured from -@uref{https://github.com/settings/tokens} or otherwise. - - -@node Invoking guix lint -@section Invoking @command{guix lint} - -@cindex @command{guix lint} -@cindex package, checking for errors -The @command{guix lint} command is meant to help package developers avoid -common errors and use a consistent style. It runs a number of checks on a -given set of packages in order to find common mistakes in their -definitions. Available @dfn{checkers} include (see @code{--list-checkers} -for a complete list): - -@table @code -@item synopsis -@itemx description -Validate certain typographical and stylistic rules about package -descriptions and synopses. - -@item inputs-should-be-native -Identify inputs that should most likely be native inputs. - -@item source -@itemx home-page -@itemx mirror-url -@itemx github-url -@itemx source-file-name -Probe @code{home-page} and @code{source} URLs and report those that are -invalid. Suggest a @code{mirror://} URL when applicable. If the -@code{source} URL redirects to a GitHub URL, recommend usage of the GitHub -URL. Check that the source file name is meaningful, e.g.@: is not just a -version number or ``git-checkout'', without a declared @code{file-name} -(@pxref{origin Reference}). - -@item source-unstable-tarball -Parse the @code{source} URL to determine if a tarball from GitHub is -autogenerated or if it is a release tarball. Unfortunately GitHub's -autogenerated tarballs are sometimes regenerated. - -@item cve -@cindex security vulnerabilities -@cindex CVE, Common Vulnerabilities and Exposures -Report known vulnerabilities found in the Common Vulnerabilities and -Exposures (CVE) databases of the current and past year -@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US NIST}. - -To view information about a particular vulnerability, visit pages such as: - -@itemize -@item -@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD} -@item -@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD} -@end itemize - -@noindent -where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g., -@code{CVE-2015-7554}. - -Package developers can specify in package recipes the -@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)} name -and version of the package when they differ from the name or version that -Guix uses, as in this example: - -@example -(package - (name "grub") - ;; @dots{} - ;; CPE calls this package "grub2". - (properties '((cpe-name . "grub2") - (cpe-version . "2.3"))) -@end example - -@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>. -Some entries in the CVE database do not specify which version of a package -they apply to, and would thus ``stick around'' forever. Package developers -who found CVE alerts and verified they can be ignored can declare them as in -this example: - -@example -(package - (name "t1lib") - ;; @dots{} - ;; These CVEs no longer apply and can be safely ignored. - (properties `((lint-hidden-cve . ("CVE-2011-0433" - "CVE-2011-1553" - "CVE-2011-1554" - "CVE-2011-5244"))))) -@end example - -@item formatting -Warn about obvious source code formatting issues: trailing white space, use -of tabulations, etc. -@end table - -The general syntax is: - -@example -guix lint @var{options} @var{package}@dots{} -@end example - -If no package is given on the command line, then all packages are checked. -The @var{options} may be zero or more of the following: - -@table @code -@item --list-checkers -@itemx -l -List and describe all the available checkers that will be run on packages -and exit. - -@item --checkers -@itemx -c -Only enable the checkers specified in a comma-separated list using the names -returned by @code{--list-checkers}. - -@end table - -@node Invoking guix size -@section Invoking @command{guix size} - -@cindex size -@cindex package size -@cindex closure -@cindex @command{guix size} -The @command{guix size} command helps package developers profile the disk -usage of packages. It is easy to overlook the impact of an additional -dependency added to a package, or the impact of using a single output for a -package that could easily be split (@pxref{Packages with Multiple -Outputs}). Such are the typical issues that @command{guix size} can -highlight. - -The command can be passed one or more package specifications such as -@code{gcc@@4.8} or @code{guile:debug}, or a file name in the store. -Consider this example: - -@example -$ guix size coreutils -store item total self -/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1% -/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6% -/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0% -/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4% -/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9% -/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5% -/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3% -/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2% -total: 78.9 MiB -@end example - -@cindex closure -The store items listed here constitute the @dfn{transitive closure} of -Coreutils---i.e., Coreutils and all its dependencies, recursively---as would -be returned by: - -@example -$ guix gc -R /gnu/store/@dots{}-coreutils-8.23 -@end example - -Here the output shows three columns next to store items. The first column, -labeled ``total'', shows the size in mebibytes (MiB) of the closure of the -store item---that is, its own size plus the size of all its dependencies. -The next column, labeled ``self'', shows the size of the item itself. The -last column shows the ratio of the size of the item itself to the space -occupied by all the items listed here. - -In this example, we see that the closure of Coreutils weighs in at -79@tie{}MiB, most of which is taken by libc and GCC's run-time support -libraries. (That libc and GCC's libraries represent a large fraction of the -closure is not a problem @i{per se} because they are always available on the -system anyway.) - -When the package(s) passed to @command{guix size} are available in the -store@footnote{More precisely, @command{guix size} looks for the -@emph{ungrafted} variant of the given package(s), as returned by @code{guix -build @var{package} --no-grafts}. @xref{Security Updates}, for information -on grafts.}, @command{guix size} queries the daemon to determine its -dependencies, and measures its size in the store, similar to @command{du -ms ---apparent-size} (@pxref{du invocation,,, coreutils, GNU Coreutils}). - -When the given packages are @emph{not} in the store, @command{guix size} -reports information based on the available substitutes -(@pxref{Substitutes}). This makes it possible it to profile disk usage of -store items that are not even on disk, only available remotely. - -You can also specify several package names: - -@example -$ guix size coreutils grep sed bash -store item total self -/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4% -/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8% -/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6% -/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2% -@dots{} -total: 102.3 MiB -@end example - -@noindent -In this example we see that the combination of the four packages takes -102.3@tie{}MiB in total, which is much less than the sum of each closure -since they have a lot of dependencies in common. - -The available options are: - -@table @option - -@item --substitute-urls=@var{urls} -Use substitute information from @var{urls}. @xref{client-substitute-urls, -the same option for @code{guix build}}. - -@item --sort=@var{key} -Sort lines according to @var{key}, one of the following options: - -@table @code -@item self -the size of each item (the default); -@item closure -the total size of the item's closure. -@end table - -@item --map-file=@var{file} -Write a graphical map of disk usage in PNG format to @var{file}. - -For the example above, the map looks like this: - -@image{images/coreutils-size-map,5in,, map of Coreutils disk usage produced -by @command{guix size}} - -This option requires that -@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be -installed and visible in Guile's module search path. When that is not the -case, @command{guix size} fails as it tries to load it. - -@item --system=@var{system} -@itemx -s @var{system} -Consider packages for @var{system}---e.g., @code{x86_64-linux}. - -@end table - -@node Invoking guix graph -@section Invoking @command{guix graph} - -@cindex DAG -@cindex @command{guix graph} -@cindex package dependencies -Packages and their dependencies form a @dfn{graph}, specifically a directed -acyclic graph (DAG). It can quickly become difficult to have a mental model -of the package DAG, so the @command{guix graph} command provides a visual -representation of the DAG. By default, @command{guix graph} emits a DAG -representation in the input format of @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, 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 -guix graph @var{options} @var{package}@dots{} -@end example - -For example, the following command generates a PDF file representing the -package DAG for the GNU@tie{}Core Utilities, showing its build-time -dependencies: - -@example -guix graph coreutils | dot -Tpdf > dag.pdf -@end example - -The output looks like this: - -@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils} - -Nice little graph, no? - -But there is more than one graph! The one above is concise: it is the graph -of package objects, omitting implicit inputs such as GCC, libc, grep, etc. -It is often useful to have such a concise graph, but sometimes one may want -to see more details. @command{guix graph} supports several types of graphs, -allowing you to choose the level of detail: - -@table @code -@item package -This is the default type used in the example above. It shows the DAG of -package objects, excluding implicit dependencies. It is concise, but -filters out many details. - -@item reverse-package -This shows the @emph{reverse} DAG of packages. For example: - -@example -guix graph --type=reverse-package ocaml -@end example - -...@: yields the graph of packages that @emph{explicitly} depend on OCaml -(if you are also interested in cases where OCaml is an implicit dependency, -see @code{reverse-bag} below.) - -Note that for core packages this can yield huge graphs. If all you want is -to know the number of packages that depend on a given package, use -@command{guix refresh --list-dependent} (@pxref{Invoking guix refresh, -@option{--list-dependent}}). - -@item bag-emerged -This is the package DAG, @emph{including} implicit inputs. - -For instance, the following command: - -@example -guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf -@end example - -...@: yields this bigger graph: - -@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU -Coreutils} - -At the bottom of the graph, we see all the implicit inputs of -@var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}). - -Now, note that the dependencies of these implicit inputs---that is, the -@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown here, -for conciseness. - -@item bag -Similar to @code{bag-emerged}, but this time including all the bootstrap -dependencies. - -@item bag-with-origins -Similar to @code{bag}, but also showing origins and their dependencies. - -@item reverse-bag -This shows the @emph{reverse} DAG of packages. Unlike -@code{reverse-package}, it also takes implicit dependencies into account. -For example: - -@example -guix graph -t reverse-bag dune -@end example - -@noindent -...@: yields the graph of all packages that depend on Dune, directly or -indirectly. Since Dune is an @emph{implicit} dependency of many packages -@i{via} @code{dune-build-system}, this shows a large number of packages, -whereas @code{reverse-package} would show very few if any. - -@item derivation -This is the most detailed representation: It shows the DAG of derivations -(@pxref{Derivations}) and plain store items. Compared to the above -representation, many additional nodes are visible, including build scripts, -patches, Guile modules, etc. - -For this type of graph, it is also possible to pass a @file{.drv} file name -instead of a package name, as in: - -@example -guix graph -t derivation `guix system build -d my-config.scm` -@end example - -@item module -This is the graph of @dfn{package modules} (@pxref{Package Modules}). For -example, the following command shows the graph for the package module that -defines the @code{guile} package: - -@example -guix graph -t module guile | dot -Tpdf > module-graph.pdf -@end example -@end table - -All the types above correspond to @emph{build-time dependencies}. The -following graph type represents the @emph{run-time dependencies}: - -@table @code -@item references -This is the graph of @dfn{references} of a package output, as returned by -@command{guix gc --references} (@pxref{Invoking guix gc}). - -If the given package output is not available in the store, @command{guix -graph} attempts to obtain dependency information from substitutes. - -Here you can also pass a store file name instead of a package name. For -example, the command below produces the reference graph of your profile -(which can be big!): - -@example -guix graph -t references `readlink -f ~/.guix-profile` -@end example - -@item referrers -This is the graph of the @dfn{referrers} of a store item, as returned by -@command{guix gc --referrers} (@pxref{Invoking guix gc}). - -This relies exclusively on local information from your store. For instance, -let us suppose that the current Inkscape is available in 10 profiles on your -machine; @command{guix graph -t referrers inkscape} will show a graph rooted -at Inkscape and with those 10 profiles linked to it. - -It can help determine what is preventing a store item from being garbage -collected. - -@end table - -The available options are the following: - -@table @option -@item --type=@var{type} -@itemx -t @var{type} -Produce a graph output of @var{type}, where @var{type} must be one of the -values listed above. - -@item --list-types -List the supported graph types. - -@item --backend=@var{backend} -@itemx -b @var{backend} -Produce a graph using the selected @var{backend}. - -@item --list-backends -List the supported graph backends. - -Currently, the available backends are Graphviz and d3.js. - -@item --expression=@var{expr} -@itemx -e @var{expr} -Consider the package @var{expr} evaluates to. - -This is useful to precisely refer to a package, as in this example: - -@example -guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' -@end example - -@item --system=@var{system} -@itemx -s @var{system} -Display the graph for @var{system}---e.g., @code{i686-linux}. - -The package dependency graph is largely architecture-independent, but there -are some architecture-dependent bits that this option allows you to -visualize. -@end table - - - -@node Invoking guix publish -@section Invoking @command{guix publish} - -@cindex @command{guix publish} -The purpose of @command{guix publish} is to enable users to easily share -their store with others, who can then use it as a substitute server -(@pxref{Substitutes}). - -When @command{guix publish} runs, it spawns an HTTP server which allows -anyone with network access to obtain substitutes from it. This means that -any machine running Guix can also act as if it were a build farm, since the -HTTP interface is compatible with Hydra, the software behind the -@code{@value{SUBSTITUTE-SERVER}} build farm. - -For security, each substitute is signed, allowing recipients to check their -authenticity and integrity (@pxref{Substitutes}). Because @command{guix -publish} uses the signing key of the system, which is only readable by the -system administrator, it must be started as root; the @code{--user} option -makes it drop root privileges early on. - -The signing key pair must be generated before @command{guix publish} is -launched, using @command{guix archive --generate-key} (@pxref{Invoking guix -archive}). - -The general syntax is: - -@example -guix publish @var{options}@dots{} -@end example - -Running @command{guix publish} without any additional arguments will spawn -an HTTP server on port 8080: - -@example -guix publish -@end example - -Once a publishing server has been authorized (@pxref{Invoking guix -archive}), the daemon may download substitutes from it: - -@example -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. The -@command{guix weather} command provides a handy way to check what a server -provides (@pxref{Invoking guix weather}). - -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 publish} is running on -@code{example.org}, the following URL returns the raw -@file{hello-2.10.tar.gz} file with the given SHA256 hash (represented in -@code{nix-base32} format, @pxref{Invoking guix hash}): - -@example -http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i -@end example - -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 -@item --port=@var{port} -@itemx -p @var{port} -Listen for HTTP requests on @var{port}. - -@item --listen=@var{host} -Listen on the network interface for @var{host}. The default is to accept -connections from any interface. - -@item --user=@var{user} -@itemx -u @var{user} -Change privileges to @var{user} as soon as possible---i.e., once the server -socket is open and the signing key has been read. - -@item --compression[=@var{level}] -@itemx -C [@var{level}] -Compress data using the given @var{level}. When @var{level} is zero, -disable compression. The range 1 to 9 corresponds to different gzip -compression levels: 1 is the fastest, and 9 is the best (CPU-intensive). -The default is 3. - -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, 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 -(TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5 -days, @code{1m} means 1 month, and so on. - -This allows the user's Guix to keep substitute information in cache for -@var{ttl}. However, note that @code{guix publish} does not itself 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} and that no longer have a corresponding item in -the store, 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 Reference -Manual}) on @var{port} (37146 by default). This is used primarily for -debugging a running @command{guix publish} server. -@end table - -Enabling @command{guix publish} on Guix System is a one-liner: just -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:” - -@itemize -@item -If your host distro uses the systemd init system: - -@example -# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \ - /etc/systemd/system/ -# systemctl start guix-publish && systemctl enable guix-publish -@end example - -@item -If your host distro uses the Upstart init system: - -@example -# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/ -# start guix-publish -@end example - -@item -Otherwise, proceed similarly with your distro's init system. -@end itemize - -@node Invoking guix challenge -@section Invoking @command{guix challenge} - -@cindex reproducible builds -@cindex verifiable builds -@cindex @command{guix challenge} -@cindex challenge -Do the binaries provided by this server really correspond to the source code -it claims to build? Is a package build process deterministic? These are the -questions the @command{guix challenge} command attempts to answer. - -The former is obviously an important question: Before using a substitute -server (@pxref{Substitutes}), one had better @emph{verify} that it provides -the right binaries, and thus @emph{challenge} it. The latter is what -enables the former: If package builds are deterministic, then independent -builds of the package should yield the exact same result, bit for bit; if a -server provides a binary different from the one obtained locally, it may be -either corrupt or malicious. - -We know that the hash that shows up in @file{/gnu/store} file names is the -hash of all the inputs of the process that built the file or -directory---compilers, libraries, build scripts, -etc. (@pxref{Introduction}). Assuming deterministic build processes, one -store file name should map to exactly one build output. @command{guix -challenge} checks whether there is, indeed, a single mapping by comparing -the build outputs of several independent builds of any given store item. - -The command output looks like this: - -@smallexample -$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org" -updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0% -updating list of substitutes from 'https://guix.example.org'... 100.0% -/gnu/store/@dots{}-openssl-1.0.2d contents differ: - local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim -/gnu/store/@dots{}-git-2.5.0 contents differ: - local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f - https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 -/gnu/store/@dots{}-pius-2.1.1 contents differ: - local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs - -@dots{} - -6,406 store items were analyzed: - - 4,749 (74.1%) were identical - - 525 (8.2%) differed - - 1,132 (17.7%) were inconclusive -@end smallexample - -@noindent -In this example, @command{guix challenge} first scans the store to determine -the set of locally-built derivations---as opposed to store items that were -downloaded from a substitute server---and then queries all the substitute -servers. It then reports those store items for which the servers obtained a -result different from the local build. - -@cindex non-determinism, in package builds -As an example, @code{guix.example.org} always gets a different answer. -Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, -except in the case of Git. This might indicate that the build process of -Git is non-deterministic, meaning that its output varies as a function of -various things that Guix does not fully control, in spite of building -packages in isolated environments (@pxref{Features}). Most common sources -of non-determinism include the addition of timestamps in build results, the -inclusion of random numbers, and directory listings sorted by inode number. -See @uref{https://reproducible-builds.org/docs/}, for more information. - -To find out what is wrong with this Git binary, we can do something along -these lines (@pxref{Invoking guix archive}): - -@example -$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \ - | guix archive -x /tmp/git -$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git -@end example - -This command shows the difference between the files resulting from the local -build, and the files resulting from the build on -@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging -Files,, diffutils, Comparing and Merging Files}). The @command{diff} -command works great for text files. When binary files differ, a better -option is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps -visualize differences for all kinds of files. - -Once you have done that work, you can tell whether the differences are due -to a non-deterministic build process or to a malicious server. We try hard -to remove sources of non-determinism in packages to make it easier to verify -substitutes, but of course, this is a process that involves not just Guix, -but a large part of the free software community. In the meantime, -@command{guix challenge} is one tool to help address the problem. - -If you are writing packages for Guix, you are encouraged to check whether -@code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the -same build result as you did with: - -@example -$ guix challenge @var{package} -@end example - -@noindent -where @var{package} is a package specification such as @code{guile@@2.0} or -@code{glibc:debug}. - -The general syntax is: - -@example -guix challenge @var{options} [@var{packages}@dots{}] -@end example - -When a difference is found between the hash of a locally-built item and that -of a server-provided substitute, or among substitutes provided by different -servers, the command displays it as in the example above and its exit code -is 2 (other non-zero exit codes denote other kinds of errors.) - -The one option that matters is: - -@table @code - -@item --substitute-urls=@var{urls} -Consider @var{urls} the whitespace-separated list of substitute source URLs -to compare to. - -@item --verbose -@itemx -v -Show details about matches (identical contents) in addition to information -about mismatches. - -@end table - -@node Invoking guix copy -@section Invoking @command{guix copy} - -@cindex copy, of store items, over SSH -@cindex SSH, copy of store items -@cindex sharing store items across machines -@cindex transferring store items across machines -The @command{guix copy} command copies items from the store of one machine -to that of another machine over a secure shell (SSH) -connection@footnote{This command is available only when Guile-SSH was -found. @xref{Requirements}, for details.}. For example, the following -command copies the @code{coreutils} package, the user's profile, and all -their dependencies over to @var{host}, logged in as @var{user}: - -@example -guix copy --to=@var{user}@@@var{host} \ - coreutils `readlink -f ~/.guix-profile` -@end example - -If some of the items to be copied are already present on @var{host}, they -are not actually sent. - -The command below retrieves @code{libreoffice} and @code{gimp} from -@var{host}, assuming they are available there: - -@example -guix copy --from=@var{host} libreoffice gimp -@end example - -The SSH connection is established using the Guile-SSH client, which is -compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and -@file{~/.ssh/config}, and uses the SSH agent for authentication. - -The key used to sign items that are sent must be accepted by the remote -machine. Likewise, the key used by the remote machine to sign items you are -retrieving must be in @file{/etc/guix/acl} so it is accepted by your own -daemon. @xref{Invoking guix archive}, for more information about store item -authentication. - -The general syntax is: - -@example -guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{} -@end example - -You must always specify one of the following options: - -@table @code -@item --to=@var{spec} -@itemx --from=@var{spec} -Specify the host to send to or receive from. @var{spec} must be an SSH spec -such as @code{example.org}, @code{charlie@@example.org}, or -@code{charlie@@example.org:2222}. -@end table - -The @var{items} can be either package names, such as @code{gimp}, or store -items, such as @file{/gnu/store/@dots{}-idutils-4.6}. - -When specifying the name of a package to send, it is first built if needed, -unless @option{--dry-run} was specified. Common build options are supported -(@pxref{Common Build Options}). - - -@node Invoking guix container -@section Invoking @command{guix container} -@cindex container -@cindex @command{guix container} -@quotation Note -As of version @value{VERSION}, this tool is experimental. The interface is -subject to radical change in the future. -@end quotation - -The purpose of @command{guix container} is to manipulate processes running -within an isolated environment, commonly known as a ``container'', typically -created by the @command{guix environment} (@pxref{Invoking guix -environment}) and @command{guix system container} (@pxref{Invoking guix -system}) commands. - -The general syntax is: - -@example -guix container @var{action} @var{options}@dots{} -@end example - -@var{action} specifies the operation to perform with a container, and -@var{options} specifies the context-specific arguments for the action. - -The following actions are available: - -@table @code -@item exec -Execute a command within the context of a running container. - -The syntax is: - -@example -guix container exec @var{pid} @var{program} @var{arguments}@dots{} -@end example - -@var{pid} specifies the process ID of the running container. @var{program} -specifies an executable file name within the root file system of the -container. @var{arguments} are the additional options that will be passed -to @var{program}. - -The following command launches an interactive login shell inside a Guix -system container, started by @command{guix system container}, and whose -process ID is 9001: - -@example -guix container exec 9001 /run/current-system/profile/bin/bash --login -@end example - -Note that the @var{pid} cannot be the parent process of a container. It -must be PID 1 of the container or one of its child processes. - -@end table - -@node Invoking guix weather -@section Invoking @command{guix weather} - -Occasionally you're grumpy because substitutes are lacking and you end up -building packages by yourself (@pxref{Substitutes}). The @command{guix -weather} command reports on substitute availability on the specified servers -so you can have an idea of whether you'll be grumpy today. It can sometimes -be useful info as a user, but it is primarily useful to people running -@command{guix publish} (@pxref{Invoking guix publish}). - -@cindex statistics, for substitutes -@cindex availability of substitutes -@cindex substitute availability -@cindex weather, substitute availability -Here's a sample run: - -@example -$ guix weather --substitute-urls=https://guix.example.org -computing 5,872 package derivations for x86_64-linux... -looking for 6,128 store items on https://guix.example.org.. -updating list of substitutes from 'https://guix.example.org'... 100.0% -https://guix.example.org - 43.4% substitutes available (2,658 out of 6,128) - 7,032.5 MiB of nars (compressed) - 19,824.2 MiB on disk (uncompressed) - 0.030 seconds per request (182.9 seconds in total) - 33.5 requests per second - - 9.8% (342 out of 3,470) of the missing items are queued - 867 queued builds - x86_64-linux: 518 (59.7%) - i686-linux: 221 (25.5%) - aarch64-linux: 128 (14.8%) - build rate: 23.41 builds per hour - x86_64-linux: 11.16 builds per hour - i686-linux: 6.03 builds per hour - aarch64-linux: 6.41 builds per hour -@end example - -@cindex continuous integration, statistics -As you can see, it reports the fraction of all the packages for which -substitutes are available on the server---regardless of whether substitutes -are enabled, and regardless of whether this server's signing key is -authorized. It also reports the size of the compressed archives (``nars'') -provided by the server, the size the corresponding store items occupy in the -store (assuming deduplication is turned off), and the server's throughput. -The second part gives continuous integration (CI) statistics, if the server -supports it. In addition, using the @option{--coverage} option, -@command{guix weather} can list ``important'' package substitutes missing on -the server (see below). - -To achieve that, @command{guix weather} queries over HTTP(S) meta-data -(@dfn{narinfos}) for all the relevant store items. Like @command{guix -challenge}, it ignores signatures on those substitutes, which is innocuous -since the command only gathers statistics and cannot install those -substitutes. - -Among other things, it is possible to query specific system types and -specific package sets. The available options are listed below. - -@table @code -@item --substitute-urls=@var{urls} -@var{urls} is the space-separated list of substitute server URLs to query. -When this option is omitted, the default set of substitute servers is -queried. - -@item --system=@var{system} -@itemx -s @var{system} -Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This -option can be repeated, in which case @command{guix weather} will query -substitutes for several system types. - -@item --manifest=@var{file} -Instead of querying substitutes for all the packages, only ask for those -specified in @var{file}. @var{file} must contain a @dfn{manifest}, as with -the @code{-m} option of @command{guix package} (@pxref{Invoking guix -package}). - -@item --coverage[=@var{count}] -@itemx -c [@var{count}] -Report on substitute coverage for packages: list packages with at least -@var{count} dependents (zero by default) for which substitutes are -unavailable. Dependent packages themselves are not listed: if @var{b} -depends on @var{a} and @var{a} has no substitutes, only @var{a} is listed, -even though @var{b} usually lacks substitutes as well. The result looks -like this: - -@example -$ guix weather --substitute-urls=https://ci.guix.zh_CN.info -c 10 -computing 8,983 package derivations for x86_64-linux... -looking for 9,343 store items on https://ci.guix.zh_CN.info... -updating substitutes from 'https://ci.guix.zh_CN.info'... 100.0% -https://ci.guix.zh_CN.info - 64.7% substitutes available (6,047 out of 9,343) -@dots{} -2502 packages are missing from 'https://ci.guix.zh_CN.info' for 'x86_64-linux', among which: - 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0 - 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1 - 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008 - @dots{} -@end example - -What this example shows is that @code{kcoreaddons} and presumably the 58 -packages that depend on it have no substitutes at @code{ci.guix.zh_CN.info}; -likewise for @code{qgpgme} and the 46 packages that depend on it. - -If you are a Guix developer, or if you are taking care of this build farm, -you'll probably want to have a closer look at these packages: they may -simply fail to build. -@end table - -@node Invoking guix processes -@section Invoking @command{guix processes} - -The @command{guix processes} command can be useful to developers and system -administrators, especially on multi-user machines and on build farms: it -lists the current sessions (connections to the daemon), as well as -information about the processes involved@footnote{Remote sessions, when -@command{guix-daemon} is started with @option{--listen} specifying a TCP -endpoint, are @emph{not} listed.}. Here's an example of the information it -returns: - -@example -$ sudo guix processes -SessionPID: 19002 -ClientPID: 19090 -ClientCommand: guix environment --ad-hoc python - -SessionPID: 19402 -ClientPID: 19367 -ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{} - -SessionPID: 19444 -ClientPID: 19419 -ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} -LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock -LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock -LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock -ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800 -ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800 -ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800 -@end example - -In this example we see that @command{guix-daemon} has three clients: -@command{guix environment}, @command{guix publish}, and the Cuirass -continuous integration tool; their process identifier (PID) is given by the -@code{ClientPID} field. The @code{SessionPID} field gives the PID of the -@command{guix-daemon} sub-process of this particular session. - -The @code{LockHeld} fields show which store items are currently locked by -this session, which corresponds to store items being built or substituted -(the @code{LockHeld} field is not displayed when @command{guix processes} is -not running as root.) Last, by looking at the @code{ChildProcess} field, we -understand that these three builds are being offloaded (@pxref{Daemon -Offload Setup}). - -The output is in Recutils format so we can use the handy @command{recsel} -command to select sessions of interest (@pxref{Selection Expressions,,, -recutils, GNU recutils manual}). As an example, the command shows the -command line and PID of the client that triggered the build of a Perl -package: - -@example -$ sudo guix processes | \ - recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"' -ClientPID: 19419 -ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} -@end example - - -@node System Configuration -@chapter System Configuration - -@cindex system configuration -The Guix System Distribution supports a consistent whole-system -configuration mechanism. By that we mean that all aspects of the global -system configuration---such as the available system services, timezone and -locale settings, user accounts---are declared in a single place. Such a -@dfn{system configuration} can be @dfn{instantiated}---i.e., effected. - -@c Yes, we're talking of Puppet, Chef, & co. here. ↑ -One of the advantages of putting all the system configuration under the -control of Guix is that it supports transactional system upgrades, and makes -it possible to roll back to a previous system instantiation, should -something go wrong with the new one (@pxref{Features}). Another advantage -is that it makes it easy to replicate the exact same configuration across -different machines, or at different points in time, without having to resort -to additional administration tools layered on top of the own tools of the -system. - -This section describes this mechanism. First we focus on the system -administrator's viewpoint---explaining how the system is configured and -instantiated. Then we show how this mechanism can be extended, for instance -to support new system services. - -@menu -* Using the Configuration System:: Customizing your GNU system. -* operating-system Reference:: Detail of operating-system declarations. -* File Systems:: Configuring file system mounts. -* Mapped Devices:: Block device extra processing. -* User Accounts:: Specifying user accounts. -* Keyboard Layout:: How the system interprets key strokes. -* Locales:: Language and cultural convention settings. -* Services:: Specifying system services. -* Setuid Programs:: Programs running with root privileges. -* X.509 Certificates:: Authenticating HTTPS servers. -* Name Service Switch:: Configuring libc's name service switch. -* Initial RAM Disk:: Linux-Libre bootstrapping. -* Bootloader Configuration:: Configuring the boot loader. -* Invoking guix system:: Instantiating a system configuration. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* Defining Services:: Adding new service definitions. -@end menu - -@node Using the Configuration System -@section Using the Configuration System - -The operating system is configured by providing an @code{operating-system} -declaration in a file that can then be passed to the @command{guix system} -command (@pxref{Invoking guix system}). A simple setup, with the default -system services, the default Linux-Libre kernel, initial RAM disk, and boot -loader looks like this: - -@findex operating-system -@lisp -@include os-config-bare-bones.texi -@end lisp - -This example should be self-describing. Some of the fields defined above, -such as @code{host-name} and @code{bootloader}, are mandatory. Others, such -as @code{packages} and @code{services}, can be omitted, in which case they -get a default value. - -Below we discuss the effect of some of the most important fields -(@pxref{operating-system Reference}, for details about all the available -fields), and how to @dfn{instantiate} the operating system using -@command{guix system}. - -@unnumberedsubsec Bootloader - -@cindex legacy boot, on Intel machines -@cindex BIOS boot, on Intel machines -@cindex UEFI boot -@cindex EFI boot -The @code{bootloader} field describes the method that will be used to boot -your system. Machines based on Intel processors can boot in ``legacy'' BIOS -mode, as in the example above. However, more recent machines rely instead -on the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that -case, the @code{bootloader} field should contain something along these -lines: - -@example -(bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi")) -@end example - -@xref{Bootloader Configuration}, for more information on the available -configuration options. - -@unnumberedsubsec Globally-Visible Packages - -@vindex %base-packages -The @code{packages} field lists packages that will be globally visible on -the system, for all user accounts---i.e., in every user's @code{PATH} -environment variable---in addition to the per-user profiles (@pxref{Invoking -guix package}). The @var{%base-packages} variable provides all the tools -one would expect for basic user and administrator tasks---including the GNU -Core Utilities, the GNU Networking Utilities, the GNU Zile lightweight text -editor, @command{find}, @command{grep}, etc. The example above adds -GNU@tie{}Screen to those, taken from the @code{(gnu packages screen)} module -(@pxref{Package Modules}). The @code{(list package output)} syntax can be -used to add a specific output of a package: - -@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 @code{bind} above, has the -advantage of being unambiguous; it also allows typos and such to be -diagnosed right away as ``unbound variables''. The downside is that one -needs to know which module defines which package, and to augment the -@code{use-package-modules} line accordingly. To avoid that, one can use the -@code{specification->package} procedure of the @code{(gnu packages)} module, -which returns the best package for a given name or name and version: - -@lisp -(use-modules (gnu packages)) - -(operating-system - ;; ... - (packages (append (map specification->package - '("tcpdump" "htop" "gnupg@@2.0")) - %base-packages))) -@end lisp - -@unnumberedsubsec System Services - -@cindex services -@vindex %base-services -The @code{services} field lists @dfn{system services} to be made available -when the system starts (@pxref{Services}). The @code{operating-system} -declaration above specifies that, in addition to the basic services, we want -the OpenSSH secure shell daemon listening on port 2222 (@pxref{Networking -Services, @code{openssh-service-type}}). Under the hood, -@code{openssh-service-type} arranges so that @command{sshd} is started with -the right command-line options, possibly with supporting configuration files -generated as needed (@pxref{Defining Services}). - -@cindex customization, of services -@findex modify-services -Occasionally, instead of using the base services as is, you will want to -customize them. To do this, use @code{modify-services} (@pxref{Service -Reference, @code{modify-services}}) to modify the list. - -For example, suppose you want to modify @code{guix-daemon} and Mingetty (the -console log-in) in the @var{%base-services} list (@pxref{Base Services, -@code{%base-services}}). To do that, you can write the following in your -operating system declaration: - -@lisp -(define %my-services - ;; My very own list of services. - (modify-services %base-services - (guix-service-type config => - (guix-configuration - (inherit config) - (use-substitutes? #f) - (extra-options '("--gc-keep-derivations")))) - (mingetty-service-type config => - (mingetty-configuration - (inherit config))))) - -(operating-system - ;; @dots{} - (services %my-services)) -@end lisp - -This changes the configuration---i.e., the service parameters---of the -@code{guix-service-type} instance, and that of all the -@code{mingetty-service-type} instances in the @var{%base-services} list. -Observe how this is accomplished: first, we arrange for the original -configuration to be bound to the identifier @code{config} in the @var{body}, -and then we write the @var{body} so that it evaluates to the desired -configuration. In particular, notice how we use @code{inherit} to create a -new configuration which has the same values as the old configuration, but -with a few modifications. - -@cindex encrypted disk -The configuration for a typical ``desktop'' usage, with an encrypted root -partition, the X11 display server, GNOME and Xfce (users can choose which of -these desktop environments to use at the log-in screen by pressing -@kbd{F1}), network management, power management, and more, would look like -this: - -@lisp -@include os-config-desktop.texi -@end lisp - -A graphical system with a choice of lightweight window managers instead of -full-blown desktop environments would look like this: - -@lisp -@include os-config-lightweight-desktop.texi -@end lisp - -This example refers to the @file{/boot/efi} file system by its UUID, -@code{1234-ABCD}. Replace this UUID with the right UUID on your system, as -returned by the @command{blkid} command. - -@xref{Desktop Services}, for the exact list of services provided by -@var{%desktop-services}. @xref{X.509 Certificates}, for background -information about the @code{nss-certs} package that is used here. - -Again, @var{%desktop-services} is just a list of service objects. If you -want to remove services from there, you can do so using the procedures for -list filtering (@pxref{SRFI-1 Filtering and Partitioning,,, guile, GNU Guile -Reference Manual}). For instance, the following expression returns a list -that contains all the services in @var{%desktop-services} minus the Avahi -service: - -@example -(remove (lambda (service) - (eq? (service-kind service) avahi-service-type)) - %desktop-services) -@end example - -@unnumberedsubsec Instantiating the System - -Assuming the @code{operating-system} declaration is stored in the -@file{my-system-config.scm} file, the @command{guix system reconfigure -my-system-config.scm} command instantiates that configuration, and makes it -the default GRUB boot entry (@pxref{Invoking guix system}). - -The normal way to change the system configuration is by updating this file -and re-running @command{guix system reconfigure}. One should never have to -touch files in @file{/etc} or to run commands that modify the system state -such as @command{useradd} or @command{grub-install}. In fact, you must -avoid that since that would not only void your warranty but also prevent you -from rolling back to previous versions of your system, should you ever need -to. - -@cindex roll-back, of the operating system -Speaking of roll-back, each time you run @command{guix system reconfigure}, -a new @dfn{generation} of the system is created---without modifying or -deleting previous generations. Old system generations get an entry in the -bootloader boot menu, allowing you to boot them in case something went wrong -with the latest generation. Reassuring, no? The @command{guix system -list-generations} command lists the system generations available on disk. -It is also possible to roll back the system via the commands @command{guix -system roll-back} and @command{guix system switch-generation}. - -Although the @command{guix system reconfigure} command will not modify -previous generations, you must take care when the current generation is not -the latest (e.g., after invoking @command{guix system roll-back}), since the -operation might overwrite a later generation (@pxref{Invoking guix system}). - -@unnumberedsubsec The Programming Interface - -At the Scheme level, the bulk of an @code{operating-system} declaration is -instantiated with the following monadic procedure (@pxref{The Store Monad}): - -@deffn {Monadic Procedure} operating-system-derivation os -Return a derivation that builds @var{os}, an @code{operating-system} object -(@pxref{Derivations}). - -The output of the derivation is a single directory that refers to all the -packages, configuration files, and other supporting files needed to -instantiate @var{os}. -@end deffn - -This procedure is provided by the @code{(gnu system)} module. Along with -@code{(gnu services)} (@pxref{Services}), this module contains the guts of -Guix System. Make sure to visit it! - - -@node operating-system Reference -@section @code{operating-system} Reference - -This section summarizes all the options available in @code{operating-system} -declarations (@pxref{Using the Configuration System}). - -@deftp {Data Type} operating-system -This is the data type representing an operating system configuration. By -that, we mean all the global system configuration, not per-user -configuration (@pxref{Using the Configuration System}). - -@table @asis -@item @code{kernel} (default: @var{linux-libre}) -The package object of the operating system kernel to use@footnote{Currently -only the Linux-libre kernel is supported. In the future, it will be -possible to use the GNU@tie{}Hurd.}. - -@item @code{kernel-arguments} (default: @code{'("quiet")}) -List of strings or gexps representing additional arguments to pass on the -command-line of the kernel---e.g., @code{("console=ttyS0")}. - -@item @code{bootloader} -The system bootloader configuration object. @xref{Bootloader -Configuration}. - -@item @code{label} -This is the label (a string) as it appears in the bootloader's menu entry. -The default label includes the kernel name and version. - -@item @code{keyboard-layout} (default: @code{#f}) -This field specifies the keyboard layout to use in the console. It can be -either @code{#f}, in which case the default keyboard layout is used (usually -US English), or a @code{<keyboard-layout>} record. - -This keyboard layout is in effect as soon as the kernel has booted. For -instance, it is the keyboard layout in effect when you type a passphrase if -your root file system is on a @code{luks-device-mapping} mapped device -(@pxref{Mapped Devices}). - -@quotation Note -This does @emph{not} specify the keyboard layout used by the bootloader, nor -that used by the graphical display server. @xref{Bootloader Configuration}, -for information on how to specify the bootloader's keyboard layout. @xref{X -Window}, for information on how to specify the keyboard layout used by the X -Window System. -@end quotation - -@item @code{initrd-modules} (default: @code{%base-initrd-modules}) -@cindex initrd -@cindex initial RAM disk -The list of Linux kernel modules that need to be available in the initial -RAM disk. @xref{Initial RAM Disk}. - -@item @code{initrd} (default: @code{base-initrd}) -A procedure that returns an initial RAM disk for the Linux kernel. This -field is provided to support low-level customization and should rarely be -needed for casual use. @xref{Initial RAM Disk}. - -@item @code{firmware} (default: @var{%base-firmware}) -@cindex firmware -List of firmware packages loadable by the operating system kernel. - -The default includes firmware needed for Atheros- and Broadcom-based WiFi -devices (Linux-libre modules @code{ath9k} and @code{b43-open}, -respectively). @xref{Hardware Considerations}, for more info on supported -hardware. - -@item @code{host-name} -The host name. - -@item @code{hosts-file} -@cindex hosts file -A file-like object (@pxref{G-Expressions, file-like objects}) for use as -@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library Reference -Manual}). The default is a file with entries for @code{localhost} and -@var{host-name}. - -@item @code{mapped-devices} (default: @code{'()}) -A list of mapped devices. @xref{Mapped Devices}. - -@item @code{file-systems} -A list of file systems. @xref{File Systems}. - -@item @code{swap-devices} (default: @code{'()}) -@cindex swap devices -A list of strings identifying devices or files to be used for ``swap space'' -(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}). For -example, @code{'("/dev/sda3")} or @code{'("/swapfile")}. It is possible to -specify a swap file in a file system on a mapped device, provided that the -necessary device mapping and file system are also specified. @xref{Mapped -Devices} and @ref{File Systems}. - -@item @code{users} (default: @code{%base-user-accounts}) -@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 the -home directory of newly-created user accounts. - -For instance, a valid value may look like this: - -@example -`((".bashrc" ,(plain-file "bashrc" "echo Hello\n")) - (".guile" ,(plain-file "guile" - "(use-modules (ice-9 readline)) - (activate-readline)"))) -@end example - -@item @code{issue} (default: @var{%default-issue}) -A string denoting the contents of the @file{/etc/issue} file, which is -displayed when users log in on a text console. - -@item @code{packages} (default: @var{%base-packages}) -The set of packages installed in the global profile, which is accessible at -@file{/run/current-system/profile}. - -The default set includes core utilities and it is good practice to install -non-core utilities in user profiles (@pxref{Invoking guix package}). - -@item @code{timezone} -A timezone identifying string---e.g., @code{"Europe/Paris"}. - -You can run the @command{tzselect} command to find out which timezone string -corresponds to your region. Choosing an invalid timezone name causes -@command{guix system} to fail. - -@item @code{locale} (default: @code{"en_US.utf8"}) -The name of the default locale (@pxref{Locale Names,,, libc, The GNU C -Library Reference Manual}). @xref{Locales}, for more information. - -@item @code{locale-definitions} (default: @var{%default-locale-definitions}) -The list of locale definitions to be compiled and that may be used at run -time. @xref{Locales}. - -@item @code{locale-libcs} (default: @code{(list @var{glibc})}) -The list of GNU@tie{}libc packages whose locale data and tools are used to -build the locale definitions. @xref{Locales}, for compatibility -considerations that justify this option. - -@item @code{name-service-switch} (default: @var{%default-nss}) -Configuration of the libc name service switch (NSS)---a -@code{<name-service-switch>} object. @xref{Name Service Switch}, for -details. - -@item @code{services} (default: @var{%base-services}) -A list of service objects denoting system services. @xref{Services}. - -@cindex essential services -@item @code{essential-services} (default: ...) -The list of ``essential services''---i.e., things like instances of -@code{system-service-type} and @code{host-name-service-type} (@pxref{Service -Reference}), which are derived from the operating system definition itself. -As a user you should @emph{never} need to touch this field. - -@item @code{pam-services} (default: @code{(base-pam-services)}) -@cindex PAM -@cindex pluggable authentication modules -@c FIXME: Add xref to PAM services section. -Linux @dfn{pluggable authentication module} (PAM) services. - -@item @code{setuid-programs} (default: @var{%setuid-programs}) -List of string-valued G-expressions denoting setuid programs. @xref{Setuid -Programs}. - -@item @code{sudoers-file} (default: @var{%sudoers-specification}) -@cindex sudoers file -The contents of the @file{/etc/sudoers} file as a file-like object -(@pxref{G-Expressions, @code{local-file} and @code{plain-file}}). - -This file specifies which users can use the @command{sudo} command, what -they are allowed to do, and what privileges they may gain. The default is -that only @code{root} and members of the @code{wheel} group may use -@code{sudo}. - -@end table - -@deffn {Scheme Syntax} this-operating-system -When used in the @emph{lexical scope} of an operating system field -definition, this identifier resolves to the operating system being defined. - -The example below shows how to refer to the operating system being defined -in the definition of the @code{label} field: - -@example -(use-modules (gnu) (guix)) - -(operating-system - ;; ... - (label (package-full-name - (operating-system-kernel this-operating-system)))) -@end example - -It is an error to refer to @code{this-operating-system} outside an operating -system definition. -@end deffn - -@end deftp - -@node File Systems -@section File Systems - -The list of file systems to be mounted is specified in the -@code{file-systems} field of the operating system declaration (@pxref{Using -the Configuration System}). Each file system is declared using the -@code{file-system} form, like this: - -@example -(file-system - (mount-point "/home") - (device "/dev/sda3") - (type "ext4")) -@end example - -As usual, some of the fields are mandatory---those shown in the example -above---while others can be omitted. These are described below. - -@deftp {Data Type} file-system -Objects of this type represent file systems to be mounted. They contain the -following members: - -@table @asis -@item @code{type} -This is a string specifying the type of the file system---e.g., -@code{"ext4"}. - -@item @code{mount-point} -This designates the place where the file system is to be mounted. - -@item @code{device} -This names the ``source'' of the file system. It can be one of three -things: a file system label, a file system UUID, or the name of a -@file{/dev} node. Labels and UUIDs offer a way to refer to file systems -without having to hard-code their actual device name@footnote{Note that, -while it is tempting to use @file{/dev/disk/by-uuid} and similar device -names to achieve the same result, this is not recommended: These special -device nodes are created by the udev daemon and may be unavailable at the -time the device is mounted.}. - -@findex file-system-label -File system labels are created using the @code{file-system-label} procedure, -UUIDs are created using @code{uuid}, and @file{/dev} node are plain -strings. Here's an example of a file system referred to by its label, as -shown by the @command{e2label} command: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (file-system-label "my-home"))) -@end example - -@findex uuid -UUIDs are converted from their string representation (as shown by the -@command{tune2fs -l} command) using the @code{uuid} form@footnote{The -@code{uuid} form expects 16-byte UUIDs as defined in -@uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the form -of UUID used by the ext2 family of file systems and others, but it is -different from ``UUIDs'' found in FAT file systems, for instance.}, like -this: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) -@end example - -When the source of a file system is a mapped device (@pxref{Mapped -Devices}), its @code{device} field @emph{must} refer to the mapped device -name---e.g., @file{"/dev/mapper/root-partition"}. This is required so that -the system knows that mounting the file system depends on having the -corresponding device mapping established. - -@item @code{flags} (default: @code{'()}) -This is a list of symbols denoting mount flags. Recognized flags include -@code{read-only}, @code{bind-mount}, @code{no-dev} (disallow access to -special files), @code{no-suid} (ignore setuid and setgid bits), and -@code{no-exec} (disallow program execution.) - -@item @code{options} (default: @code{#f}) -This is either @code{#f}, or a string denoting mount options. - -@item @code{mount?} (default: @code{#t}) -This value indicates whether to automatically mount the file system when the -system is brought up. When set to @code{#f}, the file system gets an entry -in @file{/etc/fstab} (read by the @command{mount} command) but is not -automatically mounted. - -@item @code{needed-for-boot?} (default: @code{#f}) -This Boolean value indicates whether the file system is needed when -booting. If that is true, then the file system is mounted when the initial -RAM disk (initrd) is loaded. This is always the case, for instance, for the -root file system. - -@item @code{check?} (default: @code{#t}) -This Boolean indicates whether the file system needs to be checked for -errors before being mounted. - -@item @code{create-mount-point?} (default: @code{#f}) -When true, the mount point is created if it does not exist yet. - -@item @code{dependencies} (default: @code{'()}) -This is a list of @code{<file-system>} or @code{<mapped-device>} objects -representing file systems that must be mounted or mapped devices that must -be opened before (and unmounted or closed after) this one. - -As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is a -dependency of @file{/sys/fs/cgroup/cpu} and @file{/sys/fs/cgroup/memory}. - -Another example is a file system that depends on a mapped device, for -example for an encrypted partition (@pxref{Mapped Devices}). -@end table -@end deftp - -The @code{(gnu system file-systems)} exports the following useful variables. - -@defvr {Scheme Variable} %base-file-systems -These are essential file systems that are required on normal systems, such -as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see -below.) Operating system declarations should always contain at least these. -@end defvr - -@defvr {Scheme Variable} %pseudo-terminal-file-system -This is the file system to be mounted as @file{/dev/pts}. It supports -@dfn{pseudo-terminals} created @i{via} @code{openpty} and similar functions -(@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference Manual}). -Pseudo-terminals are used by terminal emulators such as @command{xterm}. -@end defvr - -@defvr {Scheme Variable} %shared-memory-file-system -This file system is mounted as @file{/dev/shm} and is used to support memory -sharing across processes (@pxref{Memory-mapped I/O, @code{shm_open},, libc, -The GNU C Library Reference Manual}). -@end defvr - -@defvr {Scheme Variable} %immutable-store -This file system performs a read-only ``bind mount'' of @file{/gnu/store}, -making it read-only for all the users including @code{root}. This prevents -against accidental modification by software running as @code{root} or by -system administrators. - -The daemon itself is still able to write to the store: it remounts it -read-write in its own ``name space.'' -@end defvr - -@defvr {Scheme Variable} %binary-format-file-system -The @code{binfmt_misc} file system, which allows handling of arbitrary -executable file types to be delegated to user space. This requires the -@code{binfmt.ko} kernel module to be loaded. -@end defvr - -@defvr {Scheme Variable} %fuse-control-file-system -The @code{fusectl} file system, which allows unprivileged users to mount and -unmount user-space FUSE file systems. This requires the @code{fuse.ko} -kernel module to be loaded. -@end defvr - -@node Mapped Devices -@section Mapped Devices - -@cindex device mapping -@cindex mapped devices -The Linux kernel has a notion of @dfn{device mapping}: a block device, such -as a hard disk partition, can be @dfn{mapped} into another device, usually -in @code{/dev/mapper/}, with additional processing over the data that flows -through it@footnote{Note that the GNU@tie{}Hurd makes no difference between -the concept of a ``mapped device'' and that of a file system: both boil down -to @emph{translating} input/output operations made on a file to operations -on its backing store. Thus, the Hurd implements mapped devices, like file -systems, using the generic @dfn{translator} mechanism (@pxref{Translators,,, -hurd, The GNU Hurd Reference Manual}).}. A typical example is encryption -device mapping: all writes to the mapped device are encrypted, and all reads -are deciphered, transparently. Guix extends this notion by considering any -device or set of devices that are @dfn{transformed} in some way to create a -new device; for instance, RAID devices are obtained by @dfn{assembling} -several other devices, such as hard disks or partitions, into a new one that -behaves as one partition. Other examples, not yet implemented, are LVM -logical volumes. - -Mapped devices are declared using the @code{mapped-device} form, defined as -follows; for examples, see below. - -@deftp {Data Type} mapped-device -Objects of this type represent device mappings that will be made when the -system boots up. - -@table @code -@item source -This is either a string specifying the name of the block device to be -mapped, such as @code{"/dev/sda3"}, or a list of such strings when several -devices need to be assembled for creating a new one. - -@item target -This string specifies the name of the resulting mapped device. For kernel -mappers such as encrypted devices of type @code{luks-device-mapping}, -specifying @code{"my-partition"} leads to the creation of the -@code{"/dev/mapper/my-partition"} device. For RAID devices of type -@code{raid-device-mapping}, the full device name such as @code{"/dev/md0"} -needs to be given. - -@item type -This must be a @code{mapped-device-kind} object, which specifies how -@var{source} is mapped to @var{target}. -@end table -@end deftp - -@defvr {Scheme Variable} luks-device-mapping -This defines LUKS block device encryption using the @command{cryptsetup} -command from the package with the same name. It relies on the -@code{dm-crypt} Linux kernel module. -@end defvr - -@defvr {Scheme Variable} raid-device-mapping -This defines a RAID device, which is assembled using the @code{mdadm} -command from the package with the same name. It requires a Linux kernel -module for the appropriate RAID level to be loaded, such as @code{raid456} -for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10. -@end defvr - -@cindex disk encryption -@cindex LUKS -The following example specifies a mapping from @file{/dev/sda3} to -@file{/dev/mapper/home} using LUKS---the -@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a -standard mechanism for disk encryption. The @file{/dev/mapper/home} device -can then be used as the @code{device} of a @code{file-system} declaration -(@pxref{File Systems}). - -@example -(mapped-device - (source "/dev/sda3") - (target "home") - (type luks-device-mapping)) -@end example - -Alternatively, to become independent of device numbering, one may obtain the -LUKS UUID (@dfn{unique identifier}) of the source device by a command like: - -@example -cryptsetup luksUUID /dev/sda3 -@end example - -and use it as follows: - -@example -(mapped-device - (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) - (target "home") - (type luks-device-mapping)) -@end example - -@cindex swap encryption -It is also desirable to encrypt swap space, since swap space may contain -sensitive data. One way to accomplish that is to use a swap file in a file -system on a device mapped via LUKS encryption. In this way, the swap file -is encrypted because the entire device is encrypted. @xref{Preparing for -Installation,,Disk Partitioning}, for an example. - -A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1} -may be declared as follows: - -@example -(mapped-device - (source (list "/dev/sda1" "/dev/sdb1")) - (target "/dev/md0") - (type raid-device-mapping)) -@end example - -The @file{/dev/md0} device can then be used as the @code{device} of a -@code{file-system} declaration (@pxref{File Systems}). Note that the RAID -level need not be given; it is chosen during the initial creation and -formatting of the RAID device and is determined automatically later. - - -@node User Accounts -@section User Accounts - -@cindex users -@cindex accounts -@cindex user accounts -User accounts and groups are entirely managed through the -@code{operating-system} declaration. They are specified with the -@code{user-account} and @code{user-group} forms: - -@example -(user-account - (name "alice") - (group "users") - (supplementary-groups '("wheel" ;allow use of sudo, etc. - "audio" ;sound card - "video" ;video devices such as webcams - "cdrom")) ;the good ol' CD-ROM - (comment "Bob's sister") - (home-directory "/home/alice")) -@end example - -When booting or upon completion of @command{guix system reconfigure}, the -system ensures that only the user accounts and groups specified in the -@code{operating-system} declaration exist, and with the specified -properties. Thus, account or group creations or modifications made by -directly invoking commands such as @command{useradd} are lost upon -reconfiguration or reboot. This ensures that the system remains exactly as -declared. - -@deftp {Data Type} user-account -Objects of this type represent user accounts. The following members may be -specified: - -@table @asis -@item @code{name} -The name of the user account. - -@item @code{group} -@cindex groups -This is the name (a string) or identifier (a number) of the user group this -account belongs to. - -@item @code{supplementary-groups} (default: @code{'()}) -Optionally, this can be defined as a list of group names that this account -belongs to. - -@item @code{uid} (default: @code{#f}) -This is the user ID for this account (a number), or @code{#f}. In the -latter case, a number is automatically chosen by the system when the account -is created. - -@item @code{comment} (default: @code{""}) -A comment about the account, such as the account owner's full name. - -@item @code{home-directory} -This is the name of the home directory for the account. - -@item @code{create-home-directory?} (default: @code{#t}) -Indicates whether the home directory of this account should be created if it -does not exist yet. - -@item @code{shell} (default: Bash) -This is a G-expression denoting the file name of a program to be used as the -shell (@pxref{G-Expressions}). - -@item @code{system?} (default: @code{#f}) -This Boolean value indicates whether the account is a ``system'' account. -System accounts are sometimes treated specially; for instance, graphical -login managers do not list them. - -@anchor{user-account-password} -@cindex password, for user accounts -@item @code{password} (default: @code{#f}) -You would normally leave this field to @code{#f}, initialize user passwords -as @code{root} with the @command{passwd} command, and then let users change -it with @command{passwd}. Passwords set with @command{passwd} are of course -preserved across reboot and reconfiguration. - -If you @emph{do} want to set an initial password for an account, then this -field must contain the encrypted password, as a string. You can use the -@code{crypt} procedure for this purpose: - -@example -(user-account - (name "charlie") - (group "users") - - ;; Specify a SHA-512-hashed initial password. - (password (crypt "InitialPassword!" "$6$abc"))) -@end example - -@quotation Note -The hash of this initial password will be available in a file in -@file{/gnu/store}, readable by all the users, so this method must be used -with care. -@end quotation - -@xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for -more information on password encryption, and @ref{Encryption,,, guile, GNU -Guile Reference Manual}, for information on Guile's @code{crypt} procedure. - -@end table -@end deftp - -@cindex groups -User group declarations are even simpler: - -@example -(user-group (name "students")) -@end example - -@deftp {Data Type} user-group -This type is for, well, user groups. There are just a few fields: - -@table @asis -@item @code{name} -The name of the group. - -@item @code{id} (default: @code{#f}) -The group identifier (a number). If @code{#f}, a new number is -automatically allocated when the group is created. - -@item @code{system?} (default: @code{#f}) -This Boolean value indicates whether the group is a ``system'' group. -System groups have low numerical IDs. - -@item @code{password} (default: @code{#f}) -What, user groups can have a password? Well, apparently yes. Unless -@code{#f}, this field specifies the password of the group. - -@end table -@end deftp - -For convenience, a variable lists all the basic user groups one may expect: - -@defvr {Scheme Variable} %base-groups -This is the list of basic user groups that users and/or packages expect to -be present on the system. This includes groups such as ``root'', ``wheel'', -and ``users'', as well as groups used to control access to specific devices -such as ``audio'', ``disk'', and ``cdrom''. -@end defvr - -@defvr {Scheme Variable} %base-user-accounts -This is the list of basic system accounts that programs may expect to find -on a GNU/Linux system, such as the ``nobody'' account. - -Note that the ``root'' account is not included here. It is a special-case -and is automatically added whether or not it is specified. -@end defvr - -@node Keyboard Layout -@section Keyboard Layout - -@cindex keyboard layout -@cindex keymap -To specify what each key of your keyboard does, you need to tell the -operating system what @dfn{keyboard layout} you want to use. The default, -when nothing is specified, is the US English QWERTY layout for 105-key PC -keyboards. However, German speakers will usually prefer the German QWERTZ -layout, French speakers will want the AZERTY layout, and so on; hackers -might prefer Dvorak or bépo, and they might even want to further customize -the effect of some of the keys. This section explains how to get that done. - -@cindex keyboard layout, definition -There are three components that will want to know about your keyboard -layout: - -@itemize -@item -The @emph{bootloader} may want to know what keyboard layout you want to use -(@pxref{Bootloader Configuration, @code{keyboard-layout}}). This is useful -if you want, for instance, to make sure that you can type the passphrase of -your encrypted root partition using the right layout. - -@item -The @emph{operating system kernel}, Linux, will need that so that the -console is properly configured (@pxref{operating-system Reference, -@code{keyboard-layout}}). - -@item -The @emph{graphical display server}, usually Xorg, also has its own idea of -the keyboard layout (@pxref{X Window, @code{keyboard-layout}}). -@end itemize - -Guix allows you to configure all three separately but, fortunately, it -allows you to share the same keyboard layout for all three components. - -@cindex XKB, keyboard layouts -Keyboard layouts are represented by records created by the -@code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following -the X Keyboard extension (XKB), each layout has four attributes: a name -(often a language code such as ``fi'' for Finnish or ``jp'' for Japanese), -an optional variant name, an optional keyboard model name, and a possibly -empty list of additional options. In most cases the layout name is all you -care about. Here are a few example: - -@example -;; The German QWERTZ layout. Here we assume a standard -;; "pc105" keyboard model. -(keyboard-layout "de") - -;; The bépo variant of the French layout. -(keyboard-layout "fr" "bepo") - -;; The Catalan layout. -(keyboard-layout "es" "cat") - -;; The Latin American Spanish layout. In addition, the -;; "Caps Lock" key is used as an additional "Ctrl" key, -;; and the "Menu" key is used as a "Compose" key to enter -;; accented letters. -(keyboard-layout "latam" - #:options '("ctrl:nocaps" "compose:menu")) - -;; The Russian layout for a ThinkPad keyboard. -(keyboard-layout "ru" #:model "thinkpad") - -;; The "US international" layout, which is the US layout plus -;; dead keys to enter accented characters. This is for an -;; Apple MacBook keyboard. -(keyboard-layout "us" "intl" #:model "macbook78") -@end example - -See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} -package for a complete list of supported layouts, variants, and models. - -@cindex keyboard layout, configuration -Let's say you want your system to use the Turkish keyboard layout throughout -your system---bootloader, console, and Xorg. Here's what your system -configuration would look like: - -@findex set-xorg-configuration -@lisp -;; Using the Turkish layout for the bootloader, the console, -;; and for Xorg. - -(operating-system - ;; ... - (keyboard-layout (keyboard-layout "tr")) ;for the console - (bootloader (bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi") - (keyboard-layout keyboard-layout))) ;for GRUB - (services (cons (set-xorg-configuration - (xorg-configuration ;for Xorg - (keyboard-layout keyboard-layout))) - %desktop-services))) -@end lisp - -In the example above, for GRUB and for Xorg, we just refer to the -@code{keyboard-layout} field defined above, but we could just as well refer -to a different layout. The @code{set-xorg-configuration} procedure -communicates the desired Xorg configuration to the graphical log-in manager, -by default GDM. - -We've discussed how to specify the @emph{default} keyboard layout of your -system when it starts, but you can also adjust it at run time: - -@itemize -@item -If you're using GNOME, its settings panel has a ``Region & Language'' entry -where you can select one or more keyboard layouts. - -@item -Under Xorg, the @command{setxkbmap} command (from the same-named package) -allows you to change the current layout. For example, this is how you would -change the layout to US Dvorak: - -@example -setxkbmap us dvorak -@end example - -@item -The @code{loadkeys} command changes the keyboard layout in effect in the -Linux console. However, note that @code{loadkeys} does @emph{not} use the -XKB keyboard layout categorization described above. The command below loads -the French bépo layout: - -@example -loadkeys fr-bepo -@end example -@end itemize - -@node Locales -@section Locales - -@cindex locale -A @dfn{locale} defines cultural conventions for a particular language and -region of the world (@pxref{Locales,,, libc, The GNU C Library Reference -Manual}). Each locale has a name that typically has the form -@code{@var{language}_@var{territory}.@var{codeset}}---e.g., -@code{fr_LU.utf8} designates the locale for the French language, with -cultural conventions from Luxembourg, and using the UTF-8 encoding. - -@cindex locale definition -Usually, you will want to specify the default locale for the machine using -the @code{locale} field of the @code{operating-system} declaration -(@pxref{operating-system Reference, @code{locale}}). - -The selected locale is automatically added to the @dfn{locale definitions} -known to the system if needed, with its codeset inferred from its -name---e.g., @code{bo_CN.utf8} will be assumed to use the @code{UTF-8} -codeset. Additional locale definitions can be specified in the -@code{locale-definitions} slot of @code{operating-system}---this is useful, -for instance, if the codeset could not be inferred from the locale name. -The default set of locale definitions includes some widely used locales, but -not all the available locales, in order to save space. - -For instance, to add the North Frisian locale for Germany, the value of that -field may be: - -@example -(cons (locale-definition - (name "fy_DE.utf8") (source "fy_DE")) - %default-locale-definitions) -@end example - -Likewise, to save space, one might want @code{locale-definitions} to list -only the locales that are actually used, as in: - -@example -(list (locale-definition - (name "ja_JP.eucjp") (source "ja_JP") - (charset "EUC-JP"))) -@end example - -@vindex LOCPATH -The compiled locale definitions are available at -@file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc version, -which is the default location where the GNU@tie{}libc provided by Guix looks -for locale data. This can be overridden using the @code{LOCPATH} -environment variable (@pxref{locales-and-locpath, @code{LOCPATH} and locale -packages}). - -The @code{locale-definition} form is provided by the @code{(gnu system -locale)} module. Details are given below. - -@deftp {Data Type} locale-definition -This is the data type of a locale definition. - -@table @asis - -@item @code{name} -The name of the locale. @xref{Locale Names,,, libc, The GNU C Library -Reference Manual}, for more information on locale names. - -@item @code{source} -The name of the source for that locale. This is typically the -@code{@var{language}_@var{territory}} part of the locale name. - -@item @code{charset} (default: @code{"UTF-8"}) -The ``character set'' or ``code set'' for that locale, -@uref{http://www.iana.org/assignments/character-sets, as defined by IANA}. - -@end table -@end deftp - -@defvr {Scheme Variable} %default-locale-definitions -A list of commonly used UTF-8 locales, used as the default value of the -@code{locale-definitions} field of @code{operating-system} declarations. - -@cindex locale name -@cindex normalized codeset in locale names -These locale definitions use the @dfn{normalized codeset} for the part that -follows the dot in the name (@pxref{Using gettextized software, normalized -codeset,, libc, The GNU C Library Reference Manual}). So for instance it -has @code{uk_UA.utf8} but @emph{not}, say, @code{uk_UA.UTF-8}. -@end defvr - -@subsection Locale Data Compatibility Considerations - -@cindex incompatibility, of locale data -@code{operating-system} declarations provide a @code{locale-libcs} field to -specify the GNU@tie{}libc packages that are used to compile locale -declarations (@pxref{operating-system Reference}). ``Why would I care?'', -you may ask. Well, it turns out that the binary format of locale data is -occasionally incompatible from one libc version to another. - -@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html> -@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>. -For instance, a program linked against libc version 2.21 is unable to read -locale data produced with libc 2.22; worse, that program @emph{aborts} -instead of simply ignoring the incompatible locale data@footnote{Versions -2.23 and later of GNU@tie{}libc will simply skip the incompatible locale -data, which is already an improvement.}. Similarly, a program linked -against libc 2.22 can read most, but not all, of the locale data from libc -2.21 (specifically, @code{LC_COLLATE} data is incompatible); thus calls to -@code{setlocale} may fail, but programs will not abort. - -The ``problem'' with Guix is that users have a lot of freedom: They can -choose whether and when to upgrade software in their profiles, and might be -using a libc version different from the one the system administrator used to -build the system-wide locale data. - -Fortunately, unprivileged users can also install their own locale data and -define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath, -@code{GUIX_LOCPATH} and locale packages}). - -Still, it is best if the system-wide locale data at -@file{/run/current-system/locale} is built for all the libc versions -actually in use on the system, so that all the programs can access it---this -is especially crucial on a multi-user system. To do that, the administrator -can specify several libc packages in the @code{locale-libcs} field of -@code{operating-system}: - -@example -(use-package-modules base) - -(operating-system - ;; @dots{} - (locale-libcs (list glibc-2.21 (canonical-package glibc)))) -@end example - -This example would lead to a system containing locale definitions for both -libc 2.21 and the current version of libc in -@file{/run/current-system/locale}. - - -@node Services -@section Services - -@cindex system services -An important part of preparing an @code{operating-system} declaration is -listing @dfn{system services} and their configuration (@pxref{Using the -Configuration System}). System services are typically daemons launched when -the system boots, or other actions needed at that time---e.g., configuring -network access. - -Guix has a broad definition of ``service'' (@pxref{Service Composition}), -but many services are managed by the GNU@tie{}Shepherd (@pxref{Shepherd -Services}). On a running system, the @command{herd} command allows you to -list the available services, show their status, start and stop them, or do -other specific operations (@pxref{Jump Start,,, shepherd, The GNU Shepherd -Manual}). For example: - -@example -# herd status -@end example - -The above command, run as @code{root}, lists the currently defined -services. The @command{herd doc} command shows a synopsis of the given -service and its associated actions: - -@example -# herd doc nscd -Run libc's name service cache daemon (nscd). - -# herd doc nscd action invalidate -invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups. -@end example - -The @command{start}, @command{stop}, and @command{restart} sub-commands have -the effect you would expect. For instance, the commands below stop the nscd -service and restart the Xorg display server: - -@example -# herd stop nscd -Service nscd has been stopped. -# herd restart xorg-server -Service xorg-server has been stopped. -Service xorg-server has been started. -@end example - -The following sections document the available services, starting with the -core services, that may be used in an @code{operating-system} declaration. - -@menu -* Base Services:: Essential system services. -* Scheduled Job Execution:: The mcron service. -* Log Rotation:: The rottlog service. -* Networking Services:: Network setup, SSH daemon, etc. -* X Window:: Graphical display. -* Printing Services:: Local and remote printer support. -* Desktop Services:: D-Bus and desktop services. -* Sound Services:: ALSA and Pulseaudio services. -* Database Services:: SQL databases, key-value stores, etc. -* Mail Services:: IMAP, POP3, SMTP, and all that. -* Messaging Services:: Messaging services. -* Telephony Services:: Telephony services. -* Monitoring Services:: Monitoring services. -* Kerberos Services:: Kerberos services. -* LDAP Services:: LDAP services. -* Web Services:: Web servers. -* Certificate Services:: TLS certificates via Let's Encrypt. -* DNS Services:: DNS daemons. -* VPN Services:: VPN daemons. -* Network File System:: NFS related services. -* Continuous Integration:: The Cuirass service. -* Power Management Services:: Extending battery life. -* Audio Services:: The MPD. -* Virtualization Services:: Virtualization services. -* Version Control Services:: Providing remote access to Git repositories. -* Game Services:: Game servers. -* Miscellaneous Services:: Other services. -@end menu - -@node Base Services -@subsection Base Services - -The @code{(gnu services base)} module provides definitions for the basic -services that one expects from the system. The services exported by this -module are listed below. - -@defvr {Scheme Variable} %base-services -This variable contains a list of basic services (@pxref{Service Types and -Services}, for more information on service objects) one would expect from -the system: a login service (mingetty) on each tty, syslogd, the libc name -service cache daemon (nscd), the udev device manager, and more. - -This is the default value of the @code{services} field of -@code{operating-system} declarations. Usually, when customizing a system, -you will want to append services to @var{%base-services}, like this: - -@example -(append (list (service avahi-service-type) - (service openssh-service-type)) - %base-services) -@end example -@end defvr - -@defvr {Scheme Variable} special-files-service-type -This is the service that sets up ``special files'' such as @file{/bin/sh}; -an instance of it is part of @code{%base-services}. - -The value associated with @code{special-files-service-type} services must be -a list of tuples where the first element is the ``special file'' and the -second element is its target. By default it is: - -@cindex @file{/bin/sh} -@cindex @file{sh}, in @file{/bin} -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))) -@end example - -@cindex @file{/usr/bin/env} -@cindex @file{env}, in @file{/usr/bin} -If you want to add, say, @code{/usr/bin/env} to your system, you can change -it to: - -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) - ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) -@end example - -Since this is part of @code{%base-services}, you can use -@code{modify-services} to customize the set of special files (@pxref{Service -Reference, @code{modify-services}}). But the simple way to add a special -file is @i{via} the @code{extra-special-file} procedure (see below.) -@end defvr - -@deffn {Scheme Procedure} extra-special-file @var{file} @var{target} -Use @var{target} as the ``special file'' @var{file}. - -For example, adding the following lines to the @code{services} field of your -operating system declaration leads to a @file{/usr/bin/env} symlink: - -@example -(extra-special-file "/usr/bin/env" - (file-append coreutils "/bin/env")) -@end example -@end deffn - -@deffn {Scheme Procedure} host-name-service @var{name} -Return a service that sets the host name to @var{name}. -@end deffn - -@deffn {Scheme Procedure} login-service @var{config} -Return a service to run login according to @var{config}, a -@code{<login-configuration>} object, which specifies the message of the day, -among other things. -@end deffn - -@deftp {Data Type} login-configuration -This is the data type representing the configuration of login. - -@table @asis - -@item @code{motd} -@cindex message of the day -A file-like object containing the ``message of the day''. - -@item @code{allow-empty-passwords?} (default: @code{#t}) -Allow empty passwords by default so that first-time users can log in when -the 'root' account has just been created. - -@end table -@end deftp - -@deffn {Scheme Procedure} mingetty-service @var{config} -Return a service to run mingetty according to @var{config}, a -@code{<mingetty-configuration>} object, which specifies the tty to run, -among other things. -@end deffn - -@deftp {Data Type} mingetty-configuration -This is the data type representing the configuration of Mingetty, which -provides the default implementation of virtual console log-in. - -@table @asis - -@item @code{tty} -The name of the console this Mingetty runs on---e.g., @code{"tty1"}. - -@item @code{auto-login} (default: @code{#f}) -When true, this field must be a string denoting the user name under which -the system automatically logs in. When it is @code{#f}, a user name and -password must be entered to log in. - -@item @code{login-program} (default: @code{#f}) -This must be either @code{#f}, in which case the default log-in program is -used (@command{login} from the Shadow tool suite), or a gexp denoting the -name of the log-in program. - -@item @code{login-pause?} (default: @code{#f}) -When set to @code{#t} in conjunction with @var{auto-login}, the user will -have to press a key before the log-in shell is launched. - -@item @code{mingetty} (default: @var{mingetty}) -The Mingetty package to use. - -@end table -@end deftp - -@deffn {Scheme Procedure} agetty-service @var{config} -Return a service to run agetty according to @var{config}, an -@code{<agetty-configuration>} object, which specifies the tty to run, among -other things. -@end deffn - -@deftp {Data Type} agetty-configuration -This is the data type representing the configuration of agetty, which -implements virtual and serial console log-in. See the @code{agetty(8)} man -page for more information. - -@table @asis - -@item @code{tty} -The name of the console this agetty runs on, as a string---e.g., -@code{"ttyS0"}. This argument is optional, it will default to a reasonable -default serial port used by the kernel Linux. - -For this, if there is a value for an option @code{agetty.tty} in the kernel -command line, agetty will extract the device name of the serial port from it -and use that. - -If not and if there is a value for an option @code{console} with a tty in -the Linux command line, agetty will extract the device name of the serial -port from it and use that. - -In both cases, agetty will leave the other serial device settings (baud rate -etc.)@: alone---in the hope that Linux pinned them to the correct values. - -@item @code{baud-rate} (default: @code{#f}) -A string containing a comma-separated list of one or more baud rates, in -descending order. - -@item @code{term} (default: @code{#f}) -A string containing the value used for the @code{TERM} environment variable. - -@item @code{eight-bits?} (default: @code{#f}) -When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection -is disabled. - -@item @code{auto-login} (default: @code{#f}) -When passed a login name, as a string, the specified user will be logged in -automatically without prompting for their login name or password. - -@item @code{no-reset?} (default: @code{#f}) -When @code{#t}, don't reset terminal cflags (control modes). - -@item @code{host} (default: @code{#f}) -This accepts a string containing the "login_host", which will be written -into the @file{/var/run/utmpx} file. - -@item @code{remote?} (default: @code{#f}) -When set to @code{#t} in conjunction with @var{host}, this will add an -@code{-r} fakehost option to the command line of the login program specified -in @var{login-program}. - -@item @code{flow-control?} (default: @code{#f}) -When set to @code{#t}, enable hardware (RTS/CTS) flow control. - -@item @code{no-issue?} (default: @code{#f}) -When set to @code{#t}, the contents of the @file{/etc/issue} file will not -be displayed before presenting the login prompt. - -@item @code{init-string} (default: @code{#f}) -This accepts a string that will be sent to the tty or modem before sending -anything else. It can be used to initialize a modem. - -@item @code{no-clear?} (default: @code{#f}) -When set to @code{#t}, agetty will not clear the screen before showing the -login prompt. - -@item @code{login-program} (default: (file-append shadow "/bin/login")) -This must be either a gexp denoting the name of a log-in program, or unset, -in which case the default value is the @command{login} from the Shadow tool -suite. - -@item @code{local-line} (default: @code{#f}) -Control the CLOCAL line flag. This accepts one of three symbols as -arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f}, the -default value chosen by agetty is @code{'auto}. - -@item @code{extract-baud?} (default: @code{#f}) -When set to @code{#t}, instruct agetty to try to extract the baud rate from -the status messages produced by certain types of modems. - -@item @code{skip-login?} (default: @code{#f}) -When set to @code{#t}, do not prompt the user for a login name. This can be -used with @var{login-program} field to use non-standard login systems. - -@item @code{no-newline?} (default: @code{#f}) -When set to @code{#t}, do not print a newline before printing the -@file{/etc/issue} file. - -@c Is this dangerous only when used with login-program, or always? -@item @code{login-options} (default: @code{#f}) -This option accepts a string containing options that are passed to the login -program. When used with the @var{login-program}, be aware that a malicious -user could try to enter a login name containing embedded options that could -be parsed by the login program. - -@item @code{login-pause} (default: @code{#f}) -When set to @code{#t}, wait for any key before showing the login prompt. -This can be used in conjunction with @var{auto-login} to save memory by -lazily spawning shells. - -@item @code{chroot} (default: @code{#f}) -Change root to the specified directory. This option accepts a directory -path as a string. - -@item @code{hangup?} (default: @code{#f}) -Use the Linux system call @code{vhangup} to do a virtual hangup of the -specified terminal. - -@item @code{keep-baud?} (default: @code{#f}) -When set to @code{#t}, try to keep the existing baud rate. The baud rates -from @var{baud-rate} are used when agetty receives a @key{BREAK} character. - -@item @code{timeout} (default: @code{#f}) -When set to an integer value, terminate if no user name could be read within -@var{timeout} seconds. - -@item @code{detect-case?} (default: @code{#f}) -When set to @code{#t}, turn on support for detecting an uppercase-only -terminal. This setting will detect a login name containing only uppercase -letters as indicating an uppercase-only terminal and turn on some -upper-to-lower case conversions. Note that this will not support Unicode -characters. - -@item @code{wait-cr?} (default: @code{#f}) -When set to @code{#t}, wait for the user or modem to send a carriage-return -or linefeed character before displaying @file{/etc/issue} or login prompt. -This is typically used with the @var{init-string} option. - -@item @code{no-hints?} (default: @code{#f}) -When set to @code{#t}, do not print hints about Num, Caps, and Scroll locks. - -@item @code{no-hostname?} (default: @code{#f}) -By default, the hostname is printed. When this option is set to @code{#t}, -no hostname will be shown at all. - -@item @code{long-hostname?} (default: @code{#f}) -By default, the hostname is only printed until the first dot. When this -option is set to @code{#t}, the fully qualified hostname by -@code{gethostname} or @code{getaddrinfo} is shown. - -@item @code{erase-characters} (default: @code{#f}) -This option accepts a string of additional characters that should be -interpreted as backspace when the user types their login name. - -@item @code{kill-characters} (default: @code{#f}) -This option accepts a string that should be interpreted to mean "ignore all -previous characters" (also called a "kill" character) when the types their -login name. - -@item @code{chdir} (default: @code{#f}) -This option accepts, as a string, a directory path that will be changed to -before login. - -@item @code{delay} (default: @code{#f}) -This options accepts, as an integer, the number of seconds to sleep before -opening the tty and displaying the login prompt. - -@item @code{nice} (default: @code{#f}) -This option accepts, as an integer, the nice value with which to run the -@command{login} program. - -@item @code{extra-options} (default: @code{'()}) -This option provides an "escape hatch" for the user to provide arbitrary -command-line arguments to @command{agetty} as a list of strings. - -@end table -@end deftp - -@deffn {Scheme Procedure} kmscon-service-type @var{config} -Return a service to run -@uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} according to -@var{config}, a @code{<kmscon-configuration>} object, which specifies the -tty to run, among other things. -@end deffn - -@deftp {Data Type} kmscon-configuration -This is the data type representing the configuration of Kmscon, which -implements virtual console log-in. - -@table @asis - -@item @code{virtual-terminal} -The name of the console this Kmscon runs on---e.g., @code{"tty1"}. - -@item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")}) -A gexp denoting the name of the log-in program. The default log-in program -is @command{login} from the Shadow tool suite. - -@item @code{login-arguments} (default: @code{'("-p")}) -A list of arguments to pass to @command{login}. - -@item @code{auto-login} (default: @code{#f}) -When passed a login name, as a string, the specified user will be logged in -automatically without prompting for their login name or password. - -@item @code{hardware-acceleration?} (default: #f) -Whether to use hardware acceleration. - -@item @code{kmscon} (default: @var{kmscon}) -The Kmscon package to use. - -@end table -@end deftp - -@cindex name service cache daemon -@cindex nscd -@deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @ - [#:name-services '()] Return a service that runs the libc name service cache -daemon (nscd) with the given @var{config}---an @code{<nscd-configuration>} -object. @xref{Name Service Switch}, for an example. - -For convenience, the Shepherd service for nscd provides the following -actions: - -@table @code -@item invalidate -@cindex cache invalidation, nscd -@cindex nscd, cache invalidation -This invalidate the given cache. For instance, running: - -@example -herd invalidate nscd hosts -@end example - -@noindent -invalidates the host name lookup cache of nscd. - -@item statistics -Running @command{herd statistics nscd} displays information about nscd usage -and caches. -@end table - -@end deffn - -@defvr {Scheme Variable} %nscd-default-configuration -This is the default @code{<nscd-configuration>} value (see below) used by -@code{nscd-service}. It uses the caches defined by -@var{%nscd-default-caches}; see below. -@end defvr - -@deftp {Data Type} nscd-configuration -This is the data type representing the name service cache daemon (nscd) -configuration. - -@table @asis - -@item @code{name-services} (default: @code{'()}) -List of packages denoting @dfn{name services} that must be visible to the -nscd---e.g., @code{(list @var{nss-mdns})}. - -@item @code{glibc} (default: @var{glibc}) -Package object denoting the GNU C Library providing the @command{nscd} -command. - -@item @code{log-file} (default: @code{"/var/log/nscd.log"}) -Name of the nscd log file. This is where debugging output goes when -@code{debug-level} is strictly positive. - -@item @code{debug-level} (default: @code{0}) -Integer denoting the debugging levels. Higher numbers mean that more -debugging output is logged. - -@item @code{caches} (default: @var{%nscd-default-caches}) -List of @code{<nscd-cache>} objects denoting things to be cached; see below. - -@end table -@end deftp - -@deftp {Data Type} nscd-cache -Data type representing a cache database of nscd and its parameters. - -@table @asis - -@item @code{database} -This is a symbol representing the name of the database to be cached. Valid -values are @code{passwd}, @code{group}, @code{hosts}, and @code{services}, -which designate the corresponding NSS database (@pxref{NSS Basics,,, libc, -The GNU C Library Reference Manual}). - -@item @code{positive-time-to-live} -@itemx @code{negative-time-to-live} (default: @code{20}) -A number representing the number of seconds during which a positive or -negative lookup result remains in cache. - -@item @code{check-files?} (default: @code{#t}) -Whether to check for updates of the files corresponding to @var{database}. - -For instance, when @var{database} is @code{hosts}, setting this flag -instructs nscd to check for updates in @file{/etc/hosts} and to take them -into account. - -@item @code{persistent?} (default: @code{#t}) -Whether the cache should be stored persistently on disk. - -@item @code{shared?} (default: @code{#t}) -Whether the cache should be shared among users. - -@item @code{max-database-size} (default: 32@tie{}MiB) -Maximum size in bytes of the database cache. - -@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert -@c settings, so leave them out. - -@end table -@end deftp - -@defvr {Scheme Variable} %nscd-default-caches -List of @code{<nscd-cache>} objects used by default by -@code{nscd-configuration} (see above). - -It enables persistent and aggressive caching of service and host name -lookups. The latter provides better host name lookup performance, -resilience in the face of unreliable name servers, and also better -privacy---often the result of host name lookups is in local cache, so -external name servers do not even need to be queried. -@end defvr - -@anchor{syslog-configuration-type} -@cindex syslog -@cindex logging -@deftp {Data Type} syslog-configuration -This data type represents the configuration of the syslog daemon. - -@table @asis -@item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")}) -The syslog daemon to use. - -@item @code{config-file} (default: @code{%default-syslog.conf}) -The syslog configuration file to use. - -@end table -@end deftp - -@anchor{syslog-service} -@cindex syslog -@deffn {Scheme Procedure} syslog-service @var{config} -Return a service that runs a syslog daemon according to @var{config}. - -@xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more information -on the configuration file syntax. -@end deffn - -@defvr {Scheme Variable} guix-service-type -This is the type of the service that runs the build daemon, -@command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a -@code{guix-configuration} record as described below. -@end defvr - -@anchor{guix-configuration-type} -@deftp {Data Type} guix-configuration -This data type represents the configuration of the Guix build daemon. -@xref{Invoking guix-daemon}, for more information. - -@table @asis -@item @code{guix} (default: @var{guix}) -The Guix package to use. - -@item @code{build-group} (default: @code{"guixbuild"}) -Name of the group for build user accounts. - -@item @code{build-accounts} (default: @code{10}) -Number of build user accounts to create. - -@item @code{authorize-key?} (default: @code{#t}) -@cindex substitutes, authorization thereof -Whether to authorize the substitute keys listed in -@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}} -(@pxref{Substitutes}). - -@vindex %default-authorized-guix-keys -@item @code{authorized-keys} (default: @var{%default-authorized-guix-keys}) -The list of authorized key files for archive imports, as a list of -string-valued gexps (@pxref{Invoking guix archive}). By default, it -contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitutes}). - -@item @code{use-substitutes?} (default: @code{#t}) -Whether to use substitutes. - -@item @code{substitute-urls} (default: @var{%default-substitute-urls}) -The list of URLs where to look for substitutes by default. - -@item @code{max-silent-time} (default: @code{0}) -@itemx @code{timeout} (default: @code{0}) -The number of seconds of silence and the number of seconds of activity, -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}. - -@item @code{log-file} (default: @code{"/var/log/guix-daemon.log"}) -File where @command{guix-daemon}'s standard output and standard error are -written. - -@item @code{http-proxy} (default: @code{#f}) -The HTTP proxy used for downloading fixed-output derivations and -substitutes. - -@item @code{tmpdir} (default: @code{#f}) -A directory path where the @command{guix-daemon} will perform builds. - -@end table -@end deftp - -@deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}] -Run @var{udev}, which populates the @file{/dev} directory dynamically. udev -rules can be provided as a list of files through the @var{rules} variable. -The procedures @var{udev-rule} and @var{file->udev-rule} from @code{(gnu -services base)} simplify the creation of such rule files. -@end deffn - -@deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}] -Return a udev-rule file named @var{file-name} containing the rules defined -by the @var{contents} literal. - -In the following example, a rule for a USB device is defined to be stored in -the file @file{90-usb-thing.rules}. The rule runs a script upon detecting a -USB device with a given product identifier. - -@example -(define %example-udev-rule - (udev-rule - "90-usb-thing.rules" - (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", " - "ATTR@{product@}==\"Example\", " - "RUN+=\"/path/to/script\""))) -@end example - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. -@end deffn - -Here we show how the default @var{udev-service} can be extended with it. - -@example -(operating-system - ;; @dots{} - (services - (modify-services %desktop-services - (udev-service-type config => - (udev-configuration (inherit config) - (rules (append (udev-configuration-rules config) - (list %example-udev-rule)))))))) -@end example - -@deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}] -Return a udev file named @var{file-name} containing the rules defined within -@var{file}, a file-like object. - -The following example showcases how we can use an existing rule file. - -@example -(use-modules (guix download) ;for url-fetch - (guix packages) ;for origin - ;; @dots{}) - -(define %android-udev-rules - (file->udev-rule - "51-android-udev.rules" - (let ((version "20170910")) - (origin - (method url-fetch) - (uri (string-append "https://raw.githubusercontent.com/M0Rf30/" - "android-udev-rules/" version "/51-android.rules")) - (sha256 - (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003")))))) -@end example -@end deffn - -Additionally, Guix package definitions can be included in @var{rules} in -order to extend the udev rules with the definitions found under their -@file{lib/udev/rules.d} sub-directory. In lieu of the previous -@var{file->udev-rule} example, we could have used the -@var{android-udev-rules} package which exists in Guix in the @code{(gnu -packages android)} module. - -The following example shows how to use the @var{android-udev-rules} package -so that the Android tool @command{adb} can detect devices without root -privileges. It also details how to create the @code{adbusers} group, which -is required for the proper functioning of the rules defined within the -@var{android-udev-rules} package. To create such a group, we must define it -both as part of the @var{supplementary-groups} of our @var{user-account} -declaration, as well as in the @var{groups} field of the -@var{operating-system} record. - -@example -(use-modules (gnu packages android) ;for android-udev-rules - (gnu system shadow) ;for user-group - ;; @dots{}) - -(operating-system - ;; @dots{} - (users (cons (user-acount - ;; @dots{} - (supplementary-groups - '("adbusers" ;for adb - "wheel" "netdev" "audio" "video")) - ;; @dots{}))) - - (groups (cons (user-group (system? #t) (name "adbusers")) - %base-groups)) - - ;; @dots{} - - (services - (modify-services %desktop-services - (udev-service-type - config => - (udev-configuration (inherit config) - (rules (cons android-udev-rules - (udev-configuration-rules config)))))))) -@end example - -@defvr {Scheme Variable} urandom-seed-service-type -Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom} -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 -@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting. It -defaults to @file{/var/lib/random-seed}. -@end defvr - -@cindex mouse -@cindex gpm -@defvr {Scheme Variable} gpm-service-type -This is the type of the service that runs GPM, the @dfn{general-purpose -mouse daemon}, which provides mouse support to the Linux console. GPM -allows users to use the mouse in the console, notably to select, copy, and -paste text. - -The value for services of this type must be a @code{gpm-configuration} (see -below). This service is not part of @var{%base-services}. -@end defvr - -@deftp {Data Type} gpm-configuration -Data type representing the configuration of GPM. - -@table @asis -@item @code{options} (default: @code{%default-gpm-options}) -Command-line options passed to @command{gpm}. The default set of options -instruct @command{gpm} to listen to mouse events on @file{/dev/input/mice}. -@xref{Command Line,,, gpm, gpm manual}, for more information. - -@item @code{gpm} (default: @code{gpm}) -The GPM package to use. - -@end table -@end deftp - -@anchor{guix-publish-service-type} -@deffn {Scheme Variable} guix-publish-service-type -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} in seconds 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"] Return a service that runs the @command{rngd} -program from @var{rng-tools} to add @var{device} to the kernel's entropy -pool. The service will fail if @var{device} does not exist. -@end deffn - -@anchor{pam-limits-service} -@cindex session limits -@cindex ulimit -@cindex priority -@cindex realtime -@cindex jackd -@deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}] - -Return a service that installs a configuration file for the -@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html, -@code{pam_limits} module}. The procedure optionally takes a list of -@code{pam-limits-entry} values, which can be used to specify @code{ulimit} -limits and nice priority limits to user sessions. - -The following limits definition sets two hard and soft limits for all login -sessions of users in the @code{realtime} group: - -@example -(pam-limits-service - (list - (pam-limits-entry "@@realtime" 'both 'rtprio 99) - (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited))) -@end example - -The first entry increases the maximum realtime priority for non-privileged -processes; the second entry lifts any restriction of the maximum address -space that can be locked in memory. These settings are commonly used for -real-time audio systems. -@end deffn - -@node Scheduled Job Execution -@subsection Scheduled Job Execution - -@cindex cron -@cindex mcron -@cindex scheduling jobs -The @code{(gnu services mcron)} module provides an interface to -GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,, -mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional Unix -@command{cron} daemon; the main difference is that it is implemented in -Guile Scheme, which provides a lot of flexibility when specifying the -scheduling of jobs and their actions. - -The example below defines an operating system that runs the -@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files}) and -the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as well as -the @command{mkid} command on behalf of an unprivileged user (@pxref{mkid -invocation,,, idutils, ID Database Utilities}). It uses gexps to introduce -job definitions that are passed to mcron (@pxref{G-Expressions}). - -@lisp -(use-modules (guix) (gnu) (gnu services mcron)) -(use-package-modules base idutils) - -(define updatedb-job - ;; Run 'updatedb' at 3AM every day. Here we write the - ;; job's action as a Scheme procedure. - #~(job '(next-hour '(3)) - (lambda () - (execl (string-append #$findutils "/bin/updatedb") - "updatedb" - "--prunepaths=/tmp /var/tmp /gnu/store")))) - -(define garbage-collector-job - ;; Collect garbage 5 minutes after midnight every day. - ;; The job's action is a shell command. - #~(job "5 0 * * *" ;Vixie cron syntax - "guix gc -F 1G")) - -(define idutils-job - ;; Update the index database as user "charlie" at 12:15PM - ;; and 19:15PM. This runs from the user's home directory. - #~(job '(next-minute-from (next-hour '(12 19)) '(15)) - (string-append #$idutils "/bin/mkid src") - #:user "charlie")) - -(operating-system - ;; @dots{} - (services (cons (service mcron-service-type - (mcron-configuration - (jobs (list garbage-collector-job - updatedb-job - idutils-job)))) - %base-services))) -@end lisp - -@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron}, for -more information on mcron job specifications. Below is the reference of the -mcron service. - -On a running system, you can use the @code{schedule} action of the service -to visualize the mcron jobs that will be executed next: - -@example -# herd schedule mcron -@end example - -@noindent -The example above lists the next five tasks that will be executed, but you -can also specify the number of tasks to display: - -@example -# herd schedule mcron 10 -@end example - -@defvr {Scheme Variable} mcron-service-type -This is the type of the @code{mcron} service, whose value is an -@code{mcron-configuration} object. - -This service type can be the target of a service extension that provides it -additional job specifications (@pxref{Service Composition}). In other -words, it is possible to define services that provide additional mcron jobs -to run. -@end defvr - -@deftp {Data Type} mcron-configuration -Data type representing the configuration of mcron. - -@table @asis -@item @code{mcron} (default: @var{mcron}) -The mcron package to use. - -@item @code{jobs} -This is a list of gexps (@pxref{G-Expressions}), where each gexp corresponds -to an mcron job specification (@pxref{Syntax, mcron job specifications,, -mcron, GNU@tie{}mcron}). -@end table -@end deftp - - -@node Log Rotation -@subsection Log Rotation - -@cindex rottlog -@cindex log rotation -@cindex logging -Log files such as those found in @file{/var/log} tend to grow endlessly, so -it's a good idea to @dfn{rotate} them once in a while---i.e., archive their -contents in separate files, possibly compressed. The @code{(gnu services -admin)} module provides an interface to GNU@tie{}Rot[t]log, a log rotation -tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}). - -The example below defines an operating system that provides log rotation -with the default settings, for commonly encountered log files. - -@lisp -(use-modules (guix) (gnu)) -(use-service-modules admin mcron) -(use-package-modules base idutils) - -(operating-system - ;; @dots{} - (services (cons (service rottlog-service-type) - %base-services))) -@end lisp - -@defvr {Scheme Variable} rottlog-service-type -This is the type of the Rottlog service, whose value is a -@code{rottlog-configuration} object. - -Other services can extend this one with new @code{log-rotation} objects (see -below), thereby augmenting the set of files to be rotated. - -This service type can define mcron jobs (@pxref{Scheduled Job Execution}) to -run the rottlog service. -@end defvr - -@deftp {Data Type} rottlog-configuration -Data type representing the configuration of rottlog. - -@table @asis -@item @code{rottlog} (default: @code{rottlog}) -The Rottlog package to use. - -@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")}) -The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,, -rottlog, GNU Rot[t]log Manual}). - -@item @code{rotations} (default: @code{%default-rotations}) -A list of @code{log-rotation} objects as defined below. - -@item @code{jobs} -This is a list of gexps where each gexp corresponds to an mcron job -specification (@pxref{Scheduled Job Execution}). -@end table -@end deftp - -@deftp {Data Type} log-rotation -Data type representing the rotation of a group of log files. - -Taking an example from the Rottlog manual (@pxref{Period Related File -Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be defined -like this: - -@example -(log-rotation - (frequency 'daily) - (files '("/var/log/apache/*")) - (options '("storedir apache-archives" - "rotate 6" - "notifempty" - "nocompress"))) -@end example - -The list of fields is as follows: - -@table @asis -@item @code{frequency} (default: @code{'weekly}) -The log rotation frequency, a symbol. - -@item @code{files} -The list of files or file glob patterns to rotate. - -@item @code{options} (default: @code{'()}) -The list of rottlog options for this rotation (@pxref{Configuration -parameters,,, rottlog, GNU Rot[t]lg Manual}). - -@item @code{post-rotate} (default: @code{#f}) -Either @code{#f} or a gexp to execute once the rotation has completed. -@end table -@end deftp - -@defvr {Scheme Variable} %default-rotations -Specifies weekly rotation of @var{%rotated-files} and a couple of other -files. -@end defvr - -@defvr {Scheme Variable} %rotated-files -The list of syslog-controlled files to be rotated. By default it is: -@code{'("/var/log/messages" "/var/log/secure")}. -@end defvr - -@node Networking Services -@subsection Networking Services - -The @code{(gnu services networking)} module provides services to configure -the network interface. - -@cindex DHCP, networking service -@defvr {Scheme Variable} dhcp-client-service-type -This is the type of services that run @var{dhcp}, a Dynamic Host -Configuration Protocol (DHCP) client, on all the non-loopback network -interfaces. Its value is the DHCP client package to use, @code{isc-dhcp} by -default. -@end defvr - -@deffn {Scheme Procedure} dhcpd-service-type -This type defines a service that runs a DHCP daemon. To create a service of -this type, you must supply a @code{<dhcpd-configuration>}. For example: - -@example -(service dhcpd-service-type - (dhcpd-configuration - (config-file (local-file "my-dhcpd.conf")) - (interfaces '("enp0s25")))) -@end example -@end deffn - -@deftp {Data Type} dhcpd-configuration -@table @asis -@item @code{package} (default: @code{isc-dhcp}) -The package that provides the DHCP daemon. This package is expected to -provide the daemon at @file{sbin/dhcpd} relative to its output directory. -The default package is the @uref{http://www.isc.org/products/DHCP, ISC's -DHCP server}. -@item @code{config-file} (default: @code{#f}) -The configuration file to use. This is required. It will be passed to -@code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' -object (@pxref{G-Expressions, file-like objects}). See @code{man -dhcpd.conf} for details on the configuration file syntax. -@item @code{version} (default: @code{"4"}) -The DHCP version to use. The ISC DHCP server supports the values ``4'', -``6'', and ``4o6''. These correspond to the @code{dhcpd} program options -@code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for details. -@item @code{run-directory} (default: @code{"/run/dhcpd"}) -The run directory to use. At service activation time, this directory will -be created if it does not exist. -@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"}) -The PID file to use. This corresponds to the @code{-pf} option of -@code{dhcpd}. See @code{man dhcpd} for details. -@item @code{interfaces} (default: @code{'()}) -The names of the network interfaces on which dhcpd should listen for -broadcasts. If this list is not empty, then its elements (which must be -strings) will be appended to the @code{dhcpd} invocation when starting the -daemon. It may not be necessary to explicitly specify any interfaces here; -see @code{man dhcpd} for details. -@end table -@end deftp - -@defvr {Scheme Variable} static-networking-service-type -@c TODO Document <static-networking> data structures. -This is the type for statically-configured network interfaces. -@end defvr - -@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. @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 -@code{static-networking-service-type} with additional network interfaces to -handle. - -For example: - -@example -(static-networking-service "eno1" "192.168.1.82" - #:gateway "192.168.1.2" - #:name-servers '("192.168.1.2")) -@end example -@end deffn - -@cindex wicd -@cindex wireless -@cindex WiFi -@cindex network management -@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] -Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network -management daemon that aims to simplify wired and wireless networking. - -This service adds the @var{wicd} package to the global profile, providing -several commands to interact with the daemon and configure networking: -@command{wicd-client}, a graphical user interface, and the -@command{wicd-cli} and @command{wicd-curses} user interfaces. -@end deffn - -@cindex ModemManager - -@defvr {Scheme Variable} modem-manager-service-type -This is the service type for the -@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager} -service. The value for this service type is a -@code{modem-manager-configuration} record. - -This service is part of @code{%desktop-services} (@pxref{Desktop Services}). -@end defvr - -@deftp {Data Type} modem-manager-configuration -Data type representing the configuration of ModemManager. - -@table @asis -@item @code{modem-manager} (default: @code{modem-manager}) -The ModemManager package to use. - -@end table -@end deftp - -@cindex NetworkManager - -@defvr {Scheme Variable} network-manager-service-type -This is the service type for the -@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager} -service. The value for this service type is a -@code{network-manager-configuration} record. - -This service is part of @code{%desktop-services} (@pxref{Desktop Services}). -@end defvr - -@deftp {Data Type} network-manager-configuration -Data type representing the configuration of NetworkManager. - -@table @asis -@item @code{network-manager} (default: @code{network-manager}) -The NetworkManager package to use. - -@item @code{dns} (default: @code{"default"}) -Processing mode for DNS, which affects how NetworkManager uses the -@code{resolv.conf} configuration file. - -@table @samp -@item default -NetworkManager will update @code{resolv.conf} to reflect the nameservers -provided by currently active connections. - -@item dnsmasq -NetworkManager will run @code{dnsmasq} as a local caching nameserver, using -a "split DNS" configuration if you are connected to a VPN, and then update -@code{resolv.conf} to point to the local nameserver. - -@item none -NetworkManager will not modify @code{resolv.conf}. -@end table - -@item @code{vpn-plugins} (default: @code{'()}) -This is the list of available plugins for virtual private networks (VPNs). -An example of this is the @code{network-manager-openvpn} package, which -allows NetworkManager to manage VPNs @i{via} OpenVPN. - -@end table -@end deftp - -@cindex Connman -@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, disable 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 -supplicant}, an authentication daemon required to authenticate against -encrypted WiFi or ethernet networks. -@end defvr - -@deftp {Data Type} wpa-supplicant-configuration -Data type representing the configuration of WPA Supplicant. - -It takes the following parameters: - -@table @asis -@item @code{wpa-supplicant} (default: @code{wpa-supplicant}) -The WPA Supplicant package to use. - -@item @code{dbus?} (default: @code{#t}) -Whether to listen for requests on D-Bus. - -@item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"}) -Where to store the PID file. - -@item @code{interface} (default: @code{#f}) -If this is set, it must specify the name of a network interface that WPA -supplicant will control. - -@item @code{config-file} (default: @code{#f}) -Optional configuration file to use. - -@item @code{extra-options} (default: @code{'()}) -List of additional command-line arguments to pass to the daemon. -@end table -@end deftp - -@cindex iptables -@defvr {Scheme Variable} iptables-service-type -This is the service type to set up an iptables configuration. iptables is a -packet filtering framework supported by the Linux kernel. This service -supports configuring iptables for both IPv4 and IPv6. A simple example -configuration rejecting all incoming connections except those to the ssh -port 22 is shown below. - -@lisp -(service iptables-service-type - (iptables-configuration - (ipv4-rules (plain-file "iptables.rules" "*filter -:INPUT ACCEPT -:FORWARD ACCEPT -:OUTPUT ACCEPT --A INPUT -p tcp --dport 22 -j ACCEPT --A INPUT -j REJECT --reject-with icmp-port-unreachable -COMMIT -")) - (ipv6-rules (plain-file "ip6tables.rules" "*filter -:INPUT ACCEPT -:FORWARD ACCEPT -:OUTPUT ACCEPT --A INPUT -p tcp --dport 22 -j ACCEPT --A INPUT -j REJECT --reject-with icmp6-port-unreachable -COMMIT -")))) -@end lisp -@end defvr - -@deftp {Data Type} iptables-configuration -The data type representing the configuration of iptables. - -@table @asis -@item @code{iptables} (default: @code{iptables}) -The iptables package that provides @code{iptables-restore} and -@code{ip6tables-restore}. -@item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules}) -The iptables rules to use. It will be passed to @code{iptables-restore}. -This may be any ``file-like'' object (@pxref{G-Expressions, file-like -objects}). -@item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules}) -The ip6tables rules to use. It will be passed to @code{ip6tables-restore}. -This may be any ``file-like'' object (@pxref{G-Expressions, file-like -objects}). -@end table -@end deftp - -@cindex NTP (Network Time Protocol), service -@cindex real time clock -@defvr {Scheme Variable} ntp-service-type -This is the type of the service running the @uref{http://www.ntp.org, -Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep -the system clock synchronized with that of the specified NTP servers. - -The value of this service is an @code{ntpd-configuration} object, as -described below. -@end defvr - -@deftp {Data Type} ntp-configuration -This is the data type for the NTP service configuration. - -@table @asis -@item @code{servers} (default: @code{%ntp-servers}) -This is the list of servers (host names) with which @command{ntpd} will be -synchronized. - -@item @code{allow-large-adjustment?} (default: @code{#f}) -This determines whether @command{ntpd} is allowed to make an initial -adjustment of more than 1,000 seconds. - -@item @code{ntp} (default: @code{ntp}) -The NTP package to use. -@end table -@end deftp - -@defvr {Scheme Variable} %ntp-servers -List of host names used as the default NTP servers. These are servers of -the @uref{https://www.ntppool.org/en/, NTP Pool Project}. -@end defvr - -@cindex OpenNTPD -@deffn {Scheme Procedure} openntpd-service-type -Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as -implemented by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will -keep the system clock synchronized with that of the given servers. - -@example -(service - openntpd-service-type - (openntpd-configuration - (listen-on '("127.0.0.1" "::1")) - (sensor '("udcf0 correction 70000")) - (constraint-from '("www.gnu.org")) - (constraints-from '("https://www.google.com/")) - (allow-large-adjustment? #t))) - -@end example -@end deffn - -@deftp {Data Type} openntpd-configuration -@table @asis -@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")}) -The openntpd executable to use. -@item @code{listen-on} (default: @code{'("127.0.0.1" "::1")}) -A list of local IP addresses or hostnames the ntpd daemon should listen on. -@item @code{query-from} (default: @code{'()}) -A list of local IP address the ntpd daemon should use for outgoing queries. -@item @code{sensor} (default: @code{'()}) -Specify a list of timedelta sensor devices ntpd should use. @code{ntpd} -will listen to each sensor that acutally exists and ignore non-existant -ones. See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} -for more information. -@item @code{server} (default: @var{%ntp-servers}) -Specify a list of IP addresses or hostnames of NTP servers to synchronize -to. -@item @code{servers} (default: @code{'()}) -Specify a list of IP addresses or hostnames of NTP pools to synchronize to. -@item @code{constraint-from} (default: @code{'()}) -@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers -via TLS. This time information is not used for precision but acts as an -authenticated constraint, thereby reducing the impact of unauthenticated NTP -man-in-the-middle attacks. Specify a list of URLs, IP addresses or -hostnames of HTTPS servers to provide a constraint. -@item @code{constraints-from} (default: @code{'()}) -As with constraint from, specify a list of URLs, IP addresses or hostnames -of HTTPS servers to provide a constraint. Should the hostname resolve to -multiple IP addresses, @code{ntpd} will calculate a median constraint from -all of them. -@item @code{allow-large-adjustment?} (default: @code{#f}) -Determines if @code{ntpd} is allowed to make an initial adjustment of more -than 180 seconds. -@end table -@end deftp - -@cindex inetd -@deffn {Scheme variable} inetd-service-type -This service runs the @command{inetd} (@pxref{inetd invocation,,, 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 -@defvr {Scheme Variable} tor-service-type -This is the type for a service that runs the @uref{https://torproject.org, -Tor} anonymous networking daemon. The service is configured using a -@code{<tor-configuration>} record. By default, the Tor daemon runs as the -@code{tor} unprivileged user, which is a member of the @code{tor} group. - -@end defvr - -@deftp {Data Type} tor-configuration -@table @asis -@item @code{tor} (default: @code{tor}) -The package that provides the Tor daemon. This package is expected to -provide the daemon at @file{bin/tor} relative to its output directory. The -default package is the @uref{https://www.torproject.org, Tor Project's} -implementation. - -@item @code{config-file} (default: @code{(plain-file "empty" "")}) -The configuration file to use. It will be appended to a default -configuration file, and the final configuration file will be passed to -@code{tor} via its @code{-f} option. This may be any ``file-like'' object -(@pxref{G-Expressions, file-like objects}). See @code{man tor} for details -on the configuration file syntax. - -@item @code{hidden-services} (default: @code{'()}) -The list of @code{<hidden-service>} records to use. For any hidden service -you include in this list, appropriate configuration to enable the hidden -service will be automatically added to the default configuration file. You -may conveniently create @code{<hidden-service>} records using the -@code{tor-hidden-service} procedure described below. - -@item @code{socks-socket-type} (default: @code{'tcp}) -The default socket type that Tor should use for its SOCKS socket. This must -be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by -default Tor will listen on TCP port 9050 on the loopback interface (i.e., -localhost). If it is @code{'unix}, then Tor will listen on the UNIX domain -socket @file{/var/run/tor/socks-sock}, which will be made writable by -members of the @code{tor} group. - -If you want to customize the SOCKS socket in more detail, leave -@code{socks-socket-type} at its default value of @code{'tcp} and use -@code{config-file} to override the default by providing your own -@code{SocksPort} option. -@end table -@end deftp - -@cindex hidden service -@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping} -Define a new Tor @dfn{hidden service} called @var{name} and implementing -@var{mapping}. @var{mapping} is a list of port/host tuples, such as: - -@example - '((22 "127.0.0.1:22") - (80 "127.0.0.1:8080")) -@end example - -In this example, port 22 of the hidden service is mapped to local port 22, -and port 80 is mapped to local port 8080. - -This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, -where the @file{hostname} file contains the @code{.onion} host name for the -hidden service. - -See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the -Tor project's documentation} for more information. -@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 so -anyone (or just yourself) can download existing files or upload new files. - -@deffn {Scheme Variable} rsync-service-type -This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon, -@command{rsync-configuration} record as in this example: - -@example -(service rsync-service-type) -@end example - -See below for details about @code{rsync-configuration}. -@end deffn - -@deftp {Data Type} rsync-configuration -Data type representing the configuration for @code{rsync-service}. - -@table @asis -@item @code{package} (default: @var{rsync}) -@code{rsync} package to use. - -@item @code{port-number} (default: @code{873}) -TCP port on which @command{rsync} listens for incoming connections. If port -is less than @code{1024} @command{rsync} needs to be started as the -@code{root} user and group. - -@item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"}) -Name of the file where @command{rsync} writes its PID. - -@item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"}) -Name of the file where @command{rsync} writes its lock file. - -@item @code{log-file} (default: @code{"/var/log/rsyncd.log"}) -Name of the file where @command{rsync} writes its log file. - -@item @code{use-chroot?} (default: @var{#t}) -Whether to use chroot for @command{rsync} shared directory. - -@item @code{share-path} (default: @file{/srv/rsync}) -Location of the @command{rsync} shared directory. - -@item @code{share-comment} (default: @code{"Rsync share"}) -Comment of the @command{rsync} shared directory. - -@item @code{read-only?} (default: @var{#f}) -Read-write permissions to shared directory. - -@item @code{timeout} (default: @code{300}) -I/O timeout in seconds. - -@item @code{user} (default: @var{"root"}) -Owner of the @code{rsync} process. - -@item @code{group} (default: @var{"root"}) -Group of the @code{rsync} process. - -@item @code{uid} (default: @var{"rsyncd"}) -User name or user ID that file transfers to and from that module should take -place as when the daemon was run as @code{root}. - -@item @code{gid} (default: @var{"rsyncd"}) -Group name or group ID that will be used when accessing the module. - -@end table -@end deftp - -Furthermore, @code{(gnu services ssh)} provides the following services. -@cindex SSH -@cindex SSH server - -@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ - [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @ -[#:allow-empty-passwords? #f] [#:root-login? #f] @ [#:syslog-output? #t] -[#:x11-forwarding? #t] @ [#:tcp/ip-forwarding? #t] -[#:password-authentication? #t] @ [#:public-key-authentication? #t] -[#:initialize? #t] Run the @command{lshd} program from @var{lsh} to listen -on port @var{port-number}. @var{host-key} must designate a file containing -the host key, and readable only by root. - -When @var{daemonic?} is true, @command{lshd} will detach from the -controlling terminal and log its output to syslogd, unless one sets -@var{syslog-output?} to false. Obviously, it also makes lsh-service depend -on existence of syslogd service. When @var{pid-file?} is true, -@command{lshd} writes its PID to the file called @var{pid-file}. - -When @var{initialize?} is true, automatically create the seed and host key -upon service activation if they do not exist yet. This may take long and -require interaction. - -When @var{initialize?} is false, it is up to the user to initialize the -randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to -create a key pair with the private key stored in file @var{host-key} -(@pxref{lshd basics,,, lsh, LSH Manual}). - -When @var{interfaces} is empty, lshd listens for connections on all the -network interfaces; otherwise, @var{interfaces} must be a list of host names -or addresses. - -@var{allow-empty-passwords?} specifies whether to accept log-ins with empty -passwords, and @var{root-login?} specifies whether to accept log-ins as -root. - -The other options should be self-descriptive. -@end deffn - -@cindex SSH -@cindex SSH server -@deffn {Scheme Variable} openssh-service-type -This is the type for the @uref{http://www.openssh.org, OpenSSH} secure shell -daemon, @command{sshd}. Its value must be an @code{openssh-configuration} -record as in this example: - -@example -(service openssh-service-type - (openssh-configuration - (x11-forwarding? #t) - (permit-root-login 'without-password) - (authorized-keys - `(("alice" ,(local-file "alice.pub")) - ("bob" ,(local-file "bob.pub")))))) -@end example - -See below for details about @code{openssh-configuration}. - -This service can be extended with extra authorized keys, as in this example: - -@example -(service-extension openssh-service-type - (const `(("charlie" - ,(local-file "charlie.pub"))))) -@end example -@end deffn - -@deftp {Data Type} openssh-configuration -This is the configuration record for OpenSSH's @command{sshd}. - -@table @asis -@item @code{pid-file} (default: @code{"/var/run/sshd.pid"}) -Name of the file where @command{sshd} writes its PID. - -@item @code{port-number} (default: @code{22}) -TCP port on which @command{sshd} listens for incoming connections. - -@item @code{permit-root-login} (default: @code{#f}) -This field determines whether and when to allow logins as root. If -@code{#f}, root logins are disallowed; if @code{#t}, they are allowed. If -it's the symbol @code{'without-password}, then root logins are permitted but -not with password-based authentication. - -@item @code{allow-empty-passwords?} (default: @code{#f}) -When true, users with empty passwords may log in. When false, they may not. - -@item @code{password-authentication?} (default: @code{#t}) -When true, users may log in with their password. When false, they have -other authentication methods. - -@item @code{public-key-authentication?} (default: @code{#t}) -When true, users may log in using public key authentication. When false, -users have to use other authentication method. - -Authorized public keys are stored in @file{~/.ssh/authorized_keys}. This is -used only by protocol version 2. - -@item @code{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{allow-agent-forwarding?} (default: @code{#t}) -Whether to allow agent forwarding. - -@item @code{allow-tcp-forwarding?} (default: @code{#t}) -Whether to allow TCP forwarding. - -@item @code{gateway-ports?} (default: @code{#f}) -Whether to allow gateway ports. - -@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 - -@item @code{accepted-environment} (default: @code{'()}) -List of strings describing which environment variables may be exported. - -Each string gets on its own line. See the @code{AcceptEnv} option in -@code{man sshd_config}. - -This example allows ssh-clients to export the @code{COLORTERM} variable. It -is set by terminal emulators, which support colors. You can use it in your -shell's ressource file to enable colors for the prompt and commands if this -variable is set. - -@example -(service openssh-service-type - (openssh-configuration - (accepted-environment '("COLORTERM")))) -@end example - -@item @code{authorized-keys} (default: @code{'()}) -@cindex authorized keys, SSH -@cindex SSH authorized keys -This is the list of authorized keys. Each element of the list is a user -name followed by one or more file-like objects that represent SSH public -keys. For example: - -@example -(openssh-configuration - (authorized-keys - `(("rekado" ,(local-file "rekado.pub")) - ("chris" ,(local-file "chris.pub")) - ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub"))))) -@end example - -@noindent -registers the specified public keys for user accounts @code{rekado}, -@code{chris}, and @code{root}. - -Additional authorized keys can be specified @i{via} -@code{service-extension}. - -Note that this does @emph{not} interfere with the use of -@file{~/.ssh/authorized_keys}. - -@item @code{log-level} (default: @code{'info}) -This is a symbol specifying the logging level: @code{quiet}, @code{fatal}, -@code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man -page for @file{sshd_config} for the full list of level names. - -@item @code{extra-content} (default: @code{""}) -This field can be used to append arbitrary text to the configuration file. -It is especially useful for elaborate configurations that cannot be -expressed otherwise. This configuration, for example, would generally -disable root logins, but permit them from one specific IP address: - -@example -(openssh-configuration - (extra-content "\ -Match Address 192.168.0.1 - PermitRootLogin yes")) -@end example - -@end table -@end deftp - -@deffn {Scheme Procedure} dropbear-service [@var{config}] -Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH -daemon} with the given @var{config}, a @code{<dropbear-configuration>} -object. - -For example, to specify a Dropbear service listening on port 1234, add this -call to the operating system's @code{services} field: - -@example -(dropbear-service (dropbear-configuration - (port-number 1234))) -@end example -@end deffn - -@deftp {Data Type} dropbear-configuration -This data type represents the configuration of a Dropbear SSH daemon. - -@table @asis -@item @code{dropbear} (default: @var{dropbear}) -The Dropbear package to use. - -@item @code{port-number} (default: 22) -The TCP port where the daemon waits for incoming connections. - -@item @code{syslog-output?} (default: @code{#t}) -Whether to enable syslog output. - -@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"}) -File name of the daemon's PID file. - -@item @code{root-login?} (default: @code{#f}) -Whether to allow @code{root} logins. - -@item @code{allow-empty-passwords?} (default: @code{#f}) -Whether to allow empty passwords. - -@item @code{password-authentication?} (default: @code{#t}) -Whether to enable password-based authentication. -@end table -@end deftp - -@defvr {Scheme Variable} %facebook-host-aliases -This variable contains a string for use in @file{/etc/hosts} (@pxref{Host -Names,,, libc, The GNU C Library Reference Manual}). Each line contains a -entry that maps a known server name of the Facebook on-line service---e.g., -@code{www.facebook.com}---to the local host---@code{127.0.0.1} or its IPv6 -equivalent, @code{::1}. - -This variable is typically used in the @code{hosts-file} field of an -@code{operating-system} declaration (@pxref{operating-system Reference, -@file{/etc/hosts}}): - -@example -(use-modules (gnu) (guix)) - -(operating-system - (host-name "mymachine") - ;; ... - (hosts-file - ;; Create a /etc/hosts file with aliases for "localhost" - ;; and "mymachine", as well as for Facebook servers. - (plain-file "hosts" - (string-append (local-host-aliases host-name) - %facebook-host-aliases)))) -@end example - -This mechanism can prevent programs running locally, such as Web browsers, -from accessing Facebook. -@end defvr - -The @code{(gnu services avahi)} provides the following definition. - -@defvr {Scheme Variable} avahi-service-type -This is the service that runs @command{avahi-daemon}, a system-wide -mDNS/DNS-SD responder that allows for service discovery and -``zero-configuration'' host name lookups (see @uref{http://avahi.org/}). -Its value must be a @code{zero-configuration} record---see below. - -This service extends the name service cache daemon (nscd) so that it can -resolve @code{.local} host names using -@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name -Service Switch}, for information on host name resolution. - -Additionally, add the @var{avahi} package to the system profile so that -commands such as @command{avahi-browse} are directly usable. -@end defvr - -@deftp {Data Type} avahi-configuration -Data type representation the configuration for Avahi. - -@table @asis - -@item @code{host-name} (default: @code{#f}) -If different from @code{#f}, use that as the host name to publish for this -machine; otherwise, use the machine's actual host name. - -@item @code{publish?} (default: @code{#t}) -When true, allow host names and services to be published (broadcast) over -the network. - -@item @code{publish-workstation?} (default: @code{#t}) -When true, @command{avahi-daemon} publishes the machine's host name and IP -address via mDNS on the local network. To view the host names published on -your local network, you can run: - -@example -avahi-browse _workstation._tcp -@end example - -@item @code{wide-area?} (default: @code{#f}) -When true, DNS-SD over unicast DNS is enabled. - -@item @code{ipv4?} (default: @code{#t}) -@itemx @code{ipv6?} (default: @code{#t}) -These fields determine whether to use IPv4/IPv6 sockets. - -@item @code{domains-to-browse} (default: @code{'()}) -This is a list of domains to browse. -@end table -@end deftp - -@deffn {Scheme Variable} openvswitch-service-type -This is the type of the @uref{http://www.openvswitch.org, Open vSwitch} -service, whose value should be an @code{openvswitch-configuration} object. -@end deffn - -@deftp {Data Type} openvswitch-configuration -Data type representing the configuration of Open vSwitch, a multilayer -virtual switch which is designed to enable massive network automation -through programmatic extension. - -@table @asis -@item @code{package} (default: @var{openvswitch}) -Package object of the Open vSwitch. - -@end table -@end deftp - -@node X Window -@subsection X Window - -@cindex X11 -@cindex X Window System -@cindex login manager -Support for the X Window graphical display system---specifically Xorg---is -provided by the @code{(gnu services xorg)} module. Note that there is no -@code{xorg-service} procedure. Instead, the X server is started by the -@dfn{login manager}, by default the GNOME Display Manager (GDM). - -@cindex GDM -@cindex GNOME, login manager -GDM of course allows users to log in into window managers and desktop -environments other than GNOME; for those using GNOME, GDM is required for -features such as automatic screen locking. - -@cindex window manager -To use X11, you must install at least one @dfn{window manager}---for example -the @code{windowmaker} or @code{openbox} packages---preferably by adding it -to the @code{packages} field of your operating system definition -(@pxref{operating-system Reference, system-wide packages}). - -@defvr {Scheme Variable} gdm-service-type -This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME -Desktop Manager} (GDM), a program that manages graphical display servers and -handles graphical user logins. Its value must be a @code{gdm-configuration} -(see below.) - -@cindex session types (X11) -@cindex X11 session types -GDM looks for @dfn{session types} described by the @file{.desktop} files in -@file{/run/current-system/profile/share/xsessions} and allows users to -choose a session from the log-in screen. Packages such as @code{gnome}, -@code{xfce}, and @code{i3} provide @file{.desktop} files; adding them to the -system-wide set of packages automatically makes them available at the log-in -screen. - -In addition, @file{~/.xsession} files are honored. When available, -@file{~/.xsession} must be an executable that starts a window manager and/or -other X clients. -@end defvr - -@deftp {Data Type} gdm-configuration -@table @asis -@item @code{auto-login?} (default: @code{#f}) -@itemx @code{default-user} (default: @code{#f}) -When @code{auto-login?} is false, GDM presents a log-in screen. - -When @code{auto-login?} is true, GDM logs in directly as -@code{default-user}. - -@item @code{gnome-shell-assets} (default: ...) -List of GNOME Shell assets needed by GDM: icon theme, fonts, etc. - -@item @code{xorg-configuration} (default: @code{(xorg-configuration)}) -Configuration of the Xorg graphical server. - -@item @code{xsession} (default: @code{(xinitrc)}) -Script to run before starting a X session. - -@item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper}) -File name of the @code{dbus-daemon} executable. - -@item @code{gdm} (default: @code{gdm}) -The GDM package to use. -@end table -@end deftp - -@defvr {Scheme Variable} slim-service-type -This is the type for the SLiM graphical login manager for X11. - -Like GDM, SLiM looks for session types described by @file{.desktop} files -and allows users to choose a session from the log-in screen using @kbd{F1}. -It also honors @file{~/.xsession} files. -@end defvr - -@deftp {Data Type} slim-configuration -Data type representing the configuration of @code{slim-service-type}. - -@table @asis -@item @code{allow-empty-passwords?} (default: @code{#t}) -Whether to allow logins with empty passwords. - -@item @code{auto-login?} (default: @code{#f}) -@itemx @code{default-user} (default: @code{""}) -When @code{auto-login?} is false, SLiM presents a log-in screen. - -When @code{auto-login?} is true, SLiM logs in directly as -@code{default-user}. - -@item @code{theme} (default: @code{%default-slim-theme}) -@itemx @code{theme-name} (default: @code{%default-slim-theme-name}) -The graphical theme to use and its name. - -@item @code{auto-login-session} (default: @code{#f}) -If true, this must be the name of the executable to start as the default -session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}. - -If false, a session described by one of the available @file{.desktop} files -in @code{/run/current-system/profile} and @code{~/.guix-profile} will be -used. - -@quotation Note -You must install at least one window manager in the system profile or in -your user profile. Failing to do that, if @code{auto-login-session} is -false, you will be unable to log in. -@end quotation - -@item @code{xorg-configuration} (default @code{(xorg-configuration)}) -Configuration of the Xorg graphical server. - -@item @code{xauth} (default: @code{xauth}) -The XAuth package to use. - -@item @code{shepherd} (default: @code{shepherd}) -The Shepherd package used when invoking @command{halt} and @command{reboot}. - -@item @code{sessreg} (default: @code{sessreg}) -The sessreg package used in order to register the session. - -@item @code{slim} (default: @code{slim}) -The SLiM package to use. -@end table -@end deftp - -@defvr {Scheme Variable} %default-theme -@defvrx {Scheme Variable} %default-theme-name -The default SLiM theme and its name. -@end defvr - - -@deftp {Data Type} sddm-configuration -This is the data type representing the sddm service configuration. - -@table @asis -@item @code{display-server} (default: "x11") -Select display server to use for the greeter. Valid values are "x11" or -"wayland". - -@item @code{numlock} (default: "on") -Valid values are "on", "off" or "none". - -@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")}) -Command to run when halting. - -@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")}) -Command to run when rebooting. - -@item @code{theme} (default "maldives") -Theme to use. Default themes provided by SDDM are "elarun" or "maldives". - -@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes") -Directory to look for themes. - -@item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces") -Directory to look for faces. - -@item @code{default-path} (default "/run/current-system/profile/bin") -Default PATH to use. - -@item @code{minimum-uid} (default 1000) -Minimum UID to display in SDDM. - -@item @code{maximum-uid} (default 2000) -Maximum UID to display in SDDM - -@item @code{remember-last-user?} (default #t) -Remember last user. - -@item @code{remember-last-session?} (default #t) -Remember last session. - -@item @code{hide-users} (default "") -Usernames to hide from SDDM greeter. - -@item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")}) -Users with shells listed will be hidden from the SDDM greeter. - -@item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")}) -Script to run before starting a wayland session. - -@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions") -Directory to look for desktop files starting wayland sessions. - -@item @code{xorg-configuration} (default @code{(xorg-configuration)}) -Configuration of the Xorg graphical server. - -@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")}) -Path to xauth. - -@item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")}) -Path to Xephyr. - -@item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")}) -Script to run after starting xorg-server. - -@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")}) -Script to run before stopping xorg-server. - -@item @code{xsession-command} (default: @code{xinitrc}) -Script to run before starting a X session. - -@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions") -Directory to look for desktop files starting X sessions. - -@item @code{minimum-vt} (default: 7) -Minimum VT to use. - -@item @code{auto-login-user} (default "") -User to use for auto-login. - -@item @code{auto-login-session} (default "") -Desktop file to use for auto-login. - -@item @code{relogin?} (default #f) -Relogin after logout. - -@end table -@end deftp - -@cindex login manager -@cindex X11 login -@deffn {Scheme Procedure} sddm-service config -Return a service that spawns the SDDM graphical login manager for config of -type @code{<sddm-configuration>}. - -@example - (sddm-service (sddm-configuration - (auto-login-user "Alice") - (auto-login-session "xfce.desktop"))) -@end example -@end deffn - -@cindex Xorg, configuration -@deftp {Data Type} xorg-configuration -This data type represents the configuration of the Xorg graphical display -server. Note that there is not Xorg service; instead, the X server is -started by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, the -configuration of these display managers aggregates an -@code{xorg-configuration} record. - -@table @asis -@item @code{modules} (default: @code{%default-xorg-modules}) -This is a list of @dfn{module packages} loaded by the Xorg server---e.g., -@code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on. - -@item @code{fonts} (default: @code{%default-xorg-fonts}) -This is a list of font directories to add to the server's @dfn{font path}. - -@item @code{drivers} (default: @code{'()}) -This must be either the empty list, in which case Xorg chooses a graphics -driver automatically, or a list of driver names that will be tried in this -order---e.g., @code{("modesetting" "vesa")}. - -@item @code{resolutions} (default: @code{'()}) -When @code{resolutions} is the empty list, Xorg chooses an appropriate -screen resolution. Otherwise, it must be a list of resolutions---e.g., -@code{((1024 768) (640 480))}. - -@cindex keyboard layout, for Xorg -@cindex keymap, for Xorg -@item @code{keyboard-layout} (default: @code{#f}) -If this is @code{#f}, Xorg uses the default keyboard layout---usually US -English (``qwerty'') for a 105-key PC keyboard. - -Otherwise this must be a @code{keyboard-layout} object specifying the -keyboard layout in use when Xorg is running. @xref{Keyboard Layout}, for -more information on how to specify the keyboard layout. - -@item @code{extra-config} (default: @code{'()}) -This is a list of strings or objects appended to the configuration file. It -is used to pass extra text to be added verbatim to the configuration file. - -@item @code{server} (default: @code{xorg-server}) -This is the package providing the Xorg server. - -@item @code{server-arguments} (default: @code{%default-xorg-server-arguments}) -This is the list of command-line arguments to pass to the X server. The -default is @code{-nolisten tcp}. -@end table -@end deftp - -@deffn {Scheme Procedure} set-xorg-configuration @var{config} @ - [@var{login-manager-service-type}] Tell the log-in manager (of type -@var{login-manager-service-type}) to use @var{config}, an -<xorg-configuration> record. - -Since the Xorg configuration is embedded in the log-in manager's -configuration---e.g., @code{gdm-configuration}---this procedure provides a -shorthand to set the Xorg configuration. -@end deffn - -@deffn {Scheme Procedure} xorg-start-command [@var{config}] -Return a @code{startx} script in which the modules, fonts, etc. specified in -@var{config}, are available. The result should be used in place of -@code{startx}. - -Usually the X server is started by a login manager. -@end deffn - - -@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}] -Add @var{package}, a package for a screen locker or screen saver whose -command is @var{program}, to the set of setuid programs and add a PAM entry -for it. For example: - -@lisp -(screen-locker-service xlockmore "xlock") -@end lisp - -makes the good ol' XlockMore usable. -@end deffn - - -@node Printing Services -@subsection Printing Services - -@cindex printer support with CUPS -The @code{(gnu services cups)} module provides a Guix service definition for -the CUPS printing service. To add printer support to a Guix system, add a -@code{cups-service} to the operating system definition: - -@deffn {Scheme Variable} cups-service-type -The service type for the CUPS print server. Its value should be a valid -CUPS configuration (see below). To use the default settings, simply write: -@example -(service cups-service-type) -@end example -@end deffn - -The CUPS configuration controls the basic things about your CUPS -installation: what interfaces it listens on, what to do if a print job -fails, how much logging to do, and so on. To actually add a printer, you -have to visit the @url{http://localhost:631} URL, or use a tool such as -GNOME's printer configuration services. By default, configuring a CUPS -service will generate a self-signed certificate if needed, for secure -connections to the print server. - -Suppose you want to enable the Web interface of CUPS and also add support -for Epson printers @i{via} the @code{escpr} package and for HP printers -@i{via} the @code{hplip-minimal} package. You can do that directly, like -this (you need to use the @code{(gnu packages cups)} module): - -@example -(service cups-service-type - (cups-configuration - (web-interface? #t) - (extensions - (list cups-filters escpr hplip-minimal)))) -@end example - -Note: If you wish to use the Qt5 based GUI which comes with the hplip -package then it is suggested that you install the @code{hplip} package, -either in your OS configuration file or as your user. - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{foo} parameter should be specified as a list of strings. There is -also a way to specify the configuration as a string, if you have an old -@code{cupsd.conf} file that you want to port over from some other system; -see the end for more details. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services cups). 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 CUPS updates. - - -Available @code{cups-configuration} fields are: - -@deftypevr {@code{cups-configuration} parameter} package cups -The CUPS package. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} package-list extensions -Drivers and other extensions to the CUPS package. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration -Configuration of where to write logs, what directories to use for print -spools, and related privileged configuration parameters. - -Available @code{files-configuration} fields are: - -@deftypevr {@code{files-configuration} parameter} log-location access-log -Defines the access log filename. Specifying a blank filename disables -access log generation. The value @code{stderr} causes log entries to be -sent to the standard error file when the scheduler is running in the -foreground, or to the system log daemon when run in the background. The -value @code{syslog} causes log entries to be sent to the system log daemon. -The server name may be included in filenames using the string @code{%s}, as -in @code{/var/log/cups/%s-access_log}. - -Defaults to @samp{"/var/log/cups/access_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name cache-dir -Where CUPS should cache data. - -Defaults to @samp{"/var/cache/cups"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string config-file-perm -Specifies the permissions for all configuration files that the scheduler -writes. - -Note that the permissions for the printers.conf file are currently masked to -only allow access from the scheduler user (typically root). This is done -because printer device URIs sometimes contain sensitive authentication -information that should not be generally known on the system. There is no -way to disable this security feature. - -Defaults to @samp{"0640"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} log-location error-log -Defines the error log filename. Specifying a blank filename disables access -log generation. The value @code{stderr} causes log entries to be sent to -the standard error file when the scheduler is running in the foreground, or -to the system log daemon when run in the background. The value -@code{syslog} causes log entries to be sent to the system log daemon. The -server name may be included in filenames using the string @code{%s}, as in -@code{/var/log/cups/%s-error_log}. - -Defaults to @samp{"/var/log/cups/error_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string fatal-errors -Specifies which errors are fatal, causing the scheduler to exit. The kind -strings are: - -@table @code -@item none -No errors are fatal. - -@item all -All of the errors below are fatal. - -@item browse -Browsing initialization errors are fatal, for example failed connections to -the DNS-SD daemon. - -@item config -Configuration file syntax errors are fatal. - -@item listen -Listen or Port errors are fatal, except for IPv6 failures on the loopback or -@code{any} addresses. - -@item log -Log file creation or write errors are fatal. - -@item permissions -Bad startup file permissions are fatal, for example shared TLS certificate -and key files with world-read permissions. -@end table - -Defaults to @samp{"all -browse"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} boolean file-device? -Specifies whether the file pseudo-device can be used for new printer -queues. The URI @uref{file:///dev/null} is always allowed. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string group -Specifies the group name or ID that will be used when executing external -programs. - -Defaults to @samp{"lp"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string log-file-perm -Specifies the permissions for all log files that the scheduler writes. - -Defaults to @samp{"0644"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} log-location page-log -Defines the page log filename. Specifying a blank filename disables access -log generation. The value @code{stderr} causes log entries to be sent to -the standard error file when the scheduler is running in the foreground, or -to the system log daemon when run in the background. The value -@code{syslog} causes log entries to be sent to the system log daemon. The -server name may be included in filenames using the string @code{%s}, as in -@code{/var/log/cups/%s-page_log}. - -Defaults to @samp{"/var/log/cups/page_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string remote-root -Specifies the username that is associated with unauthenticated accesses by -clients claiming to be the root user. The default is @code{remroot}. - -Defaults to @samp{"remroot"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name request-root -Specifies the directory that contains print jobs and other HTTP request -data. - -Defaults to @samp{"/var/spool/cups"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} sandboxing sandboxing -Specifies the level of security sandboxing that is applied to print filters, -backends, and other child processes of the scheduler; either @code{relaxed} -or @code{strict}. This directive is currently only used/supported on macOS. - -Defaults to @samp{strict}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name server-keychain -Specifies the location of TLS certificates and private keys. CUPS will look -for public and private keys in this directory: a @code{.crt} files for -PEM-encoded certificates and corresponding @code{.key} files for PEM-encoded -private keys. - -Defaults to @samp{"/etc/cups/ssl"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name server-root -Specifies the directory containing the server configuration files. - -Defaults to @samp{"/etc/cups"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} boolean sync-on-close? -Specifies whether the scheduler calls fsync(2) after writing configuration -or state files. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group -Specifies the group(s) to use for @code{@@SYSTEM} group authentication. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name temp-dir -Specifies the directory where temporary files are stored. - -Defaults to @samp{"/var/spool/cups/tmp"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string user -Specifies the user name or ID that is used when running external programs. - -Defaults to @samp{"lp"}. -@end deftypevr -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level -Specifies the logging level for the AccessLog file. The @code{config} level -logs when printers and classes are added, deleted, or modified and when -configuration files are accessed or updated. The @code{actions} level logs -when print jobs are submitted, held, released, modified, or canceled, and -any of the conditions for @code{config}. The @code{all} level logs all -requests. - -Defaults to @samp{actions}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs? -Specifies whether to purge job history data automatically when it is no -longer required for quotas. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols -Specifies which protocols to use for local printer sharing. - -Defaults to @samp{dnssd}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if? -Specifies whether the CUPS web interface is advertised. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean browsing? -Specifies whether shared printers are advertised. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string classification -Specifies the security classification of the server. Any valid banner name -can be used, including "classified", "confidential", "secret", "topsecret", -and "unclassified", or the banner can be omitted to disable secure printing -functions. - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean classify-override? -Specifies whether users may override the classification (cover page) of -individual print jobs using the @code{job-sheets} option. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type -Specifies the default type of authentication to use. - -Defaults to @samp{Basic}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption -Specifies whether encryption will be used for authenticated requests. - -Defaults to @samp{Required}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-language -Specifies the default language to use for text and web content. - -Defaults to @samp{"en"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-paper-size -Specifies the default paper size for new print queues. @samp{"Auto"} uses a -locale-specific default, while @samp{"None"} specifies there is no default -paper size. Specific size names are typically @samp{"Letter"} or -@samp{"A4"}. - -Defaults to @samp{"Auto"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-policy -Specifies the default access policy to use. - -Defaults to @samp{"default"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean default-shared? -Specifies whether local printers are shared by default. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval -Specifies the delay for updating of configuration and state files, in -seconds. A value of 0 causes the update to happen as soon as possible, -typically within a few milliseconds. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} error-policy error-policy -Specifies what to do when an error occurs. Possible values are -@code{abort-job}, which will discard the failed print job; @code{retry-job}, -which will retry the job at a later time; @code{retry-this-job}, which -retries the failed job immediately; and @code{stop-printer}, which stops the -printer. - -Defaults to @samp{stop-printer}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit -Specifies the maximum cost of filters that are run concurrently, which can -be used to minimize disk, memory, and CPU resource problems. A limit of 0 -disables filter limiting. An average print to a non-PostScript printer -needs a filter limit of about 200. A PostScript printer needs about half -that (100). Setting the limit below these thresholds will effectively limit -the scheduler to printing a single job at any time. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice -Specifies the scheduling priority of filters that are run to print a job. -The nice value ranges from 0, the highest priority, to 19, the lowest -priority. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups -Specifies whether to do reverse lookups on connecting clients. The -@code{double} setting causes @code{cupsd} to verify that the hostname -resolved from the address matches one of the addresses returned for that -hostname. Double lookups also prevent clients with unregistered addresses -from connecting to your server. Only set this option to @code{#t} or -@code{double} if absolutely required. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay -Specifies the number of seconds to wait before killing the filters and -backend associated with a canceled or held job. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval -Specifies the interval between retries of jobs in seconds. This is -typically used for fax queues but can also be used with normal print queues -whose error policy is @code{retry-job} or @code{retry-current-job}. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit -Specifies the number of retries that are done for jobs. This is typically -used for fax queues but can also be used with normal print queues whose -error policy is @code{retry-job} or @code{retry-current-job}. - -Defaults to @samp{5}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean keep-alive? -Specifies whether to support HTTP keep-alive connections. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout -Specifies how long an idle client connection remains open, in seconds. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body -Specifies the maximum size of print files, IPP requests, and HTML form -data. A limit of 0 disables the limit check. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen -Listens on the specified interfaces for connections. Valid values are of -the form @var{address}:@var{port}, where @var{address} is either an IPv6 -address enclosed in brackets, an IPv4 address, or @code{*} to indicate all -addresses. Values can also be file names of local UNIX domain sockets. The -Listen directive is similar to the Port directive but allows you to restrict -access to specific interfaces or networks. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log -Specifies the number of pending connections that will be allowed. This -normally only affects very busy servers that have reached the MaxClients -limit, but can also be triggered by large numbers of simultaneous -connections. When the limit is reached, the operating system will refuse -additional connections until the scheduler can accept the pending ones. - -Defaults to @samp{128}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls -Specifies a set of additional access controls. - -Available @code{location-access-controls} fields are: - -@deftypevr {@code{location-access-controls} parameter} file-name path -Specifies the URI path to which the access control applies. -@end deftypevr - -@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls -Access controls for all access to this path, in the same format as the -@code{access-controls} of @code{operation-access-control}. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls -Access controls for method-specific access to this path. - -Defaults to @samp{()}. - -Available @code{method-access-controls} fields are: - -@deftypevr {@code{method-access-controls} parameter} boolean reverse? -If @code{#t}, apply access controls to all methods except the listed -methods. Otherwise apply to only the listed methods. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{method-access-controls} parameter} method-list methods -Methods to which this access control applies. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{method-access-controls} parameter} access-control-list access-controls -Access control directives, as a list of strings. Each string should be one -directive, such as "Order allow,deny". - -Defaults to @samp{()}. -@end deftypevr -@end deftypevr -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history -Specifies the number of debugging messages that are retained for logging if -an error occurs in a print job. Debug messages are logged regardless of the -LogLevel setting. - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} log-level log-level -Specifies the level of logging for the ErrorLog file. The value @code{none} -stops all logging while @code{debug2} logs everything. - -Defaults to @samp{info}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format -Specifies the format of the date and time in the log files. The value -@code{standard} logs whole seconds while @code{usecs} logs microseconds. - -Defaults to @samp{standard}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients -Specifies the maximum number of simultaneous clients that are allowed by the -scheduler. - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host -Specifies the maximum number of simultaneous clients that are allowed from a -single address. - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies -Specifies the maximum number of copies that a user can print of each job. - -Defaults to @samp{9999}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time -Specifies the maximum time a job may remain in the @code{indefinite} hold -state before it is canceled. A value of 0 disables cancellation of held -jobs. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs -Specifies the maximum number of simultaneous jobs that are allowed. Set to -0 to allow an unlimited number of jobs. - -Defaults to @samp{500}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer -Specifies the maximum number of simultaneous jobs that are allowed per -printer. A value of 0 allows up to MaxJobs jobs per printer. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user -Specifies the maximum number of simultaneous jobs that are allowed per -user. A value of 0 allows up to MaxJobs jobs per user. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time -Specifies the maximum time a job may take to print before it is canceled, in -seconds. Set to 0 to disable cancellation of "stuck" jobs. - -Defaults to @samp{10800}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size -Specifies the maximum size of the log files before they are rotated, in -bytes. The value 0 disables log rotation. - -Defaults to @samp{1048576}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout -Specifies the maximum amount of time to allow between files in a multiple -file print job, in seconds. - -Defaults to @samp{300}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string page-log-format -Specifies the format of PageLog lines. Sequences beginning with percent -(@samp{%}) characters are replaced with the corresponding information, while -all other characters are copied literally. The following percent sequences -are recognized: - -@table @samp -@item %% -insert a single percent character - -@item %@{name@} -insert the value of the specified IPP attribute - -@item %C -insert the number of copies for the current page - -@item %P -insert the current page number - -@item %T -insert the current date and time in common log format - -@item %j -insert the job ID - -@item %p -insert the printer name - -@item %u -insert the username -@end table - -A value of the empty string disables page logging. The string @code{%p %u -%j %T %P %C %@{job-billing@} %@{job-originating-host-name@} %@{job-name@} -%@{media@} %@{sides@}} creates a page log with the standard items. - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables -Passes the specified environment variable(s) to child processes; a list of -strings. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies -Specifies named access control policies. - -Available @code{policy-configuration} fields are: - -@deftypevr {@code{policy-configuration} parameter} string name -Name of the policy. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string job-private-access -Specifies an access list for a job's private values. @code{@@ACL} maps to -the printer's requesting-user-name-allowed or requesting-user-name-denied -values. @code{@@OWNER} maps to the job's owner. @code{@@SYSTEM} maps to -the groups listed for the @code{system-group} field of the -@code{files-config} configuration, which is reified into the -@code{cups-files.conf(5)} file. Other possible elements of the access list -include specific user names, and @code{@@@var{group}} to indicate members of -a specific group. The access list may also be simply @code{all} or -@code{default}. - -Defaults to @samp{"@@OWNER @@SYSTEM"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string job-private-values -Specifies the list of job values to make private, or @code{all}, -@code{default}, or @code{none}. - -Defaults to @samp{"job-name job-originating-host-name -job-originating-user-name phone"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string subscription-private-access -Specifies an access list for a subscription's private values. @code{@@ACL} -maps to the printer's requesting-user-name-allowed or -requesting-user-name-denied values. @code{@@OWNER} maps to the job's -owner. @code{@@SYSTEM} maps to the groups listed for the -@code{system-group} field of the @code{files-config} configuration, which is -reified into the @code{cups-files.conf(5)} file. Other possible elements of -the access list include specific user names, and @code{@@@var{group}} to -indicate members of a specific group. The access list may also be simply -@code{all} or @code{default}. - -Defaults to @samp{"@@OWNER @@SYSTEM"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string subscription-private-values -Specifies the list of job values to make private, or @code{all}, -@code{default}, or @code{none}. - -Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri -notify-subscriber-user-name notify-user-data"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls -Access control by IPP operation. - -Defaults to @samp{()}. -@end deftypevr -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files -Specifies whether job files (documents) are preserved after a job is -printed. If a numeric value is specified, job files are preserved for the -indicated number of seconds after printing. Otherwise a boolean value -applies indefinitely. - -Defaults to @samp{86400}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history -Specifies whether the job history is preserved after a job is printed. If a -numeric value is specified, the job history is preserved for the indicated -number of seconds after printing. If @code{#t}, the job history is -preserved until the MaxJobs limit is reached. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout -Specifies the amount of time to wait for job completion before restarting -the scheduler. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string rip-cache -Specifies the maximum amount of memory to use when converting documents into -bitmaps for a printer. - -Defaults to @samp{"128m"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string server-admin -Specifies the email address of the server administrator. - -Defaults to @samp{"root@@localhost.localdomain"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias -The ServerAlias directive is used for HTTP Host header validation when -clients connect to the scheduler from external interfaces. Using the -special name @code{*} can expose your system to known browser-based DNS -rebinding attacks, even when accessing sites through a firewall. If the -auto-discovery of alternate names does not work, we recommend listing each -alternate name with a ServerAlias directive instead of using @code{*}. - -Defaults to @samp{*}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string server-name -Specifies the fully-qualified host name of the server. - -Defaults to @samp{"localhost"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens -Specifies what information is included in the Server header of HTTP -responses. @code{None} disables the Server header. @code{ProductOnly} -reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor} -reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}. -@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is the -output of the @code{uname} command. @code{Full} reports @code{CUPS 2.0.0 -(@var{uname}) IPP/2.0}. - -Defaults to @samp{Minimal}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string set-env -Set the specified environment variable to be passed to child processes. - -Defaults to @samp{"variable value"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen -Listens on the specified interfaces for encrypted connections. Valid values -are of the form @var{address}:@var{port}, where @var{address} is either an -IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to indicate -all addresses. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options -Sets encryption options. By default, CUPS only supports encryption using -TLS v1.0 or higher using known secure cipher suites. The @code{AllowRC4} -option enables the 128-bit RC4 cipher suites, which are required for some -older clients that do not implement newer ones. The @code{AllowSSL3} option -enables SSL v3.0, which is required for some older clients that do not -support TLS v1.0. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance? -Specifies whether the scheduler requires clients to strictly adhere to the -IPP specifications. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout -Specifies the HTTP request timeout, in seconds. - -Defaults to @samp{300}. - -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean web-interface? -Specifies whether the web interface is enabled. - -Defaults to @samp{#f}. -@end deftypevr - -At this point you're probably thinking ``oh dear, Guix manual, I like you -but you can stop already with the configuration options''. Indeed. -However, one more point: it could be that you have an existing -@code{cupsd.conf} that you want to use. In that case, you can pass an -@code{opaque-cups-configuration} as the configuration of a -@code{cups-service-type}. - -Available @code{opaque-cups-configuration} fields are: - -@deftypevr {@code{opaque-cups-configuration} parameter} package cups -The CUPS package. -@end deftypevr - -@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf -The contents of the @code{cupsd.conf}, as a string. -@end deftypevr - -@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf -The contents of the @code{cups-files.conf} file, as a string. -@end deftypevr - -For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in -strings of the same name, you could instantiate a CUPS service like this: - -@example -(service cups-service-type - (opaque-cups-configuration - (cupsd.conf cupsd.conf) - (cups-files.conf cups-files.conf))) -@end example - - -@node Desktop Services -@subsection Desktop Services - -The @code{(gnu services desktop)} module provides services that are 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, 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 -environment and networking: - -@defvr {Scheme Variable} %desktop-services -This is a list of services that builds upon @var{%base-services} and adds or -adjusts services for a typical ``desktop'' setup. - -In particular, it adds a graphical login manager (@pxref{X Window, -@code{gdm-service-type}}), screen lockers, a network management tool -(@pxref{Networking Services, @code{network-manager-service-type}}), energy -and color management services, the @code{elogind} login and seat manager, -the Polkit privilege service, the GeoClue location service, the -AccountsService daemon that allows authorized users change system passwords, -an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the -name service switch service configured to be able to use @code{nss-mdns} -(@pxref{Name Service Switch, mDNS}). -@end defvr - -The @var{%desktop-services} variable can be used as the @code{services} -field of an @code{operating-system} declaration (@pxref{operating-system -Reference, @code{services}}). - -Additionally, the @code{gnome-desktop-service-type}, -@code{xfce-desktop-service}, @code{mate-desktop-service-type} and -@code{enlightenment-desktop-service-type} procedures can add GNOME, Xfce, -MATE and/or Enlightenment to a system. To ``add GNOME'' means that -system-level services like the backlight adjustment helpers and the power -management utilities are added to the system, extending @code{polkit} and -@code{dbus} appropriately, allowing GNOME to operate with elevated -privileges on a limited number of special-purpose system interfaces. -Additionally, adding a service made by @code{gnome-desktop-service-type} -adds the GNOME metapackage to the system profile. Likewise, adding the Xfce -service not only adds the @code{xfce} metapackage to the system profile, but -it 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 of type -@code{mate-desktop-service-type} adds the MATE metapackage to the system -profile. ``Adding Enlightenment'' means that @code{dbus} is extended -appropriately, and several of Enlightenment's binaries are set as setuid, -allowing Enlightenment's screen locker and other functionality to work as -expetected. - -The desktop environments in Guix use the Xorg display server by default. If -you'd like to use the newer display server protocol called Wayland, you need -to use the @code{sddm-service} instead of GDM as the graphical login -manager. You should then select the ``GNOME (Wayland)'' session in SDDM. -Alternatively you can also try starting GNOME on Wayland manually from a TTY -with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session -gnome-session``. Currently only GNOME has support for Wayland. - -@defvr {Scheme Variable} gnome-desktop-service-type -This is the type of the service that adds the @uref{https://www.gnome.org, -GNOME} desktop environment. Its value is a -@code{gnome-desktop-configuration} object (see below.) - -This service adds the @code{gnome} package to the system profile, and -extends polkit with the actions from @code{gnome-settings-daemon}. -@end defvr - -@deftp {Data Type} gnome-desktop-configuration -Configuration record for the GNOME desktop environment. - -@table @asis -@item @code{gnome} (default @code{gnome}) -The GNOME package to use. -@end table -@end deftp - -@defvr {Scheme Variable} xfce-desktop-service-type -This is the type of a service to run the @uref{Xfce, https://xfce.org/} -desktop environment. Its value is an @code{xfce-desktop-configuration} -object (see below.) - -This service that adds the @code{xfce} package to the system profile, and -extends polkit with the ability for @code{thunar} to manipulate the file -system as root from within a user session, after the user has authenticated -with the administrator's password. -@end defvr - -@deftp {Data Type} xfce-desktop-configuration -Configuration record for the Xfce desktop environment. - -@table @asis -@item @code{xfce} (default @code{xfce}) -The Xfce package to use. -@end table -@end deftp - -@deffn {Scheme Variable} mate-desktop-service-type -This is the type of the service that runs the -@uref{https://mate-desktop.org/, MATE desktop environment}. Its value is a -@code{mate-desktop-configuration} object (see below.) - -This service adds the @code{mate} package to the system profile, and extends -polkit with the actions from @code{mate-settings-daemon}. -@end deffn - -@deftp {Data Type} mate-desktop-configuration -Configuration record for the MATE desktop environment. - -@table @asis -@item @code{mate} (default @code{mate}) -The MATE package to use. -@end table -@end deftp - -@deffn {Scheme Variable} enlightenment-desktop-service-type -Return a service that adds the @code{enlightenment} package to the system -profile, and extends dbus with actions from @code{efl}. -@end deffn - -@deftp {Data Type} enlightenment-desktop-service-configuration -@table @asis -@item @code{enlightenment} (default @code{enlightenment}) -The enlightenment package to use. -@end table -@end deftp - -Because the GNOME, Xfce and MATE desktop services pull in so many packages, -the default @code{%desktop-services} variable doesn't include any of them by -default. To add GNOME, Xfce or MATE, just @code{cons} them onto -@code{%desktop-services} in the @code{services} field of your -@code{operating-system}: - -@example -(use-modules (gnu)) -(use-service-modules desktop) -(operating-system - ... - ;; cons* adds items to the list given as its last argument. - (services (cons* (service gnome-desktop-service-type) - (service xfce-desktop-service) - %desktop-services)) - ...) -@end example - -These desktop environments will then be available as options in the -graphical login window. - -The actual service definitions included in @code{%desktop-services} and -provided by @code{(gnu services dbus)} and @code{(gnu services desktop)} are -described below. - -@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] -Return a service that runs the ``system bus'', using @var{dbus}, with -support for @var{services}. - -@uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication -facility. Its system bus is used to allow system services to communicate -and to be notified of system-wide events. - -@var{services} must be a list of packages that provide an -@file{etc/dbus-1/system.d} directory containing additional D-Bus -configuration and policy files. For example, to allow avahi-daemon to use -the system bus, @var{services} must be equal to @code{(list avahi)}. -@end deffn - -@deffn {Scheme Procedure} elogind-service [#:config @var{config}] -Return a service that runs the @code{elogind} login and seat management -daemon. @uref{https://github.com/elogind/elogind, Elogind} exposes a D-Bus -interface that can be used to know which users are logged in, know what kind -of sessions they have open, suspend the system, inhibit system suspend, -reboot the system, and other tasks. - -Elogind handles most system-level power events for a computer, for example -suspending the system when a lid is closed, or shutting it down when the -power button is pressed. - -The @var{config} keyword argument specifies the configuration for elogind, -and should be the result of an @code{(elogind-configuration (@var{parameter} -@var{value})...)} invocation. Available parameters and their default values -are: - -@table @code -@item kill-user-processes? -@code{#f} -@item kill-only-users -@code{()} -@item kill-exclude-users -@code{("root")} -@item inhibit-delay-max-seconds -@code{5} -@item handle-power-key -@code{poweroff} -@item handle-suspend-key -@code{suspend} -@item handle-hibernate-key -@code{hibernate} -@item handle-lid-switch -@code{suspend} -@item handle-lid-switch-docked -@code{ignore} -@item power-key-ignore-inhibited? -@code{#f} -@item suspend-key-ignore-inhibited? -@code{#f} -@item hibernate-key-ignore-inhibited? -@code{#f} -@item lid-switch-ignore-inhibited? -@code{#t} -@item holdoff-timeout-seconds -@code{30} -@item idle-action -@code{ignore} -@item idle-action-seconds -@code{(* 30 60)} -@item runtime-directory-size-percent -@code{10} -@item runtime-directory-size -@code{#f} -@item remove-ipc? -@code{#t} -@item suspend-state -@code{("mem" "standby" "freeze")} -@item suspend-mode -@code{()} -@item hibernate-state -@code{("disk")} -@item hibernate-mode -@code{("platform" "shutdown")} -@item hybrid-sleep-state -@code{("disk")} -@item hybrid-sleep-mode -@code{("suspend" "platform" "shutdown")} -@end table -@end deffn - -@deffn {Scheme Procedure} accountsservice-service @ - [#:accountsservice @var{accountsservice}] Return a service that runs -AccountsService, a system service that can list available accounts, change -their passwords, and so on. AccountsService integrates with PolicyKit to -enable unprivileged users to acquire the capability to modify their system -configuration. -@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the -accountsservice web site} for more information. - -The @var{accountsservice} keyword argument is the @code{accountsservice} -package to expose as a service. -@end deffn - -@deffn {Scheme Procedure} polkit-service @ - [#:polkit @var{polkit}] Return a service that runs the -@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege -management service}, which allows system administrators to grant access to -privileged operations in a structured way. By querying the Polkit service, -a privileged system component can know when it should grant additional -capabilities to ordinary users. For example, an ordinary user can be -granted the capability to suspend the system if the user is logged in -locally. -@end deffn - -@defvr {Scheme Variable} upower-service-type -Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, -a system-wide monitor for power consumption and battery levels, with the -given configuration settings. - -It implements the @code{org.freedesktop.UPower} D-Bus interface, and is -notably used by GNOME. -@end defvr - -@deftp {Data Type} upower-configuration -Data type representation the configuration for UPower. - -@table @asis - -@item @code{upower} (default: @var{upower}) -Package to use for @code{upower}. - -@item @code{watts-up-pro?} (default: @code{#f}) -Enable the Watts Up Pro device. - -@item @code{poll-batteries?} (default: @code{#t}) -Enable polling the kernel for battery level changes. - -@item @code{ignore-lid?} (default: @code{#f}) -Ignore the lid state, this can be useful if it's incorrect on a device. - -@item @code{use-percentage-for-policy?} (default: @code{#f}) -Whether battery percentage based policy should be used. The default is to -use the time left, change to @code{#t} to use the percentage. - -@item @code{percentage-low} (default: @code{10}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which the battery is considered low. - -@item @code{percentage-critical} (default: @code{3}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which the battery is considered critical. - -@item @code{percentage-action} (default: @code{2}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which action will be taken. - -@item @code{time-low} (default: @code{1200}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which the battery is considered low. - -@item @code{time-critical} (default: @code{300}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which the battery is considered critical. - -@item @code{time-action} (default: @code{120}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which action will be taken. - -@item @code{critical-power-action} (default: @code{'hybrid-sleep}) -The action taken when @code{percentage-action} or @code{time-action} is -reached (depending on the configuration of -@code{use-percentage-for-policy?}). - -Possible values are: - -@itemize @bullet -@item -@code{'power-off} - -@item -@code{'hibernate} - -@item -@code{'hybrid-sleep}. -@end itemize - -@end table -@end deftp - -@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}] -Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, -UDisks}, a @dfn{disk management} daemon that provides user interfaces with -notifications and ways to mount/unmount disks. Programs that talk to UDisks -include the @command{udisksctl} command, part of UDisks, and GNOME Disks. -@end deffn - -@deffn {Scheme Procedure} colord-service [#:colord @var{colord}] -Return a service that runs @command{colord}, a system service with a D-Bus -interface to manage the color profiles of input and output devices such as -screens and scanners. It is notably used by the GNOME Color Manager -graphical tool. See @uref{http://www.freedesktop.org/software/colord/, the -colord web site} for more information. -@end deffn - -@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] -Return a configuration allowing an application to access GeoClue location -data. @var{name} is the Desktop ID of the application, without the -@code{.desktop} part. If @var{allowed?} is true, the application will have -access to location information by default. The boolean @var{system?} value -indicates whether an application is a system component or not. Finally -@var{users} is a list of UIDs of all users for which this application is -allowed location info access. An empty users list means that all users are -allowed. -@end deffn - -@defvr {Scheme Variable} %standard-geoclue-applications -The standard list of well-known GeoClue application configurations, granting -authority to the GNOME date-and-time utility to ask for the current location -in order to set the time zone, and allowing the IceCat and Epiphany web -browsers to request location information. IceCat and Epiphany both query -the user before allowing a web page to know the user's location. -@end defvr - -@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @ - [#:whitelist '()] @ [#:wifi-geolocation-url -"https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @ -[#:submit-data? #f] [#:wifi-submission-url -"https://location.services.mozilla.com/v1/submit?key=geoclue"] @ -[#:submission-nick "geoclue"] @ [#:applications -%standard-geoclue-applications] Return a service that runs the GeoClue -location service. This service provides a D-Bus interface to allow -applications to request access to a user's physical location, and optionally -to add information to online location databases. See -@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue web -site} for more information. -@end deffn - -@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @ - [@w{#:auto-enable? #f}] Return a service that runs the @command{bluetoothd} -daemon, which manages all the Bluetooth devices and provides a number of -D-Bus interfaces. When AUTO-ENABLE? is true, the bluetooth controller is -powered automatically at boot, which can be useful when using a bluetooth -keyboard or mouse. - -Users need to be in the @code{lp} group to access the D-Bus service. -@end deffn - -@node Sound Services -@subsection Sound Services - -@cindex sound support -@cindex ALSA -@cindex PulseAudio, sound support - -The @code{(gnu services sound)} module provides a service to configure the -Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the -preferred ALSA output driver. - -@deffn {Scheme Variable} alsa-service-type -This is the type for the @uref{https://alsa-project.org/, Advanced Linux -Sound Architecture} (ALSA) system, which generates the -@file{/etc/asound.conf} configuration file. The value for this type is a -@command{alsa-configuration} record as in this example: - -@example -(service alsa-service-type) -@end example - -See below for details about @code{alsa-configuration}. -@end deffn - -@deftp {Data Type} alsa-configuration -Data type representing the configuration for @code{alsa-service}. - -@table @asis -@item @code{alsa-plugins} (default: @var{alsa-plugins}) -@code{alsa-plugins} package to use. - -@item @code{pulseaudio?} (default: @var{#t}) -Whether ALSA applications should transparently be made to use the -@uref{http://www.pulseaudio.org/, PulseAudio} sound server. - -Using PulseAudio allows you to run several sound-producing applications at -the same time and to individual control them @i{via} @command{pavucontrol}, -among other things. - -@item @code{extra-options} (default: @var{""}) -String to append to the @file{/etc/asound.conf} file. - -@end table -@end deftp - -Individual users who want to override the system configuration of ALSA can -do it with the @file{~/.asoundrc} file: - -@example -# In guix, we have to specify the absolute path for plugins. -pcm_type.jack @{ - lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so" -@} - -# Routing ALSA to jack: -# <http://jackaudio.org/faq/routing_alsa.html>. -pcm.rawjack @{ - type jack - playback_ports @{ - 0 system:playback_1 - 1 system:playback_2 - @} - - capture_ports @{ - 0 system:capture_1 - 1 system:capture_2 - @} -@} - -pcm.!default @{ - type plug - slave @{ - pcm "rawjack" - @} -@} -@end example - -See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the -details. - - -@node Database Services -@subsection Database Services - -@cindex database -@cindex SQL -The @code{(gnu services databases)} module provides the following services. - -@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @ - [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @ [#:port -5432] [#:locale ``en_US.utf8''] [#:extension-packages '()] Return a service -that runs @var{postgresql}, the PostgreSQL database server. - -The PostgreSQL daemon loads its runtime configuration from -@var{config-file}, creates a database cluster with @var{locale} as the -default locale, stored in @var{data-directory}. It then listens on -@var{port}. - -@cindex postgresql extension-packages -Additional extensions are loaded from packages listed in -@var{extension-packages}. Extensions are available at runtime. For -instance, to create a geographic database using the @code{postgis} -extension, a user can configure the postgresql-service as in this example: - -@cindex postgis -@example -(use-package-modules databases geo) - -(operating-system - ... - ;; postgresql is required to run `psql' but postgis is not required for - ;; proper operation. - (packages (cons* postgresql %base-packages)) - (services - (cons* - (postgresql-service #:extension-packages (list postgis)) - %base-services))) -@end example - -Then the extension becomes visible and you can initialise an empty -geographic database in this way: - -@example -psql -U postgres -> create database postgistest; -> \connect postgistest; -> create extension postgis; -> create extension postgis_topology; -@end example - -There is no need to add this field for contrib extensions such as hstore or -dblink as they are already loadable by postgresql. This field is only -required to add extensions provided by other packages. -@end deffn - -@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)] -Return a service that runs @command{mysqld}, the MySQL or MariaDB database -server. - -The optional @var{config} argument specifies the configuration for -@command{mysqld}, which should be a @code{<mysql-configuration>} object. -@end deffn - -@deftp {Data Type} mysql-configuration -Data type representing the configuration of @var{mysql-service}. - -@table @asis -@item @code{mysql} (default: @var{mariadb}) -Package object of the MySQL database server, can be either @var{mariadb} or -@var{mysql}. - -For MySQL, a temporary root password will be displayed at activation time. -For MariaDB, the root password is empty. - -@item @code{port} (default: @code{3306}) -TCP port on which the database server listens for incoming connections. -@end table -@end deftp - -@defvr {Scheme Variable} memcached-service-type -This is the service type for the @uref{https://memcached.org/, Memcached} -service, which provides a distributed in memory cache. The value for the -service type is a @code{memcached-configuration} object. -@end defvr - -@example -(service memcached-service-type) -@end example - -@deftp {Data Type} memcached-configuration -Data type representing the configuration of memcached. - -@table @asis -@item @code{memcached} (default: @code{memcached}) -The Memcached package to use. - -@item @code{interfaces} (default: @code{'("0.0.0.0")}) -Network interfaces on which to listen. - -@item @code{tcp-port} (default: @code{11211}) -Port on which to accept connections on, - -@item @code{udp-port} (default: @code{11211}) -Port on which to accept UDP connections on, a value of 0 will disable -listening on a UDP socket. - -@item @code{additional-options} (default: @code{'()}) -Additional command line options to pass to @code{memcached}. -@end table -@end deftp - -@defvr {Scheme Variable} mongodb-service-type -This is the service type for @uref{https://www.mongodb.com/, MongoDB}. The -value for the service type is a @code{mongodb-configuration} object. -@end defvr - -@example -(service mongodb-service-type) -@end example - -@deftp {Data Type} mongodb-configuration -Data type representing the configuration of mongodb. - -@table @asis -@item @code{mongodb} (default: @code{mongodb}) -The MongoDB package to use. - -@item @code{config-file} (default: @code{%default-mongodb-configuration-file}) -The configuration file for MongoDB. - -@item @code{data-directory} (default: @code{"/var/lib/mongodb"}) -This value is used to create the directory, so that it exists and is owned -by the mongodb user. It should match the data-directory which MongoDB is -configured to use through the configuration file. -@end table -@end deftp - -@defvr {Scheme Variable} redis-service-type -This is the service type for the @uref{https://redis.io/, Redis} key/value -store, whose value is a @code{redis-configuration} object. -@end defvr - -@deftp {Data Type} redis-configuration -Data type representing the configuration of redis. - -@table @asis -@item @code{redis} (default: @code{redis}) -The Redis package to use. - -@item @code{bind} (default: @code{"127.0.0.1"}) -Network interface on which to listen. - -@item @code{port} (default: @code{6379}) -Port on which to accept connections on, a value of 0 will disable listening -on a TCP socket. - -@item @code{working-directory} (default: @code{"/var/lib/redis"}) -Directory in which to store the database and related files. -@end table -@end deftp - -@node Mail Services -@subsection Mail Services - -@cindex mail -@cindex email -The @code{(gnu services mail)} module provides Guix service definitions for -email services: IMAP, POP3, and LMTP servers, as well as mail transport -agents (MTAs). Lots of acronyms! These services are detailed in the -subsections below. - -@subsubheading Dovecot Service - -@deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)] -Return a service that runs the Dovecot IMAP/POP3/LMTP mail server. -@end deffn - -By default, Dovecot does not need much configuration; the default -configuration object created by @code{(dovecot-configuration)} will suffice -if your mail is delivered to @code{~/Maildir}. A self-signed certificate -will be generated for TLS-protected connections, though Dovecot will also -listen on cleartext ports by default. There are a number of options, -though, which mail administrators might need to change, and as is the case -with other services, Guix allows the system administrator to specify these -parameters via a uniform Scheme interface. - -For example, to specify that mail is located at @code{maildir~/.mail}, one -would instantiate the Dovecot service like this: - -@example -(dovecot-service #:config - (dovecot-configuration - (mail-location "maildir:~/.mail"))) -@end example - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{foo} parameter should be specified as a list of strings. There is -also a way to specify the configuration as a string, if you have an old -@code{dovecot.conf} file that you want to port over from some other system; -see the end for more details. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services mail). 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 dovecot updates. - -Available @code{dovecot-configuration} fields are: - -@deftypevr {@code{dovecot-configuration} parameter} package dovecot -The dovecot package. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen -A list of IPs or hosts where to listen for connections. @samp{*} listens on -all IPv4 interfaces, @samp{::} listens on all IPv6 interfaces. If you want -to specify non-default ports or anything more complex, customize the address -and port fields of the @samp{inet-listener} of the specific services you are -interested in. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols -List of protocols we want to serve. Available protocols include -@samp{imap}, @samp{pop3}, and @samp{lmtp}. - -Available @code{protocol-configuration} fields are: - -@deftypevr {@code{protocol-configuration} parameter} string name -The name of the protocol. -@end deftypevr - -@deftypevr {@code{protocol-configuration} parameter} string auth-socket-path -UNIX socket path to the master authentication server to find users. This is -used by imap (for shared users) and lda. It defaults to -@samp{"/var/run/dovecot/auth-userdb"}. -@end deftypevr - -@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins -Space separated list of plugins to load. -@end deftypevr - -@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections -Maximum number of IMAP connections allowed for a user from each IP address. -NOTE: The username is compared case-sensitively. Defaults to @samp{10}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services -List of services to enable. Available services include @samp{imap}, -@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and -@samp{lmtp}. - -Available @code{service-configuration} fields are: - -@deftypevr {@code{service-configuration} parameter} string kind -The service kind. Valid values include @code{director}, @code{imap-login}, -@code{pop3-login}, @code{lmtp}, @code{imap}, @code{pop3}, @code{auth}, -@code{auth-worker}, @code{dict}, @code{tcpwrap}, @code{quota-warning}, or -anything else. -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners -Listeners for the service. A listener is either a -@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or -an @code{inet-listener-configuration}. Defaults to @samp{()}. - -Available @code{unix-listener-configuration} fields are: - -@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 -The access mode for the socket. Defaults to @samp{"0600"}. -@end deftypevr - -@deftypevr {@code{unix-listener-configuration} parameter} string user -The user to own the socket. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{unix-listener-configuration} parameter} string group -The group to own the socket. Defaults to @samp{""}. -@end deftypevr - - -Available @code{fifo-listener-configuration} fields are: - -@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 -The access mode for the socket. Defaults to @samp{"0600"}. -@end deftypevr - -@deftypevr {@code{fifo-listener-configuration} parameter} string user -The user to own the socket. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{fifo-listener-configuration} parameter} string group -The group to own the socket. Defaults to @samp{""}. -@end deftypevr - - -Available @code{inet-listener-configuration} fields are: - -@deftypevr {@code{inet-listener-configuration} parameter} string protocol -The protocol to listen for. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} string address -The address on which to listen, or empty for all addresses. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port -The port on which to listen. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl? -Whether to use SSL for this service; @samp{yes}, @samp{no}, or -@samp{required}. Defaults to @samp{#t}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit -Maximum number of simultaneous client connections per process. Once this -number of connections is received, the next incoming connection will prompt -Dovecot to spawn another process. If set to 0, @code{default-client-limit} -is used instead. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer service-count -Number of connections to handle before starting a new process. Typically -the only useful values are 0 (unlimited) or 1. 1 is more secure, but 0 is -faster. <doc/wiki/LoginProcess.txt>. Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit -Maximum number of processes that can exist for this service. If set to 0, -@code{default-process-limit} is used instead. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail -Number of processes to always keep waiting for more connections. Defaults -to @samp{0}. -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit -If you set @samp{service-count 0}, you probably need to grow this. Defaults -to @samp{256000000}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict -Dict configuration, as created by the @code{dict-configuration} constructor. - -Available @code{dict-configuration} fields are: - -@deftypevr {@code{dict-configuration} parameter} free-form-fields entries -A list of key-value pairs that this dict should hold. Defaults to -@samp{()}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs -A list of passdb configurations, each one created by the -@code{passdb-configuration} constructor. - -Available @code{passdb-configuration} fields are: - -@deftypevr {@code{passdb-configuration} parameter} string driver -The driver that the passdb should use. Valid values include @samp{pam}, -@samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}. Defaults -to @samp{"pam"}. -@end deftypevr - -@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 - -@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs -List of userdb configurations, each one created by the -@code{userdb-configuration} constructor. - -Available @code{userdb-configuration} fields are: - -@deftypevr {@code{userdb-configuration} parameter} string driver -The driver that the userdb should use. Valid values include @samp{passwd} -and @samp{static}. Defaults to @samp{"passwd"}. -@end deftypevr - -@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 -Override fields from passwd. Defaults to @samp{()}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration -Plug-in configuration, created by the @code{plugin-configuration} -constructor. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces -List of namespaces. Each item in the list is created by the -@code{namespace-configuration} constructor. - -Available @code{namespace-configuration} fields are: - -@deftypevr {@code{namespace-configuration} parameter} string name -Name for this namespace. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string type -Namespace type: @samp{private}, @samp{shared} or @samp{public}. Defaults to -@samp{"private"}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string separator -Hierarchy separator to use. You should use the same separator for all -namespaces or some clients get confused. @samp{/} is usually a good one. -The default however depends on the underlying mail storage format. Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string prefix -Prefix required to access this namespace. This needs to be different for -all namespaces. For example @samp{Public/}. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string location -Physical location of the mailbox. This is in the same format as -mail_location, which is also the default for it. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean inbox? -There can be only one INBOX, and this setting defines which namespace has -it. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean hidden? -If namespace is hidden, it's not advertised to clients via NAMESPACE -extension. You'll most likely also want to set @samp{list? #f}. This is -mostly useful when converting from another server with different namespaces -which you want to deprecate but still keep working. For example you can -create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/} and -@samp{mail/}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean list? -Show the mailboxes under this namespace with the LIST command. This makes -the namespace visible for clients that do not support the NAMESPACE -extension. The special @code{children} value lists child mailboxes, but -hides the namespace prefix. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions? -Namespace handles its own subscriptions. If set to @code{#f}, the parent -namespace handles them. The empty prefix should always have this as -@code{#t}). Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes -List of predefined mailboxes in this namespace. Defaults to @samp{()}. - -Available @code{mailbox-configuration} fields are: - -@deftypevr {@code{mailbox-configuration} parameter} string name -Name for this mailbox. -@end deftypevr - -@deftypevr {@code{mailbox-configuration} parameter} string auto -@samp{create} will automatically create this mailbox. @samp{subscribe} will -both create and subscribe to the mailbox. Defaults to @samp{"no"}. -@end deftypevr - -@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use -List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154. Valid -values are @code{\All}, @code{\Archive}, @code{\Drafts}, @code{\Flagged}, -@code{\Junk}, @code{\Sent}, and @code{\Trash}. Defaults to @samp{()}. -@end deftypevr - -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir -Base directory where to store runtime data. Defaults to -@samp{"/var/run/dovecot/"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string login-greeting -Greeting message for clients. Defaults to @samp{"Dovecot ready."}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks -List of trusted network ranges. Connections from these IPs are allowed to -override their IP addresses and ports (for logging and for authentication -checks). @samp{disable-plaintext-auth} is also ignored for these networks. -Typically you would specify your IMAP proxy servers here. Defaults to -@samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets -List of login access check sockets (e.g.@: tcpwrap). Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle? -Show more verbose process titles (in ps). Currently shows user name and IP -address. Useful for seeing who is actually using the IMAP processes (e.g.@: -shared mailboxes or if the same uid is used for multiple accounts). -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients? -Should all processes be killed when Dovecot master process shuts down. -Setting this to @code{#f} means that Dovecot can be upgraded without forcing -existing client connections to close (although that could also be a problem -if the upgrade is e.g.@: due to a security fix). Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count -If non-zero, run mail commands via this many connections to doveadm server, -instead of running them directly in the same process. Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path -UNIX socket or host:port used for connecting to doveadm server. Defaults to -@samp{"doveadm-server"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment -List of environment variables that are preserved on Dovecot startup and -passed down to all of its child processes. You can also give key=value -pairs to always set specific settings. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth? -Disable LOGIN command and all other plaintext authentications unless SSL/TLS -is used (LOGINDISABLED capability). Note that if the remote IP matches the -local IP (i.e.@: you're connecting from the same computer), the connection -is considered secure and plaintext authentication is allowed. See also -ssl=required setting. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size -Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled. -Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set for -caching to be used. Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl -Time to live for cached data. After TTL expires the cached record is no -longer used, *except* if the main database lookup returns internal failure. -We also try to handle password changes automatically: If user's previous -authentication was successful, but this one wasn't, the cache isn't used. -For now this works only with plaintext authentication. Defaults to @samp{"1 -hour"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl -TTL for negative hits (user not found, password mismatch). 0 disables -caching them completely. Defaults to @samp{"1 hour"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms -List of realms for SASL authentication mechanisms that need them. You can -leave it empty if you don't want to support multiple realms. Many clients -simply use the first one listed here, so keep the default realm first. -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm -Default realm/domain to use if none was specified. This is used for both -SASL realms and appending @@domain to username in plaintext logins. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars -List of allowed characters in username. If the user-given username contains -a character not listed in here, the login automatically fails. This is just -an extra check to make sure user can't exploit any potential quote escaping -vulnerabilities with SQL/LDAP databases. If you want to allow all -characters, set this value to empty. Defaults to -@samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation -Username character translations before it's looked up from databases. The -value contains series of from -> to characters. For example @samp{#@@/@@} -means that @samp{#} and @samp{/} characters are translated to @samp{@@}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-username-format -Username formatting before it's looked up from databases. You can use the -standard variables here, e.g.@: %Lu would lowercase the username, %n would -drop away the domain if it was given, or @samp{%n-AT-%d} would change the -@samp{@@} into @samp{-AT-}. This translation is done after -@samp{auth-username-translation} changes. Defaults to @samp{"%Lu"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator -If you want to allow master users to log in by specifying the master -username within the normal username string (i.e.@: not using SASL -mechanism's support for it), you can specify the separator character here. -The format is then <username><separator><master username>. UW-IMAP uses -@samp{*} as the separator, so that could be a good choice. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username -Username to use for users logging in with ANONYMOUS SASL mechanism. -Defaults to @samp{"anonymous"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count -Maximum number of dovecot-auth worker processes. They're used to execute -blocking passdb and userdb queries (e.g.@: MySQL and PAM). They're -automatically created and destroyed as needed. Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname -Host name to use in GSSAPI principal names. The default is to use the name -returned by gethostname(). Use @samp{$ALL} (with quotes) to allow all -keytab entries. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab -Kerberos keytab to use for the GSSAPI mechanism. Will use the system -default (usually @file{/etc/krb5.keytab}) if not specified. You may need to -change the auth service to run as root to be able to read this file. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind? -Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon and -@samp{ntlm-auth} helper. <doc/wiki/Authentication/Mechanisms/Winbind.txt>. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path -Path for Samba's @samp{ntlm-auth} helper binary. Defaults to -@samp{"/usr/bin/ntlm_auth"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay -Time to delay before replying to failed authentications. Defaults to -@samp{"2 secs"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert? -Require a valid SSL client certificate or the authentication fails. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert? -Take the username from client's SSL certificate, using -@code{X509_NAME_get_text_by_NID()} which returns the subject's DN's -CommonName. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms -List of wanted authentication mechanisms. Supported mechanisms are: -@samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5}, @samp{ntlm}, -@samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi}, @samp{otp}, -@samp{skey}, and @samp{gss-spnego}. NOTE: See also -@samp{disable-plaintext-auth} setting. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers -List of IPs or hostnames to all director servers, including ourself. Ports -can be specified as ip:port. The default port is the same as what director -service's @samp{inet-listener} is using. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers -List of IPs or hostnames to all backend mail servers. Ranges are allowed -too, like 10.0.0.10-10.0.0.30. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string director-user-expire -How long to redirect users to a specific server after it no longer has any -connections. Defaults to @samp{"15 min"}. -@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 are shared -within domain. Defaults to @samp{"%Lu"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string log-path -Log file to use for error messages. @samp{syslog} logs to syslog, -@samp{/dev/stderr} logs to stderr. Defaults to @samp{"syslog"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string info-log-path -Log file to use for informational messages. Defaults to @samp{log-path}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path -Log file to use for debug messages. Defaults to @samp{info-log-path}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility -Syslog facility to use if you're logging to syslog. Usually if you don't -want to use @samp{mail}, you'll use local0..local7. Also other standard -facilities are supported. Defaults to @samp{"mail"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose? -Log unsuccessful authentication attempts and the reasons why they failed. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords? -In case of password mismatches, log the attempted password. Valid values -are no, plain and sha1. sha1 can be useful for detecting brute force -password attempts vs. user simply trying the same password over and over -again. You can also truncate the value to n chars by appending ":n" (e.g.@: -sha1:6). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug? -Even more verbose logging for debugging purposes. Shows for example SQL -queries. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords? -In case of password mismatches, log the passwords and used scheme so the -problem can be debugged. Enabling this also enables @samp{auth-debug}. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug? -Enable mail process debugging. This can help you figure out why Dovecot -isn't finding your mails. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl? -Show protocol level SSL errors. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string log-timestamp -Prefix for each line written to log file. % codes are in strftime(3) -format. Defaults to @samp{"\"%b %d %H:%M:%S \""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements -List of elements we want to log. The elements which have a non-empty -variable value are joined together to form a comma-separated string. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string login-log-format -Login log format. %s contains @samp{login-log-format-elements} string, %$ -contains the data we want to log. Defaults to @samp{"%$: %s"}. -@end deftypevr - -@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)<%@{pid@}><%@{session@}>: \""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format -Format to use for logging mail deliveries. You can use variables: -@table @code -@item %$ -Delivery status message (e.g.@: @samp{saved to INBOX}) -@item %m -Message-ID -@item %s -Subject -@item %f -From address -@item %p -Physical size -@item %w -Virtual size. -@end table -Defaults to @samp{"msgid=%m: %$"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-location -Location for users' mailboxes. The default is empty, which means that -Dovecot tries to find the mailboxes automatically. This won't work if the -user doesn't yet have any mail, so you should explicitly tell Dovecot the -full location. - -If you're using mbox, giving a path to the INBOX file (e.g.@: /var/mail/%u) -isn't enough. You'll also need to tell Dovecot where the other mailboxes -are kept. This is called the "root mail directory", and it must be the -first path given in the @samp{mail-location} setting. - -There are a few special variables you can use, eg.: - -@table @samp -@item %u -username -@item %n -user part in user@@domain, same as %u if there's no domain -@item %d -domain part in user@@domain, empty if there's no domain -@item %h -home director -@end table - -See doc/wiki/Variables.txt for full list. Some examples: -@table @samp -@item maildir:~/Maildir -@item mbox:~/mail:INBOX=/var/mail/%u -@item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/% -@end table -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-uid -System user and group used to access mails. If you use multiple, userdb can -override these by returning uid or gid fields. You can use either numbers -or names. <doc/wiki/UserIds.txt>. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-gid - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group -Group to enable temporarily for privileged operations. Currently this is -used only with INBOX when either its initial creation or dotlocking fails. -Typically this is set to "mail" to give access to /var/mail. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups -Grant access to these supplementary groups for mail processes. Typically -these are used to set up access to shared mailboxes. Note that it may be -dangerous to set these if users can create symlinks (e.g.@: if "mail" group -is set here, ln -s /var/mail ~/mail/var could allow a user to delete others' -mailboxes, or ln -s /secret/shared/box ~/mail/mybox would allow reading -it). Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access? -Allow full file system access to clients. There's no access checks other -than what the operating system does for the active UID/GID. It works with -both maildir and mboxes, allowing you to prefix mailboxes names with e.g.@: -/path/ or ~user/. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable? -Don't use mmap() at all. This is required if you store indexes to shared -file systems (NFS or clustered file system). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl? -Rely on @samp{O_EXCL} to work when creating dotlock files. NFS supports -@samp{O_EXCL} since version 3, so this should be safe to use nowadays by -default. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync -When to use fsync() or fdatasync() calls: -@table @code -@item optimized -Whenever necessary to avoid losing important data -@item always -Useful with e.g.@: NFS when write()s are delayed -@item never -Never use it (best performance, but crashes can lose data). -@end table -Defaults to @samp{"optimized"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage? -Mail storage exists in NFS. Set this to yes to make Dovecot flush NFS -caches whenever needed. If you're using only a single mail server this -isn't needed. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index? -Mail index files also exist in NFS. Setting this to yes requires -@samp{mmap-disable? #t} and @samp{fsync-disable? #f}. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string lock-method -Locking method for index files. Alternatives are fcntl, flock and dotlock. -Dotlocking uses some tricks which may create more disk I/O than other -locking methods. NFS users: flock doesn't work, remember to change -@samp{mmap-disable}. Defaults to @samp{"fcntl"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir -Directory in which LDA/LMTP temporarily stores incoming mails >128 kB. -Defaults to @samp{"/tmp"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid -Valid UID range for users. This is mostly to make sure that users can't log -in as daemons or other system users. Note that denying root logins is -hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid} -is set to 0. Defaults to @samp{500}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid -Valid GID range for users. Users having non-valid GID as primary group ID -aren't allowed to log in. If user belongs to supplementary groups with -non-valid GIDs, those groups are not set. Defaults to @samp{1}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length -Maximum allowed length for mail keyword name. It's only forced when trying -to create new keywords. Defaults to @samp{50}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs -List of directories under which chrooting is allowed for mail processes -(i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar too). This -setting doesn't affect @samp{login-chroot} @samp{mail-chroot} or auth chroot -settings. If this setting is empty, "/./" in home dirs are ignored. -WARNING: Never add directories here which local users can modify, that may -lead to root exploit. Usually this should be done only if you don't allow -shell access for users. <doc/wiki/Chrooting.txt>. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-chroot -Default chroot directory for mail processes. This can be overridden for -specific users in user database by giving /./ in user's home directory -(e.g.@: /home/./user chroots into /home). Note that usually there is no -real need to do chrooting, Dovecot doesn't allow users to access files -outside their mail directory anyway. If your home directories are prefixed -with the chroot directory, append "/."@: to @samp{mail-chroot}. -<doc/wiki/Chrooting.txt>. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path -UNIX socket path to master authentication server to find users. This is -used by imap (for shared users) and lda. Defaults to -@samp{"/var/run/dovecot/auth-userdb"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir -Directory where to look up mail plugins. Defaults to -@samp{"/usr/lib/dovecot"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins -List of plugins to load for all services. Plugins specific to IMAP, LDA, -etc.@: are added to this list in their own .conf files. Defaults to -@samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count -The minimum number of mails in a mailbox before updates are done to cache -file. This allows optimizing Dovecot's behavior to do less disk writes at -the cost of more disk reads. Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval -When IDLE command is running, mailbox is checked once in a while to see if -there are any new mails or other changes. This setting defines the minimum -time to wait between those checks. Dovecot can also use dnotify, inotify -and kqueue to find out immediately when changes occur. Defaults to -@samp{"30 secs"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf? -Save mails with CR+LF instead of plain LF. This makes sending those mails -take less CPU, especially with sendfile() syscall with Linux and FreeBSD. -But it also creates a bit more disk I/O which may just make it slower. Also -note that if other software reads the mboxes/maildirs, they may handle the -extra CRs wrong and cause problems. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs? -By default LIST command returns all entries in maildir beginning with a -dot. Enabling this option makes Dovecot return only entries which are -directories. This is done by stat()ing each entry, so it causes more disk -I/O. (For systems setting struct @samp{dirent->d_type} this check is free -and it's done always regardless of this setting). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks? -When copying a message, do it with hard links whenever possible. This makes -the performance much better, and it's unlikely to have any side effects. -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs? -Assume Dovecot is the only MUA accessing Maildir: Scan cur/ directory only -when its mtime changes unexpectedly or when we can't find the mail -otherwise. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks -Which locking methods to use for locking mbox. There are four available: - -@table @code -@item dotlock -Create <mailbox>.lock file. This is the oldest and most NFS-safe solution. -If you want to use /var/mail/ like directory, the users will need write -access to that directory. -@item dotlock-try -Same as dotlock, but if it fails because of permissions or because there -isn't enough disk space, just skip it. -@item fcntl -Use this if possible. Works with NFS too if lockd is used. -@item flock -May not exist in all systems. Doesn't work with NFS. -@item lockf -May not exist in all systems. Doesn't work with NFS. -@end table - -You can use multiple locking methods; if you do the order they're declared -in is important to avoid deadlocks if other MTAs/MUAs are using multiple -locking methods as well. Some operating systems don't allow using some of -them simultaneously. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout -Maximum time to wait for lock (all of them) before aborting. Defaults to -@samp{"5 mins"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout -If dotlock exists but the mailbox isn't modified in any way, override the -lock file after this much time. Defaults to @samp{"2 mins"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs? -When mbox changes unexpectedly we have to fully read it to find out what -changed. If the mbox is large this can take a long time. Since the change -is usually just a newly appended mail, it'd be faster to simply read the new -mails. If this setting is enabled, Dovecot does this but still safely -fallbacks to re-reading the whole mbox file whenever something in mbox isn't -how it's expected to be. The only real downside to this setting is that if -some other MUA changes message flags, Dovecot doesn't notice it -immediately. Note that a full sync is done with SELECT, EXAMINE, EXPUNGE -and CHECK commands. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs? -Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT, -EXAMINE, EXPUNGE or CHECK commands. If this is set, @samp{mbox-dirty-syncs} -is ignored. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes? -Delay writing mbox headers until doing a full write sync (EXPUNGE and CHECK -commands and when closing the mailbox). This is especially useful for POP3 -where clients often delete all mails. The downside is that our changes -aren't immediately visible to other MUAs. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size -If mbox size is smaller than this (e.g.@: 100k), don't write index files. -If an index file already exists it's still read, just not updated. Defaults -to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size -Maximum dbox file size until it's rotated. Defaults to @samp{10000000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval -Maximum dbox file age until it's rotated. Typically in days. Day begins -from midnight, so 1d = today, 2d = yesterday, etc. 0 = check disabled. -Defaults to @samp{"1d"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space? -When creating new mdbox files, immediately preallocate their size to -@samp{mdbox-rotate-size}. This setting currently works only in Linux with -some file systems (ext4, xfs). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir -sdbox and mdbox support saving mail attachments to external files, which -also allows single instance storage for them. Other backends don't support -this for now. - -WARNING: This feature hasn't been tested much yet. Use at your own risk. - -Directory root where to store mail attachments. Disabled, if empty. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size -Attachments smaller than this aren't saved externally. It's also possible -to write a plugin to disable saving specific attachments externally. -Defaults to @samp{128000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs -File system backend to use for saving attachments: -@table @code -@item posix -No SiS done by Dovecot (but this might help FS's own deduplication) -@item sis posix -SiS with immediate byte-by-byte comparison during saving -@item sis-queue posix -SiS with delayed comparison and deduplication. -@end table -Defaults to @samp{"sis posix"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash -Hash format to use in attachment filenames. You can add any text and -variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}}, -@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be -truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits. -Defaults to @samp{"%@{sha1@}"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit - -Defaults to @samp{1000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit -Default VSZ (virtual memory size) limit for service processes. This is -mainly intended to catch and kill processes that leak memory before they eat -up everything. Defaults to @samp{256000000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string default-login-user -Login user is internally used by login processes. This is the most -untrusted user in Dovecot system. It shouldn't have access to anything at -all. Defaults to @samp{"dovenull"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string default-internal-user -Internal user is used by unprivileged processes. It should be separate from -login user, so that login processes can't disturb other processes. Defaults -to @samp{"dovecot"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl? -SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>. Defaults to -@samp{"required"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert -PEM encoded X.509 SSL/TLS certificate (public key). Defaults to -@samp{"</etc/dovecot/default.pem"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-key -PEM encoded SSL/TLS private key. The key is opened before dropping root -privileges, so keep the key file unreadable by anyone but root. Defaults to -@samp{"</etc/dovecot/private/default.pem"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password -If key file is password protected, give the password here. Alternatively -give it when starting dovecot with -p parameter. Since this file is often -world-readable, you may want to place this setting instead to a different. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-ca -PEM encoded trusted certificate authority. Set this only if you intend to -use @samp{ssl-verify-client-cert? #t}. The file should contain the CA -certificate(s) followed by the matching CRL(s). (e.g.@: @samp{ssl-ca -</etc/ssl/certs/ca.pem}). Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl? -Require that CRL check succeeds for client certificates. Defaults to -@samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert? -Request client to send a certificate. If you also want to require it, set -@samp{auth-ssl-require-client-cert? #t} in auth section. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field -Which field from certificate to use for username. commonName and -x500UniqueIdentifier are the usual choices. You'll also need to set -@samp{auth-ssl-username-from-cert? #t}. Defaults to @samp{"commonName"}. -@end deftypevr - -@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:!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 -SSL crypto device to use, for valid values run "openssl engine". Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address -Address to use when sending rejection mails. %d expands to recipient -domain. Defaults to @samp{"postmaster@@%d"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string hostname -Hostname to use in various parts of sent mails (e.g.@: in Message-Id) and -in LMTP replies. Default is the system's real hostname@@domain. Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail? -If user is over quota, return with temporary failure instead of bouncing the -mail. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path -Binary to use for sending mails. Defaults to @samp{"/usr/sbin/sendmail"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string submission-host -If non-empty, send mails via this SMTP host[:port] instead of sendmail. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject -Subject: header to use for rejection mails. You can use the same variables -as for @samp{rejection-reason} below. Defaults to @samp{"Rejected: %s"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason -Human readable error message for rejection mails. You can use variables: - -@table @code -@item %n -CRLF -@item %r -reason -@item %s -original subject -@item %t -recipient -@end table -Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter -Delimiter character between local-part and detail in email address. -Defaults to @samp{"+"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header -Header where the original recipient address (SMTP's RCPT TO: address) is -taken from if not available elsewhere. With dovecot-lda -a parameter -overrides this. A commonly used header for this is X-Original-To. Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate? -Should saving a mail to a nonexistent mailbox automatically create it?. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe? -Should automatically created mailboxes be also automatically subscribed?. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length -Maximum IMAP command line length. Some clients generate very long command -lines with huge mailboxes, so you may need to raise this if you get "Too -long argument" or "IMAP command line too large" errors often. Defaults to -@samp{64000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format -IMAP logout format string: -@table @code -@item %i -total number of bytes read from client -@item %o -total number of bytes sent to client. -@end table -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 -Override the IMAP CAPABILITY response. If the value begins with '+', add -the given capabilities on top of the defaults (e.g.@: +XFOO XBAR). Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval -How long to wait between "OK Still here" notifications when client is -IDLEing. Defaults to @samp{"2 mins"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-id-send -ID field names and values to send to clients. Using * as the value makes -Dovecot use the default value. The following fields have default values -currently: name, version, os, os-version, support-url, support-email. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log -ID fields sent by client to log. * means everything. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds -Workarounds for various client bugs: - -@table @code -@item delay-newmail -Send EXISTS/RECENT new mail notifications only when replying to NOOP and -CHECK commands. Some clients ignore them otherwise, for example OSX Mail -(<v2.1). Outlook Express breaks more badly though, without this it may show -user "Message no longer in server" errors. Note that OE6 still breaks even -with this workaround if synchronization is set to "Headers Only". - -@item tb-extra-mailbox-sep -Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and adds -extra @samp{/} suffixes to mailbox names. This option causes Dovecot to -ignore the extra @samp{/} instead of treating it as invalid mailbox name. - -@item tb-lsub-flags -Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox). This -makes Thunderbird realize they aren't selectable and show them greyed out, -instead of only later giving "not selectable" popup error. -@end table -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host -Host allowed in URLAUTH URLs sent by client. "*" allows all. Defaults to -@samp{""}. -@end deftypevr - - -Whew! Lots of configuration options. The nice thing about it though is that -Guix has a complete interface to Dovecot's configuration language. This -allows not only a nice way to declare configurations, but also offers -reflective capabilities as well: users can write code to inspect and -transform configurations from within Scheme. - -However, it could be that you just want to get a @code{dovecot.conf} up and -running. In that case, you can pass an @code{opaque-dovecot-configuration} -as the @code{#:config} parameter to @code{dovecot-service}. As its name -indicates, an opaque configuration does not have easy reflective -capabilities. - -Available @code{opaque-dovecot-configuration} fields are: - -@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot -The dovecot package. -@end deftypevr - -@deftypevr {@code{opaque-dovecot-configuration} parameter} string string -The contents of the @code{dovecot.conf}, as a string. -@end deftypevr - -For example, if your @code{dovecot.conf} is just the empty string, you could -instantiate a dovecot service like this: - -@example -(dovecot-service #:config - (opaque-dovecot-configuration - (string ""))) -@end example - -@subsubheading OpenSMTPD Service - -@deffn {Scheme Variable} opensmtpd-service-type -This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD} service, -whose value should be an @code{opensmtpd-configuration} object as in this -example: - -@example -(service opensmtpd-service-type - (opensmtpd-configuration - (config-file (local-file "./my-smtpd.conf")))) -@end example -@end deffn - -@deftp {Data Type} opensmtpd-configuration -Data type representing the configuration of opensmtpd. - -@table @asis -@item @code{package} (default: @var{opensmtpd}) -Package object of the OpenSMTPD SMTP server. - -@item @code{config-file} (default: @var{%default-opensmtpd-file}) -File-like object of the OpenSMTPD configuration file to use. By default it -listens on the loopback network interface, and allows for mail from users -and daemons on the local machine, as well as permitting email to remote -servers. Run @command{man smtpd.conf} for more information. - -@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}). - -@subsubheading GNU Mailutils IMAP4 Daemon -@cindex GNU Mailutils IMAP4 Daemon - -@deffn {Scheme Variable} imap4d-service-type -This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,, -mailutils, GNU Mailutils Manual}), whose value should be an -@code{imap4d-configuration} object as in this example: - -@example -(service imap4d-service-type - (imap4d-configuration - (config-file (local-file "imap4d.conf")))) -@end example -@end deffn - -@deftp {Data Type} imap4d-configuration -Data type representing the configuration of @command{imap4d}. - -@table @asis -@item @code{package} (default: @code{mailutils}) -The package that provides @command{imap4d}. - -@item @code{config-file} (default: @code{%default-imap4d-config-file}) -File-like object of the configuration file to use, by default it will listen -on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU -Mailutils Manual}, for details. - -@end table -@end deftp - -@node Messaging Services -@subsection Messaging Services - -@cindex messaging -@cindex jabber -@cindex XMPP -The @code{(gnu services messaging)} module provides Guix service definitions -for messaging services: currently only Prosody is supported. - -@subsubheading Prosody Service - -@deffn {Scheme Variable} prosody-service-type -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: - -@example -(service prosody-service-type - (prosody-configuration - (modules-enabled (cons "groups" "mam" %default-modules-enabled)) - (int-components - (list - (int-component-configuration - (hostname "conference.example.net") - (plugin "muc") - (mod-muc (mod-muc-configuration))))) - (virtualhosts - (list - (virtualhost-configuration - (domain "example.net")))))) -@end example - -See below for details about @code{prosody-configuration}. - -@end deffn - -By default, Prosody does not need much configuration. Only one -@code{virtualhosts} field is needed: it specifies the domain you wish -Prosody to serve. - -You can perform various sanity checks on the generated configuration with -the @code{prosodyctl check} command. - -Prosodyctl will also help you to import certificates from the -@code{letsencrypt} directory so that the @code{prosody} user can access -them. See @url{https://prosody.im/doc/letsencrypt}. - -@example -prosodyctl --root cert import /etc/letsencrypt/live -@end example - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{foo} parameter should be specified as a list of strings. Types -starting with @code{maybe-} denote parameters that won't show up in -@code{prosody.cfg.lua} when their value is @code{'disabled}. - -There is also a way to specify the configuration as a string, if you have an -old @code{prosody.cfg.lua} file that you want to port over from some other -system; see the end for more details. - -The @code{file-object} type designates either a file-like object -(@pxref{G-Expressions, file-like objects}) or a file name. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services messaging). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@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 Prosody updates. - -Available @code{prosody-configuration} fields are: - -@deftypevr {@code{prosody-configuration} parameter} package prosody -The Prosody package. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-name data-path -Location of the Prosody data storage directory. See -@url{https://prosody.im/doc/configure}. Defaults to -@samp{"/var/lib/prosody"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths -Additional plugin directories. They are searched in all the specified paths -in order. See @url{https://prosody.im/doc/plugins_directory}. Defaults to -@samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-name certificates -Every virtual host and component needs a certificate so that clients and -servers can securely verify its identity. Prosody will automatically load -certificates/keys from the directory specified here. Defaults to -@samp{"/etc/prosody/certs"}. -@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{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{https://prosody.im/doc/libevent}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled -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{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} string-list modules-disabled -@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but should -you want to disable them then add them to this list. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-object groups-file -Path to a text file where the shared groups are defined. If this path is -empty then @samp{mod_groups} does nothing. See -@url{https://prosody.im/doc/modules/mod_groups}. 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{https://prosody.im/doc/creating_accounts}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl -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{https://prosody.im/doc/advanced_ssl_config}. - -Available @code{ssl-configuration} fields are: - -@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol -This determines what handshake to use. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-name key -Path to your private key file. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate -Path to your certificate file. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} file-object capath -Path to directory containing root certificates that you wish Prosody to -trust when verifying the certificates of remote servers. Defaults to -@samp{"/etc/ssl/certs"}. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile -Path to a file containing root certificates that you wish Prosody to trust. -Similar to @code{capath} but with all certificates concatenated together. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify -A list of verification options (these mostly map to OpenSSL's -@code{set_verify()} flags). -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options -A list of general options relating to SSL/TLS. These map to OpenSSL's -@code{set_options()}. For a full list of options available in LuaSec, see -the LuaSec source. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth -How long a chain of certificate authorities to check when looking for a -trusted root certificate. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers -An OpenSSL cipher string. This selects what ciphers Prosody will offer to -clients, and in what order. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam -A path to a file containing parameters for Diffie-Hellman key exchange. You -can create such a file with: @code{openssl dhparam -out -/etc/prosody/certs/dh-2048.pem 2048} -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string curve -Curve for Elliptic curve Diffie-Hellman. Prosody's default is -@samp{"secp384r1"}. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext -A list of "extra" verification options. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string password -Password for encrypted private keys. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption? -Whether to force all client-to-server connections to be encrypted or not. -See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms -Set of mechanisms that will never be offered. See -@url{https://prosody.im/doc/modules/mod_saslauth}. Defaults to -@samp{("DIGEST-MD5")}. -@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{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth? -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{https://prosody.im/doc/s2s#security}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains -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{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{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string authentication -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{https://prosody.im/doc/modules/mod_auth_internal_hashed} for -information about using the hashed backend. See also -@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 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{https://prosody.im/doc/modules/mod_posix}. -Defaults to @samp{"/var/run/prosody/prosody.pid"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size -Maximum allowed size of the HTTP body (in bytes). -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url -Some modules expose their own URL in various ways. This URL is built from -the protocol, host and port used. If Prosody sits behind a proxy, the -public URL will be @code{http-external-url} instead. See -@url{https://prosody.im/doc/http#external_url}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts -A host in Prosody is a domain on which user accounts can be created. For -example if you want your users to have addresses like -@samp{"john.smith@@example.com"} then you need to add a host -@samp{"example.com"}. All options in this list will apply only to this -host. - -Note: the name "virtual" host is used in configuration to avoid confusion -with the actual physical host that Prosody is installed on. A single -Prosody instance can serve many domains, each one defined as a VirtualHost -entry in Prosody's configuration. Conversely a server that hosts a single -domain would have just one VirtualHost entry. - -See @url{https://prosody.im/doc/configure#virtual_host_settings}. - -Available @code{virtualhost-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{virtualhost-configuration} parameter} string domain -Domain you wish Prosody to serve. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components -Components are extra services on a server which are available to clients, -usually on a subdomain of the main server (such as -@samp{"mycomponent.example.com"}). Example components might be chatroom -servers, user directories, or gateways to other protocols. - -Internal components are implemented with Prosody-specific plugins. To add -an internal component, you simply fill the hostname field, and the plugin -you wish to use for the component. - -See @url{https://prosody.im/doc/components}. Defaults to @samp{()}. - -Available @code{int-component-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{int-component-configuration} parameter} string hostname -Hostname of the component. -@end deftypevr - -@deftypevr {@code{int-component-configuration} parameter} string plugin -Plugin you wish to use for the component. -@end deftypevr - -@deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc -Multi-user chat (MUC) is Prosody's module for allowing you to create hosted -chatrooms/conferences for XMPP users. - -General information on setting up and using multi-user chatrooms can be -found in the "Chatrooms" documentation -(@url{https://prosody.im/doc/chatrooms}), which you should read if you are -new to XMPP chatrooms. - -See also @url{https://prosody.im/doc/modules/mod_muc}. - -Available @code{mod-muc-configuration} fields are: - -@deftypevr {@code{mod-muc-configuration} parameter} string name -The name to return in service discovery responses. Defaults to -@samp{"Prosody Chatrooms"}. -@end deftypevr - -@deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation -If @samp{#t}, this will only allow admins to create new chatrooms. -Otherwise anyone can create a room. The value @samp{"local"} restricts room -creation to users on the service's parent domain. E.g.@: -@samp{user@@example.com} can create rooms on @samp{rooms.example.com}. The -value @samp{"admin"} restricts to service administrators only. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages -Maximum number of history messages that will be sent to the member that has -just joined the room. Defaults to @samp{20}. -@end deftypevr - -@end deftypevr - -@end deftypevr - -@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{https://prosody.im/doc/components}. Defaults to @samp{()}. - -Available @code{ext-component-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{ext-component-configuration} parameter} string component-secret -Password which the component will use to log in. -@end deftypevr - -@deftypevr {@code{ext-component-configuration} parameter} string hostname -Hostname of the component. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports -Port(s) Prosody listens on for component connections. Defaults to -@samp{(5347)}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string component-interface -Interface Prosody listens on for component connections. Defaults to -@samp{"127.0.0.1"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content -Raw content that will be added to the configuration file. -@end deftypevr - -It could be that you just want to get a @code{prosody.cfg.lua} up and -running. In that case, you can pass an @code{opaque-prosody-configuration} -record as the value of @code{prosody-service-type}. As its name indicates, -an opaque configuration does not have easy reflective capabilities. -Available @code{opaque-prosody-configuration} fields are: - -@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody -The prosody package. -@end deftypevr - -@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua -The contents of the @code{prosody.cfg.lua} to use. -@end deftypevr - -For example, if your @code{prosody.cfg.lua} is just the empty string, you -could instantiate a prosody service like this: - -@example -(service prosody-service-type - (opaque-prosody-configuration - (prosody.cfg.lua ""))) -@end example - -@c end of Prosody auto-generated documentation - -@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{plugins} (default: @code{'()}) -List of plugin packages to use---e.g., @code{bitlbee-discord}. - -@item @code{extra-settings} (default: @code{""}) -Configuration snippet added as-is to the BitlBee configuration file. -@end table -@end deftp - -@subsubheading Quassel Service - -@cindex IRC (Internet Relay Chat) -@url{https://quassel-irc.org/,Quassel} is a distributed IRC client, meaning -that one or more clients can attach to and detach from the central core. - -@defvr {Scheme Variable} quassel-service-type -This is the service type for the @url{https://quassel-irc.org/,Quassel} IRC -backend daemon. Its value is a @code{quassel-configuration} (see below). -@end defvr - -@deftp {Data Type} quassel-configuration -This is the configuration for Quassel, with the following fields: - -@table @asis -@item @code{quassel} (default: @code{quassel}) -The Quassel package to use. - -@item @code{interface} (default: @code{"::,0.0.0.0"}) -@item @code{port} (default: @code{4242}) -Listen on the network interface(s) corresponding to the IPv4 or IPv6 -interfaces specified in the comma delimited @var{interface}, on @var{port}. - -@item @code{loglevel} (default: @code{"Info"}) -The level of logging desired. Accepted values are Debug, Info, Warning and -Error. -@end table -@end deftp - -@node Telephony Services -@subsection Telephony Services - -@cindex Murmur (VoIP server) -@cindex VoIP server -This section describes how to set up and run a Murmur server. Murmur is the -server of the @uref{https://mumble.info, Mumble} voice-over-IP (VoIP) suite. - -@deftp {Data Type} murmur-configuration -The service type for the Murmur server. An example configuration can look -like this: - -@example -(service murmur-service-type - (murmur-configuration - (welcome-text - "Welcome to this Mumble server running on Guix!") - (cert-required? #t) ;disallow text password logins - (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem") - (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem"))) -@end example - -After reconfiguring your system, you can manually set the murmur -@code{SuperUser} password with the command that is printed during the -activation phase. - -It is recommended to register a normal Mumble user account and grant it -admin or moderator rights. You can use the @code{mumble} client to login as -new normal user, register yourself, and log out. For the next step login -with the name @code{SuperUser} use the @code{SuperUser} password that you -set previously, and grant your newly registered mumble user administrator or -moderator rights and create some channels. - -Available @code{murmur-configuration} fields are: - -@table @asis -@item @code{package} (default: @code{mumble}) -Package that contains @code{bin/murmurd}. - -@item @code{user} (default: @code{"murmur"}) -User who will run the Murmur server. - -@item @code{group} (default: @code{"murmur"}) -Group of the user who will run the murmur server. - -@item @code{port} (default: @code{64738}) -Port on which the server will listen. - -@item @code{welcome-text} (default: @code{""}) -Welcome text sent to clients when they connect. - -@item @code{server-password} (default: @code{""}) -Password the clients have to enter in order to connect. - -@item @code{max-users} (default: @code{100}) -Maximum of users that can be connected to the server at once. - -@item @code{max-user-bandwidth} (default: @code{#f}) -Maximum voice traffic a user can send per second. - -@item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"}) -File name of the sqlite database. The service's user will become the owner -of the directory. - -@item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"}) -File name of the log file. The service's user will become the owner of the -directory. - -@item @code{autoban-attempts} (default: @code{10}) -Maximum number of logins a user can make in @code{autoban-timeframe} without -getting auto banned for @code{autoban-time}. - -@item @code{autoban-timeframe} (default: @code{120}) -Timeframe for autoban in seconds. - -@item @code{autoban-time} (default: @code{300}) -Amount of time in seconds for which a client gets banned when violating the -autoban limits. - -@item @code{opus-threshold} (default: @code{100}) -Percentage of clients that need to support opus before switching over to -opus audio codec. - -@item @code{channel-nesting-limit} (default: @code{10}) -How deep channels can be nested at maximum. - -@item @code{channelname-regex} (default: @code{#f}) -A string in form of a Qt regular expression that channel names must conform -to. - -@item @code{username-regex} (default: @code{#f}) -A string in form of a Qt regular expression that user names must conform to. - -@item @code{text-message-length} (default: @code{5000}) -Maximum size in bytes that a user can send in one text chat message. - -@item @code{image-message-length} (default: @code{(* 128 1024)}) -Maximum size in bytes that a user can send in one image message. - -@item @code{cert-required?} (default: @code{#f}) -If it is set to @code{#t} clients that use weak password authentification -will not be accepted. Users must have completed the certificate wizard to -join. - -@item @code{remember-channel?} (default: @code{#f}) -Should murmur remember the last channel each user was in when they -disconnected and put them into the remembered channel when they rejoin. - -@item @code{allow-html?} (default: @code{#f}) -Should html be allowed in text messages, user comments, and channel -descriptions. - -@item @code{allow-ping?} (default: @code{#f}) -Setting to true exposes the current user count, the maximum user count, and -the server's maximum bandwidth per client to unauthenticated users. In the -Mumble client, this information is shown in the Connect dialog. - -Disabling this setting will prevent public listing of the server. - -@item @code{bonjour?} (default: @code{#f}) -Should the server advertise itself in the local network through the bonjour -protocol. - -@item @code{send-version?} (default: @code{#f}) -Should the murmur server version be exposed in ping requests. - -@item @code{log-days} (default: @code{31}) -Murmur also stores logs in the database, which are accessible via RPC. The -default is 31 days of months, but you can set this setting to 0 to keep logs -forever, or -1 to disable logging to the database. - -@item @code{obfuscate-ips?} (default: @code{#t}) -Should logged ips be obfuscated to protect the privacy of users. - -@item @code{ssl-cert} (default: @code{#f}) -File name of the SSL/TLS certificate used for encrypted connections. - -@example -(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem") -@end example -@item @code{ssl-key} (default: @code{#f}) -Filepath to the ssl private key used for encrypted connections. -@example -(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem") -@end example - -@item @code{ssl-dh-params} (default: @code{#f}) -File name of a PEM-encoded file with Diffie-Hellman parameters for the -SSL/TLS encryption. Alternatively you set it to @code{"@@ffdhe2048"}, -@code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"} or -@code{"@@ffdhe8192"} to use bundled parameters from RFC 7919. - -@item @code{ssl-ciphers} (default: @code{#f}) -The @code{ssl-ciphers} option chooses the cipher suites to make available -for use in SSL/TLS. - -This option is specified using -@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT, -OpenSSL cipher list notation}. - -It is recommended that you try your cipher string using 'openssl ciphers -<string>' before setting it here, to get a feel for which cipher suites you -will get. After setting this option, it is recommend that you inspect your -Murmur log to ensure that Murmur is using the cipher suites that you -expected it to. - -Note: Changing this option may impact the backwards compatibility of your -Murmur server, and can remove the ability for older Mumble clients to be -able to connect to it. - -@item @code{public-registration} (default: @code{#f}) -Must be a @code{<murmur-public-registration-configuration>} record or -@code{#f}. - -You can optionally register your server in the public server list that the -@code{mumble} client shows on startup. You cannot register your server if -you have set a @code{server-password}, or set @code{allow-ping} to -@code{#f}. - -It might take a few hours until it shows up in the public list. - -@item @code{file} (default: @code{#f}) -Optional alternative override for this configuration. -@end table -@end deftp - -@deftp {Data Type} murmur-public-registration-configuration -Configuration for public registration of a murmur service. - -@table @asis -@item @code{name} -This is a display name for your server. Not to be confused with the -hostname. - -@item @code{password} -A password to identify your registration. Subsequent updates will need the -same password. Don't lose your password. - -@item @code{url} -This should be a @code{http://} or @code{https://} link to your web site. - -@item @code{hostname} (default: @code{#f}) -By default your server will be listed by its IP address. If it is set your -server will be linked by this host name instead. -@end table -@end deftp - - - -@node Monitoring Services -@subsection Monitoring Services - -@subsubheading Tailon Service - -@uref{https://tailon.readthedocs.io/, Tailon} is a web application for -viewing and searching log files. - -The following example will configure the service with default values. By -default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}). - -@example -(service tailon-service-type) -@end example - -The following example customises more of the Tailon configuration, adding -@command{sed} to the list of allowed commands. - -@example -(service tailon-service-type - (tailon-configuration - (config-file - (tailon-configuration-file - (allowed-commands '("tail" "grep" "awk" "sed")))))) -@end example - - -@deftp {Data Type} tailon-configuration -Data type representing the configuration of Tailon. This type has the -following parameters: - -@table @asis -@item @code{config-file} (default: @code{(tailon-configuration-file)}) -The configuration file to use for Tailon. This can be set to a -@dfn{tailon-configuration-file} record value, or any gexp -(@pxref{G-Expressions}). - -For example, to instead use a local file, the @code{local-file} function can -be used: - -@example -(service tailon-service-type - (tailon-configuration - (config-file (local-file "./my-tailon.conf")))) -@end example - -@item @code{package} (default: @code{tailon}) -The tailon package to use. - -@end table -@end deftp - -@deftp {Data Type} tailon-configuration-file -Data type representing the configuration options for Tailon. This type has -the following parameters: - -@table @asis -@item @code{files} (default: @code{(list "/var/log")}) -List of files to display. The list can include strings for a single file or -directory, or a list, where the first item is the name of a subsection, and -the remaining items are the files or directories in that subsection. - -@item @code{bind} (default: @code{"localhost:8080"}) -Address and port to which Tailon should bind on. - -@item @code{relative-root} (default: @code{#f}) -URL path to use for Tailon, set to @code{#f} to not use a path. - -@item @code{allow-transfers?} (default: @code{#t}) -Allow downloading the log files in the web interface. - -@item @code{follow-names?} (default: @code{#t}) -Allow tailing of not-yet existent files. - -@item @code{tail-lines} (default: @code{200}) -Number of lines to read initially from each file. - -@item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")}) -Commands to allow running. By default, @code{sed} is disabled. - -@item @code{debug?} (default: @code{#f}) -Set @code{debug?} to @code{#t} to show debug messages. - -@item @code{wrap-lines} (default: @code{#t}) -Initial line wrapping state in the web interface. Set to @code{#t} to -initially wrap lines (the default), or to @code{#f} to initially not wrap -lines. - -@item @code{http-auth} (default: @code{#f}) -HTTP authentication type to use. Set to @code{#f} to disable authentication -(the default). Supported values are @code{"digest"} or @code{"basic"}. - -@item @code{users} (default: @code{#f}) -If HTTP authentication is enabled (see @code{http-auth}), access will be -restricted to the credentials provided here. To configure users, use a list -of pairs, where the first element of the pair is the username, and the 2nd -element of the pair is the password. - -@example -(tailon-configuration-file - (http-auth "basic") - (users '(("user1" . "password1") - ("user2" . "password2")))) -@end example - -@end table -@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 - -@subsubheading Prometheus Node Exporter Service - -@cindex prometheus-node-exporter -The Prometheus ``node exporter'' makes hardware and operating system -statistics provided by the Linux kernel available for the Prometheus -monitoring system. This service should be deployed on all physical nodes -and virtual machines, where monitoring these statistics is desirable. - -@defvar {Scheme variable} prometheus-node-exporter-service-type -This is the service type for the -@uref{https://github.com/prometheus/node_exporter/, -prometheus-node-exporter} service, its value must be a -@code{prometheus-node-exporter-configuration} record as in this example: - -@example -(service prometheus-node-exporter-service-type - (prometheus-node-exporter-configuration - (web-listen-address ":9100"))) -@end example -@end defvar - -@deftp {Data Type} prometheus-node-exporter-configuration -Data type representing the configuration of @command{node_exporter}. - -@table @asis -@item @code{package} (default: @code{go-github-com-prometheus-node-exporter}) -The prometheus-node-exporter package to use. - -@item @code{web-listen-address} (default: @code{":9100"}) -Bind the web interface to the specified address. - -@end table -@end deftp - -@subsubheading Zabbix server -@cindex zabbix zabbix-server -Zabbix provides monitoring metrics, among others network utilization, CPU -load and disk space consumption: - -@itemize -@item High performance, high capacity (able to monitor hundreds of thousands of devices). -@item Auto-discovery of servers and network devices and interfaces. -@item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others. -@item Distributed monitoring with centralized web administration. -@item Native high performance agents. -@item SLA, and ITIL KPI metrics on reporting. -@item High-level (business) view of monitored resources through user-defined visual console screens and dashboards. -@item Remote command execution through Zabbix proxies. -@end itemize - -@c %start of fragment - -Available @code{zabbix-server-configuration} fields are: - -@deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server -The zabbix-server package. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string user -User who will run the Zabbix server. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} group group -Group who will run the Zabbix server. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-host -Database host name. - -Defaults to @samp{"127.0.0.1"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-name -Database name. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-user -Database user. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-password -Database password. Please, use @code{include-files} with -@code{DBPassword=SECRET} inside a specified file instead. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} number db-port -Database port. - -Defaults to @samp{5432}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string log-type -Specifies where log messages are written to: - -@itemize @bullet -@item -@code{system} - syslog. - -@item -@code{file} - file specified with @code{log-file} parameter. - -@item -@code{console} - standard output. - -@end itemize - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string log-file -Log file name for @code{log-type} @code{file} parameter. - -Defaults to @samp{"/var/log/zabbix/server.log"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string pid-file -Name of PID file. - -Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location -The location of certificate authority (CA) files for SSL server certificate -verification. - -Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location -Location of SSL client certificates. - -Defaults to @samp{"/etc/ssl/certs"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string extra-options -Extra options will be appended to Zabbix server configuration file. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} include-files include-files -You may include individual files or all files in a directory in the -configuration file. - -Defaults to @samp{()}. - -@end deftypevr - -@c %end of fragment - -@subsubheading Zabbix agent -@cindex zabbix zabbix-agent - -Zabbix agent gathers information for Zabbix server. - -@c %start of fragment - -Available @code{zabbix-agent-configuration} fields are: - -@deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent -The zabbix-agent package. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string user -User who will run the Zabbix agent. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} group group -Group who will run the Zabbix agent. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string hostname -Unique, case sensitive hostname which is required for active checks and must -match hostname as configured on the server. - -Defaults to @samp{"Zabbix server"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string log-type -Specifies where log messages are written to: - -@itemize @bullet -@item -@code{system} - syslog. - -@item -@code{file} - file specified with @code{log-file} parameter. - -@item -@code{console} - standard output. - -@end itemize - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string log-file -Log file name for @code{log-type} @code{file} parameter. - -Defaults to @samp{"/var/log/zabbix/agent.log"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file -Name of PID file. - -Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} list server -List of IP addresses, optionally in CIDR notation, or hostnames of Zabbix -servers and Zabbix proxies. Incoming connections will be accepted only from -the hosts listed here. - -Defaults to @samp{("127.0.0.1")}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} list server-active -List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix -proxies for active checks. If port is not specified, default port is used. -If this parameter is not specified, active checks are disabled. - -Defaults to @samp{("127.0.0.1")}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options -Extra options will be appended to Zabbix server configuration file. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} include-files include-files -You may include individual files or all files in a directory in the -configuration file. - -Defaults to @samp{()}. - -@end deftypevr - -@c %end of fragment - -@subsubheading Zabbix front-end -@cindex zabbix zabbix-front-end - -This service provides a WEB interface to Zabbix server. - -@c %start of fragment - -Available @code{zabbix-front-end-configuration} fields are: - -@deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx -NGINX configuration. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host -Database host name. - -Defaults to @samp{"localhost"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port -Database port. - -Defaults to @samp{5432}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name -Database name. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user -Database user. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password -Database password. Please, use @code{db-secret-file} instead. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file -Secret file which will be appended to @file{zabbix.conf.php} file. This -file contains credentials for use by Zabbix front-end. You are expected to -create it manually. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host -Zabbix server hostname. - -Defaults to @samp{"localhost"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port -Zabbix server port. - -Defaults to @samp{10051}. - -@end deftypevr - - -@c %end of fragment - -@node Kerberos Services -@subsection Kerberos Services -@cindex Kerberos - -The @code{(gnu services kerberos)} module provides services relating to the -authentication protocol @dfn{Kerberos}. - -@subsubheading Krb5 Service - -Programs using a Kerberos client library normally expect a configuration -file in @file{/etc/krb5.conf}. This service generates such a file from a -definition provided in the operating system declaration. It does not cause -any daemon to be started. - -No ``keytab'' files are provided by this service---you must explicitly -create them. This service is known to work with the MIT client library, -@code{mit-krb5}. Other implementations have not been tested. - -@defvr {Scheme Variable} krb5-service-type -A service type for Kerberos 5 clients. -@end defvr - -@noindent -Here is an example of its use: -@lisp -(service krb5-service-type - (krb5-configuration - (default-realm "EXAMPLE.COM") - (allow-weak-crypto? #t) - (realms (list - (krb5-realm - (name "EXAMPLE.COM") - (admin-server "groucho.example.com") - (kdc "karl.example.com")) - (krb5-realm - (name "ARGRX.EDU") - (admin-server "kerb-admin.argrx.edu") - (kdc "keys.argrx.edu")))))) -@end lisp - -@noindent -This example provides a Kerberos@tie{}5 client configuration which: -@itemize -@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both -of which have distinct administration servers and key distribution centers; -@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly -specified by clients; -@item Accepts services which only support encryption types known to be weak. -@end itemize - -The @code{krb5-realm} and @code{krb5-configuration} types have many fields. -Only the most commonly used ones are described here. For a full list, and -more detailed explanation of each, see the MIT -@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} -documentation. - - -@deftp {Data Type} krb5-realm -@cindex realm, kerberos -@table @asis -@item @code{name} -This field is a string identifying the name of the realm. A common -convention is to use the fully qualified DNS name of your organization, -converted to upper case. - -@item @code{admin-server} -This field is a string identifying the host where the administration server -is running. - -@item @code{kdc} -This field is a string identifying the key distribution center for the -realm. -@end table -@end deftp - -@deftp {Data Type} krb5-configuration - -@table @asis -@item @code{allow-weak-crypto?} (default: @code{#f}) -If this flag is @code{#t} then services which only offer encryption -algorithms known to be weak will be accepted. - -@item @code{default-realm} (default: @code{#f}) -This field should be a string identifying the default Kerberos realm for the -client. You should set this field to the name of your Kerberos realm. If -this value is @code{#f} then a realm must be specified with every Kerberos -principal when invoking programs such as @command{kinit}. - -@item @code{realms} -This should be a non-empty list of @code{krb5-realm} objects, which clients -may access. Normally, one of them will have a @code{name} field matching -the @code{default-realm} field. -@end table -@end deftp - - -@subsubheading PAM krb5 Service -@cindex pam-krb5 - -The @code{pam-krb5} service allows for login authentication and password -management via Kerberos. You will need this service if you want PAM enabled -applications to authenticate users using Kerberos. - -@defvr {Scheme Variable} pam-krb5-service-type -A service type for the Kerberos 5 PAM module. -@end defvr - -@deftp {Data Type} pam-krb5-configuration -Data type representing the configuration of the Kerberos 5 PAM module This -type has the following parameters: -@table @asis -@item @code{pam-krb5} (default: @code{pam-krb5}) -The pam-krb5 package to use. - -@item @code{minimum-uid} (default: @code{1000}) -The smallest user ID for which Kerberos authentications should be -attempted. Local accounts with lower values will silently fail to -authenticate. -@end table -@end deftp - - -@node LDAP Services -@subsection LDAP Services -@cindex LDAP -@cindex nslcd, LDAP service - -The @code{(gnu services authentication)} module provides the -@code{nslcd-service-type}, which can be used to authenticate against an LDAP -server. In addition to configuring the service itself, you may want to add -@code{ldap} as a name service to the Name Service Switch. @xref{Name Service -Switch} for detailed information. - -Here is a simple operating system declaration with a default configuration -of the @code{nslcd-service-type} and a Name Service Switch configuration -that consults the @code{ldap} name service last: - -@example -(use-service-modules authentication) -(use-modules (gnu system nss)) -... -(operating-system - ... - (services - (cons* - (service nslcd-service-type) - (service dhcp-client-service-type) - %base-services)) - (name-service-switch - (let ((services (list (name-service (name "db")) - (name-service (name "files")) - (name-service (name "ldap"))))) - (name-service-switch - (inherit %mdns-host-lookup-nss) - (password services) - (shadow services) - (group services) - (netgroup services) - (gshadow services))))) -@end example - -@c %start of generated documentation for nslcd-configuration - -Available @code{nslcd-configuration} fields are: - -@deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd -The @code{nss-pam-ldapd} package to use. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number threads -The number of threads to start that can handle requests and perform LDAP -queries. Each thread opens a separate connection to the LDAP server. The -default is to start 5 threads. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string uid -This specifies the user id with which the daemon should be run. - -Defaults to @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string gid -This specifies the group id with which the daemon should be run. - -Defaults to @samp{"nslcd"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} log-option log -This option controls the way logging is done via a list containing SCHEME -and LEVEL. The SCHEME argument may either be the symbols "none" or -"syslog", or an absolute file name. The LEVEL argument is optional and -specifies the log level. The log level may be one of the following symbols: -"crit", "error", "warning", "notice", "info" or "debug". All messages with -the specified log level or higher are logged. - -Defaults to @samp{("/var/log/nslcd" info)}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list uri -The list of LDAP server URIs. Normally, only the first server will be used -with the following servers as fall-back. - -Defaults to @samp{("ldap://localhost:389/")}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version -The version of the LDAP protocol to use. The default is to use the maximum -version supported by the LDAP library. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn -Specifies the distinguished name with which to bind to the directory server -for lookups. The default is to bind anonymously. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw -Specifies the credentials with which to bind. This option is only -applicable when used with binddn. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn -Specifies the distinguished name to use when the root user tries to modify a -user's password using the PAM module. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw -Specifies the credentials with which to bind if the root user tries to -change a user's password. This option is only applicable when used with -rootpwmoddn - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech -Specifies the SASL mechanism to be used when performing SASL authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm -Specifies the SASL realm to be used when performing SASL authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid -Specifies the authentication identity to be used when performing SASL -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid -Specifies the authorization identity to be used when performing SASL -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize? -Determines whether the LDAP server host name should be canonicalised. If -this is enabled the LDAP library will do a reverse host name lookup. By -default, it is left up to the LDAP library whether this check is performed -or not. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname -Set the name for the GSS-API Kerberos credentials cache. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} string base -The directory search base. - -Defaults to @samp{"dc=example,dc=com"}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} scope-option scope -Specifies the search scope (subtree, onelevel, base or children). The -default scope is subtree; base scope is almost never useful for name service -lookups; children scope is not supported on all servers. - -Defaults to @samp{(subtree)}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref -Specifies the policy for dereferencing aliases. The default policy is to -never dereference aliases. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals -Specifies whether automatic referral chasing should be enabled. The default -behaviour is to chase referrals. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps -This option allows for custom attributes to be looked up instead of the -default RFC 2307 attributes. It is a list of maps, each consisting of the -name of a map, the RFC 2307 attribute to match and the query expression for -the attribute as it is available in the directory. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters -A list of filters consisting of the name of a map to which the filter -applies and an LDAP search filter expression. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit -Specifies the time limit in seconds to use when connecting to the directory -server. The default value is 10 seconds. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit -Specifies the time limit (in seconds) to wait for a response from the LDAP -server. A value of zero, which is the default, is to wait indefinitely for -searches to be completed. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit -Specifies the period if inactivity (in seconds) after which the con‐ nection -to the LDAP server will be closed. The default is not to time out -connections. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime -Specifies the number of seconds to sleep when connecting to all LDAP servers -fails. By default one second is waited between the first failure and the -first retry. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime -Specifies the time after which the LDAP server is considered to be -permanently unavailable. Once this time is reached retries will be done -only once per this time period. The default value is 10 seconds. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl -Specifies whether to use SSL/TLS or not (the default is not to). If -'start-tls is specified then StartTLS is used rather than raw LDAP over SSL. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert -Specifies what checks to perform on a server-supplied certificate. The -meaning of the values is described in the ldap.conf(5) manual page. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir -Specifies the directory containing X.509 certificates for peer authen‐ -tication. This parameter is ignored when using GnuTLS. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile -Specifies the path to the X.509 certificate for peer authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile -Specifies the path to an entropy source. This parameter is ignored when -using GnuTLS. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers -Specifies the ciphers to use for TLS as a string. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert -Specifies the path to the file containing the local certificate for client -TLS authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key -Specifies the path to the file containing the private key for client TLS -authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize -Set this to a number greater than 0 to request paged results from the LDAP -server in accordance with RFC2696. The default (0) is to not request paged -results. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers -This option prevents group membership lookups through LDAP for the specified -users. Alternatively, the value 'all-local may be used. With that value -nslcd builds a full list of non-LDAP users on startup. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid -This option ensures that LDAP users with a numeric user id lower than the -specified value are ignored. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset -This option specifies an offset that is added to all LDAP numeric user ids. -This can be used to avoid user id collisions with local users. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset -This option specifies an offset that is added to all LDAP numeric group -ids. This can be used to avoid user id collisions with local groups. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups -If this option is set, the member attribute of a group may point to another -group. Members of nested groups are also returned in the higher level group -and parent groups are returned when finding groups for a specific user. The -default is not to perform extra searches for nested groups. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers -If this option is set, the group member list is not retrieved when looking -up groups. Lookups for finding which groups a user belongs to will remain -functional so the user will likely still get the correct groups assigned on -login. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration -If this option is set, functions which cause all user/group entries to be -loaded from the directory will not succeed in doing so. This can -dramatically reduce LDAP server load in situations where there are a great -number of users and/or groups. This option is not recommended for most -configurations. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames -This option can be used to specify how user and group names are verified -within the system. This pattern is used to check all user and group names -that are requested and returned from LDAP. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase -This specifies whether or not to perform searches using case-insensitive -matching. Enabling this could open up the system to authorization bypass -vulnerabilities and introduce nscd cache poisoning vulnerabilities which -allow denial of service. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy -This option specifies whether password policy controls are requested and -handled from the LDAP server when performing user authentication. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search -By default nslcd performs an LDAP search with the user's credentials after -BIND (authentication) to ensure that the BIND operation was successful. The -default search is a simple check to see if the user's DN exists. A search -filter can be specified that will be used instead. It should return at -least one entry. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search -This option allows flexible fine tuning of the authorisation check that -should be performed. The search filter specified is executed and if any -entries match, access is granted, otherwise access is denied. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message -If this option is set password modification using pam_ldap will be denied -and the specified message will be presented to the user instead. The -message can be used to direct the user to an alternative means of changing -their password. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{nslcd-configuration} parameter} list pam-services -List of pam service names for which LDAP authentication should suffice. - -Defaults to @samp{()}. - -@end deftypevr - -@c %end of generated documentation for nslcd-configuration - - -@node Web Services -@subsection Web Services - -@cindex web -@cindex www -@cindex HTTP -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{httpd-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 - -@defvr {Scheme Variable} %default-httpd-modules -A default list of @code{httpd-module} objects. -@end defvr - -@deffn {Data Type} httpd-config-file -This data type represents a configuration file for the httpd service. - -@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. - -For example, in order to handle requests for PHP files, you can use Apache’s -@code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}: - -@example -(service httpd-service-type - (httpd-configuration - (config - (httpd-config-file - (modules (cons* - (httpd-module - (name "proxy_module") - (file "modules/mod_proxy.so")) - (httpd-module - (name "proxy_fcgi_module") - (file "modules/mod_proxy_fcgi.so")) - %default-httpd-modules)) - (extra-config (list "\ -<FilesMatch \\.php$> - SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\" -</FilesMatch>")))))) -(service php-fpm-service-type - (php-fpm-configuration - (socket "/var/run/php-fpm.sock") - (socket-group "httpd"))) -@end example - -@item @code{server-root} (default: @code{httpd}) -The @code{ServerRoot} in the configuration file, defaults to the httpd -package. Directives including @code{Include} and @code{LoadModule} are 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 value -for this service type is a @code{<nginx-configuration>} record. - -A simple example configuration is given below. - -@example -(service nginx-service-type - (nginx-configuration - (server-blocks - (list (nginx-server-configuration - (server-name '("www.example.com")) - (root "/srv/http/www.example.com")))))) -@end example - -In addition to adding server blocks to the service configuration directly, -this service can be extended by other services to add server blocks, as in -this example: - -@example -(simple-service 'my-extra-server nginx-service-type - (list (nginx-server-configuration - (root "/srv/http/extra-website") - (try-files (list "$uri" "$uri/index.html"))))) -@end example -@end deffn - -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. - -@deffn {Data Type} nginx-configuration -This data type represents the configuration for NGinx. Some configuration -can be done through this and the other provided record types, or -alternatively, a config file can be provided. - -@table @asis -@item @code{nginx} (default: @code{nginx}) -The nginx package to use. - -@item @code{log-directory} (default: @code{"/var/log/nginx"}) -The directory to which NGinx will write log files. - -@item @code{run-directory} (default: @code{"/var/run/nginx"}) -The directory in which NGinx will create a pid file, and write temporary -files. - -@item @code{server-blocks} (default: @code{'()}) -A list of @dfn{server blocks} to create in the generated configuration file, -the elements should be of type @code{<nginx-server-configuration>}. - -The following example would setup NGinx to serve @code{www.example.com} from -the @code{/srv/http/www.example.com} directory, without using HTTPS. -@example -(service nginx-service-type - (nginx-configuration - (server-blocks - (list (nginx-server-configuration - (server-name '("www.example.com")) - (root "/srv/http/www.example.com")))))) -@end example - -@item @code{upstream-blocks} (default: @code{'()}) -A list of @dfn{upstream blocks} to create in the generated configuration -file, the elements should be of type @code{<nginx-upstream-configuration>}. - -Configuring upstreams through the @code{upstream-blocks} can be useful when -combined with @code{locations} in the @code{<nginx-server-configuration>} -records. The following example creates a server configuration with one -location configuration, that will proxy requests to a upstream -configuration, which will handle requests with two servers. - -@example -(service - nginx-service-type - (nginx-configuration - (server-blocks - (list (nginx-server-configuration - (server-name '("www.example.com")) - (root "/srv/http/www.example.com") - (locations - (list - (nginx-location-configuration - (uri "/path1") - (body '("proxy_pass http://server-proxy;")))))))) - (upstream-blocks - (list (nginx-upstream-configuration - (name "server-proxy") - (servers (list "server1.example.com" - "server2.example.com"))))))) -@end example - -@item @code{file} (default: @code{#f}) -If a configuration @var{file} is provided, this will be used, rather than -generating a configuration file from the provided @code{log-directory}, -@code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For -proper operation, these arguments should match what is in @var{file} to -ensure that the directories are created when the service is activated. - -This can be useful if you have an existing configuration file, or it's 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. - -@item @code{extra-content} (default: @code{""}) -Extra content for the @code{http} block. Should be string or a string -valued G-expression. - -@end table -@end deffn - -@deftp {Data Type} nginx-server-configuration -Data type representing the configuration of an nginx server block. This -type has the following parameters: - -@table @asis -@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: - -@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 default server for connections matching no other server. - -@item @code{root} (default: @code{"/srv/http"}) -Root of the website nginx will serve. - -@item @code{locations} (default: @code{'()}) -A list of @dfn{nginx-location-configuration} or -@dfn{nginx-named-location-configuration} records to use within this server -block. - -@item @code{index} (default: @code{(list "index.html")}) -Index files to look for when clients ask for a directory. If it cannot be -found, Nginx will send the list of files in the directory. - -@item @code{try-files} (default: @code{'()}) -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{#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{#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 - -@deftp {Data Type} nginx-upstream-configuration -Data type representing the configuration of an nginx @code{upstream} block. -This type has the following parameters: - -@table @asis -@item @code{name} -Name for this group of servers. - -@item @code{servers} -Specify the addresses of the servers in the group. The address can be -specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name (e.g.@: -@samp{backend1.example.com}) or a path to a UNIX socket using the prefix -@samp{unix:}. For addresses using an IP address or domain name, the default -port is 80, and a different port can be specified explicitly. - -@end table -@end deftp - -@deftp {Data Type} nginx-location-configuration -Data type representing the configuration of an nginx @code{location} block. -This type has the following parameters: - -@table @asis -@item @code{uri} -URI which this location block matches. - -@anchor{nginx-location-configuration body} -@item @code{body} -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{(list "proxy_pass -http://upstream-name;")}. - -@end table -@end deftp - -@deftp {Data Type} nginx-named-location-configuration -Data type representing the configuration of an nginx named location block. -Named location blocks are used for request redirection, and not used for -regular request processing. This type has the following parameters: - -@table @asis -@item @code{name} -Name to identify this location block. - -@item @code{body} -@xref{nginx-location-configuration body}, as the body for named location -blocks can be used in a similar way to the -@code{nginx-location-configuration body}. One restriction is that the body -of a named location block cannot contain location blocks. - -@end table -@end deftp - -@subsubheading Varnish Cache -@cindex Varnish -Varnish is a fast cache server that sits in between web applications and end -users. It proxies requests from clients and caches the accessed URLs such -that multiple requests for the same resource only creates one request to the -back-end. - -@defvr {Scheme Variable} varnish-service-type -Service type for the Varnish daemon. -@end defvr - -@deftp {Data Type} varnish-configuration -Data type representing the @code{varnish} service configuration. This type -has the following parameters: - -@table @asis -@item @code{package} (default: @code{varnish}) -The Varnish package to use. - -@item @code{name} (default: @code{"default"}) -A name for this Varnish instance. Varnish will create a directory in -@file{/var/varnish/} with this name and keep temporary files there. If the -name starts with a forward slash, it is interpreted as an absolute directory -name. - -Pass the @code{-n} argument to other Varnish programs to connect to the -named instance, e.g.@: @command{varnishncsa -n default}. - -@item @code{backend} (default: @code{"localhost:8080"}) -The backend to use. This option has no effect if @code{vcl} is set. - -@item @code{vcl} (default: #f) -The @dfn{VCL} (Varnish Configuration Language) program to run. If this is -@code{#f}, Varnish will proxy @code{backend} using the default -configuration. Otherwise this must be a file-like object with valid VCL -syntax. - -@c Varnish does not support HTTPS, so keep this URL to avoid confusion. -For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you can -do something along these lines: - -@example -(define %gnu-mirror - (plain-file - "gnu.vcl" - "vcl 4.1; -backend gnu @{ .host = "www.gnu.org"; @}")) - -(operating-system - ... - (services (cons (service varnish-service-type - (varnish-configuration - (listen '(":80")) - (vcl %gnu-mirror))) - %base-services))) -@end example - -The configuration of an already running Varnish instance can be inspected -and changed using the @command{varnishadm} program. - -Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and -@url{https://book.varnish-software.com/4.0/,Varnish Book} for comprehensive -documentation on Varnish and its configuration language. - -@item @code{listen} (default: @code{'("localhost:80")}) -List of addresses Varnish will listen on. - -@item @code{storage} (default: @code{'("malloc,128m")}) -List of storage backends that will be available in VCL. - -@item @code{parameters} (default: @code{'()}) -List of run-time parameters in the form @code{'(("parameter" . "value"))}. - -@item @code{extra-options} (default: @code{'()}) -Additional arguments to pass to the @command{varnishd} process. - -@end table -@end deftp - -@subsubheading FastCGI -@cindex fastcgi -@cindex fcgiwrap -FastCGI is an interface between the front-end and the back-end of a web -service. It is a somewhat legacy facility; new web services should -generally just talk HTTP between the front-end and the back-end. However -there are a number of back-end services such as PHP or the optimized HTTP -Git repository access that use FastCGI, so we have support for it in Guix. - -To use FastCGI, you configure the front-end web server (e.g., nginx) to -dispatch some subset of its requests to the fastcgi backend, which listens -on a local TCP or UNIX socket. There is an intermediary @code{fcgiwrap} -program that sits between the actual backend process and the web server. -The front-end indicates which backend program to run, passing that -information to the @code{fcgiwrap} process. - -@defvr {Scheme Variable} fcgiwrap-service-type -A service type for the @code{fcgiwrap} FastCGI proxy. -@end defvr - -@deftp {Data Type} fcgiwrap-configuration -Data type representing the configuration of the @code{fcgiwrap} service. -This type has the following parameters: -@table @asis -@item @code{package} (default: @code{fcgiwrap}) -The fcgiwrap package to use. - -@item @code{socket} (default: @code{tcp:127.0.0.1:9000}) -The socket on which the @code{fcgiwrap} process should listen, as a string. -Valid @var{socket} values include @code{unix:@var{/path/to/unix/socket}}, -@code{tcp:@var{dot.ted.qu.ad}:@var{port}} and -@code{tcp6:[@var{ipv6_addr}]:port}. - -@item @code{user} (default: @code{fcgiwrap}) -@itemx @code{group} (default: @code{fcgiwrap}) -The user and group names, as strings, under which to run the @code{fcgiwrap} -process. The @code{fastcgi} service will ensure that if the user asks for -the specific user or group names @code{fcgiwrap} that the corresponding user -and/or group is present on the system. - -It is possible to configure a FastCGI-backed web service to pass HTTP -authentication information from the front-end to the back-end, and to allow -@code{fcgiwrap} to run the back-end process as a corresponding local user. -To enable this capability on the back-end., run @code{fcgiwrap} as the -@code{root} user and group. Note that this capability also has to be -configured on the front-end as well. -@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 whether php errors and warning should be sent to clients and -displayed in their browsers. This is useful for local php development, but -a security risk for public sites, as error messages can reveal passwords and -personal data. -@item @code{timezone} (default @code{#f}) -Specifies @code{php_admin_value[date.timezone]} parameter. -@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* (service dhcp-client-service-type) - (service php-fpm-service-type) - (service nginx-service-type - (nginx-server-configuration - (server-name '("example.com")) - (root "/srv/http/") - (locations - (list (nginx-php-location))) - (listen '("80")) - (ssl-certificate #f) - (ssl-certificate-key #f))) - %base-services)) -@end example - -@cindex cat-avatar-generator -The cat avatar generator is a simple service to demonstrate the use of -php-fpm in @code{Nginx}. It is used to generate cat avatar from a seed, for -instance the hash of a user's email address. - -@deffn {Scheme Procedure} cat-avatar-generator-service @ - [#:cache-dir "/var/cache/cat-avatar-generator"] @ [#:package -cat-avatar-generator] @ [#:configuration (nginx-server-configuration)] -Returns an nginx-server-configuration that inherits @code{configuration}. -It extends the nginx configuration to add a server block that serves -@code{package}, a version of cat-avatar-generator. During execution, -cat-avatar-generator will be able to use @code{cache-dir} as its cache -directory. -@end deffn - -A simple setup for cat-avatar-generator can look like this: -@example -(services (cons* (cat-avatar-generator-service - #:configuration - (nginx-server-configuration - (server-name '("example.com")))) - ... - %base-services)) -@end example - -@subsubheading Hpcguix-web - -@cindex hpcguix-web -The @uref{hpcguix-web, https://github.com/UMCUGenetics/hpcguix-web/} program -is a customizable web interface to browse Guix packages, initially designed -for users of high-performance computing (HPC) clusters. - -@defvr {Scheme Variable} hpcguix-web-service-type -The service type for @code{hpcguix-web}. -@end defvr - -@deftp {Data Type} hpcguix-web-configuration -Data type for the hpcguix-web service configuration. - -@table @asis -@item @code{specs} -A gexp (@pxref{G-Expressions}) specifying the hpcguix-web service -configuration. The main items available in this spec are: - -@table @asis -@item @code{title-prefix} (default: @code{"hpcguix | "}) -The page title prefix. - -@item @code{guix-command} (default: @code{"guix"}) -The @command{guix} command. - -@item @code{package-filter-proc} (default: @code{(const #t)}) -A procedure specifying how to filter packages that are displayed. - -@item @code{package-page-extension-proc} (default: @code{(const '())}) -Extension package for @code{hpcguix-web}. - -@item @code{menu} (default: @code{'()}) -Additional entry in page @code{menu}. - -@item @code{channels} (default: @code{%default-channels}) -List of channels from which the package list is built (@pxref{Channels}). - -@item @code{package-list-expiration} (default: @code{(* 12 3600)}) -The expiration time, in seconds, after which the package list is rebuilt -from the latest instances of the given channels. -@end table - -See the hpcguix-web repository for a -@uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm, -complete example}. - -@item @code{package} (default: @code{hpcguix-web}) -The hpcguix-web package to use. -@end table -@end deftp - -A typical hpcguix-web service declaration looks like this: - -@example -(service hpcguix-web-service-type - (hpcguix-web-configuration - (specs - #~(define site-config - (hpcweb-configuration - (title-prefix "Guix-HPC - ") - (menu '(("/about" "ABOUT")))))))) -@end example - -@quotation Note -The hpcguix-web service periodically updates the package list it publishes -by pulling channels from Git. To that end, it needs to access X.509 -certificates so that it can authenticate Git servers when communicating over -HTTPS, and it assumes that @file{/etc/ssl/certs} contains those -certificates. - -Thus, make sure to add @code{nss-certs} or another certificate package to -the @code{packages} field of your configuration. @ref{X.509 Certificates}, -for more information on X.509 certificates. -@end quotation - -@node Certificate Services -@subsection Certificate Services - -@cindex Web -@cindex HTTP, HTTPS -@cindex Let's Encrypt -@cindex TLS certificates -The @code{(gnu services certbot)} module provides a service to automatically -obtain a valid TLS certificate from the Let's Encrypt certificate -authority. These certificates can then be used to serve content securely -over HTTPS or other TLS-based protocols, with the knowledge that the client -will be able to verify the server's authenticity. - -@url{https://letsencrypt.org/, Let's Encrypt} provides the @code{certbot} -tool to automate the certification process. This tool first securely -generates a key on the server. It then makes a request to the Let's Encrypt -certificate authority (CA) to sign the key. The CA checks that the request -originates from the host in question by using a challenge-response protocol, -requiring the server to provide its response over HTTP. If that protocol -completes successfully, the CA signs the key, resulting in a certificate. -That certificate is valid for a limited period of time, and therefore to -continue to provide TLS services, the server needs to periodically ask the -CA to renew its signature. - -The certbot service automates this process: the initial key generation, the -initial certification request to the Let's Encrypt service, the web server -challenge/response integration, writing the certificate to disk, the -automated periodic renewals, and the deployment tasks associated with the -renewal (e.g.@: reloading services, copying keys with different -permissions). - -Certbot is run twice a day, at a random minute within the hour. It won't do -anything until your certificates are due for renewal or revoked, but running -it regularly would give your service a chance of staying online in case a -Let's Encrypt-initiated revocation happened for some reason. - -By using this service, you agree to the ACME Subscriber Agreement, which can -be found there: @url{https://acme-v01.api.letsencrypt.org/directory}. - -@defvr {Scheme Variable} certbot-service-type -A service type for the @code{certbot} Let's Encrypt client. Its value must -be a @code{certbot-configuration} record as in this example: - -@example -(define %nginx-deploy-hook - (program-file - "nginx-deploy-hook" - #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read))) - (kill pid SIGHUP)))) - -(service certbot-service-type - (certbot-configuration - (email "foo@@example.net") - (certificates - (list - (certificate-configuration - (domains '("example.net" "www.example.net")) - (deploy-hook %nginx-deploy-hook)) - (certificate-configuration - (domains '("bar.example.net"))))))) -@end example - -See below for details about @code{certbot-configuration}. -@end defvr - -@deftp {Data Type} certbot-configuration -Data type representing the configuration of the @code{certbot} service. -This type has the following parameters: - -@table @asis -@item @code{package} (default: @code{certbot}) -The certbot package to use. - -@item @code{webroot} (default: @code{/var/www}) -The directory from which to serve the Let's Encrypt challenge/response -files. - -@item @code{certificates} (default: @code{()}) -A list of @code{certificates-configuration}s for which to generate -certificates and request signatures. Each certificate has a @code{name} and -several @code{domains}. - -@item @code{email} -Mandatory email used for registration, recovery contact, and important -account notifications. - -@item @code{rsa-key-size} (default: @code{2048}) -Size of the RSA key. - -@item @code{default-location} (default: @i{see below}) -The default @code{nginx-location-configuration}. Because @code{certbot} -needs to be able to serve challenges and responses, it needs to be able to -run a web server. It does so by extending the @code{nginx} web service with -an @code{nginx-server-configuration} listening on the @var{domains} on port -80, and which has a @code{nginx-location-configuration} for the -@code{/.well-known/} URI path subspace used by Let's Encrypt. @xref{Web -Services}, for more on these nginx configuration data types. - -Requests to other URL paths will be matched by the @code{default-location}, -which if present is added to all @code{nginx-server-configuration}s. - -By default, the @code{default-location} will issue a redirect from -@code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving -you to define what to serve on your site via @code{https}. - -Pass @code{#f} to not issue a default location. -@end table -@end deftp - -@deftp {Data Type} certificate-configuration -Data type representing the configuration of a certificate. This type has -the following parameters: - -@table @asis -@item @code{name} (default: @i{see below}) -This name is used by Certbot for housekeeping and in file paths; it doesn't -affect the content of the certificate itself. To see certificate names, run -@code{certbot certificates}. - -Its default is the first provided domain. - -@item @code{domains} (default: @code{()}) -The first domain provided will be the subject CN of the certificate, and all -domains will be Subject Alternative Names on the certificate. - -@item @code{deploy-hook} (default: @code{#f}) -Command to be run in a shell once for each successfully issued certificate. -For this command, the shell variable @code{$RENEWED_LINEAGE} will point to -the config live subdirectory (for example, -@samp{"/etc/letsencrypt/live/example.com"}) containing the new certificates -and keys; the shell variable @code{$RENEWED_DOMAINS} will contain a -space-delimited list of renewed certificate domains (for example, -@samp{"example.com www.example.com"}. - -@end table -@end deftp - -For each @code{certificate-configuration}, the certificate is saved to -@code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is saved -to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}. -@node DNS Services -@subsection DNS Services -@cindex DNS (domain name system) -@cindex domain name system (DNS) - -The @code{(gnu services dns)} module provides services related to the -@dfn{domain name system} (DNS). It provides a server service for hosting an -@emph{authoritative} DNS server for multiple zones, slave or master. This -service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a caching -and forwarding DNS server for the LAN, which uses -@uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}. - -@subsubheading Knot Service - -An example configuration of an authoritative server for two zones, one -master and one slave, is: - -@lisp -(define-zone-entries example.org.zone -;; Name TTL Class Type Data - ("@@" "" "IN" "A" "127.0.0.1") - ("@@" "" "IN" "NS" "ns") - ("ns" "" "IN" "A" "127.0.0.1")) - -(define master-zone - (knot-zone-configuration - (domain "example.org") - (zone (zone-file - (origin "example.org") - (entries example.org.zone))))) - -(define slave-zone - (knot-zone-configuration - (domain "plop.org") - (dnssec-policy "default") - (master (list "plop-master")))) - -(define plop-master - (knot-remote-configuration - (id "plop-master") - (address (list "208.76.58.171")))) - -(operating-system - ;; ... - (services (cons* (service knot-service-type - (knot-configuration - (remotes (list plop-master)) - (zones (list master-zone slave-zone)))) - ;; ... - %base-services))) -@end lisp - -@deffn {Scheme Variable} knot-service-type -This is the type for the Knot DNS server. - -Knot DNS is an authoritative DNS server, meaning that it can serve multiple -zones, that is to say domain names you would buy from a registrar. This -server is not a resolver, meaning that it can only resolve names for which -it is authoritative. This server can be configured to serve zones as a -master server or a slave server as a per-zone basis. Slave zones will get -their data from masters, and will serve it as an authoritative server. From -the point of view of a resolver, there is no difference between master and -slave. - -The following data types are used to configure the Knot DNS server: -@end deffn - -@deftp {Data Type} knot-key-configuration -Data type representing a key. This type has the following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for other configuration fields to refer to this key. IDs must -be unique and must not be empty. - -@item @code{algorithm} (default: @code{#f}) -The algorithm to use. Choose between @code{#f}, @code{'hmac-md5}, -@code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, -@code{'hmac-sha384} and @code{'hmac-sha512}. - -@item @code{secret} (default: @code{""}) -The secret key itself. - -@end table -@end deftp - -@deftp {Data Type} knot-acl-configuration -Data type representing an Access Control List (ACL) configuration. This -type has the following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for ether configuration fields to refer to this key. IDs must -be unique and must not be empty. - -@item @code{address} (default: @code{'()}) -An ordered list of IP addresses, network subnets, or network ranges -represented with strings. The query must match one of them. Empty value -means that address match is not required. - -@item @code{key} (default: @code{'()}) -An ordered list of references to keys represented with strings. The string -must match a key ID defined in a @code{knot-key-configuration}. No key -means that a key is not require to match that ACL. - -@item @code{action} (default: @code{'()}) -An ordered list of actions that are permitted or forbidden by this ACL. -Possible values are lists of zero or more elements from @code{'transfer}, -@code{'notify} and @code{'update}. - -@item @code{deny?} (default: @code{#f}) -When true, the ACL defines restrictions. Listed actions are forbidden. -When false, listed actions are allowed. - -@end table -@end deftp - -@deftp {Data Type} zone-entry -Data type represnting a record entry in a zone file. This type has the -following parameters: - -@table @asis -@item @code{name} (default: @code{"@@"}) -The name of the record. @code{"@@"} refers to the origin of the zone. -Names are relative to the origin of the zone. For example, in the -@code{example.org} zone, @code{"ns.example.org"} actually refers to -@code{ns.example.org.example.org}. Names ending with a dot are absolute, -which means that @code{"ns.example.org."} refers to @code{ns.example.org}. - -@item @code{ttl} (default: @code{""}) -The Time-To-Live (TTL) of this record. If not set, the default TTL is used. - -@item @code{class} (default: @code{"IN"}) -The class of the record. Knot currently supports only @code{"IN"} and -partially @code{"CH"}. - -@item @code{type} (default: @code{"A"}) -The type of the record. Common types include A (IPv4 address), AAAA (IPv6 -address), NS (Name Server) and MX (Mail eXchange). Many other types are -defined. - -@item @code{data} (default: @code{""}) -The data contained in the record. For instance an IP address associated -with an A record, or a domain name associated with an NS record. Remember -that domain names are relative to the origin unless they end with a dot. - -@end table -@end deftp - -@deftp {Data Type} zone-file -Data type representing the content of a zone file. This type has the -following parameters: - -@table @asis -@item @code{entries} (default: @code{'()}) -The list of entries. The SOA record is taken care of, so you don't need to -put it in the list of entries. This list should probably contain an entry -for your primary authoritative DNS server. Other than using a list of -entries directly, you can use @code{define-zone-entries} to define a object -containing the list of entries more easily, that you can later pass to the -@code{entries} field of the @code{zone-file}. - -@item @code{origin} (default: @code{""}) -The name of your zone. This parameter cannot be empty. - -@item @code{ns} (default: @code{"ns"}) -The domain of your primary authoritative DNS server. The name is relative -to the origin, unless it ends with a dot. It is mandatory that this primary -DNS server corresponds to an NS record in the zone and that it is associated -to an IP address in the list of entries. - -@item @code{mail} (default: @code{"hostmaster"}) -An email address people can contact you at, as the owner of the zone. This -is translated as @code{<mail>@@<origin>}. - -@item @code{serial} (default: @code{1}) -The serial number of the zone. As this is used to keep track of changes by -both slaves and resolvers, it is mandatory that it @emph{never} decreases. -Always increment it when you make a change in your zone. - -@item @code{refresh} (default: @code{(* 2 24 3600)}) -The frequency at which slaves will do a zone transfer. This value is a -number of seconds. It can be computed by multiplications or with -@code{(string->duration)}. - -@item @code{retry} (default: @code{(* 15 60)}) -The period after which a slave will retry to contact its master when it -fails to do so a first time. - -@item @code{expiry} (default: @code{(* 14 24 3600)}) -Default TTL of records. Existing records are considered correct for at most -this amount of time. After this period, resolvers will invalidate their -cache and check again that it still exists. - -@item @code{nx} (default: @code{3600}) -Default TTL of inexistant records. This delay is usually short because you -want your new domains to reach everyone quickly. - -@end table -@end deftp - -@deftp {Data Type} knot-remote-configuration -Data type representing a remote configuration. This type has the following -parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for other configuration fields to refer to this remote. IDs -must be unique and must not be empty. - -@item @code{address} (default: @code{'()}) -An ordered list of destination IP addresses. Addresses are tried in -sequence. An optional port can be given with the @@ separator. For -instance: @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53. - -@item @code{via} (default: @code{'()}) -An ordered list of source IP addresses. An empty list will have Knot choose -an appropriate source IP. An optional port can be given with the @@ -separator. The default is to choose at random. - -@item @code{key} (default: @code{#f}) -A reference to a key, that is a string containing the identifier of a key -defined in a @code{knot-key-configuration} field. - -@end table -@end deftp - -@deftp {Data Type} knot-keystore-configuration -Data type representing a keystore to hold dnssec keys. This type has the -following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -The id of the keystore. It must not be empty. - -@item @code{backend} (default: @code{'pem}) -The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}. - -@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 file system. - -@end table -@end deftp - -@deftp {Data Type} knot-policy-configuration -Data type representing a dnssec policy. Knot DNS is able to automatically -sign your zones. It can either generate and manage your keys automatically -or use keys that you generate. - -Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that -is used to sign the second, and a Zone Signing Key (ZSK) that is used to -sign the zone. In order to be trusted, the KSK needs to be present in the -parent zone (usually a top-level domain). If your registrar supports -dnssec, you will have to send them your KSK's hash so they can add a DS -record in their zone. This is not automated and need to be done each time -you change your KSK. - -The policy also defines the lifetime of keys. Usually, ZSK can be changed -easily and use weaker cryptographic functions (they use lower parameters) in -order to sign records quickly, so they are changed often. The KSK however -requires manual interaction with the registrar, so they are changed less -often and use stronger parameters because they sign only one record. - -This type has the following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -The id of the policy. It must not be empty. - -@item @code{keystore} (default: @code{"default"}) -A reference to a keystore, that is a string containing the identifier of a -keystore defined in a @code{knot-keystore-configuration} field. The -@code{"default"} identifier means the default keystore (a kasp database that -was setup by this service). - -@item @code{manual?} (default: @code{#f}) -Whether the key management is manual or automatic. - -@item @code{single-type-signing?} (default: @code{#f}) -When @code{#t}, use the Single-Type Signing Scheme. - -@item @code{algorithm} (default: @code{"ecdsap256sha256"}) -An algorithm of signing keys and issued signatures. - -@item @code{ksk-size} (default: @code{256}) -The length of the KSK. Note that this value is correct for the default -algorithm, but would be unsecure for other algorithms. - -@item @code{zsk-size} (default: @code{256}) -The length of the ZSK. Note that this value is correct for the default -algorithm, but would be unsecure for other algorithms. - -@item @code{dnskey-ttl} (default: @code{'default}) -The TTL value for DNSKEY records added into zone apex. The special -@code{'default} value means same as the zone SOA TTL. - -@item @code{zsk-lifetime} (default: @code{(* 30 24 3600)}) -The period between ZSK publication and the next rollover initiation. - -@item @code{propagation-delay} (default: @code{(* 24 3600)}) -An extra delay added for each key rollover step. This value should be high -enough to cover propagation of data from the master server to all slaves. - -@item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)}) -A validity period of newly issued signatures. - -@item @code{rrsig-refresh} (default: @code{(* 7 24 3600)}) -A period how long before a signature expiration the signature will be -refreshed. - -@item @code{nsec3?} (default: @code{#f}) -When @code{#t}, NSEC3 will be used instead of NSEC. - -@item @code{nsec3-iterations} (default: @code{5}) -The number of additional times the hashing is performed. - -@item @code{nsec3-salt-length} (default: @code{8}) -The length of a salt field in octets, which is appended to the original -owner name before hashing. - -@item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)}) -The validity period of newly issued salt field. - -@end table -@end deftp - -@deftp {Data Type} knot-zone-configuration -Data type representing a zone served by Knot. This type has the following -parameters: - -@table @asis -@item @code{domain} (default: @code{""}) -The domain served by this configuration. It must not be empty. - -@item @code{file} (default: @code{""}) -The file where this zone is saved. This parameter is ignored by master -zones. Empty means default location that depends on the domain name. - -@item @code{zone} (default: @code{(zone-file)}) -The content of the zone file. This parameter is ignored by slave zones. It -must contain a zone-file record. - -@item @code{master} (default: @code{'()}) -A list of master remotes. When empty, this zone is a master. When set, -this zone is a slave. This is a list of remotes identifiers. - -@item @code{ddns-master} (default: @code{#f}) -The main master. When empty, it defaults to the first master in the list of -masters. - -@item @code{notify} (default: @code{'()}) -A list of slave remote identifiers. - -@item @code{acl} (default: @code{'()}) -A list of acl identifiers. - -@item @code{semantic-checks?} (default: @code{#f}) -When set, this adds more semantic checks to the zone. - -@item @code{disable-any?} (default: @code{#f}) -When set, this forbids queries of the ANY type. - -@item @code{zonefile-sync} (default: @code{0}) -The delay between a modification in memory and on disk. 0 means immediate -synchronization. - -@item @code{serial-policy} (default: @code{'increment}) -A policy between @code{'increment} and @code{'unixtime}. - -@end table -@end deftp - -@deftp {Data Type} knot-configuration -Data type representing the Knot configuration. This type has the following -parameters: - -@table @asis -@item @code{knot} (default: @code{knot}) -The Knot package. - -@item @code{run-directory} (default: @code{"/var/run/knot"}) -The run directory. This directory will be used for pid file and sockets. - -@item @code{listen-v4} (default: @code{"0.0.0.0"}) -An ip address on which to listen. - -@item @code{listen-v6} (default: @code{"::"}) -An ip address on which to listen. - -@item @code{listen-port} (default: @code{53}) -A port on which to listen. - -@item @code{keys} (default: @code{'()}) -The list of knot-key-configuration used by this configuration. - -@item @code{acls} (default: @code{'()}) -The list of knot-acl-configuration used by this configuration. - -@item @code{remotes} (default: @code{'()}) -The list of knot-remote-configuration used by this configuration. - -@item @code{zones} (default: @code{'()}) -The list of knot-zone-configuration used by this configuration. - -@end table -@end deftp - -@subsubheading Dnsmasq Service - -@deffn {Scheme Variable} dnsmasq-service-type -This is the type of the dnsmasq service, whose value should be an -@code{dnsmasq-configuration} object as in this example: - -@example -(service dnsmasq-service-type - (dnsmasq-configuration - (no-resolv? #t) - (servers '("192.168.1.1")))) -@end example -@end deffn - -@deftp {Data Type} dnsmasq-configuration -Data type representing the configuration of dnsmasq. - -@table @asis -@item @code{package} (default: @var{dnsmasq}) -Package object of the dnsmasq server. - -@item @code{no-hosts?} (default: @code{#f}) -When true, don't read the hostnames in /etc/hosts. - -@item @code{port} (default: @code{53}) -The port to listen on. Setting this to zero completely disables DNS -responses, leaving only DHCP and/or TFTP functions. - -@item @code{local-service?} (default: @code{#t}) -Accept DNS queries only from hosts whose address is on a local subnet, ie a -subnet for which an interface exists on the server. - -@item @code{listen-addresses} (default: @code{'()}) -Listen on the given IP addresses. - -@item @code{resolv-file} (default: @code{"/etc/resolv.conf"}) -The file to read the IP address of the upstream nameservers from. - -@item @code{no-resolv?} (default: @code{#f}) -When true, don't read @var{resolv-file}. - -@item @code{servers} (default: @code{'()}) -Specify IP address of upstream servers directly. - -@item @code{cache-size} (default: @code{150}) -Set the size of dnsmasq's cache. Setting the cache size to zero disables -caching. - -@item @code{negative-cache?} (default: @code{#t}) -When false, disable negative caching. - -@end table -@end deftp - -@subsubheading ddclient Service - -@cindex ddclient -The ddclient service described below runs the ddclient daemon, which takes -care of automatically updating DNS entries for service providers such as -@uref{https://dyn.com/dns/, Dyn}. - -The following example show instantiates the service with its default -configuration: - -@example -(service ddclient-service-type) -@end example - -Note that ddclient needs to access credentials that are stored in a -@dfn{secret file}, by default @file{/etc/ddclient/secrets} (see -@code{secret-file} below.) You are expected to create this file manually, -in an ``out-of-band'' fashion (you @emph{could} make this file part of the -service configuration, for instance by using @code{plain-file}, but it will -be world-readable @i{via} @file{/gnu/store}.) See the examples in the -@file{share/ddclient} directory of the @code{ddclient} package. - -@c %start of fragment - -Available @code{ddclient-configuration} fields are: - -@deftypevr {@code{ddclient-configuration} parameter} package ddclient -The ddclient package. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} integer daemon -The period after which ddclient will retry to check IP and domain name. - -Defaults to @samp{300}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} boolean syslog -Use syslog for the output. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string mail -Mail to user. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string mail-failure -Mail failed update to user. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string pid -The ddclient PID file. - -Defaults to @samp{"/var/run/ddclient/ddclient.pid"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} boolean ssl -Enable SSL support. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string user -Specifies the user name or ID that is used when running ddclient program. - -Defaults to @samp{"ddclient"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string group -Group of the user who will run the ddclient program. - -Defaults to @samp{"ddclient"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string secret-file -Secret file which will be appended to @file{ddclient.conf} file. This file -contains credentials for use by ddclient. You are expected to create it -manually. - -Defaults to @samp{"/etc/ddclient/secrets.conf"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} list extra-options -Extra options will be appended to @file{ddclient.conf} file. - -Defaults to @samp{()}. - -@end deftypevr - - -@c %end of fragment - - -@node VPN Services -@subsection VPN Services -@cindex VPN (virtual private network) -@cindex virtual private network (VPN) - -The @code{(gnu services vpn)} module provides services related to -@dfn{virtual private networks} (VPNs). It provides a @emph{client} service -for your machine to connect to a VPN, and a @emph{servire} service for your -machine to host a VPN. Both services use @uref{https://openvpn.net/, -OpenVPN}. - -@deffn {Scheme Procedure} openvpn-client-service @ - [#:config (openvpn-client-configuration)] - -Return a service that runs @command{openvpn}, a VPN daemon, as a client. -@end deffn - -@deffn {Scheme Procedure} openvpn-server-service @ - [#:config (openvpn-server-configuration)] - -Return a service that runs @command{openvpn}, a VPN daemon, as a server. - -Both can be run simultaneously. -@end deffn - -@c %automatically generated documentation - -Available @code{openvpn-client-configuration} fields are: - -@deftypevr {@code{openvpn-client-configuration} parameter} package openvpn -The OpenVPN package. - -@end deftypevr - -@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 -The protocol (UDP or TCP) used to open a channel between clients and -servers. - -Defaults to @samp{udp}. - -@end deftypevr - -@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 -The certificate authority to check connections against. - -Defaults to @samp{"/etc/openvpn/ca.crt"}. - -@end deftypevr - -@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}. - -Defaults to @samp{"/etc/openvpn/client.crt"}. - -@end deftypevr - -@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}. - -Defaults to @samp{"/etc/openvpn/client.key"}. - -@end deftypevr - -@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? -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? -Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 -or --ping-restart restarts. - -Defaults to @samp{#t}. - -@end deftypevr - -@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 -Add an additional layer of HMAC authentication on top of the TLS control -channel to protect against DoS attacks. - -Defaults to @samp{#f}. - -@end deftypevr - -@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? -Bind to a specific local port number. - -Defaults to @samp{#f}. - -@end deftypevr - -@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 -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 -Server name. - -Defaults to @samp{"my-server"}. - -@end deftypevr - -@deftypevr {@code{openvpn-remote-configuration} parameter} number port -Port number the server listens to. - -Defaults to @samp{1194}. - -@end deftypevr - -@end deftypevr -@c %end of automatic openvpn-client documentation - -@c %automatically generated documentation - -Available @code{openvpn-server-configuration} fields are: - -@deftypevr {@code{openvpn-server-configuration} parameter} package openvpn -The OpenVPN package. - -@end deftypevr - -@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 -The protocol (UDP or TCP) used to open a channel between clients and -servers. - -Defaults to @samp{udp}. - -@end deftypevr - -@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 -The certificate authority to check connections against. - -Defaults to @samp{"/etc/openvpn/ca.crt"}. - -@end deftypevr - -@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}. - -Defaults to @samp{"/etc/openvpn/client.crt"}. - -@end deftypevr - -@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}. - -Defaults to @samp{"/etc/openvpn/client.key"}. - -@end deftypevr - -@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? -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? -Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 -or --ping-restart restarts. - -Defaults to @samp{#t}. - -@end deftypevr - -@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 -Add an additional layer of HMAC authentication on top of the TLS control -channel to protect against DoS attacks. - -Defaults to @samp{#f}. - -@end deftypevr - -@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 -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 -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 -The Diffie-Hellman parameters file. - -Defaults to @samp{"/etc/openvpn/dh2048.pem"}. - -@end deftypevr - -@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? -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 allowed to talk to each other inside the VPN. - -Defaults to @samp{#f}. - -@end deftypevr - -@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, and -the second element is the timeout before considering the other side down. - -@end deftypevr - -@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 -The status file. This file shows a small report on current connection. 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 -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 -Client name. - -Defaults to @samp{"client"}. - -@end deftypevr - -@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 -Client VPN IP. - -Defaults to @samp{#f}. - -@end deftypevr - -@end deftypevr - - -@c %end of automatic openvpn-server documentation - - -@node Network File System -@subsection Network File System -@cindex NFS - -The @code{(gnu services nfs)} module provides the following services, which -are most commonly used in relation to mounting or exporting directory trees -as @dfn{network file systems} (NFS). - -@subsubheading RPC Bind Service -@cindex rpcbind - -The RPC Bind service provides a facility to map program numbers into -universal addresses. Many NFS related services use this facility. Hence it -is automatically started when a dependent service starts. - -@defvr {Scheme Variable} rpcbind-service-type -A service type for the RPC portmapper daemon. -@end defvr - - -@deftp {Data Type} rpcbind-configuration -Data type representing the configuration of the RPC Bind Service. This type -has the following parameters: -@table @asis -@item @code{rpcbind} (default: @code{rpcbind}) -The rpcbind package to use. - -@item @code{warm-start?} (default: @code{#t}) -If this parameter is @code{#t}, then the daemon will read a state file on -startup thus reloading state information saved by a previous instance. -@end table -@end deftp - - -@subsubheading Pipefs Pseudo File System -@cindex pipefs -@cindex rpc_pipefs - -The pipefs file system is used to transfer NFS related data between the -kernel and user space programs. - -@defvr {Scheme Variable} pipefs-service-type -A service type for the pipefs pseudo file system. -@end defvr - -@deftp {Data Type} pipefs-configuration -Data type representing the configuration of the pipefs pseudo file system -service. This type has the following parameters: -@table @asis -@item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory to which the file system is to be attached. -@end table -@end deftp - - -@subsubheading GSS Daemon Service -@cindex GSSD -@cindex GSS -@cindex global security system - -The @dfn{global security system} (GSS) daemon provides strong security for -RPC based protocols. Before exchanging RPC requests an RPC client must -establish a security context. Typically this is done using the Kerberos -command @command{kinit} or automatically at login time using PAM services -(@pxref{Kerberos Services}). - -@defvr {Scheme Variable} gss-service-type -A service type for the Global Security System (GSS) daemon. -@end defvr - -@deftp {Data Type} gss-configuration -Data type representing the configuration of the GSS daemon service. This -type has the following parameters: -@table @asis -@item @code{nfs-utils} (default: @code{nfs-utils}) -The package in which the @command{rpc.gssd} command is to be found. - -@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory where the pipefs file system is mounted. - -@end table -@end deftp - - -@subsubheading IDMAP Daemon Service -@cindex idmapd -@cindex name mapper - -The idmap daemon service provides mapping between user IDs and user names. -Typically it is required in order to access file systems mounted via NFSv4. - -@defvr {Scheme Variable} idmap-service-type -A service type for the Identity Mapper (IDMAP) daemon. -@end defvr - -@deftp {Data Type} idmap-configuration -Data type representing the configuration of the IDMAP daemon service. This -type has the following parameters: -@table @asis -@item @code{nfs-utils} (default: @code{nfs-utils}) -The package in which the @command{rpc.idmapd} command is to be found. - -@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory where the pipefs file system is mounted. - -@item @code{domain} (default: @code{#f}) -The local NFSv4 domain name. This must be a string or @code{#f}. If it is -@code{#f} then the daemon will use the host's fully qualified domain name. - -@end table -@end deftp - -@node Continuous Integration -@subsection Continuous Integration - -@cindex continuous integration -@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a -continuous integration tool for Guix. It can be used both for development -and for providing substitutes to others (@pxref{Substitutes}). - -The @code{(gnu services cuirass)} module provides the following service. - -@defvr {Scheme Procedure} cuirass-service-type -The type of the Cuirass service. Its value must be a -@code{cuirass-configuration} object, as described below. -@end defvr - -To add build jobs, you have to set the @code{specifications} field of the -configuration. Here is an example of a service that polls the Guix -repository and builds the packages from a manifest. Some of the packages -are defined in the @code{"custom-packages"} input, which is the equivalent -of @code{GUIX_PACKAGE_PATH}. - -@example -(define %cuirass-specs - #~(list - '((#:name . "my-manifest") - (#:load-path-inputs . ("guix")) - (#:package-path-inputs . ("custom-packages")) - (#:proc-input . "guix") - (#:proc-file . "build-aux/cuirass/gnu-system.scm") - (#:proc . cuirass-jobs) - (#:proc-args . ((subset . "manifests") - (systems . ("x86_64-linux")) - (manifests . (("config" . "guix/manifest.scm"))))) - (#:inputs . (((#:name . "guix") - (#:url . "git://git.savannah.gnu.org/guix.git") - (#:load-path . ".") - (#:branch . "master") - (#:no-compile? . #t)) - ((#:name . "config") - (#:url . "git://git.example.org/config.git") - (#:load-path . ".") - (#:branch . "master") - (#:no-compile? . #t)) - ((#:name . "custom-packages") - (#:url . "git://git.example.org/custom-packages.git") - (#:load-path . ".") - (#:branch . "master") - (#:no-compile? . #t))))))) - -(service cuirass-service-type - (cuirass-configuration - (specifications %cuirass-specs))) -@end example - -While information related to build jobs is located directly in the -specifications, global settings for the @command{cuirass} process are -accessible in other @code{cuirass-configuration} fields. - -@deftp {Data Type} cuirass-configuration -Data type representing the configuration of Cuirass. - -@table @asis -@item @code{log-file} (default: @code{"/var/log/cuirass.log"}) -Location of the log file. - -@item @code{cache-directory} (default: @code{"/var/cache/cuirass"}) -Location of the repository cache. - -@item @code{user} (default: @code{"cuirass"}) -Owner of the @code{cuirass} process. - -@item @code{group} (default: @code{"cuirass"}) -Owner's group of the @code{cuirass} process. - -@item @code{interval} (default: @code{60}) -Number of seconds between the poll of the repositories followed by the -Cuirass jobs. - -@item @code{database} (default: @code{"/var/lib/cuirass/cuirass.db"}) -Location of sqlite database which contains the build results and previously -added specifications. - -@item @code{ttl} (default: @code{(* 30 24 3600)}) -Specifies the time-to-live (TTL) in seconds of garbage collector roots that -are registered for build results. This means that build results are -protected from garbage collection for at least @var{ttl} seconds. - -@item @code{port} (default: @code{8081}) -Port number used by the HTTP server. - -@item --listen=@var{host} -Listen on the network interface for @var{host}. The default is to accept -connections from localhost. - -@item @code{specifications} (default: @code{#~'()}) -A gexp (@pxref{G-Expressions}) that evaluates to a list of specifications, -where a specification is an association list (@pxref{Associations Lists,,, -guile, GNU Guile Reference Manual}) whose keys are keywords -(@code{#:keyword-example}) as shown in the example above. - -@item @code{use-substitutes?} (default: @code{#f}) -This allows using substitutes to avoid building every dependencies of a job -from source. - -@item @code{one-shot?} (default: @code{#f}) -Only evaluate specifications and build derivations once. - -@item @code{fallback?} (default: @code{#f}) -When substituting a pre-built binary fails, fall back to building packages -locally. - -@item @code{cuirass} (default: @code{cuirass}) -The Cuirass package to use. -@end table -@end deftp - -@node Power Management Services -@subsection Power Management Services - -@cindex tlp -@cindex power management with TLP -@subsubheading TLP daemon - -The @code{(gnu services pm)} module provides a Guix service definition for -the Linux power management tool TLP. - -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}. - -@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 - -By default TLP does not need much configuration but most TLP parameters can -be tweaked using @code{tlp-configuration}. - -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}. - -@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. - -Available @code{tlp-configuration} fields are: - -@deftypevr {@code{tlp-configuration} parameter} package tlp -The TLP package. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable? -Set to true if you wish to enable TLP. - -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 - -@cindex thermald -@cindex CPU frequency scaling with thermald -@subsubheading Thermald daemon - -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 Audio Services -@subsection Audio Services - -The @code{(gnu services audio)} module provides a service to start MPD (the -Music Player Daemon). - -@cindex mpd -@subsubheading Music Player Daemon - -The Music Player Daemon (MPD) is a service that can play music while being -controlled from the local machine or over the network by a variety of -clients. - -The following example shows how one might run @code{mpd} as user -@code{"bob"} on port @code{6666}. It uses pulseaudio for output. - -@example -(service mpd-service-type - (mpd-configuration - (user "bob") - (port "6666"))) -@end example - -@defvr {Scheme Variable} mpd-service-type -The service type for @command{mpd} -@end defvr - -@deftp {Data Type} mpd-configuration -Data type representing the configuration of @command{mpd}. - -@table @asis -@item @code{user} (default: @code{"mpd"}) -The user to run mpd as. - -@item @code{music-dir} (default: @code{"~/Music"}) -The directory to scan for music files. - -@item @code{playlist-dir} (default: @code{"~/.mpd/playlists"}) -The directory to store playlists. - -@item @code{db-file} (default: @code{"~/.mpd/tag_cache"}) -The location of the music database. - -@item @code{state-file} (default: @code{"~/.mpd/state"}) -The location of the file that stores current MPD's state. - -@item @code{sticker-file} (default: @code{"~/.mpd/sticker.sql"}) -The location of the sticker database. - -@item @code{port} (default: @code{"6600"}) -The port to run mpd on. - -@item @code{address} (default: @code{"any"}) -The address that mpd will bind to. To use a Unix domain socket, an absolute -path can be specified here. - -@end table -@end deftp - -@node Virtualization Services -@subsection Virtualization services - -The @code{(gnu services virtualization)} module provides services for 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 -virtualization management system. This daemon runs on host servers and -performs required management tasks for virtualized guests. - -@deffn {Scheme Variable} libvirt-service-type -This is the type of the @uref{https://libvirt.org, libvirt daemon}. Its -value must be a @code{libvirt-configuration}. - -@example -(service libvirt-service-type - (libvirt-configuration - (unix-sock-group "libvirt") - (tls-port "16555"))) -@end example -@end deffn - -@c Auto-generated with (generate-libvirt-documentation) -Available @code{libvirt-configuration} fields are: - -@deftypevr {@code{libvirt-configuration} parameter} package libvirt -Libvirt package. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls? -Flag listening for secure TLS connections on the public TCP/IP port. must -set @code{listen} for this to have any effect. - -It is necessary to setup a CA and issue server certificates before using -this capability. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp? -Listen for unencrypted TCP connections on the public TCP/IP port. must set -@code{listen} for this to have any effect. - -Using the TCP socket requires SASL authentication by default. Only SASL -mechanisms which support data encryption are allowed. This is DIGEST_MD5 -and GSSAPI (Kerberos5) - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string tls-port -Port for accepting secure TLS connections This can be a port number, or -service name - -Defaults to @samp{"16514"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string tcp-port -Port for accepting insecure TCP connections This can be a port number, or -service name - -Defaults to @samp{"16509"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string listen-addr -IP address or hostname used for client connections. - -Defaults to @samp{"0.0.0.0"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv? -Flag toggling mDNS advertisement of the libvirt service. - -Alternatively can disable for all services on a host by stopping the Avahi -daemon. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string mdns-name -Default mDNS advertisement name. This must be unique on the immediate -broadcast network. - -Defaults to @samp{"Virtualization Host <hostname>"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group -UNIX domain socket group ownership. This can be used to allow a 'trusted' -set of users access to management capabilities without becoming root. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms -UNIX socket permissions for the R/O socket. This is used for monitoring VM -status only. - -Defaults to @samp{"0777"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms -UNIX socket permissions for the R/W socket. Default allows only root. If -PolicyKit is enabled on the socket, the default will change to allow -everyone (eg, 0777) - -Defaults to @samp{"0770"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms -UNIX socket permissions for the admin socket. Default allows only owner -(root), do not change it unless you are sure to whom you are exposing the -access to. - -Defaults to @samp{"0777"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir -The directory in which sockets will be found/created. - -Defaults to @samp{"/var/run/libvirt"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro -Authentication scheme for UNIX read-only sockets. By default socket -permissions allow anyone to connect - -Defaults to @samp{"polkit"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw -Authentication scheme for UNIX read-write sockets. By default socket -permissions only allow root. If PolicyKit support was compiled into -libvirt, the default will be to use 'polkit' auth. - -Defaults to @samp{"polkit"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-tcp -Authentication scheme for TCP sockets. If you don't enable SASL, then all -TCP traffic is cleartext. Don't do this outside of a dev/test scenario. - -Defaults to @samp{"sasl"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-tls -Authentication scheme for TLS sockets. TLS sockets already have encryption -provided by the TLS layer, and limited authentication is done by -certificates. - -It is possible to make use of any SASL authentication mechanism as well, by -using 'sasl' for this option - -Defaults to @samp{"none"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers -API access control scheme. - -By default an authenticated user is allowed access to all APIs. Access -drivers can place restrictions on this. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string key-file -Server key file path. If set to an empty string, then no private key is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string cert-file -Server key file path. If set to an empty string, then no certificate is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string ca-file -Server key file path. If set to an empty string, then no CA certificate is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string crl-file -Certificate revocation list path. If set to an empty string, then no CRL is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert -Disable verification of our own server certificates. - -When libvirtd starts it performs some sanity checks against its own -certificates. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert -Disable verification of client certificates. - -Client certificate verification is the primary authentication mechanism. -Any client which does not present a certificate signed by the CA will be -rejected. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list -Whitelist of allowed x509 Distinguished Name. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames -Whitelist of allowed SASL usernames. The format for username depends on the -SASL authentication mechanism. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string tls-priority -Override the compile time default TLS priority string. The default is -usually "NORMAL" unless overridden at build time. Only set this is it is -desired for libvirt to deviate from the global default settings. - -Defaults to @samp{"NORMAL"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-clients -Maximum number of concurrent client connections to allow over all sockets -combined. - -Defaults to @samp{5000}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients -Maximum length of queue of connections waiting to be accepted by the -daemon. Note, that some protocols supporting retransmission may obey this -so that a later reattempt at connection succeeds. - -Defaults to @samp{1000}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients -Maximum length of queue of accepted but not yet authenticated clients. Set -this to zero to turn this feature off - -Defaults to @samp{20}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer min-workers -Number of workers to start up initially. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-workers -Maximum number of worker threads. - -If the number of active clients exceeds @code{min-workers}, then more -threads are spawned, up to max_workers limit. Typically you'd want -max_workers to equal maximum number of clients allowed. - -Defaults to @samp{20}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer prio-workers -Number of priority workers. If all workers from above pool are stuck, some -calls marked as high priority (notably domainDestroy) can be executed in -this pool. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-requests -Total global limit on concurrent RPC calls. - -Defaults to @samp{20}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests -Limit on concurrent requests from a single client connection. To avoid one -client monopolizing the server this should be a small fraction of the global -max_requests and max_workers parameter. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers -Same as @code{min-workers} but for the admin interface. - -Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers -Same as @code{max-workers} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients -Same as @code{max-clients} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients -Same as @code{max-queued-clients} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests -Same as @code{max-client-requests} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer log-level -Logging level. 4 errors, 3 warnings, 2 information, 1 debug. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string log-filters -Logging filters. - -A filter allows to select a different logging level for a given category of -logs The format for a filter is one of: - -@itemize @bullet -@item -x:name - -@item -x:+name - -@end itemize - -where @code{name} is a string which is matched against the category given in -the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g., -"remote", "qemu", or "util.json" (the name in the filter can be a substring -of the full category name, in order to match multiple similar categories), -the optional "+" prefix tells libvirt to log stack trace for each message -matching name, and @code{x} is the minimal level where matching messages -should be logged: - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple filters can be defined in a single filters statement, they just -need to be separated by spaces. - -Defaults to @samp{"3:remote 4:event"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string log-outputs -Logging outputs. - -An output is one of the places to save logging information The format for an -output can be: - -@table @code -@item x:stderr -output goes to stderr - -@item x:syslog:name -use syslog for the output and use the given name as the ident - -@item x:file:file_path -output to a file, with the given filepath - -@item x:journald -output to journald logging system - -@end table - -In all case the x prefix is the minimal level, acting as a filter - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple outputs can be defined, they just need to be separated by spaces. - -Defaults to @samp{"3:stderr"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer audit-level -Allows usage of the auditing subsystem to be altered - -@itemize @bullet -@item -0: disable all auditing - -@item -1: enable auditing, only if enabled on host - -@item -2: enable auditing, and exit if disabled on host. - -@end itemize - -Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging -Send audit messages via libvirt logging infrastructure. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid -Host UUID. UUID must not have all digits be the same. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source -Source to read host UUID. - -@itemize @bullet -@item -@code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid} - -@item -@code{machine-id}: fetch the UUID from @code{/etc/machine-id} - -@end itemize - -If @code{dmidecode} does not provide a valid UUID a temporary UUID will be -generated. - -Defaults to @samp{"smbios"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval -A keepalive message is sent to a client after @code{keepalive_interval} -seconds of inactivity to check if the client is still responding. If set to --1, libvirtd will never send keepalive requests; however clients can still -send them and the daemon will send responses. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count -Maximum number of keepalive messages that are allowed to be sent to the -client without getting any response before the connection is considered -broken. - -In other words, the connection is automatically closed approximately after -@code{keepalive_interval * (keepalive_count + 1)} seconds since the last -message received from the client. When @code{keepalive-count} is set to 0, -connections will be automatically closed after @code{keepalive-interval} -seconds of inactivity without sending any keepalive messages. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval -Same as above but for admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count -Same as above but for admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout -Timeout for Open vSwitch calls. - -The @code{ovs-vsctl} utility is used for the configuration and its timeout -option is set by default to 5 seconds to avoid potential infinite waits -blocking libvirt. - -Defaults to @samp{5}. - -@end deftypevr - -@c %end of autogenerated docs - -@subsubheading Virtlog daemon -The virtlogd service is a server side daemon component of libvirt that is -used to manage logs from virtual machine consoles. - -This daemon is not used directly by libvirt client applications, rather it -is called on their behalf by @code{libvirtd}. By maintaining the logs in a -standalone daemon, the main @code{libvirtd} daemon can be restarted without -risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec() -itself upon receiving @code{SIGUSR1}, to allow live upgrades without -downtime. - -@deffn {Scheme Variable} virtlog-service-type -This is the type of the virtlog daemon. Its value must be a -@code{virtlog-configuration}. - -@example -(service virtlog-service-type - (virtlog-configuration - (max-clients 1000))) -@end example -@end deffn - -@deftypevr {@code{virtlog-configuration} parameter} integer log-level -Logging level. 4 errors, 3 warnings, 2 information, 1 debug. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} string log-filters -Logging filters. - -A filter allows to select a different logging level for a given category of -logs The format for a filter is one of: - -@itemize @bullet -@item -x:name - -@item -x:+name - -@end itemize - -where @code{name} is a string which is matched against the category given in -the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g., -"remote", "qemu", or "util.json" (the name in the filter can be a substring -of the full category name, in order to match multiple similar categories), -the optional "+" prefix tells libvirt to log stack trace for each message -matching name, and @code{x} is the minimal level where matching messages -should be logged: - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple filters can be defined in a single filters statement, they just -need to be separated by spaces. - -Defaults to @samp{"3:remote 4:event"}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} string log-outputs -Logging outputs. - -An output is one of the places to save logging information The format for an -output can be: - -@table @code -@item x:stderr -output goes to stderr - -@item x:syslog:name -use syslog for the output and use the given name as the ident - -@item x:file:file_path -output to a file, with the given filepath - -@item x:journald -output to journald logging system - -@end table - -In all case the x prefix is the minimal level, acting as a filter - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple outputs can be defined, they just need to be separated by spaces. - -Defaults to @samp{"3:stderr"}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-clients -Maximum number of concurrent client connections to allow over all sockets -combined. - -Defaults to @samp{1024}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-size -Maximum file size before rolling over. - -Defaults to @samp{2MB} - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-backups -Maximum number of backup files to keep. - -Defaults to @samp{3} - -@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" "mips64el")))) -@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 -@subsection Version Control Services - -The @code{(gnu services version-control)} module provides a service to allow -remote access to local Git repositories. There are three options: the -@code{git-daemon-service}, which provides access to repositories via the -@code{git://} unsecured TCP-based protocol, extending the @code{nginx} web -server to proxy some requests to @code{git-http-backend}, or providing a web -interface with @code{cgit-service-type}. - -@deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)] - -Return a service that runs @command{git daemon}, a simple TCP server to -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 -access to exported@footnote{By creating the magic file -"git-daemon-export-ok" in the repository directory.} repositories under -@file{/srv/git}. - -@end deffn - -@deftp {Data Type} git-daemon-configuration -Data type representing the configuration for @code{git-daemon-service}. - -@table @asis -@item @code{package} (default: @var{git}) -Package object of the Git distributed version control system. - -@item @code{export-all?} (default: @var{#f}) -Whether to allow access for all Git repositories, even if they do not have -the @file{git-daemon-export-ok} file. - -@item @code{base-path} (default: @file{/srv/git}) -Whether to remap all the path requests as relative to the given path. If -you run git daemon with @var{(base-path "/srv/git")} on example.com, then if -you later try to pull @code{git://example.com/hello.git}, git daemon will -interpret the path as @code{/srv/git/hello.git}. - -@item @code{user-path} (default: @var{#f}) -Whether to allow @code{~user} notation to be used in requests. When -specified with empty string, requests to @code{git://host/~alice/foo} is -taken as a request to access @code{foo} repository in the home directory of -user @code{alice}. If @var{(user-path "path")} is specified, the same -request is taken as a request to access @code{path/foo} repository in the -home directory of user @code{alice}. - -@item @code{listen} (default: @var{'()}) -Whether to listen on specific IP addresses or hostnames, defaults to all. - -@item @code{port} (default: @var{#f}) -Whether to listen on an alternative port, which defaults to 9418. - -@item @code{whitelist} (default: @var{'()}) -If not empty, only allow access to this list of directories. - -@item @code{extra-options} (default: @var{'()}) -Extra options will be passed to @code{git daemon}, please run @command{man -git-daemon} for more information. - -@end table -@end deftp - -The @code{git://} protocol lacks authentication. When you pull from a -repository fetched via @code{git://}, you don't know that the data you -receive was modified is really coming from the specified host, and you have -your connection is subject to eavesdropping. It's better to use an -authenticated and encrypted transport, such as @code{https}. Although Git -allows you to serve repositories using unsophisticated file-based web -servers, there is a faster protocol implemented by the -@code{git-http-backend} program. This program is the back-end of a proper -Git web service. It is designed to sit behind a FastCGI proxy. @xref{Web -Services}, for more on running the necessary @code{fcgiwrap} daemon. - -Guix has a separate configuration data type for serving Git repositories -over HTTP. - -@deftp {Data Type} git-http-configuration -Data type representing the configuration for @code{git-http-service}. - -@table @asis -@item @code{package} (default: @var{git}) -Package object of the Git distributed version control system. - -@item @code{git-root} (default: @file{/srv/git}) -Directory containing the Git repositories to expose to the world. - -@item @code{export-all?} (default: @var{#f}) -Whether to expose access for all Git repositories in @var{git-root}, even if -they do not have the @file{git-daemon-export-ok} file. - -@item @code{uri-path} (default: @file{/git/}) -Path prefix for Git access. With the default @code{/git/} prefix, this will -map @code{http://@var{server}/git/@var{repo}.git} to -@code{/srv/git/@var{repo}.git}. Requests whose URI paths do not begin with -this prefix are not passed on to this Git instance. - -@item @code{fcgiwrap-socket} (default: @code{127.0.0.1:9000}) -The socket on which the @code{fcgiwrap} daemon is listening. @xref{Web -Services}. -@end table -@end deftp - -There is no @code{git-http-service-type}, currently; instead you can create -an @code{nginx-location-configuration} from a @code{git-http-configuration} -and then add that location to a web server. - -@deffn {Scheme Procedure} git-http-nginx-location-configuration @ - [config=(git-http-configuration)] Compute an -@code{nginx-location-configuration} that corresponds to the given Git http -configuration. An example nginx service definition to serve the default -@file{/srv/git} over HTTPS might be: - -@example -(service nginx-service-type - (nginx-configuration - (server-blocks - (list - (nginx-server-configuration - (listen '("443 ssl")) - (server-name "git.my-host.org") - (ssl-certificate - "/etc/letsencrypt/live/git.my-host.org/fullchain.pem") - (ssl-certificate-key - "/etc/letsencrypt/live/git.my-host.org/privkey.pem") - (locations - (list - (git-http-nginx-location-configuration - (git-http-configuration (uri-path "/")))))))))) -@end example - -This example assumes that you are using Let's Encrypt to get your TLS -certificate. @xref{Certificate Services}. The default @code{certbot} -service will redirect all HTTP traffic on @code{git.my-host.org} to HTTPS. -You will also need to add an @code{fcgiwrap} proxy to your system services. -@xref{Web Services}. -@end deffn - -@subsubheading Cgit Service - -@cindex Cgit service -@cindex Git, web interface -@uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git -repositories written in C. - -The following example will configure the service with default values. By -default, Cgit can be accessed on port 80 (@code{http://localhost:80}). - -@example -(service cgit-service-type) -@end example - -The @code{file-object} type designates either a file-like object -(@pxref{G-Expressions, file-like objects}) or a string. - -@c %start of fragment - -Available @code{cgit-configuration} fields are: - -@deftypevr {@code{cgit-configuration} parameter} package package -The CGIT package. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx -NGINX configuration. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object about-filter -Specifies a command which will be invoked to format the content of about -pages (both top-level and for each repository). - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string agefile -Specifies a path, relative to each repository path, which can be used to -specify the date and time of the youngest commit in the repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object auth-filter -Specifies a command that will be invoked for authenticating repository -access. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string branch-sort -Flag which, when set to @samp{age}, enables date ordering in the branch ref -list, and when set @samp{name} enables ordering by branch name. - -Defaults to @samp{"name"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string cache-root -Path used to store the cgit cache entries. - -Defaults to @samp{"/var/cache/cgit"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of repository pages accessed with a fixed SHA1. - -Defaults to @samp{-1}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of repository pages accessed without a fixed SHA1. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of the repository summary page. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of the repository index page. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl -Number which specifies the time-to-live, in minutes, for the result of -scanning a path for Git repositories. - -Defaults to @samp{15}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of the repository about page. - -Defaults to @samp{15}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of snapshots. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-size -The maximum number of entries in the cgit cache. When set to @samp{0}, -caching is disabled. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort? -Sort items in the repo list case sensitively. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list clone-prefix -List of common prefixes which, when combined with a repository URL, -generates valid clone URLs for the repository. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list clone-url -List of @code{clone-url} templates. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object commit-filter -Command which will be invoked to format commit messages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string commit-sort -Flag which, when set to @samp{date}, enables strict date ordering in the -commit log, and when set to @samp{topo} enables strict topological ordering. - -Defaults to @samp{"git log"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object css -URL which specifies the css document to include in all cgit pages. - -Defaults to @samp{"/share/cgit/cgit.css"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object email-filter -Specifies a command which will be invoked to format names and email address -of committers, authors, and taggers, as represented in various places -throughout the cgit interface. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean embedded? -Flag which, when set to @samp{#t}, will make cgit generate a HTML fragment -suitable for embedding in other HTML pages. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph? -Flag which, when set to @samp{#t}, will make cgit print an ASCII-art commit -history graph to the left of the commit messages in the repository log page. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides? -Flag which, when set to @samp{#t}, allows all filter settings to be -overridden in repository-specific cgitrc files. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links? -Flag which, when set to @samp{#t}, allows users to follow a file in the log -view. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone? -If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git clones. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links? -Flag which, when set to @samp{#t}, will make cgit generate extra links -"summary", "commit", "tree" for each repo in the repository index. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner? -Flag which, when set to @samp{#t}, will make cgit display the owner of each -repo in the repository index. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount? -Flag which, when set to @samp{#t}, will make cgit print the number of -modified files for each commit on the repository log page. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount? -Flag which, when set to @samp{#t}, will make cgit print the number of added -and removed lines for each commit on the repository log page. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches? -Flag which, when set to @code{#t}, will make cgit display remote branches in -the summary and refs views. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links? -Flag which, when set to @code{1}, will make cgit use the subject of the -parent commit as link text when generating links to parent commits in commit -view. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving? -Flag which, when set to @samp{#t}, will make cgit use the subject of the -parent commit as link text when generating links to parent commits in commit -view. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers? -Flag which, when set to @samp{#t}, will make cgit generate linenumber links -for plaintext blobs printed in the tree view. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config? -Flag which, when set to @samp{#f}, will allow cgit to use Git config to set -any repo specific settings. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object favicon -URL used as link to a shortcut icon for cgit. - -Defaults to @samp{"/favicon.ico"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string footer -The content of the file specified with this option will be included verbatim -at the bottom of all pages (i.e.@: it replaces the standard "generated -by..."@: message). - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string head-include -The content of the file specified with this option will be included verbatim -in the HTML HEAD section on all pages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string header -The content of the file specified with this option will be included verbatim -at the top of all pages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object include -Name of a configfile to include before the rest of the current config- file -is parsed. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string index-header -The content of the file specified with this option will be included verbatim -above the repository index. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string index-info -The content of the file specified with this option will be included verbatim -below the heading on the repository index page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean local-time? -Flag which, if set to @samp{#t}, makes cgit print commit and tag times in -the servers timezone. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object logo -URL which specifies the source of an image which will be used as a logo on -all cgit pages. - -Defaults to @samp{"/share/cgit/cgit.png"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string logo-link -URL loaded when clicking on the cgit logo image. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object owner-filter -Command which will be invoked to format the Owner column of the main page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-atom-items -Number of items to display in atom feeds view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-commit-count -Number of entries to list per page in "log" view. - -Defaults to @samp{50}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-message-length -Number of commit message characters to display in "log" view. - -Defaults to @samp{80}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-repo-count -Specifies the number of entries to list per page on the repository index -page. - -Defaults to @samp{50}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length -Specifies the maximum number of repo description characters to display on -the repository index page. - -Defaults to @samp{80}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-blob-size -Specifies the maximum size of a blob to display HTML for in KBytes. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string max-stats -Maximum statistics period. Valid values are @samp{week},@samp{month}, -@samp{quarter} and @samp{year}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype -Mimetype for the specified filename extension. - -Defaults to @samp{((gif "image/gif") (html "text/html") (jpg "image/jpeg") -(jpeg "image/jpeg") (pdf "application/pdf") (png "image/png") (svg -"image/svg+xml"))}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file -Specifies the file to use for automatic mimetype lookup. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string module-link -Text which will be used as the formatstring for a hyperlink when a submodule -is printed in a directory listing. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean nocache? -If set to the value @samp{#t} caching will be disabled. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean noplainemail? -If set to @samp{#t} showing full author email addresses will be disabled. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean noheader? -Flag which, when set to @samp{#t}, will make cgit omit the standard header -on all pages. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} project-list project-list -A list of subdirectories inside of @code{repository-directory}, relative to -it, that should loaded as Git repositories. An empty list means that all -subdirectories will be loaded. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object readme -Text which will be used as default value for @code{cgit-repo-readme}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix? -If set to @code{#t} and @code{repository-directory} is enabled, if any -repositories are found with a suffix of @code{.git}, this suffix will be -removed for the URL and name. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer renamelimit -Maximum number of files to consider when detecting renames. - -Defaults to @samp{-1}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string repository-sort -The way in which repositories in each section are sorted. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} robots-list robots -Text used as content for the @code{robots} meta-tag. - -Defaults to @samp{("noindex" "nofollow")}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-desc -Text printed below the heading on the repository index page. - -Defaults to @samp{"a fast webinterface for the git dscm"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-readme -The content of the file specified with this option will be included verbatim -below thef "about" link on the repository index page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-title -Text printed as heading on the repository index page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path -If set to @samp{#t} and repository-directory is enabled, -repository-directory will recurse into directories whose name starts with a -period. Otherwise, repository-directory will stay away from such -directories, considered as "hidden". Note that this does not apply to the -".git" directory in non-bare repos. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list snapshots -Text which specifies the default set of snapshot formats that cgit generates -links for. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory -Name of the directory to scan for repositories (represents -@code{scan-path}). - -Defaults to @samp{"/srv/git"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string section -The name of the current repository section - all repositories defined after -this option will inherit the current section name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string section-sort -Flag which, when set to @samp{1}, will sort the sections on the repository -listing by name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer section-from-path -A number which, if defined prior to repository-directory, specifies how many -path elements from each repo path to use as a default section name. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs? -If set to @samp{#t} shows side-by-side diffs instead of unidiffs per -default. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object source-filter -Specifies a command which will be invoked to format plaintext blobs in the -tree view. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-branches -Specifies the number of branches to display in the repository "summary" -view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-log -Specifies the number of log entries to display in the repository "summary" -view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-tags -Specifies the number of tags to display in the repository "summary" view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string strict-export -Filename which, if specified, needs to be present within the repository for -cgit to allow access to that repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string virtual-root -URL which, if specified, will be used as root for all cgit links. - -Defaults to @samp{"/"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories -A list of @dfn{cgit-repo} records to use with config. - -Defaults to @samp{()}. - -Available @code{repository-cgit-configuration} fields are: - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots -A mask of snapshot formats for this repo that cgit generates links for, -restricted by the global @code{snapshots} setting. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter -Override the default @code{source-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string url -The relative URL used to access the repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter -Override the default @code{about-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort -Flag which, when set to @samp{age}, enables date ordering in the branch ref -list, and when set to @samp{name} enables ordering by branch name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url -A list of URLs which can be used to clone repo. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter -Override the default @code{commit-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort -Flag which, when set to @samp{date}, enables strict date ordering in the -commit log, and when set to @samp{topo} enables strict topological ordering. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch -The name of the default branch for this repository. If no such branch -exists in the repository, the first branch name (when sorted) is used as -default instead. By default branch pointed to by HEAD, or "master" if there -is no suitable HEAD. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc -The value to show as repository description. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage -The value to show as repository homepage. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter -Override the default @code{email-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph? -A flag which can be used to disable the global setting -@code{enable-commit-graph?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount? -A flag which can be used to disable the global setting -@code{enable-log-filecount?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount? -A flag which can be used to disable the global setting -@code{enable-log-linecount?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches? -Flag which, when set to @code{#t}, will make cgit display remote branches in -the summary and refs views. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links? -A flag which can be used to override the global setting -@code{enable-subject-links?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving? -A flag which can be used to override the global setting -@code{enable-html-serving?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide? -Flag which, when set to @code{#t}, hides the repository from the repository -index. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore? -Flag which, when set to @samp{#t}, ignores the repository. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo -URL which specifies the source of an image which will be used as a logo on -this repo’s pages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link -URL loaded when clicking on the cgit logo image. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter -Override the default @code{owner-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link -Text which will be used as the formatstring for a hyperlink when a submodule -is printed in a directory listing. The arguments for the formatstring are -the path and SHA1 of the submodule commit. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path -Text which will be used as the formatstring for a hyperlink when a submodule -with the specified subdirectory path is printed in a directory listing. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats -Override the default maximum statistics period. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string name -The value to show as repository name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner -A value used to identify the owner of the repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string path -An absolute path to the repository directory. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme -A path (relative to repo) which specifies a file to include verbatim as the -"About" page for this repo. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string section -The name of the current repository section - all repositories defined after -this option will inherit the current section name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options -Extra options will be appended to cgitrc file. - -Defaults to @samp{()}. - -@end deftypevr - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list extra-options -Extra options will be appended to cgitrc file. - -Defaults to @samp{()}. - -@end deftypevr - - -@c %end of fragment - -However, it could be that you just want to get a @code{cgitrc} up and -running. In that case, you can pass an @code{opaque-cgit-configuration} as -a record to @code{cgit-service-type}. As its name indicates, an opaque -configuration does not have easy reflective capabilities. - -Available @code{opaque-cgit-configuration} fields are: - -@deftypevr {@code{opaque-cgit-configuration} parameter} package cgit -The cgit package. -@end deftypevr - -@deftypevr {@code{opaque-cgit-configuration} parameter} string string -The contents of the @code{cgitrc}, as a string. -@end deftypevr - -For example, if your @code{cgitrc} is just the empty string, you could -instantiate a cgit service like this: - -@example -(service cgit-service-type - (opaque-cgit-configuration - (cgitrc ""))) -@end example - -@subsubheading Gitolite Service - -@cindex Gitolite service -@cindex Git, hosting -@uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git -repositories on a central server. - -Gitolite can handle multiple repositories and users, and supports flexible -configuration of the permissions for the users on the repositories. - -The following example will configure Gitolite using the default @code{git} -user, and the provided SSH public key. - -@example -(service gitolite-service-type - (gitolite-configuration - (admin-pubkey (plain-file - "yourname.pub" - "ssh-rsa AAAA... guix@@example.com")))) -@end example - -Gitolite is configured through a special admin repository which you can -clone, for example, if you setup Gitolite on @code{example.com}, you would -run the following command to clone the admin repository. - -@example -git clone git@@example.com:gitolite-admin -@end example - -When the Gitolite service is activated, the provided @code{admin-pubkey} -will be inserted in to the @file{keydir} directory in the gitolite-admin -repository. If this results in a change in the repository, it will be -committed using the message ``gitolite setup by GNU Guix''. - -@deftp {Data Type} gitolite-configuration -Data type representing the configuration for @code{gitolite-service-type}. - -@table @asis -@item @code{package} (default: @var{gitolite}) -Gitolite package to use. - -@item @code{user} (default: @var{git}) -User to use for Gitolite. This will be user that you use when accessing -Gitolite over SSH. - -@item @code{group} (default: @var{git}) -Group to use for Gitolite. - -@item @code{home-directory} (default: @var{"/var/lib/gitolite"}) -Directory in which to store the Gitolite configuration and repositories. - -@item @code{rc-file} (default: @var{(gitolite-rc-file)}) -A ``file-like'' object (@pxref{G-Expressions, file-like objects}), -representing the configuration for Gitolite. - -@item @code{admin-pubkey} (default: @var{#f}) -A ``file-like'' object (@pxref{G-Expressions, file-like objects}) used to -setup Gitolite. This will be inserted in to the @file{keydir} directory -within the gitolite-admin repository. - -To specify the SSH key as a string, use the @code{plain-file} function. - -@example -(plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com") -@end example - -@end table -@end deftp - -@deftp {Data Type} gitolite-rc-file -Data type representing the Gitolite RC file. - -@table @asis -@item @code{umask} (default: @code{#o0077}) -This controls the permissions Gitolite sets on the repositories and their -contents. - -A value like @code{#o0027} will give read access to the group used by -Gitolite (by default: @code{git}). This is necessary when using Gitolite -with software like cgit or gitweb. - -@item @code{git-config-keys} (default: @code{""}) -Gitolite allows you to set git config values using the "config" -keyword. This setting allows control over the config keys to accept. - -@item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))}) -Set the role names allowed to be used by users running the perms command. - -@item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")}) -This setting controls the commands and features to enable within Gitolite. - -@end table -@end deftp - - -@node Game Services -@subsection Game Services - -@subsubheading The Battle for Wesnoth Service -@cindex wesnothd -@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn based -tactical strategy game, with several single player campaigns, and -multiplayer games (both networked and local). - -@defvar {Scheme Variable} wesnothd-service-type -Service type for the wesnothd service. Its value must be a -@code{wesnothd-configuration} object. To run wesnothd in the default -configuration, instantiate it as: - -@example -(service wesnothd-service-type) -@end example -@end defvar - -@deftp {Data Type} wesnothd-configuration -Data type representing the configuration of @command{wesnothd}. - -@table @asis -@item @code{package} (default: @code{wesnoth-server}) -The wesnoth server package to use. - -@item @code{port} (default: @code{15000}) -The port to bind the server to. -@end table -@end deftp - -@node Miscellaneous Services -@subsection Miscellaneous Services - -@cindex fingerprint -@subsubheading Fingerprint Service - -The @code{(gnu services authentication)} module provides a DBus service to -read and identify fingerprints via a fingerprint sensor. - -@defvr {Scheme Variable} fprintd-service-type -The service type for @command{fprintd}, which provides the fingerprint -reading capability. - -@example -(service fprintd-service-type) -@end example -@end defvr - -@cindex sysctl -@subsubheading System Control Service - -The @code{(gnu services sysctl)} provides a service to configure kernel -parameters at boot. - -@defvr {Scheme Variable} sysctl-service-type -The service type for @command{sysctl}, which modifies kernel parameters -under @file{/proc/sys/}. To enable IPv4 forwarding, it can be instantiated -as: - -@example -(service sysctl-service-type - (sysctl-configuration - (settings '(("net.ipv4.ip_forward" . "1"))))) -@end example -@end defvr - -@deftp {Data Type} sysctl-configuration -The data type representing the configuration of @command{sysctl}. - -@table @asis -@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"}) -The @command{sysctl} executable to use. - -@item @code{settings} (default: @code{'()}) -An association list specifies kernel parameters and their values. -@end table -@end deftp - -@cindex pcscd -@subsubheading PC/SC Smart Card Daemon Service - -The @code{(gnu services security-token)} module provides the following -service to run @command{pcscd}, the PC/SC Smart Card Daemon. -@command{pcscd} is the daemon program for pcsc-lite and the MuscleCard -framework. It is a resource manager that coordinates communications with -smart card readers, smart cards and cryptographic tokens that are connected -to the system. - -@defvr {Scheme Variable} pcscd-service-type -Service type for the @command{pcscd} service. Its value must be a -@code{pcscd-configuration} object. To run pcscd in the default -configuration, instantiate it as: - -@example -(service pcscd-service-type) -@end example -@end defvr - -@deftp {Data Type} pcscd-configuration -The data type representing the configuration of @command{pcscd}. - -@table @asis -@item @code{pcsc-lite} (default: @code{pcsc-lite}) -The pcsc-lite package that provides pcscd. -@item @code{usb-drivers} (default: @code{(list ccid)}) -List of packages that provide USB drivers to pcscd. Drivers are expected to -be under @file{pcsc/drivers} in the store directory of the package. -@end table -@end deftp - -@cindex lirc -@subsubheading Lirc Service - -The @code{(gnu services lirc)} module provides the following service. - -@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @ - [#:device #f] [#:driver #f] [#:config-file #f] @ [#:extra-options '()] -Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that -decodes infrared signals from remote controls. - -Optionally, @var{device}, @var{driver} and @var{config-file} (configuration -file name) may be specified. See @command{lircd} manual for details. - -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{lircd}. -@end deffn - -@cindex spice -@subsubheading Spice Service - -The @code{(gnu services spice)} module provides the following service. - -@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent] -Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a -daemon that enables sharing the clipboard with a vm and setting the guest -display resolution when the graphical console window resizes. -@end deffn - -@cindex inputattach -@subsubheading inputattach Service - -@cindex tablet input, for Xorg -@cindex touchscreen input, for Xorg -The @uref{https://linuxwacom.github.io/, inputattach} service allows you to -use input devices such as Wacom tablets, touchscreens, or joysticks with the -Xorg display server. - -@deffn {Scheme Variable} inputattach-service-type -Type of a service that runs @command{inputattach} on a device and dispatches -events from it. -@end deffn - -@deftp {Data Type} inputattach-configuration -@table @asis -@item @code{device-type} (default: @code{"wacom"}) -The type of device to connect to. Run @command{inputattach --help}, from -the @code{inputattach} package, to see the list of supported device types. - -@item @code{device} (default: @code{"/dev/ttyS0"}) -The device file to connect to the device. - -@item @code{log-file} (default: @code{#f}) -If true, this must be the name of a file to log messages to. -@end table -@end deftp - -@subsection Dictionary Services -@cindex dictionary -The @code{(gnu services dict)} module provides the following service: - -@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)] -Return a service that runs the @command{dicod} daemon, an implementation of -DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). - -The optional @var{config} argument specifies the configuration for -@command{dicod}, which should be a @code{<dicod-configuration>} object, by -default it serves the GNU Collaborative International Dictonary of English. - -You can add @command{open localhost} to your @file{~/.dico} file to make -@code{localhost} the default server for @command{dico} client -(@pxref{Initialization File,,, dico, GNU Dico Manual}). -@end deffn - -@deftp {Data Type} dicod-configuration -Data type representing the configuration of dicod. - -@table @asis -@item @code{dico} (default: @var{dico}) -Package object of the GNU Dico dictionary server. - -@item @code{interfaces} (default: @var{'("localhost")}) -This is the list of IP addresses and ports and possibly socket file names to -listen to (@pxref{Server Settings, @code{listen} directive,, dico, GNU Dico -Manual}). - -@item @code{handlers} (default: @var{'()}) -List of @code{<dicod-handler>} objects denoting handlers (module instances). - -@item @code{databases} (default: @var{(list %dicod-database:gcide)}) -List of @code{<dicod-database>} objects denoting dictionaries to be served. -@end table -@end deftp - -@deftp {Data Type} dicod-handler -Data type representing a dictionary handler (module instance). - -@table @asis -@item @code{name} -Name of the handler (module instance). - -@item @code{module} (default: @var{#f}) -Name of the dicod module of the handler (instance). If it is @code{#f}, the -module has the same name as the handler. (@pxref{Modules,,, dico, GNU Dico -Manual}). - -@item @code{options} -List of strings or gexps representing the arguments for the module handler -@end table -@end deftp - -@deftp {Data Type} dicod-database -Data type representing a dictionary database. - -@table @asis -@item @code{name} -Name of the database, will be used in DICT commands. - -@item @code{handler} -Name of the dicod handler (module instance) used by this database -(@pxref{Handlers,,, dico, GNU Dico Manual}). - -@item @code{complex?} (default: @var{#f}) -Whether the database configuration complex. The complex configuration will -need a corresponding @code{<dicod-handler>} object, otherwise not. - -@item @code{options} -List of strings or gexps representing the arguments for the database -(@pxref{Databases,,, dico, GNU Dico Manual}). -@end table -@end deftp - -@defvr {Scheme Variable} %dicod-database:gcide -A @code{<dicod-database>} object serving the GNU Collaborative International -Dictionary of English using the @code{gcide} package. -@end defvr - -The following is an example @code{dicod-service} configuration. - -@example -(dicod-service #:config - (dicod-configuration - (handlers (list (dicod-handler - (name "wordnet") - (module "dictorg") - (options - (list #~(string-append "dbdir=" #$wordnet)))))) - (databases (list (dicod-database - (name "wordnet") - (complex? #t) - (handler "wordnet") - (options '("database=wn"))) - %dicod-database:gcide)))) -@end example - -@cindex Docker -@subsubheading Docker Service - -The @code{(gnu services docker)} module provides the following service. - -@defvr {Scheme Variable} docker-service-type - -This is the type of the service that runs -@url{http://www.docker.com,Docker}, a daemon that can execute application -bundles (sometimes referred to as ``containers'') in isolated environments. - -@end defvr - -@deftp {Data Type} docker-configuration -This is the data type representing the configuration of Docker and -Containerd. - -@table @asis - -@item @code{package} (default: @code{docker}) -The Docker package to use. - -@item @code{containerd} (default: @var{containerd}) -The Containerd package to use. - -@end table -@end deftp - -@node Setuid Programs -@section Setuid Programs - -@cindex setuid programs -Some programs need to run with ``root'' privileges, even when they are -launched by unprivileged users. A notorious example is the @command{passwd} -program, which users can run to change their password, and which needs to -access the @file{/etc/passwd} and @file{/etc/shadow} files---something -normally restricted to root, for obvious security reasons. To address that, -these executables are @dfn{setuid-root}, meaning that they always run with -root privileges (@pxref{How Change Persona,,, libc, The GNU C Library -Reference Manual}, for more info about the setuid mechanism.) - -The store itself @emph{cannot} contain setuid programs: that would be a -security issue since any user on the system can write derivations that -populate the store (@pxref{The Store}). Thus, a different mechanism is -used: instead of changing the setuid bit directly on files that are in the -store, we let the system administrator @emph{declare} which programs should -be setuid root. - -The @code{setuid-programs} field of an @code{operating-system} declaration -contains a list of G-expressions denoting the names of programs to be -setuid-root (@pxref{Using the Configuration System}). For instance, the -@command{passwd} program, which is part of the Shadow package, can be -designated by this G-expression (@pxref{G-Expressions}): - -@example -#~(string-append #$shadow "/bin/passwd") -@end example - -A default set of setuid programs is defined by the @code{%setuid-programs} -variable of the @code{(gnu system)} module. - -@defvr {Scheme Variable} %setuid-programs -A list of G-expressions denoting common programs that are setuid-root. - -The list includes commands such as @command{passwd}, @command{ping}, -@command{su}, and @command{sudo}. -@end defvr - -Under the hood, the actual setuid programs are created in the -@file{/run/setuid-programs} directory at system activation time. The files -in this directory refer to the ``real'' binaries, which are in the store. - -@node X.509 Certificates -@section X.509 Certificates - -@cindex HTTPS, certificates -@cindex X.509 certificates -@cindex TLS -Web servers available over HTTPS (that is, HTTP over the transport-layer -security mechanism, TLS) send client programs an @dfn{X.509 certificate} -that the client can then use to @emph{authenticate} the server. To do that, -clients verify that the server's certificate is signed by a so-called -@dfn{certificate authority} (CA). But to verify the CA's signature, clients -must have first acquired the CA's certificate. - -Web browsers such as GNU@tie{}IceCat include their own set of CA -certificates, such that they are able to verify CA signatures -out-of-the-box. - -However, most other programs that can talk HTTPS---@command{wget}, -@command{git}, @command{w3m}, etc.---need to be told where CA certificates -can be found. - -@cindex @code{nss-certs} -In Guix, this is done by adding a package that provides certificates to the -@code{packages} field of the @code{operating-system} declaration -(@pxref{operating-system Reference}). Guix includes one such package, -@code{nss-certs}, which is a set of CA certificates provided as part of -Mozilla's Network Security Services. - -Note that it is @emph{not} part of @var{%base-packages}, so you need to -explicitly add it. The @file{/etc/ssl/certs} directory, which is where most -applications and libraries look for certificates by default, points to the -certificates installed globally. - -Unprivileged users, including users of Guix on a foreign distro, can also -install their own certificate package in their profile. A number of -environment variables need to be defined so that applications and libraries -know where to find them. Namely, the OpenSSL library honors the -@code{SSL_CERT_DIR} and @code{SSL_CERT_FILE} variables. Some applications -add their own environment variables; for instance, the Git version control -system honors the certificate bundle pointed to by the @code{GIT_SSL_CAINFO} -environment variable. Thus, you would typically run something like: - -@example -$ guix package -i nss-certs -$ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs" -$ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -$ export GIT_SSL_CAINFO="$SSL_CERT_FILE" -@end example - -As another example, R requires the @code{CURL_CA_BUNDLE} environment -variable to point to a certificate bundle, so you would have to run -something like this: - -@example -$ guix package -i nss-certs -$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -@end example - -For other applications you may want to look up the required environment -variable in the relevant documentation. - - -@node Name Service Switch -@section Name Service Switch - -@cindex name service switch -@cindex NSS -The @code{(gnu system nss)} module provides bindings to the configuration -file of the libc @dfn{name service switch} or @dfn{NSS} (@pxref{NSS -Configuration File,,, libc, The GNU C Library Reference Manual}). In a -nutshell, the NSS is a mechanism that allows libc to be extended with new -``name'' lookup methods for system databases, which includes host names, -service names, user accounts, and more (@pxref{Name Service Switch, System -Databases and Name Service Switch,, libc, The GNU C Library Reference -Manual}). - -The NSS configuration specifies, for each system database, which lookup -method is to be used, and how the various methods are chained together---for -instance, under which circumstances NSS should try the next method in the -list. The NSS configuration is given in the @code{name-service-switch} -field of @code{operating-system} declarations (@pxref{operating-system -Reference, @code{name-service-switch}}). - -@cindex nss-mdns -@cindex .local, host name lookup -As an example, the declaration below configures the NSS to use the -@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns} -back-end}, which supports host name lookups over multicast DNS (mDNS) for -host names ending in @code{.local}: - -@example -(name-service-switch - (hosts (list %files ;first, check /etc/hosts - - ;; If the above did not succeed, try - ;; with 'mdns_minimal'. - (name-service - (name "mdns_minimal") - - ;; 'mdns_minimal' is authoritative for - ;; '.local'. When it returns "not found", - ;; no need to try the next methods. - (reaction (lookup-specification - (not-found => return)))) - - ;; Then fall back to DNS. - (name-service - (name "dns")) - - ;; Finally, try with the "full" 'mdns'. - (name-service - (name "mdns"))))) -@end example - -Do not worry: the @code{%mdns-host-lookup-nss} variable (see below) -contains this configuration, so you will not have to type it if all you want -is to have @code{.local} host lookup working. - -Note that, in this case, in addition to setting the -@code{name-service-switch} of the @code{operating-system} declaration, you -also need to use @code{avahi-service-type} (@pxref{Networking Services, -@code{avahi-service-type}}), or @var{%desktop-services}, which includes it -(@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible to -the name service cache daemon (@pxref{Base Services, @code{nscd-service}}). - -For convenience, the following variables provide typical NSS configurations. - -@defvr {Scheme Variable} %default-nss -This is the default name service switch configuration, a -@code{name-service-switch} object. -@end defvr - -@defvr {Scheme Variable} %mdns-host-lookup-nss -This is the name service switch configuration with support for host name -lookup over multicast DNS (mDNS) for host names ending in @code{.local}. -@end defvr - -The reference for name service switch configuration is given below. It is a -direct mapping of the configuration file format of the C library , so please -refer to the C library manual for more information (@pxref{NSS Configuration -File,,, libc, The GNU C Library Reference Manual}). Compared to the -configuration file format of libc NSS, it has the advantage not only of -adding this warm parenthetic feel that we like, but also static checks: you -will know about syntax errors and typos as soon as you run @command{guix -system}. - -@deftp {Data Type} name-service-switch - -This is the data type representation the configuration of libc's name -service switch (NSS). Each field below represents one of the supported -system databases. - -@table @code -@item aliases -@itemx ethers -@itemx group -@itemx gshadow -@itemx hosts -@itemx initgroups -@itemx netgroup -@itemx networks -@itemx password -@itemx public-key -@itemx rpc -@itemx services -@itemx shadow -The system databases handled by the NSS. Each of these fields must be a -list of @code{<name-service>} objects (see below). -@end table -@end deftp - -@deftp {Data Type} name-service - -This is the data type representing an actual name service and the associated -lookup action. - -@table @code -@item name -A string denoting the name service (@pxref{Services in the NSS -configuration,,, libc, The GNU C Library Reference Manual}). - -Note that name services listed here must be visible to nscd. This is -achieved by passing the @code{#:name-services} argument to -@code{nscd-service} the list of packages providing the needed name services -(@pxref{Base Services, @code{nscd-service}}). - -@item reaction -An action specified using the @code{lookup-specification} macro -(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library -Reference Manual}). For example: - -@example -(lookup-specification (unavailable => continue) - (success => return)) -@end example -@end table -@end deftp - -@node Initial RAM Disk -@section Initial RAM Disk - -@cindex initrd -@cindex initial RAM disk -For bootstrapping purposes, the Linux-Libre kernel is passed an @dfn{initial -RAM disk}, or @dfn{initrd}. An initrd contains a temporary root file system -as well as an initialization script. The latter is responsible for mounting -the real root file system, and for loading any kernel modules that may be -needed to achieve that. - -The @code{initrd-modules} field of an @code{operating-system} declaration -allows you to specify Linux-libre kernel modules that must be available in -the initrd. In particular, this is where you would list modules needed to -actually drive the hard disk where your root partition is---although the -default value of @code{initrd-modules} should cover most use cases. For -example, assuming you need the @code{megaraid_sas} module in addition to the -default modules to be able to access your root file system, you would write: - -@example -(operating-system - ;; @dots{} - (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) -@end example - -@defvr {Scheme Variable} %base-initrd-modules -This is the list of kernel modules included in the initrd by default. -@end defvr - -Furthermore, if you need lower-level customization, the @code{initrd} field -of an @code{operating-system} declaration allows you to specify which initrd -you would like to use. The @code{(gnu system linux-initrd)} module provides -three ways to build an initrd: the high-level @code{base-initrd} procedure -and the low-level @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 at boot -time, you can define the @code{initrd} field of the operating system -declaration like this: - -@example -(initrd (lambda (file-systems . rest) - ;; Create a standard initrd but set up networking - ;; with the parameters QEMU expects by default. - (apply base-initrd file-systems - #:qemu-networking? #t - rest))) -@end example - -The @code{base-initrd} procedure also handles common use cases that involves -using the system as a QEMU guest, or as a ``live'' system with volatile root -file system. - -The @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 -@item --load=@var{boot} -Tell the initial RAM disk to load @var{boot}, a file containing a Scheme -program, once it has mounted the root file system. - -Guix uses this option to yield control to a boot program that runs the -service activation programs and then spawns the GNU@tie{}Shepherd, the -initialization system. - -@item --root=@var{root} -Mount @var{root} as the root file system. @var{root} can be a device name -like @code{/dev/sda1}, a file system label, or a file system UUID. - -@item --system=@var{system} -Have @file{/run/booted-system} and @file{/run/current-system} point to -@var{system}. - -@item modprobe.blacklist=@var{modules}@dots{} -@cindex module, black-listing -@cindex black list, of kernel modules -Instruct the initial RAM disk as well as the @command{modprobe} command -(from the kmod package) to refuse to load @var{modules}. @var{modules} must -be a comma-separated list of module names---e.g., @code{usbkbd,9pnet}. - -@item --repl -Start a read-eval-print loop (REPL) from the initial RAM disk before it -tries to load kernel modules and to mount the root file system. Our -marketing team calls it @dfn{boot-to-Guile}. The Schemer in you will love -it. @xref{Using Guile Interactively,,, guile, GNU Guile Reference Manual}, -for more information on Guile's REPL. - -@end table - -Now that you know all the features that initial RAM disks produced by -@code{base-initrd} and @code{raw-initrd} provide, here is how to use it and -customize it further. - -@cindex initrd -@cindex initial RAM disk -@deffn {Scheme Procedure} raw-initrd @var{file-systems} @ - [#:linux-modules '()] [#:mapped-devices '()] @ [#:keyboard-layout #f] @ -[#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f] Return -a derivation that builds a raw initrd. @var{file-systems} is a list of file -systems to be mounted by the initrd, possibly in addition to the root file -system specified on the kernel command line via @code{--root}. -@var{linux-modules} is a list of kernel modules to be loaded at boot time. -@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 the root file system. - -When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record -denoting the desired console keyboard layout. This is done before -@var{mapped-devices} are set up and before @var{file-systems} are mounted -such that, should the user need to enter a passphrase or use the REPL, this -happens using the intended keyboard layout. - -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 initrd can be used as a QEMU guest with para-virtualized I/O -drivers. - -When @var{volatile-root?} is true, the root file system is writable but any -changes to it are lost. -@end deffn - -@deffn {Scheme Procedure} base-initrd @var{file-systems} @ - [#:mapped-devices '()] [#:keyboard-layout #f] @ [#:qemu-networking? #f] -[#:volatile-root? #f] @ [#:linux-modules '()] Return as a file-like object a -generic initrd, with kernel modules taken from @var{linux}. -@var{file-systems} is a list of file-systems to be mounted by the initrd, -possibly in addition to the root file system specified on the kernel command -line via @code{--root}. @var{mapped-devices} is a list of device mappings -to realize before @var{file-systems} are mounted. - -When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record -denoting the desired console keyboard layout. This is done before -@var{mapped-devices} are set up and before @var{file-systems} are mounted -such that, should the user need to enter a passphrase or use the REPL, this -happens using the intended keyboard layout. - -@var{qemu-networking?} and @var{volatile-root?} behaves as in -@code{raw-initrd}. - -The initrd is automatically populated with all the kernel modules necessary -for @var{file-systems} and for the given options. Additional kernel modules -can be listed in @var{linux-modules}. They will be added to the initrd, and -loaded at boot time in the order in which they appear. -@end deffn - -Needless to say, the initrds we produce and use embed a statically-linked -Guile, and the initialization program is a Guile program. That gives a lot -of flexibility. The @code{expression->initrd} procedure builds such an -initrd, given the program to run in that initrd. - -@deffn {Scheme Procedure} expression->initrd @var{exp} @ - [#:guile %guile-static-stripped] [#:name "guile-initrd"] Return as a -file-like object a Linux initrd (a gzipped cpio archive) containing -@var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All -the derivations referenced by @var{exp} are automatically copied to the -initrd. -@end deffn - -@node Bootloader Configuration -@section Bootloader Configuration - -@cindex bootloader -@cindex boot loader - -The operating system supports multiple bootloaders. The bootloader is -configured using @code{bootloader-configuration} declaration. All the -fields of this structure are bootloader agnostic except for one field, -@code{bootloader} that indicates the bootloader to be configured and -installed. - -Some of the bootloaders do not honor every field of -@code{bootloader-configuration}. For instance, the extlinux bootloader does -not support themes and thus ignores the @code{theme} field. - -@deftp {Data Type} bootloader-configuration -The type of a bootloader configuration declaration. - -@table @asis - -@item @code{bootloader} -@cindex EFI, bootloader -@cindex UEFI, bootloader -@cindex BIOS, bootloader -The bootloader to use, as a @code{bootloader} object. For now -@code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported. - -@vindex grub-efi-bootloader -@code{grub-efi-bootloader} allows to boot on modern systems using the -@dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should -use if the installation image contains a @file{/sys/firmware/efi} directory -when you boot it on your system. - -@vindex grub-bootloader -@code{grub-bootloader} allows you to boot in particular Intel-based machines -in ``legacy'' BIOS mode. - -@cindex ARM, bootloaders -@cindex AArch64, bootloaders -Available bootloaders are described in @code{(gnu bootloader @dots{})} -modules. In particular, @code{(gnu bootloader u-boot)} contains definitions -of bootloaders for a wide range of ARM and AArch64 systems, using the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. - -@item @code{target} -This is a string denoting the target onto which to install the bootloader. - -The interpretation depends on the bootloader in question. For -@code{grub-bootloader}, for example, it should be a device name understood -by the bootloader @command{installer} command, such as @code{/dev/sda} or -@code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}). For -@code{grub-efi-bootloader}, it should be the mount point of the EFI file -system, usually @file{/boot/efi}. - -@item @code{menu-entries} (default: @code{()}) -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. - -@item @code{default-entry} (default: @code{0}) -The index of the default boot menu entry. Index 0 is for the entry of the -current system. - -@item @code{timeout} (default: @code{5}) -The number of seconds to wait for keyboard input before booting. Set to 0 -to boot immediately, and to -1 to wait indefinitely. - -@cindex keyboard layout, for the bootloader -@item @code{keyboard-layout} (default: @code{#f}) -If this is @code{#f}, the bootloader's menu (if any) uses the default -keyboard layout, usually US@tie{}English (``qwerty''). - -Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard -Layout}). - -@quotation Note -This option is currently ignored by bootloaders other than @code{grub} and -@code{grub-efi}. -@end quotation - -@item @code{theme} (default: @var{#f}) -The bootloader theme object describing the theme to use. If no theme is -provided, some bootloaders might use a default theme, that's true for GRUB. - -@item @code{terminal-outputs} (default: @code{'gfxterm}) -The output terminals used for the bootloader boot menu, as a list of -symbols. GRUB accepts the values: @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 @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple configuration,,, -grub,GNU GRUB manual}). - -@item @code{terminal-inputs} (default: @code{'()}) -The input terminals used for the bootloader boot menu, as a list of -symbols. For GRUB, the default is the native platform terminal as -determined at run-time. GRUB accepts the values: @code{console}, -@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and -@code{usb_keyboard}. This field corresponds to the GRUB variable -@code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB -manual}). - -@item @code{serial-unit} (default: @code{#f}) -The serial unit used by the bootloader, as an integer from 0 to 3. For -GRUB, it is chosen 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. For GRUB, the default -value is chosen at run-time; currently GRUB chooses 9600@tie{}bps -(@pxref{Serial terminal,,, grub,GNU GRUB manual}). -@end table - -@end deftp - -@cindex dual boot -@cindex boot menu -Should you want to list additional boot menu entries @i{via} the -@code{menu-entries} field above, you will need to create them with the -@code{menu-entry} form. For example, imagine you want to be able to boot -another distro (hard to imagine!), you can define a menu entry along these -lines: - -@example -(menu-entry - (label "The Other Distro") - (linux "/boot/old/vmlinux-2.6.32") - (linux-arguments '("root=/dev/sda2")) - (initrd "/boot/old/initrd")) -@end example - -Details below. - -@deftp {Data Type} menu-entry -The type of an entry in the bootloader menu. - -@table @asis - -@item @code{label} -The label to show in the menu---e.g., @code{"GNU"}. - -@item @code{linux} -The Linux kernel image to boot, for example: - -@example -(file-append linux-libre "/bzImage") -@end example - -For GRUB, it is also possible to specify a device explicitly in the file -path using GRUB's device naming convention (@pxref{Naming convention,,, -grub, GNU GRUB manual}), for example: - -@example -"(hd0,msdos1)/boot/vmlinuz" -@end example - -If the device is specified explicitly as above, then the @code{device} field -is ignored entirely. - -@item @code{linux-arguments} (default: @code{()}) -The list of extra Linux kernel command-line arguments---e.g., -@code{("console=ttyS0")}. - -@item @code{initrd} -A G-Expression or string denoting the file name of the initial RAM disk to -use (@pxref{G-Expressions}). -@item @code{device} (default: @code{#f}) -The device where the kernel and initrd are to be found---i.e., for GRUB, -@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}). - -This may be a file system label (a string), a file system UUID (a -bytevector, @pxref{File Systems}), or @code{#f}, in which case the -bootloader will search the device containing the file specified by the -@code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It must -@emph{not} be an OS device name such as @file{/dev/sda1}. - -@end table -@end deftp - -@c FIXME: Write documentation once it's stable. -For now only GRUB has theme support. GRUB themes are created using the -@code{grub-theme} form, which is not documented yet. - -@defvr {Scheme Variable} %default-theme -This is the default GRUB theme used by the operating system if no -@code{theme} field is specified in @code{bootloader-configuration} record. - -It comes with a fancy background image displaying the GNU and Guix logos. -@end defvr - - -@node Invoking guix system -@section Invoking @code{guix system} - -Once you have written an operating system declaration as seen in the -previous section, it can be @dfn{instantiated} using the @command{guix -system} command. The synopsis is: - -@example -guix system @var{options}@dots{} @var{action} @var{file} -@end example - -@var{file} must be the name of a file containing an @code{operating-system} -declaration. @var{action} specifies how the operating system is -instantiated. Currently the following values are supported: - -@table @code -@item search -Display available service type definitions that match the given regular -expressions, sorted by relevance: - -@example -$ guix system search console font -name: console-fonts -location: gnu/services/base.scm:729:2 -extends: shepherd-root -description: Install the given fonts on the specified ttys (fonts are -+ per virtual console on GNU/Linux). The value of this service is a list -+ of tty/font pairs like: -+ -+ '(("tty1" . "LatGrkCyr-8x16")) -relevance: 20 - -name: mingetty -location: gnu/services/base.scm:1048:2 -extends: shepherd-root -description: Provide console login using the `mingetty' program. -relevance: 2 - -name: login -location: gnu/services/base.scm:775:2 -extends: pam -description: Provide a console log-in service as specified by its -+ configuration value, a `login-configuration' object. -relevance: 2 - -@dots{} -@end example - -As for @command{guix package --search}, the result is written in -@code{recutils} format, which makes it easy to filter the output -(@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}). - -@item reconfigure -Build the operating system described in @var{file}, activate it, and switch -to it@footnote{This action (and the related actions @code{switch-generation} -and @code{roll-back}) are usable only on systems already running Guix -System.}. - -This effects all the configuration specified in @var{file}: user accounts, -system services, global package list, setuid programs, etc. The command -starts system services specified in @var{file} that are not currently -running; if a service is currently running this command will arrange for it -to be upgraded the next time it is stopped (e.g.@: by @code{herd stop X} or -@code{herd restart X}). - -This command creates a new generation whose number is one greater than the -current generation (as reported by @command{guix system list-generations}). -If that generation already exists, it will be overwritten. This behavior -mirrors that of @command{guix package} (@pxref{Invoking guix package}). - -It also adds a bootloader menu entry for the new OS configuration, ---unless -@option{--no-bootloader} is passed. For GRUB, it moves entries for older -configurations to a submenu, allowing you to choose an older system -generation at boot time should you need it. - -@quotation Note -@c The paragraph below refers to the problem discussed at -@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>. -It is highly recommended to run @command{guix pull} once before you run -@command{guix system reconfigure} for the first time (@pxref{Invoking guix -pull}). Failing to do that you would see an older version of Guix once -@command{reconfigure} has completed. -@end quotation - -@item switch-generation -@cindex generations -Switch to an existing system generation. This action atomically switches -the system profile to the specified system generation. It also rearranges -the system's existing bootloader menu entries. It makes the menu entry for -the specified system generation the default, and it moves the entries for -the other generatiors to a submenu, if supported by the bootloader being -used. The next time the system boots, it will use the specified system -generation. - -The bootloader itself is not being reinstalled when using this command. -Thus, the installed bootloader is used with an updated configuration file. - -The target generation can be specified explicitly by its generation number. -For example, the following invocation would switch to system generation 7: - -@example -guix system switch-generation 7 -@end example - -The target generation can also be specified relative to the current -generation with the form @code{+N} or @code{-N}, where @code{+3} means ``3 -generations ahead of the current generation,'' and @code{-1} means ``1 -generation prior to the current generation.'' When specifying a negative -value such as @code{-1}, you must precede it with @code{--} to prevent it -from being parsed as an option. For example: - -@example -guix system switch-generation -- -1 -@end example - -Currently, the effect of invoking this action is @emph{only} to switch the -system profile to an existing generation and rearrange the bootloader menu -entries. To actually start using the target system generation, you must -reboot after running this action. In the future, it will be updated to do -the same things as @command{reconfigure}, like activating and deactivating -services. - -This action will fail if the specified generation does not exist. - -@item roll-back -@cindex rolling back -Switch to the preceding system generation. The next time the system boots, -it will use the preceding system generation. This is the inverse of -@command{reconfigure}, and it is exactly the same as invoking -@command{switch-generation} with an argument of @code{-1}. - -Currently, as with @command{switch-generation}, you must reboot after -running this action to actually start using the preceding system generation. - -@item delete-generations -@cindex deleting system generations -@cindex saving space -Delete system generations, making them candidates for garbage collection -(@pxref{Invoking guix gc}, for information on how to run the ``garbage -collector''). - -This works in the same way as @command{guix package --delete-generations} -(@pxref{Invoking guix package, @code{--delete-generations}}). With no -arguments, all system generations but the current one are deleted: - -@example -guix system delete-generations -@end example - -You can also select the generations you want to delete. The example below -deletes all the system generations that are more than two month old: - -@example -guix system delete-generations 2m -@end example - -Running this command automatically reinstalls the bootloader with an updated -list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no -longer lists the generations that have been deleted. - -@item build -Build the derivation of the operating system, which includes all the -configuration files and programs needed to boot and run the system. This -action does not actually install anything. - -@item init -Populate the given directory with all the files necessary to run the -operating system specified in @var{file}. This is useful for first-time -installations of Guix System. For instance: - -@example -guix system init my-os-config.scm /mnt -@end example - -copies to @file{/mnt} all the store items required by the configuration -specified in @file{my-os-config.scm}. This includes configuration files, -packages, and so on. It also creates other essential files needed for the -system to operate correctly---e.g., the @file{/etc}, @file{/var}, and -@file{/run} directories, and the @file{/bin/sh} file. - -This command also installs bootloader on the target specified in -@file{my-os-config}, unless the @option{--no-bootloader} option was passed. - -@item vm -@cindex virtual machine -@cindex VM -@anchor{guix system vm} -Build a virtual machine that contains the operating system declared in -@var{file}, and return a script to run that virtual machine (VM). - -@quotation Note -The @code{vm} action and others below can use KVM support in the Linux-libre -kernel. Specifically, if the machine has hardware virtualization support, -the corresponding KVM kernel module should be loaded, and the -@file{/dev/kvm} device node must exist and be readable and writable by the -user and by the build users of the daemon (@pxref{Build Environment Setup}). -@end quotation - -Arguments given to the script are passed to QEMU as in the example below, -which enables networking and requests 1@tie{}GiB of RAM for the emulated -machine: - -@example -$ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user -@end example - -The VM shares its store with the host system. - -Additional file systems can be shared between the host and the VM using the -@code{--share} and @code{--expose} command-line options: the former -specifies a directory to be shared with write access, while the latter -provides read-only access to the shared directory. - -The example below creates a VM in which the user's home directory is -accessible read-only, and where the @file{/exchange} directory is a -read-write mapping of @file{$HOME/tmp} on the host: - -@example -guix system vm my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/exchange -@end example - -On GNU/Linux, the default is to boot directly to the kernel; this has the -advantage of requiring only a very tiny root disk image since the store of -the host can then be mounted. - -The @code{--full-boot} option forces a complete boot sequence, starting with -the bootloader. This requires more disk space since a root image containing -at least the kernel, initrd, and bootloader data files must be created. The -@code{--image-size} option can be used to specify the size of the image. - -@cindex System images, creation in various formats -@cindex Creating system images in various formats -@item vm-image -@itemx disk-image -@itemx docker-image -Return a virtual machine, disk image, or Docker image of the operating -system declared in @var{file} that stands alone. By default, @command{guix -system} estimates the size of the image needed to store the system, but you -can use the @option{--image-size} option to specify a value. Docker images -are built to contain exactly what they need, so the @option{--image-size} -option is ignored in the case of @code{docker-image}. - -You can specify the root file system type by using the -@option{--file-system-type} option. It defaults to @code{ext4}. - -When using @code{vm-image}, the returned image is in qcow2 format, which the -QEMU emulator can efficiently use. @xref{Running Guix in a VM}, for more -information on how to run the image in a virtual machine. - -When using @code{disk-image}, a raw disk image is produced; it can be copied -as is to a USB stick, for instance. Assuming @code{/dev/sdc} is the device -corresponding to a USB stick, one can copy the image to it using the -following command: - -@example -# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc -@end example - -When using @code{docker-image}, a Docker image is produced. Guix builds the -image from scratch, not from a pre-existing Docker base image. As a result, -it contains @emph{exactly} what you define in the operating system -configuration file. You can then load the image and launch a Docker -container using commands like the following: - -@example -image_id="$(docker load < guix-system-docker-image.tar.gz)" -docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\ - --entrypoint /var/guix/profiles/system/profile/bin/guile \\ - $image_id /var/guix/profiles/system/boot -@end example - -This command starts a new Docker container from the specified image. It -will boot the Guix system in the usual manner, which means it will start any -services you have defined in the operating system configuration. Depending -on what you run in the Docker container, it may be necessary to give the -container additional permissions. For example, if you intend to build -software using Guix inside of the Docker container, you may need to pass the -@option{--privileged} option to @code{docker run}. - -@item container -Return a script to run the operating system declared in @var{file} within a -container. Containers are a set of lightweight isolation mechanisms -provided by the kernel Linux-libre. Containers are substantially less -resource-demanding than full virtual machines since the kernel, shared -objects, and other resources can be shared with the host system; this also -means they provide thinner isolation. - -Currently, the script must be run as root in order to support more than a -single user and group. The container shares its store with the host system. - -As with the @code{vm} action (@pxref{guix system vm}), additional file -systems to be shared between the host and container can be specified using -the @option{--share} and @option{--expose} options: - -@example -guix system container my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/exchange -@end example - -@quotation Note -This option requires Linux-libre 3.19 or newer. -@end quotation - -@end table - -@var{options} can contain any of the common build options (@pxref{Common -Build Options}). In addition, @var{options} can contain one 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 Guix system 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. This -works as per @command{guix build} (@pxref{Invoking guix build}). - -@item --derivation -@itemx -d -Return the derivation file name of the given operating system without -building anything. - -@item --file-system-type=@var{type} -@itemx -t @var{type} -For the @code{disk-image} action, create a file system of the given -@var{type} on the image. - -When this option is omitted, @command{guix system} uses @code{ext4}. - -@cindex ISO-9660 format -@cindex CD image format -@cindex DVD image format -@code{--file-system-type=iso9660} produces an ISO-9660 image, suitable for -burning on CDs and DVDs. - -@item --image-size=@var{size} -For the @code{vm-image} and @code{disk-image} actions, create an image of -the given @var{size}. @var{size} may be a number of bytes, or it may -include a unit as a suffix (@pxref{Block size, size specifications,, -coreutils, GNU Coreutils}). - -When this option is omitted, @command{guix system} computes an estimate of -the image size as a function of the size of the system declared in -@var{file}. - -@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 --skip-checks -Skip pre-installation safety checks. - -By default, @command{guix system init} and @command{guix system reconfigure} -perform safety checks: they make sure the file systems that appear in the -@code{operating-system} declaration actually exist (@pxref{File Systems}), -and that any Linux kernel modules that may be needed at boot time are listed -in @code{initrd-modules} (@pxref{Initial RAM Disk}). Passing this option -skips these tests altogether. - -@cindex on-error -@cindex on-error strategy -@cindex error strategy -@item --on-error=@var{strategy} -Apply @var{strategy} when an error occurs when reading @var{file}. -@var{strategy} may be one of the following: - -@table @code -@item nothing-special -Report the error concisely and exit. This is the default strategy. - -@item backtrace -Likewise, but also display a backtrace. - -@item debug -Report the error and enter Guile's debugger. From there, you can run -commands such as @code{,bt} to get a backtrace, @code{,locals} to display -local variable values, and more generally inspect the state of the program. -@xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for a list of -available debugging commands. -@end table -@end table - -Once you have built, configured, re-configured, and re-re-configured your -Guix installation, you may find it useful to list the operating system -generations available on disk---and that you can choose from the bootloader -boot menu: - -@table @code - -@item list-generations -List a summary of each generation of the operating system available on disk, -in a human-readable way. This is similar to the @option{--list-generations} -option of @command{guix package} (@pxref{Invoking guix package}). - -Optionally, one can specify a pattern, with the same syntax that is used in -@command{guix package --list-generations}, to restrict the list of -generations displayed. For instance, the following command displays -generations that are up to 10 days old: - -@example -$ guix system list-generations 10d -@end example - -@end table - -The @command{guix system} command has even more to offer! The following -sub-commands allow you to visualize how your system services relate to each -other: - -@anchor{system-extension-graph} -@table @code - -@item extension-graph -Emit in Dot/Graphviz format to standard output the @dfn{service extension -graph} of the operating system defined in @var{file} (@pxref{Service -Composition}, for more information on service extensions.) - -The command: - -@example -$ guix system extension-graph @var{file} | dot -Tpdf > services.pdf -@end example - -produces a PDF file showing the extension relations among services. - -@anchor{system-shepherd-graph} -@item shepherd-graph -Emit in Dot/Graphviz format to standard output the @dfn{dependency graph} of -shepherd services of the operating system defined in @var{file}. -@xref{Shepherd Services}, for more information and for an example graph. - -@end table - -@node Running Guix in a VM -@section Running Guix in a Virtual Machine - -@cindex virtual machine -To run Guix in a virtual machine (VM), one can either use the pre-built Guix -VM image distributed at -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-system-vm-image-@value{VERSION}.@var{system}.xz} -, or build their own virtual machine image using @command{guix system -vm-image} (@pxref{Invoking guix system}). The returned image is in qcow2 -format, which the @uref{http://qemu.org/, QEMU emulator} can efficiently -use. - -@cindex QEMU -If you built your own image, you must copy it out of the store (@pxref{The -Store}) and give yourself permission to write to the copy before you can use -it. When invoking QEMU, you must choose a system emulator that is suitable -for your hardware platform. Here is a minimal QEMU invocation that will -boot the result of @command{guix system vm-image} on x86_64 hardware: - -@example -$ qemu-system-x86_64 \ - -net user -net nic,model=virtio \ - -enable-kvm -m 256 /tmp/qemu-image -@end example - -Here is what each of these options means: - -@table @code -@item qemu-system-x86_64 -This specifies the hardware platform to emulate. This should match the -host. - -@item -net user -Enable the unprivileged user-mode network stack. The guest OS can access -the host but not vice versa. This is the simplest way to get the guest OS -online. - -@item -net nic,model=virtio -You must create a network interface of a given model. If you do not create -a NIC, the boot will fail. Assuming your hardware platform is x86_64, you -can get a list of available NIC models by running -@command{qemu-system-x86_64 -net nic,model=help}. - -@item -enable-kvm -If your system has hardware virtualization extensions, enabling the virtual -machine support (KVM) of the Linux kernel will make things run faster. - -@item -m 256 -RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB, -which may be insufficient for some operations. - -@item /tmp/qemu-image -The file name of the qcow2 image. -@end table - -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, for example @command{guix -download}. - -@subsection Connecting Through SSH - -@cindex SSH -@cindex SSH server -To enable SSH inside a VM you need to add a SSH server like -@code{(dropbear-service)} or @code{(lsh-service)} to your VM. The -@code{(lsh-service}) doesn't currently boot unsupervised. It requires you -to type some characters to initialize the randomness generator. In addition -you need to forward the SSH port, 22 by default, to the host. You can do -this with - -@example -`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 -@end example - -To connect to the VM you can run - -@example -ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 -@end example - -The @command{-p} tells @command{ssh} the port you want to connect to. -@command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from -complaining every time you modify your @command{config.scm} file and the -@command{-o StrictHostKeyChecking=no} prevents you from having to allow a -connection to an unknown host every time you connect. - -@subsection Using @command{virt-viewer} with Spice - -As an alternative to the default @command{qemu} graphical client you can use -the @command{remote-viewer} from the @command{virt-viewer} package. To -connect pass the @command{-spice port=5930,disable-ticketing} flag to -@command{qemu}. See previous section for further information on how to do -this. - -Spice also allows you to do some nice stuff like share your clipboard with -your VM. To enable that you'll also have to pass the following flags to -@command{qemu}: - -@example --device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5 --chardev spicevmc,name=vdagent,id=vdagent --device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent, -name=com.redhat.spice.0 -@end example - -You'll also need to add the @pxref{Miscellaneous Services, Spice service}. - -@node Defining Services -@section Defining Services - -The previous sections show the available services and how one can combine -them in an @code{operating-system} declaration. But how do we define them -in the first place? And what is a service anyway? - -@menu -* Service Composition:: The model for composing services. -* Service Types and Services:: Types and services. -* Service Reference:: API reference. -* Shepherd Services:: A particular type of service. -@end menu - -@node Service Composition -@subsection Service Composition - -@cindex services -@cindex daemons -Here we define a @dfn{service} as, broadly, something that extends the -functionality of the operating system. Often a service is a process---a -@dfn{daemon}---started when the system boots: a secure shell server, a Web -server, the Guix build daemon, etc. Sometimes a service is a daemon whose -execution can be triggered by another daemon---e.g., an FTP server started -by @command{inetd} or a D-Bus service activated by @command{dbus-daemon}. -Occasionally, a service does not map to a daemon. For instance, the -``account'' service collects user accounts and makes sure they exist when -the system runs; the ``udev'' service collects device management rules and -makes them available to the eudev daemon; the @file{/etc} service populates -the @file{/etc} directory of the system. - -@cindex service extensions -Guix system services are connected by @dfn{extensions}. For instance, the -secure shell service @emph{extends} the Shepherd---the initialization -system, running as PID@tie{}1---by giving it the command lines to start and -stop the secure shell daemon (@pxref{Networking Services, -@code{openssh-service-type}}); the UPower service extends the D-Bus service -by passing it its @file{.service} specification, and extends the udev -service by passing it device management rules (@pxref{Desktop Services, -@code{upower-service}}); the Guix daemon service extends the Shepherd by -passing it the command lines to start and stop the daemon, and extends the -account service by passing it a list of required build user accounts -(@pxref{Base Services}). - -All in all, services and their ``extends'' relations form a directed acyclic -graph (DAG). If we represent services as boxes and extensions as arrows, a -typical system might provide something like this: - -@image{images/service-graph,,5in,Typical service extension graph.} - -@cindex system service -At the bottom, we see the @dfn{system service}, which produces the directory -containing everything to run and boot the system, as returned by the -@command{guix system build} command. @xref{Service Reference}, to learn -about the other service types shown here. @xref{system-extension-graph, the -@command{guix system extension-graph} command}, for information on how to -generate this representation for a particular operating system definition. - -@cindex service types -Technically, developers can define @dfn{service types} to express these -relations. There can be any number of services of a given type on the -system---for instance, a system running two instances of the GNU secure -shell server (lsh) has two instances of @code{lsh-service-type}, with -different parameters. - -The following section describes the programming interface for service types -and services. - -@node Service Types and Services -@subsection Service Types and Services - -A @dfn{service type} is a node in the DAG described above. Let us start -with a simple example, the service type for the Guix build daemon -(@pxref{Invoking guix-daemon}): - -@example -(define guix-service-type - (service-type - (name 'guix) - (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))) - (default-value (guix-configuration)))) -@end example - -@noindent -It defines three things: - -@enumerate -@item -A name, whose sole purpose is to make inspection and debugging easier. - -@item -A list of @dfn{service extensions}, where each extension designates the -target service type and a procedure that, given the parameters of the -service, returns a list of objects to extend the service of that type. - -Every service type has at least one service extension. The only exception -is the @dfn{boot service type}, which is the ultimate service. - -@item -Optionally, a default value for instances of this type. -@end enumerate - -In this example, @code{guix-service-type} extends three services: - -@table @code -@item shepherd-root-service-type -The @code{guix-shepherd-service} procedure defines how the Shepherd service -is extended. Namely, it returns a @code{<shepherd-service>} object that -defines how @command{guix-daemon} is started and stopped (@pxref{Shepherd -Services}). - -@item account-service-type -This extension for this service is computed by @code{guix-accounts}, which -returns a list of @code{user-group} and @code{user-account} objects -representing the build user accounts (@pxref{Invoking guix-daemon}). - -@item activation-service-type -Here @code{guix-activation} is a procedure that returns a gexp, which is a -code snippet to run at ``activation time''---e.g., when the service is -booted. -@end table - -A service of this type is instantiated like this: - -@example -(service guix-service-type - (guix-configuration - (build-accounts 5) - (use-substitutes? #f))) -@end example - -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. When the value is omitted, -the default value specified by @code{guix-service-type} is used: - -@example -(service guix-service-type) -@end example - -@code{guix-service-type} is quite simple because it extends other services -but is not extensible itself. - -@c @subsubsubsection Extensible Service Types - -The service type for an @emph{extensible} service looks like this: - -@example -(define udev-service-type - (service-type (name 'udev) - (extensions - (list (service-extension shepherd-root-service-type - udev-shepherd-service))) - - (compose concatenate) ;concatenate the list of rules - (extend (lambda (config rules) - (match config - (($ <udev-configuration> udev initial-rules) - (udev-configuration - (udev udev) ;the udev package to use - (rules (append initial-rules rules))))))))) -@end example - -This is the service type for the -@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device management -daemon}. Compared to the previous example, in addition to an extension of -@code{shepherd-root-service-type}, we see two new fields: - -@table @code -@item compose -This is the procedure to @dfn{compose} the list of extensions to services of -this type. - -Services can extend the udev service by passing it lists of rules; we -compose those extensions simply by concatenating them. - -@item extend -This procedure defines how the value of the service is @dfn{extended} with -the composition of the extensions. - -Udev extensions are composed into a list of rules, but the udev service -value is itself a @code{<udev-configuration>} record. So here, we extend -that record by appending the list of rules it contains to the list of -contributed rules. - -@item description -This is a string giving an overview of the service type. The string can -contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}). The -@command{guix system search} command searches these strings and displays -them (@pxref{Invoking guix system}). -@end table - -There can be only one instance of an extensible service type such as -@code{udev-service-type}. If there were more, the @code{service-extension} -specifications would be ambiguous. - -Still here? The next section provides a reference of the programming -interface for services. - -@node Service Reference -@subsection Service Reference - -We have seen an overview of service types (@pxref{Service Types and -Services}). This section provides a reference on how to manipulate services -and service types. This interface is provided by the @code{(gnu services)} -module. - -@deffn {Scheme Procedure} service @var{type} [@var{value}] -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 true if @var{obj} is a service. -@end deffn - -@deffn {Scheme Procedure} service-kind @var{service} -Return the type of @var{service}---i.e., a @code{<service-type>} object. -@end deffn - -@deffn {Scheme Procedure} service-value @var{service} -Return the value associated with @var{service}. It represents its -parameters. -@end deffn - -Here is an example of how a service is created and manipulated: - -@example -(define s - (service nginx-service-type - (nginx-configuration - (nginx nginx) - (log-directory log-directory) - (run-directory run-directory) - (file config-file)))) - -(service? s) -@result{} #t - -(eq? (service-kind s) nginx-service-type) -@result{} #t -@end example - -The @code{modify-services} form provides a handy way to change the -parameters of some of the services of a list such as @code{%base-services} -(@pxref{Base Services, @code{%base-services}}). It evaluates to a list of -services. Of course, you could always use standard list combinators such as -@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, guile, -GNU Guile Reference Manual}); @code{modify-services} simply provides a more -concise form for this common pattern. - -@deffn {Scheme Syntax} modify-services @var{services} @ - (@var{type} @var{variable} => @var{body}) @dots{} - -Modify the services listed in @var{services} according to the given -clauses. Each clause has the form: - -@example -(@var{type} @var{variable} => @var{body}) -@end example - -where @var{type} is a service type---e.g., @code{guix-service-type}---and -@var{variable} is an identifier that is bound within the @var{body} to the -service parameters---e.g., a @code{guix-configuration} instance---of the -original service of that @var{type}. - -The @var{body} should evaluate to the new service parameters, which will be -used to configure the new service. This new service will replace the -original in the resulting list. Because a service's service parameters are -created using @code{define-record-type*}, you can write a succinct -@var{body} that evaluates to the new service parameters by using the -@code{inherit} feature that @code{define-record-type*} provides. - -@xref{Using the Configuration System}, for example usage. - -@end deffn - -Next comes the programming interface for service types. This is something -you want to know when writing new service definitions, but not necessarily -when simply looking for ways to customize your @code{operating-system} -declaration. - -@deftp {Data Type} service-type -@cindex service type -This is the representation of a @dfn{service type} (@pxref{Service Types and -Services}). - -@table @asis -@item @code{name} -This is a symbol, used only to simplify inspection and debugging. - -@item @code{extensions} -A non-empty list of @code{<service-extension>} objects (see below). - -@item @code{compose} (default: @code{#f}) -If this is @code{#f}, then the service type denotes services that cannot be -extended---i.e., services that do not receive ``values'' from other -services. - -Otherwise, it must be a one-argument procedure. The procedure is called by -@code{fold-services} and is passed a list of values collected from -extensions. It may return any single value. - -@item @code{extend} (default: @code{#f}) -If this is @code{#f}, services of this type cannot be extended. - -Otherwise, it must be a two-argument procedure: @code{fold-services} calls -it, passing it the initial value of the service as the first argument and -the result of applying @code{compose} to the extension values as the second -argument. It must return a value that is a valid parameter value for the -service instance. -@end table - -@xref{Service Types and Services}, for examples. -@end deftp - -@deffn {Scheme Procedure} service-extension @var{target-type} @ - @var{compute} Return a new extension for services of type -@var{target-type}. @var{compute} must be a one-argument procedure: -@code{fold-services} calls it, passing it the value associated with the -service that provides the extension; it must return a valid value for the -target service. -@end deffn - -@deffn {Scheme Procedure} service-extension? @var{obj} -Return true if @var{obj} is a service extension. -@end deffn - -Occasionally, you might want to simply extend an existing service. This -involves creating a new service type and specifying the extension of -interest, which can be verbose; the @code{simple-service} procedure provides -a shorthand for this. - -@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value} -Return a service that extends @var{target} with @var{value}. This works by -creating a singleton service type @var{name}, of which the returned service -is an instance. - -For example, this extends mcron (@pxref{Scheduled Job Execution}) with an -additional job: - -@example -(simple-service 'my-mcron-job mcron-service-type - #~(job '(next-hour (3)) "guix gc -F 2G")) -@end example -@end deffn - -At the core of the service abstraction lies the @code{fold-services} -procedure, which is responsible for ``compiling'' a list of services down to -a single directory that contains everything needed to boot and run the -system---the directory shown by the @command{guix system build} command -(@pxref{Invoking guix system}). In essence, it propagates service -extensions down the service graph, updating each node parameters on the way, -until it reaches the root node. - -@deffn {Scheme Procedure} fold-services @var{services} @ - [#:target-type @var{system-service-type}] Fold @var{services} by propagating -their extensions down to the root of type @var{target-type}; return the root -service adjusted accordingly. -@end deffn - -Lastly, the @code{(gnu services)} module also defines several essential -service types, some of which are listed below. - -@defvr {Scheme Variable} system-service-type -This is the root of the service graph. It produces the system directory as -returned by the @command{guix system build} command. -@end defvr - -@defvr {Scheme Variable} boot-service-type -The type of the ``boot service'', which produces the @dfn{boot script}. The -boot script is what the initial RAM disk runs when booting. -@end defvr - -@defvr {Scheme Variable} etc-service-type -The type of the @file{/etc} service. This service is used to create files -under @file{/etc} and can be extended by passing it name/file tuples such -as: - -@example -(list `("issue" ,(plain-file "issue" "Welcome!\n"))) -@end example - -In this example, the effect would be to add an @file{/etc/issue} file -pointing to the given file. -@end defvr - -@defvr {Scheme Variable} setuid-program-service-type -Type for the ``setuid-program service''. This service collects lists of -executable file names, passed as gexps, and adds them to the set of -setuid-root programs on the system (@pxref{Setuid Programs}). -@end defvr - -@defvr {Scheme Variable} profile-service-type -Type of the service that populates the @dfn{system profile}---i.e., the -programs under @file{/run/current-system/profile}. Other services can -extend it by passing it lists of packages to add to the system profile. -@end defvr - - -@node Shepherd Services -@subsection Shepherd Services - -@cindex shepherd services -@cindex PID 1 -@cindex init system -The @code{(gnu services shepherd)} module provides a way to define services -managed by the GNU@tie{}Shepherd, which is the initialization system---the -first process that is started when the system boots, also known as -PID@tie{}1 (@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}). - -Services in the Shepherd can depend on each other. For instance, the SSH -daemon may need to be started after the syslog daemon has been started, -which in turn can only happen once all the file systems have been mounted. -The simple operating system defined earlier (@pxref{Using the Configuration -System}) results in a service graph like this: - -@image{images/shepherd-graph,,5in,Typical shepherd service graph.} - -You can actually generate such a graph for any operating system definition -using the @command{guix system shepherd-graph} command -(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). - -The @code{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended by -passing it lists of @code{<shepherd-service>} objects. - -@deftp {Data Type} shepherd-service -The data type representing a service managed by the Shepherd. - -@table @asis -@item @code{provision} -This is a list of symbols denoting what the service provides. - -These are the names that may be passed to @command{herd start}, -@command{herd status}, and similar commands (@pxref{Invoking herd,,, -shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the -@code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details. - -@item @code{requirements} (default: @code{'()}) -List of symbols denoting the Shepherd services this one depends on. - -@cindex one-shot services, for the Shepherd -@item @code{one-shot?} (default: @code{#f}) -Whether this service is @dfn{one-shot}. One-shot services stop immediately -after their @code{start} action has completed. @xref{Slots of services,,, -shepherd, The GNU Shepherd Manual}, for more info. - -@item @code{respawn?} (default: @code{#t}) -Whether to restart the service when it stops, for instance when the -underlying process dies. - -@item @code{start} -@itemx @code{stop} (default: @code{#~(const #f)}) -The @code{start} and @code{stop} fields refer to the Shepherd's facilities -to start and stop processes (@pxref{Service De- and Constructors,,, -shepherd, The GNU Shepherd Manual}). They are given as G-expressions that -get expanded in the Shepherd configuration file (@pxref{G-Expressions}). - -@item @code{actions} (default: @code{'()}) -@cindex actions, of Shepherd services -This is a list of @code{shepherd-action} objects (see below) defining -@dfn{actions} supported by the service, in addition to the standard -@code{start} and @code{stop} actions. Actions listed here become available -as @command{herd} sub-commands: - -@example -herd @var{action} @var{service} [@var{arguments}@dots{}] -@end example - -@item @code{documentation} -A documentation string, as shown when running: - -@example -herd doc @var{service-name} -@end example - -where @var{service-name} is one of the symbols in @code{provision} -(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). - -@item @code{modules} (default: @code{%default-modules}) -This is the list of modules that must be in scope when @code{start} and -@code{stop} are evaluated. - -@end table -@end deftp - -@deftp {Data Type} shepherd-action -This is the data type that defines additional actions implemented by a -Shepherd service (see above). - -@table @code -@item name -Symbol naming the action. - -@item documentation -This is a documentation string for the action. It can be viewed by running: - -@example -herd doc @var{service} action @var{action} -@end example - -@item procedure -This should be a gexp that evaluates to a procedure of at least one -argument, which is the ``running value'' of the service (@pxref{Slots of -services,,, shepherd, The GNU Shepherd Manual}). -@end table - -The following example defines an action called @code{say-hello} that kindly -greets the user: - -@example -(shepherd-action - (name 'say-hello) - (documentation "Say hi!") - (procedure #~(lambda (running . args) - (format #t "Hello, friend! arguments: ~s\n" - args) - #t))) -@end example - -Assuming this action is added to the @code{example} service, then you can -do: - -@example -# herd say-hello example -Hello, friend! arguments: () -# herd say-hello example a b c -Hello, friend! arguments: ("a" "b" "c") -@end example - -This, as you can see, is a fairly sophisticated way to say hello. -@xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more -info on actions. -@end deftp - -@defvr {Scheme Variable} shepherd-root-service-type -The service type for the Shepherd ``root service''---i.e., PID@tie{}1. - -This is the service type that extensions target when they want to create -shepherd services (@pxref{Service Types and Services}, for an example). -Each extension must pass a list of @code{<shepherd-service>}. -@end defvr - -@defvr {Scheme Variable} %shepherd-root-service -This service represents PID@tie{}1. -@end defvr - - -@node Documentation -@chapter 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 -@chapter Installing Debugging Files - -@cindex debugging files -Program binaries, as produced by the GCC compilers for instance, are -typically written in the ELF format, with a section containing -@dfn{debugging information}. Debugging information is what allows the -debugger, GDB, to map binary code to source code; it is required to debug a -compiled program in good conditions. - -The problem with debugging information is that is takes up a fair amount of -disk space. For example, debugging information for the GNU C Library weighs -in at more than 60 MiB. Thus, as a user, keeping all the debugging info of -all the installed programs is usually not an option. Yet, space savings -should not come at the cost of an impediment to debugging---especially in -the GNU system, which should make it easier for users to exert their -computing freedom (@pxref{GNU Distribution}). - -Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a mechanism -that allows users to get the best of both worlds: debugging information can -be stripped from the binaries and stored in separate files. GDB is then -able to load debugging information from those files, when they are available -(@pxref{Separate Debug Files,,, gdb, Debugging with GDB}). - -The GNU distribution takes advantage of this by storing debugging -information in the @code{lib/debug} sub-directory of a separate package -output unimaginatively called @code{debug} (@pxref{Packages with Multiple -Outputs}). Users can choose to install the @code{debug} output of a package -when they need it. For instance, the following command installs the -debugging information for the GNU C Library and for GNU Guile: - -@example -guix package -i glibc:debug guile:debug -@end example - -GDB must then be told to look for debug files in the user's profile, by -setting the @code{debug-file-directory} variable (consider setting it from -the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with GDB}): - -@example -(gdb) set debug-file-directory ~/.guix-profile/lib/debug -@end example - -From there on, GDB will pick up debugging information from the @code{.debug} -files under @file{~/.guix-profile/lib/debug}. - -In addition, you will most likely want GDB to be able to show the source -code being debugged. To do that, you will have to unpack the source code of -the package of interest (obtained with @code{guix build --source}, -@pxref{Invoking guix build}), and to point GDB to that source directory -using the @code{directory} command (@pxref{Source Path, @code{directory},, -gdb, Debugging with GDB}). - -@c XXX: keep me up-to-date -The @code{debug} output mechanism in Guix is implemented by the -@code{gnu-build-system} (@pxref{Build Systems}). Currently, it is -opt-in---debugging information is available only for the packages with -definitions explicitly declaring a @code{debug} output. This may be changed -to opt-out in the future if our build farm servers can handle the load. To -check whether a package has a @code{debug} output, use @command{guix package ---list-available} (@pxref{Invoking guix package}). - - -@node Security Updates -@chapter Security Updates - -@cindex security updates -@cindex security vulnerabilities -Occasionally, important security vulnerabilities are discovered in software -packages and must be patched. Guix developers try hard to keep track of -known vulnerabilities and to apply fixes as soon as possible in the -@code{master} branch of Guix (we do not yet provide a ``stable'' branch -containing only security updates.) The @command{guix lint} tool helps -developers find out about vulnerable versions of software packages in the -distribution: - -@smallexample -$ guix lint -c cve -gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547 -gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276 -gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924 -@dots{} -@end smallexample - -@xref{Invoking guix lint}, for more information. - -@quotation Note -As of version @value{VERSION}, the feature described below is considered -``beta''. -@end quotation - -Guix follows a functional package management discipline -(@pxref{Introduction}), which implies that, when a package is changed, -@emph{every package that depends on it} must be rebuilt. This can -significantly slow down the deployment of fixes in core packages such as -libc or Bash, since basically the whole distribution would need to be -rebuilt. Using pre-built binaries helps (@pxref{Substitutes}), but -deployment may still take more time than desired. - -@cindex grafts -To address this, Guix implements @dfn{grafts}, a mechanism that allows for -fast deployment of critical updates without the costs associated with a -whole-distribution rebuild. The idea is to rebuild only the package that -needs to be patched, and then to ``graft'' it onto packages explicitly -installed by the user and that were previously referring to the original -package. The cost of grafting is typically very low, and order of -magnitudes lower than a full rebuild of the dependency chain. - -@cindex replacements of packages, for grafts -For instance, suppose a security update needs to be applied to Bash. Guix -developers will provide a package definition for the ``fixed'' Bash, say -@code{bash-fixed}, in the usual way (@pxref{Defining Packages}). Then, the -original package definition is augmented with a @code{replacement} field -pointing to the package containing the bug fix: - -@example -(define bash - (package - (name "bash") - ;; @dots{} - (replacement bash-fixed))) -@end example - -From there on, any package depending directly or indirectly on Bash---as -reported by @command{guix gc --requisites} (@pxref{Invoking guix gc})---that -is installed is automatically ``rewritten'' to refer to @code{bash-fixed} -instead of @code{bash}. This grafting process takes time proportional to -the size of the package, usually less than a minute for an ``average'' -package on a recent machine. Grafting is recursive: when an indirect -dependency requires grafting, then grafting ``propagates'' up to the package -that the user is installing. - -Currently, the length of the name and version of the graft and that of the -package it replaces (@code{bash-fixed} and @code{bash} in the example above) -must be equal. This restriction mostly comes from the fact that grafting -works by patching files, including binary files, directly. Other -restrictions may apply: for instance, when adding a graft to a package -providing a shared library, the original shared library and its replacement -must have the same @code{SONAME} and be binary-compatible. - -The @option{--no-grafts} command-line option allows you to forcefully avoid -grafting (@pxref{Common Build Options, @option{--no-grafts}}). Thus, the -command: - -@example -guix build bash --no-grafts -@end example - -@noindent -returns the store file name of the original Bash, whereas: - -@example -guix build bash -@end example - -@noindent -returns the store file name of the ``fixed'', replacement Bash. This allows -you to distinguish between the two variants of Bash. - -To verify which Bash your whole profile refers to, you can run -(@pxref{Invoking guix gc}): - -@example -guix gc -R `readlink -f ~/.guix-profile` | grep bash -@end example - -@noindent -@dots{} and compare the store file names that you get with those above. -Likewise for a complete Guix system generation: - -@example -guix gc -R `guix system build my-config.scm` | grep bash -@end example - -Lastly, to check which Bash running processes are using, you can use the -@command{lsof} command: - -@example -lsof | grep /gnu/store/.*bash -@end example - - -@node Bootstrapping -@chapter Bootstrapping - -@c Adapted from the ELS 2013 paper. - -@cindex bootstrapping - -Bootstrapping in our context refers to how the distribution gets built -``from nothing''. Remember that the build environment of a derivation -contains nothing but its declared inputs (@pxref{Introduction}). So there's -an obvious chicken-and-egg problem: how does the first package get built? -How does the first compiler get compiled? Note that this is a question of -interest only to the curious hacker, not to the regular user, so you can -shamelessly skip this section if you consider yourself a ``regular user''. - -@cindex bootstrap binaries -The GNU system is primarily made of C code, with libc at its core. The GNU -build system itself assumes the availability of a Bourne shell and -command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and -`grep'. Furthermore, build programs---programs that run @code{./configure}, -@code{make}, etc.---are written in Guile Scheme (@pxref{Derivations}). -Consequently, to be able to build anything at all, from scratch, Guix relies -on pre-built binaries of Guile, GCC, Binutils, libc, and the other packages -mentioned above---the @dfn{bootstrap binaries}. - -These bootstrap binaries are ``taken for granted'', though we can also -re-create them if needed (more on that later). - -@unnumberedsec Preparing to Use the Bootstrap Binaries - -@c As of Emacs 24.3, Info-mode displays the image, but since it's a -@c large image, it's hard to scroll. Oh well. -@image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap -derivations} - -The figure above shows the very beginning of the dependency graph of the -distribution, corresponding to the package definitions of the @code{(gnu -packages bootstrap)} module. A similar figure can be generated with -@command{guix graph} (@pxref{Invoking guix graph}), along the lines of: - -@example -guix graph -t derivation \ - -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \ - | dot -Tps > t.ps -@end example - -At this level of detail, things are slightly complex. First, Guile itself -consists of an ELF executable, along with many source and compiled Scheme -files that are dynamically loaded when it runs. This gets stored in the -@file{guile-2.0.7.tar.xz} tarball shown in this graph. This tarball is part -of Guix's ``source'' distribution, and gets inserted into the store with -@code{add-to-store} (@pxref{The Store}). - -But how do we write a derivation that unpacks this tarball and adds it to -the store? To solve this problem, the @code{guile-bootstrap-2.0.drv} -derivation---the first one that gets built---uses @code{bash} as its -builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls -@code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar}, @file{xz}, -and @file{mkdir} are statically-linked binaries, also part of the Guix -source distribution, whose sole purpose is to allow the Guile tarball to be -unpacked. - -Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning Guile -that can be used to run subsequent build programs. Its first task is to -download tarballs containing the other pre-built binaries---this is what the -@code{.tar.xz.drv} derivations do. Guix modules such as -@code{ftp-client.scm} are used for this purpose. The -@code{module-import.drv} derivations import those modules in a directory in -the store, using the original layout. The @code{module-import-compiled.drv} -derivations compile those modules, and write them in an output directory -with the right layout. This corresponds to the @code{#:modules} argument of -@code{build-expression->derivation} (@pxref{Derivations}). - -Finally, the various tarballs are unpacked by the derivations -@code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, etc., at which -point we have a working C tool chain. - - -@unnumberedsec Building the Build Tools - -Bootstrapping is complete when we have a full tool chain that does not -depend on the pre-built bootstrap tools discussed above. This no-dependency -requirement is verified by checking whether the files of the final tool -chain contain references to the @file{/gnu/store} directories of the -bootstrap inputs. The process that leads to this ``final'' tool chain is -described by the package definitions found in the @code{(gnu packages -commencement)} module. - -The @command{guix graph} command allows us to ``zoom out'' compared to the -graph above, by looking at the level of package objects instead of -individual derivations---remember that a package may translate to several -derivations, typically one derivation to download its source, one to build -the Guile modules it needs, and one to actually build the package from -source. The command: - -@example -guix graph -t bag \ - -e '(@@@@ (gnu packages commencement) - glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps -@end example - -@noindent -produces the dependency graph leading to the ``final'' C -library@footnote{You may notice the @code{glibc-intermediate} label, -suggesting that it is not @emph{quite} final, but as a good approximation, -we will consider it final.}, depicted below. - -@image{images/bootstrap-packages,6in,,Dependency graph of the early -packages} - -@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>. -The first tool that gets built with the bootstrap binaries is -GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite for -all the following packages. From there Findutils and Diffutils get built. - -Then come the first-stage Binutils and GCC, built as pseudo cross -tools---i.e., with @code{--target} equal to @code{--host}. They are used to -build libc. Thanks to this cross-build trick, this libc is guaranteed not -to hold any reference to the initial tool chain. - -From there the final Binutils and GCC (not shown above) are built. GCC uses -@code{ld} from the final Binutils, and links programs against the just-built -libc. This tool chain is used to build the other packages used by Guix and -by the GNU Build System: Guile, Bash, Coreutils, etc. - -And voilà! At this point we have the complete set of build tools that the -GNU Build System expects. These are in the @code{%final-inputs} variable of -the @code{(gnu packages commencement)} module, and are implicitly used by -any package that uses @code{gnu-build-system} (@pxref{Build Systems, -@code{gnu-build-system}}). - - -@unnumberedsec Building the Bootstrap Binaries - -@cindex bootstrap binaries -Because the final tool chain does not depend on the bootstrap binaries, -those rarely need to be updated. Nevertheless, it is useful to have an -automated way to produce them, should an update occur, and this is what the -@code{(gnu packages make-bootstrap)} module provides. - -The following command builds the tarballs containing the bootstrap binaries -(Guile, Binutils, GCC, libc, and a tarball containing a mixture of Coreutils -and other basic command-line tools): - -@example -guix build bootstrap-tarballs -@end example - -The generated tarballs are those that should be referred to in the -@code{(gnu packages bootstrap)} module mentioned at the beginning of this -section. - -Still here? Then perhaps by now you've started to wonder: when do we reach a -fixed point? That is an interesting question! The answer is unknown, but if -you would like to investigate further (and have significant computational -and storage resources to do so), then let us know. - -@unnumberedsec Reducing the Set of Bootstrap Binaries - -Our bootstrap binaries currently include GCC, Guile, etc. That's a lot of -binary code! Why is that a problem? It's a problem because these big chunks -of binary code are practically non-auditable, which makes it hard to -establish what source code produced them. Every unauditable binary also -leaves us vulnerable to compiler backdoors as described by Ken Thompson in -the 1984 paper @emph{Reflections on Trusting Trust}. - -This is mitigated by the fact that our bootstrap binaries were generated -from an earlier Guix revision. Nevertheless it lacks the level of -transparency that we get in the rest of the package dependency graph, where -Guix always gives us a source-to-binary mapping. Thus, our goal is to -reduce the set of bootstrap binaries to the bare minimum. - -The @uref{http://bootstrappable.org, Bootstrappable.org web site} lists -on-going projects to do that. One of these is about replacing the bootstrap -GCC with a sequence of assemblers, interpreters, and compilers of increasing -complexity, which could be built from source starting from a simple and -auditable assembler. Your help is welcome! - - -@node Porting -@chapter Porting to a New Platform - -As discussed above, the GNU distribution is self-contained, and -self-containment is achieved by relying on pre-built ``bootstrap binaries'' -(@pxref{Bootstrapping}). These binaries are specific to an operating system -kernel, CPU architecture, and application binary interface (ABI). Thus, to -port the distribution to a platform that is not yet supported, one must -build those bootstrap binaries, and update the @code{(gnu packages -bootstrap)} module to use them on that platform. - -Fortunately, Guix can @emph{cross compile} those bootstrap binaries. When -everything goes well, and assuming the GNU tool chain supports the target -platform, this can be as simple as running a command like this one: - -@example -guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs -@end example - -For this to work, the @code{glibc-dynamic-linker} procedure in @code{(gnu -packages bootstrap)} must be augmented to return the right file name for -libc's dynamic linker on that platform; likewise, -@code{system->linux-architecture} in @code{(gnu packages linux)} must be -taught about the new platform. - -Once these are built, the @code{(gnu packages bootstrap)} module needs to be -updated to refer to these binaries on the target platform. That is, the -hashes and URLs of the bootstrap tarballs for the new platform must be added -alongside those of the currently supported platforms. The bootstrap Guile -tarball is treated specially: it is expected to be available locally, and -@file{gnu/local.mk} has rules to download it for the supported -architectures; a rule for the new platform must be added as well. - -In practice, there may be some complications. First, it may be that the -extended GNU triplet that specifies an ABI (like the @code{eabi} suffix -above) is not recognized by all the GNU tools. Typically, glibc recognizes -some of these, whereas GCC uses an extra @code{--with-abi} configure flag -(see @code{gcc.scm} for examples of how to handle this). Second, some of -the required packages could fail to build for that platform. Lastly, the -generated binaries could be broken for some reason. - -@c ********************************************************************* -@include contributing.zh_CN.texi - -@c ********************************************************************* -@node Acknowledgments -@chapter Acknowledgments - -Guix is based on the @uref{http://nixos.org/nix/, Nix package manager}, -which was designed and implemented by Eelco Dolstra, with contributions from -other people (see the @file{nix/AUTHORS} file in Guix.) Nix pioneered -functional package management, and promoted unprecedented features, such as -transactional package upgrades and rollbacks, per-user profiles, and -referentially transparent build processes. Without this work, Guix would -not exist. - -The Nix-based software distributions, Nixpkgs and NixOS, have also been an -inspiration for Guix. - -GNU@tie{}Guix itself is a collective work with contributions from a number -of people. See the @file{AUTHORS} file in Guix for more information on -these fine people. The @file{THANKS} file lists people who have helped by -reporting bugs, taking care of the infrastructure, providing artwork and -themes, making suggestions, and more---thank you! - - -@c ********************************************************************* -@node GNU Free Documentation License -@appendix GNU Free Documentation License -@cindex license, GNU Free Documentation License -@include fdl-1.3.texi - -@c ********************************************************************* -@node Concept Index -@unnumbered Concept Index -@printindex cp - -@node Programming Index -@unnumbered Programming Index -@syncodeindex tp fn -@syncodeindex vr fn -@printindex fn - -@bye - -@c Local Variables: -@c ispell-local-dictionary: "american"; -@c End: |