Bootstrap error - Current master

DoneSubmitted by Danny Milosavljevic.
Details
3 participants
  • Danny Milosavljevic
  • Julien Lepiller
  • Ludovic Courtès
Owner
unassigned
Severity
normal
D
D
Danny Milosavljevic wrote on 12 May 2019 22:55
(address . bug-guix@gnu.org)
20190512225546.39594750@scratchpost.org
$ ./bootstrap[...]Makefile.am: error: 'version.texi', included in 'doc/guix.zh_CN.texi', also included in 'doc/guix.texi'
Commit: f8cd07e8d8acf85fd6d08646a0719178895b5894
-----BEGIN PGP SIGNATURE-----
iQEzBAEBCAAdFiEEds7GsXJ0tGXALbPZ5xo1VCwwuqUFAlzYiFIACgkQ5xo1VCwwuqUMAwf+KlrYc+GlaoTXWA3BTIDYYnQTh52V9N6ol7tiOWyKd5F2Wqtn8fyWY+whbvgAPJzkKuQkEXEEVwZy8kd2FF0As43y9CoivLgDp0oklJTNrtutmYrAGV+AyuJErYnBetTCBWcpCkeX6NkxX+YD2sjdkldXfH4tKbZWBsa8kGnxyJbSmJxa4uG6ZTFAauOhwOXgjUSRpoPCY41VjYxrdF8oD4wMlWsXbeA8N0nZ5QuxW4LuAcgwVxsf7zuy64et39Rr6LI65Y0g8JoP+sfxgkSl2VWqS3K2peJerAjK6iJ3h4D8oMRUt2LmsT/Y51lfO84E99Nrz/Shlp5RAXn/7pUhMA===8s6e-----END PGP SIGNATURE-----

J
J
Julien Lepiller wrote on 13 May 2019 08:36
1AC0BF2C-6E5E-4D1C-A34A-46E24B550F60@lepiller.eu
Le 12 mai 2019 22:55:46 GMT+02:00, Danny Milosavljevic <dannym@scratchpost.org> a écrit :
Toggle quote (7 lines)>$ ./bootstrap>[...]>Makefile.am: error: 'version.texi', included in 'doc/guix.zh_CN.texi',>also included in 'doc/guix.texi'>>Commit: f8cd07e8d8acf85fd6d08646a0719178895b5894
What does guix.zh_CN.texi contain after bootstrap?
D
D
Danny Milosavljevic wrote on 13 May 2019 09:45
(name . Julien Lepiller)(address . julien@lepiller.eu)(address . 35703@debbugs.gnu.org)
20190513094512.6ce7cf19@scratchpost.org
Toggle quote (2 lines)> What does guix.zh_CN.texi contain after bootstrap?
Attached.
\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.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
@copyingCopyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019Ludovic 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, 2017Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 RicardoWurmus@* 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, 2018Clé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{} 2017Christopher Allan Webber@* Copyright @copyright{} 2017, 2018 Marius Bakke@*Copyright @copyright{} 2017 Hartmut Goebel@* Copyright @copyright{} 2017Maxim Cournoyer@* Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@*Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017Andy 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 MikeGerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright@copyright{} 2018 Gábor Boskovits@* Copyright @copyright{} 2018 FlorianPelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{}2018 Alex Vong@*
Permission is granted to copy, distribute and/or modify this document underthe terms of the GNU Free Documentation License, Version 1.3 or any laterversion published by the Free Software Foundation; with no InvariantSections, no Front-Cover Texts, and no Back-Cover Texts. A copy of thelicense is included in the section entitled ``GNU Free DocumentationLicense''.@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 1filllEdition @value{EDITION} @* @value{UPDATED} @*
@insertcopying@end titlepage
@contents
@c *********************************************************************@node Top@top GNU Guix
This document describes GNU Guix version @value{VERSION}, a functionalpackage 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 Simplified Chinese (@pxref{Top,,,guix.zh_CN, GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel deréférence de GNU Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zuGNU Guix}), and Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNUGuix}). If you would like to translate it in your native language, considerjoining 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 purposeGNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' usingthe international phonetic alphabet (IPA).} is a package management tool forand distribution of the GNU system. Guix makes it easy for unprivilegedusers to install, upgrade, or remove software packages, to roll back to aprevious package set, to build packages from source, and generally assistswith the creation and maintenance of software environments.
@cindex Guix System@cindex GuixSD, now Guix System@cindex Guix System Distribution, now Guix SystemYou can install GNU@tie{}Guix on top of an existing GNU/Linux system whereit complements the available tools without interference(@pxref{Installation}), or you can use it as a standalone operating systemdistribution, @dfn{Guix@tie{}System}@footnote{We used to refer to GuixSystem as ``Guix System Distribution'' or ``GuixSD''. We now consider itmakes more sense to group everything under the ``Guix'' banner since, afterall, Guix System is readily available through the @command{guix system}command, even if you're using a different distro underneath!}. @xref{GNUDistribution}.
@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 interfacesGuix provides a command-line package management interface (@pxref{PackageManagement}), tools to help with software development (@pxref{Development}),command-line utilities for more advanced usage, (@pxref{Utilities}), as wellas Scheme programming interfaces (@pxref{Programming Interface}).@cindex build daemonIts @dfn{build daemon} is responsible for building packages on behalf ofusers (@pxref{Setting Up the Daemon}) and for downloading pre-built binariesfrom authorized sources (@pxref{Substitutes}).
@cindex extensibility of the distribution@cindex customization, of packagesGuix includes package definitions for many GNU and non-GNU packages, all ofwhich @uref{https://www.gnu.org/philosophy/free-sw.html,respect the user'scomputing freedom}. It is @emph{extensible}: users can write their ownpackage definitions (@pxref{Defining Packages}) and make them available asindependent package modules (@pxref{Package Modules}). It is also@emph{customizable}: users can @emph{derive} specialized package definitionsfrom existing ones, including from the command line (@pxref{PackageTransformation Options}).
@cindex functional package management@cindex isolationUnder the hood, Guix implements the @dfn{functional package management}discipline pioneered by Nix (@pxref{Acknowledgments}). In Guix, the packagebuild and installation process is seen as a @emph{function}, in themathematical sense. That function takes inputs, such as build scripts, acompiler, and libraries, and returns an installed package. As a purefunction, its result depends solely on its inputs---for instance, it cannotrefer to software or scripts that were not explicitly passed as inputs. Abuild function always produces the same result when passed a given set ofinputs. It cannot alter the environment of the running system in any way;for instance, it cannot create, modify, or delete files outside of its buildand installation directories. This is achieved by running build processesin isolated environments (or @dfn{containers}), where only their explicitinputs are visible.
@cindex storeThe result of package build functions is @dfn{cached} in the file system, ina special directory called @dfn{the store} (@pxref{The Store}). Eachpackage is installed in a directory of its own in the store---by defaultunder @file{/gnu/store}. The directory name contains a hash of all theinputs used to build that package; thus, changing an input yields adifferent directory name.
This approach is the foundation for the salient features of Guix: supportfor transactional package upgrade and rollback, per-user installation, andgarbage collection of packages (@pxref{Features}).

@node GNU Distribution@section GNU Distribution
@cindex Guix SystemGuix comes with a distribution of the GNU system consisting entirely of freesoftware@footnote{The term ``free'' here refers to the@url{http://www.gnu.org/philosophy/free-sw.html,freedomprovided to users ofthat software}.}. The distribution can be installed on its own(@pxref{System Installation}), but it is also possible to install Guix as apackage manager on top of an installed GNU/Linux system(@pxref{Installation}). When we need to distinguish between the two, werefer to the standalone distribution as Guix@tie{}System.
The distribution provides core GNU packages such as GNU libc, GCC, andBinutils, as well as many GNU and non-GNU applications. The complete listof 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}):
@exampleguix package --list-available@end example
Our goal is to provide a practical 100% free software distribution ofLinux-based and other variants of GNU, with a focus on the promotion andtight integration of GNU components, and an emphasis on programs and toolsthat help users exert that freedom.
Packages are currently available on the following platforms:
@table @code
@item x86_64-linuxIntel/AMD @code{x86_64} architecture, Linux-Libre kernel;
@item i686-linuxIntel 32-bit architecture (IA32), Linux-Libre kernel;
@item armhf-linuxARMv7-A architecture with hard float, Thumb-2 and NEON, using the EABIhard-float application binary interface (ABI), and Linux-Libre kernel.
@item aarch64-linuxlittle-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This iscurrently in an experimental stage, with limited support.@xref{贡献}, for how to help!
@item mips64el-linuxlittle-endian 64-bit MIPS processors, specifically the Loongson series, n32ABI, and Linux-Libre kernel.
@end table
With Guix@tie{}System, you @emph{declare} all aspects of the operatingsystem configuration and Guix takes care of instantiating the configurationin a transactional, reproducible, and stateless fashion (@pxref{SystemConfiguration}). Guix System uses the Linux-libre kernel, the Shepherdinitialization system (@pxref{Introduction,,, shepherd, The GNU ShepherdManual}), the well-known GNU utilities and tool chain, as well as thegraphical environment or system services of your choice.
Guix System is available on all the above platforms except@code{mips64el-linux}.
@noindentFor information on porting to other architectures or kernels,@pxref{Porting}.
Building this distribution is a cooperative effort, and you are invited tojoin! @xref{贡献}, for information about how you can help.

@c *********************************************************************@node Installation@chapter Installation
@cindex installing Guix
@quotation NoteWe 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/Linuxsystem, thereafter called a @dfn{foreign distro}.@footnote{This section isconcerned with the installation of the package manager, which can be done ontop of a running GNU/Linux system. If, instead, you want to install thecomplete GNU operating system, @pxref{System Installation}.} The scriptautomates the download, installation, and initial configuration of Guix. Itshould be run as the root user.@end quotation
@cindex foreign distro@cindex directories related to foreign distroWhen installed on a foreign distro, GNU@tie{}Guix complements the availabletools 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 tweakthem, you may find the following subsections useful. They describe thesoftware requirements of Guix, as well as how to install it manually and getready 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 scriptThis section describes how to install Guix on an arbitrary system from aself-contained tarball providing binaries for Guix and for all itsdependencies. This is often quicker than installing from source, which isdescribed in the next sections. The only requirement is to haveGNU@tie{}tar and Xz.
Installing goes along these lines:
@enumerate@item@cindex downloading Guix binaryDownload 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} machinealready 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 theauthenticity 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, thenrun this command to import it:
@example$ gpg --keyserver @value{KEY-SERVER} \ --recv-keys @value{OPENPGP-SIGNING-KEY-ID}@end example
@noindent@c end authentication partand rerun the @code{gpg --verify} command.
@itemNow, you need to become the @code{root} user. Depending on yourdistribution, 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 wouldoverwrite its own essential files.
The @code{--warning=no-timestamp} option makes sure GNU@tie{}tar does notemit warnings about ``implausibly old time stamps'' (such warnings weretriggered by GNU@tie{}tar 1.26 and older; recent versions are fine.) Theystem from the fact that all the files in the archive have their modificationtime set to zero (which means January 1st, 1970.) This is done on purposeto make sure the archive content is independent of its creation time, thusmaking it reproducible.
@itemMake the profile available under @file{~root/.config/guix/current}, which iswhere @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 relevantenvironment variables:
@example# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ source $GUIX_PROFILE/etc/profile@end example
@itemCreate the group and user accounts for build users as explained below(@pxref{Build Environment Setup}).
@itemRun the daemon, and set it to automatically start on boot.
If your host distro uses the systemd init system, this can be achieved withthese 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
@itemMake the @command{guix} command available to other users on the machine, forinstance 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 availablethere:
@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 InfoDirectories,,, texinfo, GNU Texinfo}, for more details on changing the Infosearch path.)
@item@cindex substitutes, authorization thereofTo use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of itsmirrors (@pxref{Substitutes}), authorize them:
@example# guix archive --authorize < \ ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub@end example
@itemEach user may need to perform a few additional steps to make their Guixenvironment 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 theroot profile:
@example# guix package -i hello@end example
The @code{guix} package must remain available in @code{root}'s profile, orit would become subject to garbage collection---in which case you would findyourself badly handicapped by the lack of the @command{guix} command. Inother words, do not remove @code{guix} by running @code{guix package -rguix}.
The binary installation tarball can be (re)produced and verified simply byrunning the following command in the Guix source tree:
@examplemake guix-binary.@var{system}.tar.xz@end example
@noindent...@: which, in turn, runs:
@exampleguix 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 buildprocedure for Guix is the same as for other GNU software, and is not coveredhere. Please see the files @file{README} and @file{INSTALL} in the Guixsource tree for additional details.
@cindex official websiteGNU 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}, version0.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 2017or 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}, version0.10.2 or later.
@itemWhen @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}, thefollowing 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 theC++11 standard.@end itemize
@cindex state directoryWhen configuring Guix on a system that already has a Guix installation, besure to specify the same state directory as the existing installation usingthe @code{--localstatedir} option of the @command{configure} script(@pxref{Directory Variables, @code{localstatedir},, standards, GNU CodingStandards}). The @command{configure} script protects against unintendedmisconfiguration of @var{localstatedir} so you do not inadvertently corruptyour store (@pxref{The Store}).
@cindex Nix, compatibilityWhen a working installation of @url{http://nixos.org/nix/,the Nix packagemanager} is available, you can instead configure Guix with@code{--disable-daemon}. In that case, Nix replaces the three dependenciesabove.
Guix is compatible with Nix, so it is possible to share the same storebetween 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 thatstores metadata about the store is located, among other things. The defaultvalues for Nix are @code{--with-store-dir=/nix/store} and@code{--localstatedir=/nix/var}. Note that @code{--disable-daemon} is notrequired if your goal is to share the store with Nix.
@node Running the Test Suite@section Running the Test Suite
@cindex test suiteAfter a successful @command{configure} and @code{make} run, it is a goodidea to run the test suite. It can help catch issues with the setup orenvironment, or bugs in Guix itself---and really, reporting test failures isa good way to help improve the software. To run the test suite, type:
@examplemake check@end example
Test cases can run in parallel: you can use the @code{-j} option ofGNU@tie{}make to speed things up. The first run may take a few minutes on arecent machine; subsequent runs will be faster because the store that iscreated 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:
@examplemake check TESTS="tests/store.scm tests/cpio.scm"@end example
By default, tests results are displayed at a file level. In order to seethe details of every individual test cases, it is possible to define the@code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
@examplemake 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 aswell as version numbers of the dependencies (@pxref{Requirements}) in yourmessage.
Guix also comes with a whole-system test suite that tests complete GuixSystem instances. It can only run on systems where Guix is alreadyinstalled, using:
@examplemake check-system@end example
@noindentor, again, by defining @code{TESTS} to select a subset of tests to run:
@examplemake 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 lightweightinstrumentation in a virtual machine (VM). They can be computationallyintensive or rather cheap, depending on whether substitutes are availablefor their dependencies (@pxref{Substitutes}). Some of them require a lot ofstorage space to hold VM images.
Again in case of test failures, please send @email{bug-guix@@gnu.org} allthe details.
@node Setting Up the Daemon@section Setting Up the Daemon
@cindex daemonOperations such as building a package or running the garbage collector areall performed by a specialized process, the @dfn{build daemon}, on behalf ofclients. Only the daemon may access the store and its associated database.Thus, any operation that manipulates the store goes through the daemon. Forinstance, command-line tools such as @command{guix package} and@command{guix build} communicate with the daemon (@i{via} remote procedurecalls) to instruct it what to do.
The following sections explain how to prepare the build daemon'senvironment. See also @ref{Substitutes}, for information on how to allowthe 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 environmentIn 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 orotherwise access the store, and the daemon will do it on their behalf,ensuring that the store is kept in a consistent state, and allowing builtpackages to be shared among users.
@cindex build usersWhen @command{guix-daemon} runs as @code{root}, you may not want packagebuild processes themselves to run as @code{root} too, for obvious securityreasons. To avoid that, a special pool of @dfn{build users} should becreated for use by build processes started by the daemon. These build usersneed not have a shell and a home directory: they will just be used when thedaemon drops @code{root} privileges in build processes. Having several suchusers allows the daemon to launch distinct build processes under separateUIDs, which guarantees that they do not interfere with each other---anessential feature since builds are regarded as pure functions(@pxref{Introduction}).
On a GNU/Linux system, a build user pool may be created like this (usingBash 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
@noindentThe number of build users determines how many build jobs may run inparallel, as specified by the @option{--max-jobs} option (@pxref{Invokingguix-daemon, @option{--max-jobs}}). To use @command{guix system vm} andrelated 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 thefollowing command@footnote{If your machine uses the systemd init system,dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service} filein @file{/etc/systemd/system} will ensure that @command{guix-daemon} isautomatically started. Similarly, if your machine uses the Upstart initsystem, 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@noindentThis way, the daemon starts build processes in a chroot, under one of the@code{guixbuilder} users. On GNU/Linux, by default, the chroot environmentcontains nothing but:
@c Keep this list in sync with libstore/build.cc! -----------------------@itemize@itema minimal @code{/dev} directory, created mostly independently from the host@code{/dev}@footnote{``Mostly'', because while the set of files that appearin the chroot's @code{/dev} is fixed, most of these files can only becreated if the host has them.};
@itemthe @code{/proc} directory; it only shows the processes of the containersince 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};
@itema 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 thechroot 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, whichavoids discrepancies in cases where build processes capture the name oftheir build tree.
@vindex http_proxyThe daemon also honors the @code{http_proxy} environment variable for HTTPdownloads 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 torun @command{guix-daemon} provided you pass @code{--disable-chroot}.However, build processes will not be isolated from one another, and not fromthe rest of the system. Thus, build processes may interfere with eachother, and may access programs, libraries, and other files available on thesystem---making it much harder to view them as @emph{pure} functions.

@node Daemon Offload Setup@subsection Using the Offload Facility
@cindex offloading@cindex build hookWhen desired, the build daemon can @dfn{offload} derivation builds to othermachines running Guix, using the @code{offload} @dfn{buildhook}@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 isread 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 oneof the machines that satisfy the constraints of the derivation, inparticular its system type---e.g., @file{x86_64-linux}. Missingprerequisites for the build are copied over SSH to the target machine, whichthen proceeds with the build; upon success the output(s) of the build arecopied 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
@noindentIn 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 evaluatedwhen 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 ofbuild machines, one could imagine, say, using DNS-SD to return a list ofpotential build machines discovered in the local network(@pxref{Introduction, Guile-Avahi,, guile-avahi, Using Avahi in Guile SchemePrograms}). The @code{build-machine} data type is detailed below.
@deftp {Data Type} build-machineThis data type represents build machines to which the daemon may offloadbuilds. The important fields are:
@table @code
@item nameThe host name of the remote machine.
@item systemThe system type of the remote machine---e.g., @code{"x86_64-linux"}.
@item userThe 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 allownon-interactive logins.
@item host-keyThis 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 along string that looks like this:
@examplessh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org@end example
If the machine is running the OpenSSH daemon, @command{sshd}, the host keycan 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 canbe 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 OpenSSHformat. 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 usagewhen 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 onthat 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 prefermachines with a higher speed factor.
@item @code{features} (default: @code{'()})A list of strings denoting specific features supported by the machine. Anexample is @code{"kvm"} for machines that have the KVM Linux modules andcorresponding 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 buildmachines. You can check whether this is the case by running:
@examplessh build-machine guix repl --version@end example
There is one last thing to do once @file{machines.scm} is in place. Asexplained above, when offloading, files are transferred back and forthbetween the machine stores. For this to work, you first need to generate akey pair on each machine to allow the daemon to export signed archives offiles from the store (@pxref{Invoking guix archive}):
@example# guix archive --generate-key@end example
@noindentEach build machine must authorize the key of the master machine so that itaccepts store items it receives from the master:
@example# guix archive --authorize < master-public-key.txt@end example
@noindentLikewise, the master machine must authorize the key of each build machine.
All the fuss with keys is here to express pairwise mutual trust relationsbetween the master and the build machines. Concretely, when the masterreceives files from a build machine (and @i{vice versa}), its build daemoncan make sure they are genuine, have not been tampered with, and that theyare signed by an authorized key.
@cindex offload testTo test whether your setup is operational, run this command on the masternode:
@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 areavailable on each machine, attempt to export to the machine and import fromit, and report any error in the process.
If you want to test a different machine file, just specify it on the commandline:
@example# guix offload test machines-qualif.scm@end example
Last, you can test the subset of the machines whose name matches a regularexpression like this:
@example# guix offload test machines.scm '\.gnu\.org$'@end example
@cindex offload statusTo display the current load of all build hosts, run this command on the mainnode:
@example# guix offload status@end example

@node SELinux Support@subsection SELinux Support
@cindex SELinux, daemon policy@cindex mandatory access control, SELinux@cindex security, guix-daemonGuix includes an SELinux policy file at @file{etc/guix-daemon.cil} that canbe installed on a system where SELinux is enabled, in order to label Guixfiles and to specify the expected behavior of the daemon. Since Guix Systemdoes not provide an SELinux base policy, the daemon policy cannot be used onGuix System.
@subsubsection Installing the SELinux policy@cindex SELinux, policy installationTo install the policy run this command as root:
@examplesemodule -i etc/guix-daemon.cil@end example
Then relabel the file system with @code{restorecon} or by a differentmechanism provided by your system.
Once the policy is installed, the file system has been relabeled, and thedaemon has been restarted, it should be running in the @code{guix_daemon_t}context. You can confirm this with the following command:
@exampleps -Zax | grep guix-daemon@end example
Monitor the SELinux log files as you run a command like @code{guix buildhello} 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 thatshould be considered when deploying the provided SELinux policy for the Guixdaemon.
@enumerate@item@code{guix_daemon_socket_t} isn’t actually used. None of the socketoperations involve contexts that have anything to do with@code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label, butit would be preferrable to define socket rules for only this label.
@item@code{guix gc} cannot access arbitrary links to profiles. By design, thefile label of the destination of a symlink is independent of the file labelof the link itself. Although all profiles under $localstatedir arelabelled, the links to these profiles inherit the label of the directorythey 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.
@itemThe daemon’s feature to listen for TCP connections might no longer work.This might require extra rules, because SELinux treats network socketsdifferently from files.
@itemCurrently all files with a name matching the regular expression@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned thelabel @code{guix_daemon_exec_t}; this means that @emph{any} file with thatname 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 providesthis executable and convince a user to install and run it, which lifts itinto the @code{guix_daemon_t} domain. At that point SELinux could notprevent it from accessing files that are allowed for processes in thatdomain.
We could generate a much more restrictive policy at installation time, sothat 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. Thedownside is that root would have to install or upgrade the policy atinstallation time whenever the Guix package that provides the effectivelyrunning @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 accessthe store. This includes launching build processes, running the garbagecollector, querying the availability of a build result, etc. It is normallyrun as @code{root} like this:
@example# guix-daemon --build-users-group=guixbuild@end example
@noindentFor details on how to set it up, @pxref{Setting Up the Daemon}.
@cindex chroot@cindex container, build environment@cindex build environment@cindex reproducible buildsBy default, @command{guix-daemon} launches build processes under differentUIDs, taken from the build group specified with @code{--build-users-group}.In addition, each build process is run in a chroot environment that onlycontains the subset of the store that the build process depends on, asspecified 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 buildenvironment is a @dfn{container}: in addition to having its own file systemtree, it has a separate mount name space, its own PID name space, networkname space, etc. This helps achieve reproducible builds (@pxref{Features}).
When the daemon performs a build on behalf of the user, it creates a builddirectory under @file{/tmp} or under the directory specified by its@code{TMPDIR} environment variable. This directory is shared with thecontainer for the duration of the build, though within the container, thebuild tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
The build directory is automatically deleted upon completion, unless thebuild 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 eachsession started by a client (one of the @command{guix} sub-commands.) The@command{guix processes} command allows you to get an overview of theactivity 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 theDaemon, build users}).
@item --no-substitutes@cindex substitutesDo not use substitutes for build products. That is, always build thingslocally instead of allowing downloads of pre-built binaries(@pxref{Substitutes}).
When the daemon runs with @code{--no-substitutes}, clients can stillexplicitly enable substitution @i{via} the @code{set-build-options} remoteprocedure call (@pxref{The Store}).
@item --substitute-urls=@var{urls}@anchor{daemon-substitute-urls}Consider @var{urls} the default whitespace-separated list of substitutesource 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 asthey are signed by a trusted signature (@pxref{Substitutes}).
@cindex build hook@item --no-build-hookDo not use the @dfn{build hook}.
The build hook is a helper program that the daemon can start and to which itsubmits build requests. This mechanism is used to offload builds to othermachines (@pxref{Daemon Offload Setup}).
@item --cache-failuresCache build failures. By default, only successful builds are cached.
When this option is used, @command{guix gc --list-failures} can be used toquery 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 asavailable.
The default value is @code{0}, but it may be overridden by clients, such asthe @code{--cores} option of @command{guix build} (@pxref{Invoking guixbuild}).
The effect is to define the @code{NIX_BUILD_CORES} environment variable inthe build process, which can then use it to exploit internalparallelism---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 performedlocally; instead, the daemon will offload builds (@pxref{Daemon OffloadSetup}), 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 BuildOptions, @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 BuildOptions, @code{--timeout}}).
@item --rounds=@var{N}Build each derivation @var{n} times in a row, and raise an error ifconsecutive build results are not bit-for-bit identical. Note that thissetting can be overridden by clients such as @command{guix build}(@pxref{Invoking guix build}).
When used in conjunction with @option{--keep-failed}, the differing outputis kept in the store, under @file{/gnu/store/@dots{}-check}. This makes iteasy to look for differences between the two results.
@item --debugProduce debugging output.
This is useful to debug daemon start-up issues, but then it may beoverridden 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 theyuse optional dependencies found in @var{dir} when it is available, and nototherwise. For that reason, it is not recommended to do so. Instead, makesure that each derivation declares all the inputs that it needs.
@item --disable-chrootDisable chroot builds.
Using this option is not recommended since, again, it would allow buildprocesses to gain access to undeclared dependencies. It is necessary,though, when @command{guix-daemon} is running under an unprivileged useraccount.
@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 compressesthem with bzip2 by default.
@item --disable-deduplication@cindex deduplicationDisable automatic file ``deduplication'' in the store.
By default, files added to the store are automatically ``deduplicated'': ifa newly added file is identical to another one found in the store, thedaemon makes the new file a hard link to the other file. This cannoticeably reduce disk usage, at the expense of slightly increasedinput/output load at the end of a build process. This option disables thisoptimization.
@item --gc-keep-outputs[=yes|no]Tell whether the garbage collector (GC) must keep outputs of livederivations.
@cindex GC roots@cindex garbage collector rootsWhen set to ``yes'', the GC will keep the outputs of any live derivationavailable in the store---the @code{.drv} files. The default is ``no'',meaning that derivation outputs are kept only if they are reachable from aGC 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 correspondingto live outputs.
When set to ``yes'', as is the case by default, the GC keepsderivations---i.e., @code{.drv} files---as long as at least one of theiroutputs is live. This allows users to keep track of the origins of items intheir store. Setting it to ``no'' saves a bit of disk space.
In this way, setting @code{--gc-keep-derivations} to ``yes'' causes livenessto flow from outputs to derivations, and setting @code{--gc-keep-outputs} to``yes'' causes liveness to flow from derivations to outputs. When both areset to ``yes'', the effect is to keep all the build prerequisites (thesources, compiler, libraries, and other build-time tools) of live objects inthe store, regardless of whether these prerequisites are reachable from a GCroot. This is convenient for developers since it saves rebuilds ordownloads.
@item --impersonate-linux-2.6On 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 onthe kernel version number.
@item --lose-logsDo 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 thearchitecture/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 asthe file name of a Unix-domain socket if it starts with @code{/} (slashsign). Otherwise, @var{endpoint} is interpreted as a host name or host nameand port to listen to. Here are a few examples:
@table @code@item --listen=/gnu/var/daemonListen 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 setupListen for TCP connections on the network interface corresponding to@code{localhost}, on port 44146.
@item --listen=128.0.0.42:1234Listen 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 NoteThe 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 caseswhere remote access to the daemon is needed, we recommend using Unix-domainsockets along with SSH.@end quotation
When @code{--listen} is omitted, @command{guix-daemon} listens forconnections on the Unix-domain socket located at@file{@var{localstatedir}/guix/daemon-socket/socket}.@end table

@node Application Setup@section Application Setup
@cindex foreign distroWhen using Guix on top of GNU/Linux distribution other than Guix System---aso-called @dfn{foreign distro}---a few additional steps are needed to geteverything in place. Here are some of them.
@subsection Locales
@anchor{locales-and-locpath}@cindex locales, when not on Guix System@vindex LOCPATH@vindex GUIX_LOCPATHPackages installed @i{via} Guix will not use the locale data of the hostsystem. Instead, you must first install one of the locale packagesavailable with Guix and then define the @code{GUIX_LOCPATH} environmentvariable:
@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 localessupported 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 fewUTF-8 locales.
The @code{GUIX_LOCPATH} variable plays a role similar to @code{LOCPATH}(@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C Library ReferenceManual}). There are two important differences though:
@enumerate@item@code{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libcprovided by foreign distros. Thus, using @code{GUIX_LOCPATH} allows you tomake sure the programs of the foreign distro will not end up loadingincompatible locale data.
@itemlibc 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, shouldyour Guix profile contain a mixture of programs linked against differentlibc version, each libc version will only try to load locale data in theright format.@end enumerate
This is important because the locale data format used by different libcversions 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 thesystem 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 tolook up host names or user accounts, or may even crash. The next paragraphsexplain why.
@cindex @file{nsswitch.conf}The GNU C library implements a @dfn{name service switch} (NSS), which is anextensible mechanism for ``name lookups'' in general: host name resolution,user accounts, and more (@pxref{Name Service Switch,,, libc, The GNU CLibrary Reference Manual}).
@cindex Network information service (NIS)@cindex NIS (Network information service)Being extensible, the NSS supports @dfn{plugins}, which provide new namelookup implementations: for example, the @code{nss-mdns} plugin allowresolution of @code{.local} host names, the @code{nis} plugin allows useraccount 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 honorthose settings (@pxref{NSS Configuration File,,, libc, The GNU C ReferenceManual}).
When they perform a name lookup---for instance by calling the@code{getaddrinfo} function in C---applications first try to connect to thenscd; on success, nscd performs name lookups on their behalf. If the nscdis not running, then they perform the name lookup by themselves, by loadingthe name lookup services into their own address space and running it. Thesename 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 Clibrary the application is linked against (the C library coming from Guix).
And this is where the problem is: if your application is linked againstGuix's C library (say, glibc 2.24) and tries to load NSS plugins fromanother C library (say, @code{libnss_mdns.so} for glibc 2.22), it willlikely crash or have its name lookups fail unexpectedly.
Running @command{nscd} on the system, among other advantages, eliminatesthis binary incompatibility problem because those @code{libnss_*.so} filesare loaded in the @command{nscd} process, not in applications themselves.
@subsection X11 Fonts
@cindex fontsThe majority of graphical applications use Fontconfig to locate and loadfonts and perform X11-client-side rendering. The @code{fontconfig} packagein Guix looks for fonts in @file{$HOME/.guix-profile} by default. Thus, toallow graphical applications installed with Guix to display fonts, you haveto 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 ingraphical applications, consider installing@code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former hasmultiple outputs, one per language family (@pxref{Packages with MultipleOutputs}). For instance, the following command installs fonts for Chineselanguages:
@exampleguix package -i font-adobe-source-han-sans:cn@end example
@cindex @code{xterm}Older programs such as @command{xterm} do not use Fontconfig and insteadrely on server-side font rendering. Such programs require to specify a fullname 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 yourGuix 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.@examplexset +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) tomake sure your TrueType fonts are listed there.
@cindex @code{fc-cache}@cindex font cacheAfter installing fonts you may have to refresh the font cache to use them inapplications. The same applies when applications installed via Guix do notseem 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 allowprograms to authenticate Web servers accessed over HTTPS.
When using Guix on a foreign distro, you can install this package and definethe relevant environment variables so that packages know where to look forcertificates. @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 placedeither in @file{$HOME/.guix-profile/share/emacs/site-lisp/} or insub-directories of@file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}. The latterdirectory exists because potentially there may exist thousands of Emacspackages and storing all their files in a single directory may not bereliable (because of name conflicts). So we think using a separatedirectory for each package is a good idea. It is very similar to how theEmacs package system organizes the file structure (@pxref{Package Files,,,emacs, The GNU Emacs Manual}).
By default, Emacs (installed with Guix) ``knows'' where these packages areplaced, so you do not need to perform any configuration. If, for somereason, 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 arein need of a complete toolchain for compiling and linking source code whatyou really want is the @code{gcc-toolchain} package. This package providesa complete GCC toolchain for C/C++ development, including GCC itself, theGNU 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} switchespassed to the linker, add corresponding @code{-rpath} arguments, and invokethe actual linker with this new set of arguments. You can instruct thewrapper 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, installationThis section explains how to install Guix System on a machine. Guix, as apackage 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 howto use it, hit the @key{RET} key (``return'' or ``enter'') on the link thatfollows: @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 manualavailable.@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'' andserver use cases. The reliability guarantees it provides---transactionalupgrades and rollbacks, reproducibility---make it a solid foundation.
Nevertheless, before you proceed with the installation, be aware of thefollowing noteworthy limitations applicable to version @value{VERSION}:
@itemize@itemSupport for the Logical Volume Manager (LVM) is missing.
@itemMore and more system services are provided (@pxref{Services}), but some maybe missing.
@itemGNOME, Xfce, LXDE, and Enlightenment are available (@pxref{DesktopServices}), as well as a number of X11 window managers. However, KDE iscurrently missing.@end itemize
More than a disclaimer, this is an invitation to report issues (and successstories!), and to join us in improving it. @xref{贡献}, for moreinfo.

@node Hardware Considerations@section Hardware Considerations
@cindex hardware support on Guix SystemGNU@tie{}Guix focuses on respecting the user's computing freedom. It buildsaround the kernel Linux-libre, which means that only hardware for which freesoftware drivers and firmware exist is supported. Nowadays, a wide range ofoff-the-shelf hardware is supported on GNU/Linux-libre---from keyboards tographics cards to scanners and Ethernet controllers. Unfortunately, thereare still areas where hardware vendors deny users control over their owncomputing, and such hardware is not supported on Guix System.
@cindex WiFi, hardware supportOne of the main areas where free drivers or firmware are lacking is WiFidevices. WiFi devices known to work include those using Atheros chips(AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libredriver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-CoreRevision 5), which corresponds to the @code{b43-open} Linux-libre driver.Free firmware exists for both and is available out-of-the-box on GuixSystem, as part of @code{%base-firmware} (@pxref{operating-system Reference,@code{firmware}}).
@cindex RYF, Respects Your FreedomThe @uref{https://www.fsf.org/,Free Software Foundation} runs@uref{https://www.fsf.org/ryf,@dfn{Respects Your Freedom}} (RYF), acertification program for hardware products that respect your freedom andyour privacy and ensure that you have control over your device. Weencourage you to check the list of RYF-certified devices.
Another useful resource is the @uref{https://www.h-node.org/,H-Node} website. It contains a catalog of hardware devices with information abouttheir 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 burntto 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-linuxfor a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
@item i686-linuxfor 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 theauthenticity 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, thenrun this command to import it:
@example$ gpg --keyserver @value{KEY-SERVER} \ --recv-keys @value{OPENPGP-SIGNING-KEY-ID}@end example
@noindent@c end duplicationand rerun the @code{gpg --verify} command.
This image contains the tools necessary for an installation. It is meant tobe 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@itemDecompress the image using the @command{xz} command:
@examplexz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz@end example
@itemInsert a USB stick of 1@tie{}GiB or more into your machine, and determineits device name. Assuming that the USB stick is known as @file{/dev/sdX},copy the image with:
@exampledd if=guix-system-install-@value{VERSION}.@var{system}.iso of=/dev/sdXsync@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@itemDecompress the image using the @command{xz} command:
@examplexz -d guix-system-install-@value{VERSION}.@var{system}.iso.xz@end example
@itemInsert a blank DVD into your machine, and determine its device name.Assuming that the DVD drive is known as @file{/dev/srX}, copy the imagewith:
@examplegrowisofs -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 theUSB stick or DVD. The latter usually requires you to get in the BIOS orUEFI 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 GuixSystem in a virtual machine (VM).

@node Preparing for Installation@section Preparing for Installation
Once you have booted, you can use the guided graphical installer, whichmakes it easy to get started (@pxref{Guided Graphical Installation}).Alternately, if you are already familiar with GNU/Linux and if you want morecontrol 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 onTTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2shows 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 GPMmouse daemon, which allows you to select text with the left mouse button andto paste it with the middle button.
@quotation NoteInstallation requires access to the Internet so that any missingdependencies 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 duringthe installation: you can choose the language, keyboard layout, and set upnetworking, which will be used during the installation. The image belowshows the networking dialog.
@image{images/installer-network,5in,, networking setup with the graphicalinstaller}
Later steps allow you to partition your hard disk, as shown in the imagebelow, to choose whether or not to use encrypted file systems, to enter thehost name and root password, and to create an additional account, amongother things.
@image{images/installer-partitions,5in,, partitioning with the graphicalinstaller}
Note that, at any time, the installer allows you to exit the currentinstallation 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 configurationand displays it (@pxref{Using the Configuration System}). At that point youcan hit ``OK'' and installation will proceed. On success, you can rebootinto the new system and enjoy. @xref{After System Installation}, for what'snext!

@node Manual Installation@section Manual Installation
This section describes how you would ``manually'' install GNU@tie{}GuixSystem on your machine. This option requires familiarity with GNU/Linux,with the shell, and with common administration tools. If you think this isnot for you, consider using the guided graphical installer (@pxref{GuidedGraphical 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 includesmany common tools needed to install the system. But it is also a full-blownGuix System, which means that you can install additional packages, shouldyou 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 keyboardlayout, set up networking, and partition your target hard disk. Thissection will guide you through this.
@subsubsection Keyboard Layout
@cindex keyboard layoutThe installation image uses the US qwerty keyboard layout. If you want tochange it, you can use the @command{loadkeys} command. For example, thefollowing command selects the Dvorak keyboard layout:
@exampleloadkeys dvorak@end example
See the files under @file{/run/current-system/profile/share/keymaps} for alist of available keyboard layouts. Run @command{man loadkeys} for moreinformation.
@subsubsection Networking
Run the following command to see what your network interfaces are called:
@exampleifconfig -a@end example
@noindent@dots{} or, using the GNU/Linux-specific @command{ip} command:
@exampleip a@end example
@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20Wired interfaces have a name starting with @samp{e}; for example, theinterface 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 connectionTo configure a wired network run the following command, substituting@var{interface} with the name of the wired interface you want to use.
@exampleifconfig @var{interface} up@end example
@item Wireless connection@cindex wireless@cindex WiFiTo configure wireless networking, you can create a configuration file forthe @command{wpa_supplicant} configuration tool (its location is notimportant) using one of the available text editors such as @command{nano}:
@examplenano wpa_supplicant.conf@end example
As an example, the following stanza can go to this file and will work formany wireless networks, provided you give the actual SSID and passphrase forthe network you are connecting to:
@examplenetwork=@{ 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 followingcommand (substitute @var{interface} with the name of the network interfaceyou want to use):
@examplewpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B@end example
Run @command{man wpa_supplicant} for more information.@end table
@cindex DHCPAt this point, you need to acquire an IP address. On a network where IPaddresses are automatically assigned @i{via} DHCP, you can run:
@exampledhclient -v @var{interface}@end example
Try to ping a server to see if networking is up and running:
@exampleping -c 3 gnu.org@end example
Setting up network access is almost always a requirement because the imagedoes not contain all the software and tools that may be needed.
@cindex installing over SSHIf you want to, you can continue the installation remotely by starting anSSH server:
@exampleherd start ssh-daemon@end example
Make sure to either set a password with @command{passwd}, or configureOpenSSH public key authentication before logging in.
@subsubsection Disk Partitioning
Unless this has already been done, the next step is to partition, and thenformat 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 youwant:
@examplecfdisk@end example
If your disk uses the GUID Partition Table (GPT) format and you plan toinstall BIOS-based GRUB (which is the default), make sure a BIOS BootPartition is available (@pxref{BIOS installation,,, grub, GNU GRUB manual}).
@cindex EFI, installation@cindex UEFI, installation@cindex ESP, EFI system partitionIf you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI SystemPartition} (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}:
@exampleparted /dev/sda set 1 esp on@end example
@quotation Note@vindex grub-bootloader@vindex grub-efi-bootloaderUnsure whether to use EFI- or BIOS-based GRUB? If the directory@file{/sys/firmware/efi} exists in the installation image, then you shouldprobably 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 onbootloaders.@end quotation
Once you are done partitioning the target hard disk drive, you have tocreate a file system on the relevant partition(s)@footnote{Currently GuixSystem only supports ext4 and btrfs file systems. In particular, code thatreads file system UUIDs and labels only works for these file systemtypes.}. For the ESP, if you have one and assuming it is @file{/dev/sda1},run:
@examplemkfs.fat -F32 /dev/sda1@end example
Preferably, assign file systems a label so that you can easily and reliablyrefer to them in @code{file-system} declarations (@pxref{File Systems}).This is typically done using the @code{-L} option of @command{mkfs.ext4} andrelated commands. So, assuming the target root partition lives at@file{/dev/sda2}, a file system with the label @code{my-root} can be createdwith:
@examplemkfs.ext4 -L my-root /dev/sda2@end example
@cindex encrypted diskIf you are instead planning to encrypt the root partition, you can use theCryptsetup/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 storethe root partition on @file{/dev/sda2}, the command sequence would be alongthese lines:
@examplecryptsetup luksFormat /dev/sda2cryptsetup open --type luks /dev/sda2 my-partitionmkfs.ext4 -L my-root /dev/mapper/my-partition@end example
Once that is done, mount the target file system under @file{/mnt} with acommand like (again, assuming @code{my-root} is the label of the root filesystem):
@examplemount LABEL=my-root /mnt@end example
Also mount any other file systems you would like to use on the target systemrelative to this path. If you have opted for @file{/boot/efi} as an EFImount point for example, mount it at @file{/mnt/boot/efi} now so it is foundby @code{guix system init} afterwards.
Finally, if you plan to use one or more swap partitions (@pxref{MemoryConcepts, swap space,, libc, The GNU C Library Reference Manual}), make sureto initialize them with @command{mkswap}. Assuming you have one swappartition on @file{/dev/sda3}, you would run:
@examplemkswap /dev/sda3swapon /dev/sda3@end example
Alternatively, you may use a swap file. For example, assuming that in thenew system you want to use the file @file{/swapfile} as a swap file, youwould 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), therequired 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/swapfilemkswap /mnt/swapfileswapon /mnt/swapfile@end example
Note that if you have encrypted the root partition and created a swap filein its file system as described above, then the encryption also protects theswap 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:
@exampleherd start cow-store /mnt@end example
This makes @file{/gnu/store} copy-on-write, such that packages added to itduring the installation phase are written to the target disk on @file{/mnt}rather than kept in memory. This is necessary because the first phase ofthe @command{guix system init} command (see below) entails downloads orbuilds 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 operatingsystem to be installed. To that end, the installation system comes withthree text editors. We recommend GNU nano (@pxref{Top,,, nano, GNU nanoManual}), which supports syntax highlighting and parentheses matching; othereditors include GNU Zile (an Emacs clone), and nvi (a clone of the originalBSD @command{vi} editor). We strongly recommend storing that file on thetarget root file system, say, as @file{/mnt/etc/config.scm}. Failing to dothat, you will have lost your configuration file once you have rebooted intothe newly-installed system.
@xref{Using the Configuration System}, for an overview of the configurationfile. The example configurations discussed in that section are availableunder @file{/etc/configuration} in the installation image. Thus, to getstarted 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 inparticular:
@itemize@itemMake sure the @code{bootloader-configuration} form refers to the target youwant to install GRUB on. It should mention @code{grub-bootloader} if youare installing GRUB in the legacy way, or @code{grub-efi-bootloader} fornewer UEFI systems. For legacy systems, the @code{target} field names adevice, like @code{/dev/sda}; for UEFI systems it names a path to a mountedEFI partition, like @code{/boot/efi}; do make sure the path is currentlymounted and a @code{file-system} entry is specified in your configuration.
@itemBe 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} procedurein its @code{device} field.
@itemIf 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 beinitialized (remember that the target root file system is mounted under@file{/mnt}):
@exampleguix system init /mnt/etc/config.scm /mnt@end example
@noindentThis 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 buildsof 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 inthe new system is initially empty; other users' passwords need to beinitialized by running the @command{passwd} command as @code{root}, unlessyour configuration specifies otherwise (@pxref{user-account-password, useraccount 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 updatethe system whenever you want by running, say:
@exampleguix pullsudo guix system reconfigure /etc/config.scm@end example
@noindentThis builds a new system generation with the latest packages and services(@pxref{Invoking guix system}). We recommend doing that regularly so thatyour 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. Toexplicitly 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 avirtual private server (VPS) rather than on your beloved machine, thissection is for you.
To boot a @uref{http://qemu.org/,QEMU}VM for installing Guix System in adisk image, follow these steps:
@enumerate@itemFirst, retrieve and decompress the Guix system installation image asdescribed previously (@pxref{USB Stick and DVD Installation}).
@itemCreate a disk image that will hold the installed system. To make aqcow2-formatted disk image, use the @command{qemu-img} command:
@exampleqemu-img create -f qcow2 guixsd.img 50G@end example
The resulting file will be much smaller than 50 GB (typically less than 1MB), but it will grow as the virtualized storage device is filled up.
@itemBoot the USB installation image in an VM:
@exampleqemu-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.
@itemYou'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 imageThe installation image described above was built using the @command{guixsystem} command, specifically:
@exampleguix 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 seealso @ref{Invoking guix system} for more information about the installationimage.
@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 (onanother boot drive etc), it's advisable to build an image that includes thebootloader, specifically:
@exampleguix 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 aninvalid board, a list of possible boards will be printed.
@c *********************************************************************@node Package Management@chapter Package Management
@cindex packagesThe purpose of GNU Guix is to allow users to easily install, upgrade, andremove software packages, without having to know about their buildprocedures or dependencies. Guix also goes beyond this obvious set offeatures.
This chapter describes the main features of Guix, as well as the packagemanagement tools it provides. Along with the command-line interfacedescribed below (@pxref{Invoking guix package, @code{guix package}}), youmay also use the Emacs-Guix interface (@pxref{Top,,, emacs-guix, TheEmacs-Guix Reference Manual}), after installing @code{emacs-guix} package(run @kbd{M-x guix-help} command to start with it):
@exampleguix 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 owndirectory---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 GCCcoexist 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, andcan be used @emph{with normal user privileges}.
@cindex transactionsThe command provides the obvious install, remove, and upgrade operations.Each invocation is actually a @emph{transaction}: either the specifiedoperation succeeds, or nothing happens. Thus, if the @command{guix package}process is terminated during the transaction, or if a power outage occursduring the transaction, then the user's profile remains in its previousstate, and remains usable.
In addition, any package transaction may be @emph{rolled back}. So, if, forexample, an upgrade installs a new version of a package that turns out tohave a serious bug, users may roll back to the previous instance of theirprofile, which was known to work well. Similarly, the global systemconfiguration 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 candetermine which packages are still referenced by user profiles, and removethose that are provably no longer referenced (@pxref{Invoking guix gc}).Users may also explicitly remove old generations of their profile so thatthe packages they refer to can be collected.
@cindex reproducibility@cindex reproducible buildsGuix takes a @dfn{purely functional} approach to package management, asdescribed in the introduction (@pxref{Introduction}). Each@file{/gnu/store} package directory name contains a hash of all the inputsthat were used to build that package---compiler, libraries, build scripts,etc. This direct correspondence allows users to make sure a given packageinstallation matches the current state of their distribution. It also helpsmaximize @dfn{build reproducibility}: thanks to the isolated buildenvironments that are used, a given build is likely to yield bit-identicalfiles when performed on different machines (@pxref{Invoking guix-daemon,container}).
@cindex substitutesThis foundation allows Guix to support @dfn{transparent binary/sourcedeployment}. When a pre-built binary for a @file{/gnu/store} item isavailable from an external source---a @dfn{substitute}, Guix just downloadsit and unpacks it; otherwise, it builds the package from source, locally(@pxref{Substitutes}). Because build results are usually bit-for-bitreproducible, users do not have to trust servers that provide substitutes:they can force a local build and @emph{challenge} providers (@pxref{Invokingguix challenge}).
Control over the build environment is a feature that is also useful fordevelopers. The @command{guix environment} command allows developers of apackage to quickly set up the right development environment for theirpackage, without having to manually install the dependencies of the packageinto their profile (@pxref{Invoking guix environment}).
@cindex replication, of software environments@cindex provenance tracking, of software artifactsAll of Guix and its package definitions is version-controlled, and@command{guix pull} allows you to ``travel in time'' on the history of Guixitself (@pxref{Invoking guix pull}). This makes it possible to replicate aGuix instance on a different machine or at a later point in time, which inturn allows you to @emph{replicate complete software environments}, whileretaining 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 removalThe @command{guix package} command is the tool that allows users to install,upgrade, and remove packages, as well as rolling back to previousconfigurations. It operates only on the user's own profile, and works withnormal user privileges (@pxref{Features}). Its syntax is:
@exampleguix package @var{options}@end example@cindex transactionsPrimarily, @var{options} specifies the operations to be performed during thetransaction. Upon completion, a new profile is created, but previous@dfn{generations} of the profile remain available, should the user want toroll back.
For example, to remove @code{lua} and install @code{guile} and@code{guile-cairo} in a single transaction:
@exampleguix package -r lua -i guile guile-cairo@end example
@command{guix package} also supports a @dfn{declarative approach} wherebythe 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 profileFor each user, a symlink to the user's default profile is automaticallycreated in @file{$HOME/.guix-profile}. This symlink always points to thecurrent 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 pathsIf you are not using the Guix System Distribution, consider adding thefollowing lines to your @file{~/.bash_profile} (@pxref{Bash Startup Files,,,bash, The GNU Bash Reference Manual}) so that newly-spawned shells get allthe right environment variable definitions:
@exampleGUIX_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 beselected. In addition, @var{package} may contain a colon, followed by thename 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 foramong the GNU distribution modules (@pxref{Package Modules}).
@cindex propagated inputsSometimes packages have @dfn{propagated inputs}: these are dependencies thatautomatically get installed along with the required package(@pxref{package-propagated-inputs, @code{propagated-inputs} in@code{package} objects}, for information about propagated inputs in packagedefinitions).
@anchor{package-cmd-propagated-inputs}An example is the GNU MPC library: its C header files refer to those of theGNU 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 theprofile; removing MPC also removes MPFR and GMP---unless they had also beenexplicitly installed by the user.
Besides, packages sometimes rely on the definition of environment variablesfor their search paths (see explanation of @code{--search-paths} below).Any missing or possibly incorrect environment variable definitions arereported 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-namedvariants of a package, with expressions such as @code{(@@ (gnu packagesbase) guile-final)}.
Note that this option installs the first output of the specified package,which may be insufficient when needing a specific output of amultiple-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 theroot of their project source tree that can be used to test developmentsnapshots and create reproducible development environments (@pxref{Invokingguix 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 numberand/or output name in addition to the package name. For instance, @code{-rglibc:debug} would remove the @code{debug} output of @code{glibc}.
@item --upgrade[=@var{regexp} @dots{}]@itemx -u [@var{regexp} @dots{}]@cindex upgrading packagesUpgrade all the installed packages. If one or more @var{regexp}s arespecified, 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 inthe distribution currently installed. To update your distribution, youshould 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} upgradeany packages whose name matches a @var{regexp}. For example, to upgrade allpackages 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 manifestCreate a new generation of the profile from the manifest object returned bythe Scheme code in @var{file}.
This allows you to @emph{declare} the profile's contents rather thanconstructing it through a sequence of @code{--install} and similarcommands. The advantage is that @var{file} can be put under versioncontrol, copied to different machines to reproduce the same profile, and soon.
@c FIXME: Add reference to (guix profile) documentation when available.@var{file} must return a @dfn{manifest} object, which is roughly a list ofpackages:
@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->manifestIn 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 packagespecifications and let @code{specifications->manifest} look up thecorresponding 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, undoingRoll back to the previous @dfn{generation} of the profile---i.e., undo thelast transaction.
When combined with options such as @code{--install}, roll back occurs beforeany other actions.
When rolling back from the first generation that actually contains installedpackages, the profile is made to point to the @dfn{zeroth generation}, whichcontains no files apart from its own metadata.
After having rolled back, installing, removing, or upgrading packagesoverwrites previous future generations. Thus, the history of thegenerations in a profile is always linear.
@item --switch-generation=@var{pattern}@itemx -S @var{pattern}@cindex generationsSwitch 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 specifiednumber of generations. For example, if you want to return to the latestgeneration 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 ifa specified generation does not exist, the current generation will not bechanged.
@item --search-paths[=@var{kind}]@cindex search pathsReport environment variable definitions, in Bash syntax, that may be neededin order to use the set of installed packages. These environment variablesare used to specify @dfn{search paths} for files used by some of theinstalled packages.
For example, GCC needs the @code{CPATH} and @code{LIBRARY_PATH} environmentvariables to be defined so it can look for headers and libraries in theuser's profile (@pxref{Environment Variables,,, gcc, Using the GNU CompilerCollection (GCC)}). If GCC and, say, the C library are installed in theprofile, 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 beexact settings, or prefixes or suffixes of the current value of thesevariables. When omitted, @var{kind} defaults to @code{exact}.
This option can also be used to compute the @emph{combined} search paths ofseveral 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} wouldlead 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-collisionsAllow colliding packages in the new profile. Use at your own risk!
By default, @command{guix package} reports as an error @dfn{collisions} inthe profile. Collisions happen when two or more different versions orvariants of a given package end up in the profile.
@item --bootstrapUse the bootstrap Guile to build the profile. This option is only useful todistribution developers.
@end table
In addition to these actions, @command{guix package} supports the followingoptions to query the current state of a profile, or the availability ofpackages:
@table @option
@item --search=@var{regexp}@itemx -s @var{regexp}@cindex searching for packagesList the available packages whose name, synopsis, or description matches@var{regexp} (in a case-insensitive fashion), sorted by relevance. Printall 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,relevancename: jemallocversion: 4.5.0relevance: 6
name: glibcversion: 2.25relevance: 1
name: libgcversion: 7.6.0relevance: 1@end example
Similarly, to show the name of all the packages available under the terms ofthe 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 namename: gnubg@dots{}@end example
If we were to omit @code{-s game}, we would also get software packages thatdeal 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 forcryptographic libraries, filters out Haskell, Perl, Python, and Rubylibraries, 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 moreinformation 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,versionname: pythonversion: 2.7.6
name: pythonversion: 3.3.5@end example
You may also specify the full name of a package to only get details about aspecific version of it:@example$ guix package --show=python@@3.4 | recsel -p name,versionname: pythonversion: 3.4.3@end example


@item --list-installed[=@var{regexp}]@itemx -I [@var{regexp}]List the currently installed packages in the specified profile, with themost recently installed packages shown last. When @var{regexp} isspecified, 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 isinstalled (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 onlyinstalled packages whose name matches @var{regexp}.
For each package, print the following items separated by tabs: its name, itsversion string, the parts of the package (@pxref{Packages with MultipleOutputs}), and the source location of its definition.
@item --list-generations[=@var{pattern}]@itemx -l [@var{pattern}]@cindex generationsReturn a list of generations along with their creation dates; for eachgeneration, show the installed packages, with the most recently installedpackages 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 isinstalled (@pxref{Packages with Multiple Outputs}), and the location of thispackage 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 denotegeneration numbers. For instance, @code{--list-generations=1} returns thefirst one.
And @code{--list-generations=1,8,2} outputs three generations in thespecified order. Neither spaces nor trailing commas are allowed.
@item @emph{Ranges}. @code{--list-generations=2..9} prints thespecified generations and everything in between. Note that the start of arange 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 thesecond 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 theduration. For example, @code{--list-generations=20d} lists generations thatare 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 currentone.
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 thespecified 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, thezeroth 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, itsupports all the common build options (@pxref{Common Build Options}). Italso supports package transformation options, such as @option{--with-source}(@pxref{Package Transformation Options}). However, note that packagetransformations are lost when upgrading; to preserve transformations acrossupgrades, you should define your own package variant in a Guile module andadd it to @code{GUIX_PACKAGE_PATH} (@pxref{Defining Packages}).
@node Substitutes@section Substitutes
@cindex substitutes@cindex pre-built binariesGuix supports transparent source/binary deployment, which means that it caneither build things locally, or download pre-built items from a server, orboth. We call these pre-built items @dfn{substitutes}---they aresubstitutes for local build results. In many cases, downloading asubstitute 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-builtpackage binaries, but source tarballs, for instance, which also result fromderivation 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 farmThe @code{@value{SUBSTITUTE-SERVER}} server is a front-end to an officialbuild farm that builds packages from Guix continuously for somearchitectures, and makes them available as substitutes. This is the defaultsource 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}}) orto 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 becausecommunications are encrypted; conversely, using HTTP makes allcommunications visible to an eavesdropper, who could use the informationgathered to determine, for instance, whether your system has unpatchedsecurity vulnerabilities.
Substitutes from the official build farm are enabled by default when usingthe Guix System Distribution (@pxref{GNU Distribution}). However, they aredisabled by default when using Guix on a foreign distribution, unless youhave explicitly enabled them via one of the recommended installation steps(@pxref{Installation}). The following paragraphs describe how to enable ordisable substitutes for the official build farm; the same procedure can alsobe 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 substitutesTo 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 genuinesubstitutes.
The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along withGuix, in @code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where@var{prefix} is the installation prefix of Guix. If you installed Guix fromsource, 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 NoteSimilarly, the @file{hydra.gnu.org.pub} file contains the public key of anindependent 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} shouldchange from something like:
@example$ guix build emacs --dry-runThe 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
@noindentto something like:
@example$ guix build emacs --dry-run112.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
@noindentThis indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} areusable and will be downloaded, when possible, for future builds.
@cindex substitutes, how to disableThe substitute mechanism can be disabled globally by running@code{guix-daemon} with @code{--no-substitutes} (@pxref{Invokingguix-daemon}). It can also be disabled temporarily by passing the@code{--no-substitutes} option to @command{guix package}, @command{guixbuild}, and other command-line tools.
@node Substitute Authentication@subsection Substitute Authentication
@cindex digital signaturesGuix detects and raises an error when attempting to use a substitute thathas been tampered with. Likewise, it ignores substitutes that are notsigned, or that are not signed by one of the keys listed in the ACL.
There is one exception though: if an unauthorized server providessubstitutes that are @emph{bit-for-bit identical} to those provided by anauthorized server, then the unauthorized server becomes eligible fordownloads. For example, assume we have chosen two substitute servers withthis option:
@example--substitute-urls="https://a.example.orghttps://b.example.org"@end example
@noindent@cindex reproducible buildsIf 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 itcomes first in the list and can be considered a mirror of@code{b.example.org}. In practice, independent build machines usuallyproduce the same binaries, thanks to bit-reproducible builds (see below).
When using HTTPS, the server's X.509 certificate is @emph{not} validated (inother words, the server is not authenticated), contrary to what HTTPSclients such as Web browsers usually do. This is because Guix authenticatessubstitute information itself, as explained above, which is what we careabout (whereas X.509 certificates are about authenticating bindings betweendomain names and public keys.)
@node Proxy Settings@subsection Proxy Settings
@vindex http_proxySubstitutes 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 thesubstitution attempt will fail. This can happen for a variety of reasons:the substitute server might be offline, the substitute may recently havebeen 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 thederivation 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 beperformed, and the derivation is considered to have failed. However, if@code{--fallback} was given, then Guix will attempt to build the derivationlocally, and the success or failure of the derivation depends on the successor failure of the local build. Note that when substitutes are disabled orno substitute is available for the derivation in question, a local buildwill @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 tryrunning 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 binariesToday, each individual's control over their own computing is at the mercy ofinstitutions, corporations, and groups with enough power and determinationto subvert the computing infrastructure and exploit its weaknesses. Whileusing @code{@value{SUBSTITUTE-SERVER}} substitutes can be convenient, weencourage users to also build on their own, or even run their own buildfarm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an interestingtarget. One way to help is by publishing the software you build using@command{guix publish} so that others have one more choice of server todownload 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 orderivation should yield bit-identical results. Thus, through a diverse setof independent package builds, we can strengthen the integrity of oursystems. The @command{guix challenge} command aims to help users assesssubstitute servers, and to assist developers in finding out aboutnon-deterministic package builds (@pxref{Invoking guix challenge}).Similarly, the @option{--check} option of @command{guix build} allows usersto check whether previously-installed substitutes are genuine by rebuildingthem locally (@pxref{build-check, @command{guix build --check}}).
In the future, we want Guix to have support to publish and retrieve binariesto/from other users, in a peer-to-peer fashion. If you would like todiscuss 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., thesource package leads to exactly one directory in the store. When running@command{guix package -i glibc}, one installs the default output of the GNUlibc package; the default output is called @code{out}, but its name can beomitted as shown in this command. In this particular case, the defaultoutput 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 filesproduced from a single source package into separate outputs. For instance,the GLib C library (used by GTK+ and related packages) installs more than20 MiB of reference documentation as HTML pages. To save space for userswho do not need it, the documentation goes to a separate output, called@code{doc}. To install the main GLib output, which contains everything butthe documentation, one would run:
@exampleguix package -i glib@end example
@cindex documentationThe command to install its documentation is:
@exampleguix package -i glib:doc@end example
Some packages install programs with different ``dependency footprints''.For instance, the WordNet package installs both command-line tools andgraphical user interfaces (GUIs). The former depend solely on the Clibrary, whereas the latter depend on Tcl/Tk and the underlying Xlibraries. In this case, we leave the command-line tools in the defaultoutput, whereas the GUIs are in a separate output. This allows users who donot need the GUIs to save space. The @command{guix size} command can helpfind out about such situations (@pxref{Invoking guix size}). @command{guixgraph} 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 andpossibly header files, @code{bin} for stand-alone programs, and @code{debug}for debugging information (@pxref{Installing Debugging Files}). The outputsof a packages are listed in the third column of the output of @command{guixpackage --list-available} (@pxref{Invoking guix package}).

@node Invoking guix gc@section Invoking @command{guix gc}
@cindex garbage collector@cindex disk spacePackages that are installed, but not used, may be @dfn{garbage-collected}.The @command{guix gc} command allows users to explicitly run the garbagecollector to reclaim space from the @file{/gnu/store} directory. It is the@emph{only} way to remove files from @file{/gnu/store}---removing files ordirectories manually may break it beyond repair!
@cindex GC roots@cindex garbage collector rootsThe garbage collector has a set of known @dfn{roots}: any file under@file{/gnu/store} reachable from a root is considered @dfn{live} and cannotbe deleted; any other file is considered @dfn{dead} and may be deleted. Theset of garbage collector roots (``GC roots'' for short) includes defaultuser profiles; by default, the symlinks under @file{/var/guix/gcroots}represent these GC roots. New GC roots can be added with @command{guixbuild --root}, for example (@pxref{Invoking guix build}). The @command{guixgc --list-roots} command lists them.
Prior to running @code{guix gc --collect-garbage} to make space, it is oftenuseful to remove old generations from user profiles; that way, old packagebuilds referenced by those generations can be reclaimed. This is achievedby running @code{guix package --delete-generations} (@pxref{Invoking guixpackage}).
Our recommendation is to run a garbage collection periodically, or when youare short on disk space. For instance, to guarantee that at least 5@tie{}GBare available on your disk, simply run:
@exampleguix 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 orre-download software that is ``dead'' from the GC viewpoint but that isnecessary 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 usedto garbage-collect any dead files (the default), to delete specific files(the @code{--delete} option), to print garbage-collector information, or formore 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 andsub-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{Blocksize, 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}, asdescribed above.
When @var{free} or more is already available in @file{/gnu/store}, donothing and exit immediately.
@item --delete-generations[=@var{duration}]@itemx -d [@var{duration}]Before starting the garbage collection process, delete all the generationsolder than @var{duration}, for all the user profiles; when run as root, thisapplies to all the profiles @emph{of all the users}.
For example, this command deletes all the generations of all your profilesthat are older than 2 months (except generations that are current), and thenproceeds to free space until at least 10 GiB are available:
@exampleguix gc -d 2m -F 10G@end example
@item --delete@itemx -DAttempt to delete all the store files and directories specified asarguments. This fails if some of the files are not in the store, or if theyare still live.
@item --list-failuresList 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-rootsList the GC roots owned by the user; when run as root, list @emph{all} theGC roots.
@item --clear-failuresRemove 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-deadShow the list of dead files and directories still present in thestore---i.e., files and directories no longer reachable from any root.
@item --list-liveShow 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 dependenciesList the references (respectively, the referrers) of store files given asarguments.
@item --requisites@itemx -R@cindex closureList the requisites of the store files passed as arguments. Requisitesinclude the store files themselves, their references, and the references ofthese, 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 ofan element. @xref{Invoking guix graph}, for a tool to visualize the graphof references.
@item --derivers@cindex derivationReturn the derivation(s) leading to the given store items(@pxref{Derivations}).
For example, this command:
@exampleguix gc --derivers `guix package -I ^emacs$ | cut -f4`@end example
@noindentreturns the @file{.drv} file(s) leading to the @code{emacs} packageinstalled in your profile.
Note that there may be zero matching @file{.drv} files, for instance becausethese files have been garbage-collected. There can also be more than onematching @file{.drv} due to fixed-output derivations.@end table
Lastly, the following options allow you to check the integrity of the storeand to control disk usage.
@table @option
@item --verify[=@var{options}]@cindex integrity, of the store@cindex integrity checkingVerify the integrity of the store.
By default, make sure that all the store items marked as valid in thedatabase of the daemon actually exist in @file{/gnu/store}.
When provided, @var{options} must be a comma-separated list containing oneor more of @code{contents} and @code{repair}.
When passing @option{--verify=contents}, the daemon computes the contenthash 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 fromUsing @option{--verify=repair} or @option{--verify=contents,repair} causesthe daemon to try to repair corrupt store items by fetching substitutes forthem (@pxref{Substitutes}). Because repairing is not atomic, and thuspotentially dangerous, it is available only to the system administrator. Alightweight alternative, when you know exactly which items in the store arecorrupt, is @command{guix build --repair} (@pxref{Invoking guix build}).
@item --optimize@cindex deduplicationOptimize the store by hard-linking identical files---this is@dfn{deduplication}.
The daemon performs deduplication after each successful build or archiveimport, unless it was started with @code{--disable-deduplication}(@pxref{Invoking guix-daemon, @code{--disable-deduplication}}). Thus, thisoption 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 pullPackages are installed or upgraded to the latest version available in thedistribution currently available on your local machine. To update thatdistribution, 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, thoughthis can be customized.
On completion, @command{guix package} will use packages and package versionsfrom this just-retrieved copy of Guix. Not only that, but all the Guixcommands 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 theeffect 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 theversion 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 sureto add it to the beginning of your search path so that you use the latestversion, and similarly for the Info manual (@pxref{Documentation}):
@exampleexport 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 generationsproduced by @command{guix pull}, along with details about their provenance:
@example$ guix pull -lGeneration 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 todescribe the current status of Guix.
This @code{~/.config/guix/current} profile works like any other profilecreated by @command{guix package} (@pxref{Invoking guix package}). That is,you can list generations, roll back to the previous generation---i.e., theprevious Guix---and so on:
@example$ guix package -p ~/.config/guix/current --roll-backswitched from generation 3 to 2$ guix package -p ~/.config/guix/current --delete-generations=1deleting /var/guix/profiles/per-user/charlie/current-guix-1-link@end example
The @command{guix pull} command is usually invoked with no arguments, but itsupports 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}, atthe given @var{commit} (a valid Git commit ID represented as a hexadecimalstring), or @var{branch}.
@cindex @file{channels.scm}, configuration file@cindex configuration file for channelsThese options are provided for convenience, but you can also specify yourconfiguration 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 codethat evaluates to a list of channel objects. @xref{Channels}, for moreinformation.
@item --news@itemx -NDisplay the list of packages added or upgraded since the previousgeneration.
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{guixpackage --list-generations} (@pxref{Invoking guix package}).
@xref{Invoking guix describe}, for a way to display information about thecurrent generation only.
@item --profile=@var{profile}@itemx -p @var{profile}Use @var{profile} instead of @file{~/.config/guix/current}.
@item --dry-run@itemx -nShow which channel commit(s) would be used and what would be built orsubstituted 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 thesystem type of the build host.
@item --verboseProduce verbose output, writing build logs to the standard error output.
@item --bootstrapUse the bootstrap Guile to build the latest Guix. This option is onlyuseful to Guix developers.@end table
The @dfn{channel} mechanism allows you to instruct @command{guix pull} whichrepository 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 anddeploys Guix itself from the official GNU@tie{}Guix repository. This can becustomized by defining @dfn{channels} in the@file{~/.config/guix/channels.scm} file. A channel specifies a URL andbranch of a Git repository to be deployed, and @command{guix pull} can beinstructed to pull from one or more channels. In other words, channels canbe 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---itscommand-line tools as well as its package collection---should bedownloaded. For instance, suppose you want to update from your own copy ofthe 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
@noindentFrom 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 packagesYou can also specify @emph{additional channels} to pull from. Let's say youhave a bunch of custom package variants or personal packages that you thinkwould make little sense to contribute to the Guix project, but would like tohave these packages transparently available to you at the command line. Youwould first write modules containing those package definitions(@pxref{Package Modules}), maintain them in a Git repository, and then youand 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 WarningBefore you, dear user, shout---``woow this is @emph{soooo coool}!''---andpublish your personal channel to the world, we would like to share a fewwords of caution:
@itemize@itemBefore publishing a channel, please consider contributing your packagedefinitions to Guix proper (@pxref{贡献}). Guix as a project isopen to free software of all sorts, and packages in Guix proper are readilyavailable to all Guix users and benefit from the project's quality assuranceprocess.
@itemWhen you maintain package definitions outside Guix, we, Guix developers,consider that @emph{the compatibility burden is on you}. Remember thatpackage modules and package definitions are just Scheme code that usesvarious programming interfaces (APIs). We want to remain free to changethese APIs to keep improving Guix, possibly in ways that break yourchannel. We never change APIs gratuitously, but we will @emph{not} committo freezing APIs either.
@itemCorollary: if you're using an external channel and that channel breaks,please @emph{report the issue to the channel authors}, not to the Guixproject.@end itemize
You've been warned! Having said this, we believe external channels are apractical way to exert your freedom to augment Guix' package collection andto share your improvements, which are basic tenets of@uref{https://www.gnu.org/philosophy/free-sw.html,free software}. Pleaseemail 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 Guixchannel(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
@noindentNote 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{guixpull} builds not only Guix but also the package modules from your ownrepository. The result in @file{~/.config/guix/current} is the union ofGuix 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
@noindentThe output of @command{guix pull} above shows that Generation@tie{}19includes 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 defaultchannel.
To create a channel, create a Git repository containing your own packagemodules and make it available. The repository can contain anything, but auseful channel will contain Guile modules that export packages. Once youstart using a channel, Guix will behave as if the root directory of thatchannel's Git repository has been added to the Guile load path (@pxref{LoadPaths,,, guile, GNU Guile Reference Manual}). For example, if your channelcontains a file at @file{my-packages/my-tools.scm} that defines a Guilemodule, then the module will be available under the name @code{(my-packagesmy-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 otherchannels. They can declare their channel to be dependent on other channelsin a meta-data file @file{.guix-channel}, which is to be placed in the rootof 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 otherchannels, which will both be fetched automatically. The modules provided bythe channel will be compiled in an environment where the modules of allthese declared channels are available.
For the sake of reliability and maintainability, you should avoiddependencies on channels that you don't control, and you should aim to keepthe number of dependencies to a minimum.
@subsection Replicating Guix
@cindex pinning, channels@cindex replicating Guix@cindex reproducibility, of GuixThe @command{guix pull --list-generations} output above shows preciselywhich commits were used to build this instance of Guix. We can thusreplicate it, say, on another machine, by providing a channel specificationin @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 thislist of channels directly (@pxref{Invoking guix describe}).
At this point the two machines run the @emph{exact same Guix}, with accessto 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 thesame command on the other machine. It also means both machines have accessto all the source code of Guix and, transitively, to all the source code ofevery package it defines.
This gives you super powers, allowing you to track the provenance of binaryartifacts with very fine grain, and to reproduce software environments atwill---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 NoteThe 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 revisionsSometimes you might need to mix packages from the revision of Guix you'recurrently running with packages available in a different revision of Guix.Guix @dfn{inferiors} allow you to achieve that by composing different Guixrevisions in arbitrary ways.
@cindex inferior packagesTechnically, an ``inferior'' is essentially a separate Guix processconnected to your main Guix process through a REPL (@pxref{Invoking guixrepl}). The @code{(guix inferior)} module allows you to create inferiorsand to communicate with them. It also provides a high-level interface tobrowse and manipulate the packages that an inferior provides---@dfn{inferiorpackages}.
When combined with channels (@pxref{Channels}), inferiors provide a simpleway to interact with a separate revision of Guix. For example, let's assumeyou want to install in your profile the current @code{guile} package, alongwith the @code{guile-json} as it existed in an older revision ofGuix---perhaps because the newer @code{guile-json} has an incompatible APIand you want to run your code against the old API@. To do that, you couldwrite a manifest for use by @code{guix package --manifest} (@pxref{Invokingguix package}); in that manifest, you would create an inferior for that oldGuix 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 thechannel you specified before it can create the inferior; subsequent runswill be much faster because the Guix revision will be cached.
The @code{(guix inferior)} module provides the following procedures to openan inferior:
@deffn {Scheme Procedure} inferior-for-channels @var{channels} @ [#:cache-directory] [#:ttl] Return an inferior for @var{channels}, a list ofchannels. Use the cache at @var{cache-directory}, where entries can bereclaimed after @var{ttl} seconds. This procedure opens a new connection tothe 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 packagesThe procedures listed below allow you to obtain and manipulate inferiorpackages.
@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 prefixedby @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 callthese procedures.@end deffn
Inferior packages can be used transparently like any other package orfile-like object in G-expressions (@pxref{G-Expressions}). They are alsotransparently handled by the @code{packages->manifest} procedure, which iscommonly use in manifests (@pxref{Invoking guix package, the@option{--manifest} option of @command{guix package}}). Thus you can insertan 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 GuixOften you may want to answer questions like: ``Which revision of Guix am Iusing?'' or ``Which channels am I using?'' This is useful information inmany situations: if you want to @emph{replicate} an environment on adifferent machine or user account, if you want to report a bug or todetermine what change in the channels you are using caused it, or if youwant 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{guixdescribe} displays the channel(s) that it was built from, including theirrepository URL and commit IDs (@pxref{Channels}):
@example$ guix describeGeneration 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 inspirit to @command{git describe}; the output is also similar to that of@command{guix pull --list-generations}, but limited to the currentgeneration (@pxref{Invoking guix pull, the @option{--list-generations}option}). Because the Git commit ID shown above unambiguously refers to asnapshot of Guix, this information is all it takes to describe the revisionof Guix you're using, and also to replicate it.
To make it easier to replicate Guix, @command{guix describe} can also beasked to return a list of channels instead of the human-readable descriptionabove:
@example$ guix describe -f channels(list (channel (name 'guix) (url "https://git.savannah.gnu.org/git/guix.git") (commit "e0fa68c7718fffd33d81af415279d6ddb518f727")))@end example
@noindentYou can save this to a file and feed it to @command{guix pull -C} on someother machine or at a later point in time, which will instantiate @emph{thisexact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).From there on, since you're able to deploy the same revision of Guix, youcan just as well @emph{replicate a complete software environment}. Wehumbly 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 asfollows:
@table @code@item --format=@var{format}@itemx -f @var{format}Produce output in the specified @var{format}, one of:
@table @code@item humanproduce human-readable output;@item channelsproduce a list of channel specifications that can be passed to @command{guixpull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invokingguix pull});@item json@cindex JSONproduce a list of channel specifications in JSON format;@item recutilsproduce 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 archiveThe @command{guix archive} command allows users to @dfn{export} files fromthe store into a single archive, and to later @dfn{import} them on a machinethat runs Guix. In particular, it allows store files to be transferred fromone machine to the store on another machine.
@quotation NoteIf you're looking for a way to produce archives in a format suitable fortools other than Guix, @pxref{Invoking guix pack}.@end quotation
@cindex exporting store itemsTo export store files as an archive to standard output, run:
@exampleguix archive --export @var{options} @var{specifications}...@end example
@var{specifications} may be either store file names or packagespecifications, as for @command{guix package} (@pxref{Invoking guixpackage}). For instance, the following command creates an archivecontaining the @code{gui} output of the @code{git} package and the mainoutput of @code{emacs}:
@exampleguix 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 thecommon build options (@pxref{Common Build Options}).
To transfer the @code{emacs} package to a machine connected over SSH, onewould run:
@exampleguix archive --export -r emacs | ssh the-machine guix archive --import@end example
@noindentSimilarly, a complete user profile may be transferred from one machine toanother like this:
@exampleguix archive --export -r $(readlink -f ~/.guix-profile) | \ ssh the-machine guix-archive --import@end example
@noindentHowever, note that, in both examples, all of @code{emacs} and the profile aswell 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 fromthe target store. The @command{guix copy} command simplifies and optimizesthis 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, whichis comparable in spirit to `tar', but with differences that make it moreappropriate for our purposes. First, rather than recording all Unixmetadata for each file, the nar format only mentions the file type (regular,directory, or symbolic link); Unix permissions and owner/group aredismissed. Second, the order in which directory entries are stored alwaysfollows 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, andthat digital signature is appended. When importing, the daemon verifies thesignature and rejects the import in case of an invalid signature or if thesigning key is not authorized.
The main options are:
@table @code@item --exportExport the specified store files or packages (see below.) Write theresulting archive to the standard output.
Dependencies are @emph{not} included in the output, unless@code{--recursive} is passed.
@item -r@itemx --recursiveWhen combined with @code{--export}, this instructs @command{guix archive} toinclude dependencies of the given items in the archive. Thus, the resultingarchive is self-contained: it contains the closure of the exported storeitems.
@item --importRead an archive from the standard input, and import the files listed thereininto the store. Abort if the archive has an invalid digital signature, orif it is signed by a public key not among the authorized keys (see@code{--authorize} below.)
@item --missingRead a list of store file names from the standard input, one per line, andwrite on the standard output the subset of these files missing from thestore.
@item --generate-key[=@var{parameters}]@cindex signing, archivesGenerate a new key pair for the daemon. This is a prerequisite beforearchives can be exported with @code{--export}. Note that this operationusually takes time, because it needs to gather enough entropy to generatethe 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 keyusing the Ed25519 curve is generated, or, for Libgcrypt versions before1.6.0, it is a 4096-bit RSA key. Alternatively, @var{parameters} canspecify @code{genkey} parameters suitable for Libgcrypt (@pxref{Generalpublic-key related Functions, @code{gcry_pk_genkey},, gcrypt, The LibgcryptReference Manual}).
@item --authorize@cindex authorizing, archivesAuthorize imports signed by the public key passed on standard input. Thepublic key must be in ``s-expression advanced format''---i.e., the sameformat 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-formats-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 alow-level operation needed in only very narrow use cases; see below.
For example, the following command extracts the substitute for Emacs servedby @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 theydo @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 archivecontents coming from possibly untrusted substitute servers.
@end table

@c *********************************************************************@node Development@chapter Development
@cindex software developmentIf you are a software developer, Guix provides tools that you should findhelpful---independently of the language you're developing in. This is whatthis chapter is about.
The @command{guix environment} command provides a convenient way to set up@dfn{development environments} containing all the dependencies and toolsnecessary to work on the software package of your choice. The @command{guixpack} command allows you to create @dfn{application bundles} that can beeasily 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 environmentThe purpose of @command{guix environment} is to assist hackers in creatingreproducible development environments without polluting their packageprofile. 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:
@exampleguix environment @var{options} @var{package}@dots{}@end example
The following example spawns a new shell set up for the development ofGNU@tie{}Guile:
@exampleguix 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 augmentedversion of the environment that @command{guix environment} was run in. Itcontains the necessary search paths for building the given package added tothe existing environment variables. To create a ``pure'' environment, inwhich the original environment variables have been unset, use the@code{--pure} option@footnote{Users sometimes wrongfully augment environmentvariables such as @code{PATH} in their @file{~/.bashrc} file. As aconsequence, when @code{guix environment} launches it, Bash may read@file{~/.bashrc}, thereby introducing ``impurities'' in these environmentvariables. 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 inthe shell it spawns; its value is the file name of the profile of thisenvironment. This allows users to, say, define a specific prompt fordevelopment environments in their @file{.bashrc} (@pxref{Bash StartupFiles,,, bash, The GNU Bash Reference Manual}):
@exampleif [ -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 theunion of the inputs for the given packages are used. For example, thecommand below spawns a shell where all of the dependencies of both Guile andEmacs are available:
@exampleguix environment guile emacs@end example
Sometimes an interactive shell session is not desired. An arbitrary commandmay be invoked by placing the @code{--} token to separate the command fromthe rest of the arguments:
@exampleguix environment guile -- make -j4@end example
In other situations, it is more convenient to specify the list of packagesneeded in the environment. For example, the following command runs@command{python} from an environment containing Python@tie{}2.7 and NumPy:
@exampleguix environment --ad-hoc python2-numpy python-2.7 -- python@end example
Furthermore, one might want the dependencies of a package and also someadditional packages that are not build-time or runtime dependencies, but areuseful when developing nonetheless. Because of this, the @code{--ad-hoc}flag is positional. Packages appearing before @code{--ad-hoc} areinterpreted as packages whose dependencies will be added to theenvironment. Packages appearing after are interpreted as packages that willbe added to the environment directly. For example, the following commandcreates a Guix development environment that additionally includes Git andstrace:
@exampleguix 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 ahost distro that is not Guix System, it is desirable to prevent access to@file{/usr/bin} and other system-wide resources from the developmentenvironment. For example, the following command spawns a Guile REPL in a``container'' where only the store and the current working directory aremounted:
@exampleguix environment --ad-hoc --container guile -- guile@end example
@quotation NoteThe @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 environmentsMake @var{file} a symlink to the profile for this environment, and registerit as a garbage collector root.
This is useful if you want to protect your environment from garbagecollection, to make it ``persistent''.
When this option is omitted, the environment is protected from garbagecollection only for the duration of the @command{guix environment} session.This means that next time you recreate the same environment, you could haveto rebuild or re-download packages. @xref{Invoking guix gc}, for more on GCroots.
@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:
@exampleguix environment -e '(@@ (gnu packages maths) petsc-openmpi)'@end example
starts a shell with the environment for this specific variant of the PETScpackage.
Running:
@exampleguix 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. Toselect other outputs, two element tuples can be specified:
@exampleguix 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 codewithin @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 objectreturned 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 manifestfiles.
@item --ad-hocInclude all specified packages in the resulting environment, as if an @i{adhoc} package were defined with them as inputs. This option is useful forquickly creating an environment without having to write a package expressionto contain the desired inputs.
For instance, the command:
@exampleguix environment --ad-hoc guile guile-sdl -- guile@end example
runs @command{guile} in an environment where Guile and Guile-SDL areavailable.
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 specificoutput---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{guixenvironment}. Packages appearing before @code{--ad-hoc} are interpreted aspackages whose dependencies will be added to the environment, the defaultbehavior. Packages appearing after are interpreted as packages that will beadded to the environment directly.
@item --pureUnset existing environment variables when building the new environment,except those specified with @option{--preserve} (see below.) This has theeffect of creating an environment in which search paths only contain packageinputs.
@item --preserve=@var{regexp}@itemx -E @var{regexp}When used alongside @option{--pure}, preserve the environment variablesmatching @var{regexp}---in other words, put them on a ``white list'' ofenvironment variables that must be preserved. This option can be repeatedseveral times.
@exampleguix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ -- mpirun @dots{}@end example
This example runs @command{mpirun} in a context where the only environmentvariables defined are @code{PATH}, environment variables whose name startswith @code{SLURM}, as well as the usual ``precious'' variables (@code{HOME},@code{USER}, etc.)
@item --search-pathsDisplay 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 containerRun @var{command} within an isolated container. The current workingdirectory outside the container is mapped inside the container.Additionally, unless overridden with @code{--user}, a dummy home directoryis 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. Insidethe container, it has the same UID and GID as the current user, unless@option{--user} is passed (see below.)
@item --network@itemx -NFor containers, share the network namespace with the host system.Containers created without this flag only have access to the loopbackdevice.
@item --link-profile@itemx -PFor 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 willfail and abort the environment if the directory already exists, which willcertainly be the case if @command{guix environment} was invoked in theuser's home directory.
Certain packages are configured to look in @code{~/.guix-profile} forconfiguration 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 theenvironment.
@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 thename @var{user}, the home directory will be @file{/home/@var{user}}, and nouser GECOS data will be copied. Furthermore, the UID and GID inside thecontainer 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 homedirectory will be remapped relative to @file{/home/USER}; this includes theautomatic mapping of the current working directory.
@example# will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/targetcd $HOME/wdguix 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 andeach of the user fields, this is only one useful component of a broaderprivacy/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 asthe read-only file system @var{target} within the container. If@var{target} is not specified, @var{source} is used as the target mountpoint in the container.
The example below spawns a Guile REPL in a container in which the user'shome directory is accessible read-only via the @file{/exchange} directory:
@exampleguix 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 asthe writable file system @var{target} within the container. If @var{target}is not specified, @var{source} is used as the target mount point in thecontainer.
The example below spawns a Guile REPL in a container in which the user'shome directory is accessible for both reading and writing via the@file{/exchange} directory:
@exampleguix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile@end example@end table
@command{guix environment} also supports all of the common build optionsthat @command{guix build} supports (@pxref{Common Build Options}) as well aspackage 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!) luckyenough 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 NoteIf you are looking for ways to exchange binaries among machines that alreadyrun 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 bundleThe @command{guix pack} command creates a shrink-wrapped @dfn{pack} or@dfn{software bundle}: it creates a tarball or some other archive containingthe binaries of the software you're interested in, and all itsdependencies. The resulting archive can be used on any machine that doesnot have Guix, and people can run the exact same binaries as those you havewith Guix. The pack itself is created in a bit-reproducible fashion, soanyone can verify that it really contains the build results that you pretendto be shipping.
For example, to create a bundle containing Guile, Emacs, Geiser, and alltheir 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 withall the relevant packages. The resulting tarball contains a @dfn{profile}with the three packages of interest; the profile is the same as would becreated by @command{guix package -i}. It is this mechanism that is used tocreate 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 findinconvenient. To work around it, you can create, say, a @file{/opt/gnu/bin}symlink to the profile:
@exampleguix pack -S /opt/gnu/bin=bin guile emacs geiser@end example
@noindentThat 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 theirmachine, and thus cannot unpack it in the root file system? In that case,you will want to use the @code{--relocatable} option (see below). Thisoption produces @dfn{relocatable binaries}, meaning they they can be placedanywhere in the file system hierarchy: in the example above, users canunpack your tarball in their home directory and directly run@file{./opt/gnu/bin/guile}.
@cindex Docker, build an image with guix packAlternatively, you can produce a pack in the Docker image format using thefollowing command:
@exampleguix pack -f docker guile emacs geiser@end example
@noindentThe 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/,Dockerdocumentation} for more information.
@cindex Singularity, build an image with guix pack@cindex SquashFS, build an image with guix packYet another option is to produce a SquashFS image with the followingcommand:
@exampleguix pack -f squashfs guile emacs geiser@end example
@noindentThe result is a SquashFS file system image that can either be mounted ordirectly be used as a file system container image with the@uref{http://singularity.lbl.gov, Singularity container executionenvironment}, 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 tarballThis is the default format. It produces a tarball containing all thespecified binaries and symlinks.
@item dockerThis produces a tarball that follows the@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,Docker Image Specification}.
@item squashfsThis produces a SquashFS image containing all the specified binaries andsymlinks, as well as empty mount points for virtual file systems likeprocfs.@end table
@cindex relocatable binaries@item --relocatable@itemx -RProduce @dfn{relocatable binaries}---i.e., binaries that can be placedanywhere 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 addsPRoot support, can be thought of as the abbreviation of ``ReallyRelocatable''. Neat, isn't it?}, relocatable binaries fall to back to PRootif user namespaces are unavailable, and essentially work anywhere---seebelow for the implications.
For example, if you create a pack containing Bash with:
@exampleguix pack -RR -S /mybin=bin bash@end example
@noindent...@: you can copy that pack to a machine that lacks Guix, and from yourhome directory as a normal user, run:
@exampletar xf pack.tar.gz./mybin/sh@end example
@noindentIn 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 isprobably the simplest way to deploy Guix-built software on a non-Guixmachine.
@quotation NoteBy default, relocatable binaries rely on the @dfn{user namespace} feature ofthe kernel Linux, which allows unprivileged users to mount or change root.Old versions of Linux did not support it, and some GNU/Linux distributionsturn it off.
To produce relocatable binaries that work even in the absence of usernamespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. Inthat case, binaries will try user namespace support and fall back to PRootif user namespaces are not supported.
The @uref{https://proot-me.github.io/,PRoot} program provides the necessarysupport for file system virtualization. It achieves that by using the@code{ptrace} system call on the running program. This approach has theadvantage to work without requiring special kernel support, but it incursrun-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{guixbuild}}).
@item --manifest=@var{file}@itemx -m @var{file}Use the packages contained in the manifest object returned by the Schemecode in @var{file}.
This has a similar purpose as the same-named option in @command{guixpackage} (@pxref{profile-manifest, @option{--manifest}}) and uses the samemanifest files. It allows you to define a collection of packages once anduse it both for creating profiles and for creating archives for use onmachines 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 thesystem type of the build host.
@item --target=@var{triplet}@cindex cross-compilationCross-build for @var{triplet}, which must be a valid GNU triplet, such as@code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNUconfiguration 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 canappear 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-provenanceSave 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 theusual package metadata---the name and version of each package, theirpropagated inputs, and so on. It is useful information to the recipient ofthe pack, who then knows how the pack was (supposedly) obtained.
This option is not enabled by default because, like timestamps, provenanceinformation contributes nothing to the build process. In other words, thereis an infinity of channel URLs and commit IDs that can lead to the samepack. Recording such ``silent'' metadata in the output thus potentiallybreaks the source-to-binary bitwise reproducibility property.
@item --localstatedir@itemx --profile-name=@var{name}Include the ``local state directory'', @file{/var/guix}, in the resultingpack, 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 asgarbage-collector roots (@pxref{Invoking guix gc}). Providing it in thepack means that the store is ``complete'' and manageable by Guix; notproviding it pack means that the store is ``dead'': items cannot be added toit 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 --bootstrapUse the bootstrap binaries to build the pack. This option is only useful toGuix 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 writehigh-level package definitions. These definitions refer to familiarpackaging concepts, such as the name and version of a package, its buildsystem, and its dependencies. These definitions can then be turned intoconcrete build actions.
Build actions are performed by the Guix daemon, on behalf of users. In astandard setup, the daemon has write access to the store---the@file{/gnu/store} directory---whereas users do not. The recommended setupalso has the daemon perform builds in chroots, under a specific build users,to minimize interference with the rest of the system.
@cindex derivationLower-level APIs are available to interact with the daemon and the store.To instruct the daemon to perform a build action, users actually provide itwith a @dfn{derivation}. A derivation is a low-level representation of thebuild actions to be taken, and the environment in which they shouldoccur---derivations are to package definitions what assembly is to Cprograms. 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-levelpackage 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 GNUdistribution are provided by Guile modules in the @code{(gnu packages@dots{})} name space@footnote{Note that packages under the @code{(gnupackages @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 GNUsystem, and @code{packages} identifies modules that define packages.}(@pxref{Modules, Guile modules,, guile, GNU Guile Reference Manual}). Forinstance, the @code{(gnu packages emacs)} module exports a variable named@code{emacs}, which is bound to a @code{<package>} object (@pxref{DefiningPackages}).
The @code{(gnu packages @dots{})} module name space is automatically scannedfor packages by the command-line tools. For instance, when running@code{guix package -i emacs}, all the @code{(gnu packages @dots{})} modulesare 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 pathUsers can store package definitions in modules with different names---e.g.,@code{(my-packages emacs)}@footnote{Note that the file name and module namemust match. For instance, the @code{(my-packages emacs)} module must bestored in a @file{my-packages/emacs.scm} file relative to the load pathspecified with @option{--load-path} or @code{GUIX_PACKAGE_PATH}.@xref{Modules and the File System,,, guile, GNU Guile Reference Manual}, fordetails.}. There are two ways to make these package definitions visible tothe user interfaces:
@enumerate@itemBy adding the directory containing your package modules to the search pathwith 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.
@itemBy defining a @dfn{channel} and configuring @command{guix pull} so that itpulls from it. A channel is essentially a Git repository containing packagemodules. @xref{Channels}, for more information on how to define and usechannels.@end enumerate
@code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
@defvr {Environment Variable} GUIX_PACKAGE_PATHThis is a colon-separated list of directories to search for additionalpackage modules. Directories listed in this variable take precedence overthe own modules of the distribution.@end defvr
The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: eachpackage is built based solely on other packages in the distribution. Theroot of this dependency graph is a small set of @dfn{bootstrap binaries},provided by the @code{(gnu packages bootstrap)} module. For moreinformation 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 anexample, the package definition, or @dfn{recipe}, for the GNU Hello packagelooks 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
@noindentWithout being a Scheme expert, the reader may have guessed the meaning ofthe various fields here. This expression binds the variable @code{hello} toa @code{<package>} object, which is essentially a record (@pxref{SRFI-9,Scheme records,, guile, GNU Guile Reference Manual}). This package objectcan 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 thepackage you are interested in from another repository, using the @code{guiximport} 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-linetools (@pxref{Package Modules}).
There are a few points worth noting in the above package definition:
@itemize@itemThe @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 thatthe source is a file to be downloaded over FTP or HTTP.
The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of theGNU mirrors defined in @code{(guix download)}.
The @code{sha256} field specifies the expected SHA256 hash of the file beingdownloaded. It is mandatory, and allows Guix to check the integrity of thefile. The @code{(base32 @dots{})} form introduces the base32 representationof the hash. You can obtain this information with @code{guix download}(@pxref{Invoking guix download}) and @code{guix hash} (@pxref{Invoking guixhash}).
@cindex patchesWhen needed, the @code{origin} form can also have a @code{patches} fieldlisting patches to be applied, and a @code{snippet} field giving a Schemeexpression to modify the source code.
@item@cindex GNU Build SystemThe @code{build-system} field specifies the procedure to build the package(@pxref{Build Systems}). Here, @var{gnu-build-system} represents thefamiliar GNU Build System, where packages may be configured, built, andinstalled with the usual @code{./configure && make && make check && makeinstall} command sequence.
@itemThe @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 quoteWhat about these quote (@code{'}) characters? They are Scheme syntax tointroduce a literal list; @code{'} is synonymous with @code{quote}.@xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual}, fordetails. Here the value of the @code{arguments} field is a list ofarguments 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 thebuild system (@pxref{Coding With Keywords,,, guile, GNU Guile ReferenceManual}).
@itemThe @code{inputs} field specifies inputs to the build process---i.e.,build-time or run-time dependencies of the package. Here, we define aninput 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-splicingAgain, @code{`} (a backquote, synonymous with @code{quasiquote}) allows usto introduce a literal list in the @code{inputs} field, while @code{,} (acomma, synonymous with @code{unquote}) allows us to insert a value in thatlist (@pxref{Expression Syntax, unquote,, guile, GNU Guile ReferenceManual}).
Note that GCC, Coreutils, Bash, and other essential tools do not need to bespecified as inputs here. Instead, @var{gnu-build-system} takes care ofensuring 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 thebuild 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 builtusing the @code{guix build} command-line tool (@pxref{Invoking guix build}),troubleshooting any build failures you encounter (@pxref{Debugging BuildFailures}). 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 forstyle conformance.@vindex GUIX_PACKAGE_PATHLastly, @pxref{Channels}, for information on how to extend the distributionby adding your own package definitions in a ``channel''.
Finally, updating the package definition to a new upstream version can bepartly automated by the @command{guix refresh} command (@pxref{Invoking guixrefresh}).
Behind the scenes, a derivation corresponding to the @code{<package>} objectis first computed by the @code{package-derivation} procedure. Thatderivation is stored in a @code{.drv} file under @file{/gnu/store}. Thebuild 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} mustbe 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 tothe daemon, which operates on the store (@pxref{The Store}).@end deffn
@noindent@cindex cross-compilationSimilarly, it is possible to compute a derivation that cross-builds apackage 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 andoperating system, such as @code{"mips64el-linux-gnu"} (@pxref{ConfigurationNames, GNU configuration triplets,, configure, GNU Configure and BuildSystem}).@end deffn
@cindex package transformations@cindex input rewriting@cindex dependency tree rewritingPackages can be manipulated in arbitrary ways. An example of a usefultransformation is @dfn{input rewriting}, whereby the dependency tree of apackage 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 packagepairs; the first element of each pair is the package to replace, and thesecond one is the replacement.
Optionally, @var{rewrite-name} is a one-argument procedure that takes thename of a package and returns its new name after rewrite.@end deffn
@noindentConsider 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
@noindentHere 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 exactlywhat the @option{--with-input} command-line option does (@pxref{PackageTransformation Options, @option{--with-input}}).
The following variant of @code{package-input-rewriting} can match packagesto 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 packagespecification such as @code{"gcc"} or @code{"guile@@2"}, and each proceduretakes 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 andnot 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 thepackages depended on and returns the resulting package. The procedure stopsrecursion 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} packageThis 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 filefetched from the Internet (@pxref{origin Reference}). It can also be anyother ``file-like'' object such as a @code{local-file}, which denotes a filefrom 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{BuildSystems}).
@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 packagesThese fields list dependencies of the package. Each one is a list oftuples, where each tuple has a label for the input (a string) as its firstelement, a package, origin, or derivation as its second element, andoptionally the name of the output thereof that should be used, whichdefaults to @code{"out"} (@pxref{Packages with Multiple Outputs}, for moreon 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 dependenciesThe distinction between @code{native-inputs} and @code{inputs} is necessarywhen considering cross-compilation. When cross-compiling, dependencieslisted in @code{inputs} are built for the @emph{target} architecture;conversely, dependencies listed in @code{native-inputs} are built for thearchitecture 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, orBison. @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 thespecified packages will be automatically installed alongside the packagethey belong to (@pxref{package-cmd-propagated-inputs, @command{guixpackage}}, for information on how @command{guix package} deals withpropagated inputs.)
For example this is necessary when a C/C++ library needs headers of anotherlibrary 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 languagesthat 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 codethey 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 MultipleOutputs}, 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-pathenvironment 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}, fordetails.
@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 packagesThe license of the package; a value from @code{(guix licenses)}, or a listof 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 wheninheriting from another package, in which case this field is notautomatically corrected.@end table@end deftp
@deffn {Scheme Syntax} this-packageWhen used in the @emph{lexical scope} of a package field definition, thisidentifier resolves to the package being defined.
The example below shows how to add a package as a native input of itselfwhen 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} originThis 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 URLrepresented 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 revisionspecified 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-32string.
You can obtain this information using @code{guix download} (@pxref{Invokingguix 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 thesource is fetched from a URL, the file name from the URL will be used. Forversion control checkouts, it is recommended to provide the file nameexplicitly 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 dependon 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 inthe 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, suchas GNU@tie{}Patch.
@item @code{modules} (default: @code{'()})A list of Guile modules that should be loaded during the patching processand 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 systemEach package definition specifies a @dfn{build system} and arguments forthat build system (@pxref{Defining Packages}). This @code{build-system}field represents the build procedure of the package, as well as implicitdependencies of that build procedure.
Build systems are @code{<build-system>} objects. The interface to createand 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 theinputs of that package, including some that were implicitly added by thebuild system. This intermediate representation is then compiled to aderivation (@pxref{Derivations}).
Build systems accept an optional list of @dfn{arguments}. In packagedefinitions, 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 GuileReference Manual}). The value of these arguments is usually evaluated inthe @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 thestandard build procedure for GNU and many other packages. It is provided bythe @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 phasesIn a nutshell, packages using it are configured, built, and installed withthe usual @code{./configure && make && make check && make install} commandsequence. In practice, a few additional steps are often needed. All thesesteps are split up in separate @dfn{phases}, notably@footnote{Please see the@code{(guix build gnu-build-system)} modules for more details about thebuild phases.}:
@table @code@item unpackUnpack the source tarball, and change the current directory to the extractedsource tree. If the source is actually a directory, copy it to the buildtree, and enter that directory.
@item patch-source-shebangsPatch shebangs encountered in source files so they refer to the right storefile names. For instance, this changes @code{#!/bin/sh} to@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
@item configureRun 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 buildRun @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 checkRun @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{makecheck -j}.
@item installRun @code{make install} with the flags listed in @code{#:make-flags}.
@item patch-shebangsPatch shebangs on the installed executable files.
@item stripStrip debugging symbols from ELF files (unless @code{#:strip-binaries?} isfalse), copying them to the @code{debug} output when available(@pxref{Installing Debugging Files}).@end table
@vindex %standard-phasesThe 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 theprocedure 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 forGNU packages is available. This includes tools such as GCC, libc,Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guixbuild-system gnu)} module for a complete list). We call these the@dfn{implicit inputs} of a package, because package definitions do not haveto mention them.@end defvr
Other @code{<build-system>} objects are defined to support other conventionsand tools used by free software packages. They inherit most of@var{gnu-build-system}, and differ mainly in the set of inputs implicitlyadded to the build process, and in the list of phases executed. Some ofthese build systems are listed below.
@defvr {Scheme Variable} ant-build-systemThis variable is exported by @code{(guix build-system ant)}. It implementsthe 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 providedby the @code{icedtea} package to the set of inputs. Different packages canbe specified with the @code{#:ant} and @code{#:jdk} parameters,respectively.
When the original package does not provide a suitable Ant build file, theparameter @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 thiscase the parameter @code{#:source-dir} can be used to specify the sourcesub-directory, defaulting to ``src''.
The @code{#:main-class} parameter can be used with the minimal ant buildfileto specify the main class of the resulting jar. This makes the jar fileexecutable. The @code{#:test-include} parameter can be used to specify thelist 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 astests.
The parameter @code{#:build-target} can be used to specify the Ant task thatshould be run during the @code{build} phase. By default the ``jar'' taskwill be run.
@end defvr
@defvr {Scheme Variable} android-ndk-build-system@cindex Android distribution@cindex Android NDK build systemThis variable is exported by @code{(guix build-system android-ndk)}. Itimplements 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 theirlibraries to the subdirectory "lib" of the "out" output.
It's also assumed that the union of all the dependencies of a package has noconflicting files.
For the time being, cross-compilation is not supported - so right now thelibraries 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)}, implementbuild procedures for Common Lisp packages using@url{https://common-lisp.net/project/asdf/,``ASDF''}. ASDF is a systemdefinition facility for Common Lisp programs and libraries.
The @code{asdf-build-system/source} system installs the packages in sourceform, and can be loaded using any common lisp implementation, via ASDF. Theothers, such as @code{asdf-build-system/sbcl}, install binary systems in theformat which a particular implementation understands. These build systemscan also be used to produce executable programs, or lisp images whichcontain a set of packages pre-loaded.
The build system uses naming conventions. For binary packages, the packagename 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 thesame convention as python packages (see @ref{Python模块}), using the@code{cl-} prefix.
For binary packages, each system should be defined as a Guix package. Ifone package @code{origin} contains several systems, package variants can becreated 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 becalled in a build phase after the @code{create-symlinks} phase, so that thesystem which was just built can be used within the resulting image.@code{build-program} requires a list of Common Lisp expressions to be passedas the @code{#:entry-program} argument.
If the system is not defined within its own @code{.asd} file of the samename, then the @code{#:asd-file} parameter should be used to specify whichfile the system is defined in. Furthermore, if the package defines a systemfor its tests in a separate file, it will be loaded before the tests are runif it is specified by the @code{#:test-asd-file} parameter. If it is notset, 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 thenaming conventions suggest, the @code{#:asd-system-name} parameter can beused 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 supportsbuilds 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 dependenciesspecified in the @file{Carto.toml} file with inputs to the Guix package.The @code{install} phase installs the binaries, and it also installs thesource code and @file{Cargo.toml} file.@end defvr
@cindex Clojure (programming language)@cindex simple Clojure build system@defvr {Scheme Variable} clojure-build-systemThis variable is exported by @code{(guix build-system clojure)}. Itimplements a simple build procedure for @uref{https://clojure.org/,Clojure}packages using plain old @code{compile} in Clojure. Cross-compilation isnot 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 bespecified with the @code{#:source-dirs}, @code{#:test-dirs} and@code{#:jar-names} parameters, respectively. Compile directory and mainclass 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 thefollowing phases changed:
@table @code
@item buildThis phase calls @code{compile} in Clojure to compile source files and runs@command{jar} to create jars from both source files and compiled filesaccording to the include list and exclude list specified in@code{#:aot-include} and @code{#:aot-exclude}, respectively. The excludelist has priority over the include list. These lists consist of symbolsrepresenting Clojure libraries or the special keyword @code{#:all}representing all Clojure libraries found under the source directories. Theparameter @code{#:omit-source?} decides if source should be included intothe jars.
@item checkThis phase runs tests according to the include list and exclude listspecified 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} nowstands for all Clojure libraries found under the test directories. Theparameter @code{#:tests?} decides if tests should be run.
@item installThis phase installs all jars built previously.@end table
Apart from the above, this build system also contains an additional phase:
@table @code
@item install-docThis 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 thedocumentation directories specified in @code{#:doc-dirs} are installed aswell.@end table@end defvr
@defvr {Scheme Variable} cmake-build-systemThis variable is exported by @code{(guix build-system cmake)}. Itimplements 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. Whichpackage is used can be specified with the @code{#:cmake} parameter.
The @code{#:configure-flags} parameter is taken as a list of flags passed tothe @command{cmake} command. The @code{#:build-type} parameter specifies inabstract terms the flags passed to the compiler; it defaults to@code{"RelWithDebInfo"} (short for ``release mode with debugginginformation''), 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-systemThis variable is exported by @code{(guix build-system dune)}. It supportsbuilds of packages using @uref{https://dune.build/,Dune}, a build tool forthe 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 buildsystem.
It automatically adds the @code{dune} package to the set of inputs. Whichpackage is used can be specified with the @code{#:dune} parameter.
There is no @code{configure} phase because dune packages typically don'tneed to be configured. The @code{#:build-flags} parameter is taken as alist 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 apackage. 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 tobuild only one of them. This is equivalent to passing the @code{-p}argument to @code{dune}.@end defvr
@defvr {Scheme Variable} go-build-systemThis variable is exported by @code{(guix build-system go)}. It implements abuild procedure for Go packages using the standard@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,Gobuild 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} correspondsto the file system path expected by the package's build scripts and anyreferring packages, and provides a unique way to refer to a Go package. Itis typically based on a combination of the package source code's remote URIand file system hierarchy structure. In some cases, you will need to unpackthe package's source code to a different directory structure than the oneindicated by the import path, and @code{#:unpack-path} should be used insuch cases.
Packages that provide Go libraries should install their source code into thebuilt output. The key @code{#:install-source?}, which defaults to@code{#t}, controls whether or not the source code is installed. It can beset to @code{#f} for packages that only provide executable files.@end defvr
@defvr {Scheme Variable} glib-or-gtk-build-systemThis variable is exported by @code{(guix build-system glib-or-gtk)}. It isintended 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-wrapThe phase @code{glib-or-gtk-wrap} ensures that programs in @file{bin/} areable 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 thatappropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH} environmentvariables.
It is possible to exclude specific package outputs from that wrappingprocess by listing their names in the@code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful whenan output is known not to contain any GLib or GTK+ binaries, and wherewrapping would gratuitously add a dependency of that output on GLib andGTK+.
@item glib-or-gtk-compile-schemasThe 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 bespecified with the @code{#:glib} parameter.@end table
Both phases are executed after the @code{install} phase.@end defvr
@defvr {Scheme Variable} guile-build-systemThis build system is for Guile packages that consist exclusively of Schemecode 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{guildcompile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) andinstalls the @file{.scm} and @file{.go} files in the right place. It alsoinstalls 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 packagein their @code{native-inputs} field.@end defvr
@defvr {Scheme Variable} minify-build-systemThis variable is exported by @code{(guix build-system minify)}. Itimplements a minification procedure for simple JavaScript packages.
It adds @code{uglify-js} to the set of inputs and uses it to compress allJavaScript files in the @file{src} directory. A different minifier packagecan be specified with the @code{#:uglify-js} parameter, but it is expectedthat 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 alist of file names to feed to the minifier.@end defvr
@defvr {Scheme Variable} ocaml-build-systemThis variable is exported by @code{(guix build-system ocaml)}. Itimplements a build procedure for @uref{https://ocaml.org, OCaml} packages,which consists of choosing the correct set of commands to run for eachpackage. OCaml packages can expect many different commands to be run. Thisbuild system will try some of them.
When the package has a @file{setup.ml} file present at the top-level, itwill run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and@code{ocaml setup.ml -install}. The build system will assume that this filewas generated by @uref{http://oasis.forge.ocamlcore.org/,OASIS} and willtake care of setting the prefix and enabling tests if they are notdisabled. 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 andinstall phases.
When the package has a @file{configure} file, it is assumed that it is ahand-made configure script that requires a different argument format than inthe @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 andinstall phases with the @code{#:make-flags} key.
Finally, some packages do not have these files and use a somewhat standardlocation 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 ofproviding the path to the required findlib module. Additional flags can bepassed via the @code{#:build-flags} key. Install is taken care of by@command{opam-installer}. In this case, the @code{opam} package must beadded to the @code{native-inputs} field of the package definition.
Note that most OCaml packages assume they will be installed in the samedirectory as OCaml, which is not what we want in guix. In particular, theywill install @file{.so} files in their module's directory, which is usuallyfine because it is in the OCaml compiler directory. In guix though, theselibraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. Thisvariable 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-systemThis variable is exported by @code{(guix build-system python)}. Itimplements the more or less standard build procedure used by Pythonpackages, 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/}, ittakes 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 bebuilt for a specific version of the Python interpreter, which might benecessary if the package is only compatible with a single interpreterversion.
By default guix calls @code{setup.py} under control of @code{setuptools},much like @command{pip} does. Some packages are not compatible withsetuptools (and pip), thus you can disable this by setting the@code{#:use-setuptools} parameter to @code{#f}.@end defvr
@defvr {Scheme Variable} perl-build-systemThis variable is exported by @code{(guix build-system perl)}. It implementsthe standard build procedure for Perl packages, which either consists inrunning @code{perl Build.PL --prefix=/gnu/store/@dots{}}, followed by@code{Build} and @code{Build install}; or in running @code{perl Makefile.PLPREFIX=/gnu/store/@dots{}}, followed by @code{make} and @code{make install},depending on which of @code{Build.PL} or @code{Makefile.PL} is present inthe 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} invocationpasses 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-systemThis variable is exported by @code{(guix build-system r)}. It implementsthe build procedure used by @uref{http://r-project.org, R} packages, whichessentially 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 afterinstallation using the R function @code{tools::testInstalledPackage}.@end defvr
@defvr {Scheme Variable} rakudo-build-systemThis variable is exported by @code{(guix build-system rakudo)} It implementsthe 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 thebinaries, library files and the resources, as well as wrap the files underthe @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}. Whichperl6-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 bespecified with @code{#:zef} or removed by passing @code{#f} to the@code{with-zef?} parameter.@end defvr
@defvr {Scheme Variable} texlive-build-systemThis variable is exported by @code{(guix build-system texlive)}. It is usedto build TeX packages in batch mode with a specified engine. The buildsystem sets the @code{TEXINPUTS} variable to find all TeX source files inthe inputs.
By default it runs @code{luatex} on all files ending on @code{ins}. Adifferent 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. Thebuild system adds only @code{texlive-bin} and @code{texlive-latex-base}(both from @code{(gnu packages tex}) to the inputs. Both can be overriddenwith the arguments @code{#:texlive-bin} and @code{#:texlive-latex-base},respectively.
The @code{#:tex-directory} parameter tells the build system where to installthe built files under the texmf tree.@end defvr
@defvr {Scheme Variable} ruby-build-systemThis variable is exported by @code{(guix build-system ruby)}. It implementsthe 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 typicallyreferences a gem archive, since this is the format that Ruby developers usewhen releasing their software. The build system unpacks the gem archive,potentially patches the source, runs the test suite, repackages the gem, andinstalls it. Additionally, directories and tarballs may be referenced toallow building unreleased gems from Git or a traditional source releasetarball.
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-systemThis variable is exported by @code{(guix build-system waf)}. It implementsa build procedure around the @code{waf} script. The commonphases---@code{configure}, @code{build}, and @code{install}---areimplemented by passing their names as arguments to the @code{waf} script.
The @code{waf} script is executed by the Python interpreter. Which Pythonpackage is used to run the script can be specified with the @code{#:python}parameter.@end defvr
@defvr {Scheme Variable} scons-build-systemThis variable is exported by @code{(guix build-system scons)}. Itimplements the build procedure used by the SCons software constructiontool. This build system runs @code{scons} to build the package, @code{sconstest} 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 canbe specified by selecting the appropriate SCons package with the@code{#:scons} parameter.@end defvr
@defvr {Scheme Variable} haskell-build-systemThis variable is exported by @code{(guix build-system haskell)}. Itimplements the Cabal build procedure used by Haskell packages, whichinvolves running @code{runhaskell Setup.hs configure--prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}. Insteadof installing the package by running @code{runhaskell Setup.hs install}, toavoid trying to register libraries in the read-only compiler storedirectory, the build system uses @code{runhaskell Setup.hs copy}, followedby @code{runhaskell Setup.hs register}. In addition, the build systemgenerates the package documentation by running @code{runhaskell Setup.hshaddock}, unless @code{#:haddock? #f} is passed. Optional Haddockparameters can be passed with the help of the @code{#:haddock-flags}parameter. If the file @code{Setup.hs} is not found, the build system looksfor @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-systemThis variable is exported by @code{(guix build-system dub)}. It implementsthe Dub build procedure used by D packages, which involves running @code{dubbuild} and @code{dub run}. Installation is done by copying the filesmanually.
Which D compiler is used can be specified with the @code{#:ldc} parameterwhich defaults to @code{ldc}.@end defvr
@defvr {Scheme Variable} emacs-build-systemThis variable is exported by @code{(guix build-system emacs)}. Itimplements an installation procedure similar to the packaging system ofEmacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
It first creates the @code{@var{package}-autoloads.el} file, then it bytecompiles all Emacs Lisp files. Differently from the Emacs packaging system,the Info documentation files are moved to the standard documentationdirectory and the @file{dir} file is deleted. Each package is installed inits own directory under @file{share/emacs/site-lisp/guix.d}.@end defvr
@defvr {Scheme Variable} font-build-systemThis variable is exported by @code{(guix build-system font)}. It implementsan installation procedure for font packages where upstream providespre-compiled TrueType, OpenType, etc.@: font files that merely need to becopied into place. It copies font files to standard locations in the outputdirectory.@end defvr
@defvr {Scheme Variable} meson-build-systemThis variable is exported by @code{(guix build-system meson)}. Itimplements 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 ofinputs, 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 andlibraries when they are installed.
This build system is an extension of @var{gnu-build-system}, but with thefollowing phases changed to some specific for Meson:
@table @code
@item configureThe 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 buildThe phase runs @code{ninja} to build the package in parallel by default, butthis can be changed with @code{#:parallel-build?}.
@item checkThe phase runs @code{ninja} with the target specified in@code{#:test-target}, which is @code{"test"} by default.
@item installThe 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-runpathThis phase ensures that all binaries can find the libraries they need. Itsearches for required libraries in subdirectories of the package beingbuilt, and adds those to @code{RUNPATH} where needed. It also removesreferences to libraries left over from the build phase by@code{meson-for-build}, such as test dependencies, that aren't actuallyrequired for the program to run.
@item glib-or-gtk-wrapThis phase is the phase provided by @code{glib-or-gtk-build-system}, and itis not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
@item glib-or-gtk-compile-schemasThis phase is the phase provided by @code{glib-or-gtk-build-system}, and itis 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 phasesThis build system is an extension of @var{gnu-build-system}, but with thefollowing phases changed:
@table @code
@item configureThis phase configures the environment so that the Linux kernel's Makefilecan be used to build the external kernel module.
@item buildThis phase uses the Linux kernel's Makefile in order to build the externalkernel module.
@item installThis phase uses the Linux kernel's Makefile in order to install the externalkernel module.@end table
It is possible and useful to specify the Linux kernel to use for buildingthe module (in the "arguments" form of a package using thelinux-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 itprovides basically no support: it does not pull any implicit inputs, anddoes not have a notion of build phases.
@defvr {Scheme Variable} trivial-build-systemThis variable is exported by @code{(guix build-system trivial)}.
This build system requires a @code{#:builder} argument. This argument mustbe 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 beenbuilt successfully are stored---by default, @file{/gnu/store}.Sub-directories in the store are referred to as @dfn{store items} orsometimes @dfn{store paths}. The store has an associated database thatcontains 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 tothe daemon over a Unix-domain socket, send requests to it, and read theresult---these are remote procedure calls, or RPCs.
@quotation NoteUsers must @emph{never} modify files under @file{/gnu/store} directly. Thiswould lead to inconsistencies and break the immutability assumptions ofGuix's functional model (@pxref{Introduction}).
@xref{Invoking guix gc, @command{guix gc --verify}}, for information on howto check the integrity of the store and attempt recovery from accidentalmodifications.@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 tothe local daemon or to the URI specified by the @code{GUIX_DAEMON_SOCKET}environment variable.
@defvr {Environment Variable} GUIX_DAEMON_SOCKETWhen set, the value of this variable should be a file name or a URIdesignating the daemon endpoint. When it is a file name, it denotes aUnix-domain socket to connect to. In addition to file names, the supportedURI schemes are:
@table @code@item file@itemx unixThese 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 setupThese URIs denote connections over TCP/IP, without encryption norauthentication of the remote host. The URI must specify the host name andoptionally a port number (by default port 44146 is used):
@exampleguix://master.guix.example.org:1234@end example
This setup is suitable on local networks, such as clusters, where onlytrusted 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 instructit to listen for TCP connections (@pxref{Invoking guix-daemon,@code{--listen}}).
@item ssh@cindex SSH access to build daemonsThese URIs allow you to connect to a remote daemon over SSH@footnote{Thisfeature requires Guile-SSH (@pxref{Requirements}).}. A typical URL mightlook like this:
@examplessh://charlie@@guix.example.org:22@end example
As for @command{guix copy}, the usual OpenSSH client configuration files arehonored (@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 NoteThe ability to connect to remote build daemons is considered experimental asof @value{VERSION}. Please get in touch with us to share any problems orsuggestions 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 ofextra space on the file system so that the garbage collector can stilloperate should the disk become full. Return a server object.
@var{file} defaults to @var{%default-socket-path}, which is the normallocation 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-portThis variable is bound to a SRFI-39 parameter, which refers to the portwhere 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 itemsReturn @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, forinstance because it is the result of an aborted or failed build.)
A @code{&store-protocol-error} condition is raised if @var{path} is notprefixed 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 storepath. @var{references} is the list of store paths referred to by theresulting store path.@end deffn
@deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}Build @var{derivations} (a list of @code{<derivation>} objects or derivationpaths), 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 asmonadic versions of the above procedures, with the goal of making it moreconvenient to work with code that accesses the store (@pxref{The StoreMonad}).
@c FIXME@i{This section is currently incomplete.}
@node Derivations@section Derivations
@cindex derivationsLow-level build actions and the environment in which they are performed arerepresented by @dfn{derivations}. A derivation contains the followingpieces of information:
@itemize@itemThe outputs of the derivation---derivations produce at least one file ordirectory in the store, but may produce more.
@item@cindex build-time dependencies@cindex dependencies, build-timeThe inputs of the derivations---i.e., its build-time dependencies---whichmay be other derivations or plain files in the store (patches, buildscripts, etc.)
@itemThe system type targeted by the derivation---e.g., @code{x86_64-linux}.
@itemThe file name of a build script in the store, along with the arguments to bepassed.
@itemA list of environment variables to be defined.
@end itemize
@cindex derivation pathDerivations allow clients of the daemon to communicate build actions to thestore. They exist in two forms: as an in-memory representation, both on theclient- 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 toperform the build actions they prescribe (@pxref{The Store}).
@cindex fixed-output derivationsOperations such as file downloads and version-control checkouts for whichthe expected content hash is known in advance are modeled as@dfn{fixed-output derivations}. Unlike regular derivations, the outputs ofa fixed-output derivation are independent of its inputs---e.g., a sourcecode download produces the same result regardless of the download method andtools being used.
@cindex references@cindex run-time dependencies@cindex dependencies, run-timeThe 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 isautomatically computed by the build daemon by scanning all the files in theoutputs.
The @code{(guix derivations)} module provides a representation ofderivations as Scheme objects, along with procedures to create and otherwisemanipulate derivations. The lowest-level primitive to create a derivationis 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 givenarguments, and return the resulting @code{<derivation>} object.
When @var{hash} and @var{hash-algo} are given, a @dfn{fixed-outputderivation} is created---i.e., one whose result is known in advance, such asa file download. If, in addition, @var{recursive?} is true, then that fixedoutput may be an executable file or a directory and @var{hash} must be thehash of an archive containing this output.
When @var{references-graphs} is true, it must be a list of file name/storepath pairs. In that case, the reference graph of each store path isexported in the build environment in the corresponding file, in a simpletext format.
When @var{allowed-references} is true, it must be a list of store items oroutputs that the derivation's output may refer to. Likewise,@var{disallowed-references}, if true, must be a list of things the outputsmay @emph{not} refer to.
When @var{leaked-env-vars} is true, it must be a list of strings denotingenvironment variables that are allowed to ``leak'' from the daemon'senvironment to the build environment. This is only applicable tofixed-output derivations---i.e., when @var{hash} is true. The main use isto allow variables such as @code{http_proxy} to be passed to derivationsthat download files.
When @var{local-build?} is true, declare that the derivation is not a goodcandidate for offloading and should rather be built locally (@pxref{DaemonOffload Setup}). This is the case for small derivations where the costs ofdata transfers would outweigh the benefits.
When @var{substitutable?} is false, declare that substitutes of thederivation's output should not be used (@pxref{Substitutes}). This isuseful, for instance, when building packages that capture details of thehost CPU instruction set.
@var{properties} must be an association list describing ``properties'' ofthe derivation. It is kept as-is, uninterpreted, in the derivation.@end deffn
@noindentHere'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 Bashexecutable 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 betterapproach is to write build scripts in Scheme, of course! The best course ofaction for that is to write the build code as a ``G-expression'', and topass it to @code{gexp->derivation}. For more information,@pxref{G-Expressions}.
Once upon a time, @code{gexp->derivation} did not exist and constructingderivations with build code written in Scheme was achieved with@code{build-expression->derivation}, documented below. This procedure isnow 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 thatexecutes 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 searchpath to be copied in the store, compiled, and made available in the loadpath 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 alist of output/path pairs, and where @code{%build-inputs} is bound to a listof string/output-path pairs made from @var{inputs}. Optionally,@var{env-vars} is a list of string pairs specifying the name and value ofenvironment variables visible to the builder. The builder terminates bypassing 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
@noindentHere's an example of a single-output derivation that creates a directorycontaining 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 sectionsall take an open connection to the build daemon as their first argument.Although the underlying model is functional, they either have side effectsor depend on the current state of the store.
The former is inconvenient: the connection to the build daemon has to becarried around in all those functions, making it impossible to composefunctions that do not take that parameter with functions that do. Thelatter can be problematic: since store operations have side effects and/ordepend on external state, they have to be properly sequenced.
@cindex monadic values@cindex monadic functionsThis is where the @code{(guix monads)} module comes in. This moduleprovides a framework for working with @dfn{monads}, and a particularlyuseful monad for our uses, the @dfn{store monad}. Monads are a constructthat allows two things: associating ``context'' with values (in our case,the context is the store), and building sequences of computations (herecomputations include accesses to the store). Values in a monad---valuesthat 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 amonadic 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 omittedsince 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, toexit 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 withnew ``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:
@examplescheme@@(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 areautomatically run through the store:
@examplescheme@@(guile-user)> ,enter-store-monadstore-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]> ,qscheme@@(guile-user)>@end example
@noindentNote 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 monadicprocedures @var{mproc}@dots{}@footnote{This operation is commonly referredto as ``bind'', but that name denotes an unrelated procedure in Guile. Thuswe 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 thebind operator, this can be thought of as ``unpacking'' the raw, non-monadicvalue ``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 itsresult will become the result of the @code{mlet} or @code{mlet*} when run inthe @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, returningthe result of the last expression. Every expression in the sequence must bea monadic expression.
This is akin to @code{mlet}, except that the return values of the monadicexpressions 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} isfalse, return @code{*unspecified*} in the current monad. Every expressionin 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} istrue, return @code{*unspecified*} in the current monad. Every expression inthe sequence must be a monadic expression.@end deffn
@cindex state monadThe @code{(guix monads)} module provides the @dfn{state monad}, which allowsan additional value---the state---to be @emph{threaded} through monadicprocedure calls.
@defvr {Scheme Variable} %state-monadThe state monad. Procedures in the state monad can access and change thestate that is threaded.
Consider the example below. The @code{square} procedure returns a value inthe state monad. It returns the square of its argument, but also incrementsthe 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 statevalue, which is the number of @code{square} calls.@end defvr
@deffn {Monadic Procedure} current-stateReturn 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 amonadic value.@end deffn
@deffn {Monadic Procedure} state-push @var{value}Push @var{value} to the current state, which is assumed to be a list, andreturn the previous state as a monadic value.@end deffn
@deffn {Monadic Procedure} state-popPop a value from the current state and return it as a monadic value. Thestate 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 initialstate. 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-monadThe store monad---an alias for @var{%state-monad}.
Values in the store monad encapsulate accesses to the store. When itseffect is needed, a value of the store monad must be ``evaluated'' bypassing 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 openstore 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 filecontaining @var{text}, a string. @var{references} is a list of store itemsthat 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 filecontaining @var{data}, a bytevector. @var{references} is a list of storeitems that the resulting binary file refers to; it defaults to the emptylist.@end deffn
@deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @ [#:recursive? #t] [#:select? (const #t)] Return the name of @var{file} onceinterned 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 addedrecursively; if @var{file} designates a flat file and @var{recursive?} istrue, 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'sabsolute file name and @var{stat} is the result of @code{lstat}; excludeentries 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-relatedmonadic procedures:
@deffn {Monadic Procedure} package-file @var{package} [@var{file}] @ [#:system (%current-system)] [#:target #f] @ [#:output "out"] Return as amonadic value in the absolute file name of @var{file} within the@var{output} directory of @var{package}. When @var{file} is omitted, returnthe 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 quotingSo we have ``derivations'', which represent a sequence of build actions tobe performed to produce an item in the store (@pxref{Derivations}). Thesebuild actions are performed when asking the daemon to actually build thederivations; they are run by the daemon in a container (@pxref{Invokingguix-daemon}).
@cindex strata of codeIt should come as no surprise that we like to write these build actions inScheme. When we do that, we end up with two @dfn{strata} of Schemecode@footnote{The term @dfn{stratum} in this context was coined by ManuelSerrano et al.@: in the context of their work on Hop. Oleg Kiselyov, whohas written insightful@url{http://okmij.org/ftp/meta-programming/#meta-scheme,essays and code onthis topic}, refers to this kind of code generation as @dfn{staging}.}: the``host code''---code that defines packages, talks to the daemon, etc.---andthe ``build code''---code that actually performs build actions, such asmaking directories, invoking @command{make}, etc.
To describe a derivation and its build actions, one typically needs to embedbuild code inside host code. It boils down to manipulating build code asdata, and the homoiconicity of Scheme---code has a direct representation asdata---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 ofS-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 aremajor differences:
@itemize@itemGexps are meant to be written to a file and run or manipulated by otherprocesses.
@itemWhen a high-level object such as a package or derivation is unquoted insidea gexp, the result is as if its output file name had been introduced.
@itemGexps carry information about the packages or derivations they refer to, andthese dependencies are automatically added as inputs to the build processesthat use them.@end itemize
@cindex lowering, of high-level objects in gexpsThis mechanism is not limited to package and derivation objects:@dfn{compilers} able to ``lower'' other high-level objects to derivations orfiles in the store can be defined, such that these objects can also beinserted into gexps. For example, a useful type of high-level objects thatcan be inserted in a gexp is ``file-like objects'', which make it easy toadd 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 derivationthat 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"} stringis substituted to the reference to the @var{coreutils} package in the actualbuild code, and @var{coreutils} is automatically made an input to thederivation. Likewise, @code{#$output} (equivalent to @code{(ungexpoutput)}) is replaced by a string containing the directory name of theoutput of the derivation.
@cindex cross compilationIn a cross-compilation context, it is useful to distinguish betweenreferences to the @emph{native} build of a package---that can run on thehost---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 nativepackage 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
@noindentIn 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 buildof @var{emacs} is referenced.
@cindex imported modules, for gexps@findex with-imported-modulesAnother gexp feature is @dfn{imported modules}: sometimes you want to beable 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
@noindentIn this example, the @code{(guix build utils)} module is automaticallypulled 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-closureUsually you want the @emph{closure} of the module to be imported---i.e., themodule itself and all the modules it depends on---rather than just themodule; failing to do that, attempts to use the module will fail because ofmissing dependent modules. The @code{source-module-closure} procedurecomputes 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-extensionsIn 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} packageavailable 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 ormore 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 supportedtypes, 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 objectsare substituted similarly.
If @var{obj} is another gexp, its contents are inserted and its dependenciesare 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} buildof @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 outputwhen @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 containinglist.
@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 ofthe @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} intheir execution environment.
Each item in @var{modules} can be the name of a module, such as @code{(guixbuild utils)}, or it can be a module name, followed by an arrow, followed bya file-like object:
@example`((guix build utils) (guix gcrypt) ((guix config) => ,(scheme-file "config.scm" #~(define-module @dots{}))))@end example
@noindentIn 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 directlydefined in @var{body}@dots{}, but not on those defined, say, in procedurescalled 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} intheir build and execution environment. @var{extensions} is typically a listof package objects such as those defined in the @code{(gnu packages guile)}module.
Concretely, the packages listed in @var{extensions} are added to the loadpath while compiling imported modules in @var{body}@dots{}; they are alsoadded 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 somederivation, or as plain files in the store. The monadic procedures belowallow you to do that (@pxref{The Store Monad}, for more information aboutmonads.)
@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} (agexp) 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, itis 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}. Itsmeaning 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 inthe load path during the execution of @var{exp}---e.g., @code{((guix buildutils) (guix build gnu-build-system))}.
@var{effective-version} determines the string to use when adding extensionsof @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 begrafted when applicable.
When @var{references-graphs} is true, it must be a list of tuples of one ofthe 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} isautomatically made an input of the build process of @var{exp}. In the buildenvironment, each @var{file-name} contains the reference graph of thecorresponding item, in a simple text format.
@var{allowed-references} must be either @code{#f} or a list of output namesand packages. In the latter case, the list denotes store items that theresult is allowed to refer to. Any reference to another store item willlead to a build error. Similarly for @var{disallowed-references}, which canlist items that must not be referenced by the outputs.
@var{deprecation-warnings} determines whether to show deprecation warningswhile 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 objectsThe @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, theseobjects 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 tothe store. Once expanded, for instance @i{via} @code{gexp->derivation}, theG-expression refers to that copy under @file{/gnu/store}; thus, modifying orremoving the file in @file{/tmp} does not have any effect on what theG-expression does. @code{plain-file} can be used similarly; it differs inthat 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 localfile @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 sourcefile 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 addedrecursively; if @var{file} designates a flat file and @var{recursive?} istrue, 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'sabsolute file name and @var{stat} is the result of @code{lstat}; excludeentries for which @var{select?} does not return true.
This is the declarative counterpart of the @code{interned-file} monadicprocedure (@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 storeitem @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 executablescript @var{name} that runs @var{exp} using @var{guile}, with @var{exp}'simported 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 executablefile @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 theexecutable store item @var{name} that runs @var{gexp}. @var{guile} is theGuile 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 consideredto 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}'simported modules. Look up @var{exp}'s modules in @var{module-path}.
The resulting file holds references to all the dependencies of @var{exp} ora 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 containingall of @var{text}. @var{text} may list, in addition to strings, objects ofany type that can be used in a gexp: packages, derivations, local fileobjects, etc. The resulting store file holds references to all these.
This variant should be preferred over @code{text-file} anytime the file tocreate will reference items from the store. This is typically the case whenbuilding 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} filewill reference @var{coreutils}, @var{grep}, and @var{sed}, therebypreventing 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 thefirst element is the file name to use in the new directory, and the secondelement 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} isa 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} isa 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, theresulting script contains the absolute file name as a string, whereas in thesecond 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 alsomodules containing build tools. To make it clear that they are meant to beused in the build stratum, these modules are kept in the @code{(guix build@dots{})} name space.
@cindex lowering, of high-level objects in gexpsInternally, high-level objects are @dfn{lowered}, using their compiler, toeither derivations or store items. For instance, lowering a package yieldsa derivation, and lowering a @code{plain-file} yields a store item. This isachieved 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 orstore 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 hasan associated gexp compiler, such as a @code{<package>}.@end deffn
@node Invoking guix repl@section Invoking @command{guix repl}
@cindex REPL, read-eval-print loopThe @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 Guixmodules and all its dependencies are available in the search path. You canuse it this way:
@example$ guix replscheme@@(guile-user)> ,use (gnu packages base)scheme@@(guile-user)> coreutils$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>@end example
@cindex inferiorsIn addition, @command{guix repl} implements a simple machine-readable REPLprotocol for use by @code{(guix inferior)}, a facility to interact with@dfn{inferiors}, separate processes running a potentially different revisionof 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 guileThis is default, and it spawns a standard full-featured Guile REPL.@item machineSpawn a REPL that uses the machine-readable protocol. This is the protocolthat the @code{(guix inferior)} module speaks.@end table
@item --listen=@var{endpoint}By default, @command{guix repl} reads from standard input and writes tostandard output. When this option is passed, it will instead listen forconnections on @var{endpoint}. Here are examples of valid options:
@table @code@item --listen=tcp:37146Accept connections on localhost on port 37146.
@item --listen=unix:/tmp/socketAccept 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 areprimarily targeted at developers and users who write new packagedefinitions, while others are more generally useful. They complement theScheme 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 theirdependencies, and prints the resulting store paths. Note that it does notmodify the user's profile---this is the job of the @command{guix package}command (@pxref{Invoking guix package}). Thus, it is mainly useful fordistribution developers.
The general syntax is:
@exampleguix build @var{options} @var{package-or-derivation}@dots{}@end example
As an example, the following command builds the latest versions of Emacs andof Guile, displays their build logs, and finally displays the resultingdirectories:
@exampleguix build emacs guile@end example
Similarly, the following command builds all the available packages:
@exampleguix 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 thesoftware distribution such as @code{coreutils} or @code{coreutils@@8.20}, ora derivation such as @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In theformer case, a package with the corresponding name (and optionally version)is searched for among the GNU distribution modules (@pxref{PackageModules}).
Alternatively, the @code{--expression} option may be used to specify aScheme expression that evaluates to a package; this is useful whendisambiguating among several same-named packages or package variants isneeded.
There may be zero or more @var{options}. The available options aredescribed 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 thecommand-line tools.
@item --keep-failed@itemx -KKeep the build tree of failed builds. Thus, if a build fails, its buildtree is kept under @file{/tmp}, in a directory whose name is shown at theend of the build log. This is useful when debugging build issues.@xref{Debugging Build Failures}, for tips and tricks on how to debug buildissues.
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 -kKeep going when some of the derivations fail to build; return only once allthe builds have either completed or failed.
The default behavior is to stop as soon as one of the specified derivationshas failed.
@item --dry-run@itemx -nDo not build the derivations.
@anchor{fallback-option}@item --fallbackWhen substituting a pre-built binary fails, fall back to building packageslocally (@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 theyare signed by a key authorized by the system administrator(@pxref{Substitutes}).
When @var{urls} is the empty string, substitutes are effectively disabled.
@item --no-substitutesDo not use substitutes for build products. That is, always build thingslocally instead of allowing downloads of pre-built binaries(@pxref{Substitutes}).
@item --no-graftsDo not ``graft'' packages. In practice, this means that package updatesavailable as grafts are not applied. @xref{Security Updates}, for moreinformation on grafts.
@item --rounds=@var{n}Build each derivation @var{n} times in a row, and raise an error ifconsecutive 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 itpractically impossible for users to @emph{verify} whether third-partybinaries are genuine. @xref{Invoking guix challenge}, for more.
Note that, currently, the differing build results are not kept around, soyou will have to manually investigate in case of an error---e.g., bystashing one of the build results with @code{guix archive --export}(@pxref{Invoking guix archive}), then rebuilding, and finally comparing thetwo results.
@item --no-build-hookDo not attempt to offload builds @i{via} the ``build hook'' of the daemon(@pxref{Daemon Offload Setup}). That is, always build things locallyinstead 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 nooutput is produced, 1 is for quiet output, and 2 shows all the build logoutput 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 bean integer between 0 and 5; higher means more verbose output. Setting alevel of 4 or more may be helpful when debugging setup issues with the builddaemon.
@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{(guixderivations)} module.
In addition to options explicitly passed on the command line, @command{guixbuild} and other @command{guix} commands that support building honor the@code{GUIX_BUILD_OPTIONS} environment variable.
@defvr {Environment Variable} GUIX_BUILD_OPTIONSUsers can define this variable to a list of command line options that willautomatically 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 theparsed command-line options.@end defvr

@node Package Transformation Options@subsection Package Transformation Options
@cindex package variantsAnother set of command-line options supported by @command{guix build} andalso @command{guix package} are @dfn{package transformation options}. Theseare options that make it possible to define @dfn{package variants}---forinstance, packages built from different source code. This is a convenientway to create customized packages on the fly without having to type in thedefinitions 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 itsversion 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 specifiedon 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 packageis @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 oneprovided 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:
@exampleguix 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 releasecandidates:
@exampleguix 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 apackage specification such as @code{guile} or @code{guile@@1.8}.
For instance, the following command builds Guix, but replaces its dependencyon the current stable version of Guile with a dependency on the legacyversion of Guile, @code{guile@@2.0}:
@exampleguix 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} Schemeprocedure (@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 builtand 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 andall its dependencies, replacing references to the version of GnuTLS theycurrently refer to:
@exampleguix build --with-graft=gnutls=gnutls@@3.5.4 wget@end example
This has the advantage of being much faster than rebuilding everything. Butthere is a caveat: it works if and only if @var{package} and@var{replacement} are strictly compatible---for example, if they provide alibrary, the application binary interface (ABI) of those libraries must becompatible. 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, buildingBuild @var{package} from the latest commit of the @code{master} branch ofthe Git repository at @var{url}. Git sub-modules of the repository arefetched, recursively.
For example, the following command builds the NumPy Python library againstthe latest commit of the master branch of Python itself:
@exampleguix 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 integrationObviously, since it uses the latest commit of the given branch, the resultof such a command varies over time. Nevertheless it is a convenient way torebuild entire software stacks against the latest commit of one or morepackages. This is particularly useful in the context of continuousintegration (CI).
Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speedup consecutive accesses to the same repository. You may want to clean it uponce 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, therepository 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 thelatest 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:
@exampleguix 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 validGit commit SHA1 identifier.@end table
@node Additional Build Options@subsection Additional Build Options
The command-line options presented below are specific to @command{guixbuild}.
@table @code
@item --quiet@itemx -qBuild 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 codewithin @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 ofGuile.
Alternatively, @var{expr} may be a G-expression, in which case it is used asa 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 amonadic value, which is then passed through @code{run-with-store}.
@item --source@itemx -SBuild the source derivations of the packages, rather than the packagesthemselves.
For instance, @code{guix build -S gcc} returns something like@file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC sourcetarball.
The returned source tarball is the result of applying any patches and codesnippets specified in the package @code{origin} (@pxref{Defining Packages}).
@item --sourcesFetch and return the source of @var{package-or-derivation} and all theirdependencies, recursively. This is a handy way to obtain a local copy ofall the source code needed to build @var{packages}, allowing you toeventually build them even without network access. It is an extension ofthe @code{--source} option and can accept one of the following optionalargument values:
@table @code@item packageThis value causes the @code{--sources} option to behave in the same way asthe @code{--source} option.
@item allBuild the source derivations of all packages, including any source thatmight be listed as @code{inputs}. This is the default value.
@example$ guix build --sources tzdataThe following derivations will be built: /gnu/store/@dots{}-tzdata2015b.tar.gz.drv /gnu/store/@dots{}-tzcode2015b.tar.gz.drv@end example
@item transitiveBuild the source derivations of all packages, as well of all transitiveinputs to the packages. This can be used e.g.@: to prefetch package sourcefor later offline building.
@example$ guix build --sources=transitive tzdataThe 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 thesystem type of the build host. The @command{guix build} command allows youto repeat this option several times, in which case it builds for all thespecified systems; other commands ignore extraneous @option{-s} options.
@quotation NoteThe @code{--system} flag is for @emph{native} compilation and must not beconfused with cross-compilation. See @code{--target} below for informationon cross-compilation.@end quotation
An example use of this is on Linux-based systems, which can emulatedifferent 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 complete32-bit environment.
@quotation NoteBuilding for an @code{armhf-linux} system is unconditionally enabled on@code{aarch64-linux} machines, although certain aarch64 chipsets do notallow for this functionality, notably the ThunderX.@end quotation
Similarly, when transparent emulation with QEMU and @code{binfmt_misc} isenabled (@pxref{Virtualization Services, @code{qemu-binfmt-service-type}}),you can build for any system for which a QEMU @code{binfmt_misc} handler isinstalled.
Builds for a system other than that of the machine you are using can also beoffloaded to a remote machine of the right architecture. @xref{DaemonOffload Setup}, for more information on offloading.
@item --target=@var{triplet}@cindex cross-compilationCross-build for @var{triplet}, which must be a valid GNU triplet, such as@code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNUconfiguration triplets,, autoconf, Autoconf}).
@anchor{build-check}@item --check@cindex determinism, checking@cindex reproducibility, checkingRebuild @var{package-or-derivation}, which are already available in thestore, and raise an error if the build results are not bit-for-bitidentical.
This mechanism allows you to check whether previously installed substitutesare genuine (@pxref{Substitutes}), or whether the build result of a packageis deterministic. @xref{Invoking guix challenge}, for more backgroundinformation and tools.
When used in conjunction with @option{--keep-failed}, the differing outputis kept in the store, under @file{/gnu/store/@dots{}-check}. This makes iteasy to look for differences between the two results.
@item --repair@cindex repairing store items@cindex corruption, recovering fromAttempt to repair the specified store items, if they are corrupt, byre-downloading or rebuilding them.
This operation is not atomic and thus restricted to @code{root}.
@item --derivations@itemx -dReturn 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, addingMake @var{file} a symlink to the result, and register it as a garbagecollector root.
Consequently, the results of this @command{guix build} invocation areprotected from garbage collection until @var{file} is removed. When thatoption is omitted, build results are eligible for garbage collection as soonas the build completes. @xref{Invoking guix gc}, for more on GC roots.
@item --log-file@cindex build logs, accessReturn 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. Forinstance, the following invocations are equivalent:
@exampleguix build --log-file `guix build -d guile`guix build --log-file `guix build guile`guix build --log-file guileguix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'@end example
If a log is unavailable locally, and unless @code{--no-substitutes} ispassed, the command looks for a corresponding log on one of the substituteservers (as specified with @code{--substitute-urls}.)
So for instance, imagine you want to see the build log of GDB on MIPS, butyou are actually on an @code{x86_64} machine:
@example$ guix build --log-file gdb -s mips64el-linuxhttps://@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, debuggingWhen defining a new package (@pxref{Defining Packages}), you will probablyfind yourself spending some time debugging and tweaking the build until itsucceeds. To do that, you need to operate the build commands yourself in anenvironment 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 buildtree 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 environmentvariable definitions that were in place when the build failed. So let's sayyou're debugging a build failure in package @code{foo}; a typical sessionwould 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) andtroubleshoot your build process.
Sometimes it happens that, for example, a package's tests pass when you runthem manually but they fail when the daemon runs them. This can happenbecause the daemon runs builds in containers where, unlike in ourenvironment 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 acontainer 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 newshell in it (@pxref{Invoking guix environment}). The @command{--ad-hocstrace gdb} part adds the @command{strace} and @command{gdb} commands to thecontainer, 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 canremove @file{/bin/sh}:
@example[env]# rm /bin/sh@end example
(Don't worry, this is harmless: this is all happening in the throw-awaycontainer created by @command{guix environment}.)
The @command{strace} command is probably not in the search path, but we canrun:
@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 thedaemon uses, you will also be running the build process in a containersimilar to the one the daemon uses.

@node Invoking guix edit@section Invoking @command{guix edit}
@cindex @command{guix edit}@cindex package definition, editingSo many packages, so many source files! The @command{guix edit} commandfacilitates the life of users and packagers by pointing their editor at thesource file containing the definition of the specified packages. Forinstance:
@exampleguix edit gcc@@4.9 vim@end example
@noindentlaunches 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 havecreated your own packages on @code{GUIX_PACKAGE_PATH} (@pxref{PackageModules}), 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 inthe store.

@node Invoking guix download@section Invoking @command{guix download}
@cindex @command{guix download}@cindex downloading package sourcesWhen writing a package definition, developers typically need to download asource tarball, compute its SHA256 hash, and write that hash in the packagedefinition (@pxref{Defining Packages}). The @command{guix download} toolhelps with this task: it downloads a file from the given URI, adds it to thestore, 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 downloadedagain because it is already in the store. It is also a convenient way totemporarily stash files, which may be deleted eventually (@pxref{Invokingguix gc}).
The @command{guix download} command supports the same URIs as used inpackage definitions. In particular, it supports @code{mirror://} URIs.@code{https} URIs (HTTP over TLS) are supported @emph{provided} the Guilebindings for GnuTLS are available in the user's environment; when they arenot available, an error is raised. @xref{Guile Preparations, how to installthe GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, for moreinformation.
@command{guix download} verifies HTTPS server certificates by loading thecertificates 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 informationon the valid values for @var{fmt}, @pxref{Invoking guix hash}.
@item --no-check-certificateDo not validate the X.509 certificates of HTTPS servers.
When using this option, you have @emph{absolutely no guarantee} that you arecommunicating with the authentic server responsible for the given URL, whichmakes 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 isprimarily a convenience tool for anyone contributing to the distribution: itcomputes the cryptographic hash of a file, which can be used in thedefinition of a package (@pxref{Defining Packages}).
The general syntax is:
@exampleguix hash @var{option} @var{file}@end example
When @var{file} is @code{-} (a hyphen), @command{guix hash} computes thehash of data read from standard input. @command{guix hash} has thefollowing 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} willoutput the hash in @code{nix-base32}. This representation is used in thedefinitions of packages.
@item --recursive@itemx -rCompute 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 aregular file, the hash is different depending on whether @var{file} isexecutable or not. Metadata such as time stamps has no impact on the hash(@pxref{Invoking guix archive}).
@item --exclude-vcs@itemx -xWhen combined with @option{--recursive}, exclude version control systemdirectories (@file{.bzr}, @file{.git}, @file{.hg}, etc.)
@vindex git-fetchAs 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{originReference}):
@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 adda package to the distribution with as little work as possible---a legitimatedemand. The command knows of a few repositories from which it can``import'' package metadata. The result is a package definition, or atemplate thereof, in the format we know (@pxref{Defining Packages}).
The general syntax is:
@exampleguix 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 specificto @var{importer}. Currently, the available ``importers'' are:
@table @code@item gnuImport metadata for the given GNU package. This provides a template for thelatest version of that GNU package, including the hash of its sourcetarball, and its canonical synopsis and description.
Additional information such as the package dependencies and its licenseneeds to be figured out manually.
For example, the following command returns a package definition forGNU@tie{}Hello:
@exampleguix 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 OpenPGPkeys when verifying the package signature. @xref{Invoking guix refresh,@code{--key-download}}.@end table
@item pypi@cindex pypiImport metadata from the @uref{https://pypi.python.org/,Python PackageIndex}. Information is taken from the JSON-formatted description availableat @code{pypi.python.org} and usually includes all the relevant information,including package dependencies. For maximum efficiency, it is recommendedto install the @command{unzip} utility, so that the importer can unzipPython wheels and gather data from them.
The command below imports metadata for the @code{itsdangerous} Pythonpackage:
@exampleguix import pypi itsdangerous@end example
@table @code@item --recursive@itemx -rTraverse the dependency graph of the given upstream package recursively andgenerate package expressions for all those packages that are not yet inGuix.@end table
@item gem@cindex gemImport metadata from @uref{https://rubygems.org/,RubyGems}. Information istaken 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 betweensynopses and descriptions, so the same string is used for both fields.Additionally, the details of non-Ruby dependencies required to build nativeextensions is unavailable and left as an exercise to the packager.
The command below imports metadata for the @code{rails} Ruby package:
@exampleguix import gem rails@end example
@table @code@item --recursive@itemx -rTraverse the dependency graph of the given upstream package recursively andgenerate package expressions for all those packages that are not yet inGuix.@end table
@item cpan@cindex CPANImport 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 mostrelevant information, such as module dependencies. License informationshould 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 listof dependencies.
The command command below imports metadata for the @code{Acme::Boolean} Perlmodule:
@exampleguix import cpan Acme::Boolean@end example
@item cran@cindex CRAN@cindex BioconductorImport metadata from @uref{https://cran.r-project.org/,CRAN}, the centralrepository for the @uref{http://r-project.org, GNU@tie{}R statistical andgraphical environment}.
Information is extracted from the @code{DESCRIPTION} file of the package.
The command command below imports metadata for the @code{Cairo} R package:
@exampleguix import cran Cairo@end example
When @code{--recursive} is added, the importer will traverse the dependencygraph of the given upstream package recursively and generate packageexpressions 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 Rpackages for for the analysis and comprehension of high-throughput genomicdata in bioinformatics.
Information is extracted from the @code{DESCRIPTION} file of a packagepublished on the web interface of the Bioconductor SVN repository.
The command below imports metadata for the @code{GenomicRanges} R package:
@exampleguix import cran --archive=bioconductor GenomicRanges@end example
@item texlive@cindex TeX Live@cindex CTANImport metadata from @uref{http://www.ctan.org/,CTAN}, the comprehensiveTeX 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 byCTAN, while the source code is downloaded from the SVN repository of the TexLive project. This is done because the CTAN does not keep versionedarchives.
The command command below imports metadata for the @code{fontspec} TeXpackage:
@exampleguix import texlive fontspec@end example
When @code{--archive=DIRECTORY} is added, the source code is downloaded notfrom the @file{latex} sub-directory of the @file{texmf-dist/source} tree inthe TeX Live SVN repository, but from the specified sibling directory underthe same root.
The command below imports metadata for the @code{ifxetex} package from CTANwhile fetching the sources from the directory @file{texmf/source/generic}:
@exampleguix import texlive --archive=generic ifxetex@end example
@item json@cindex JSON, importImport package metadata from a local JSON file. Consider the followingexample 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 asJSON 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 thecommon 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} andoutputs a package expression:
@exampleguix import json hello.json@end example
@item nixImport metadata from a local copy of the source of the@uref{http://nixos.org/nixpkgs/,Nixpkgs distribution}@footnote{This relieson the @command{nix-instantiate} command of @uref{http://nixos.org/nix/,Nix}.}. Package definitions in Nixpkgs are typically written in a mixtureof Nix-language and Bash code. This command only imports the high-levelpackage structure that is written in the Nix language. It normally includesall the basic fields of a package definition.
When importing a GNU package, the synopsis and descriptions are replaced bytheir canonical upstream variant.
Usually, you will first need to do:
@exampleexport NIX_REMOTE=daemon@end example
@noindentso that @command{nix-instantiate} does not try to open the Nix database.
As an example, the command below imports the package definition ofLibreOffice (more precisely, it imports the definition of the package boundto the @code{libreoffice} top-level attribute):
@exampleguix import nix ~/path/to/nixpkgs libreoffice@end example
@item hackage@cindex hackageImport metadata from the Haskell community's central package archive@uref{https://hackage.haskell.org/,Hackage}. Information is taken fromCabal files and includes all the relevant information, including packagedependencies.
Specific command-line options are:
@table @code@item --stdin@itemx -sRead a Cabal file from standard input.@item --no-test-dependencies@itemx -tDo 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 Cabalconditionals are evaluated. The accepted keys are: @code{os}, @code{arch},@code{impl} and a string representing the name of a flag. The valueassociated with a flag has to be either the symbol @code{true} or@code{false}. The value associated with other keys has to conform to theCabal 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 -rTraverse the dependency graph of the given upstream package recursively andgenerate package expressions for all those packages that are not yet inGuix.@end table
The command below imports metadata for the latest version of the @code{HTTP}Haskell package without including test dependencies and specifying the valueof the flag @samp{network-uri} as @code{false}:
@exampleguix import hackage -t -e "'((\"network-uri\" . false))" HTTP@end example
A specific package version may optionally be specified by following thepackage name by an at-sign and a version number as in the following example:
@exampleguix import hackage mtl@@2.1.3.1@end example
@item stackage@cindex stackageThe @code{stackage} importer is a wrapper around the @code{hackage} one. Ittakes a package name, looks up the package version included in a long-termsupport (LTS) @uref{https://www.stackage.org, Stackage} release and uses the@code{hackage} importer to retrieve its metadata. Note that it is up to youto select an LTS release compatible with the GHC compiler used by Guix.
Specific command-line options are:
@table @code@item --no-test-dependencies@itemx -tDo 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 latestrelease is used.@item --recursive@itemx -rTraverse the dependency graph of the given upstream package recursively andgenerate package expressions for all those packages that are not yet inGuix.@end table
The command below imports metadata for the @code{HTTP} Haskell packageincluded in the LTS Stackage release version 7.18:
@exampleguix import stackage --lts-version=7.18 HTTP@end example
@item elpa@cindex elpaImport 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 theinformation. Currently the supported repositories and their identifiersare:@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 containedin the GnuPG keyring at @file{share/emacs/25.1/etc/package-keyring.gpg} (orsimilar) in the @code{emacs} package (@pxref{Package Installation, ELPApackage 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 -rTraverse the dependency graph of the given upstream package recursively andgenerate package expressions for all those packages that are not yet inGuix.@end table
@item crate@cindex crateImport metadata from the crates.io Rust package repository@uref{https://crates.io, crates.io}.
@item opam@cindex OPAM@cindex OCamlImport metadata from the @uref{https://opam.ocaml.org/,OPAM} packagerepository used by the OCaml community.@end table
The structure of the @command{guix import} code is modular. It would beuseful to have more importers for other package formats, and your help iswelcome 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 ofthe GNU software distribution. By default, it reports any packages providedby the distribution that are outdated compared to the latest upstreamversion, like this:
@example$ guix refreshgnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1gnu/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 warningis emitted for packages that lack an updater:
@example$ guix refresh coreutils guile guile-sshgnu/packages/ssh.scm:205:2: warning: no updater for guile-sshgnu/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 anddetermines the highest version number of the releases therein. The commandknows how to update specific types of packages: GNU packages, ELPA packages,etc.---see the documentation for @option{--type} below. There are manypackages, though, for which it lacks a method to determine whether a newupstream release is available. However, the mechanism is extensible, sofeel free to get in touch with us to add a new method!
@table @code
@item --recursiveConsider the packages specified, and all the packages upon which theydepend.
@example$ guix refresh --recursive coreutilsgnu/packages/acl.scm:35:2: warning: no updater for aclgnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4gnu/packages/xml.scm:68:2: warning: no updater for expatgnu/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 tothat 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 updatethe version numbers and source tarball hashes of those package recipes(@pxref{Defining Packages}). This is achieved by downloading each package'slatest source tarball and its associated OpenPGP signature, authenticatingthe downloaded tarball against its signature using @command{gpg}, andfinally computing its hash. When the public key used to sign the tarball ismissing from the user's keyring, an attempt is made to automaticallyretrieve it from a public key server; when this is successful, the key isadded to the user's keyring; otherwise, @command{guix refresh} reports anerror.
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:
@exampleguix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'@end example
This command lists the dependents of the ``final'' libc (essentially all thepackages.)
@item --update@itemx -uUpdate distribution source files (package recipes) in place. This isusually 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 thedistribution---i.e., packages that are used to build ``everything else''.This includes GCC, libc, Binutils, Bash, etc. Usually, changing one ofthese packages in the distribution entails a rebuild of all the others.Thus, such updates are an inconvenience to users in terms of build time orbandwidth used to achieve the upgrade.
The @code{non-core} subset refers to the remaining packages. It istypically useful in cases where an update of the core packages would beinconvenient.
@item --manifest=@var{file}@itemx -m @var{file}Select all the packages from the manifest in @var{file}. This is useful tocheck 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 listof updaters). Currently, @var{updater} may be one of:
@table @code@item gnuthe updater for GNU packages;@item gnomethe updater for GNOME packages;@item kdethe updater for KDE packages;@item xorgthe updater for X.org packages;@item kernel.orgthe updater for packages hosted on kernel.org;@item elpathe updater for @uref{http://elpa.gnu.org/,ELPA} packages;@item cranthe updater for @uref{https://cran.r-project.org/,CRAN} packages;@item bioconductorthe updater for @uref{https://www.bioconductor.org/,Bioconductor} Rpackages;@item cpanthe updater for @uref{http://www.cpan.org/,CPAN} packages;@item pypithe updater for @uref{https://pypi.python.org, PyPI} packages.@item gemthe updater for @uref{https://rubygems.org, RubyGems} packages.@item githubthe updater for @uref{https://github.com, GitHub} packages.@item hackagethe updater for @uref{https://hackage.haskell.org, Hackage} packages.@item stackagethe updater for @uref{https://www.stackage.org, Stackage} packages.@item cratethe updater for @uref{https://crates.io, Crates} packages.@item launchpadthe updater for @uref{https://launchpad.net, Launchpad} packages.@end table
For instance, the following command only checks for updates of Emacspackages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
@example$ guix refresh --type=elpa,crangnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0gnu/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
@noindentThe 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 toknow which packages would be affected by the upgrade and should be checkedfor 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 -LList 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 -lList top-level dependent packages that would need to be rebuilt as a resultof upgrading one or more packages.
@xref{Invoking guix graph, the @code{reverse-package} type of @command{guixgraph}}, for information on how to visualize the list of dependents of apackage.
@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. Morerebuilds might be required under some circumstances.
@example$ guix refresh --list-dependent flexBuilding 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 forcompatibility with an upgraded @code{flex} package.
@table @code
@item --list-transitiveList all the packages which one or more packages depend upon.
@example$ guix refresh --list-transitive flexflex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6bison@@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 forin @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 upstreamsigning keys. OpenPGP signatures are checked against keys from thiskeyring; 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 usingcommands like this one:
@examplegpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx@end example
Likewise, you can fetch keys to a specific keybox file like this:
@examplegpg --no-default-keyring --keyring mykeyring.kbx \ --recv-keys @value{OPENPGP-SIGNING-KEY-ID}@end example
@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNUPrivacy 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 alwaysAlways download missing OpenPGP keys from the key server, and add them tothe user's GnuPG keyring.
@item neverNever try to download missing OpenPGP keys. Instead just bail out.
@item interactiveWhen a package signed with an unknown OpenPGP key is encountered, ask theuser 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.@: whenrefreshing all packages, GitHub will eventually refuse to answer any furtherAPI requests. By default 60 API requests per hour are allowed, and a fullrefresh on all GitHub packages in Guix requires more than this.Authentication with GitHub through the use of an API token alleviates theselimits. 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 errorsThe @command{guix lint} command is meant to help package developers avoidcommon errors and use a consistent style. It runs a number of checks on agiven set of packages in order to find common mistakes in theirdefinitions. Available @dfn{checkers} include (see @code{--list-checkers}for a complete list):
@table @code@item synopsis@itemx descriptionValidate certain typographical and stylistic rules about packagedescriptions and synopses.
@item inputs-should-be-nativeIdentify inputs that should most likely be native inputs.
@item source@itemx home-page@itemx mirror-url@itemx github-url@itemx source-file-nameProbe @code{home-page} and @code{source} URLs and report those that areinvalid. Suggest a @code{mirror://} URL when applicable. If the@code{source} URL redirects to a GitHub URL, recommend usage of the GitHubURL. Check that the source file name is meaningful, e.g.@: is not just aversion number or ``git-checkout'', without a declared @code{file-name}(@pxref{origin Reference}).
@item source-unstable-tarballParse the @code{source} URL to determine if a tarball from GitHub isautogenerated or if it is a release tarball. Unfortunately GitHub'sautogenerated tarballs are sometimes regenerated.
@item cve@cindex security vulnerabilities@cindex CVE, Common Vulnerabilities and ExposuresReport known vulnerabilities found in the Common Vulnerabilities andExposures (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
@noindentwhere @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,CommonPlatform Enumeration (CPE)} nameand version of the package when they differ from the name or version thatGuix 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 packagethey apply to, and would thus ``stick around'' forever. Package developerswho found CVE alerts and verified they can be ignored can declare them as inthis 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 formattingWarn about obvious source code formatting issues: trailing white space, useof tabulations, etc.@end table
The general syntax is:
@exampleguix 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 -lList and describe all the available checkers that will be run on packagesand exit.
@item --checkers@itemx -cOnly enable the checkers specified in a comma-separated list using the namesreturned 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 diskusage of packages. It is easy to overlook the impact of an additionaldependency added to a package, or the impact of using a single output for apackage that could easily be split (@pxref{Packages with MultipleOutputs}). Such are the typical issues that @command{guix size} canhighlight.
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 coreutilsstore 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 closureThe store items listed here constitute the @dfn{transitive closure} ofCoreutils---i.e., Coreutils and all its dependencies, recursively---as wouldbe 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 thestore 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. Thelast column shows the ratio of the size of the item itself to the spaceoccupied by all the items listed here.
In this example, we see that the closure of Coreutils weighs in at79@tie{}MiB, most of which is taken by libc and GCC's run-time supportlibraries. (That libc and GCC's libraries represent a large fraction of theclosure is not a problem @i{per se} because they are always available on thesystem anyway.)
When the package(s) passed to @command{guix size} are available in thestore@footnote{More precisely, @command{guix size} looks for the@emph{ungrafted} variant of the given package(s), as returned by @code{guixbuild @var{package} --no-grafts}. @xref{Security Updates}, for informationon grafts.}, @command{guix size} queries the daemon to determine itsdependencies, 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 ofstore items that are not even on disk, only available remotely.
You can also specify several package names:
@example$ guix size coreutils grep sed bashstore 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
@noindentIn this example we see that the combination of the four packages takes102.3@tie{}MiB in total, which is much less than the sum of each closuresince 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 selfthe size of each item (the default);@item closurethe 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 producedby @command{guix size}}
This option requires that@uref{http://wingolog.org/software/guile-charting/,Guile-Charting} beinstalled and visible in Guile's module search path. When that is not thecase, @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 dependenciesPackages and their dependencies form a @dfn{graph}, specifically a directedacyclic graph (DAG). It can quickly become difficult to have a mental modelof the package DAG, so the @command{guix graph} command provides a visualrepresentation of the DAG. By default, @command{guix graph} emits a DAGrepresentation in the input format of @uref{http://www.graphviz.org/,Graphviz}, so its output can be passed directly to the @command{dot} commandof Graphviz. It can also emit an HTML page with embedded JavaScript code todisplay a ``chord diagram'' in a Web browser, using the@uref{https://d3js.org/,d3.js} library, or emit Cypher queries to constructa graph in a graph database supporting the @uref{http://www.opencypher.org/,openCypher} query language. The general syntax is:
@exampleguix graph @var{options} @var{package}@dots{}@end example
For example, the following command generates a PDF file representing thepackage DAG for the GNU@tie{}Core Utilities, showing its build-timedependencies:
@exampleguix 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 graphof 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 wantto see more details. @command{guix graph} supports several types of graphs,allowing you to choose the level of detail:
@table @code@item packageThis is the default type used in the example above. It shows the DAG ofpackage objects, excluding implicit dependencies. It is concise, butfilters out many details.
@item reverse-packageThis shows the @emph{reverse} DAG of packages. For example:
@exampleguix 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 isto 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-emergedThis is the package DAG, @emph{including} implicit inputs.
For instance, the following command:
@exampleguix 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 GNUCoreutils}
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 bagSimilar to @code{bag-emerged}, but this time including all the bootstrapdependencies.
@item bag-with-originsSimilar to @code{bag}, but also showing origins and their dependencies.
@item reverse-bagThis shows the @emph{reverse} DAG of packages. Unlike@code{reverse-package}, it also takes implicit dependencies into account.For example:
@exampleguix graph -t reverse-bag dune@end example
@noindent...@: yields the graph of all packages that depend on Dune, directly orindirectly. 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 derivationThis is the most detailed representation: It shows the DAG of derivations(@pxref{Derivations}) and plain store items. Compared to the aboverepresentation, 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 nameinstead of a package name, as in:
@exampleguix graph -t derivation `guix system build -d my-config.scm`@end example
@item moduleThis is the graph of @dfn{package modules} (@pxref{Package Modules}). Forexample, the following command shows the graph for the package module thatdefines the @code{guile} package:
@exampleguix graph -t module guile | dot -Tpdf > module-graph.pdf@end example@end table
All the types above correspond to @emph{build-time dependencies}. Thefollowing graph type represents the @emph{run-time dependencies}:
@table @code@item referencesThis 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{guixgraph} attempts to obtain dependency information from substitutes.
Here you can also pass a store file name instead of a package name. Forexample, the command below produces the reference graph of your profile(which can be big!):
@exampleguix graph -t references `readlink -f ~/.guix-profile`@end example
@item referrersThis 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 yourmachine; @command{guix graph -t referrers inkscape} will show a graph rootedat Inkscape and with those 10 profiles linked to it.
It can help determine what is preventing a store item from being garbagecollected.
@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 thevalues listed above.
@item --list-typesList the supported graph types.
@item --backend=@var{backend}@itemx -b @var{backend}Produce a graph using the selected @var{backend}.
@item --list-backendsList 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:
@exampleguix 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 thereare some architecture-dependent bits that this option allows you tovisualize.@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 sharetheir 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 allowsanyone with network access to obtain substitutes from it. This means thatany machine running Guix can also act as if it were a build farm, since theHTTP 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 theirauthenticity and integrity (@pxref{Substitutes}). Because @command{guixpublish} uses the signing key of the system, which is only readable by thesystem administrator, it must be started as root; the @code{--user} optionmakes it drop root privileges early on.
The signing key pair must be generated before @command{guix publish} islaunched, using @command{guix archive --generate-key} (@pxref{Invoking guixarchive}).
The general syntax is:
@exampleguix publish @var{options}@dots{}@end example
Running @command{guix publish} without any additional arguments will spawnan HTTP server on port 8080:
@exampleguix publish@end example
Once a publishing server has been authorized (@pxref{Invoking guixarchive}), the daemon may download substitutes from it:
@exampleguix-daemon --substitute-urls=http://example.org:8080@end example
By default, @command{guix publish} compresses archives on the fly as itserves them. This ``on-the-fly'' mode is convenient in that it requires nosetup and is immediately available. However, when serving lots of clients,we recommend using the @option{--cache} option, which enables caching of thearchives before they are sent to clients---see below for details. The@command{guix weather} command provides a handy way to check what a serverprovides (@pxref{Invoking guix weather}).
As a bonus, @command{guix publish} also serves as a content-addressed mirrorfor source files referenced in @code{origin} records (@pxref{originReference}). 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}):
@examplehttp://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 othercases, they return 404 (``Not Found'').
@cindex build logs, publicationBuild logs are available from @code{/log} URLs like:
@examplehttp://example.org/log/gwspk@dots{}-guile-2.2.3@end example
@noindentWhen @command{guix-daemon} is configured to save compressed build logs, asis the case by default (@pxref{Invoking guix-daemon}), @code{/log} URLsreturn 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 browserscan automatically decompress it, which is not the case with bzip2compression.
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 acceptconnections from any interface.
@item --user=@var{user}@itemx -u @var{user}Change privileges to @var{user} as soon as possible---i.e., once the serversocket 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 gzipcompression 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 thecompressed streams are not cached. Thus, to reduce load on the machine thatruns @command{guix publish}, it may be a good idea to choose a lowcompression level, to run @command{guix publish} behind a caching proxy, orto use @option{--cache}. Using @option{--cache} has the advantage that itallows @command{guix publish} to add @code{Content-Length} HTTP header toits responses.
@item --cache=@var{directory}@itemx -c @var{directory}Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory} andonly 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 isenabled, since this may become CPU-bound. Another drawback of the defaultmode is that the length of archives is not known in advance, so@command{guix publish} does not add a @code{Content-Length} HTTP header toits responses, which in turn prevents clients from knowing the amount ofdata being downloaded.
Conversely, when @option{--cache} is used, the first request for a storeitem (@i{via} a @code{.narinfo} URL) returns 404 and triggers a backgroundprocess to @dfn{bake} the archive---computing its @code{.narinfo} andcompressing the archive, if needed. Once the archive is cached in@var{directory}, subsequent requests succeed and are served directly fromthe cache, which guarantees that clients get the best possible bandwidth.
The ``baking'' process is performed by worker threads. By default, onethread per CPU core is created, but this can be customized. See@option{--workers} below.
When @option{--ttl} is used, cached entries are automatically deleted whenthey have expired.
@item --workers=@var{N}When @option{--cache} is used, request the allocation of @var{N} workerthreads 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 5days, @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 guaranteethat 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 notbeen accessed for @var{ttl} and that no longer have a corresponding item inthe store, may be deleted.
@item --nar-path=@var{path}Use @var{path} as the prefix for the URLs of ``nar'' files (@pxref{Invokingguix 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 changethe @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 thestore items being published.
The files must correspond to the same key pair (the private key is used forsigning 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}). Bydefault, @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 ReferenceManual}) on @var{port} (37146 by default). This is used primarily fordebugging a running @command{guix publish} server.@end table
Enabling @command{guix publish} on Guix System is a one-liner: justinstantiate 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 theseinstructions:”
@itemize@itemIf 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
@itemIf 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
@itemOtherwise, 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 challengeDo the binaries provided by this server really correspond to the source codeit claims to build? Is a package build process deterministic? These are thequestions the @command{guix challenge} command attempts to answer.
The former is obviously an important question: Before using a substituteserver (@pxref{Substitutes}), one had better @emph{verify} that it providesthe right binaries, and thus @emph{challenge} it. The latter is whatenables the former: If package builds are deterministic, then independentbuilds of the package should yield the exact same result, bit for bit; if aserver provides a binary different from the one obtained locally, it may beeither corrupt or malicious.
We know that the hash that shows up in @file{/gnu/store} file names is thehash of all the inputs of the process that built the file ordirectory---compilers, libraries, build scripts,etc. (@pxref{Introduction}). Assuming deterministic build processes, onestore file name should map to exactly one build output. @command{guixchallenge} checks whether there is, indeed, a single mapping by comparingthe 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
@noindentIn this example, @command{guix challenge} first scans the store to determinethe set of locally-built derivations---as opposed to store items that weredownloaded from a substitute server---and then queries all the substituteservers. It then reports those store items for which the servers obtained aresult different from the local build.
@cindex non-determinism, in package buildsAs 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 ofGit is non-deterministic, meaning that its output varies as a function ofvarious things that Guix does not fully control, in spite of buildingpackages in isolated environments (@pxref{Features}). Most common sourcesof non-determinism include the addition of timestamps in build results, theinclusion 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 alongthese 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 localbuild, and the files resulting from the build on@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and MergingFiles,, diffutils, Comparing and Merging Files}). The @command{diff}command works great for text files. When binary files differ, a betteroption is @uref{https://diffoscope.org/,Diffoscope}, a tool that helpsvisualize differences for all kinds of files.
Once you have done that work, you can tell whether the differences are dueto a non-deterministic build process or to a malicious server. We try hardto remove sources of non-determinism in packages to make it easier to verifysubstitutes, 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 thesame build result as you did with:
@example$ guix challenge @var{package}@end example
@noindentwhere @var{package} is a package specification such as @code{guile@@2.0} or@code{glibc:debug}.
The general syntax is:
@exampleguix challenge @var{options} [@var{packages}@dots{}]@end example
When a difference is found between the hash of a locally-built item and thatof a server-provided substitute, or among substitutes provided by differentservers, the command displays it as in the example above and its exit codeis 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 URLsto compare to.
@item --verbose@itemx -vShow details about matches (identical contents) in addition to informationabout 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 machinesThe @command{guix copy} command copies items from the store of one machineto that of another machine over a secure shell (SSH)connection@footnote{This command is available only when Guile-SSH wasfound. @xref{Requirements}, for details.}. For example, the followingcommand copies the @code{coreutils} package, the user's profile, and alltheir dependencies over to @var{host}, logged in as @var{user}:
@exampleguix 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}, theyare not actually sent.
The command below retrieves @code{libreoffice} and @code{gimp} from@var{host}, assuming they are available there:
@exampleguix copy --from=@var{host} libreoffice gimp@end example
The SSH connection is established using the Guile-SSH client, which iscompatible 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 remotemachine. Likewise, the key used by the remote machine to sign items you areretrieving must be in @file{/etc/guix/acl} so it is accepted by your owndaemon. @xref{Invoking guix archive}, for more information about store itemauthentication.
The general syntax is:
@exampleguix 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 specsuch 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 storeitems, 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 NoteAs of version @value{VERSION}, this tool is experimental. The interface issubject to radical change in the future.@end quotation
The purpose of @command{guix container} is to manipulate processes runningwithin an isolated environment, commonly known as a ``container'', typicallycreated by the @command{guix environment} (@pxref{Invoking guixenvironment}) and @command{guix system container} (@pxref{Invoking guixsystem}) commands.
The general syntax is:
@exampleguix 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 execExecute a command within the context of a running container.
The syntax is:
@exampleguix 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 thecontainer. @var{arguments} are the additional options that will be passedto @var{program}.
The following command launches an interactive login shell inside a Guixsystem container, started by @command{guix system container}, and whoseprocess ID is 9001:
@exampleguix 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. Itmust 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 upbuilding packages by yourself (@pxref{Substitutes}). The @command{guixweather} command reports on substitute availability on the specified serversso you can have an idea of whether you'll be grumpy today. It can sometimesbe 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 availabilityHere's a sample run:
@example$ guix weather --substitute-urls=https://guix.example.orgcomputing 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, statisticsAs you can see, it reports the fraction of all the packages for whichsubstitutes are available on the server---regardless of whether substitutesare enabled, and regardless of whether this server's signing key isauthorized. It also reports the size of the compressed archives (``nars'')provided by the server, the size the corresponding store items occupy in thestore (assuming deduplication is turned off), and the server's throughput.The second part gives continuous integration (CI) statistics, if the serversupports it. In addition, using the @option{--coverage} option,@command{guix weather} can list ``important'' package substitutes missing onthe 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{guixchallenge}, it ignores signatures on those substitutes, which is innocuoussince the command only gathers statistics and cannot install thosesubstitutes.
Among other things, it is possible to query specific system types andspecific 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 isqueried.
@item --system=@var{system}@itemx -s @var{system}Query substitutes for @var{system}---e.g., @code{aarch64-linux}. Thisoption can be repeated, in which case @command{guix weather} will querysubstitutes for several system types.
@item --manifest=@var{file}Instead of querying substitutes for all the packages, only ask for thosespecified in @var{file}. @var{file} must contain a @dfn{manifest}, as withthe @code{-m} option of @command{guix package} (@pxref{Invoking guixpackage}).
@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 areunavailable. 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 lookslike this:
@example$ guix weather --substitute-urls=https://ci.guix.zh_CN.info -c 10computing 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 58packages 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 maysimply 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 systemadministrators, especially on multi-user machines and on build farms: itlists the current sessions (connections to the daemon), as well asinformation about the processes involved@footnote{Remote sessions, when@command{guix-daemon} is started with @option{--listen} specifying a TCPendpoint, are @emph{not} listed.}. Here's an example of the information itreturns:
@example$ sudo guix processesSessionPID: 19002ClientPID: 19090ClientCommand: guix environment --ad-hoc python
SessionPID: 19402ClientPID: 19367ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
SessionPID: 19444ClientPID: 19419ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lockLockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lockLockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lockChildProcess: 20495: guix offload x86_64-linux 7200 1 28800ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800ChildProcess: 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 Cuirasscontinuous 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 bythis session, which corresponds to store items being built or substituted(the @code{LockHeld} field is not displayed when @command{guix processes} isnot running as root.) Last, by looking at the @code{ChildProcess} field, weunderstand that these three builds are being offloaded (@pxref{DaemonOffload 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 thecommand line and PID of the client that triggered the build of a Perlpackage:
@example$ sudo guix processes | \ recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'ClientPID: 19419ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}@end example

@node System Configuration@chapter System Configuration
@cindex system configurationThe Guix System Distribution supports a consistent whole-systemconfiguration mechanism. By that we mean that all aspects of the globalsystem configuration---such as the available system services, timezone andlocale 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 thecontrol of Guix is that it supports transactional system upgrades, and makesit possible to roll back to a previous system instantiation, shouldsomething go wrong with the new one (@pxref{Features}). Another advantageis that it makes it easy to replicate the exact same configuration acrossdifferent machines, or at different points in time, without having to resortto additional administration tools layered on top of the own tools of thesystem.
This section describes this mechanism. First we focus on the systemadministrator's viewpoint---explaining how the system is configured andinstantiated. Then we show how this mechanism can be extended, for instanceto 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 defaultsystem services, the default Linux-Libre kernel, initial RAM disk, and bootloader 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, suchas @code{packages} and @code{services}, can be omitted, in which case theyget a default value.
Below we discuss the effect of some of the most important fields(@pxref{operating-system Reference}, for details about all the availablefields), 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 bootThe @code{bootloader} field describes the method that will be used to bootyour system. Machines based on Intel processors can boot in ``legacy'' BIOSmode, as in the example above. However, more recent machines rely insteadon the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In thatcase, the @code{bootloader} field should contain something along theselines:
@example(bootloader-configuration (bootloader grub-efi-bootloader) (target "/boot/efi"))@end example
@xref{Bootloader Configuration}, for more information on the availableconfiguration options.
@unnumberedsubsec Globally-Visible Packages
@vindex %base-packagesThe @code{packages} field lists packages that will be globally visible onthe system, for all user accounts---i.e., in every user's @code{PATH}environment variable---in addition to the per-user profiles (@pxref{Invokingguix package}). The @var{%base-packages} variable provides all the toolsone would expect for basic user and administrator tasks---including the GNUCore Utilities, the GNU Networking Utilities, the GNU Zile lightweight texteditor, @command{find}, @command{grep}, etc. The example above addsGNU@tie{}Screen to those, taken from the @code{(gnu packages screen)} module(@pxref{Package Modules}). The @code{(list package output)} syntax can beused 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->packageReferring to packages by variable name, like @code{bind} above, has theadvantage of being unambiguous; it also allows typos and such to bediagnosed right away as ``unbound variables''. The downside is that oneneeds 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-servicesThe @code{services} field lists @dfn{system services} to be made availablewhen the system starts (@pxref{Services}). The @code{operating-system}declaration above specifies that, in addition to the basic services, we wantthe OpenSSH secure shell daemon listening on port 2222 (@pxref{NetworkingServices, @code{openssh-service-type}}). Under the hood,@code{openssh-service-type} arranges so that @command{sshd} is started withthe right command-line options, possibly with supporting configuration filesgenerated as needed (@pxref{Defining Services}).
@cindex customization, of services@findex modify-servicesOccasionally, instead of using the base services as is, you will want tocustomize them. To do this, use @code{modify-services} (@pxref{ServiceReference, @code{modify-services}}) to modify the list.
For example, suppose you want to modify @code{guix-daemon} and Mingetty (theconsole log-in) in the @var{%base-services} list (@pxref{Base Services,@code{%base-services}}). To do that, you can write the following in youroperating 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 originalconfiguration 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 desiredconfiguration. In particular, notice how we use @code{inherit} to create anew configuration which has the same values as the old configuration, butwith a few modifications.
@cindex encrypted diskThe configuration for a typical ``desktop'' usage, with an encrypted rootpartition, the X11 display server, GNOME and Xfce (users can choose which ofthese desktop environments to use at the log-in screen by pressing@kbd{F1}), network management, power management, and more, would look likethis:
@lisp@include os-config-desktop.texi@end lisp
A graphical system with a choice of lightweight window managers instead offull-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, asreturned by the @command{blkid} command.
@xref{Desktop Services}, for the exact list of services provided by@var{%desktop-services}. @xref{X.509 Certificates}, for backgroundinformation about the @code{nss-certs} package that is used here.
Again, @var{%desktop-services} is just a list of service objects. If youwant to remove services from there, you can do so using the procedures forlist filtering (@pxref{SRFI-1 Filtering and Partitioning,,, guile, GNU GuileReference Manual}). For instance, the following expression returns a listthat contains all the services in @var{%desktop-services} minus the Avahiservice:
@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 reconfiguremy-system-config.scm} command instantiates that configuration, and makes itthe default GRUB boot entry (@pxref{Invoking guix system}).
The normal way to change the system configuration is by updating this fileand re-running @command{guix system reconfigure}. One should never have totouch files in @file{/etc} or to run commands that modify the system statesuch as @command{useradd} or @command{grub-install}. In fact, you mustavoid that since that would not only void your warranty but also prevent youfrom rolling back to previous versions of your system, should you ever needto.
@cindex roll-back, of the operating systemSpeaking of roll-back, each time you run @command{guix system reconfigure},a new @dfn{generation} of the system is created---without modifying ordeleting previous generations. Old system generations get an entry in thebootloader boot menu, allowing you to boot them in case something went wrongwith the latest generation. Reassuring, no? The @command{guix systemlist-generations} command lists the system generations available on disk.It is also possible to roll back the system via the commands @command{guixsystem roll-back} and @command{guix system switch-generation}.
Although the @command{guix system reconfigure} command will not modifyprevious generations, you must take care when the current generation is notthe latest (e.g., after invoking @command{guix system roll-back}), since theoperation 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 isinstantiated with the following monadic procedure (@pxref{The Store Monad}):
@deffn {Monadic Procedure} operating-system-derivation osReturn 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 thepackages, configuration files, and other supporting files needed toinstantiate @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 ofGuix 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-systemThis is the data type representing an operating system configuration. Bythat, we mean all the global system configuration, not per-userconfiguration (@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{Currentlyonly the Linux-libre kernel is supported. In the future, it will bepossible to use the GNU@tie{}Hurd.}.
@item @code{kernel-arguments} (default: @code{'("quiet")})List of strings or gexps representing additional arguments to pass on thecommand-line of the kernel---e.g., @code{("console=ttyS0")}.
@item @code{bootloader}The system bootloader configuration object. @xref{BootloaderConfiguration}.
@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 beeither @code{#f}, in which case the default keyboard layout is used (usuallyUS English), or a @code{<keyboard-layout>} record.
This keyboard layout is in effect as soon as the kernel has booted. Forinstance, it is the keyboard layout in effect when you type a passphrase ifyour root file system is on a @code{luks-device-mapping} mapped device(@pxref{Mapped Devices}).
@quotation NoteThis does @emph{not} specify the keyboard layout used by the bootloader, northat used by the graphical display server. @xref{Bootloader Configuration},for information on how to specify the bootloader's keyboard layout. @xref{XWindow}, for information on how to specify the keyboard layout used by the XWindow System.@end quotation
@item @code{initrd-modules} (default: @code{%base-initrd-modules})@cindex initrd@cindex initial RAM diskThe list of Linux kernel modules that need to be available in the initialRAM disk. @xref{Initial RAM Disk}.
@item @code{initrd} (default: @code{base-initrd})A procedure that returns an initial RAM disk for the Linux kernel. Thisfield is provided to support low-level customization and should rarely beneeded for casual use. @xref{Initial RAM Disk}.
@item @code{firmware} (default: @var{%base-firmware})@cindex firmwareList of firmware packages loadable by the operating system kernel.
The default includes firmware needed for Atheros- and Broadcom-based WiFidevices (Linux-libre modules @code{ath9k} and @code{b43-open},respectively). @xref{Hardware Considerations}, for more info on supportedhardware.
@item @code{host-name}The host name.
@item @code{hosts-file}@cindex hosts fileA file-like object (@pxref{G-Expressions, file-like objects}) for use as@file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library ReferenceManual}). 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 devicesA list of strings identifying devices or files to be used for ``swap space''(@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}). Forexample, @code{'("/dev/sda3")} or @code{'("/swapfile")}. It is possible tospecify a swap file in a file system on a mapped device, provided that thenecessary device mapping and file system are also specified. @xref{MappedDevices} 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 thehome 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 isdisplayed 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 installnon-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 stringcorresponds 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 CLibrary 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 runtime. @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 tobuild the locale definitions. @xref{Locales}, for compatibilityconsiderations 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}, fordetails.
@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{ServiceReference}), 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{SetuidPrograms}.
@item @code{sudoers-file} (default: @var{%sudoers-specification})@cindex sudoers fileThe 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, whatthey are allowed to do, and what privileges they may gain. The default isthat only @code{root} and members of the @code{wheel} group may use@code{sudo}.
@end table
@deffn {Scheme Syntax} this-operating-systemWhen used in the @emph{lexical scope} of an operating system fielddefinition, this identifier resolves to the operating system being defined.
The example below shows how to refer to the operating system being definedin 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 operatingsystem 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{Usingthe 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 exampleabove---while others can be omitted. These are described below.
@deftp {Data Type} file-systemObjects of this type represent file systems to be mounted. They contain thefollowing 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 threethings: 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 systemswithout having to hard-code their actual device name@footnote{Note that,while it is tempting to use @file{/dev/disk/by-uuid} and similar devicenames to achieve the same result, this is not recommended: These specialdevice nodes are created by the udev daemon and may be unavailable at thetime the device is mounted.}.
@findex file-system-labelFile system labels are created using the @code{file-system-label} procedure,UUIDs are created using @code{uuid}, and @file{/dev} node are plainstrings. Here's an example of a file system referred to by its label, asshown by the @command{e2label} command:
@example(file-system (mount-point "/home") (type "ext4") (device (file-system-label "my-home")))@end example
@findex uuidUUIDs 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 formof UUID used by the ext2 family of file systems and others, but it isdifferent from ``UUIDs'' found in FAT file systems, for instance.}, likethis:
@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{MappedDevices}), its @code{device} field @emph{must} refer to the mapped devicename---e.g., @file{"/dev/mapper/root-partition"}. This is required so thatthe system knows that mounting the file system depends on having thecorresponding 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 tospecial 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 thesystem is brought up. When set to @code{#f}, the file system gets an entryin @file{/etc/fstab} (read by the @command{mount} command) but is notautomatically mounted.
@item @code{needed-for-boot?} (default: @code{#f})This Boolean value indicates whether the file system is needed whenbooting. If that is true, then the file system is mounted when the initialRAM disk (initrd) is loaded. This is always the case, for instance, for theroot file system.
@item @code{check?} (default: @code{#t})This Boolean indicates whether the file system needs to be checked forerrors 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>} objectsrepresenting file systems that must be mounted or mapped devices that mustbe opened before (and unmounted or closed after) this one.
As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is adependency of @file{/sys/fs/cgroup/cpu} and @file{/sys/fs/cgroup/memory}.
Another example is a file system that depends on a mapped device, forexample 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-systemsThese are essential file systems that are required on normal systems, suchas @var{%pseudo-terminal-file-system} and @var{%immutable-store} (seebelow.) Operating system declarations should always contain at least these.@end defvr
@defvr {Scheme Variable} %pseudo-terminal-file-systemThis 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-systemThis file system is mounted as @file{/dev/shm} and is used to support memorysharing across processes (@pxref{Memory-mapped I/O, @code{shm_open},, libc,The GNU C Library Reference Manual}).@end defvr
@defvr {Scheme Variable} %immutable-storeThis file system performs a read-only ``bind mount'' of @file{/gnu/store},making it read-only for all the users including @code{root}. This preventsagainst accidental modification by software running as @code{root} or bysystem administrators.
The daemon itself is still able to write to the store: it remounts itread-write in its own ``name space.''@end defvr
@defvr {Scheme Variable} %binary-format-file-systemThe @code{binfmt_misc} file system, which allows handling of arbitraryexecutable 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-systemThe @code{fusectl} file system, which allows unprivileged users to mount andunmount 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 devicesThe Linux kernel has a notion of @dfn{device mapping}: a block device, suchas a hard disk partition, can be @dfn{mapped} into another device, usuallyin @code{/dev/mapper/}, with additional processing over the data that flowsthrough it@footnote{Note that the GNU@tie{}Hurd makes no difference betweenthe concept of a ``mapped device'' and that of a file system: both boil downto @emph{translating} input/output operations made on a file to operationson its backing store. Thus, the Hurd implements mapped devices, like filesystems, using the generic @dfn{translator} mechanism (@pxref{Translators,,,hurd, The GNU Hurd Reference Manual}).}. A typical example is encryptiondevice mapping: all writes to the mapped device are encrypted, and all readsare deciphered, transparently. Guix extends this notion by considering anydevice or set of devices that are @dfn{transformed} in some way to create anew device; for instance, RAID devices are obtained by @dfn{assembling}several other devices, such as hard disks or partitions, into a new one thatbehaves as one partition. Other examples, not yet implemented, are LVMlogical volumes.
Mapped devices are declared using the @code{mapped-device} form, defined asfollows; for examples, see below.
@deftp {Data Type} mapped-deviceObjects of this type represent device mappings that will be made when thesystem boots up.
@table @code@item sourceThis is either a string specifying the name of the block device to bemapped, such as @code{"/dev/sda3"}, or a list of such strings when severaldevices need to be assembled for creating a new one.
@item targetThis string specifies the name of the resulting mapped device. For kernelmappers 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 typeThis 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-mappingThis 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-mappingThis defines a RAID device, which is assembled using the @code{mdadm}command from the package with the same name. It requires a Linux kernelmodule 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 LUKSThe following example specifies a mapping from @file{/dev/sda3} to@file{/dev/mapper/home} using LUKS---the@url{https://gitlab.com/cryptsetup/cryptsetup,LinuxUnified Key Setup}, astandard mechanism for disk encryption. The @file{/dev/mapper/home} devicecan 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 theLUKS UUID (@dfn{unique identifier}) of the source device by a command like:
@examplecryptsetup 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 encryptionIt is also desirable to encrypt swap space, since swap space may containsensitive data. One way to accomplish that is to use a swap file in a filesystem on a device mapped via LUKS encryption. In this way, the swap fileis encrypted because the entire device is encrypted. @xref{Preparing forInstallation,,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 RAIDlevel need not be given; it is chosen during the initial creation andformatting of the RAID device and is determined automatically later.

@node User Accounts@section User Accounts
@cindex users@cindex accounts@cindex user accountsUser 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}, thesystem ensures that only the user accounts and groups specified in the@code{operating-system} declaration exist, and with the specifiedproperties. Thus, account or group creations or modifications made bydirectly invoking commands such as @command{useradd} are lost uponreconfiguration or reboot. This ensures that the system remains exactly asdeclared.
@deftp {Data Type} user-accountObjects of this type represent user accounts. The following members may bespecified:
@table @asis@item @code{name}The name of the user account.
@item @code{group}@cindex groupsThis is the name (a string) or identifier (a number) of the user group thisaccount belongs to.
@item @code{supplementary-groups} (default: @code{'()})Optionally, this can be defined as a list of group names that this accountbelongs to.
@item @code{uid} (default: @code{#f})This is the user ID for this account (a number), or @code{#f}. In thelatter case, a number is automatically chosen by the system when the accountis 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 itdoes not exist yet.
@item @code{shell} (default: Bash)This is a G-expression denoting the file name of a program to be used as theshell (@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, graphicallogin 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 passwordsas @code{root} with the @command{passwd} command, and then let users changeit with @command{passwd}. Passwords set with @command{passwd} are of coursepreserved across reboot and reconfiguration.
If you @emph{do} want to set an initial password for an account, then thisfield 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 NoteThe 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 usedwith care.@end quotation
@xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, formore information on password encryption, and @ref{Encryption,,, guile, GNUGuile Reference Manual}, for information on Guile's @code{crypt} procedure.
@end table@end deftp
@cindex groupsUser group declarations are even simpler:
@example(user-group (name "students"))@end example
@deftp {Data Type} user-groupThis 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 isautomatically 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-groupsThis is the list of basic user groups that users and/or packages expect tobe present on the system. This includes groups such as ``root'', ``wheel'',and ``users'', as well as groups used to control access to specific devicessuch as ``audio'', ``disk'', and ``cdrom''.@end defvr
@defvr {Scheme Variable} %base-user-accountsThis is the list of basic system accounts that programs may expect to findon a GNU/Linux system, such as the ``nobody'' account.
Note that the ``root'' account is not included here. It is a special-caseand is automatically added whether or not it is specified.@end defvr
@node Keyboard Layout@section Keyboard Layout
@cindex keyboard layout@cindex keymapTo specify what each key of your keyboard does, you need to tell theoperating system what @dfn{keyboard layout} you want to use. The default,when nothing is specified, is the US English QWERTY layout for 105-key PCkeyboards. However, German speakers will usually prefer the German QWERTZlayout, French speakers will want the AZERTY layout, and so on; hackersmight prefer Dvorak or bépo, and they might even want to further customizethe effect of some of the keys. This section explains how to get that done.
@cindex keyboard layout, definitionThere are three components that will want to know about your keyboardlayout:
@itemize@itemThe @emph{bootloader} may want to know what keyboard layout you want to use(@pxref{Bootloader Configuration, @code{keyboard-layout}}). This is usefulif you want, for instance, to make sure that you can type the passphrase ofyour encrypted root partition using the right layout.
@itemThe @emph{operating system kernel}, Linux, will need that so that theconsole is properly configured (@pxref{operating-system Reference,@code{keyboard-layout}}).
@itemThe @emph{graphical display server}, usually Xorg, also has its own idea ofthe keyboard layout (@pxref{X Window, @code{keyboard-layout}}).@end itemize
Guix allows you to configure all three separately but, fortunately, itallows you to share the same keyboard layout for all three components.
@cindex XKB, keyboard layoutsKeyboard layouts are represented by records created by the@code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Followingthe 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 possiblyempty list of additional options. In most cases the layout name is all youcare 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, configurationLet's say you want your system to use the Turkish keyboard layout throughoutyour system---bootloader, console, and Xorg. Here's what your systemconfiguration 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 referto a different layout. The @code{set-xorg-configuration} procedurecommunicates 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 yoursystem when it starts, but you can also adjust it at run time:
@itemize@itemIf you're using GNOME, its settings panel has a ``Region & Language'' entrywhere you can select one or more keyboard layouts.
@itemUnder Xorg, the @command{setxkbmap} command (from the same-named package)allows you to change the current layout. For example, this is how you wouldchange the layout to US Dvorak:
@examplesetxkbmap us dvorak@end example
@itemThe @code{loadkeys} command changes the keyboard layout in effect in theLinux console. However, note that @code{loadkeys} does @emph{not} use theXKB keyboard layout categorization described above. The command below loadsthe French bépo layout:
@exampleloadkeys fr-bepo@end example@end itemize
@node Locales@section Locales
@cindex localeA @dfn{locale} defines cultural conventions for a particular language andregion of the world (@pxref{Locales,,, libc, The GNU C Library ReferenceManual}). 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, withcultural conventions from Luxembourg, and using the UTF-8 encoding.
@cindex locale definitionUsually, you will want to specify the default locale for the machine usingthe @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 itsname---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, butnot all the available locales, in order to save space.
For instance, to add the North Frisian locale for Germany, the value of thatfield 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 listonly 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 LOCPATHThe 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 looksfor locale data. This can be overridden using the @code{LOCPATH}environment variable (@pxref{locales-and-locpath, @code{LOCPATH} and localepackages}).
The @code{locale-definition} form is provided by the @code{(gnu systemlocale)} module. Details are given below.
@deftp {Data Type} locale-definitionThis 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 LibraryReference 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-definitionsA 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 namesThese locale definitions use the @dfn{normalized codeset} for the part thatfollows the dot in the name (@pxref{Using gettextized software, normalizedcodeset,, libc, The GNU C Library Reference Manual}). So for instance ithas @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 tospecify the GNU@tie{}libc packages that are used to compile localedeclarations (@pxref{operating-system Reference}). ``Why would I care?'',you may ask. Well, it turns out that the binary format of locale data isoccasionally 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 readlocale data produced with libc 2.22; worse, that program @emph{aborts}instead of simply ignoring the incompatible locale data@footnote{Versions2.23 and later of GNU@tie{}libc will simply skip the incompatible localedata, which is already an improvement.}. Similarly, a program linkedagainst libc 2.22 can read most, but not all, of the locale data from libc2.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 canchoose whether and when to upgrade software in their profiles, and might beusing a libc version different from the one the system administrator used tobuild the system-wide locale data.
Fortunately, unprivileged users can also install their own locale data anddefine @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 versionsactually in use on the system, so that all the programs can access it---thisis especially crucial on a multi-user system. To do that, the administratorcan 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 bothlibc 2.21 and the current version of libc in@file{/run/current-system/locale}.

@node Services@section Services
@cindex system servicesAn important part of preparing an @code{operating-system} declaration islisting @dfn{system services} and their configuration (@pxref{Using theConfiguration System}). System services are typically daemons launched whenthe system boots, or other actions needed at that time---e.g., configuringnetwork access.
Guix has a broad definition of ``service'' (@pxref{Service Composition}),but many services are managed by the GNU@tie{}Shepherd (@pxref{ShepherdServices}). On a running system, the @command{herd} command allows you tolist the available services, show their status, start and stop them, or doother specific operations (@pxref{Jump Start,,, shepherd, The GNU ShepherdManual}). For example:
@example# herd status@end example
The above command, run as @code{root}, lists the currently definedservices. The @command{herd doc} command shows a synopsis of the givenservice and its associated actions:
@example# herd doc nscdRun libc's name service cache daemon (nscd).
# herd doc nscd action invalidateinvalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.@end example
The @command{start}, @command{stop}, and @command{restart} sub-commands havethe effect you would expect. For instance, the commands below stop the nscdservice and restart the Xorg display server:
@example# herd stop nscdService nscd has been stopped.# herd restart xorg-serverService xorg-server has been stopped.Service xorg-server has been started.@end example
The following sections document the available services, starting with thecore 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 basicservices that one expects from the system. The services exported by thismodule are listed below.
@defvr {Scheme Variable} %base-servicesThis variable contains a list of basic services (@pxref{Service Types andServices}, for more information on service objects) one would expect fromthe system: a login service (mingetty) on each tty, syslogd, the libc nameservice 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-typeThis 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 bea list of tuples where the first element is the ``special file'' and thesecond 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 changeit 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{ServiceReference, @code{modify-services}}). But the simple way to add a specialfile 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 youroperating 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-configurationThis is the data type representing the configuration of login.
@table @asis
@item @code{motd}@cindex message of the dayA 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 whenthe '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-configurationThis is the data type representing the configuration of Mingetty, whichprovides 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 whichthe system automatically logs in. When it is @code{#f}, a user name andpassword 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 isused (@command{login} from the Shadow tool suite), or a gexp denoting thename 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 willhave 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, amongother things.@end deffn
@deftp {Data Type} agetty-configurationThis is the data type representing the configuration of agetty, whichimplements virtual and serial console log-in. See the @code{agetty(8)} manpage 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 reasonabledefault serial port used by the kernel Linux.
For this, if there is a value for an option @code{agetty.tty} in the kernelcommand line, agetty will extract the device name of the serial port from itand use that.
If not and if there is a value for an option @code{console} with a tty inthe Linux command line, agetty will extract the device name of the serialport from it and use that.
In both cases, agetty will leave the other serial device settings (baud rateetc.)@: 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, indescending 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 detectionis disabled.
@item @code{auto-login} (default: @code{#f})When passed a login name, as a string, the specified user will be logged inautomatically 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 writteninto 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 specifiedin @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 notbe 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 sendinganything 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 thelogin 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 toolsuite.
@item @code{local-line} (default: @code{#f})Control the CLOCAL line flag. This accepts one of three symbols asarguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f}, thedefault 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 fromthe 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 beused 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 loginprogram. When used with the @var{login-program}, be aware that a malicioususer could try to enter a login name containing embedded options that couldbe 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 bylazily spawning shells.
@item @code{chroot} (default: @code{#f})Change root to the specified directory. This option accepts a directorypath as a string.
@item @code{hangup?} (default: @code{#f})Use the Linux system call @code{vhangup} to do a virtual hangup of thespecified terminal.
@item @code{keep-baud?} (default: @code{#f})When set to @code{#t}, try to keep the existing baud rate. The baud ratesfrom @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-onlyterminal. This setting will detect a login name containing only uppercaseletters as indicating an uppercase-only terminal and turn on someupper-to-lower case conversions. Note that this will not support Unicodecharacters.
@item @code{wait-cr?} (default: @code{#f})When set to @code{#t}, wait for the user or modem to send a carriage-returnor 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 thisoption 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 beinterpreted 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 allprevious characters" (also called a "kill" character) when the types theirlogin name.
@item @code{chdir} (default: @code{#f})This option accepts, as a string, a directory path that will be changed tobefore login.
@item @code{delay} (default: @code{#f})This options accepts, as an integer, the number of seconds to sleep beforeopening 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 arbitrarycommand-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 thetty to run, among other things.@end deffn
@deftp {Data Type} kmscon-configurationThis is the data type representing the configuration of Kmscon, whichimplements 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 programis @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 inautomatically 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 cachedaemon (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 followingactions:
@table @code@item invalidate@cindex cache invalidation, nscd@cindex nscd, cache invalidationThis invalidate the given cache. For instance, running:
@exampleherd invalidate nscd hosts@end example
@noindentinvalidates the host name lookup cache of nscd.
@item statisticsRunning @command{herd statistics nscd} displays information about nscd usageand caches.@end table
@end deffn
@defvr {Scheme Variable} %nscd-default-configurationThis 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-configurationThis 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 thenscd---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 moredebugging 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-cacheData 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. Validvalues 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 ornegative 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 flaginstructs nscd to check for updates in @file{/etc/hosts} and to take theminto 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-cachesList of @code{<nscd-cache>} objects used by default by@code{nscd-configuration} (see above).
It enables persistent and aggressive caching of service and host namelookups. The latter provides better host name lookup performance,resilience in the face of unreliable name servers, and also betterprivacy---often the result of host name lookups is in local cache, soexternal name servers do not even need to be queried.@end defvr
@anchor{syslog-configuration-type}@cindex syslog@cindex logging@deftp {Data Type} syslog-configurationThis 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 informationon the configuration file syntax.@end deffn
@defvr {Scheme Variable} guix-service-typeThis 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-configurationThis 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 thereofWhether 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 ofstring-valued gexps (@pxref{Invoking guix archive}). By default, itcontains 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 zerodisables 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 arewritten.
@item @code{http-proxy} (default: @code{#f})The HTTP proxy used for downloading fixed-output derivations andsubstitutes.
@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. udevrules 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{(gnuservices 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 definedby the @var{contents} literal.
In the following example, a rule for a USB device is defined to be stored inthe file @file{90-usb-thing.rules}. The rule runs a script upon detecting aUSB 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 thedirectory 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} inorder 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{(gnupackages android)} module.
The following example shows how to use the @var{android-udev-rules} packageso that the Android tool @command{adb} can detect devices without rootprivileges. It also details how to create the @code{adbusers} group, whichis required for the proper functioning of the rules defined within the@var{android-udev-rules} package. To create such a group, we must define itboth 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-typeSave 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 isreadable.@end defvr
@defvr {Scheme Variable} %random-seed-fileThis is the name of the file where some random bytes are saved by@var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting. Itdefaults to @file{/var/lib/random-seed}.@end defvr
@cindex mouse@cindex gpm@defvr {Scheme Variable} gpm-service-typeThis is the type of the service that runs GPM, the @dfn{general-purposemouse daemon}, which provides mouse support to the Linux console. GPMallows users to use the mouse in the console, notably to select, copy, andpaste text.
The value for services of this type must be a @code{gpm-configuration} (seebelow). This service is not part of @var{%base-services}.@end defvr
@deftp {Data Type} gpm-configurationData 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 optionsinstruct @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-typeThis is the service type for @command{guix publish} (@pxref{Invoking guixpublish}). Its value must be a @code{guix-configuration} object, asdescribed below.
This assumes that @file{/etc/guix} already contains a signing key pair ascreated by @command{guix archive --generate-key} (@pxref{Invoking guixarchive}). If that is not the case, the service will fail to start.@end deffn
@deftp {Data Type} guix-publish-configurationData 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 bestcompression 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 ondemand. Otherwise, this should be the name of a directory---e.g.,@code{"/var/cache/guix/publish"}---where @command{guix publish} cachesarchives 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 forcaching; when @code{#f}, the number of processors is used. @xref{Invokingguix 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 thepublished archives. @xref{Invoking guix publish, @option{--ttl}}, for moreinformation.@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 entropypool. 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 loginsessions 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-privilegedprocesses; the second entry lifts any restriction of the maximum addressspace that can be locked in memory. These settings are commonly used forreal-time audio systems.@end deffn
@node Scheduled Job Execution@subsection Scheduled Job Execution
@cindex cron@cindex mcron@cindex scheduling jobsThe @code{(gnu services mcron)} module provides an interface toGNU@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 inGuile Scheme, which provides a lot of flexibility when specifying thescheduling of jobs and their actions.
The example below defines an operating system that runs the@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files}) andthe @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as well asthe @command{mkid} command on behalf of an unprivileged user (@pxref{mkidinvocation,,, idutils, ID Database Utilities}). It uses gexps to introducejob 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}, formore information on mcron job specifications. Below is the reference of themcron service.
On a running system, you can use the @code{schedule} action of the serviceto visualize the mcron jobs that will be executed next:
@example# herd schedule mcron@end example
@noindentThe example above lists the next five tasks that will be executed, but youcan also specify the number of tasks to display:
@example# herd schedule mcron 10@end example
@defvr {Scheme Variable} mcron-service-typeThis 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 itadditional job specifications (@pxref{Service Composition}). In otherwords, it is possible to define services that provide additional mcron jobsto run.@end defvr
@deftp {Data Type} mcron-configurationData 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 correspondsto 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 loggingLog files such as those found in @file{/var/log} tend to grow endlessly, soit's a good idea to @dfn{rotate} them once in a while---i.e., archive theircontents in separate files, possibly compressed. The @code{(gnu servicesadmin)} module provides an interface to GNU@tie{}Rot[t]log, a log rotationtool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
The example below defines an operating system that provides log rotationwith 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-typeThis 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 (seebelow), thereby augmenting the set of files to be rotated.
This service type can define mcron jobs (@pxref{Scheduled Job Execution}) torun the rottlog service.@end defvr
@deftp {Data Type} rottlog-configurationData 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 jobspecification (@pxref{Scheduled Job Execution}).@end table@end deftp
@deftp {Data Type} log-rotationData type representing the rotation of a group of log files.
Taking an example from the Rottlog manual (@pxref{Period Related FileExamples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be definedlike 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{Configurationparameters,,, 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-rotationsSpecifies weekly rotation of @var{%rotated-files} and a couple of otherfiles.@end defvr
@defvr {Scheme Variable} %rotated-filesThe 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 configurethe network interface.
@cindex DHCP, networking service@defvr {Scheme Variable} dhcp-client-service-typeThis is the type of services that run @var{dhcp}, a Dynamic HostConfiguration Protocol (DHCP) client, on all the non-loopback networkinterfaces. Its value is the DHCP client package to use, @code{isc-dhcp} bydefault.@end defvr
@deffn {Scheme Procedure} dhcpd-service-typeThis type defines a service that runs a DHCP daemon. To create a service ofthis 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 toprovide the daemon at @file{sbin/dhcpd} relative to its output directory.The default package is the @uref{http://www.isc.org/products/DHCP,ISC'sDHCP 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{mandhcpd.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 willbe 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 forbroadcasts. If this list is not empty, then its elements (which must bestrings) will be appended to the @code{dhcpd} invocation when starting thedaemon. 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 networkgateway. @var{requirement} can be used to declare a dependency on anotherservice before configuring the interface.
This procedure can be called several times, one for each network interfaceof interest. Behind the scenes what it does is extend@code{static-networking-service-type} with additional network interfaces tohandle.
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 networkmanagement daemon that aims to simplify wired and wireless networking.
This service adds the @var{wicd} package to the global profile, providingseveral 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-typeThis 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-configurationData 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-typeThis 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-configurationData 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 defaultNetworkManager will update @code{resolv.conf} to reflect the nameserversprovided by currently active connections.
@item dnsmasqNetworkManager will run @code{dnsmasq} as a local caching nameserver, usinga "split DNS" configuration if you are connected to a VPN, and then update@code{resolv.conf} to point to the local nameserver.
@item noneNetworkManager 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, whichallows NetworkManager to manage VPNs @i{via} OpenVPN.
@end table@end deftp
@cindex Connman@deffn {Scheme Variable} connman-service-typeThis is the service type to run @url{https://01.org/connman,Connman},anetwork 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-configurationData 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-typeThis is the service type to run @url{https://w1.fi/wpa_supplicant/,WPAsupplicant}, an authentication daemon required to authenticate againstencrypted WiFi or ethernet networks.@end defvr
@deftp {Data Type} wpa-supplicant-configurationData 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 WPAsupplicant 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-typeThis is the service type to set up an iptables configuration. iptables is apacket filtering framework supported by the Linux kernel. This servicesupports configuring iptables for both IPv4 and IPv6. A simple exampleconfiguration rejecting all incoming connections except those to the sshport 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-unreachableCOMMIT")) (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-unreachableCOMMIT"))))@end lisp@end defvr
@deftp {Data Type} iptables-configurationThe 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-likeobjects}).@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-likeobjects}).@end table@end deftp
@cindex NTP (Network Time Protocol), service@cindex real time clock@defvr {Scheme Variable} ntp-service-typeThis is the type of the service running the @uref{http://www.ntp.org,Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keepthe system clock synchronized with that of the specified NTP servers.
The value of this service is an @code{ntpd-configuration} object, asdescribed below.@end defvr
@deftp {Data Type} ntp-configurationThis 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 besynchronized.
@item @code{allow-large-adjustment?} (default: @code{#f})This determines whether @command{ntpd} is allowed to make an initialadjustment 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-serversList of host names used as the default NTP servers. These are servers ofthe @uref{https://www.ntppool.org/en/,NTP Pool Project}.@end defvr
@cindex OpenNTPD@deffn {Scheme Procedure} openntpd-service-typeRun the @command{ntpd}, the Network Time Protocol (NTP) daemon, asimplemented by @uref{http://www.openntpd.org, OpenNTPD}. The daemon willkeep 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-existantones. 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 synchronizeto.@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 serversvia TLS. This time information is not used for precision but acts as anauthenticated constraint, thereby reducing the impact of unauthenticated NTPman-in-the-middle attacks. Specify a list of URLs, IP addresses orhostnames 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 hostnamesof HTTPS servers to provide a constraint. Should the hostname resolve tomultiple IP addresses, @code{ntpd} will calculate a median constraint fromall of them.@item @code{allow-large-adjustment?} (default: @code{#f})Determines if @code{ntpd} is allowed to make an initial adjustment of morethan 180 seconds.@end table@end deftp
@cindex inetd@deffn {Scheme variable} inetd-service-typeThis service runs the @command{inetd} (@pxref{inetd invocation,,, inetutils,GNU Inetutils}) daemon. @command{inetd} listens for connections on internetsockets, and lazily starts the specified server program when a connection ismade on one of these sockets.
The value of this service is an @code{inetd-configuration} object. Thefollowing example configures the @command{inetd} daemon to provide thebuilt-in @command{echo} service, as well as an smtp service which forwardssmtp 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-configurationData 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 bythe @code{inetd-entry} constructor.@end table@end deftp
@deftp {Data Type} inetd-entryData type representing an entry in the @command{inetd} configuration. Eachentry corresponds to a socket where @command{inetd} will listen forrequests.
@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 listeningto new service requests.@item @code{user}A string containing the user (and, optionally, group) name of the user aswhom 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'sarguments, starting with the zeroth argument, i.e.@: the name of the programitself. 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 detaileddiscussion of each configuration field.@end deftp
@cindex Tor@defvr {Scheme Variable} tor-service-typeThis 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 toprovide the daemon at @file{bin/tor} relative to its output directory. Thedefault 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 defaultconfiguration 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 detailson the configuration file syntax.
@item @code{hidden-services} (default: @code{'()})The list of @code{<hidden-service>} records to use. For any hidden serviceyou include in this list, appropriate configuration to enable the hiddenservice will be automatically added to the default configuration file. Youmay 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 mustbe either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then bydefault 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 domainsocket @file{/var/run/tor/socks-sock}, which will be made writable bymembers 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 thehidden service.
See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en,theTor 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 soanyone (or just yourself) can download existing files or upload new files.
@deffn {Scheme Variable} rsync-service-typeThis 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-configurationData 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 portis 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 takeplace 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 listenon port @var{port-number}. @var{host-key} must designate a file containingthe host key, and readable only by root.
When @var{daemonic?} is true, @command{lshd} will detach from thecontrolling terminal and log its output to syslogd, unless one sets@var{syslog-output?} to false. Obviously, it also makes lsh-service dependon 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 keyupon service activation if they do not exist yet. This may take long andrequire interaction.
When @var{initialize?} is false, it is up to the user to initialize therandomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and tocreate 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 thenetwork interfaces; otherwise, @var{interfaces} must be a list of host namesor addresses.
@var{allow-empty-passwords?} specifies whether to accept log-ins with emptypasswords, and @var{root-login?} specifies whether to accept log-ins asroot.
The other options should be self-descriptive.@end deffn
@cindex SSH@cindex SSH server@deffn {Scheme Variable} openssh-service-typeThis is the type for the @uref{http://www.openssh.org, OpenSSH} secure shelldaemon, @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-configurationThis 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. Ifit's the symbol @code{'without-password}, then root logins are permitted butnot 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 haveother 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 isused only by protocol version 2.
@item @code{x11-forwarding?} (default: @code{#f})When true, forwarding of X11 graphical client connections is enabled---inother 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.@: viaPAM).
@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 sessionmodule processing for all authentication types.
Because PAM challenge response authentication usually serves an equivalentrole 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 lastuser 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 subsystemname and a command (with optional arguments) to execute upon subsystemrequest.
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. Itis set by terminal emulators, which support colors. You can use it in yourshell's ressource file to enable colors for the prompt and commands if thisvariable 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 keysThis is the list of authorized keys. Each element of the list is a username followed by one or more file-like objects that represent SSH publickeys. 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
@noindentregisters 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 manpage 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 beexpressed otherwise. This configuration, for example, would generallydisable 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,DropbearSSHdaemon} with the given @var{config}, a @code{<dropbear-configuration>}object.
For example, to specify a Dropbear service listening on port 1234, add thiscall to the operating system's @code{services} field:
@example(dropbear-service (dropbear-configuration (port-number 1234)))@end example@end deffn
@deftp {Data Type} dropbear-configurationThis 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-aliasesThis variable contains a string for use in @file{/etc/hosts} (@pxref{HostNames,,, libc, The GNU C Library Reference Manual}). Each line contains aentry 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 IPv6equivalent, @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-typeThis is the service that runs @command{avahi-daemon}, a system-widemDNS/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 canresolve @code{.local} host names using@uref{http://0pointer.de/lennart/projects/nss-mdns/,nss-mdns}. @xref{NameService Switch}, for information on host name resolution.
Additionally, add the @var{avahi} package to the system profile so thatcommands such as @command{avahi-browse} are directly usable.@end defvr
@deftp {Data Type} avahi-configurationData 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 thismachine; 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) overthe network.
@item @code{publish-workstation?} (default: @code{#t})When true, @command{avahi-daemon} publishes the machine's host name and IPaddress via mDNS on the local network. To view the host names published onyour local network, you can run:
@exampleavahi-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-typeThis 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-configurationData type representing the configuration of Open vSwitch, a multilayervirtual switch which is designed to enable massive network automationthrough 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 managerSupport for the X Window graphical display system---specifically Xorg---isprovided 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 managerGDM of course allows users to log in into window managers and desktopenvironments other than GNOME; for those using GNOME, GDM is required forfeatures such as automatic screen locking.
@cindex window managerTo use X11, you must install at least one @dfn{window manager}---for examplethe @code{windowmaker} or @code{openbox} packages---preferably by adding itto the @code{packages} field of your operating system definition(@pxref{operating-system Reference, system-wide packages}).
@defvr {Scheme Variable} gdm-service-typeThis is the type for the @uref{https://wiki.gnome.org/Projects/GDM/,GNOMEDesktop Manager} (GDM), a program that manages graphical display servers andhandles graphical user logins. Its value must be a @code{gdm-configuration}(see below.)
@cindex session types (X11)@cindex X11 session typesGDM looks for @dfn{session types} described by the @file{.desktop} files in@file{/run/current-system/profile/share/xsessions} and allows users tochoose a session from the log-in screen. Packages such as @code{gnome},@code{xfce}, and @code{i3} provide @file{.desktop} files; adding them to thesystem-wide set of packages automatically makes them available at the log-inscreen.
In addition, @file{~/.xsession} files are honored. When available,@file{~/.xsession} must be an executable that starts a window manager and/orother 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-typeThis is the type for the SLiM graphical login manager for X11.
Like GDM, SLiM looks for session types described by @file{.desktop} filesand 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-configurationData 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 defaultsession---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.
If false, a session described by one of the available @file{.desktop} filesin @code{/run/current-system/profile} and @code{~/.guix-profile} will beused.
@quotation NoteYou must install at least one window manager in the system profile or inyour user profile. Failing to do that, if @code{auto-login-session} isfalse, 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-nameThe default SLiM theme and its name.@end defvr

@deftp {Data Type} sddm-configurationThis 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 configReturn a service that spawns the SDDM graphical login manager for config oftype @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-configurationThis data type represents the configuration of the Xorg graphical displayserver. Note that there is not Xorg service; instead, the X server isstarted by a ``display manager'' such as GDM, SDDM, and SLiM. Thus, theconfiguration 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 graphicsdriver automatically, or a list of driver names that will be tried in thisorder---e.g., @code{("modesetting" "vesa")}.
@item @code{resolutions} (default: @code{'()})When @code{resolutions} is the empty list, Xorg chooses an appropriatescreen 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 USEnglish (``qwerty'') for a 105-key PC keyboard.
Otherwise this must be a @code{keyboard-layout} object specifying thekeyboard layout in use when Xorg is running. @xref{Keyboard Layout}, formore 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. Itis 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. Thedefault 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'sconfiguration---e.g., @code{gdm-configuration}---this procedure provides ashorthand 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 whosecommand is @var{program}, to the set of setuid programs and add a PAM entryfor 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 CUPSThe @code{(gnu services cups)} module provides a Guix service definition forthe 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-typeThe service type for the CUPS print server. Its value should be a validCUPS 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 CUPSinstallation: what interfaces it listens on, what to do if a print jobfails, how much logging to do, and so on. To actually add a printer, youhave to visit the @url{http://localhost:631} URL, or use a tool such asGNOME's printer configuration services. By default, configuring a CUPSservice will generate a self-signed certificate if needed, for secureconnections to the print server.
Suppose you want to enable the Web interface of CUPS and also add supportfor Epson printers @i{via} the @code{escpr} package and for HP printers@i{via} the @code{hplip-minimal} package. You can do that directly, likethis (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 hplippackage 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 ispreceded by its type; for example, @samp{string-list foo} indicates that the@code{foo} parameter should be specified as a list of strings. There isalso 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 cupsThe CUPS package.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} package-list extensionsDrivers and other extensions to the CUPS package.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} files-configuration files-configurationConfiguration of where to write logs, what directories to use for printspools, and related privileged configuration parameters.
Available @code{files-configuration} fields are:
@deftypevr {@code{files-configuration} parameter} log-location access-logDefines the access log filename. Specifying a blank filename disablesaccess log generation. The value @code{stderr} causes log entries to besent to the standard error file when the scheduler is running in theforeground, or to the system log daemon when run in the background. Thevalue @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}, asin @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-dirWhere CUPS should cache data.
Defaults to @samp{"/var/cache/cups"}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} string config-file-permSpecifies the permissions for all configuration files that the schedulerwrites.
Note that the permissions for the printers.conf file are currently masked toonly allow access from the scheduler user (typically root). This is donebecause printer device URIs sometimes contain sensitive authenticationinformation that should not be generally known on the system. There is noway to disable this security feature.
Defaults to @samp{"0640"}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} log-location error-logDefines the error log filename. Specifying a blank filename disables accesslog generation. The value @code{stderr} causes log entries to be sent tothe standard error file when the scheduler is running in the foreground, orto the system log daemon when run in the background. The value@code{syslog} causes log entries to be sent to the system log daemon. Theserver 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-errorsSpecifies which errors are fatal, causing the scheduler to exit. The kindstrings are:
@table @code@item noneNo errors are fatal.
@item allAll of the errors below are fatal.
@item browseBrowsing initialization errors are fatal, for example failed connections tothe DNS-SD daemon.
@item configConfiguration file syntax errors are fatal.
@item listenListen or Port errors are fatal, except for IPv6 failures on the loopback or@code{any} addresses.
@item logLog file creation or write errors are fatal.
@item permissionsBad startup file permissions are fatal, for example shared TLS certificateand 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 printerqueues. The URI @uref{file:///dev/null} is always allowed.
Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} string groupSpecifies the group name or ID that will be used when executing externalprograms.
Defaults to @samp{"lp"}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} string log-file-permSpecifies the permissions for all log files that the scheduler writes.
Defaults to @samp{"0644"}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} log-location page-logDefines the page log filename. Specifying a blank filename disables accesslog generation. The value @code{stderr} causes log entries to be sent tothe standard error file when the scheduler is running in the foreground, orto the system log daemon when run in the background. The value@code{syslog} causes log entries to be sent to the system log daemon. Theserver 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-rootSpecifies the username that is associated with unauthenticated accesses byclients 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-rootSpecifies the directory that contains print jobs and other HTTP requestdata.
Defaults to @samp{"/var/spool/cups"}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} sandboxing sandboxingSpecifies 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-keychainSpecifies the location of TLS certificates and private keys. CUPS will lookfor public and private keys in this directory: a @code{.crt} files forPEM-encoded certificates and corresponding @code{.key} files for PEM-encodedprivate keys.
Defaults to @samp{"/etc/cups/ssl"}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} file-name server-rootSpecifies 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 configurationor state files.
Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-groupSpecifies the group(s) to use for @code{@@SYSTEM} group authentication.@end deftypevr
@deftypevr {@code{files-configuration} parameter} file-name temp-dirSpecifies the directory where temporary files are stored.
Defaults to @samp{"/var/spool/cups/tmp"}.@end deftypevr
@deftypevr {@code{files-configuration} parameter} string userSpecifies 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-levelSpecifies the logging level for the AccessLog file. The @code{config} levellogs when printers and classes are added, deleted, or modified and whenconfiguration files are accessed or updated. The @code{actions} level logswhen print jobs are submitted, held, released, modified, or canceled, andany of the conditions for @code{config}. The @code{all} level logs allrequests.
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 nolonger required for quotas.
Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocolsSpecifies 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 classificationSpecifies the security classification of the server. Any valid banner namecan be used, including "classified", "confidential", "secret", "topsecret",and "unclassified", or the banner can be omitted to disable secure printingfunctions.
Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} boolean classify-override?Specifies whether users may override the classification (cover page) ofindividual print jobs using the @code{job-sheets} option.
Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-typeSpecifies the default type of authentication to use.
Defaults to @samp{Basic}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryptionSpecifies whether encryption will be used for authenticated requests.
Defaults to @samp{Required}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} string default-languageSpecifies the default language to use for text and web content.
Defaults to @samp{"en"}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} string default-paper-sizeSpecifies the default paper size for new print queues. @samp{"Auto"} uses alocale-specific default, while @samp{"None"} specifies there is no defaultpaper size. Specific size names are typically @samp{"Letter"} or@samp{"A4"}.
Defaults to @samp{"Auto"}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} string default-policySpecifies 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-intervalSpecifies the delay for updating of configuration and state files, inseconds. 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-policySpecifies 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}, whichretries the failed job immediately; and @code{stop-printer}, which stops theprinter.
Defaults to @samp{stop-printer}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limitSpecifies the maximum cost of filters that are run concurrently, which canbe used to minimize disk, memory, and CPU resource problems. A limit of 0disables filter limiting. An average print to a non-PostScript printerneeds a filter limit of about 200. A PostScript printer needs about halfthat (100). Setting the limit below these thresholds will effectively limitthe scheduler to printing a single job at any time.
Defaults to @samp{0}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-niceSpecifies the scheduling priority of filters that are run to print a job.The nice value ranges from 0, the highest priority, to 19, the lowestpriority.
Defaults to @samp{0}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookupsSpecifies whether to do reverse lookups on connecting clients. The@code{double} setting causes @code{cupsd} to verify that the hostnameresolved from the address matches one of the addresses returned for thathostname. Double lookups also prevent clients with unregistered addressesfrom 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-delaySpecifies the number of seconds to wait before killing the filters andbackend associated with a canceled or held job.
Defaults to @samp{30}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-intervalSpecifies the interval between retries of jobs in seconds. This istypically used for fax queues but can also be used with normal print queueswhose 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-limitSpecifies the number of retries that are done for jobs. This is typicallyused for fax queues but can also be used with normal print queues whoseerror 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-timeoutSpecifies 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-bodySpecifies the maximum size of print files, IPP requests, and HTML formdata. A limit of 0 disables the limit check.
Defaults to @samp{0}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} multiline-string-list listenListens on the specified interfaces for connections. Valid values are ofthe form @var{address}:@var{port}, where @var{address} is either an IPv6address enclosed in brackets, an IPv4 address, or @code{*} to indicate alladdresses. Values can also be file names of local UNIX domain sockets. TheListen directive is similar to the Port directive but allows you to restrictaccess to specific interfaces or networks.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-logSpecifies the number of pending connections that will be allowed. Thisnormally only affects very busy servers that have reached the MaxClientslimit, but can also be triggered by large numbers of simultaneousconnections. When the limit is reached, the operating system will refuseadditional 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-controlsSpecifies a set of additional access controls.
Available @code{location-access-controls} fields are:
@deftypevr {@code{location-access-controls} parameter} file-name pathSpecifies the URI path to which the access control applies.@end deftypevr
@deftypevr {@code{location-access-controls} parameter} access-control-list access-controlsAccess 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-controlsAccess 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 listedmethods. Otherwise apply to only the listed methods.
Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{method-access-controls} parameter} method-list methodsMethods to which this access control applies.
Defaults to @samp{()}.@end deftypevr
@deftypevr {@code{method-access-controls} parameter} access-control-list access-controlsAccess control directives, as a list of strings. Each string should be onedirective, such as "Order allow,deny".
Defaults to @samp{()}.@end deftypevr@end deftypevr@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-historySpecifies the number of debugging messages that are retained for logging ifan error occurs in a print job. Debug messages are logged regardless of theLogLevel setting.
Defaults to @samp{100}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} log-level log-levelSpecifies 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-formatSpecifies 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-clientsSpecifies the maximum number of simultaneous clients that are allowed by thescheduler.
Defaults to @samp{100}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-hostSpecifies the maximum number of simultaneous clients that are allowed from asingle address.
Defaults to @samp{100}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copiesSpecifies 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-timeSpecifies the maximum time a job may remain in the @code{indefinite} holdstate before it is canceled. A value of 0 disables cancellation of heldjobs.
Defaults to @samp{0}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobsSpecifies the maximum number of simultaneous jobs that are allowed. Set to0 to allow an unlimited number of jobs.
Defaults to @samp{500}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printerSpecifies the maximum number of simultaneous jobs that are allowed perprinter. 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-userSpecifies the maximum number of simultaneous jobs that are allowed peruser. 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-timeSpecifies the maximum time a job may take to print before it is canceled, inseconds. 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-sizeSpecifies the maximum size of the log files before they are rotated, inbytes. The value 0 disables log rotation.
Defaults to @samp{1048576}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeoutSpecifies the maximum amount of time to allow between files in a multiplefile print job, in seconds.
Defaults to @samp{300}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} string page-log-formatSpecifies the format of PageLog lines. Sequences beginning with percent(@samp{%}) characters are replaced with the corresponding information, whileall other characters are copied literally. The following percent sequencesare recognized:
@table @samp@item %%insert a single percent character
@item %@{name@}insert the value of the specified IPP attribute
@item %Cinsert the number of copies for the current page
@item %Pinsert the current page number
@item %Tinsert the current date and time in common log format
@item %jinsert the job ID
@item %pinsert the printer name
@item %uinsert 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-variablesPasses the specified environment variable(s) to child processes; a list ofstrings.
Defaults to @samp{()}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policiesSpecifies named access control policies.
Available @code{policy-configuration} fields are:
@deftypevr {@code{policy-configuration} parameter} string nameName of the policy.@end deftypevr
@deftypevr {@code{policy-configuration} parameter} string job-private-accessSpecifies an access list for a job's private values. @code{@@ACL} maps tothe printer's requesting-user-name-allowed or requesting-user-name-deniedvalues. @code{@@OWNER} maps to the job's owner. @code{@@SYSTEM} maps tothe 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 listinclude specific user names, and @code{@@@var{group}} to indicate members ofa 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-valuesSpecifies the list of job values to make private, or @code{all},@code{default}, or @code{none}.
Defaults to @samp{"job-name job-originating-host-namejob-originating-user-name phone"}.@end deftypevr
@deftypevr {@code{policy-configuration} parameter} string subscription-private-accessSpecifies an access list for a subscription's private values. @code{@@ACL}maps to the printer's requesting-user-name-allowed orrequesting-user-name-denied values. @code{@@OWNER} maps to the job'sowner. @code{@@SYSTEM} maps to the groups listed for the@code{system-group} field of the @code{files-config} configuration, which isreified into the @code{cups-files.conf(5)} file. Other possible elements ofthe access list include specific user names, and @code{@@@var{group}} toindicate 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-valuesSpecifies 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-urinotify-subscriber-user-name notify-user-data"}.@end deftypevr
@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controlsAccess control by IPP operation.
Defaults to @samp{()}.@end deftypevr@end deftypevr
@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-filesSpecifies whether job files (documents) are preserved after a job isprinted. If a numeric value is specified, job files are preserved for theindicated number of seconds after printing. Otherwise a boolean valueapplies indefinitely.
Defaults to @samp{86400}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-historySpecifies whether the job history is preserved after a job is printed. If anumeric value is specified, the job history is preserved for the indicatednumber of seconds after printing. If @code{#t}, the job history ispreserved until the MaxJobs limit is reached.
Defaults to @samp{#t}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeoutSpecifies the amount of time to wait for job completion before restartingthe scheduler.
Defaults to @samp{30}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} string rip-cacheSpecifies the maximum amount of memory to use when converting documents intobitmaps for a printer.
Defaults to @samp{"128m"}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} string server-adminSpecifies 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-aliasThe ServerAlias directive is used for HTTP Host header validation whenclients connect to the scheduler from external interfaces. Using thespecial name @code{*} can expose your system to known browser-based DNSrebinding attacks, even when accessing sites through a firewall. If theauto-discovery of alternate names does not work, we recommend listing eachalternate name with a ServerAlias directive instead of using @code{*}.
Defaults to @samp{*}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} string server-nameSpecifies the fully-qualified host name of the server.
Defaults to @samp{"localhost"}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokensSpecifies what information is included in the Server header of HTTPresponses. @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 theoutput 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-envSet 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-listenListens on the specified interfaces for encrypted connections. Valid valuesare of the form @var{address}:@var{port}, where @var{address} is either anIPv6 address enclosed in brackets, an IPv4 address, or @code{*} to indicateall addresses.
Defaults to @samp{()}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} ssl-options ssl-optionsSets encryption options. By default, CUPS only supports encryption usingTLS v1.0 or higher using known secure cipher suites. The @code{AllowRC4}option enables the 128-bit RC4 cipher suites, which are required for someolder clients that do not implement newer ones. The @code{AllowSSL3} optionenables SSL v3.0, which is required for some older clients that do notsupport 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 theIPP specifications.
Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeoutSpecifies 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 youbut 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 cupsThe CUPS package.@end deftypevr
@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.confThe contents of the @code{cupsd.conf}, as a string.@end deftypevr
@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.confThe 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 instrings 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 usuallyuseful in the context of a ``desktop'' setup---that is, on a machine runninga graphical display server, possibly with graphical user interfaces, etc.It also defines services that provide specific desktop environments likeGNOME, Xfce or MATE.
To simplify things, the module defines a variable containing the set ofservices that users typically expect on a machine with a graphicalenvironment and networking:
@defvr {Scheme Variable} %desktop-servicesThis is a list of services that builds upon @var{%base-services} and adds oradjusts 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}}), energyand color management services, the @code{elogind} login and seat manager,the Polkit privilege service, the GeoClue location service, theAccountsService daemon that allows authorized users change system passwords,an NTP client (@pxref{Networking Services}), the Avahi daemon, and has thename 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-systemReference, @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 thatsystem-level services like the backlight adjustment helpers and the powermanagement utilities are added to the system, extending @code{polkit} and@code{dbus} appropriately, allowing GNOME to operate with elevatedprivileges 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 Xfceservice not only adds the @code{xfce} metapackage to the system profile, butit also gives the Thunar file manager the ability to open a ``root-mode''file management window, if the user authenticates using the administrator'spassword via the standard polkit graphical interface. To ``add MATE'' meansthat @code{polkit} and @code{dbus} are extended appropriately, allowing MATEto operate with elevated privileges on a limited number of special-purposesystem interfaces. Additionally, adding a service of type@code{mate-desktop-service-type} adds the MATE metapackage to the systemprofile. ``Adding Enlightenment'' means that @code{dbus} is extendedappropriately, and several of Enlightenment's binaries are set as setuid,allowing Enlightenment's screen locker and other functionality to work asexpetected.
The desktop environments in Guix use the Xorg display server by default. Ifyou'd like to use the newer display server protocol called Wayland, you needto use the @code{sddm-service} instead of GDM as the graphical loginmanager. You should then select the ``GNOME (Wayland)'' session in SDDM.Alternatively you can also try starting GNOME on Wayland manually from a TTYwith the command ``XDG_SESSION_TYPE=wayland exec dbus-run-sessiongnome-session``. Currently only GNOME has support for Wayland.
@defvr {Scheme Variable} gnome-desktop-service-typeThis 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, andextends polkit with the actions from @code{gnome-settings-daemon}.@end defvr
@deftp {Data Type} gnome-desktop-configurationConfiguration 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-typeThis 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, andextends polkit with the ability for @code{thunar} to manipulate the filesystem as root from within a user session, after the user has authenticatedwith the administrator's password.@end defvr
@deftp {Data Type} xfce-desktop-configurationConfiguration 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-typeThis 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 extendspolkit with the actions from @code{mate-settings-daemon}.@end deffn
@deftp {Data Type} mate-desktop-configurationConfiguration 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-typeReturn a service that adds the @code{enlightenment} package to the systemprofile, 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 bydefault. 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 thegraphical login window.
The actual service definitions included in @code{%desktop-services} andprovided by @code{(gnu services dbus)} and @code{(gnu services desktop)} aredescribed below.
@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]Return a service that runs the ``system bus'', using @var{dbus}, withsupport for @var{services}.
@uref{http://dbus.freedesktop.org/,D-Bus} is an inter-process communicationfacility. Its system bus is used to allow system services to communicateand 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-Busconfiguration and policy files. For example, to allow avahi-daemon to usethe 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 managementdaemon. @uref{https://github.com/elogind/elogind,Elogind} exposes a D-Businterface that can be used to know which users are logged in, know what kindof 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 examplesuspending the system when a lid is closed, or shutting it down when thepower 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 valuesare:
@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 runsAccountsService, a system service that can list available accounts, changetheir passwords, and so on. AccountsService integrates with PolicyKit toenable unprivileged users to acquire the capability to modify their systemconfiguration.@uref{https://www.freedesktop.org/wiki/Software/AccountsService/,theaccountsservice 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 privilegemanagement service}, which allows system administrators to grant access toprivileged operations in a structured way. By querying the Polkit service,a privileged system component can know when it should grant additionalcapabilities to ordinary users. For example, an ordinary user can begranted the capability to suspend the system if the user is logged inlocally.@end deffn
@defvr {Scheme Variable} upower-service-typeService that runs @uref{http://upower.freedesktop.org/,@command{upowerd}},a system-wide monitor for power consumption and battery levels, with thegiven configuration settings.
It implements the @code{org.freedesktop.UPower} D-Bus interface, and isnotably used by GNOME.@end defvr
@deftp {Data Type} upower-configurationData 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 touse 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 thepercentage 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 thepercentage 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 thepercentage 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 remainingin 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 remainingin 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 remainingin 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} isreached (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 withnotifications and ways to mount/unmount disks. Programs that talk to UDisksinclude 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-Businterface to manage the color profiles of input and output devices such asscreens and scanners. It is notably used by the GNOME Color Managergraphical tool. See @uref{http://www.freedesktop.org/software/colord/,thecolord 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 locationdata. @var{name} is the Desktop ID of the application, without the@code{.desktop} part. If @var{allowed?} is true, the application will haveaccess to location information by default. The boolean @var{system?} valueindicates whether an application is a system component or not. Finally@var{users} is a list of UIDs of all users for which this application isallowed location info access. An empty users list means that all users areallowed.@end deffn
@defvr {Scheme Variable} %standard-geoclue-applicationsThe standard list of well-known GeoClue application configurations, grantingauthority to the GNOME date-and-time utility to ask for the current locationin order to set the time zone, and allowing the IceCat and Epiphany webbrowsers to request location information. IceCat and Epiphany both querythe 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 GeoCluelocation service. This service provides a D-Bus interface to allowapplications to request access to a user's physical location, and optionallyto add information to online location databases. See@uref{https://wiki.freedesktop.org/www/Software/GeoClue/,the GeoClue website} 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 ofD-Bus interfaces. When AUTO-ENABLE? is true, the bluetooth controller ispowered automatically at boot, which can be useful when using a bluetoothkeyboard 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 theAdvanced Linux Sound Architecture (ALSA) system, which makes PulseAudio thepreferred ALSA output driver.
@deffn {Scheme Variable} alsa-service-typeThis is the type for the @uref{https://alsa-project.org/,Advanced LinuxSound 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-configurationData 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 atthe 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 cando 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 thedetails.

@node Database Services@subsection Database Services
@cindex database@cindex SQLThe @code{(gnu services databases)} module provides the following services.
@deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @ [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @ [#:port5432] [#:locale ``en_US.utf8''] [#:extension-packages '()] Return a servicethat 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 thedefault locale, stored in @var{data-directory}. It then listens on@var{port}.
@cindex postgresql extension-packagesAdditional extensions are loaded from packages listed in@var{extension-packages}. Extensions are available at runtime. Forinstance, 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 emptygeographic database in this way:
@examplepsql -U postgres
Toggle quote (4 lines)> 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 ordblink as they are already loadable by postgresql. This field is onlyrequired 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 databaseserver.
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-configurationData 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-typeThis is the service type for the @uref{https://memcached.org/,Memcached}service, which provides a distributed in memory cache. The value for theservice type is a @code{memcached-configuration} object.@end defvr
@example(service memcached-service-type)@end example
@deftp {Data Type} memcached-configurationData 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 disablelistening 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-typeThis is the service type for @uref{https://www.mongodb.com/,MongoDB}. Thevalue for the service type is a @code{mongodb-configuration} object.@end defvr
@example(service mongodb-service-type)@end example
@deftp {Data Type} mongodb-configurationData 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 ownedby the mongodb user. It should match the data-directory which MongoDB isconfigured to use through the configuration file.@end table@end deftp
@defvr {Scheme Variable} redis-service-typeThis is the service type for the @uref{https://redis.io/,Redis} key/valuestore, whose value is a @code{redis-configuration} object.@end defvr
@deftp {Data Type} redis-configurationData 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 listeningon 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 emailThe @code{(gnu services mail)} module provides Guix service definitions foremail services: IMAP, POP3, and LMTP servers, as well as mail transportagents (MTAs). Lots of acronyms! These services are detailed in thesubsections 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 defaultconfiguration object created by @code{(dovecot-configuration)} will sufficeif your mail is delivered to @code{~/Maildir}. A self-signed certificatewill be generated for TLS-protected connections, though Dovecot will alsolisten on cleartext ports by default. There are a number of options,though, which mail administrators might need to change, and as is the casewith other services, Guix allows the system administrator to specify theseparameters via a uniform Scheme interface.
For example, to specify that mail is located at @code{maildir~/.mail}, onewould 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 ispreceded by its type; for example, @samp{string-list foo} indicates that the@code{foo} parameter should be specified as a list of strings. There isalso 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 dovecotThe dovecot package.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listenA list of IPs or hosts where to listen for connections. @samp{*} listens onall IPv4 interfaces, @samp{::} listens on all IPv6 interfaces. If you wantto specify non-default ports or anything more complex, customize the addressand port fields of the @samp{inet-listener} of the specific services you areinterested in.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocolsList 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 nameThe name of the protocol.@end deftypevr
@deftypevr {@code{protocol-configuration} parameter} string auth-socket-pathUNIX socket path to the master authentication server to find users. This isused 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-pluginsSpace separated list of plugins to load.@end deftypevr
@deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connectionsMaximum 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 servicesList 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 kindThe 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}, oranything else.@end deftypevr
@deftypevr {@code{service-configuration} parameter} listener-configuration-list listenersListeners for the service. A listener is either a@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, oran @code{inet-listener-configuration}. Defaults to @samp{()}.
Available @code{unix-listener-configuration} fields are:
@deftypevr {@code{unix-listener-configuration} parameter} string pathPath to the file, relative to @code{base-dir} field. This is also used asthe section name.@end deftypevr
@deftypevr {@code{unix-listener-configuration} parameter} string modeThe access mode for the socket. Defaults to @samp{"0600"}.@end deftypevr
@deftypevr {@code{unix-listener-configuration} parameter} string userThe user to own the socket. Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{unix-listener-configuration} parameter} string groupThe group to own the socket. Defaults to @samp{""}.@end deftypevr

Available @code{fifo-listener-configuration} fields are:
@deftypevr {@code{fifo-listener-configuration} parameter} string pathPath to the file, relative to @code{base-dir} field. This is also used asthe section name.@end deftypevr
@deftypevr {@code{fifo-listener-configuration} parameter} string modeThe access mode for the socket. Defaults to @samp{"0600"}.@end deftypevr
@deftypevr {@code{fifo-listener-configuration} parameter} string userThe user to own the socket. Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{fifo-listener-configuration} parameter} string groupThe group to own the socket. Defaults to @samp{""}.@end deftypevr

Available @code{inet-listener-configuration} fields are:
@deftypevr {@code{inet-listener-configuration} parameter} string protocolThe protocol to listen for.@end deftypevr
@deftypevr {@code{inet-listener-configuration} parameter} string addressThe address on which to listen, or empty for all addresses. Defaults to@samp{""}.@end deftypevr
@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer portThe 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-limitMaximum number of simultaneous client connections per process. Once thisnumber of connections is received, the next incoming connection will promptDovecot 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-countNumber of connections to handle before starting a new process. Typicallythe only useful values are 0 (unlimited) or 1. 1 is more secure, but 0 isfaster. <doc/wiki/LoginProcess.txt>. Defaults to @samp{1}.
@end deftypevr
@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limitMaximum 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-availNumber of processes to always keep waiting for more connections. Defaultsto @samp{0}.@end deftypevr
@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limitIf you set @samp{service-count 0}, you probably need to grow this. Defaultsto @samp{256000000}.@end deftypevr
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dictDict configuration, as created by the @code{dict-configuration} constructor.
Available @code{dict-configuration} fields are:
@deftypevr {@code{dict-configuration} parameter} free-form-fields entriesA 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 passdbsA 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 driverThe driver that the passdb should use. Valid values include @samp{pam},@samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}. Defaultsto @samp{"pam"}.@end deftypevr
@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list argsSpace separated list of arguments to the passdb driver. Defaults to@samp{""}.@end deftypevr
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbsList of userdb configurations, each one created by the@code{userdb-configuration} constructor.
Available @code{userdb-configuration} fields are:
@deftypevr {@code{userdb-configuration} parameter} string driverThe 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 argsSpace separated list of arguments to the userdb driver. Defaults to@samp{""}.@end deftypevr
@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fieldsOverride fields from passwd. Defaults to @samp{()}.@end deftypevr
@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configurationPlug-in configuration, created by the @code{plugin-configuration}constructor.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespacesList 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 nameName for this namespace.@end deftypevr
@deftypevr {@code{namespace-configuration} parameter} string typeNamespace type: @samp{private}, @samp{shared} or @samp{public}. Defaults to@samp{"private"}.@end deftypevr
@deftypevr {@code{namespace-configuration} parameter} string separatorHierarchy separator to use. You should use the same separator for allnamespaces or some clients get confused. @samp{/} is usually a good one.The default however depends on the underlying mail storage format. Defaultsto @samp{""}.@end deftypevr
@deftypevr {@code{namespace-configuration} parameter} string prefixPrefix required to access this namespace. This needs to be different forall namespaces. For example @samp{Public/}. Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{namespace-configuration} parameter} string locationPhysical location of the mailbox. This is in the same format asmail_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 hasit. Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{namespace-configuration} parameter} boolean hidden?If namespace is hidden, it's not advertised to clients via NAMESPACEextension. You'll most likely also want to set @samp{list? #f}. This ismostly useful when converting from another server with different namespaceswhich you want to deprecate but still keep working. For example you cancreate 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 makesthe namespace visible for clients that do not support the NAMESPACEextension. The special @code{children} value lists child mailboxes, buthides 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 parentnamespace 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 mailboxesList of predefined mailboxes in this namespace. Defaults to @samp{()}.
Available @code{mailbox-configuration} fields are:
@deftypevr {@code{mailbox-configuration} parameter} string nameName for this mailbox.@end deftypevr
@deftypevr {@code{mailbox-configuration} parameter} string auto@samp{create} will automatically create this mailbox. @samp{subscribe} willboth create and subscribe to the mailbox. Defaults to @samp{"no"}.@end deftypevr
@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-useList of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154. Validvalues 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-dirBase directory where to store runtime data. Defaults to@samp{"/var/run/dovecot/"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string login-greetingGreeting message for clients. Defaults to @samp{"Dovecot ready."}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networksList of trusted network ranges. Connections from these IPs are allowed tooverride their IP addresses and ports (for logging and for authenticationchecks). @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-socketsList 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 IPaddress. 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 forcingexisting client connections to close (although that could also be a problemif 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-countIf 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-pathUNIX 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-environmentList of environment variables that are preserved on Dovecot startup andpassed down to all of its child processes. You can also give key=valuepairs 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/TLSis used (LOGINDISABLED capability). Note that if the remote IP matches thelocal IP (i.e.@: you're connecting from the same computer), the connectionis considered secure and plaintext authentication is allowed. See alsossl=required setting. Defaults to @samp{#t}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-sizeAuthentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled.Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set forcaching to be used. Defaults to @samp{0}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttlTime to live for cached data. After TTL expires the cached record is nolonger used, *except* if the main database lookup returns internal failure.We also try to handle password changes automatically: If user's previousauthentication was successful, but this one wasn't, the cache isn't used.For now this works only with plaintext authentication. Defaults to @samp{"1hour"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttlTTL for negative hits (user not found, password mismatch). 0 disablescaching them completely. Defaults to @samp{"1 hour"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realmsList of realms for SASL authentication mechanisms that need them. You canleave it empty if you don't want to support multiple realms. Many clientssimply 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-realmDefault realm/domain to use if none was specified. This is used for bothSASL realms and appending @@domain to username in plaintext logins.Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string auth-username-charsList of allowed characters in username. If the user-given username containsa character not listed in here, the login automatically fails. This is justan extra check to make sure user can't exploit any potential quote escapingvulnerabilities with SQL/LDAP databases. If you want to allow allcharacters, set this value to empty. Defaults to@samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string auth-username-translationUsername character translations before it's looked up from databases. Thevalue 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-formatUsername formatting before it's looked up from databases. You can use thestandard variables here, e.g.@: %Lu would lowercase the username, %n woulddrop 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-separatorIf you want to allow master users to log in by specifying the masterusername within the normal username string (i.e.@: not using SASLmechanism'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-usernameUsername 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-countMaximum number of dovecot-auth worker processes. They're used to executeblocking passdb and userdb queries (e.g.@: MySQL and PAM). They'reautomatically created and destroyed as needed. Defaults to @samp{30}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostnameHost name to use in GSSAPI principal names. The default is to use the namereturned by gethostname(). Use @samp{$ALL} (with quotes) to allow allkeytab entries. Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytabKerberos keytab to use for the GSSAPI mechanism. Will use the systemdefault (usually @file{/etc/krb5.keytab}) if not specified. You may need tochange 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-pathPath 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-delayTime 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'sCommonName. Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanismsList 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-serversList of IPs or hostnames to all director servers, including ourself. Portscan be specified as ip:port. The default port is the same as what directorservice's @samp{inet-listener} is using. Defaults to @samp{()}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-serversList of IPs or hostnames to all backend mail servers. Ranges are allowedtoo, like 10.0.0.10-10.0.0.30. Defaults to @samp{()}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string director-user-expireHow long to redirect users to a specific server after it no longer has anyconnections. Defaults to @samp{"15 min"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string director-username-hashHow the username is translated before being hashed. Useful values include%Ln if user can log in with or without @@domain, %Ld if mailboxes are sharedwithin domain. Defaults to @samp{"%Lu"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string log-pathLog 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-pathLog file to use for informational messages. Defaults to @samp{log-path}.Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string debug-log-pathLog file to use for debug messages. Defaults to @samp{info-log-path}.Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string syslog-facilitySyslog facility to use if you're logging to syslog. Usually if you don'twant to use @samp{mail}, you'll use local0..local7. Also other standardfacilities 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 valuesare no, plain and sha1. sha1 can be useful for detecting brute forcepassword attempts vs. user simply trying the same password over and overagain. 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 SQLqueries. 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 theproblem 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 Dovecotisn'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-timestampPrefix 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-elementsList of elements we want to log. The elements which have a non-emptyvariable value are joined together to form a comma-separated string.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string login-log-formatLogin 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-prefixLog prefix for mail processes. See doc/wiki/Variables.txt for list ofpossible variables you can use. Defaults to@samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-formatFormat to use for logging mail deliveries. You can use variables:@table @code@item %$Delivery status message (e.g.@: @samp{saved to INBOX})@item %mMessage-ID@item %sSubject@item %fFrom address@item %pPhysical size@item %wVirtual size.@end tableDefaults to @samp{"msgid=%m: %$"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-locationLocation for users' mailboxes. The default is empty, which means thatDovecot tries to find the mailboxes automatically. This won't work if theuser doesn't yet have any mail, so you should explicitly tell Dovecot thefull 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 mailboxesare kept. This is called the "root mail directory", and it must be thefirst path given in the @samp{mail-location} setting.
There are a few special variables you can use, eg.:
@table @samp@item %uusername@item %nuser part in user@@domain, same as %u if there's no domain@item %ddomain part in user@@domain, empty if there's no domain@item %hhome 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 tableDefaults to @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-uidSystem user and group used to access mails. If you use multiple, userdb canoverride these by returning uid or gid fields. You can use either numbersor 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-groupGroup to enable temporarily for privileged operations. Currently this isused 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-groupsGrant access to these supplementary groups for mail processes. Typicallythese are used to set up access to shared mailboxes. Note that it may bedangerous to set these if users can create symlinks (e.g.@: if "mail" groupis 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 readingit). 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 otherthan what the operating system does for the active UID/GID. It works withboth 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 sharedfile 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 bydefault. Defaults to @samp{#t}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-fsyncWhen to use fsync() or fdatasync() calls:@table @code@item optimizedWhenever necessary to avoid losing important data@item alwaysUseful with e.g.@: NFS when write()s are delayed@item neverNever use it (best performance, but crashes can lose data).@end tableDefaults 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 NFScaches whenever needed. If you're using only a single mail server thisisn'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-methodLocking method for index files. Alternatives are fcntl, flock and dotlock.Dotlocking uses some tricks which may create more disk I/O than otherlocking 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-dirDirectory 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-uidValid UID range for users. This is mostly to make sure that users can't login as daemons or other system users. Note that denying root logins ishardcoded 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-gidValid GID range for users. Users having non-valid GID as primary group IDaren't allowed to log in. If user belongs to supplementary groups withnon-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-lengthMaximum allowed length for mail keyword name. It's only forced when tryingto create new keywords. Defaults to @samp{50}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirsList of directories under which chrooting is allowed for mail processes(i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar too). Thissetting doesn't affect @samp{login-chroot} @samp{mail-chroot} or auth chrootsettings. If this setting is empty, "/./" in home dirs are ignored.WARNING: Never add directories here which local users can modify, that maylead to root exploit. Usually this should be done only if you don't allowshell access for users. <doc/wiki/Chrooting.txt>. Defaults to @samp{()}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-chrootDefault chroot directory for mail processes. This can be overridden forspecific users in user database by giving /./ in user's home directory(e.g.@: /home/./user chroots into /home). Note that usually there is noreal need to do chrooting, Dovecot doesn't allow users to access filesoutside their mail directory anyway. If your home directories are prefixedwith 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-pathUNIX socket path to master authentication server to find users. This isused 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-dirDirectory where to look up mail plugins. Defaults to@samp{"/usr/lib/dovecot"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-pluginsList 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-countThe minimum number of mails in a mailbox before updates are done to cachefile. This allows optimizing Dovecot's behavior to do less disk writes atthe cost of more disk reads. Defaults to @samp{0}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-intervalWhen IDLE command is running, mailbox is checked once in a while to see ifthere are any new mails or other changes. This setting defines the minimumtime to wait between those checks. Dovecot can also use dnotify, inotifyand 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 mailstake 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. Alsonote that if other software reads the mboxes/maildirs, they may handle theextra 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 adot. Enabling this option makes Dovecot return only entries which aredirectories. This is done by stat()ing each entry, so it causes more diskI/O. (For systems setting struct @samp{dirent->d_type} this check is freeand 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 makesthe 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 onlywhen its mtime changes unexpectedly or when we can't find the mailotherwise. Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locksWhich locking methods to use for locking mbox. There are four available:
@table @code@item dotlockCreate <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 writeaccess to that directory.@item dotlock-trySame as dotlock, but if it fails because of permissions or because thereisn't enough disk space, just skip it.@item fcntlUse this if possible. Works with NFS too if lockd is used.@item flockMay not exist in all systems. Doesn't work with NFS.@item lockfMay 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 declaredin is important to avoid deadlocks if other MTAs/MUAs are using multiplelocking methods as well. Some operating systems don't allow using some ofthem 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-timeoutMaximum 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-timeoutIf dotlock exists but the mailbox isn't modified in any way, override thelock 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 whatchanged. If the mbox is large this can take a long time. Since the changeis usually just a newly appended mail, it'd be faster to simply read the newmails. If this setting is enabled, Dovecot does this but still safelyfallbacks to re-reading the whole mbox file whenever something in mbox isn'thow it's expected to be. The only real downside to this setting is that ifsome other MUA changes message flags, Dovecot doesn't notice itimmediately. Note that a full sync is done with SELECT, EXAMINE, EXPUNGEand 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 CHECKcommands and when closing the mailbox). This is especially useful for POP3where clients often delete all mails. The downside is that our changesaren't immediately visible to other MUAs. Defaults to @samp{#t}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-sizeIf 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. Defaultsto @samp{0}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-sizeMaximum dbox file size until it's rotated. Defaults to @samp{10000000}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-intervalMaximum dbox file age until it's rotated. Typically in days. Day beginsfrom 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 withsome file systems (ext4, xfs). Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dirsdbox and mdbox support saving mail attachments to external files, whichalso allows single instance storage for them. Other backends don't supportthis 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-sizeAttachments smaller than this aren't saved externally. It's also possibleto write a plugin to disable saving specific attachments externally.Defaults to @samp{128000}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fsFile system backend to use for saving attachments:@table @code@item posixNo SiS done by Dovecot (but this might help FS's own deduplication)@item sis posixSiS with immediate byte-by-byte comparison during saving@item sis-queue posixSiS with delayed comparison and deduplication.@end tableDefaults to @samp{"sis posix"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hashHash format to use in attachment filenames. You can add any text andvariables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can betruncated, 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-limitDefault VSZ (virtual memory size) limit for service processes. This ismainly intended to catch and kill processes that leak memory before they eatup everything. Defaults to @samp{256000000}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string default-login-userLogin user is internally used by login processes. This is the mostuntrusted user in Dovecot system. It shouldn't have access to anything atall. Defaults to @samp{"dovenull"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string default-internal-userInternal user is used by unprivileged processes. It should be separate fromlogin user, so that login processes can't disturb other processes. Defaultsto @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-certPEM encoded X.509 SSL/TLS certificate (public key). Defaults to@samp{"</etc/dovecot/default.pem"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string ssl-keyPEM encoded SSL/TLS private key. The key is opened before dropping rootprivileges, 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-passwordIf key file is password protected, give the password here. Alternativelygive it when starting dovecot with -p parameter. Since this file is oftenworld-readable, you may want to place this setting instead to a different.Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string ssl-caPEM encoded trusted certificate authority. Set this only if you intend touse @samp{ssl-verify-client-cert? #t}. The file should contain the CAcertificate(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-fieldWhich field from certificate to use for username. commonName andx500UniqueIdentifier 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-protocolMinimum SSL protocol version to accept. Defaults to @samp{"TLSv1"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-listSSL 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-deviceSSL crypto device to use, for valid values run "openssl engine". Defaultsto @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string postmaster-addressAddress to use when sending rejection mails. %d expands to recipientdomain. Defaults to @samp{"postmaster@@%d"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string hostnameHostname to use in various parts of sent mails (e.g.@: in Message-Id) andin LMTP replies. Default is the system's real hostname@@domain. Defaultsto @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?If user is over quota, return with temporary failure instead of bouncing themail. Defaults to @samp{#f}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-pathBinary to use for sending mails. Defaults to @samp{"/usr/sbin/sendmail"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string submission-hostIf non-empty, send mails via this SMTP host[:port] instead of sendmail.Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string rejection-subjectSubject: header to use for rejection mails. You can use the same variablesas for @samp{rejection-reason} below. Defaults to @samp{"Rejected: %s"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string rejection-reasonHuman readable error message for rejection mails. You can use variables:
@table @code@item %nCRLF@item %rreason@item %soriginal subject@item %trecipient@end tableDefaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiterDelimiter character between local-part and detail in email address.Defaults to @samp{"+"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-headerHeader where the original recipient address (SMTP's RCPT TO: address) istaken from if not available elsewhere. With dovecot-lda -a parameteroverrides this. A commonly used header for this is X-Original-To. Defaultsto @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-lengthMaximum IMAP command line length. Some clients generate very long commandlines with huge mailboxes, so you may need to raise this if you get "Toolong argument" or "IMAP command line too large" errors often. Defaults to@samp{64000}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-formatIMAP logout format string:@table @code@item %itotal number of bytes read from client@item %ototal number of bytes sent to client.@end tableSee @file{doc/wiki/Variables.txt} for a list of all the variables you canuse. 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-capabilityOverride the IMAP CAPABILITY response. If the value begins with '+', addthe given capabilities on top of the defaults (e.g.@: +XFOO XBAR). Defaultsto @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-intervalHow long to wait between "OK Still here" notifications when client isIDLEing. Defaults to @samp{"2 mins"}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string imap-id-sendID field names and values to send to clients. Using * as the value makesDovecot use the default value. The following fields have default valuescurrently: name, version, os, os-version, support-url, support-email.Defaults to @samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string imap-id-logID fields sent by client to log. * means everything. Defaults to@samp{""}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workaroundsWorkarounds for various client bugs:
@table @code@item delay-newmailSend EXISTS/RECENT new mail notifications only when replying to NOOP andCHECK commands. Some clients ignore them otherwise, for example OSX Mail(<v2.1). Outlook Express breaks more badly though, without this it may showuser "Message no longer in server" errors. Note that OE6 still breaks evenwith this workaround if synchronization is set to "Headers Only".
@item tb-extra-mailbox-sepThunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and addsextra @samp{/} suffixes to mailbox names. This option causes Dovecot toignore the extra @samp{/} instead of treating it as invalid mailbox name.
@item tb-lsub-flagsShow \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox). Thismakes Thunderbird realize they aren't selectable and show them greyed out,instead of only later giving "not selectable" popup error.@end tableDefaults to @samp{()}.@end deftypevr
@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-hostHost 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 thatGuix has a complete interface to Dovecot's configuration language. Thisallows not only a nice way to declare configurations, but also offersreflective capabilities as well: users can write code to inspect andtransform configurations from within Scheme.
However, it could be that you just want to get a @code{dovecot.conf} up andrunning. In that case, you can pass an @code{opaque-dovecot-configuration}as the @code{#:config} parameter to @code{dovecot-service}. As its nameindicates, an opaque configuration does not have easy reflectivecapabilities.
Available @code{opaque-dovecot-configuration} fields are:
@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecotThe dovecot package.@end deftypevr
@deftypevr {@code{opaque-dovecot-configuration} parameter} string stringThe contents of the @code{dovecot.conf}, as a string.@end deftypevr
For example, if your @code{dovecot.conf} is just the empty string, you couldinstantiate a dovecot service like this:
@example(dovecot-service #:config (opaque-dovecot-configuration (string "")))@end example
@subsubheading OpenSMTPD Service
@deffn {Scheme Variable} opensmtpd-service-typeThis is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD} service,whose value should be an @code{opensmtpd-configuration} object as in thisexample:
@example(service opensmtpd-service-type (opensmtpd-configuration (config-file (local-file "./my-smtpd.conf"))))@end example@end deffn
@deftp {Data Type} opensmtpd-configurationData 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 itlistens on the loopback network interface, and allows for mail from usersand daemons on the local machine, as well as permitting email to remoteservers. 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-typeThis 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 thisexample:
@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-configurationData 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 providedin @code{package}. The resulting configuration file is loaded after settingthe @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-typeThis 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 anassociation list denoting how to deliver mail that comes to thissystem. Each entry is of the form @code{(alias addresses ...)}, with@code{alias} specifying the local alias and @code{addresses} specifyingwhere to deliver this user's mail.
The aliases aren't required to exist as users on the local system. In theabove 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 mailto @code{bob@@example.com} and @code{bob@@example2.com}).
@subsubheading GNU Mailutils IMAP4 Daemon@cindex GNU Mailutils IMAP4 Daemon
@deffn {Scheme Variable} imap4d-service-typeThis 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-configurationData 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 listenon TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNUMailutils Manual}, for details.
@end table@end deftp
@node Messaging Services@subsection Messaging Services
@cindex messaging@cindex jabber@cindex XMPPThe @code{(gnu services messaging)} module provides Guix service definitionsfor messaging services: currently only Prosody is supported.
@subsubheading Prosody Service
@deffn {Scheme Variable} prosody-service-typeThis is the type for the @uref{https://prosody.im, Prosody XMPPcommunication 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 wishProsody to serve.
You can perform various sanity checks on the generated configuration withthe @code{prosodyctl check} command.
Prosodyctl will also help you to import certificates from the@code{letsencrypt} directory so that the @code{prosody} user can accessthem. See @url{https://prosody.im/doc/letsencrypt}.
@exampleprosodyctl --root cert import /etc/letsencrypt/live@end example
The available configuration parameters follow. Each parameter definition ispreceded by its type; for example, @samp{string-list foo} indicates that the@code{foo} parameter should be specified as a list of strings. Typesstarting 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 anold @code{prosody.cfg.lua} file that you want to port over from some othersystem; 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 prosodyThe Prosody package.@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} file-name data-pathLocation 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-pathsAdditional plugin directories. They are searched in all the specified pathsin order. See @url{https://prosody.im/doc/plugins_directory}. Defaults to@samp{()}.@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} file-name certificatesEvery virtual host and component needs a certificate so that clients andservers can securely verify its identity. Prosody will automatically loadcertificates/keys from the directory specified here. Defaults to@samp{"/etc/prosody/certs"}.@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} string-list adminsThis is a list of accounts that are admins for the server. Note that youmust 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-enabledThis 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 existstoo. 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 shouldyou want to disable them then add them to this list. Defaults to @samp{()}.@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} file-object groups-filePath to a text file where the shared groups are defined. If this path isempty 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 sslThese are the SSL/TLS-related settings. Most of them are disabled so to useProsody's defaults. If you do not completely understand these options, donot add them to your config, it is easy to lower the security of your serverusing them. See @url{https://prosody.im/doc/advanced_ssl_config}.
Available @code{ssl-configuration} fields are:
@deftypevr {@code{ssl-configuration} parameter} maybe-string protocolThis determines what handshake to use.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-file-name keyPath to your private key file.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificatePath to your certificate file.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} file-object capathPath to directory containing root certificates that you wish Prosody totrust when verifying the certificates of remote servers. Defaults to@samp{"/etc/ssl/certs"}.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafilePath 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 verifyA list of verification options (these mostly map to OpenSSL's@code{set_verify()} flags).@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string-list optionsA 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, seethe LuaSec source.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depthHow long a chain of certificate authorities to check when looking for atrusted root certificate.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphersAn OpenSSL cipher string. This selects what ciphers Prosody will offer toclients, and in what order.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparamA path to a file containing parameters for Diffie-Hellman key exchange. Youcan 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 curveCurve for Elliptic curve Diffie-Hellman. Prosody's default is@samp{"secp384r1"}.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyextA list of "extra" verification options.@end deftypevr
@deftypevr {@code{ssl-configuration} parameter} maybe-string passwordPassword 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-mechanismsSet 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 providesideal security, but requires servers you communicate with to supportencryption 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-domainsMany servers don't support encryption or have invalid or self-signedcertificates. You can list domains here that will not be required toauthenticate 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-domainsEven if you leave @code{s2s-secure-auth?} disabled, you can still requirevalid 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 authenticationSelect the authentication backend to use. The default provider storespasswords in plaintext and uses Prosody's configured data storage to storethe authentication data. If you do not trust your server please see@url{https://prosody.im/doc/modules/mod_auth_internal_hashed}forinformation 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 logSet logging options. Advanced logging configuration is not yet supported bythe Prosody service. See @url{https://prosody.im/doc/logging}. Defaults to@samp{"*syslog"}.@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} file-name pidfileFile 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-sizeMaximum allowed size of the HTTP body (in bytes).@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-urlSome modules expose their own URL in various ways. This URL is built fromthe protocol, host and port used. If Prosody sits behind a proxy, thepublic 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 virtualhostsA host in Prosody is a domain on which user accounts can be created. Forexample 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 thishost.
Note: the name "virtual" host is used in configuration to avoid confusionwith the actual physical host that Prosody is installed on. A singleProsody instance can serve many domains, each one defined as a VirtualHostentry in Prosody's configuration. Conversely a server that hosts a singledomain 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 domainDomain you wish Prosody to serve.@end deftypevr
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-componentsComponents 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 chatroomservers, user directories, or gateways to other protocols.
Internal components are implemented with Prosody-specific plugins. To addan internal component, you simply fill the hostname field, and the pluginyou 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 hostnameHostname of the component.@end deftypevr
@deftypevr {@code{int-component-configuration} parameter} string pluginPlugin you wish to use for the component.@end deftypevr
@deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-mucMulti-user chat (MUC) is Prosody's module for allowing you to create hostedchatrooms/conferences for XMPP users.
General information on setting up and using multi-user chatrooms can befound in the "Chatrooms" documentation(@url{https://prosody.im/doc/chatrooms}),which you should read if you arenew 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 nameThe 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-creationIf @samp{#t}, this will only allow admins to create new chatrooms.Otherwise anyone can create a room. The value @samp{"local"} restricts roomcreation to users on the service's parent domain. E.g.@:@samp{user@@example.com} can create rooms on @samp{rooms.example.com}. Thevalue @samp{"admin"} restricts to service administrators only. Defaults to@samp{#f}.@end deftypevr
@deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messagesMaximum number of history messages that will be sent to the member that hasjust joined the room. Defaults to @samp{20}.@end deftypevr
@end deftypevr
@end deftypevr
@deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-componentsExternal 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-secretPassword which the component will use to log in.@end deftypevr
@deftypevr {@code{ext-component-configuration} parameter} string hostnameHostname of the component.@end deftypevr
@end deftype