6 @documentencoding UTF-8
7 @settitle GNU Guix Reference Manual
12 @c Identifier of the OpenPGP key used to sign tarballs and such.
13 @set OPENPGP-SIGNING-KEY-ID 27D586A4F8900854329FF09F1260E46482E63562
14 @set OPENPGP-SIGNING-KEY-URL https://sv.gnu.org/people/viewgpg.php?user_id=127547
16 @c Base URL for downloads.
17 @set BASE-URL https://ftp.gnu.org/gnu/guix
19 @c The official substitute server used by default.
20 @set SUBSTITUTE-SERVER-1 ci.guix.gnu.org
21 @set SUBSTITUTE-SERVER-2 bordeaux.guix.gnu.org
22 @set SUBSTITUTE-URLS https://@value{SUBSTITUTE-SERVER-1} https://@value{SUBSTITUTE-SERVER-2}
25 Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ludovic Courtès@*
26 Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@*
27 Copyright @copyright{} 2013 Nikita Karetnikov@*
28 Copyright @copyright{} 2014, 2015, 2016 Alex Kost@*
29 Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
30 Copyright @copyright{} 2014 Pierre-Antoine Rault@*
31 Copyright @copyright{} 2015 Taylan Ulrich Bayırlı/Kammer@*
32 Copyright @copyright{} 2015, 2016, 2017, 2019, 2020, 2021 Leo Famulari@*
33 Copyright @copyright{} 2015, 2016, 2017, 2018, 2019, 2020, 2021 Ricardo Wurmus@*
34 Copyright @copyright{} 2016 Ben Woodcroft@*
35 Copyright @copyright{} 2016, 2017, 2018, 2021 Chris Marusich@*
36 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Efraim Flashner@*
37 Copyright @copyright{} 2016 John Darrington@*
38 Copyright @copyright{} 2016, 2017 Nikita Gillmann@*
39 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020 Jan Nieuwenhuizen@*
40 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Julien Lepiller@*
41 Copyright @copyright{} 2016 Alex ter Weele@*
42 Copyright @copyright{} 2016, 2017, 2018, 2019, 2020, 2021 Christopher Baines@*
43 Copyright @copyright{} 2017, 2018, 2019 Clément Lassieur@*
44 Copyright @copyright{} 2017, 2018, 2020, 2021 Mathieu Othacehe@*
45 Copyright @copyright{} 2017 Federico Beffa@*
46 Copyright @copyright{} 2017, 2018 Carlo Zancanaro@*
47 Copyright @copyright{} 2017 Thomas Danckaert@*
48 Copyright @copyright{} 2017 humanitiesNerd@*
49 Copyright @copyright{} 2017, 2021 Christine Lemmer-Webber@*
50 Copyright @copyright{} 2017, 2018, 2019, 2020, 2021 Marius Bakke@*
51 Copyright @copyright{} 2017, 2019, 2020 Hartmut Goebel@*
52 Copyright @copyright{} 2017, 2019, 2020, 2021 Maxim Cournoyer@*
53 Copyright @copyright{} 2017–2022 Tobias Geerinckx-Rice@*
54 Copyright @copyright{} 2017 George Clemmer@*
55 Copyright @copyright{} 2017 Andy Wingo@*
56 Copyright @copyright{} 2017, 2018, 2019, 2020 Arun Isaac@*
57 Copyright @copyright{} 2017 nee@*
58 Copyright @copyright{} 2018 Rutger Helling@*
59 Copyright @copyright{} 2018, 2021 Oleg Pykhalov@*
60 Copyright @copyright{} 2018 Mike Gerwitz@*
61 Copyright @copyright{} 2018 Pierre-Antoine Rouby@*
62 Copyright @copyright{} 2018, 2019 Gábor Boskovits@*
63 Copyright @copyright{} 2018, 2019, 2020 Florian Pelz@*
64 Copyright @copyright{} 2018 Laura Lazzati@*
65 Copyright @copyright{} 2018 Alex Vong@*
66 Copyright @copyright{} 2019 Josh Holland@*
67 Copyright @copyright{} 2019, 2020 Diego Nicola Barbato@*
68 Copyright @copyright{} 2019 Ivan Petkov@*
69 Copyright @copyright{} 2019 Jakob L. Kreuze@*
70 Copyright @copyright{} 2019 Kyle Andrews@*
71 Copyright @copyright{} 2019 Alex Griffin@*
72 Copyright @copyright{} 2019, 2020, 2021 Guillaume Le Vaillant@*
73 Copyright @copyright{} 2020 Liliana Marie Prikler@*
74 Copyright @copyright{} 2019, 2020, 2021, 2022 Simon Tournier@*
75 Copyright @copyright{} 2020 Wiktor Żelazny@*
76 Copyright @copyright{} 2020 Damien Cassou@*
77 Copyright @copyright{} 2020 Jakub Kądziołka@*
78 Copyright @copyright{} 2020 Jack Hill@*
79 Copyright @copyright{} 2020 Naga Malleswari@*
80 Copyright @copyright{} 2020, 2021 Brice Waegeneire@*
81 Copyright @copyright{} 2020 R Veera Kumar@*
82 Copyright @copyright{} 2020, 2021 Pierre Langlois@*
83 Copyright @copyright{} 2020 pinoaffe@*
84 Copyright @copyright{} 2020 André Batista@*
85 Copyright @copyright{} 2020, 2021 Alexandru-Sergiu Marton@*
86 Copyright @copyright{} 2020 raingloom@*
87 Copyright @copyright{} 2020 Daniel Brooks@*
88 Copyright @copyright{} 2020 John Soo@*
89 Copyright @copyright{} 2020 Jonathan Brielmaier@*
90 Copyright @copyright{} 2020 Edgar Vincent@*
91 Copyright @copyright{} 2021 Maxime Devos@*
92 Copyright @copyright{} 2021 B. Wilson@*
93 Copyright @copyright{} 2021 Xinglu Chen@*
94 Copyright @copyright{} 2021 Raghav Gururajan@*
95 Copyright @copyright{} 2021 Domagoj Stolfa@*
96 Copyright @copyright{} 2021 Hui Lu@*
97 Copyright @copyright{} 2021 pukkamustard@*
98 Copyright @copyright{} 2021 Alice Brenon@*
99 Copyright @copyright{} 2021 Josselin Poiret@*
100 Copyright @copyright{} 2021 Andrew Tropin@*
101 Copyright @copyright{} 2021 Sarah Morgensen@*
102 Copyright @copyright{} 2021 Josselin Poiret@*
104 Permission is granted to copy, distribute and/or modify this document
105 under the terms of the GNU Free Documentation License, Version 1.3 or
106 any later version published by the Free Software Foundation; with no
107 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
108 copy of the license is included in the section entitled ``GNU Free
109 Documentation License''.
112 @dircategory System administration
114 * Guix: (guix). Manage installed software and system configuration.
115 * guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
116 * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
117 * guix pull: (guix)Invoking guix pull. Update the list of available packages.
118 * guix system: (guix)Invoking guix system. Manage the operating system configuration.
119 * guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts.
122 @dircategory Software development
124 * guix shell: (guix)Invoking guix shell. Creating software environments.
125 * guix environment: (guix)Invoking guix environment. Building development environments with Guix.
126 * guix build: (guix)Invoking guix build. Building packages.
127 * guix pack: (guix)Invoking guix pack. Creating binary bundles.
131 @title GNU Guix Reference Manual
132 @subtitle Using the GNU Guix Functional Package Manager
133 @author The GNU Guix Developers
136 @vskip 0pt plus 1filll
137 Edition @value{EDITION} @*
145 @c *********************************************************************
149 This document describes GNU Guix version @value{VERSION}, a functional
150 package management tool written for the GNU system.
152 @c TRANSLATORS: You can replace the following paragraph with information on
153 @c how to join your own translation team and how to report issues with the
155 This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
156 GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
157 Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
158 Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and
159 Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you
160 would like to translate it in your native language, consider joining
161 @uref{https://translate.fedoraproject.org/projects/guix/documentation-manual,
162 Weblate} (@pxref{Translating Guix}).
165 * Introduction:: What is Guix about?
166 * Installation:: Installing Guix.
167 * System Installation:: Installing the whole operating system.
168 * Getting Started:: Your first steps.
169 * Package Management:: Package installation, upgrade, etc.
170 * Channels:: Customizing the package collection.
171 * Development:: Guix-aided software development.
172 * Programming Interface:: Using Guix in Scheme.
173 * Utilities:: Package management commands.
174 * System Configuration:: Configuring the operating system.
175 * Home Configuration:: Configuring the home environment.
176 * Documentation:: Browsing software user manuals.
177 * Installing Debugging Files:: Feeding the debugger.
178 * Security Updates:: Deploying security fixes quickly.
179 * Bootstrapping:: GNU/Linux built from scratch.
180 * Porting:: Targeting another platform or kernel.
181 * Contributing:: Your help needed!
183 * Acknowledgments:: Thanks!
184 * GNU Free Documentation License:: The license of this manual.
185 * Concept Index:: Concepts.
186 * Programming Index:: Data types, functions, and variables.
189 --- The Detailed Node Listing ---
193 * Managing Software the Guix Way:: What's special.
194 * GNU Distribution:: The packages and tools.
198 * Binary Installation:: Getting Guix running in no time!
199 * Requirements:: Software needed to build and run Guix.
200 * Running the Test Suite:: Testing Guix.
201 * Setting Up the Daemon:: Preparing the build daemon's environment.
202 * Invoking guix-daemon:: Running the build daemon.
203 * Application Setup:: Application-specific setup.
204 * Upgrading Guix:: Upgrading Guix and its build daemon.
206 Setting Up the Daemon
208 * Build Environment Setup:: Preparing the isolated build environment.
209 * Daemon Offload Setup:: Offloading builds to remote machines.
210 * SELinux Support:: Using an SELinux policy for the daemon.
214 * Limitations:: What you can expect.
215 * Hardware Considerations:: Supported hardware.
216 * USB Stick and DVD Installation:: Preparing the installation medium.
217 * Preparing for Installation:: Networking, partitioning, etc.
218 * Guided Graphical Installation:: Easy graphical installation.
219 * Manual Installation:: Manual installation for wizards.
220 * After System Installation:: When installation succeeded.
221 * Installing Guix in a VM:: Guix System playground.
222 * Building the Installation Image:: How this comes to be.
226 * Keyboard Layout and Networking and Partitioning:: Initial setup.
227 * Proceeding with the Installation:: Installing.
231 * Features:: How Guix will make your life brighter.
232 * Invoking guix package:: Package installation, removal, etc.
233 * Substitutes:: Downloading pre-built binaries.
234 * Packages with Multiple Outputs:: Single source package, multiple outputs.
235 * Invoking guix gc:: Running the garbage collector.
236 * Invoking guix pull:: Fetching the latest Guix and distribution.
237 * Invoking guix time-machine:: Running an older revision of Guix.
238 * Inferiors:: Interacting with another revision of Guix.
239 * Invoking guix describe:: Display information about your Guix revision.
240 * Invoking guix archive:: Exporting and importing store files.
244 * Official Substitute Servers:: One particular source of substitutes.
245 * Substitute Server Authorization:: How to enable or disable substitutes.
246 * Getting Substitutes from Other Servers:: Substitute diversity.
247 * Substitute Authentication:: How Guix verifies substitutes.
248 * Proxy Settings:: How to get substitutes via proxy.
249 * Substitution Failure:: What happens when substitution fails.
250 * On Trusting Binaries:: How can you trust that binary blob?
254 * Specifying Additional Channels:: Extending the package collection.
255 * Using a Custom Guix Channel:: Using a customized Guix.
256 * Replicating Guix:: Running the @emph{exact same} Guix.
257 * Channel Authentication:: How Guix verifies what it fetches.
258 * Channels with Substitutes:: Using channels with available substitutes.
259 * Creating a Channel:: How to write your custom channel.
260 * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
261 * Declaring Channel Dependencies:: How to depend on other channels.
262 * Specifying Channel Authorizations:: Defining channel authors authorizations.
263 * Primary URL:: Distinguishing mirror to original.
264 * Writing Channel News:: Communicating information to channel's users.
268 * Invoking guix shell:: Spawning one-off software environments.
269 * Invoking guix environment:: Setting up development environments.
270 * Invoking guix pack:: Creating software bundles.
271 * The GCC toolchain:: Working with languages supported by GCC.
272 * Invoking guix git authenticate:: Authenticating Git repositories.
274 Programming Interface
276 * Package Modules:: Packages from the programmer's viewpoint.
277 * Defining Packages:: Defining new packages.
278 * Defining Package Variants:: Customizing packages.
279 * Build Systems:: Specifying how packages are built.
280 * Build Phases:: Phases of the build process of a package.
281 * Build Utilities:: Helpers for your package definitions and more.
282 * The Store:: Manipulating the package store.
283 * Derivations:: Low-level interface to package derivations.
284 * The Store Monad:: Purely functional interface to the store.
285 * G-Expressions:: Manipulating build expressions.
286 * Invoking guix repl:: Programming Guix in Guile.
290 * package Reference:: The package data type.
291 * origin Reference:: The origin data type.
295 * Invoking guix build:: Building packages from the command line.
296 * Invoking guix edit:: Editing package definitions.
297 * Invoking guix download:: Downloading a file and printing its hash.
298 * Invoking guix hash:: Computing the cryptographic hash of a file.
299 * Invoking guix import:: Importing package definitions.
300 * Invoking guix refresh:: Updating package definitions.
301 * Invoking guix style:: Styling package definitions.
302 * Invoking guix lint:: Finding errors in package definitions.
303 * Invoking guix size:: Profiling disk usage.
304 * Invoking guix graph:: Visualizing the graph of packages.
305 * Invoking guix publish:: Sharing substitutes.
306 * Invoking guix challenge:: Challenging substitute servers.
307 * Invoking guix copy:: Copying to and from a remote store.
308 * Invoking guix container:: Process isolation.
309 * Invoking guix weather:: Assessing substitute availability.
310 * Invoking guix processes:: Listing client processes.
312 Invoking @command{guix build}
314 * Common Build Options:: Build options for most commands.
315 * Package Transformation Options:: Creating variants of packages.
316 * Additional Build Options:: Options specific to 'guix build'.
317 * Debugging Build Failures:: Real life packaging experience.
321 * Using the Configuration System:: Customizing your GNU system.
322 * operating-system Reference:: Detail of operating-system declarations.
323 * File Systems:: Configuring file system mounts.
324 * Mapped Devices:: Block device extra processing.
325 * Swap Space:: Backing RAM with disk space.
326 * User Accounts:: Specifying user accounts.
327 * Keyboard Layout:: How the system interprets key strokes.
328 * Locales:: Language and cultural convention settings.
329 * Services:: Specifying system services.
330 * Setuid Programs:: Programs running with root privileges.
331 * X.509 Certificates:: Authenticating HTTPS servers.
332 * Name Service Switch:: Configuring libc's name service switch.
333 * Initial RAM Disk:: Linux-Libre bootstrapping.
334 * Bootloader Configuration:: Configuring the boot loader.
335 * Invoking guix system:: Instantiating a system configuration.
336 * Invoking guix deploy:: Deploying a system configuration to a remote host.
337 * Running Guix in a VM:: How to run Guix System in a virtual machine.
338 * Defining Services:: Adding new service definitions.
340 Home Environment Configuration
342 * Invoking guix home:: Instantiating a home environment configuration.
346 * Base Services:: Essential system services.
347 * Scheduled Job Execution:: The mcron service.
348 * Log Rotation:: The rottlog service.
349 * Networking Setup:: Setting up network interfaces.
350 * Networking Services:: Firewall, SSH daemon, etc.
351 * Unattended Upgrades:: Automated system upgrades.
352 * X Window:: Graphical display.
353 * Printing Services:: Local and remote printer support.
354 * Desktop Services:: D-Bus and desktop services.
355 * Sound Services:: ALSA and Pulseaudio services.
356 * Database Services:: SQL databases, key-value stores, etc.
357 * Mail Services:: IMAP, POP3, SMTP, and all that.
358 * Messaging Services:: Messaging services.
359 * Telephony Services:: Telephony services.
360 * Monitoring Services:: Monitoring services.
361 * Kerberos Services:: Kerberos services.
362 * LDAP Services:: LDAP services.
363 * Web Services:: Web servers.
364 * Certificate Services:: TLS certificates via Let's Encrypt.
365 * DNS Services:: DNS daemons.
366 * VPN Services:: VPN daemons.
367 * Network File System:: NFS related services.
368 * Continuous Integration:: Cuirass and Laminar services.
369 * Power Management Services:: Extending battery life.
370 * Audio Services:: The MPD.
371 * Virtualization Services:: Virtualization services.
372 * Version Control Services:: Providing remote access to Git repositories.
373 * Game Services:: Game servers.
374 * PAM Mount Service:: Service to mount volumes when logging in.
375 * Guix Services:: Services relating specifically to Guix.
376 * Linux Services:: Services tied to the Linux kernel.
377 * Hurd Services:: Services specific for a Hurd System.
378 * Miscellaneous Services:: Other services.
382 * Service Composition:: The model for composing services.
383 * Service Types and Services:: Types and services.
384 * Service Reference:: API reference.
385 * Shepherd Services:: A particular type of service.
386 * Complex Configurations:: Defining bindings for complex configurations.
388 Installing Debugging Files
390 * Separate Debug Info:: Installing 'debug' outputs.
391 * Rebuilding Debug Info:: Building missing debug info.
395 * Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
396 * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
401 @c *********************************************************************
403 @chapter Introduction
406 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
407 using the international phonetic alphabet (IPA).} is a package
408 management tool for and distribution of the GNU system.
409 Guix makes it easy for unprivileged
410 users to install, upgrade, or remove software packages, to roll back to a
411 previous package set, to build packages from source, and generally
412 assists with the creation and maintenance of software environments.
415 @cindex GuixSD, now Guix System
416 @cindex Guix System Distribution, now Guix System
417 You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it
418 complements the available tools without interference (@pxref{Installation}),
419 or you can use it as a standalone operating system distribution,
420 @dfn{Guix@tie{}System}@footnote{We used to refer to Guix System as ``Guix
421 System Distribution'' or ``GuixSD''. We now consider it makes more sense to
422 group everything under the ``Guix'' banner since, after all, Guix System is
423 readily available through the @command{guix system} command, even if you're
424 using a different distro underneath!}. @xref{GNU Distribution}.
427 * Managing Software the Guix Way:: What's special.
428 * GNU Distribution:: The packages and tools.
431 @node Managing Software the Guix Way
432 @section Managing Software the Guix Way
434 @cindex user interfaces
435 Guix provides a command-line package management interface
436 (@pxref{Package Management}), tools to help with software development
437 (@pxref{Development}), command-line utilities for more advanced usage
438 (@pxref{Utilities}), as well as Scheme programming interfaces
439 (@pxref{Programming Interface}).
441 Its @dfn{build daemon} is responsible for building packages on behalf of
442 users (@pxref{Setting Up the Daemon}) and for downloading pre-built
443 binaries from authorized sources (@pxref{Substitutes}).
445 @cindex extensibility of the distribution
446 @cindex customization, of packages
447 Guix includes package definitions for many GNU and non-GNU packages, all
448 of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the
449 user's computing freedom}. It is @emph{extensible}: users can write
450 their own package definitions (@pxref{Defining Packages}) and make them
451 available as independent package modules (@pxref{Package Modules}). It
452 is also @emph{customizable}: users can @emph{derive} specialized package
453 definitions from existing ones, including from the command line
454 (@pxref{Package Transformation Options}).
456 @cindex functional package management
458 Under the hood, Guix implements the @dfn{functional package management}
459 discipline pioneered by Nix (@pxref{Acknowledgments}).
460 In Guix, the package build and installation process is seen
461 as a @emph{function}, in the mathematical sense. That function takes inputs,
462 such as build scripts, a compiler, and libraries, and
463 returns an installed package. As a pure function, its result depends
464 solely on its inputs---for instance, it cannot refer to software or
465 scripts that were not explicitly passed as inputs. A build function
466 always produces the same result when passed a given set of inputs. It
467 cannot alter the environment of the running system in
468 any way; for instance, it cannot create, modify, or delete files outside
469 of its build and installation directories. This is achieved by running
470 build processes in isolated environments (or @dfn{containers}), where only their
471 explicit inputs are visible.
474 The result of package build functions is @dfn{cached} in the file
475 system, in a special directory called @dfn{the store} (@pxref{The
476 Store}). Each package is installed in a directory of its own in the
477 store---by default under @file{/gnu/store}. The directory name contains
478 a hash of all the inputs used to build that package; thus, changing an
479 input yields a different directory name.
481 This approach is the foundation for the salient features of Guix: support
482 for transactional package upgrade and rollback, per-user installation, and
483 garbage collection of packages (@pxref{Features}).
486 @node GNU Distribution
487 @section GNU Distribution
490 Guix comes with a distribution of the GNU system consisting entirely of
491 free software@footnote{The term ``free'' here refers to the
492 @url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to
493 users of that software}.}. The
494 distribution can be installed on its own (@pxref{System Installation}),
495 but it is also possible to install Guix as a package manager on top of
496 an installed GNU/Linux system (@pxref{Installation}). When we need to
497 distinguish between the two, we refer to the standalone distribution as
500 The distribution provides core GNU packages such as GNU libc, GCC, and
501 Binutils, as well as many GNU and non-GNU applications. The complete
502 list of available packages can be browsed
503 @url{https://www.gnu.org/software/guix/packages,on-line} or by
504 running @command{guix package} (@pxref{Invoking guix package}):
507 guix package --list-available
510 Our goal is to provide a practical 100% free software distribution of
511 Linux-based and other variants of GNU, with a focus on the promotion and
512 tight integration of GNU components, and an emphasis on programs and
513 tools that help users exert that freedom.
515 Packages are currently available on the following platforms:
520 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel.
523 Intel 32-bit architecture (IA32), Linux-Libre kernel.
526 ARMv7-A architecture with hard float, Thumb-2 and NEON,
527 using the EABI hard-float application binary interface (ABI),
528 and Linux-Libre kernel.
531 little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
534 @uref{https://hurd.gnu.org, GNU/Hurd} on the Intel 32-bit architecture
537 This configuration is experimental and under development. The easiest
538 way for you to give it a try is by setting up an instance of
539 @code{hurd-vm-service-type} on your GNU/Linux machine
540 (@pxref{transparent-emulation-qemu, @code{hurd-vm-service-type}}).
541 @xref{Contributing}, on how to help!
543 @item mips64el-linux (unsupported)
544 little-endian 64-bit MIPS processors, specifically the Loongson series,
545 n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
546 supported; in particular, there is no ongoing work to ensure that this
547 architecture still works. Should someone decide they wish to revive this
548 architecture then the code is still available.
550 @item powerpc-linux (unsupported)
551 big-endian 32-bit PowerPC processors, specifically the PowerPC G4 with
552 AltiVec support, and Linux-Libre kernel. This configuration is not
553 fully supported and there is no ongoing work to ensure this architecture
556 @item powerpc64le-linux
557 little-endian 64-bit Power ISA processors, Linux-Libre kernel. This
558 includes POWER9 systems such as the
559 @uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
560 RYF Talos II mainboard}. This platform is available as a "technology
561 preview": although it is supported, substitutes are not yet available
562 from the build farm (@pxref{Substitutes}), and some packages may fail to
563 build (@pxref{Tracking Bugs and Patches}). That said, the Guix
564 community is actively working on improving this support, and now is a
565 great time to try it and get involved!
569 With Guix@tie{}System, you @emph{declare} all aspects of the operating system
570 configuration and Guix takes care of instantiating the configuration in a
571 transactional, reproducible, and stateless fashion (@pxref{System
572 Configuration}). Guix System uses the Linux-libre kernel, the Shepherd
573 initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
574 Manual}), the well-known GNU utilities and tool chain, as well as the
575 graphical environment or system services of your choice.
577 Guix System is available on all the above platforms except
578 @code{mips64el-linux} and @code{powerpc64le-linux}.
581 For information on porting to other architectures or kernels,
584 Building this distribution is a cooperative effort, and you are invited
585 to join! @xref{Contributing}, for information about how you can help.
588 @c *********************************************************************
590 @chapter Installation
592 @cindex installing Guix
595 We recommend the use of this
596 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
597 shell installer script} to install Guix on top of a running GNU/Linux system,
598 thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
599 with the installation of the package manager, which can be done on top of a
600 running GNU/Linux system. If, instead, you want to install the complete GNU
601 operating system, @pxref{System Installation}.} The script automates the
602 download, installation, and initial configuration of Guix. It should be run
606 @cindex foreign distro
607 @cindex directories related to foreign distro
608 When installed on a foreign distro, GNU@tie{}Guix complements the available
609 tools without interference. Its data lives exclusively in two directories,
610 usually @file{/gnu/store} and @file{/var/guix}; other files on your system,
611 such as @file{/etc}, are left untouched.
613 Once installed, Guix can be updated by running @command{guix pull}
614 (@pxref{Invoking guix pull}).
616 If you prefer to perform the installation steps manually or want to tweak
617 them, you may find the following subsections useful. They describe the
618 software requirements of Guix, as well as how to install it manually and get
622 * Binary Installation:: Getting Guix running in no time!
623 * Requirements:: Software needed to build and run Guix.
624 * Running the Test Suite:: Testing Guix.
625 * Setting Up the Daemon:: Preparing the build daemon's environment.
626 * Invoking guix-daemon:: Running the build daemon.
627 * Application Setup:: Application-specific setup.
628 * Upgrading Guix:: Upgrading Guix and its build daemon.
631 @node Binary Installation
632 @section Binary Installation
634 @cindex installing Guix from binaries
635 @cindex installer script
636 This section describes how to install Guix on an arbitrary system from a
637 self-contained tarball providing binaries for Guix and for all its
638 dependencies. This is often quicker than installing from source, which
639 is described in the next sections. The only requirement is to have
642 @c Note duplicated from the ``Installation'' node.
644 We recommend the use of this
645 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
646 shell installer script}. The script automates the download, installation, and
647 initial configuration steps described below. It should be run as the root
648 user. As root, you can thus run this:
652 wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
653 chmod +x guix-install.sh
657 When you're done, @pxref{Application Setup} for extra configuration you
658 might need, and @ref{Getting Started} for your first steps!
661 Installing goes along these lines:
665 @cindex downloading Guix binary
666 Download the binary tarball from
667 @indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
668 where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
669 @code{i686} (32-bits) machine already running the kernel Linux, and so on
670 (@pxref{GNU Distribution}).
672 @c The following is somewhat duplicated in ``System Installation''.
673 Make sure to download the associated @file{.sig} file and to verify the
674 authenticity of the tarball against it, along these lines:
677 $ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
678 $ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
681 If that command fails because you do not have the required public key,
682 then run this command to import it:
685 $ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
686 -qO - | gpg --import -
690 and rerun the @code{gpg --verify} command.
692 Take note that a warning like ``This key is not certified with a trusted
693 signature!'' is normal.
695 @c end authentication part
698 Now, you need to become the @code{root} user. Depending on your distribution,
699 you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run:
703 # tar --warning=no-timestamp -xf \
704 /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
705 # mv var/guix /var/ && mv gnu /
708 This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
709 The latter contains a ready-to-use profile for @code{root} (see next
712 Do @emph{not} unpack the tarball on a working Guix system since that
713 would overwrite its own essential files.
715 The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
716 not emit warnings about ``implausibly old time stamps'' (such
717 warnings were triggered by GNU@tie{}tar 1.26 and older; recent
719 They stem from the fact that all the
720 files in the archive have their modification time set to 1 (which
721 means January 1st, 1970). This is done on purpose to make sure the
722 archive content is independent of its creation time, thus making it
726 Make the profile available under @file{~root/.config/guix/current}, which is
727 where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
730 # mkdir -p ~root/.config/guix
731 # ln -sf /var/guix/profiles/per-user/root/current-guix \
732 ~root/.config/guix/current
735 Source @file{etc/profile} to augment @env{PATH} and other relevant
736 environment variables:
739 # GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
740 source $GUIX_PROFILE/etc/profile
744 Create the group and user accounts for build users as explained below
745 (@pxref{Build Environment Setup}).
748 Run the daemon, and set it to automatically start on boot.
750 If your host distro uses the systemd init system, this can be achieved
753 @c Versions of systemd that supported symlinked service files are not
754 @c yet widely deployed, so we should suggest that users copy the service
757 @c See this thread for more information:
758 @c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
761 # cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
762 ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
764 # systemctl enable --now gnu-store.mount guix-daemon
767 You may also want to arrange for @command{guix gc} to run periodically:
770 # cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
771 ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
773 # systemctl enable --now guix-gc.timer
776 You may want to edit @file{guix-gc.service} to adjust the command line
777 options to fit your needs (@pxref{Invoking guix gc}).
779 If your host distro uses the Upstart init system:
782 # initctl reload-configuration
783 # cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
788 Otherwise, you can still start the daemon manually with:
791 # ~root/.config/guix/current/bin/guix-daemon \
792 --build-users-group=guixbuild
796 Make the @command{guix} command available to other users on the machine,
800 # mkdir -p /usr/local/bin
802 # ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
805 It is also a good idea to make the Info version of this manual available
809 # mkdir -p /usr/local/share/info
810 # cd /usr/local/share/info
811 # for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
815 That way, assuming @file{/usr/local/share/info} is in the search path,
816 running @command{info guix} will open this manual (@pxref{Other Info
817 Directories,,, texinfo, GNU Texinfo}, for more details on changing the
821 @cindex substitutes, authorization thereof
822 To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
823 @code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
827 # guix archive --authorize < \
828 ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
829 # guix archive --authorize < \
830 ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
834 If you do not enable substitutes, Guix will end up building
835 @emph{everything} from source on your machine, making each installation
836 and upgrade very expensive. @xref{On Trusting Binaries}, for a
837 discussion of reasons why one might want do disable substitutes.
841 Each user may need to perform a few additional steps to make their Guix
842 environment ready for use, @pxref{Application Setup}.
845 Voilà, the installation is complete!
847 You can confirm that Guix is working by installing a sample package into
854 The binary installation tarball can be (re)produced and verified simply
855 by running the following command in the Guix source tree:
858 make guix-binary.@var{system}.tar.xz
862 ...@: which, in turn, runs:
865 guix pack -s @var{system} --localstatedir \
866 --profile-name=current-guix guix
869 @xref{Invoking guix pack}, for more info on this handy tool.
872 @section Requirements
874 This section lists requirements when building Guix from source. The
875 build procedure for Guix is the same as for other GNU software, and is
876 not covered here. Please see the files @file{README} and @file{INSTALL}
877 in the Guix source tree for additional details.
879 @cindex official website
880 GNU Guix is available for download from its website at
881 @url{https://www.gnu.org/software/guix/}.
883 GNU Guix depends on the following packages:
886 @item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x;
887 @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
890 @uref{https://gnutls.org/, GnuTLS}, specifically its Guile bindings
891 (@pxref{Guile Preparations, how to install the GnuTLS bindings for
892 Guile,, gnutls-guile, GnuTLS-Guile});
894 @uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
896 @item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
897 version 0.1.0 or later;
898 @item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
899 @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
901 @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
903 @item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
905 @item @url{https://www.gnu.org/software/make/, GNU Make}.
908 The following dependencies are optional:
912 @c Note: We need at least 0.13.0 for #:nodelay.
913 Support for build offloading (@pxref{Daemon Offload Setup}) and
914 @command{guix copy} (@pxref{Invoking guix copy}) depends on
915 @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
916 version 0.13.0 or later.
919 @uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
920 compression and decompression in @command{guix publish} and for
921 substitutes (@pxref{Invoking guix publish}).
924 @uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
925 the @code{crate} importer (@pxref{Invoking guix import}).
928 @uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
929 the @code{go} importer (@pxref{Invoking guix import}) and for some of
930 the ``updaters'' (@pxref{Invoking guix refresh}).
933 When @url{http://www.bzip.org, libbz2} is available,
934 @command{guix-daemon} can use it to compress build logs.
937 Unless @option{--disable-daemon} was passed to @command{configure}, the
938 following packages are also needed:
941 @item @url{https://gnupg.org/, GNU libgcrypt};
942 @item @url{https://sqlite.org, SQLite 3};
943 @item @url{https://gcc.gnu.org, GCC's g++}, with support for the
947 @cindex state directory
948 When configuring Guix on a system that already has a Guix installation,
949 be sure to specify the same state directory as the existing installation
950 using the @option{--localstatedir} option of the @command{configure}
951 script (@pxref{Directory Variables, @code{localstatedir},, standards,
952 GNU Coding Standards}). Usually, this @var{localstatedir} option is
953 set to the value @file{/var}. The @command{configure} script protects
954 against unintended misconfiguration of @var{localstatedir} so you do not
955 inadvertently corrupt your store (@pxref{The Store}).
957 @node Running the Test Suite
958 @section Running the Test Suite
961 After a successful @command{configure} and @code{make} run, it is a good
962 idea to run the test suite. It can help catch issues with the setup or
963 environment, or bugs in Guix itself---and really, reporting test
964 failures is a good way to help improve the software. To run the test
971 Test cases can run in parallel: you can use the @code{-j} option of
972 GNU@tie{}make to speed things up. The first run may take a few minutes
973 on a recent machine; subsequent runs will be faster because the store
974 that is created for test purposes will already have various things in
977 It is also possible to run a subset of the tests by defining the
978 @code{TESTS} makefile variable as in this example:
981 make check TESTS="tests/store.scm tests/cpio.scm"
984 By default, tests results are displayed at a file level. In order to
985 see the details of every individual test cases, it is possible to define
986 the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
989 make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
992 The underlying SRFI 64 custom Automake test driver used for the 'check'
993 test suite (located at @file{build-aux/test-driver.scm}) also allows
994 selecting which test cases to run at a finer level, via its
995 @option{--select} and @option{--exclude} options. Here's an example, to
996 run all the test cases from the @file{tests/packages.scm} test file
997 whose names start with ``transaction-upgrade-entry'':
1000 export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
1001 make check TESTS="tests/packages.scm"
1004 Those wishing to inspect the results of failed tests directly from the
1005 command line can add the @option{--errors-only=yes} option to the
1006 @code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
1007 Automake makefile variable, as in:
1010 make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
1013 The @option{--show-duration=yes} option can be used to print the
1014 duration of the individual test cases, when used in combination with
1015 @option{--brief=no}:
1018 make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
1021 @xref{Parallel Test Harness,,,automake,GNU Automake} for more
1022 information about the Automake Parallel Test Harness.
1024 Upon failure, please email @email{bug-guix@@gnu.org} and attach the
1025 @file{test-suite.log} file. Please specify the Guix version being used
1026 as well as version numbers of the dependencies (@pxref{Requirements}) in
1029 Guix also comes with a whole-system test suite that tests complete
1030 Guix System instances. It can only run on systems where
1031 Guix is already installed, using:
1038 or, again, by defining @code{TESTS} to select a subset of tests to run:
1041 make check-system TESTS="basic mcron"
1044 These system tests are defined in the @code{(gnu tests @dots{})}
1045 modules. They work by running the operating systems under test with
1046 lightweight instrumentation in a virtual machine (VM). They can be
1047 computationally intensive or rather cheap, depending on whether
1048 substitutes are available for their dependencies (@pxref{Substitutes}).
1049 Some of them require a lot of storage space to hold VM images.
1051 Again in case of test failures, please send @email{bug-guix@@gnu.org}
1054 @node Setting Up the Daemon
1055 @section Setting Up the Daemon
1058 Operations such as building a package or running the garbage collector
1059 are all performed by a specialized process, the @dfn{build daemon}, on
1060 behalf of clients. Only the daemon may access the store and its
1061 associated database. Thus, any operation that manipulates the store
1062 goes through the daemon. For instance, command-line tools such as
1063 @command{guix package} and @command{guix build} communicate with the
1064 daemon (@i{via} remote procedure calls) to instruct it what to do.
1066 The following sections explain how to prepare the build daemon's
1067 environment. See also @ref{Substitutes}, for information on how to allow
1068 the daemon to download pre-built binaries.
1071 * Build Environment Setup:: Preparing the isolated build environment.
1072 * Daemon Offload Setup:: Offloading builds to remote machines.
1073 * SELinux Support:: Using an SELinux policy for the daemon.
1076 @node Build Environment Setup
1077 @subsection Build Environment Setup
1079 @cindex build environment
1080 In a standard multi-user setup, Guix and its daemon---the
1081 @command{guix-daemon} program---are installed by the system
1082 administrator; @file{/gnu/store} is owned by @code{root} and
1083 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
1084 Guix tools to build packages or otherwise access the store, and the
1085 daemon will do it on their behalf, ensuring that the store is kept in a
1086 consistent state, and allowing built packages to be shared among users.
1089 When @command{guix-daemon} runs as @code{root}, you may not want package
1090 build processes themselves to run as @code{root} too, for obvious
1091 security reasons. To avoid that, a special pool of @dfn{build users}
1092 should be created for use by build processes started by the daemon.
1093 These build users need not have a shell and a home directory: they will
1094 just be used when the daemon drops @code{root} privileges in build
1095 processes. Having several such users allows the daemon to launch
1096 distinct build processes under separate UIDs, which guarantees that they
1097 do not interfere with each other---an essential feature since builds are
1098 regarded as pure functions (@pxref{Introduction}).
1100 On a GNU/Linux system, a build user pool may be created like this (using
1101 Bash syntax and the @code{shadow} commands):
1103 @c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
1104 @c for why `-G' is needed.
1106 # groupadd --system guixbuild
1107 # for i in $(seq -w 1 10);
1109 useradd -g guixbuild -G guixbuild \
1110 -d /var/empty -s $(which nologin) \
1111 -c "Guix build user $i" --system \
1117 The number of build users determines how many build jobs may run in
1118 parallel, as specified by the @option{--max-jobs} option
1119 (@pxref{Invoking guix-daemon, @option{--max-jobs}}). To use
1120 @command{guix system vm} and related commands, you may need to add the
1121 build users to the @code{kvm} group so they can access @file{/dev/kvm},
1122 using @code{-G guixbuild,kvm} instead of @code{-G guixbuild}
1123 (@pxref{Invoking guix system}).
1125 The @code{guix-daemon} program may then be run as @code{root} with the
1126 following command@footnote{If your machine uses the systemd init system,
1127 dropping the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
1128 file in @file{/etc/systemd/system} will ensure that
1129 @command{guix-daemon} is automatically started. Similarly, if your
1130 machine uses the Upstart init system, drop the
1131 @file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
1132 file in @file{/etc/init}.}:
1135 # guix-daemon --build-users-group=guixbuild
1140 This way, the daemon starts build processes in a chroot, under one of
1141 the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
1142 environment contains nothing but:
1144 @c Keep this list in sync with libstore/build.cc! -----------------------
1147 a minimal @code{/dev} directory, created mostly independently from the
1148 host @code{/dev}@footnote{``Mostly'', because while the set of files
1149 that appear in the chroot's @code{/dev} is fixed, most of these files
1150 can only be created if the host has them.};
1153 the @code{/proc} directory; it only shows the processes of the container
1154 since a separate PID name space is used;
1157 @file{/etc/passwd} with an entry for the current user and an entry for
1161 @file{/etc/group} with an entry for the user's group;
1164 @file{/etc/hosts} with an entry that maps @code{localhost} to
1168 a writable @file{/tmp} directory.
1171 You can influence the directory where the daemon stores build trees
1172 @i{via} the @env{TMPDIR} environment variable. However, the build tree
1173 within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
1174 where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
1175 This way, the value of @env{TMPDIR} does not leak inside build
1176 environments, which avoids discrepancies in cases where build processes
1177 capture the name of their build tree.
1181 The daemon also honors the @env{http_proxy} and @env{https_proxy}
1182 environment variables for HTTP and HTTPS downloads it performs, be it
1183 for fixed-output derivations (@pxref{Derivations}) or for substitutes
1184 (@pxref{Substitutes}).
1186 If you are installing Guix as an unprivileged user, it is still possible
1187 to run @command{guix-daemon} provided you pass @option{--disable-chroot}.
1188 However, build processes will not be isolated from one another, and not
1189 from the rest of the system. Thus, build processes may interfere with
1190 each other, and may access programs, libraries, and other files
1191 available on the system---making it much harder to view them as
1192 @emph{pure} functions.
1195 @node Daemon Offload Setup
1196 @subsection Using the Offload Facility
1200 When desired, the build daemon can @dfn{offload} derivation builds to
1201 other machines running Guix, using the @code{offload} @dfn{build
1202 hook}@footnote{This feature is available only when
1203 @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
1204 present.}. When that feature is enabled, a list of user-specified build
1205 machines is read from @file{/etc/guix/machines.scm}; every time a build
1206 is requested, for instance via @code{guix build}, the daemon attempts to
1207 offload it to one of the machines that satisfy the constraints of the
1208 derivation, in particular its system types---e.g., @code{x86_64-linux}.
1209 A single machine can have multiple system types, either because its
1210 architecture natively supports it, via emulation
1211 (@pxref{transparent-emulation-qemu, Transparent Emulation with QEMU}),
1212 or both. Missing prerequisites for the build are
1213 copied over SSH to the target machine, which then proceeds with the
1214 build; upon success the output(s) of the build are copied back to the
1215 initial machine. The offload facility comes with a basic scheduler that
1216 attempts to select the best machine. The best machine is chosen among
1217 the available machines based on criteria such as:
1221 The availability of a build slot. A build machine can have as many
1222 build slots (connections) as the value of the @code{parallel-builds}
1223 field of its @code{build-machine} object.
1226 Its relative speed, as defined via the @code{speed} field of its
1227 @code{build-machine} object.
1230 Its load. The normalized machine load must be lower than a threshold
1231 value, configurable via the @code{overload-threshold} field of its
1232 @code{build-machine} object.
1235 Disk space availability. More than a 100 MiB must be available.
1238 The @file{/etc/guix/machines.scm} file typically looks like this:
1241 (list (build-machine
1242 (name "eightysix.example.org")
1243 (systems (list "x86_64-linux" "i686-linux"))
1244 (host-key "ssh-ed25519 AAAAC3Nza@dots{}")
1246 (speed 2.)) ;incredibly fast!
1249 (name "armeight.example.org")
1250 (systems (list "aarch64-linux"))
1251 (host-key "ssh-rsa AAAAB3Nza@dots{}")
1254 ;; Remember 'guix offload' is spawned by
1255 ;; 'guix-daemon' as root.
1256 (private-key "/root/.ssh/identity-for-guix")))
1260 In the example above we specify a list of two build machines, one for
1261 the @code{x86_64} and @code{i686} architectures and one for the
1262 @code{aarch64} architecture.
1264 In fact, this file is---not surprisingly!---a Scheme file that is
1265 evaluated when the @code{offload} hook is started. Its return value
1266 must be a list of @code{build-machine} objects. While this example
1267 shows a fixed list of build machines, one could imagine, say, using
1268 DNS-SD to return a list of potential build machines discovered in the
1269 local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
1270 Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
1273 @deftp {Data Type} build-machine
1274 This data type represents build machines to which the daemon may offload
1275 builds. The important fields are:
1280 The host name of the remote machine.
1283 The system types the remote machine supports---e.g., @code{(list
1284 "x86_64-linux" "i686-linux")}.
1287 The user account to use when connecting to the remote machine over SSH.
1288 Note that the SSH key pair must @emph{not} be passphrase-protected, to
1289 allow non-interactive logins.
1292 This must be the machine's SSH @dfn{public host key} in OpenSSH format.
1293 This is used to authenticate the machine when we connect to it. It is a
1294 long string that looks like this:
1297 ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
1300 If the machine is running the OpenSSH daemon, @command{sshd}, the host
1301 key can be found in a file such as
1302 @file{/etc/ssh/ssh_host_ed25519_key.pub}.
1304 If the machine is running the SSH daemon of GNU@tie{}lsh,
1305 @command{lshd}, the host key is in @file{/etc/lsh/host-key.pub} or a
1306 similar file. It can be converted to the OpenSSH format using
1307 @command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
1310 $ lsh-export-key --openssh < /etc/lsh/host-key.pub
1311 ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
1316 A number of optional fields may be specified:
1320 @item @code{port} (default: @code{22})
1321 Port number of SSH server on the machine.
1323 @item @code{private-key} (default: @file{~root/.ssh/id_rsa})
1324 The SSH private key file to use when connecting to the machine, in
1325 OpenSSH format. This key must not be protected with a passphrase.
1327 Note that the default value is the private key @emph{of the root
1328 account}. Make sure it exists if you use the default.
1330 @item @code{compression} (default: @code{"zlib@@openssh.com,zlib"})
1331 @itemx @code{compression-level} (default: @code{3})
1332 The SSH-level compression methods and compression level requested.
1334 Note that offloading relies on SSH compression to reduce bandwidth usage
1335 when transferring files to and from build machines.
1337 @item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"})
1338 File name of the Unix-domain socket @command{guix-daemon} is listening
1341 @item @code{overload-threshold} (default: @code{0.6})
1342 The load threshold above which a potential offload machine is
1343 disregarded by the offload scheduler. The value roughly translates to
1344 the total processor usage of the build machine, ranging from 0.0 (0%) to
1345 1.0 (100%). It can also be disabled by setting
1346 @code{overload-threshold} to @code{#f}.
1348 @item @code{parallel-builds} (default: @code{1})
1349 The number of builds that may run in parallel on the machine.
1351 @item @code{speed} (default: @code{1.0})
1352 A ``relative speed factor''. The offload scheduler will tend to prefer
1353 machines with a higher speed factor.
1355 @item @code{features} (default: @code{'()})
1356 A list of strings denoting specific features supported by the machine.
1357 An example is @code{"kvm"} for machines that have the KVM Linux modules
1358 and corresponding hardware support. Derivations can request features by
1359 name, and they will be scheduled on matching build machines.
1364 The @command{guix} command must be in the search path on the build
1365 machines. You can check whether this is the case by running:
1368 ssh build-machine guix repl --version
1371 There is one last thing to do once @file{machines.scm} is in place. As
1372 explained above, when offloading, files are transferred back and forth
1373 between the machine stores. For this to work, you first need to
1374 generate a key pair on each machine to allow the daemon to export signed
1375 archives of files from the store (@pxref{Invoking guix archive}):
1378 # guix archive --generate-key
1382 Each build machine must authorize the key of the master machine so that
1383 it accepts store items it receives from the master:
1386 # guix archive --authorize < master-public-key.txt
1390 Likewise, the master machine must authorize the key of each build machine.
1392 All the fuss with keys is here to express pairwise mutual trust
1393 relations between the master and the build machines. Concretely, when
1394 the master receives files from a build machine (and @i{vice versa}), its
1395 build daemon can make sure they are genuine, have not been tampered
1396 with, and that they are signed by an authorized key.
1398 @cindex offload test
1399 To test whether your setup is operational, run this command on the
1406 This will attempt to connect to each of the build machines specified in
1407 @file{/etc/guix/machines.scm}, make sure Guix is
1408 available on each machine, attempt to export to the machine and import
1409 from it, and report any error in the process.
1411 If you want to test a different machine file, just specify it on the
1415 # guix offload test machines-qualif.scm
1418 Last, you can test the subset of the machines whose name matches a
1419 regular expression like this:
1422 # guix offload test machines.scm '\.gnu\.org$'
1425 @cindex offload status
1426 To display the current load of all build hosts, run this command on the
1430 # guix offload status
1434 @node SELinux Support
1435 @subsection SELinux Support
1437 @cindex SELinux, daemon policy
1438 @cindex mandatory access control, SELinux
1439 @cindex security, guix-daemon
1440 Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that
1441 can be installed on a system where SELinux is enabled, in order to label
1442 Guix files and to specify the expected behavior of the daemon. Since
1443 Guix System does not provide an SELinux base policy, the daemon policy cannot
1444 be used on Guix System.
1446 @subsubsection Installing the SELinux policy
1447 @cindex SELinux, policy installation
1448 To install the policy run this command as root:
1451 semodule -i etc/guix-daemon.cil
1454 Then relabel the file system with @code{restorecon} or by a different
1455 mechanism provided by your system.
1457 Once the policy is installed, the file system has been relabeled, and
1458 the daemon has been restarted, it should be running in the
1459 @code{guix_daemon_t} context. You can confirm this with the following
1463 ps -Zax | grep guix-daemon
1466 Monitor the SELinux log files as you run a command like @code{guix build
1467 hello} to convince yourself that SELinux permits all necessary
1470 @subsubsection Limitations
1471 @cindex SELinux, limitations
1473 This policy is not perfect. Here is a list of limitations or quirks
1474 that should be considered when deploying the provided SELinux policy for
1479 @code{guix_daemon_socket_t} isn’t actually used. None of the socket
1480 operations involve contexts that have anything to do with
1481 @code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label,
1482 but it would be preferable to define socket rules for only this label.
1485 @code{guix gc} cannot access arbitrary links to profiles. By design,
1486 the file label of the destination of a symlink is independent of the
1487 file label of the link itself. Although all profiles under
1488 $localstatedir are labelled, the links to these profiles inherit the
1489 label of the directory they are in. For links in the user’s home
1490 directory this will be @code{user_home_t}. But for links from the root
1491 user’s home directory, or @file{/tmp}, or the HTTP server’s working
1492 directory, etc, this won’t work. @code{guix gc} would be prevented from
1493 reading and following these links.
1496 The daemon’s feature to listen for TCP connections might no longer work.
1497 This might require extra rules, because SELinux treats network sockets
1498 differently from files.
1501 Currently all files with a name matching the regular expression
1502 @code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the
1503 label @code{guix_daemon_exec_t}; this means that @emph{any} file with
1504 that name in any profile would be permitted to run in the
1505 @code{guix_daemon_t} domain. This is not ideal. An attacker could
1506 build a package that provides this executable and convince a user to
1507 install and run it, which lifts it into the @code{guix_daemon_t} domain.
1508 At that point SELinux could not prevent it from accessing files that are
1509 allowed for processes in that domain.
1511 You will need to relabel the store directory after all upgrades to
1512 @file{guix-daemon}, such as after running @code{guix pull}. Assuming the
1513 store is in @file{/gnu}, you can do this with @code{restorecon -vR /gnu},
1514 or by other means provided by your operating system.
1516 We could generate a much more restrictive policy at installation time,
1517 so that only the @emph{exact} file name of the currently installed
1518 @code{guix-daemon} executable would be labelled with
1519 @code{guix_daemon_exec_t}, instead of using a broad regular expression.
1520 The downside is that root would have to install or upgrade the policy at
1521 installation time whenever the Guix package that provides the
1522 effectively running @code{guix-daemon} executable is upgraded.
1525 @node Invoking guix-daemon
1526 @section Invoking @command{guix-daemon}
1528 The @command{guix-daemon} program implements all the functionality to
1529 access the store. This includes launching build processes, running the
1530 garbage collector, querying the availability of a build result, etc. It
1531 is normally run as @code{root} like this:
1534 # guix-daemon --build-users-group=guixbuild
1538 For details on how to set it up, @pxref{Setting Up the Daemon}.
1541 @cindex container, build environment
1542 @cindex build environment
1543 @cindex reproducible builds
1544 By default, @command{guix-daemon} launches build processes under
1545 different UIDs, taken from the build group specified with
1546 @option{--build-users-group}. In addition, each build process is run in a
1547 chroot environment that only contains the subset of the store that the
1548 build process depends on, as specified by its derivation
1549 (@pxref{Programming Interface, derivation}), plus a set of specific
1550 system directories. By default, the latter contains @file{/dev} and
1551 @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
1552 @dfn{container}: in addition to having its own file system tree, it has
1553 a separate mount name space, its own PID name space, network name space,
1554 etc. This helps achieve reproducible builds (@pxref{Features}).
1556 When the daemon performs a build on behalf of the user, it creates a
1557 build directory under @file{/tmp} or under the directory specified by
1558 its @env{TMPDIR} environment variable. This directory is shared with
1559 the container for the duration of the build, though within the container,
1560 the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
1562 The build directory is automatically deleted upon completion, unless the
1563 build failed and the client specified @option{--keep-failed}
1564 (@pxref{Common Build Options, @option{--keep-failed}}).
1566 The daemon listens for connections and spawns one sub-process for each session
1567 started by a client (one of the @command{guix} sub-commands). The
1568 @command{guix processes} command allows you to get an overview of the activity
1569 on your system by viewing each of the active sessions and clients.
1570 @xref{Invoking guix processes}, for more information.
1572 The following command-line options are supported:
1575 @item --build-users-group=@var{group}
1576 Take users from @var{group} to run build processes (@pxref{Setting Up
1577 the Daemon, build users}).
1579 @item --no-substitutes
1581 Do not use substitutes for build products. That is, always build things
1582 locally instead of allowing downloads of pre-built binaries
1583 (@pxref{Substitutes}).
1585 When the daemon runs with @option{--no-substitutes}, clients can still
1586 explicitly enable substitution @i{via} the @code{set-build-options}
1587 remote procedure call (@pxref{The Store}).
1589 @anchor{daemon-substitute-urls}
1590 @item --substitute-urls=@var{urls}
1591 Consider @var{urls} the default whitespace-separated list of substitute
1592 source URLs. When this option is omitted,
1593 @indicateurl{@value{SUBSTITUTE-URLS}} is used.
1595 This means that substitutes may be downloaded from @var{urls}, as long
1596 as they are signed by a trusted signature (@pxref{Substitutes}).
1598 @xref{Getting Substitutes from Other Servers}, for more information on
1599 how to configure the daemon to get substitutes from other servers.
1603 Do not use offload builds to other machines (@pxref{Daemon Offload
1604 Setup}). That is, always build things locally instead of offloading
1605 builds to remote machines.
1607 @item --cache-failures
1608 Cache build failures. By default, only successful builds are cached.
1610 When this option is used, @command{guix gc --list-failures} can be used
1611 to query the set of store items marked as failed; @command{guix gc
1612 --clear-failures} removes store items from the set of cached failures.
1613 @xref{Invoking guix gc}.
1615 @item --cores=@var{n}
1617 Use @var{n} CPU cores to build each derivation; @code{0} means as many
1620 The default value is @code{0}, but it may be overridden by clients, such
1621 as the @option{--cores} option of @command{guix build} (@pxref{Invoking
1624 The effect is to define the @env{NIX_BUILD_CORES} environment variable
1625 in the build process, which can then use it to exploit internal
1626 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
1628 @item --max-jobs=@var{n}
1630 Allow at most @var{n} build jobs in parallel. The default value is
1631 @code{1}. Setting it to @code{0} means that no builds will be performed
1632 locally; instead, the daemon will offload builds (@pxref{Daemon Offload
1633 Setup}), or simply fail.
1635 @item --max-silent-time=@var{seconds}
1636 When the build or substitution process remains silent for more than
1637 @var{seconds}, terminate it and report a build failure.
1639 The default value is @code{0}, which disables the timeout.
1641 The value specified here can be overridden by clients (@pxref{Common
1642 Build Options, @option{--max-silent-time}}).
1644 @item --timeout=@var{seconds}
1645 Likewise, when the build or substitution process lasts for more than
1646 @var{seconds}, terminate it and report a build failure.
1648 The default value is @code{0}, which disables the timeout.
1650 The value specified here can be overridden by clients (@pxref{Common
1651 Build Options, @option{--timeout}}).
1653 @item --rounds=@var{N}
1654 Build each derivation @var{n} times in a row, and raise an error if
1655 consecutive build results are not bit-for-bit identical. Note that this
1656 setting can be overridden by clients such as @command{guix build}
1657 (@pxref{Invoking guix build}).
1659 When used in conjunction with @option{--keep-failed}, the differing
1660 output is kept in the store, under @file{/gnu/store/@dots{}-check}.
1661 This makes it easy to look for differences between the two results.
1664 Produce debugging output.
1666 This is useful to debug daemon start-up issues, but then it may be
1667 overridden by clients, for example the @option{--verbosity} option of
1668 @command{guix build} (@pxref{Invoking guix build}).
1670 @item --chroot-directory=@var{dir}
1671 Add @var{dir} to the build chroot.
1673 Doing this may change the result of build processes---for instance if
1674 they use optional dependencies found in @var{dir} when it is available,
1675 and not otherwise. For that reason, it is not recommended to do so.
1676 Instead, make sure that each derivation declares all the inputs that it
1679 @item --disable-chroot
1680 Disable chroot builds.
1682 Using this option is not recommended since, again, it would allow build
1683 processes to gain access to undeclared dependencies. It is necessary,
1684 though, when @command{guix-daemon} is running under an unprivileged user
1687 @item --log-compression=@var{type}
1688 Compress build logs according to @var{type}, one of @code{gzip},
1689 @code{bzip2}, or @code{none}.
1691 Unless @option{--lose-logs} is used, all the build logs are kept in the
1692 @var{localstatedir}. To save space, the daemon automatically compresses
1693 them with Bzip2 by default.
1695 @item --discover[=yes|no]
1696 Whether to discover substitute servers on the local network using mDNS
1699 This feature is still experimental. However, here are a few
1704 It might be faster/less expensive than fetching from remote servers;
1706 There are no security risks, only genuine substitutes will be used
1707 (@pxref{Substitute Authentication});
1709 An attacker advertising @command{guix publish} on your LAN cannot serve
1710 you malicious binaries, but they can learn what software you’re
1713 Servers may serve substitute over HTTP, unencrypted, so anyone on the
1714 LAN can see what software you’re installing.
1717 It is also possible to enable or disable substitute server discovery at
1718 run-time by running:
1721 herd discover guix-daemon on
1722 herd discover guix-daemon off
1725 @item --disable-deduplication
1726 @cindex deduplication
1727 Disable automatic file ``deduplication'' in the store.
1729 By default, files added to the store are automatically ``deduplicated'':
1730 if a newly added file is identical to another one found in the store,
1731 the daemon makes the new file a hard link to the other file. This can
1732 noticeably reduce disk usage, at the expense of slightly increased
1733 input/output load at the end of a build process. This option disables
1736 @item --gc-keep-outputs[=yes|no]
1737 Tell whether the garbage collector (GC) must keep outputs of live
1741 @cindex garbage collector roots
1742 When set to @code{yes}, the GC will keep the outputs of any live
1743 derivation available in the store---the @file{.drv} files. The default
1744 is @code{no}, meaning that derivation outputs are kept only if they are
1745 reachable from a GC root. @xref{Invoking guix gc}, for more on GC
1748 @item --gc-keep-derivations[=yes|no]
1749 Tell whether the garbage collector (GC) must keep derivations
1750 corresponding to live outputs.
1752 When set to @code{yes}, as is the case by default, the GC keeps
1753 derivations---i.e., @file{.drv} files---as long as at least one of their
1754 outputs is live. This allows users to keep track of the origins of
1755 items in their store. Setting it to @code{no} saves a bit of disk
1758 In this way, setting @option{--gc-keep-derivations} to @code{yes} causes
1759 liveness to flow from outputs to derivations, and setting
1760 @option{--gc-keep-outputs} to @code{yes} causes liveness to flow from
1761 derivations to outputs. When both are set to @code{yes}, the effect is
1762 to keep all the build prerequisites (the sources, compiler, libraries,
1763 and other build-time tools) of live objects in the store, regardless of
1764 whether these prerequisites are reachable from a GC root. This is
1765 convenient for developers since it saves rebuilds or downloads.
1767 @item --impersonate-linux-2.6
1768 On Linux-based systems, impersonate Linux 2.6. This means that the
1769 kernel's @command{uname} system call will report 2.6 as the release number.
1771 This might be helpful to build programs that (usually wrongfully) depend
1772 on the kernel version number.
1775 Do not keep build logs. By default they are kept under
1776 @file{@var{localstatedir}/guix/log}.
1778 @item --system=@var{system}
1779 Assume @var{system} as the current system type. By default it is the
1780 architecture/kernel pair found at configure time, such as
1781 @code{x86_64-linux}.
1783 @item --listen=@var{endpoint}
1784 Listen for connections on @var{endpoint}. @var{endpoint} is interpreted
1785 as the file name of a Unix-domain socket if it starts with
1786 @code{/} (slash sign). Otherwise, @var{endpoint} is interpreted as a
1787 host name or host name and port to listen to. Here are a few examples:
1790 @item --listen=/gnu/var/daemon
1791 Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
1792 creating it if needed.
1794 @item --listen=localhost
1795 @cindex daemon, remote access
1796 @cindex remote access to the daemon
1797 @cindex daemon, cluster setup
1798 @cindex clusters, daemon setup
1799 Listen for TCP connections on the network interface corresponding to
1800 @code{localhost}, on port 44146.
1802 @item --listen=128.0.0.42:1234
1803 Listen for TCP connections on the network interface corresponding to
1804 @code{128.0.0.42}, on port 1234.
1807 This option can be repeated multiple times, in which case
1808 @command{guix-daemon} accepts connections on all the specified
1809 endpoints. Users can tell client commands what endpoint to connect to
1810 by setting the @env{GUIX_DAEMON_SOCKET} environment variable
1811 (@pxref{The Store, @env{GUIX_DAEMON_SOCKET}}).
1814 The daemon protocol is @emph{unauthenticated and unencrypted}. Using
1815 @option{--listen=@var{host}} is suitable on local networks, such as
1816 clusters, where only trusted nodes may connect to the build daemon. In
1817 other cases where remote access to the daemon is needed, we recommend
1818 using Unix-domain sockets along with SSH.
1821 When @option{--listen} is omitted, @command{guix-daemon} listens for
1822 connections on the Unix-domain socket located at
1823 @file{@var{localstatedir}/guix/daemon-socket/socket}.
1827 @node Application Setup
1828 @section Application Setup
1830 @cindex foreign distro
1831 When using Guix on top of GNU/Linux distribution other than Guix System---a
1832 so-called @dfn{foreign distro}---a few additional steps are needed to
1833 get everything in place. Here are some of them.
1837 @anchor{locales-and-locpath}
1838 @cindex locales, when not on Guix System
1840 @vindex GUIX_LOCPATH
1841 Packages installed @i{via} Guix will not use the locale data of the
1842 host system. Instead, you must first install one of the locale packages
1843 available with Guix and then define the @env{GUIX_LOCPATH} environment
1847 $ guix install glibc-locales
1848 $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
1851 Note that the @code{glibc-locales} package contains data for all the
1852 locales supported by the GNU@tie{}libc and weighs in at around
1853 917@tie{}MiB@. Alternatively, the @code{glibc-utf8-locales} is smaller but
1854 limited to a few UTF-8 locales.
1856 The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
1857 (@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
1858 Manual}). There are two important differences though:
1862 @env{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
1863 provided by foreign distros. Thus, using @env{GUIX_LOCPATH} allows you
1864 to make sure the programs of the foreign distro will not end up loading
1865 incompatible locale data.
1868 libc suffixes each entry of @env{GUIX_LOCPATH} with @code{/X.Y}, where
1869 @code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
1870 should your Guix profile contain a mixture of programs linked against
1871 different libc version, each libc version will only try to load locale
1872 data in the right format.
1875 This is important because the locale data format used by different libc
1876 versions may be incompatible.
1878 @subsection Name Service Switch
1880 @cindex name service switch, glibc
1881 @cindex NSS (name service switch), glibc
1882 @cindex nscd (name service caching daemon)
1883 @cindex name service caching daemon (nscd)
1884 When using Guix on a foreign distro, we @emph{strongly recommend} that
1885 the system run the GNU C library's @dfn{name service cache daemon},
1886 @command{nscd}, which should be listening on the
1887 @file{/var/run/nscd/socket} socket. Failing to do that, applications
1888 installed with Guix may fail to look up host names or user accounts, or
1889 may even crash. The next paragraphs explain why.
1891 @cindex @file{nsswitch.conf}
1892 The GNU C library implements a @dfn{name service switch} (NSS), which is
1893 an extensible mechanism for ``name lookups'' in general: host name
1894 resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
1895 The GNU C Library Reference Manual}).
1897 @cindex Network information service (NIS)
1898 @cindex NIS (Network information service)
1899 Being extensible, the NSS supports @dfn{plugins}, which provide new name
1900 lookup implementations: for example, the @code{nss-mdns} plugin allow
1901 resolution of @code{.local} host names, the @code{nis} plugin allows
1902 user account lookup using the Network information service (NIS), and so
1903 on. These extra ``lookup services'' are configured system-wide in
1904 @file{/etc/nsswitch.conf}, and all the programs running on the system
1905 honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
1908 When they perform a name lookup---for instance by calling the
1909 @code{getaddrinfo} function in C---applications first try to connect to
1910 the nscd; on success, nscd performs name lookups on their behalf. If
1911 the nscd is not running, then they perform the name lookup by
1912 themselves, by loading the name lookup services into their own address
1913 space and running it. These name lookup services---the
1914 @file{libnss_*.so} files---are @code{dlopen}'d, but they may come from
1915 the host system's C library, rather than from the C library the
1916 application is linked against (the C library coming from Guix).
1918 And this is where the problem is: if your application is linked against
1919 Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
1920 another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
1921 likely crash or have its name lookups fail unexpectedly.
1923 Running @command{nscd} on the system, among other advantages, eliminates
1924 this binary incompatibility problem because those @code{libnss_*.so}
1925 files are loaded in the @command{nscd} process, not in applications
1928 @subsection X11 Fonts
1931 The majority of graphical applications use Fontconfig to locate and load
1932 fonts and perform X11-client-side rendering. The @code{fontconfig}
1933 package in Guix looks for fonts in @file{$HOME/.guix-profile} by
1934 default. Thus, to allow graphical applications installed with Guix to
1935 display fonts, you have to install fonts with Guix as well. Essential
1936 font packages include @code{font-ghostscript}, @code{font-dejavu}, and
1937 @code{font-gnu-freefont}.
1939 @cindex @code{fc-cache}
1941 Once you have installed or removed fonts, or when you notice an
1942 application that does not find fonts, you may need to install Fontconfig
1943 and to force an update of its font cache by running:
1946 guix install fontconfig
1950 To display text written in Chinese languages, Japanese, or Korean in
1951 graphical applications, consider installing
1952 @code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
1953 has multiple outputs, one per language family (@pxref{Packages with
1954 Multiple Outputs}). For instance, the following command installs fonts
1955 for Chinese languages:
1958 guix install font-adobe-source-han-sans:cn
1961 @cindex @code{xterm}
1962 Older programs such as @command{xterm} do not use Fontconfig and instead
1963 rely on server-side font rendering. Such programs require to specify a
1964 full name of a font using XLFD (X Logical Font Description), like this:
1967 -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
1970 To be able to use such full names for the TrueType fonts installed in
1971 your Guix profile, you need to extend the font path of the X server:
1973 @c Note: 'xset' does not accept symlinks so the trick below arranges to
1974 @c get at the real directory. See <https://bugs.gnu.org/30655>.
1976 xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))
1979 @cindex @code{xlsfonts}
1980 After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
1981 to make sure your TrueType fonts are listed there.
1984 @subsection X.509 Certificates
1986 @cindex @code{nss-certs}
1987 The @code{nss-certs} package provides X.509 certificates, which allow
1988 programs to authenticate Web servers accessed over HTTPS.
1990 When using Guix on a foreign distro, you can install this package and
1991 define the relevant environment variables so that packages know where to
1992 look for certificates. @xref{X.509 Certificates}, for detailed
1995 @subsection Emacs Packages
1997 @cindex @code{emacs}
1998 When you install Emacs packages with Guix, the Elisp files are placed
1999 under the @file{share/emacs/site-lisp/} directory of the profile in
2000 which they are installed. The Elisp libraries are made available to
2001 Emacs through the @env{EMACSLOADPATH} environment variable, which is
2002 set when installing Emacs itself.
2004 Additionally, autoload definitions are automatically evaluated at the
2005 initialization of Emacs, by the Guix-specific
2006 @code{guix-emacs-autoload-packages} procedure. If, for some reason, you
2007 want to avoid auto-loading the Emacs packages installed with Guix, you
2008 can do so by running Emacs with the @option{--no-site-file} option
2009 (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
2012 @node Upgrading Guix
2013 @section Upgrading Guix
2015 @cindex Upgrading Guix, on a foreign distro
2017 To upgrade Guix, run:
2023 @xref{Invoking guix pull}, for more information.
2025 @cindex upgrading Guix for the root user, on a foreign distro
2026 @cindex upgrading the Guix daemon, on a foreign distro
2027 @cindex @command{guix pull} for the root user, on a foreign distro
2029 On a foreign distro, you can upgrade the build daemon by running:
2036 followed by (assuming your distro uses the systemd service management
2040 systemctl restart guix-daemon.service
2043 On Guix System, upgrading the daemon is achieved by reconfiguring the
2044 system (@pxref{Invoking guix system, @code{guix system reconfigure}}).
2048 @c *********************************************************************
2049 @node System Installation
2050 @chapter System Installation
2052 @cindex installing Guix System
2053 @cindex Guix System, installation
2054 This section explains how to install Guix System
2055 on a machine. Guix, as a package manager, can
2056 also be installed on top of a running GNU/Linux system,
2057 @pxref{Installation}.
2061 @c This paragraph is for people reading this from tty2 of the
2062 @c installation image.
2063 You are reading this documentation with an Info reader. For details on
2064 how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
2065 link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
2066 Info}. Hit @kbd{l} afterwards to come back here.
2068 Alternatively, run @command{info info} in another tty to keep the manual
2074 * Limitations:: What you can expect.
2075 * Hardware Considerations:: Supported hardware.
2076 * USB Stick and DVD Installation:: Preparing the installation medium.
2077 * Preparing for Installation:: Networking, partitioning, etc.
2078 * Guided Graphical Installation:: Easy graphical installation.
2079 * Manual Installation:: Manual installation for wizards.
2080 * After System Installation:: When installation succeeded.
2081 * Installing Guix in a VM:: Guix System playground.
2082 * Building the Installation Image:: How this comes to be.
2086 @section Limitations
2088 We consider Guix System to be ready for a wide range of ``desktop'' and server
2089 use cases. The reliability guarantees it provides---transactional upgrades
2090 and rollbacks, reproducibility---make it a solid foundation.
2092 Nevertheless, before you proceed with the installation, be aware of the
2093 following noteworthy limitations applicable to version @value{VERSION}:
2097 More and more system services are provided (@pxref{Services}), but some
2101 GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
2102 as well as a number of X11 window managers. However, KDE is currently
2106 More than a disclaimer, this is an invitation to report issues (and success
2107 stories!), and to join us in improving it. @xref{Contributing}, for more
2111 @node Hardware Considerations
2112 @section Hardware Considerations
2114 @cindex hardware support on Guix System
2115 GNU@tie{}Guix focuses on respecting the user's computing freedom. It
2116 builds around the kernel Linux-libre, which means that only hardware for
2117 which free software drivers and firmware exist is supported. Nowadays,
2118 a wide range of off-the-shelf hardware is supported on
2119 GNU/Linux-libre---from keyboards to graphics cards to scanners and
2120 Ethernet controllers. Unfortunately, there are still areas where
2121 hardware vendors deny users control over their own computing, and such
2122 hardware is not supported on Guix System.
2124 @cindex WiFi, hardware support
2125 One of the main areas where free drivers or firmware are lacking is WiFi
2126 devices. WiFi devices known to work include those using Atheros chips
2127 (AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
2128 driver, and those using Broadcom/AirForce chips (BCM43xx with
2129 Wireless-Core Revision 5), which corresponds to the @code{b43-open}
2130 Linux-libre driver. Free firmware exists for both and is available
2131 out-of-the-box on Guix System, as part of @code{%base-firmware}
2132 (@pxref{operating-system Reference, @code{firmware}}).
2134 @cindex RYF, Respects Your Freedom
2135 The @uref{https://www.fsf.org/, Free Software Foundation} runs
2136 @uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
2137 certification program for hardware products that respect your freedom
2138 and your privacy and ensure that you have control over your device. We
2139 encourage you to check the list of RYF-certified devices.
2141 Another useful resource is the @uref{https://www.h-node.org/, H-Node}
2142 web site. It contains a catalog of hardware devices with information
2143 about their support in GNU/Linux.
2146 @node USB Stick and DVD Installation
2147 @section USB Stick and DVD Installation
2149 An ISO-9660 installation image that can be written to a USB stick or
2150 burnt to a DVD can be downloaded from
2151 @indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso},
2152 where you can replace @code{x86_64-linux} with one of:
2156 for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
2159 for a 32-bit GNU/Linux system on Intel-compatible CPUs.
2162 @c start duplication of authentication part from ``Binary Installation''
2163 Make sure to download the associated @file{.sig} file and to verify the
2164 authenticity of the image against it, along these lines:
2167 $ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
2168 $ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
2171 If that command fails because you do not have the required public key,
2172 then run this command to import it:
2175 $ wget @value{OPENPGP-SIGNING-KEY-URL} \
2176 -qO - | gpg --import -
2180 and rerun the @code{gpg --verify} command.
2182 Take note that a warning like ``This key is not certified with a trusted
2183 signature!'' is normal.
2187 This image contains the tools necessary for an installation.
2188 It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
2190 @unnumberedsubsec Copying to a USB Stick
2192 Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
2193 its device name. Assuming that the USB stick is known as @file{/dev/sdX},
2194 copy the image with:
2197 dd if=guix-system-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX status=progress
2201 Access to @file{/dev/sdX} usually requires root privileges.
2203 @unnumberedsubsec Burning on a DVD
2205 Insert a blank DVD into your machine, and determine
2206 its device name. Assuming that the DVD drive is known as @file{/dev/srX},
2207 copy the image with:
2210 growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.x86_64-linux.iso
2213 Access to @file{/dev/srX} usually requires root privileges.
2215 @unnumberedsubsec Booting
2217 Once this is done, you should be able to reboot the system and boot from
2218 the USB stick or DVD@. The latter usually requires you to get in the
2219 BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
2220 In order to boot from Libreboot, switch to the command mode by pressing
2221 the @kbd{c} key and type @command{search_grub usb}.
2223 @xref{Installing Guix in a VM}, if, instead, you would like to install
2224 Guix System in a virtual machine (VM).
2227 @node Preparing for Installation
2228 @section Preparing for Installation
2230 Once you have booted, you can use the guided graphical installer, which makes
2231 it easy to get started (@pxref{Guided Graphical Installation}). Alternatively,
2232 if you are already familiar with GNU/Linux and if you want more control than
2233 what the graphical installer provides, you can choose the ``manual''
2234 installation process (@pxref{Manual Installation}).
2236 The graphical installer is available on TTY1. You can obtain root shells on
2237 TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2 shows
2238 this documentation and you can reach it with @kbd{ctrl-alt-f2}. Documentation
2239 is browsable using the Info reader commands (@pxref{Top,,, info-stnd,
2240 Stand-alone GNU Info}). The installation system runs the GPM mouse daemon,
2241 which allows you to select text with the left mouse button and to paste it
2242 with the middle button.
2245 Installation requires access to the Internet so that any missing
2246 dependencies of your system configuration can be downloaded. See the
2247 ``Networking'' section below.
2250 @node Guided Graphical Installation
2251 @section Guided Graphical Installation
2253 The graphical installer is a text-based user interface. It will guide you,
2254 with dialog boxes, through the steps needed to install GNU@tie{}Guix System.
2256 The first dialog boxes allow you to set up the system as you use it during the
2257 installation: you can choose the language, keyboard layout, and set up
2258 networking, which will be used during the installation. The image below shows
2259 the networking dialog.
2261 @image{images/installer-network,5in,, networking setup with the graphical installer}
2263 Later steps allow you to partition your hard disk, as shown in the image
2264 below, to choose whether or not to use encrypted file systems, to enter the
2265 host name and root password, and to create an additional account, among other
2268 @image{images/installer-partitions,5in,, partitioning with the graphical installer}
2270 Note that, at any time, the installer allows you to exit the current
2271 installation step and resume at a previous step, as show in the image below.
2273 @image{images/installer-resume,5in,, resuming the installation process}
2275 Once you're done, the installer produces an operating system configuration and
2276 displays it (@pxref{Using the Configuration System}). At that point you can
2277 hit ``OK'' and installation will proceed. On success, you can reboot into the
2278 new system and enjoy. @xref{After System Installation}, for what's next!
2281 @node Manual Installation
2282 @section Manual Installation
2284 This section describes how you would ``manually'' install GNU@tie{}Guix System
2285 on your machine. This option requires familiarity with GNU/Linux, with the
2286 shell, and with common administration tools. If you think this is not for
2287 you, consider using the guided graphical installer (@pxref{Guided Graphical
2290 The installation system provides root shells on TTYs 3 to 6; press
2291 @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them. It includes
2292 many common tools needed to install the system. But it is also a full-blown
2293 Guix System, which means that you can install additional packages, should you
2294 need it, using @command{guix package} (@pxref{Invoking guix package}).
2297 * Keyboard Layout and Networking and Partitioning:: Initial setup.
2298 * Proceeding with the Installation:: Installing.
2301 @node Keyboard Layout and Networking and Partitioning
2302 @subsection Keyboard Layout, Networking, and Partitioning
2304 Before you can install the system, you may want to adjust the keyboard layout,
2305 set up networking, and partition your target hard disk. This section will
2306 guide you through this.
2308 @subsubsection Keyboard Layout
2310 @cindex keyboard layout
2311 The installation image uses the US qwerty keyboard layout. If you want
2312 to change it, you can use the @command{loadkeys} command. For example,
2313 the following command selects the Dvorak keyboard layout:
2319 See the files under @file{/run/current-system/profile/share/keymaps} for
2320 a list of available keyboard layouts. Run @command{man loadkeys} for
2323 @subsubsection Networking
2325 Run the following command to see what your network interfaces are called:
2332 @dots{} or, using the GNU/Linux-specific @command{ip} command:
2338 @c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
2339 Wired interfaces have a name starting with @samp{e}; for example, the
2340 interface corresponding to the first on-board Ethernet controller is
2341 called @samp{eno1}. Wireless interfaces have a name starting with
2342 @samp{w}, like @samp{w1p2s0}.
2345 @item Wired connection
2346 To configure a wired network run the following command, substituting
2347 @var{interface} with the name of the wired interface you want to use.
2350 ifconfig @var{interface} up
2354 @dots{} or, using the GNU/Linux-specific @command{ip} command:
2357 ip link set @var{interface} up
2360 @item Wireless connection
2363 To configure wireless networking, you can create a configuration file
2364 for the @command{wpa_supplicant} configuration tool (its location is not
2365 important) using one of the available text editors such as
2369 nano wpa_supplicant.conf
2372 As an example, the following stanza can go to this file and will work
2373 for many wireless networks, provided you give the actual SSID and
2374 passphrase for the network you are connecting to:
2378 ssid="@var{my-ssid}"
2380 psk="the network's secret passphrase"
2384 Start the wireless service and run it in the background with the
2385 following command (substitute @var{interface} with the name of the
2386 network interface you want to use):
2389 wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
2392 Run @command{man wpa_supplicant} for more information.
2396 At this point, you need to acquire an IP address. On a network where IP
2397 addresses are automatically assigned @i{via} DHCP, you can run:
2400 dhclient -v @var{interface}
2403 Try to ping a server to see if networking is up and running:
2409 Setting up network access is almost always a requirement because the
2410 image does not contain all the software and tools that may be needed.
2412 @cindex proxy, during system installation
2413 If you need HTTP and HTTPS access to go through a proxy, run the
2417 herd set-http-proxy guix-daemon @var{URL}
2421 where @var{URL} is the proxy URL, for example
2422 @code{http://example.org:8118}.
2424 @cindex installing over SSH
2425 If you want to, you can continue the installation remotely by starting
2429 herd start ssh-daemon
2432 Make sure to either set a password with @command{passwd}, or configure
2433 OpenSSH public key authentication before logging in.
2435 @subsubsection Disk Partitioning
2437 Unless this has already been done, the next step is to partition, and
2438 then format the target partition(s).
2440 The installation image includes several partitioning tools, including
2441 Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
2442 @command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
2443 the partition layout you want:
2449 If your disk uses the GUID Partition Table (GPT) format and you plan to
2450 install BIOS-based GRUB (which is the default), make sure a BIOS Boot
2451 Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
2454 @cindex EFI, installation
2455 @cindex UEFI, installation
2456 @cindex ESP, EFI system partition
2457 If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
2458 (ESP) is required. This partition can be mounted at @file{/boot/efi} for
2459 instance and must have the @code{esp} flag set. E.g., for @command{parted}:
2462 parted /dev/sda set 1 esp on
2466 @vindex grub-bootloader
2467 @vindex grub-efi-bootloader
2468 Unsure whether to use EFI- or BIOS-based GRUB? If the directory
2469 @file{/sys/firmware/efi} exists in the installation image, then you should
2470 probably perform an EFI installation, using @code{grub-efi-bootloader}.
2471 Otherwise you should use the BIOS-based GRUB, known as
2472 @code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on
2476 Once you are done partitioning the target hard disk drive, you have to
2477 create a file system on the relevant partition(s)@footnote{Currently
2478 Guix System only supports ext4, btrfs, JFS, F2FS, and XFS file systems. In
2479 particular, code that reads file system UUIDs and labels only works for these
2480 file system types.}. For the ESP, if you have one and assuming it is
2481 @file{/dev/sda1}, run:
2484 mkfs.fat -F32 /dev/sda1
2487 For the root file system, ext4 is the most widely used format. Other
2488 file systems, such as Btrfs, support compression, which is reported to
2489 nicely complement file deduplication that the daemon performs
2490 independently of the file system (@pxref{Invoking guix-daemon,
2493 Preferably, assign file systems a label so that you can easily and
2494 reliably refer to them in @code{file-system} declarations (@pxref{File
2495 Systems}). This is typically done using the @code{-L} option of
2496 @command{mkfs.ext4} and related commands. So, assuming the target root
2497 partition lives at @file{/dev/sda2}, a file system with the label
2498 @code{my-root} can be created with:
2501 mkfs.ext4 -L my-root /dev/sda2
2504 @cindex encrypted disk
2505 If you are instead planning to encrypt the root partition, you can use
2506 the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
2507 @uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
2508 @code{man cryptsetup}} for more information).
2511 Note that GRUB can unlock LUKS2 devices since version 2.06, but only
2512 supports the PBKDF2 key derivation function, which is not the default
2513 for @command{cryptsetup luksFormat}. You can check which key derivation
2514 function is being used by a device by running @command{cryptsetup
2515 luksDump @var{device}}, and looking for the PBKDF field of your
2519 Assuming you want to store the root partition on @file{/dev/sda2}, the
2520 command sequence to format it as a LUKS2 partition would be along these
2524 cryptsetup luksFormat --type luks2 --pbkdf pbkdf2 /dev/sda2
2525 cryptsetup open /dev/sda2 my-partition
2526 mkfs.ext4 -L my-root /dev/mapper/my-partition
2529 Once that is done, mount the target file system under @file{/mnt}
2530 with a command like (again, assuming @code{my-root} is the label of the
2534 mount LABEL=my-root /mnt
2537 Also mount any other file systems you would like to use on the target
2538 system relative to this path. If you have opted for @file{/boot/efi} as an
2539 EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is
2540 found by @code{guix system init} afterwards.
2542 Finally, if you plan to use one or more swap partitions (@pxref{Swap
2543 Space}), make sure to initialize them with @command{mkswap}. Assuming
2544 you have one swap partition on @file{/dev/sda3}, you would run:
2551 Alternatively, you may use a swap file. For example, assuming that in
2552 the new system you want to use the file @file{/swapfile} as a swap file,
2553 you would run@footnote{This example will work for many types of file
2554 systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
2555 btrfs), the required steps may be different. For details, see the
2556 manual pages for @command{mkswap} and @command{swapon}.}:
2559 # This is 10 GiB of swap space. Adjust "count" to change the size.
2560 dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
2561 # For security, make the file readable and writable only by root.
2562 chmod 600 /mnt/swapfile
2563 mkswap /mnt/swapfile
2564 swapon /mnt/swapfile
2567 Note that if you have encrypted the root partition and created a swap
2568 file in its file system as described above, then the encryption also
2569 protects the swap file, just like any other file in that file system.
2571 @node Proceeding with the Installation
2572 @subsection Proceeding with the Installation
2574 With the target partitions ready and the target root mounted on
2575 @file{/mnt}, we're ready to go. First, run:
2578 herd start cow-store /mnt
2581 This makes @file{/gnu/store} copy-on-write, such that packages added to it
2582 during the installation phase are written to the target disk on @file{/mnt}
2583 rather than kept in memory. This is necessary because the first phase of
2584 the @command{guix system init} command (see below) entails downloads or
2585 builds to @file{/gnu/store} which, initially, is an in-memory file system.
2587 Next, you have to edit a file and
2588 provide the declaration of the operating system to be installed. To
2589 that end, the installation system comes with three text editors. We
2590 recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
2591 supports syntax highlighting and parentheses matching; other editors
2592 include mg (an Emacs clone), and
2593 nvi (a clone of the original BSD @command{vi} editor).
2594 We strongly recommend storing that file on the target root file system, say,
2595 as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
2596 configuration file once you have rebooted into the newly-installed system.
2598 @xref{Using the Configuration System}, for an overview of the
2599 configuration file. The example configurations discussed in that
2600 section are available under @file{/etc/configuration} in the
2601 installation image. Thus, to get started with a system configuration
2602 providing a graphical display server (a ``desktop'' system), you can run
2603 something along these lines:
2607 # cp /etc/configuration/desktop.scm /mnt/etc/config.scm
2608 # nano /mnt/etc/config.scm
2611 You should pay attention to what your configuration file contains, and
2616 Make sure the @code{bootloader-configuration} form refers to the targets
2617 you want to install GRUB on. It should mention @code{grub-bootloader}
2618 if you are installing GRUB in the legacy way, or
2619 @code{grub-efi-bootloader} for newer UEFI systems. For legacy systems,
2620 the @code{targets} field contain the names of the devices, like
2621 @code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
2622 EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
2623 are currently mounted and a @code{file-system} entry is specified in
2627 Be sure that your file system labels match the value of their respective
2628 @code{device} fields in your @code{file-system} configuration, assuming
2629 your @code{file-system} configuration uses the @code{file-system-label}
2630 procedure in its @code{device} field.
2633 If there are encrypted or RAID partitions, make sure to add a
2634 @code{mapped-devices} field to describe them (@pxref{Mapped Devices}).
2637 Once you are done preparing the configuration file, the new system must
2638 be initialized (remember that the target root file system is mounted
2642 guix system init /mnt/etc/config.scm /mnt
2646 This copies all the necessary files and installs GRUB on
2647 @file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For
2648 more information, @pxref{Invoking guix system}. This command may trigger
2649 downloads or builds of missing packages, which can take some time.
2651 Once that command has completed---and hopefully succeeded!---you can run
2652 @command{reboot} and boot into the new system. The @code{root} password
2653 in the new system is initially empty; other users' passwords need to be
2654 initialized by running the @command{passwd} command as @code{root},
2655 unless your configuration specifies otherwise
2656 (@pxref{user-account-password, user account passwords}).
2657 @xref{After System Installation}, for what's next!
2660 @node After System Installation
2661 @section After System Installation
2663 Success, you've now booted into Guix System! From then on, you can update the
2664 system whenever you want by running, say:
2668 sudo guix system reconfigure /etc/config.scm
2672 This builds a new system generation with the latest packages and services
2673 (@pxref{Invoking guix system}). We recommend doing that regularly so that
2674 your system includes the latest security updates (@pxref{Security Updates}).
2676 @c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
2678 @cindex sudo vs. @command{guix pull}
2679 Note that @command{sudo guix} runs your user's @command{guix} command and
2680 @emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To
2681 explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
2683 The difference matters here, because @command{guix pull} updates
2684 the @command{guix} command and package definitions only for the user it is run
2685 as. This means that if you choose to use @command{guix system reconfigure} in
2686 root's login shell, you'll need to @command{guix pull} separately.
2689 Now, @pxref{Getting Started}, and
2690 join us on @code{#guix} on the Libera Chat IRC network or on
2691 @email{guix-devel@@gnu.org} to share your experience!
2694 @node Installing Guix in a VM
2695 @section Installing Guix in a Virtual Machine
2697 @cindex virtual machine, Guix System installation
2698 @cindex virtual private server (VPS)
2699 @cindex VPS (virtual private server)
2700 If you'd like to install Guix System in a virtual machine (VM) or on a
2701 virtual private server (VPS) rather than on your beloved machine, this
2704 To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a
2705 disk image, follow these steps:
2709 First, retrieve and decompress the Guix system installation image as
2710 described previously (@pxref{USB Stick and DVD Installation}).
2713 Create a disk image that will hold the installed system. To make a
2714 qcow2-formatted disk image, use the @command{qemu-img} command:
2717 qemu-img create -f qcow2 guix-system.img 50G
2720 The resulting file will be much smaller than 50 GB (typically less than
2721 1 MB), but it will grow as the virtualized storage device is filled up.
2724 Boot the USB installation image in an VM:
2727 qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
2728 -nic user,model=virtio-net-pci -boot menu=on,order=d \
2729 -drive file=guix-system.img \
2730 -drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso
2733 @code{-enable-kvm} is optional, but significantly improves performance,
2734 @pxref{Running Guix in a VM}.
2737 You're now root in the VM, proceed with the installation process.
2738 @xref{Preparing for Installation}, and follow the instructions.
2741 Once installation is complete, you can boot the system that's on your
2742 @file{guix-system.img} image. @xref{Running Guix in a VM}, for how to do
2745 @node Building the Installation Image
2746 @section Building the Installation Image
2748 @cindex installation image
2749 The installation image described above was built using the @command{guix
2750 system} command, specifically:
2753 guix system image -t iso9660 gnu/system/install.scm
2756 Have a look at @file{gnu/system/install.scm} in the source tree,
2757 and see also @ref{Invoking guix system} for more information
2758 about the installation image.
2760 @section Building the Installation Image for ARM Boards
2762 Many ARM boards require a specific variant of the
2763 @uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
2765 If you build a disk image and the bootloader is not available otherwise
2766 (on another boot drive etc), it's advisable to build an image that
2767 includes the bootloader, specifically:
2770 guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
2773 @code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
2774 board, a list of possible boards will be printed.
2776 @c *********************************************************************
2777 @node Getting Started
2778 @chapter Getting Started
2780 Presumably, you've reached this section because either you have
2781 installed Guix on top of another distribution (@pxref{Installation}), or
2782 you've installed the standalone Guix System (@pxref{System
2783 Installation}). It's time for you to get started using Guix and this
2784 section aims to help you do that and give you a feel of what it's like.
2786 Guix is about installing software, so probably the first thing you'll
2787 want to do is to actually look for software. Let's say you're looking
2788 for a text editor, you can run:
2791 guix search text editor
2794 This command shows you a number of matching @dfn{packages}, each time
2795 showing the package's name, version, a description, and additional info.
2796 Once you've found out the one you want to use, let's say Emacs (ah ha!),
2797 you can go ahead and install it (run this command as a regular user,
2798 @emph{no need for root privileges}!):
2805 You've installed your first package, congrats! The package is now
2806 visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
2807 profile is a directory containing installed packages.
2808 In the process, you've
2809 probably noticed that Guix downloaded pre-built binaries; or, if you
2810 explicitly chose to @emph{not} use pre-built binaries, then probably
2811 Guix is still building software (@pxref{Substitutes}, for more info).
2813 Unless you're using Guix System, the @command{guix install} command must
2814 have printed this hint:
2817 hint: Consider setting the necessary environment variables by running:
2819 GUIX_PROFILE="$HOME/.guix-profile"
2820 . "$GUIX_PROFILE/etc/profile"
2822 Alternately, see `guix package --search-paths -p "$HOME/.guix-profile"'.
2825 Indeed, you must now tell your shell where @command{emacs} and other
2826 programs installed with Guix are to be found. Pasting the two lines
2827 above will do just that: it will add
2828 @code{$HOME/.guix-profile/bin}---which is where the installed package
2829 is---to the @code{PATH} environment variable. You can paste these two
2830 lines in your shell so they take effect right away, but more importantly
2831 you should add them to @file{~/.bash_profile} (or equivalent file if you
2832 do not use Bash) so that environment variables are set next time you
2833 spawn a shell. You only need to do this once and other search paths
2834 environment variables will be taken care of similarly---e.g., if you
2835 eventually install @code{python} and Python libraries,
2836 @env{GUIX_PYTHONPATH} will be defined.
2838 You can go on installing packages at your will. To list installed
2842 guix package --list-installed
2845 To remove a package, you would unsurprisingly run @command{guix remove}.
2846 A distinguishing feature is the ability to @dfn{roll back} any operation
2847 you made---installation, removal, upgrade---by simply typing:
2850 guix package --roll-back
2853 This is because each operation is in fact a @dfn{transaction} that
2854 creates a new @dfn{generation}. These generations and the difference
2855 between them can be displayed by running:
2858 guix package --list-generations
2861 Now you know the basics of package management!
2863 @quotation Going further
2864 @xref{Package Management}, for more about package management. You may
2865 like @dfn{declarative} package management with @command{guix package
2866 --manifest}, managing separate @dfn{profiles} with @option{--profile},
2867 deleting old generations, collecting garbage, and other nifty features
2868 that will come in handy as you become more familiar with Guix. If you
2869 are a developer, @pxref{Development} for additional tools. And if
2870 you're curious, @pxref{Features}, to peek under the hood.
2873 Once you've installed a set of packages, you will want to periodically
2874 @emph{upgrade} them to the latest and greatest version. To do that, you
2875 will first pull the latest revision of Guix and its package collection:
2881 The end result is a new @command{guix} command, under
2882 @file{~/.config/guix/current/bin}. Unless you're on Guix System, the
2883 first time you run @command{guix pull}, be sure to follow the hint that
2884 the command prints and, similar to what we saw above, paste these two
2885 lines in your terminal and @file{.bash_profile}:
2888 GUIX_PROFILE="$HOME/.config/guix/current"
2889 . "$GUIX_PROFILE/etc/profile"
2893 You must also instruct your shell to point to this new @command{guix}:
2899 At this point, you're running a brand new Guix. You can thus go ahead
2900 and actually upgrade all the packages you previously installed:
2906 As you run this command, you will see that binaries are downloaded (or
2907 perhaps some packages are built), and eventually you end up with the
2908 upgraded packages. Should one of these upgraded packages not be to your
2909 liking, remember you can always roll back!
2911 You can display the exact revision of Guix you're currently using by
2918 The information it displays is @emph{all it takes to reproduce the exact
2919 same Guix}, be it at a different point in time or on a different
2922 @quotation Going further
2923 @xref{Invoking guix pull}, for more information. @xref{Channels}, on
2924 how to specify additional @dfn{channels} to pull packages from, how to
2925 replicate Guix, and more. You may also find @command{time-machine}
2926 handy (@pxref{Invoking guix time-machine}).
2929 If you installed Guix System, one of the first things you'll want to do
2930 is to upgrade your system. Once you've run @command{guix pull} to get
2931 the latest Guix, you can upgrade the system like this:
2934 sudo guix system reconfigure /etc/config.scm
2937 Upon completion, the system runs the latest versions of its software
2938 packages. When you eventually reboot, you'll notice a sub-menu in the
2939 bootloader that reads ``Old system generations'': it's what allows you
2940 to boot @emph{an older generation of your system}, should the latest
2941 generation be ``broken'' or otherwise unsatisfying. Just like for
2942 packages, you can always @emph{roll back} to a previous generation
2943 @emph{of the whole system}:
2946 sudo guix system roll-back
2949 There are many things you'll probably want to tweak on your system:
2950 adding new user accounts, adding new system services, fiddling with the
2951 configuration of those services, etc. The system configuration is
2952 @emph{entirely} described in the @file{/etc/config.scm} file.
2953 @xref{Using the Configuration System}, to learn how to change it.
2955 Now you know enough to get started!
2957 @quotation Resources
2958 The rest of this manual provides a reference for all things Guix. Here
2959 are some additional resources you may find useful:
2963 @xref{Top,,, guix-cookbook, The GNU Guix Cookbook}, for a list of
2964 ``how-to'' style of recipes for a variety of applications.
2967 The @uref{https://guix.gnu.org/guix-refcard.pdf, GNU Guix Reference
2968 Card} lists in two pages most of the commands and options you'll ever
2972 The web site contains @uref{https://guix.gnu.org/en/videos/,
2973 instructional videos} covering topics such as everyday use of Guix, how
2974 to get help, and how to become a contributor.
2977 @xref{Documentation}, to learn how to access documentation on your
2981 We hope you will enjoy Guix as much as the community enjoys building it!
2984 @c *********************************************************************
2985 @node Package Management
2986 @chapter Package Management
2989 The purpose of GNU Guix is to allow users to easily install, upgrade, and
2990 remove software packages, without having to know about their build
2991 procedures or dependencies. Guix also goes beyond this obvious set of
2994 This chapter describes the main features of Guix, as well as the
2995 package management tools it provides. Along with the command-line
2996 interface described below (@pxref{Invoking guix package, @code{guix
2997 package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
2998 emacs-guix, The Emacs-Guix Reference Manual}), after installing
2999 @code{emacs-guix} package (run @kbd{M-x guix-help} command to start
3003 guix install emacs-guix
3007 * Features:: How Guix will make your life brighter.
3008 * Invoking guix package:: Package installation, removal, etc.
3009 * Substitutes:: Downloading pre-built binaries.
3010 * Packages with Multiple Outputs:: Single source package, multiple outputs.
3011 * Invoking guix gc:: Running the garbage collector.
3012 * Invoking guix pull:: Fetching the latest Guix and distribution.
3013 * Invoking guix time-machine:: Running an older revision of Guix.
3014 * Inferiors:: Interacting with another revision of Guix.
3015 * Invoking guix describe:: Display information about your Guix revision.
3016 * Invoking guix archive:: Exporting and importing store files.
3022 Here we assume you've already made your first steps with Guix
3023 (@pxref{Getting Started}) and would like to get an overview about what's
3024 going on under the hood.
3026 When using Guix, each package ends up in the @dfn{package store}, in its
3027 own directory---something that resembles
3028 @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
3030 Instead of referring to these directories, users have their own
3031 @dfn{profile}, which points to the packages that they actually want to
3032 use. These profiles are stored within each user's home directory, at
3033 @code{$HOME/.guix-profile}.
3035 For example, @code{alice} installs GCC 4.7.2. As a result,
3036 @file{/home/alice/.guix-profile/bin/gcc} points to
3037 @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
3038 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
3039 simply continues to point to
3040 @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
3041 coexist on the same system without any interference.
3043 The @command{guix package} command is the central tool to manage
3044 packages (@pxref{Invoking guix package}). It operates on the per-user
3045 profiles, and can be used @emph{with normal user privileges}.
3047 @cindex transactions
3048 The command provides the obvious install, remove, and upgrade
3049 operations. Each invocation is actually a @emph{transaction}: either
3050 the specified operation succeeds, or nothing happens. Thus, if the
3051 @command{guix package} process is terminated during the transaction,
3052 or if a power outage occurs during the transaction, then the user's
3053 profile remains in its previous state, and remains usable.
3055 In addition, any package transaction may be @emph{rolled back}. So, if,
3056 for example, an upgrade installs a new version of a package that turns
3057 out to have a serious bug, users may roll back to the previous instance
3058 of their profile, which was known to work well. Similarly, the global
3059 system configuration on Guix is subject to
3060 transactional upgrades and roll-back
3061 (@pxref{Using the Configuration System}).
3063 All packages in the package store may be @emph{garbage-collected}.
3064 Guix can determine which packages are still referenced by user
3065 profiles, and remove those that are provably no longer referenced
3066 (@pxref{Invoking guix gc}). Users may also explicitly remove old
3067 generations of their profile so that the packages they refer to can be
3070 @cindex reproducibility
3071 @cindex reproducible builds
3072 Guix takes a @dfn{purely functional} approach to package
3073 management, as described in the introduction (@pxref{Introduction}).
3074 Each @file{/gnu/store} package directory name contains a hash of all the
3075 inputs that were used to build that package---compiler, libraries, build
3076 scripts, etc. This direct correspondence allows users to make sure a
3077 given package installation matches the current state of their
3078 distribution. It also helps maximize @dfn{build reproducibility}:
3079 thanks to the isolated build environments that are used, a given build
3080 is likely to yield bit-identical files when performed on different
3081 machines (@pxref{Invoking guix-daemon, container}).
3084 This foundation allows Guix to support @dfn{transparent binary/source
3085 deployment}. When a pre-built binary for a @file{/gnu/store} item is
3086 available from an external source---a @dfn{substitute}, Guix just
3087 downloads it and unpacks it;
3088 otherwise, it builds the package from source, locally
3089 (@pxref{Substitutes}). Because build results are usually bit-for-bit
3090 reproducible, users do not have to trust servers that provide
3091 substitutes: they can force a local build and @emph{challenge} providers
3092 (@pxref{Invoking guix challenge}).
3094 Control over the build environment is a feature that is also useful for
3095 developers. The @command{guix shell} command allows developers of
3096 a package to quickly set up the right development environment for their
3097 package, without having to manually install the dependencies of the
3098 package into their profile (@pxref{Invoking guix shell}).
3100 @cindex replication, of software environments
3101 @cindex provenance tracking, of software artifacts
3102 All of Guix and its package definitions is version-controlled, and
3103 @command{guix pull} allows you to ``travel in time'' on the history of Guix
3104 itself (@pxref{Invoking guix pull}). This makes it possible to replicate a
3105 Guix instance on a different machine or at a later point in time, which in
3106 turn allows you to @emph{replicate complete software environments}, while
3107 retaining precise @dfn{provenance tracking} of the software.
3109 @node Invoking guix package
3110 @section Invoking @command{guix package}
3112 @cindex installing packages
3113 @cindex removing packages
3114 @cindex package installation
3115 @cindex package removal
3117 The @command{guix package} command is the tool that allows users to
3118 install, upgrade, and remove packages, as well as rolling back to
3119 previous configurations. These operations work on a user
3120 @dfn{profile}---a directory of installed packages. Each user has a
3121 default profile in @file{$HOME/.guix-profile}.
3122 The command operates only on the user's own profile,
3123 and works with normal user privileges (@pxref{Features}). Its syntax
3127 guix package @var{options}
3130 @cindex transactions
3131 Primarily, @var{options} specifies the operations to be performed during
3132 the transaction. Upon completion, a new profile is created, but
3133 previous @dfn{generations} of the profile remain available, should the user
3136 For example, to remove @code{lua} and install @code{guile} and
3137 @code{guile-cairo} in a single transaction:
3140 guix package -r lua -i guile guile-cairo
3143 @cindex aliases, for @command{guix package}
3144 For your convenience, we also provide the following aliases:
3148 @command{guix search} is an alias for @command{guix package -s},
3150 @command{guix install} is an alias for @command{guix package -i},
3152 @command{guix remove} is an alias for @command{guix package -r},
3154 @command{guix upgrade} is an alias for @command{guix package -u},
3156 and @command{guix show} is an alias for @command{guix package --show=}.
3159 These aliases are less expressive than @command{guix package} and provide
3160 fewer options, so in some cases you'll probably want to use @command{guix
3163 @command{guix package} also supports a @dfn{declarative approach}
3164 whereby the user specifies the exact set of packages to be available and
3165 passes it @i{via} the @option{--manifest} option
3166 (@pxref{profile-manifest, @option{--manifest}}).
3169 For each user, a symlink to the user's default profile is automatically
3170 created in @file{$HOME/.guix-profile}. This symlink always points to the
3171 current generation of the user's default profile. Thus, users can add
3172 @file{$HOME/.guix-profile/bin} to their @env{PATH} environment
3173 variable, and so on.
3174 @cindex search paths
3175 If you are not using Guix System, consider adding the
3176 following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
3177 Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
3178 shells get all the right environment variable definitions:
3181 GUIX_PROFILE="$HOME/.guix-profile" ; \
3182 source "$GUIX_PROFILE/etc/profile"
3185 In a multi-user setup, user profiles are stored in a place registered as
3186 a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
3187 to (@pxref{Invoking guix gc}). That directory is normally
3188 @code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
3189 @var{localstatedir} is the value passed to @code{configure} as
3190 @option{--localstatedir}, and @var{user} is the user name. The
3191 @file{per-user} directory is created when @command{guix-daemon} is
3192 started, and the @var{user} sub-directory is created by @command{guix
3195 The @var{options} can be among the following:
3199 @item --install=@var{package} @dots{}
3200 @itemx -i @var{package} @dots{}
3201 Install the specified @var{package}s.
3203 Each @var{package} may specify either a simple package name, such as
3204 @code{guile}, or a package name followed by an at-sign and version number,
3205 such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
3206 case, the newest version prefixed by @code{1.8} is selected).
3208 If no version number is specified, the
3209 newest available version will be selected. In addition, @var{package}
3210 may contain a colon, followed by the name of one of the outputs of the
3211 package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
3212 (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
3213 name (and optionally version) are searched for among the GNU
3214 distribution modules (@pxref{Package Modules}).
3216 @cindex propagated inputs
3217 Sometimes packages have @dfn{propagated inputs}: these are dependencies
3218 that automatically get installed along with the required package
3219 (@pxref{package-propagated-inputs, @code{propagated-inputs} in
3220 @code{package} objects}, for information about propagated inputs in
3221 package definitions).
3223 @anchor{package-cmd-propagated-inputs}
3224 An example is the GNU MPC library: its C header files refer to those of
3225 the GNU MPFR library, which in turn refer to those of the GMP library.
3226 Thus, when installing MPC, the MPFR and GMP libraries also get installed
3227 in the profile; removing MPC also removes MPFR and GMP---unless they had
3228 also been explicitly installed by the user.
3230 Besides, packages sometimes rely on the definition of environment
3231 variables for their search paths (see explanation of
3232 @option{--search-paths} below). Any missing or possibly incorrect
3233 environment variable definitions are reported here.
3235 @item --install-from-expression=@var{exp}
3237 Install the package @var{exp} evaluates to.
3239 @var{exp} must be a Scheme expression that evaluates to a
3240 @code{<package>} object. This option is notably useful to disambiguate
3241 between same-named variants of a package, with expressions such as
3242 @code{(@@ (gnu packages base) guile-final)}.
3244 Note that this option installs the first output of the specified
3245 package, which may be insufficient when needing a specific output of a
3246 multiple-output package.
3248 @item --install-from-file=@var{file}
3249 @itemx -f @var{file}
3250 Install the package that the code within @var{file} evaluates to.
3252 As an example, @var{file} might contain a definition like this
3253 (@pxref{Defining Packages}):
3256 @include package-hello.scm
3259 Developers may find it useful to include such a @file{guix.scm} file
3260 in the root of their project source tree that can be used to test
3261 development snapshots and create reproducible development environments
3262 (@pxref{Invoking guix shell}).
3264 The @var{file} may also contain a JSON representation of one or more
3265 package definitions. Running @code{guix package -f} on
3266 @file{hello.json} with the following contents would result in installing
3267 the package @code{greeter} after building @code{myhello}:
3270 @verbatiminclude package-hello.json
3273 @item --remove=@var{package} @dots{}
3274 @itemx -r @var{package} @dots{}
3275 Remove the specified @var{package}s.
3277 As for @option{--install}, each @var{package} may specify a version number
3278 and/or output name in addition to the package name. For instance,
3279 @samp{-r glibc:debug} would remove the @code{debug} output of
3282 @item --upgrade[=@var{regexp} @dots{}]
3283 @itemx -u [@var{regexp} @dots{}]
3284 @cindex upgrading packages
3285 Upgrade all the installed packages. If one or more @var{regexp}s are
3286 specified, upgrade only installed packages whose name matches a
3287 @var{regexp}. Also see the @option{--do-not-upgrade} option below.
3289 Note that this upgrades package to the latest version of packages found
3290 in the distribution currently installed. To update your distribution,
3291 you should regularly run @command{guix pull} (@pxref{Invoking guix
3294 @cindex package transformations, upgrades
3295 When upgrading, package transformations that were originally applied
3296 when creating the profile are automatically re-applied (@pxref{Package
3297 Transformation Options}). For example, assume you first installed Emacs
3298 from the tip of its development branch with:
3301 guix install emacs-next --with-branch=emacs-next=master
3304 Next time you run @command{guix upgrade}, Guix will again pull the tip
3305 of the Emacs development branch and build @code{emacs-next} from that
3308 Note that transformation options such as @option{--with-branch} and
3309 @option{--with-source} depend on external state; it is up to you to
3310 ensure that they work as expected. You can also discard a
3311 transformations that apply to a package by running:
3314 guix install @var{package}
3317 @item --do-not-upgrade[=@var{regexp} @dots{}]
3318 When used together with the @option{--upgrade} option, do @emph{not}
3319 upgrade any packages whose name matches a @var{regexp}. For example, to
3320 upgrade all packages in the current profile except those containing the
3321 substring ``emacs'':
3324 $ guix package --upgrade . --do-not-upgrade emacs
3327 @item @anchor{profile-manifest}--manifest=@var{file}
3328 @itemx -m @var{file}
3329 @cindex profile declaration
3330 @cindex profile manifest
3331 Create a new generation of the profile from the manifest object
3332 returned by the Scheme code in @var{file}. This option can be repeated
3333 several times, in which case the manifests are concatenated.
3335 This allows you to @emph{declare} the profile's contents rather than
3336 constructing it through a sequence of @option{--install} and similar
3337 commands. The advantage is that @var{file} can be put under version
3338 control, copied to different machines to reproduce the same profile, and
3341 @c FIXME: Add reference to (guix profile) documentation when available.
3342 @var{file} must return a @dfn{manifest} object, which is roughly a list
3345 @findex packages->manifest
3347 (use-package-modules guile emacs)
3352 ;; Use a specific package output.
3353 (list guile-2.0 "debug")))
3356 @findex specifications->manifest
3357 In this example we have to know which modules define the @code{emacs}
3358 and @code{guile-2.0} variables to provide the right
3359 @code{use-package-modules} line, which can be cumbersome. We can
3360 instead provide regular package specifications and let
3361 @code{specifications->manifest} look up the corresponding package
3365 (specifications->manifest
3366 '("emacs" "guile@@2.2" "guile@@2.2:debug"))
3369 @findex package->development-manifest
3370 You might also want to create a manifest for all the dependencies of a
3371 package, rather than the package itself:
3374 (package->development-manifest (specification->package "emacs"))
3377 The example above gives you all the software required to develop Emacs,
3378 similar to what @command{guix environment emacs} provides.
3380 @xref{export-manifest, @option{--export-manifest}}, to learn how to
3381 obtain a manifest file from an existing profile.
3384 @cindex rolling back
3385 @cindex undoing transactions
3386 @cindex transactions, undoing
3387 Roll back to the previous @dfn{generation} of the profile---i.e., undo
3388 the last transaction.
3390 When combined with options such as @option{--install}, roll back occurs
3391 before any other actions.
3393 When rolling back from the first generation that actually contains
3394 installed packages, the profile is made to point to the @dfn{zeroth
3395 generation}, which contains no files apart from its own metadata.
3397 After having rolled back, installing, removing, or upgrading packages
3398 overwrites previous future generations. Thus, the history of the
3399 generations in a profile is always linear.
3401 @item --switch-generation=@var{pattern}
3402 @itemx -S @var{pattern}
3404 Switch to a particular generation defined by @var{pattern}.
3406 @var{pattern} may be either a generation number or a number prefixed
3407 with ``+'' or ``-''. The latter means: move forward/backward by a
3408 specified number of generations. For example, if you want to return to
3409 the latest generation after @option{--roll-back}, use
3410 @option{--switch-generation=+1}.
3412 The difference between @option{--roll-back} and
3413 @option{--switch-generation=-1} is that @option{--switch-generation} will
3414 not make a zeroth generation, so if a specified generation does not
3415 exist, the current generation will not be changed.
3417 @item --search-paths[=@var{kind}]
3418 @cindex search paths
3419 Report environment variable definitions, in Bash syntax, that may be
3420 needed in order to use the set of installed packages. These environment
3421 variables are used to specify @dfn{search paths} for files used by some
3422 of the installed packages.
3424 For example, GCC needs the @env{CPATH} and @env{LIBRARY_PATH}
3425 environment variables to be defined so it can look for headers and
3426 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
3427 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
3428 library are installed in the profile, then @option{--search-paths} will
3429 suggest setting these variables to @file{@var{profile}/include} and
3430 @file{@var{profile}/lib}, respectively.
3432 The typical use case is to define these environment variables in the
3436 $ eval `guix package --search-paths`
3439 @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
3440 meaning that the returned environment variable definitions will either
3441 be exact settings, or prefixes or suffixes of the current value of these
3442 variables. When omitted, @var{kind} defaults to @code{exact}.
3444 This option can also be used to compute the @emph{combined} search paths
3445 of several profiles. Consider this example:
3448 $ guix package -p foo -i guile
3449 $ guix package -p bar -i guile-json
3450 $ guix package -p foo -p bar --search-paths
3453 The last command above reports about the @env{GUILE_LOAD_PATH}
3454 variable, even though, taken individually, neither @file{foo} nor
3455 @file{bar} would lead to that recommendation.
3458 @cindex profile, choosing
3459 @item --profile=@var{profile}
3460 @itemx -p @var{profile}
3461 Use @var{profile} instead of the user's default profile.
3463 @var{profile} must be the name of a file that will be created upon
3464 completion. Concretely, @var{profile} will be a mere symbolic link
3465 (``symlink'') pointing to the actual profile where packages are
3469 $ guix install hello -p ~/code/my-profile
3471 $ ~/code/my-profile/bin/hello
3475 All it takes to get rid of the profile is to remove this symlink and its
3476 siblings that point to specific generations:
3479 $ rm ~/code/my-profile ~/code/my-profile-*-link
3482 @item --list-profiles
3483 List all the user's profiles:
3486 $ guix package --list-profiles
3487 /home/charlie/.guix-profile
3488 /home/charlie/code/my-profile
3489 /home/charlie/code/devel-profile
3490 /home/charlie/tmp/test
3493 When running as root, list all the profiles of all the users.
3495 @cindex collisions, in a profile
3496 @cindex colliding packages in profiles
3497 @cindex profile collisions
3498 @item --allow-collisions
3499 Allow colliding packages in the new profile. Use at your own risk!
3501 By default, @command{guix package} reports as an error @dfn{collisions}
3502 in the profile. Collisions happen when two or more different versions
3503 or variants of a given package end up in the profile.
3506 Use the bootstrap Guile to build the profile. This option is only
3507 useful to distribution developers.
3511 In addition to these actions, @command{guix package} supports the
3512 following options to query the current state of a profile, or the
3513 availability of packages:
3517 @item --search=@var{regexp}
3518 @itemx -s @var{regexp}
3519 @anchor{guix-search}
3520 @cindex searching for packages
3521 List the available packages whose name, synopsis, or description matches
3522 @var{regexp} (in a case-insensitive fashion), sorted by relevance.
3523 Print all the metadata of matching packages in
3524 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
3525 GNU recutils manual}).
3527 This allows specific fields to be extracted using the @command{recsel}
3528 command, for instance:
3531 $ guix package -s malloc | recsel -p name,version,relevance
3545 Similarly, to show the name of all the packages available under the
3546 terms of the GNU@tie{}LGPL version 3:
3549 $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
3556 It is also possible to refine search results using several @code{-s} flags to
3557 @command{guix package}, or several arguments to @command{guix search}. For
3558 example, the following command returns a list of board games (this time using
3559 the @command{guix search} alias):
3562 $ guix search '\<board\>' game | recsel -p name
3567 If we were to omit @code{-s game}, we would also get software packages
3568 that deal with printed circuit boards; removing the angle brackets
3569 around @code{board} would further add packages that have to do with
3572 And now for a more elaborate example. The following command searches
3573 for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
3574 libraries, and prints the name and synopsis of the matching packages:
3577 $ guix search crypto library | \
3578 recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
3582 @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
3583 information on @dfn{selection expressions} for @code{recsel -e}.
3585 @item --show=@var{package}
3586 Show details about @var{package}, taken from the list of available packages, in
3587 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
3591 $ guix package --show=guile | recsel -p name,version
3603 You may also specify the full name of a package to only get details about a
3604 specific version of it (this time using the @command{guix show} alias):
3606 $ guix show guile@@3.0.5 | recsel -p name,version
3611 @item --list-installed[=@var{regexp}]
3612 @itemx -I [@var{regexp}]
3613 List the currently installed packages in the specified profile, with the
3614 most recently installed packages shown last. When @var{regexp} is
3615 specified, list only installed packages whose name matches @var{regexp}.
3617 For each installed package, print the following items, separated by
3618 tabs: the package name, its version string, the part of the package that
3619 is installed (for instance, @code{out} for the default output,
3620 @code{include} for its headers, etc.), and the path of this package in
3623 @item --list-available[=@var{regexp}]
3624 @itemx -A [@var{regexp}]
3625 List packages currently available in the distribution for this system
3626 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
3627 available packages whose name matches @var{regexp}.
3629 For each package, print the following items separated by tabs: its name,
3630 its version string, the parts of the package (@pxref{Packages with
3631 Multiple Outputs}), and the source location of its definition.
3633 @item --list-generations[=@var{pattern}]
3634 @itemx -l [@var{pattern}]
3636 Return a list of generations along with their creation dates; for each
3637 generation, show the installed packages, with the most recently
3638 installed packages shown last. Note that the zeroth generation is never
3641 For each installed package, print the following items, separated by
3642 tabs: the name of a package, its version string, the part of the package
3643 that is installed (@pxref{Packages with Multiple Outputs}), and the
3644 location of this package in the store.
3646 When @var{pattern} is used, the command returns only matching
3647 generations. Valid patterns include:
3650 @item @emph{Integers and comma-separated integers}. Both patterns denote
3651 generation numbers. For instance, @option{--list-generations=1} returns
3654 And @option{--list-generations=1,8,2} outputs three generations in the
3655 specified order. Neither spaces nor trailing commas are allowed.
3657 @item @emph{Ranges}. @option{--list-generations=2..9} prints the
3658 specified generations and everything in between. Note that the start of
3659 a range must be smaller than its end.
3661 It is also possible to omit the endpoint. For example,
3662 @option{--list-generations=2..}, returns all generations starting from the
3665 @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
3666 or months by passing an integer along with the first letter of the
3667 duration. For example, @option{--list-generations=20d} lists generations
3668 that are up to 20 days old.
3671 @item --delete-generations[=@var{pattern}]
3672 @itemx -d [@var{pattern}]
3673 When @var{pattern} is omitted, delete all generations except the current
3676 This command accepts the same patterns as @option{--list-generations}.
3677 When @var{pattern} is specified, delete the matching generations. When
3678 @var{pattern} specifies a duration, generations @emph{older} than the
3679 specified duration match. For instance, @option{--delete-generations=1m}
3680 deletes generations that are more than one month old.
3682 If the current generation matches, it is @emph{not} deleted. Also, the
3683 zeroth generation is never deleted.
3685 Note that deleting generations prevents rolling back to them.
3686 Consequently, this command must be used with care.
3688 @cindex manifest, exporting
3689 @anchor{export-manifest}
3690 @item --export-manifest
3691 Write to standard output a manifest suitable for @option{--manifest}
3692 corresponding to the chosen profile(s).
3694 This option is meant to help you migrate from the ``imperative''
3695 operating mode---running @command{guix install}, @command{guix upgrade},
3696 etc.---to the declarative mode that @option{--manifest} offers.
3698 Be aware that the resulting manifest @emph{approximates} what your
3699 profile actually contains; for instance, depending on how your profile
3700 was created, it can refer to packages or package versions that are not
3701 exactly what you specified.
3703 Keep in mind that a manifest is purely symbolic: it only contains
3704 package names and possibly versions, and their meaning varies over time.
3705 If you wish to ``pin'' channels to the revisions that were used to build
3706 the profile(s), see @option{--export-channels} below.
3708 @cindex pinning, channel revisions of a profile
3709 @item --export-channels
3710 Write to standard output the list of channels used by the chosen
3711 profile(s), in a format suitable for @command{guix pull --channels} or
3712 @command{guix time-machine --channels} (@pxref{Channels}).
3714 Together with @option{--export-manifest}, this option provides
3715 information allowing you to replicate the current profile
3716 (@pxref{Replicating Guix}).
3718 However, note that the output of this command @emph{approximates} what
3719 was actually used to build this profile. In particular, a single
3720 profile might have been built from several different revisions of the
3721 same channel. In that case, @option{--export-manifest} chooses the last
3722 one and writes the list of other revisions in a comment. If you really
3723 need to pick packages from different channel revisions, you can use
3724 inferiors in your manifest to do so (@pxref{Inferiors}).
3726 Together with @option{--export-manifest}, this is a good starting point
3727 if you are willing to migrate from the ``imperative'' model to the fully
3728 declarative model consisting of a manifest file along with a channels
3729 file pinning the exact channel revision(s) you want.
3732 Finally, since @command{guix package} may actually start build
3733 processes, it supports all the common build options (@pxref{Common Build
3734 Options}). It also supports package transformation options, such as
3735 @option{--with-source}, and preserves them across upgrades
3736 (@pxref{Package Transformation Options}).
3739 @section Substitutes
3742 @cindex pre-built binaries
3743 Guix supports transparent source/binary deployment, which means that it
3744 can either build things locally, or download pre-built items from a
3745 server, or both. We call these pre-built items @dfn{substitutes}---they
3746 are substitutes for local build results. In many cases, downloading a
3747 substitute is much faster than building things locally.
3749 Substitutes can be anything resulting from a derivation build
3750 (@pxref{Derivations}). Of course, in the common case, they are
3751 pre-built package binaries, but source tarballs, for instance, which
3752 also result from derivation builds, can be available as substitutes.
3755 * Official Substitute Servers:: One particular source of substitutes.
3756 * Substitute Server Authorization:: How to enable or disable substitutes.
3757 * Getting Substitutes from Other Servers:: Substitute diversity.
3758 * Substitute Authentication:: How Guix verifies substitutes.
3759 * Proxy Settings:: How to get substitutes via proxy.
3760 * Substitution Failure:: What happens when substitution fails.
3761 * On Trusting Binaries:: How can you trust that binary blob?
3764 @node Official Substitute Servers
3765 @subsection Official Substitute Servers
3768 @code{@value{SUBSTITUTE-SERVER-1}} and
3769 @code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build
3770 farms that build packages from Guix continuously for some architectures,
3771 and make them available as substitutes. These are the default source of
3772 substitutes; which can be overridden by passing the
3773 @option{--substitute-urls} option either to @command{guix-daemon}
3774 (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
3775 or to client tools such as @command{guix package}
3776 (@pxref{client-substitute-urls,, client @option{--substitute-urls}
3779 Substitute URLs can be either HTTP or HTTPS.
3780 HTTPS is recommended because communications are encrypted; conversely,
3781 using HTTP makes all communications visible to an eavesdropper, who
3782 could use the information gathered to determine, for instance, whether
3783 your system has unpatched security vulnerabilities.
3785 Substitutes from the official build farms are enabled by default when
3786 using Guix System (@pxref{GNU Distribution}). However,
3787 they are disabled by default when using Guix on a foreign distribution,
3788 unless you have explicitly enabled them via one of the recommended
3789 installation steps (@pxref{Installation}). The following paragraphs
3790 describe how to enable or disable substitutes for the official build
3791 farm; the same procedure can also be used to enable substitutes for any
3792 other substitute server.
3794 @node Substitute Server Authorization
3795 @subsection Substitute Server Authorization
3798 @cindex substitutes, authorization thereof
3799 @cindex access control list (ACL), for substitutes
3800 @cindex ACL (access control list), for substitutes
3801 To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you
3802 must add the relevant public key to the access control list (ACL) of archive
3803 imports, using the @command{guix archive} command (@pxref{Invoking guix
3804 archive}). Doing so implies that you trust the substitute server to not
3805 be compromised and to serve genuine substitutes.
3808 If you are using Guix System, you can skip this section: Guix System
3809 authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and
3810 @code{@value{SUBSTITUTE-SERVER-2}} by default.
3813 The public keys for each of the project maintained substitute servers
3814 are installed along with Guix, in @code{@var{prefix}/share/guix/}, where
3815 @var{prefix} is the installation prefix of Guix. If you installed Guix
3816 from source, make sure you checked the GPG signature of
3817 @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
3818 Then, you can run something like this:
3821 # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
3822 # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
3825 Once this is in place, the output of a command like @code{guix build}
3826 should change from something like:
3829 $ guix build emacs --dry-run
3830 The following derivations would be built:
3831 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
3832 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
3833 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
3834 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
3842 $ guix build emacs --dry-run
3843 112.3 MB would be downloaded:
3844 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
3845 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
3846 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
3847 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
3852 The text changed from ``The following derivations would be built'' to
3853 ``112.3 MB would be downloaded''. This indicates that substitutes from
3854 the configured substitute servers are usable and will be downloaded,
3855 when possible, for future builds.
3857 @cindex substitutes, how to disable
3858 The substitute mechanism can be disabled globally by running
3859 @code{guix-daemon} with @option{--no-substitutes} (@pxref{Invoking
3860 guix-daemon}). It can also be disabled temporarily by passing the
3861 @option{--no-substitutes} option to @command{guix package},
3862 @command{guix build}, and other command-line tools.
3864 @node Getting Substitutes from Other Servers
3865 @subsection Getting Substitutes from Other Servers
3867 @cindex substitute servers, adding more
3868 Guix can look up and fetch substitutes from several servers. This is
3869 useful when you are using packages from additional channels for which
3870 the official server does not have substitutes but another server
3871 provides them. Another situation where this is useful is when you would
3872 prefer to download from your organization's substitute server, resorting
3873 to the official server only as a fallback or dismissing it altogether.
3875 You can give Guix a list of substitute server URLs and it will check
3876 them in the specified order. You also need to explicitly authorize the
3877 public keys of substitute servers to instruct Guix to accept the
3878 substitutes they sign.
3880 On Guix System, this is achieved by modifying the configuration of the
3881 @code{guix} service. Since the @code{guix} service is part of the
3882 default lists of services, @code{%base-services} and
3883 @code{%desktop-services}, you can use @code{modify-services} to change
3884 its configuration and add the URLs and substitute keys that you want
3885 (@pxref{Service Reference, @code{modify-services}}).
3887 As an example, suppose you want to fetch substitutes from
3888 @code{guix.example.org} and to authorize the signing key of that server,
3889 in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and
3890 @code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system
3891 configuration will look something like:
3897 ;; Assume we're starting from '%desktop-services'. Replace it
3898 ;; with the list of services you're actually using.
3899 (modify-services %desktop-services
3900 (guix-service-type config =>
3904 (append (list "https://guix.example.org")
3905 %default-substitute-urls))
3907 (append (list (local-file "./key.pub"))
3908 %default-authorized-guix-keys)))))))
3911 This assumes that the file @file{key.pub} contains the signing key of
3912 @code{guix.example.org}. With this change in place in your operating
3913 system configuration file (say @file{/etc/config.scm}), you can
3914 reconfigure and restart the @code{guix-daemon} service or reboot so the
3915 changes take effect:
3918 $ sudo guix system reconfigure /etc/config.scm
3919 $ sudo herd restart guix-daemon
3922 If you're running Guix on a ``foreign distro'', you would instead take
3923 the following steps to get substitutes from additional servers:
3927 Edit the service configuration file for @code{guix-daemon}; when using
3928 systemd, this is normally
3929 @file{/etc/systemd/system/guix-daemon.service}. Add the
3930 @option{--substitute-urls} option on the @command{guix-daemon} command
3931 line and list the URLs of interest (@pxref{daemon-substitute-urls,
3932 @code{guix-daemon --substitute-urls}}):
3935 @dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
3939 Restart the daemon. For systemd, it goes like this:
3942 systemctl daemon-reload
3943 systemctl restart guix-daemon.service
3947 Authorize the key of the new server (@pxref{Invoking guix archive}):
3950 guix archive --authorize < key.pub
3953 Again this assumes @file{key.pub} contains the public key that
3954 @code{guix.example.org} uses to sign substitutes.
3957 Now you're all set! Substitutes will be preferably taken from
3958 @code{https://guix.example.org}, using
3959 @code{@value{SUBSTITUTE-SERVER-1}} then
3960 @code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you
3961 can list as many substitute servers as you like, with the caveat that
3962 substitute lookup can be slowed down if too many servers need to be
3965 Note that there are also situations where one may want to add the URL of
3966 a substitute server @emph{without} authorizing its key.
3967 @xref{Substitute Authentication}, to understand this fine point.
3969 @node Substitute Authentication
3970 @subsection Substitute Authentication
3972 @cindex digital signatures
3973 Guix detects and raises an error when attempting to use a substitute
3974 that has been tampered with. Likewise, it ignores substitutes that are
3975 not signed, or that are not signed by one of the keys listed in the ACL.
3977 There is one exception though: if an unauthorized server provides
3978 substitutes that are @emph{bit-for-bit identical} to those provided by
3979 an authorized server, then the unauthorized server becomes eligible for
3980 downloads. For example, assume we have chosen two substitute servers
3984 --substitute-urls="https://a.example.org https://b.example.org"
3988 @cindex reproducible builds
3989 If the ACL contains only the key for @samp{b.example.org}, and if
3990 @samp{a.example.org} happens to serve the @emph{exact same} substitutes,
3991 then Guix will download substitutes from @samp{a.example.org} because it
3992 comes first in the list and can be considered a mirror of
3993 @samp{b.example.org}. In practice, independent build machines usually
3994 produce the same binaries, thanks to bit-reproducible builds (see
3997 When using HTTPS, the server's X.509 certificate is @emph{not} validated
3998 (in other words, the server is not authenticated), contrary to what
3999 HTTPS clients such as Web browsers usually do. This is because Guix
4000 authenticates substitute information itself, as explained above, which
4001 is what we care about (whereas X.509 certificates are about
4002 authenticating bindings between domain names and public keys).
4004 @node Proxy Settings
4005 @subsection Proxy Settings
4009 Substitutes are downloaded over HTTP or HTTPS@. The @env{http_proxy} and
4010 @env{https_proxy} environment variables can be set in the environment of
4011 @command{guix-daemon} and are honored for downloads of substitutes.
4012 Note that the value of those environment variables in the environment
4013 where @command{guix build}, @command{guix package}, and other client
4014 commands are run has @emph{absolutely no effect}.
4016 @node Substitution Failure
4017 @subsection Substitution Failure
4019 Even when a substitute for a derivation is available, sometimes the
4020 substitution attempt will fail. This can happen for a variety of
4021 reasons: the substitute server might be offline, the substitute may
4022 recently have been deleted, the connection might have been interrupted,
4025 When substitutes are enabled and a substitute for a derivation is
4026 available, but the substitution attempt fails, Guix will attempt to
4027 build the derivation locally depending on whether or not
4028 @option{--fallback} was given (@pxref{fallback-option,, common build
4029 option @option{--fallback}}). Specifically, if @option{--fallback} was
4030 omitted, then no local build will be performed, and the derivation is
4031 considered to have failed. However, if @option{--fallback} was given,
4032 then Guix will attempt to build the derivation locally, and the success
4033 or failure of the derivation depends on the success or failure of the
4034 local build. Note that when substitutes are disabled or no substitute
4035 is available for the derivation in question, a local build will
4036 @emph{always} be performed, regardless of whether or not
4037 @option{--fallback} was given.
4039 To get an idea of how many substitutes are available right now, you can
4040 try running the @command{guix weather} command (@pxref{Invoking guix
4041 weather}). This command provides statistics on the substitutes provided
4044 @node On Trusting Binaries
4045 @subsection On Trusting Binaries
4047 @cindex trust, of pre-built binaries
4048 Today, each individual's control over their own computing is at the
4049 mercy of institutions, corporations, and groups with enough power and
4050 determination to subvert the computing infrastructure and exploit its
4051 weaknesses. While using substitutes can be convenient, we encourage
4052 users to also build on their own, or even run their own build farm, such
4053 that the project run substitute servers are less of an interesting
4054 target. One way to help is by publishing the software you build using
4055 @command{guix publish} so that others have one more choice of server to
4056 download substitutes from (@pxref{Invoking guix publish}).
4058 Guix has the foundations to maximize build reproducibility
4059 (@pxref{Features}). In most cases, independent builds of a given
4060 package or derivation should yield bit-identical results. Thus, through
4061 a diverse set of independent package builds, we can strengthen the
4062 integrity of our systems. The @command{guix challenge} command aims to
4063 help users assess substitute servers, and to assist developers in
4064 finding out about non-deterministic package builds (@pxref{Invoking guix
4065 challenge}). Similarly, the @option{--check} option of @command{guix
4066 build} allows users to check whether previously-installed substitutes
4067 are genuine by rebuilding them locally (@pxref{build-check,
4068 @command{guix build --check}}).
4070 In the future, we want Guix to have support to publish and retrieve
4071 binaries to/from other users, in a peer-to-peer fashion. If you would
4072 like to discuss this project, join us on @email{guix-devel@@gnu.org}.
4074 @node Packages with Multiple Outputs
4075 @section Packages with Multiple Outputs
4077 @cindex multiple-output packages
4078 @cindex package outputs
4081 Often, packages defined in Guix have a single @dfn{output}---i.e., the
4082 source package leads to exactly one directory in the store. When running
4083 @command{guix install glibc}, one installs the default output of the
4084 GNU libc package; the default output is called @code{out}, but its name
4085 can be omitted as shown in this command. In this particular case, the
4086 default output of @code{glibc} contains all the C header files, shared
4087 libraries, static libraries, Info documentation, and other supporting
4090 Sometimes it is more appropriate to separate the various types of files
4091 produced from a single source package into separate outputs. For
4092 instance, the GLib C library (used by GTK+ and related packages)
4093 installs more than 20 MiB of reference documentation as HTML pages.
4094 To save space for users who do not need it, the documentation goes to a
4095 separate output, called @code{doc}. To install the main GLib output,
4096 which contains everything but the documentation, one would run:
4102 @cindex documentation
4103 The command to install its documentation is:
4106 guix install glib:doc
4109 Some packages install programs with different ``dependency footprints''.
4110 For instance, the WordNet package installs both command-line tools and
4111 graphical user interfaces (GUIs). The former depend solely on the C
4112 library, whereas the latter depend on Tcl/Tk and the underlying X
4113 libraries. In this case, we leave the command-line tools in the default
4114 output, whereas the GUIs are in a separate output. This allows users
4115 who do not need the GUIs to save space. The @command{guix size} command
4116 can help find out about such situations (@pxref{Invoking guix size}).
4117 @command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
4119 There are several such multiple-output packages in the GNU distribution.
4120 Other conventional output names include @code{lib} for libraries and
4121 possibly header files, @code{bin} for stand-alone programs, and
4122 @code{debug} for debugging information (@pxref{Installing Debugging
4123 Files}). The outputs of a packages are listed in the third column of
4124 the output of @command{guix package --list-available} (@pxref{Invoking
4128 @node Invoking guix gc
4129 @section Invoking @command{guix gc}
4131 @cindex garbage collector
4133 Packages that are installed, but not used, may be @dfn{garbage-collected}.
4134 The @command{guix gc} command allows users to explicitly run the garbage
4135 collector to reclaim space from the @file{/gnu/store} directory. It is
4136 the @emph{only} way to remove files from @file{/gnu/store}---removing
4137 files or directories manually may break it beyond repair!
4140 @cindex garbage collector roots
4141 The garbage collector has a set of known @dfn{roots}: any file under
4142 @file{/gnu/store} reachable from a root is considered @dfn{live} and
4143 cannot be deleted; any other file is considered @dfn{dead} and may be
4144 deleted. The set of garbage collector roots (``GC roots'' for short)
4145 includes default user profiles; by default, the symlinks under
4146 @file{/var/guix/gcroots} represent these GC roots. New GC roots can be
4147 added with @command{guix build --root}, for example (@pxref{Invoking
4148 guix build}). The @command{guix gc --list-roots} command lists them.
4150 Prior to running @code{guix gc --collect-garbage} to make space, it is
4151 often useful to remove old generations from user profiles; that way, old
4152 package builds referenced by those generations can be reclaimed. This
4153 is achieved by running @code{guix package --delete-generations}
4154 (@pxref{Invoking guix package}).
4156 Our recommendation is to run a garbage collection periodically, or when
4157 you are short on disk space. For instance, to guarantee that at least
4158 5@tie{}GB are available on your disk, simply run:
4164 It is perfectly safe to run as a non-interactive periodic job
4165 (@pxref{Scheduled Job Execution}, for how to set up such a job).
4166 Running @command{guix gc} with no arguments will collect as
4167 much garbage as it can, but that is often inconvenient: you may find
4168 yourself having to rebuild or re-download software that is ``dead'' from
4169 the GC viewpoint but that is necessary to build other pieces of
4170 software---e.g., the compiler tool chain.
4172 The @command{guix gc} command has three modes of operation: it can be
4173 used to garbage-collect any dead files (the default), to delete specific
4174 files (the @option{--delete} option), to print garbage-collector
4175 information, or for more advanced queries. The garbage collection
4176 options are as follows:
4179 @item --collect-garbage[=@var{min}]
4180 @itemx -C [@var{min}]
4181 Collect garbage---i.e., unreachable @file{/gnu/store} files and
4182 sub-directories. This is the default operation when no option is
4185 When @var{min} is given, stop once @var{min} bytes have been collected.
4186 @var{min} may be a number of bytes, or it may include a unit as a
4187 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
4188 (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
4190 When @var{min} is omitted, collect all the garbage.
4192 @item --free-space=@var{free}
4193 @itemx -F @var{free}
4194 Collect garbage until @var{free} space is available under
4195 @file{/gnu/store}, if possible; @var{free} denotes storage space, such
4196 as @code{500MiB}, as described above.
4198 When @var{free} or more is already available in @file{/gnu/store}, do
4199 nothing and exit immediately.
4201 @item --delete-generations[=@var{duration}]
4202 @itemx -d [@var{duration}]
4203 Before starting the garbage collection process, delete all the generations
4204 older than @var{duration}, for all the user profiles; when run as root, this
4205 applies to all the profiles @emph{of all the users}.
4207 For example, this command deletes all the generations of all your profiles
4208 that are older than 2 months (except generations that are current), and then
4209 proceeds to free space until at least 10 GiB are available:
4212 guix gc -d 2m -F 10G
4217 Attempt to delete all the store files and directories specified as
4218 arguments. This fails if some of the files are not in the store, or if
4219 they are still live.
4221 @item --list-failures
4222 List store items corresponding to cached build failures.
4224 This prints nothing unless the daemon was started with
4225 @option{--cache-failures} (@pxref{Invoking guix-daemon,
4226 @option{--cache-failures}}).
4229 List the GC roots owned by the user; when run as root, list @emph{all} the GC
4233 List store items in use by currently running processes. These store
4234 items are effectively considered GC roots: they cannot be deleted.
4236 @item --clear-failures
4237 Remove the specified store items from the failed-build cache.
4239 Again, this option only makes sense when the daemon is started with
4240 @option{--cache-failures}. Otherwise, it does nothing.
4243 Show the list of dead files and directories still present in the
4244 store---i.e., files and directories no longer reachable from any root.
4247 Show the list of live store files and directories.
4251 In addition, the references among existing store files can be queried:
4257 @cindex package dependencies
4258 List the references (respectively, the referrers) of store files given
4264 List the requisites of the store files passed as arguments. Requisites
4265 include the store files themselves, their references, and the references
4266 of these, recursively. In other words, the returned list is the
4267 @dfn{transitive closure} of the store files.
4269 @xref{Invoking guix size}, for a tool to profile the size of the closure
4270 of an element. @xref{Invoking guix graph}, for a tool to visualize
4271 the graph of references.
4275 Return the derivation(s) leading to the given store items
4276 (@pxref{Derivations}).
4278 For example, this command:
4281 guix gc --derivers $(guix package -I ^emacs$ | cut -f4)
4285 returns the @file{.drv} file(s) leading to the @code{emacs} package
4286 installed in your profile.
4288 Note that there may be zero matching @file{.drv} files, for instance
4289 because these files have been garbage-collected. There can also be more
4290 than one matching @file{.drv} due to fixed-output derivations.
4293 Lastly, the following options allow you to check the integrity of the
4294 store and to control disk usage.
4298 @item --verify[=@var{options}]
4299 @cindex integrity, of the store
4300 @cindex integrity checking
4301 Verify the integrity of the store.
4303 By default, make sure that all the store items marked as valid in the
4304 database of the daemon actually exist in @file{/gnu/store}.
4306 When provided, @var{options} must be a comma-separated list containing one
4307 or more of @code{contents} and @code{repair}.
4309 When passing @option{--verify=contents}, the daemon computes the
4310 content hash of each store item and compares it against its hash in the
4311 database. Hash mismatches are reported as data corruptions. Because it
4312 traverses @emph{all the files in the store}, this command can take a
4313 long time, especially on systems with a slow disk drive.
4315 @cindex repairing the store
4316 @cindex corruption, recovering from
4317 Using @option{--verify=repair} or @option{--verify=contents,repair}
4318 causes the daemon to try to repair corrupt store items by fetching
4319 substitutes for them (@pxref{Substitutes}). Because repairing is not
4320 atomic, and thus potentially dangerous, it is available only to the
4321 system administrator. A lightweight alternative, when you know exactly
4322 which items in the store are corrupt, is @command{guix build --repair}
4323 (@pxref{Invoking guix build}).
4326 @cindex deduplication
4327 Optimize the store by hard-linking identical files---this is
4328 @dfn{deduplication}.
4330 The daemon performs deduplication after each successful build or archive
4331 import, unless it was started with @option{--disable-deduplication}
4332 (@pxref{Invoking guix-daemon, @option{--disable-deduplication}}). Thus,
4333 this option is primarily useful when the daemon was running with
4334 @option{--disable-deduplication}.
4338 @node Invoking guix pull
4339 @section Invoking @command{guix pull}
4341 @cindex upgrading Guix
4342 @cindex updating Guix
4343 @cindex @command{guix pull}
4345 @cindex security, @command{guix pull}
4346 @cindex authenticity, of code obtained with @command{guix pull}
4347 Packages are installed or upgraded to the latest version available in
4348 the distribution currently available on your local machine. To update
4349 that distribution, along with the Guix tools, you must run @command{guix
4350 pull}: the command downloads the latest Guix source code and package
4351 descriptions, and deploys it. Source code is downloaded from a
4352 @uref{https://git-scm.com, Git} repository, by default the official
4353 GNU@tie{}Guix repository, though this can be customized. @command{guix
4354 pull} ensures that the code it downloads is @emph{authentic} by
4355 verifying that commits are signed by Guix developers.
4357 Specifically, @command{guix pull} downloads code from the @dfn{channels}
4358 (@pxref{Channels}) specified by one of the followings, in this order:
4362 the @option{--channels} option;
4364 the user's @file{~/.config/guix/channels.scm} file;
4366 the system-wide @file{/etc/guix/channels.scm} file;
4368 the built-in default channels specified in the @code{%default-channels}
4372 On completion, @command{guix package} will use packages and package
4373 versions from this just-retrieved copy of Guix. Not only that, but all
4374 the Guix commands and Scheme modules will also be taken from that latest
4375 version. New @command{guix} sub-commands added by the update also
4378 Any user can update their Guix copy using @command{guix pull}, and the
4379 effect is limited to the user who ran @command{guix pull}. For
4380 instance, when user @code{root} runs @command{guix pull}, this has no
4381 effect on the version of Guix that user @code{alice} sees, and vice
4384 The result of running @command{guix pull} is a @dfn{profile} available
4385 under @file{~/.config/guix/current} containing the latest Guix. Thus,
4386 make sure to add it to the beginning of your search path so that you use
4387 the latest version, and similarly for the Info manual
4388 (@pxref{Documentation}):
4391 export PATH="$HOME/.config/guix/current/bin:$PATH"
4392 export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
4395 The @option{--list-generations} or @option{-l} option lists past generations
4396 produced by @command{guix pull}, along with details about their provenance:
4400 Generation 1 Jun 10 2018 00:18:18
4402 repository URL: https://git.savannah.gnu.org/git/guix.git
4403 branch: origin/master
4404 commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
4406 Generation 2 Jun 11 2018 11:02:49
4408 repository URL: https://git.savannah.gnu.org/git/guix.git
4409 branch: origin/master
4410 commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
4411 2 new packages: keepalived, libnfnetlink
4412 6 packages upgraded: emacs-nix-mode@@2.0.4,
4413 guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
4414 heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4
4416 Generation 3 Jun 13 2018 23:31:07 (current)
4418 repository URL: https://git.savannah.gnu.org/git/guix.git
4419 branch: origin/master
4420 commit: 844cc1c8f394f03b404c5bb3aee086922373490c
4421 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
4422 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
4425 @xref{Invoking guix describe, @command{guix describe}}, for other ways to
4426 describe the current status of Guix.
4428 This @code{~/.config/guix/current} profile works exactly like the profiles
4429 created by @command{guix package} (@pxref{Invoking guix package}). That
4430 is, you can list generations, roll back to the previous
4431 generation---i.e., the previous Guix---and so on:
4434 $ guix pull --roll-back
4435 switched from generation 3 to 2
4436 $ guix pull --delete-generations=1
4437 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
4440 You can also use @command{guix package} (@pxref{Invoking guix package})
4441 to manage the profile by naming it explicitly:
4443 $ guix package -p ~/.config/guix/current --roll-back
4444 switched from generation 3 to 2
4445 $ guix package -p ~/.config/guix/current --delete-generations=1
4446 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
4449 The @command{guix pull} command is usually invoked with no arguments,
4450 but it supports the following options:
4453 @item --url=@var{url}
4454 @itemx --commit=@var{commit}
4455 @itemx --branch=@var{branch}
4456 Download code for the @code{guix} channel from the specified @var{url}, at the
4457 given @var{commit} (a valid Git commit ID represented as a hexadecimal
4458 string), or @var{branch}.
4460 @cindex @file{channels.scm}, configuration file
4461 @cindex configuration file for channels
4462 These options are provided for convenience, but you can also specify your
4463 configuration in the @file{~/.config/guix/channels.scm} file or using the
4464 @option{--channels} option (see below).
4466 @item --channels=@var{file}
4467 @itemx -C @var{file}
4468 Read the list of channels from @var{file} instead of
4469 @file{~/.config/guix/channels.scm} or @file{/etc/guix/channels.scm}.
4470 @var{file} must contain Scheme code that
4471 evaluates to a list of channel objects. @xref{Channels}, for more
4474 @cindex channel news
4477 Display the list of packages added or upgraded since the previous
4478 generation, as well as, occasionally, news written by channel authors
4479 for their users (@pxref{Channels, Writing Channel News}).
4481 The package information is the same as displayed upon @command{guix
4482 pull} completion, but without ellipses; it is also similar to the output
4483 of @command{guix pull -l} for the last generation (see below).
4485 @item --list-generations[=@var{pattern}]
4486 @itemx -l [@var{pattern}]
4487 List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
4488 is provided, the subset of generations that match @var{pattern}.
4489 The syntax of @var{pattern} is the same as with @code{guix package
4490 --list-generations} (@pxref{Invoking guix package}).
4493 @cindex rolling back
4494 @cindex undoing transactions
4495 @cindex transactions, undoing
4496 Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e.,
4497 undo the last transaction.
4499 @item --switch-generation=@var{pattern}
4500 @itemx -S @var{pattern}
4502 Switch to a particular generation defined by @var{pattern}.
4504 @var{pattern} may be either a generation number or a number prefixed
4505 with ``+'' or ``-''. The latter means: move forward/backward by a
4506 specified number of generations. For example, if you want to return to
4507 the latest generation after @option{--roll-back}, use
4508 @option{--switch-generation=+1}.
4510 @item --delete-generations[=@var{pattern}]
4511 @itemx -d [@var{pattern}]
4512 When @var{pattern} is omitted, delete all generations except the current
4515 This command accepts the same patterns as @option{--list-generations}.
4516 When @var{pattern} is specified, delete the matching generations. When
4517 @var{pattern} specifies a duration, generations @emph{older} than the
4518 specified duration match. For instance, @option{--delete-generations=1m}
4519 deletes generations that are more than one month old.
4521 If the current generation matches, it is @emph{not} deleted.
4523 Note that deleting generations prevents rolling back to them.
4524 Consequently, this command must be used with care.
4526 @xref{Invoking guix describe}, for a way to display information about the
4527 current generation only.
4529 @item --profile=@var{profile}
4530 @itemx -p @var{profile}
4531 Use @var{profile} instead of @file{~/.config/guix/current}.
4535 Show which channel commit(s) would be used and what would be built or
4536 substituted but do not actually do it.
4538 @item --allow-downgrades
4539 Allow pulling older or unrelated revisions of channels than those
4542 @cindex downgrade attacks, protection against
4543 By default, @command{guix pull} protects against so-called ``downgrade
4544 attacks'' whereby the Git repository of a channel would be reset to an
4545 earlier or unrelated revision of itself, potentially leading you to
4546 install older, known-vulnerable versions of software packages.
4549 Make sure you understand its security implications before using
4550 @option{--allow-downgrades}.
4553 @item --disable-authentication
4554 Allow pulling channel code without authenticating it.
4556 @cindex authentication, of channel code
4557 By default, @command{guix pull} authenticates code downloaded from
4558 channels by verifying that its commits are signed by authorized
4559 developers, and raises an error if this is not the case. This option
4560 instructs it to not perform any such verification.
4563 Make sure you understand its security implications before using
4564 @option{--disable-authentication}.
4567 @item --system=@var{system}
4568 @itemx -s @var{system}
4569 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
4570 the system type of the build host.
4573 Use the bootstrap Guile to build the latest Guix. This option is only
4574 useful to Guix developers.
4577 The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
4578 repository and branch to pull from, as well as @emph{additional} repositories
4579 containing package modules that should be deployed. @xref{Channels}, for more
4582 In addition, @command{guix pull} supports all the common build options
4583 (@pxref{Common Build Options}).
4585 @node Invoking guix time-machine
4586 @section Invoking @command{guix time-machine}
4588 @cindex @command{guix time-machine}
4589 @cindex pinning, channels
4590 @cindex replicating Guix
4591 @cindex reproducibility, of Guix
4593 The @command{guix time-machine} command provides access to other
4594 revisions of Guix, for example to install older versions of packages,
4595 or to reproduce a computation in an identical environment. The revision
4596 of Guix to be used is defined by a commit or by a channel
4597 description file created by @command{guix describe}
4598 (@pxref{Invoking guix describe}).
4600 The general syntax is:
4603 guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
4606 where @var{command} and @var{arg}@dots{} are passed unmodified to the
4607 @command{guix} command of the specified revision. The @var{options} that define
4608 this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
4611 @item --url=@var{url}
4612 @itemx --commit=@var{commit}
4613 @itemx --branch=@var{branch}
4614 Use the @code{guix} channel from the specified @var{url}, at the
4615 given @var{commit} (a valid Git commit ID represented as a hexadecimal
4616 string), or @var{branch}.
4618 @item --channels=@var{file}
4619 @itemx -C @var{file}
4620 Read the list of channels from @var{file}. @var{file} must contain
4621 Scheme code that evaluates to a list of channel objects.
4622 @xref{Channels} for more information.
4625 As for @command{guix pull}, the absence of any options means that the
4626 latest commit on the master branch will be used. The command
4629 guix time-machine -- build hello
4632 will thus build the package @code{hello} as defined in the master branch,
4633 which is in general a newer revision of Guix than you have installed.
4634 Time travel works in both directions!
4636 Note that @command{guix time-machine} can trigger builds of channels and
4637 their dependencies, and these are controlled by the standard build
4638 options (@pxref{Common Build Options}).
4643 @c TODO: Remove this once we're more confident about API stability.
4645 The functionality described here is a ``technology preview'' as of version
4646 @value{VERSION}. As such, the interface is subject to change.
4650 @cindex composition of Guix revisions
4651 Sometimes you might need to mix packages from the revision of Guix you're
4652 currently running with packages available in a different revision of Guix.
4653 Guix @dfn{inferiors} allow you to achieve that by composing different Guix
4654 revisions in arbitrary ways.
4656 @cindex inferior packages
4657 Technically, an ``inferior'' is essentially a separate Guix process connected
4658 to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
4659 @code{(guix inferior)} module allows you to create inferiors and to
4660 communicate with them. It also provides a high-level interface to browse and
4661 manipulate the packages that an inferior provides---@dfn{inferior packages}.
4663 When combined with channels (@pxref{Channels}), inferiors provide a simple way
4664 to interact with a separate revision of Guix. For example, let's assume you
4665 want to install in your profile the current @code{guile} package, along with
4666 the @code{guile-json} as it existed in an older revision of Guix---perhaps
4667 because the newer @code{guile-json} has an incompatible API and you want to
4668 run your code against the old API@. To do that, you could write a manifest for
4669 use by @code{guix package --manifest} (@pxref{Invoking guix package}); in that
4670 manifest, you would create an inferior for that old Guix revision you care
4671 about, and you would look up the @code{guile-json} package in the inferior:
4674 (use-modules (guix inferior) (guix channels)
4675 (srfi srfi-1)) ;for 'first'
4678 ;; This is the old revision from which we want to
4679 ;; extract guile-json.
4682 (url "https://git.savannah.gnu.org/git/guix.git")
4684 "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
4687 ;; An inferior representing the above revision.
4688 (inferior-for-channels channels))
4690 ;; Now create a manifest with the current "guile" package
4691 ;; and the old "guile-json" package.
4693 (list (first (lookup-inferior-packages inferior "guile-json"))
4694 (specification->package "guile")))
4697 On its first run, @command{guix package --manifest} might have to build the
4698 channel you specified before it can create the inferior; subsequent runs will
4699 be much faster because the Guix revision will be cached.
4701 The @code{(guix inferior)} module provides the following procedures to open an
4704 @deffn {Scheme Procedure} inferior-for-channels @var{channels} @
4705 [#:cache-directory] [#:ttl]
4706 Return an inferior for @var{channels}, a list of channels. Use the cache at
4707 @var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
4708 This procedure opens a new connection to the build daemon.
4710 As a side effect, this procedure may build or substitute binaries for
4711 @var{channels}, which can take time.
4714 @deffn {Scheme Procedure} open-inferior @var{directory} @
4715 [#:command "bin/guix"]
4716 Open the inferior Guix in @var{directory}, running
4717 @code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
4718 the inferior could not be launched.
4721 @cindex inferior packages
4722 The procedures listed below allow you to obtain and manipulate inferior
4725 @deffn {Scheme Procedure} inferior-packages @var{inferior}
4726 Return the list of packages known to @var{inferior}.
4729 @deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
4731 Return the sorted list of inferior packages matching @var{name} in
4732 @var{inferior}, with highest version numbers first. If @var{version} is true,
4733 return only packages with a version number prefixed by @var{version}.
4736 @deffn {Scheme Procedure} inferior-package? @var{obj}
4737 Return true if @var{obj} is an inferior package.
4740 @deffn {Scheme Procedure} inferior-package-name @var{package}
4741 @deffnx {Scheme Procedure} inferior-package-version @var{package}
4742 @deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
4743 @deffnx {Scheme Procedure} inferior-package-description @var{package}
4744 @deffnx {Scheme Procedure} inferior-package-home-page @var{package}
4745 @deffnx {Scheme Procedure} inferior-package-location @var{package}
4746 @deffnx {Scheme Procedure} inferior-package-inputs @var{package}
4747 @deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
4748 @deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
4749 @deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
4750 @deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
4751 @deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
4752 @deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
4753 These procedures are the counterpart of package record accessors
4754 (@pxref{package Reference}). Most of them work by querying the inferior
4755 @var{package} comes from, so the inferior must still be live when you call
4759 Inferior packages can be used transparently like any other package or
4760 file-like object in G-expressions (@pxref{G-Expressions}). They are also
4761 transparently handled by the @code{packages->manifest} procedure, which is
4762 commonly used in manifests (@pxref{Invoking guix package, the
4763 @option{--manifest} option of @command{guix package}}). Thus you can insert
4764 an inferior package pretty much anywhere you would insert a regular package:
4765 in manifests, in the @code{packages} field of your @code{operating-system}
4766 declaration, and so on.
4768 @node Invoking guix describe
4769 @section Invoking @command{guix describe}
4771 @cindex reproducibility
4772 @cindex replicating Guix
4773 Often you may want to answer questions like: ``Which revision of Guix am I
4774 using?'' or ``Which channels am I using?'' This is useful information in many
4775 situations: if you want to @emph{replicate} an environment on a different
4776 machine or user account, if you want to report a bug or to determine what
4777 change in the channels you are using caused it, or if you want to record your
4778 system state for reproducibility purposes. The @command{guix describe}
4779 command answers these questions.
4781 When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
4782 displays the channel(s) that it was built from, including their repository URL
4783 and commit IDs (@pxref{Channels}):
4787 Generation 10 Sep 03 2018 17:32:44 (current)
4789 repository URL: https://git.savannah.gnu.org/git/guix.git
4791 commit: e0fa68c7718fffd33d81af415279d6ddb518f727
4794 If you're familiar with the Git version control system, this is similar in
4795 spirit to @command{git describe}; the output is also similar to that of
4796 @command{guix pull --list-generations}, but limited to the current generation
4797 (@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
4798 the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
4799 information is all it takes to describe the revision of Guix you're using, and
4800 also to replicate it.
4802 To make it easier to replicate Guix, @command{guix describe} can also be asked
4803 to return a list of channels instead of the human-readable description above:
4806 $ guix describe -f channels
4809 (url "https://git.savannah.gnu.org/git/guix.git")
4811 "e0fa68c7718fffd33d81af415279d6ddb518f727")
4813 (make-channel-introduction
4814 "9edb3f66fd807b096b48283debdcddccfea34bad"
4815 (openpgp-fingerprint
4816 "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA")))))
4820 You can save this to a file and feed it to @command{guix pull -C} on some
4821 other machine or at a later point in time, which will instantiate @emph{this
4822 exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
4823 From there on, since you're able to deploy the same revision of Guix, you can
4824 just as well @emph{replicate a complete software environment}. We humbly
4825 think that this is @emph{awesome}, and we hope you'll like it too!
4827 The details of the options supported by @command{guix describe} are as
4831 @item --format=@var{format}
4832 @itemx -f @var{format}
4833 Produce output in the specified @var{format}, one of:
4837 produce human-readable output;
4839 produce a list of channel specifications that can be passed to @command{guix
4840 pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
4842 @item channels-sans-intro
4843 like @code{channels}, but omit the @code{introduction} field; use it to
4844 produce a channel specification suitable for Guix version 1.1.0 or
4845 earlier---the @code{introduction} field has to do with channel
4846 authentication (@pxref{Channels, Channel Authentication}) and is not
4847 supported by these older versions;
4850 produce a list of channel specifications in JSON format;
4852 produce a list of channel specifications in Recutils format.
4855 @item --list-formats
4856 Display available formats for @option{--format} option.
4858 @item --profile=@var{profile}
4859 @itemx -p @var{profile}
4860 Display information about @var{profile}.
4863 @node Invoking guix archive
4864 @section Invoking @command{guix archive}
4866 @cindex @command{guix archive}
4868 The @command{guix archive} command allows users to @dfn{export} files
4869 from the store into a single archive, and to later @dfn{import} them on
4870 a machine that runs Guix.
4871 In particular, it allows store files to be transferred from one machine
4872 to the store on another machine.
4875 If you're looking for a way to produce archives in a format suitable for
4876 tools other than Guix, @pxref{Invoking guix pack}.
4879 @cindex exporting store items
4880 To export store files as an archive to standard output, run:
4883 guix archive --export @var{options} @var{specifications}...
4886 @var{specifications} may be either store file names or package
4887 specifications, as for @command{guix package} (@pxref{Invoking guix
4888 package}). For instance, the following command creates an archive
4889 containing the @code{gui} output of the @code{git} package and the main
4890 output of @code{emacs}:
4893 guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
4896 If the specified packages are not built yet, @command{guix archive}
4897 automatically builds them. The build process may be controlled with the
4898 common build options (@pxref{Common Build Options}).
4900 To transfer the @code{emacs} package to a machine connected over SSH,
4904 guix archive --export -r emacs | ssh the-machine guix archive --import
4908 Similarly, a complete user profile may be transferred from one machine
4909 to another like this:
4912 guix archive --export -r $(readlink -f ~/.guix-profile) | \
4913 ssh the-machine guix archive --import
4917 However, note that, in both examples, all of @code{emacs} and the
4918 profile as well as all of their dependencies are transferred (due to
4919 @option{-r}), regardless of what is already available in the store on
4920 the target machine. The @option{--missing} option can help figure out
4921 which items are missing from the target store. The @command{guix copy}
4922 command simplifies and optimizes this whole process, so this is probably
4923 what you should use in this case (@pxref{Invoking guix copy}).
4925 @cindex nar, archive format
4926 @cindex normalized archive (nar)
4927 @cindex nar bundle, archive format
4928 Each store item is written in the @dfn{normalized archive} or @dfn{nar}
4929 format (described below), and the output of @command{guix archive
4930 --export} (and input of @command{guix archive --import}) is a @dfn{nar
4934 comparable in spirit to `tar', but with differences
4935 that make it more appropriate for our purposes. First, rather than
4936 recording all Unix metadata for each file, the nar format only mentions
4937 the file type (regular, directory, or symbolic link); Unix permissions
4938 and owner/group are dismissed. Second, the order in which directory
4939 entries are stored always follows the order of file names according to
4940 the C locale collation order. This makes archive production fully
4943 That nar bundle format is essentially the concatenation of zero or more
4944 nars along with metadata for each store item it contains: its file name,
4945 references, corresponding derivation, and a digital signature.
4947 When exporting, the daemon digitally signs the contents of the archive,
4948 and that digital signature is appended. When importing, the daemon
4949 verifies the signature and rejects the import in case of an invalid
4950 signature or if the signing key is not authorized.
4951 @c FIXME: Add xref to daemon doc about signatures.
4953 The main options are:
4957 Export the specified store files or packages (see below). Write the
4958 resulting archive to the standard output.
4960 Dependencies are @emph{not} included in the output, unless
4961 @option{--recursive} is passed.
4965 When combined with @option{--export}, this instructs @command{guix archive}
4966 to include dependencies of the given items in the archive. Thus, the
4967 resulting archive is self-contained: it contains the closure of the
4968 exported store items.
4971 Read an archive from the standard input, and import the files listed
4972 therein into the store. Abort if the archive has an invalid digital
4973 signature, or if it is signed by a public key not among the authorized
4974 keys (see @option{--authorize} below).
4977 Read a list of store file names from the standard input, one per line,
4978 and write on the standard output the subset of these files missing from
4981 @item --generate-key[=@var{parameters}]
4982 @cindex signing, archives
4983 Generate a new key pair for the daemon. This is a prerequisite before
4984 archives can be exported with @option{--export}. This
4985 operation is usually instantaneous but it can take time if the system's
4986 entropy pool needs to be refilled. On Guix System,
4987 @code{guix-service-type} takes care of generating this key pair the
4990 The generated key pair is typically stored under @file{/etc/guix}, in
4991 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
4992 key, which must be kept secret). When @var{parameters} is omitted,
4993 an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
4994 versions before 1.6.0, it is a 4096-bit RSA key.
4995 Alternatively, @var{parameters} can specify
4996 @code{genkey} parameters suitable for Libgcrypt (@pxref{General
4997 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
4998 Libgcrypt Reference Manual}).
5001 @cindex authorizing, archives
5002 Authorize imports signed by the public key passed on standard input.
5003 The public key must be in ``s-expression advanced format''---i.e., the
5004 same format as the @file{signing-key.pub} file.
5006 The list of authorized keys is kept in the human-editable file
5007 @file{/etc/guix/acl}. The file contains
5008 @url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
5009 s-expressions''} and is structured as an access-control list in the
5010 @url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
5013 @item --extract=@var{directory}
5014 @itemx -x @var{directory}
5015 Read a single-item archive as served by substitute servers
5016 (@pxref{Substitutes}) and extract it to @var{directory}. This is a
5017 low-level operation needed in only very narrow use cases; see below.
5019 For example, the following command extracts the substitute for Emacs
5020 served by @code{@value{SUBSTITUTE-SERVER-1}} to @file{/tmp/emacs}:
5024 https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \
5025 | gunzip | guix archive -x /tmp/emacs
5028 Single-item archives are different from multiple-item archives produced
5029 by @command{guix archive --export}; they contain a single store item,
5030 and they do @emph{not} embed a signature. Thus this operation does
5031 @emph{no} signature verification and its output should be considered
5034 The primary purpose of this operation is to facilitate inspection of
5035 archive contents coming from possibly untrusted substitute servers
5036 (@pxref{Invoking guix challenge}).
5040 Read a single-item archive as served by substitute servers
5041 (@pxref{Substitutes}) and print the list of files it contains, as in
5046 https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \
5047 | lzip -d | guix archive -t
5052 @c *********************************************************************
5057 @cindex @file{channels.scm}, configuration file
5058 @cindex configuration file for channels
5059 @cindex @command{guix pull}, configuration file
5060 @cindex configuration of @command{guix pull}
5061 Guix and its package collection are updated by running @command{guix pull}
5062 (@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
5063 deploys Guix itself from the official GNU@tie{}Guix repository. This can be
5064 customized by defining @dfn{channels} in the
5065 @file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
5066 of a Git repository to be deployed, and @command{guix pull} can be instructed
5067 to pull from one or more channels. In other words, channels can be used
5068 to @emph{customize} and to @emph{extend} Guix, as we will see below.
5069 Guix is able to take into account security concerns and deal with authenticated
5073 * Specifying Additional Channels:: Extending the package collection.
5074 * Using a Custom Guix Channel:: Using a customized Guix.
5075 * Replicating Guix:: Running the @emph{exact same} Guix.
5076 * Channel Authentication:: How Guix verifies what it fetches.
5077 * Channels with Substitutes:: Using channels with available substitutes.
5078 * Creating a Channel:: How to write your custom channel.
5079 * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
5080 * Declaring Channel Dependencies:: How to depend on other channels.
5081 * Specifying Channel Authorizations:: Defining channel authors authorizations.
5082 * Primary URL:: Distinguishing mirror to original.
5083 * Writing Channel News:: Communicating information to channel's users.
5086 @node Specifying Additional Channels
5087 @section Specifying Additional Channels
5089 @cindex extending the package collection (channels)
5090 @cindex variant packages (channels)
5091 You can specify @emph{additional channels} to pull from. To use a channel, write
5092 @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it
5093 @emph{in addition} to the default Guix channel(s):
5095 @vindex %default-channels
5097 ;; Add variant packages to those Guix provides.
5099 (name 'variant-packages)
5100 (url "https://example.org/variant-packages.git"))
5105 Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
5106 add a channel the list of channels that the variable @code{%default-channels}
5107 is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
5108 Manual}). With this file in place, @command{guix pull} builds not only Guix
5109 but also the package modules from your own repository. The result in
5110 @file{~/.config/guix/current} is the union of Guix with your own package
5114 $ guix pull --list-generations
5116 Generation 19 Aug 27 2018 16:20:48
5118 repository URL: https://git.savannah.gnu.org/git/guix.git
5120 commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
5121 variant-packages dd3df5e
5122 repository URL: https://example.org/variant-packages.git
5124 commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
5125 11 new packages: variant-gimp, variant-emacs-with-cool-features, @dots{}
5126 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
5130 The output of @command{guix pull} above shows that Generation@tie{}19 includes
5131 both Guix and packages from the @code{variant-personal-packages} channel. Among
5132 the new and upgraded packages that are listed, some like @code{variant-gimp} and
5133 @code{variant-emacs-with-cool-features} might come from
5134 @code{variant-packages}, while others come from the Guix default channel.
5136 @node Using a Custom Guix Channel
5137 @section Using a Custom Guix Channel
5139 The channel called @code{guix} specifies where Guix itself---its command-line
5140 tools as well as its package collection---should be downloaded. For instance,
5141 suppose you want to update from another copy of the Guix repository at
5142 @code{example.org}, and specifically the @code{super-hacks} branch, you can
5143 write in @code{~/.config/guix/channels.scm} this specification:
5146 ;; Tell 'guix pull' to use another repo.
5149 (url "https://example.org/another-guix.git")
5150 (branch "super-hacks")))
5154 From there on, @command{guix pull} will fetch code from the @code{super-hacks}
5155 branch of the repository at @code{example.org}. The authentication concern is
5156 addressed below ((@pxref{Channel Authentication}).
5158 @node Replicating Guix
5159 @section Replicating Guix
5161 @cindex pinning, channels
5162 @cindex replicating Guix
5163 @cindex reproducibility, of Guix
5164 The @command{guix pull --list-generations} output above shows precisely which
5165 commits were used to build this instance of Guix. We can thus replicate it,
5166 say, on another machine, by providing a channel specification in
5167 @file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
5170 ;; Deploy specific commits of my channels of interest.
5173 (url "https://git.savannah.gnu.org/git/guix.git")
5174 (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
5176 (name 'variant-packages)
5177 (url "https://example.org/variant-packages.git")
5178 (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
5181 The @command{guix describe --format=channels} command can even generate this
5182 list of channels directly (@pxref{Invoking guix describe}). The resulting
5183 file can be used with the -C options of @command{guix pull}
5184 (@pxref{Invoking guix pull}) or @command{guix time-machine}
5185 (@pxref{Invoking guix time-machine}).
5187 At this point the two machines run the @emph{exact same Guix}, with access to
5188 the @emph{exact same packages}. The output of @command{guix build gimp} on
5189 one machine will be exactly the same, bit for bit, as the output of the same
5190 command on the other machine. It also means both machines have access to all
5191 the source code of Guix and, transitively, to all the source code of every
5194 This gives you super powers, allowing you to track the provenance of binary
5195 artifacts with very fine grain, and to reproduce software environments at
5196 will---some sort of ``meta reproducibility'' capabilities, if you will.
5197 @xref{Inferiors}, for another way to take advantage of these super powers.
5199 @node Channel Authentication
5200 @section Channel Authentication
5202 @anchor{channel-authentication}
5203 @cindex authentication, of channel code
5204 The @command{guix pull} and @command{guix time-machine} commands
5205 @dfn{authenticate} the code retrieved from channels: they make sure each
5206 commit that is fetched is signed by an authorized developer. The goal
5207 is to protect from unauthorized modifications to the channel that would
5208 lead users to run malicious code.
5210 As a user, you must provide a @dfn{channel introduction} in your
5211 channels file so that Guix knows how to authenticate its first commit.
5212 A channel specification, including its introduction, looks something
5217 (name 'some-channel)
5218 (url "https://example.org/some-channel.git")
5220 (make-channel-introduction
5221 "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
5222 (openpgp-fingerprint
5223 "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
5226 The specification above shows the name and URL of the channel. The call
5227 to @code{make-channel-introduction} above specifies that authentication
5228 of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
5229 by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
5231 For the main channel, called @code{guix}, you automatically get that
5232 information from your Guix installation. For other channels, include
5233 the channel introduction provided by the channel authors in your
5234 @file{channels.scm} file. Make sure you retrieve the channel
5235 introduction from a trusted source since that is the root of your trust.
5237 If you're curious about the authentication mechanics, read on!
5239 @node Channels with Substitutes
5240 @section Channels with Substitutes
5242 When running @command{guix pull}, Guix will first compile the
5243 definitions of every available package. This is an expensive operation
5244 for which substitutes (@pxref{Substitutes}) may be available. The
5245 following snippet in @file{channels.scm} will ensure that @command{guix
5246 pull} uses the latest commit with available substitutes for the package
5247 definitions: this is done by querying the continuous integration
5248 server at @url{https://ci.guix.gnu.org}.
5251 (use-modules (guix ci))
5253 (list (channel-with-substitutes-available
5254 %default-guix-channel
5255 "https://ci.guix.gnu.org"))
5258 Note that this does not mean that all the packages that you will
5259 install after running @command{guix pull} will have available
5260 substitutes. It only ensures that @command{guix pull} will not try to
5261 compile package definitions. This is particularly useful when using
5262 machines with limited resources.
5264 @node Creating a Channel
5265 @section Creating a Channel
5267 @cindex personal packages (channels)
5268 @cindex channels, for personal packages
5269 Let's say you have a bunch of custom package variants or personal packages
5270 that you think would make little sense to contribute to the Guix project, but
5271 would like to have these packages transparently available to you at the
5272 command line. You would first write modules containing those package
5273 definitions (@pxref{Package Modules}), maintain them in a Git repository, and
5274 then you and anyone else can use it as an additional channel to get packages
5277 @c What follows stems from discussions at
5278 @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
5279 @c earlier discussions on guix-devel@gnu.org.
5281 Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
5282 publish your personal channel to the world, we would like to share a few words
5287 Before publishing a channel, please consider contributing your package
5288 definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
5289 to free software of all sorts, and packages in Guix proper are readily
5290 available to all Guix users and benefit from the project's quality assurance
5294 When you maintain package definitions outside Guix, we, Guix developers,
5295 consider that @emph{the compatibility burden is on you}. Remember that
5296 package modules and package definitions are just Scheme code that uses various
5297 programming interfaces (APIs). We want to remain free to change these APIs to
5298 keep improving Guix, possibly in ways that break your channel. We never
5299 change APIs gratuitously, but we will @emph{not} commit to freezing APIs
5303 Corollary: if you're using an external channel and that channel breaks, please
5304 @emph{report the issue to the channel authors}, not to the Guix project.
5307 You've been warned! Having said this, we believe external channels are a
5308 practical way to exert your freedom to augment Guix' package collection and to
5309 share your improvements, which are basic tenets of
5310 @uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
5311 email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
5314 To create a channel, create a Git repository containing your own package
5315 modules and make it available. The repository can contain anything, but a
5316 useful channel will contain Guile modules that export packages. Once you
5317 start using a channel, Guix will behave as if the root directory of that
5318 channel's Git repository has been added to the Guile load path (@pxref{Load
5319 Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel
5320 contains a file at @file{my-packages/my-tools.scm} that defines a Guile
5321 module, then the module will be available under the name @code{(my-packages
5322 my-tools)}, and you will be able to use it like any other module
5323 (@pxref{Modules,,, guile, GNU Guile Reference Manual}).
5325 As a channel author, consider bundling authentication material with your
5326 channel so that users can authenticate it. @xref{Channel
5327 Authentication}, and @ref{Specifying Channel Authorizations}, for info
5331 @node Package Modules in a Sub-directory
5332 @section Package Modules in a Sub-directory
5334 @cindex subdirectory, channels
5335 As a channel author, you may want to keep your channel modules in a
5336 sub-directory. If your modules are in the sub-directory @file{guix}, you must
5337 add a meta-data file @file{.guix-channel} that contains:
5345 @node Declaring Channel Dependencies
5346 @section Declaring Channel Dependencies
5348 @cindex dependencies, channels
5349 @cindex meta-data, channels
5350 Channel authors may decide to augment a package collection provided by other
5351 channels. They can declare their channel to be dependent on other channels in
5352 a meta-data file @file{.guix-channel}, which is to be placed in the root of
5353 the channel repository.
5355 The meta-data file should contain a simple S-expression like this:
5362 (name some-collection)
5363 (url "https://example.org/first-collection.git")
5365 ;; The 'introduction' bit below is optional: you would
5366 ;; provide it for dependencies that can be authenticated.
5368 (channel-introduction
5370 (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
5371 (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
5373 (name some-other-collection)
5374 (url "https://example.org/second-collection.git")
5375 (branch "testing"))))
5378 In the above example this channel is declared to depend on two other channels,
5379 which will both be fetched automatically. The modules provided by the channel
5380 will be compiled in an environment where the modules of all these declared
5381 channels are available.
5383 For the sake of reliability and maintainability, you should avoid dependencies
5384 on channels that you don't control, and you should aim to keep the number of
5385 dependencies to a minimum.
5387 @node Specifying Channel Authorizations
5388 @section Specifying Channel Authorizations
5390 @cindex channel authorizations
5391 @anchor{channel-authorizations}
5392 As we saw above, Guix ensures the source code it pulls from channels
5393 comes from authorized developers. As a channel author, you need to
5394 specify the list of authorized developers in the
5395 @file{.guix-authorizations} file in the channel's Git repository. The
5396 authentication rule is simple: each commit must be signed by a key
5397 listed in the @file{.guix-authorizations} file of its parent
5398 commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
5399 (DAG). Each commit can have zero or more parents; ``regular'' commits
5400 have one parent and merge commits have two parent commits. Read
5401 @uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
5402 for Computer Scientists}} for a great overview.} The
5403 @file{.guix-authorizations} file looks like this:
5406 ;; Example '.guix-authorizations' file.
5409 (version 0) ;current file format version
5411 (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3"
5413 ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5"
5415 ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"
5419 Each fingerprint is followed by optional key/value pairs, as in the
5420 example above. Currently these key/value pairs are ignored.
5422 This authentication rule creates a chicken-and-egg issue: how do we
5423 authenticate the first commit? Related to that: how do we deal with
5424 channels whose repository history contains unsigned commits and lack
5425 @file{.guix-authorizations}? And how do we fork existing channels?
5427 @cindex channel introduction
5428 Channel introductions answer these questions by describing the first
5429 commit of a channel that should be authenticated. The first time a
5430 channel is fetched with @command{guix pull} or @command{guix
5431 time-machine}, the command looks up the introductory commit and verifies
5432 that it is signed by the specified OpenPGP key. From then on, it
5433 authenticates commits according to the rule above.
5435 Additionally, your channel must provide all the OpenPGP keys that were
5436 ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
5437 files, which can be either binary or ``ASCII-armored''. By default,
5438 those @file{.key} files are searched for in the branch named
5439 @code{keyring} but you can specify a different branch name in
5440 @code{.guix-channel} like so:
5445 (keyring-reference "my-keyring-branch"))
5448 To summarize, as the author of a channel, there are three things you have
5449 to do to allow users to authenticate your code:
5453 Export the OpenPGP keys of past and present committers with @command{gpg
5454 --export} and store them in @file{.key} files, by default in a branch
5455 named @code{keyring} (we recommend making it an @dfn{orphan branch}).
5458 Introduce an initial @file{.guix-authorizations} in the channel's
5459 repository. Do that in a signed commit (@pxref{Commit Access}, for
5460 information on how to sign Git commits.)
5463 Advertise the channel introduction, for instance on your channel's web
5464 page. The channel introduction, as we saw above, is the commit/key
5465 pair---i.e., the commit that introduced @file{.guix-authorizations}, and
5466 the fingerprint of the OpenPGP used to sign it.
5469 Before pushing to your public Git repository, you can run @command{guix
5470 git-authenticate} to verify that you did sign all the commits you are
5471 about to push with an authorized key:
5474 guix git authenticate @var{commit} @var{signer}
5478 where @var{commit} and @var{signer} are your channel introduction.
5479 @xref{Invoking guix git authenticate}, for details.
5481 Publishing a signed channel requires discipline: any mistake, such as an
5482 unsigned commit or a commit signed by an unauthorized key, will prevent
5483 users from pulling from your channel---well, that's the whole point of
5484 authentication! Pay attention to merges in particular: merge commits
5485 are considered authentic if and only if they are signed by a key present
5486 in the @file{.guix-authorizations} file of @emph{both} branches.
5489 @section Primary URL
5491 @cindex primary URL, channels
5492 Channel authors can indicate the primary URL of their channel's Git
5493 repository in the @file{.guix-channel} file, like so:
5498 (url "https://example.org/guix.git"))
5501 This allows @command{guix pull} to determine whether it is pulling code
5502 from a mirror of the channel; when that is the case, it warns the user
5503 that the mirror might be stale and displays the primary URL@. That way,
5504 users cannot be tricked into fetching code from a stale mirror that does
5505 not receive security updates.
5507 This feature only makes sense for authenticated repositories, such as
5508 the official @code{guix} channel, for which @command{guix pull} ensures
5509 the code it fetches is authentic.
5511 @node Writing Channel News
5512 @section Writing Channel News
5514 @cindex news, for channels
5515 Channel authors may occasionally want to communicate to their users
5516 information about important changes in the channel. You'd send them all
5517 an email, but that's not convenient.
5519 Instead, channels can provide a @dfn{news file}; when the channel users
5520 run @command{guix pull}, that news file is automatically read and
5521 @command{guix pull --news} can display the announcements that correspond
5522 to the new commits that have been pulled, if any.
5524 To do that, channel authors must first declare the name of the news file
5525 in their @file{.guix-channel} file:
5530 (news-file "etc/news.txt"))
5533 The news file itself, @file{etc/news.txt} in this example, must look
5534 something like this:
5539 (entry (tag "the-bug-fix")
5540 (title (en "Fixed terrible bug")
5542 (body (en "@@emph@{Good news@}! It's fixed!")
5543 (eo "Certe ĝi pli bone funkcias nun!")))
5544 (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
5545 (title (en "Added a great package")
5546 (ca "Què vol dir guix?"))
5547 (body (en "Don't miss the @@code@{hello@} package!"))))
5550 While the news file is using the Scheme syntax, avoid naming it with a
5551 @file{.scm} extension or else it will get picked up when building the
5552 channel and yield an error since it is not a valid module.
5553 Alternatively, you can move the channel module to a subdirectory and
5554 store the news file in another directory.
5556 The file consists of a list of @dfn{news entries}. Each entry is
5557 associated with a commit or tag: it describes changes made in this
5558 commit, possibly in preceding commits as well. Users see entries only
5559 the first time they obtain the commit the entry refers to.
5561 The @code{title} field should be a one-line summary while @code{body}
5562 can be arbitrarily long, and both can contain Texinfo markup
5563 (@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are
5564 a list of language tag/message tuples, which allows @command{guix pull}
5565 to display news in the language that corresponds to the user's locale.
5567 If you want to translate news using a gettext-based workflow, you can
5568 extract translatable strings with @command{xgettext} (@pxref{xgettext
5569 Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming
5570 you write news entries in English first, the command below creates a PO
5571 file containing the strings to translate:
5574 xgettext -o news.po -l scheme -ken etc/news.txt
5577 To sum up, yes, you could use your channel as a blog. But beware, this
5578 is @emph{not quite} what your users might expect.
5580 @c *********************************************************************
5582 @chapter Development
5584 @cindex software development
5585 If you are a software developer, Guix provides tools that you should find
5586 helpful---independently of the language you're developing in. This is what
5587 this chapter is about.
5589 The @command{guix shell} command provides a convenient way to set up
5590 one-off software environments, be it for development purposes or to run
5591 a command without installing it in your profile. The @command{guix
5592 pack} command allows you to create @dfn{application bundles} that can be
5593 easily distributed to users who do not run Guix.
5596 * Invoking guix shell:: Spawning one-off software environments.
5597 * Invoking guix environment:: Setting up development environments.
5598 * Invoking guix pack:: Creating software bundles.
5599 * The GCC toolchain:: Working with languages supported by GCC.
5600 * Invoking guix git authenticate:: Authenticating Git repositories.
5603 @node Invoking guix shell
5604 @section Invoking @command{guix shell}
5606 @cindex reproducible build environments
5607 @cindex development environments
5608 @cindex @command{guix environment}
5609 @cindex environment, package build environment
5610 The purpose of @command{guix shell} is to make it easy to create one-off
5611 software environments, without changing one's profile. It is typically
5612 used to create development environments; it is also a convenient way to
5613 run applications without ``polluting'' your profile.
5616 The @command{guix shell} command was recently introduced to supersede
5617 @command{guix environment} (@pxref{Invoking guix environment}). If you
5618 are familiar with @command{guix environment}, you will notice that it is
5619 similar but also---we hope!---more convenient.
5622 The general syntax is:
5625 guix shell [@var{options}] [@var{package}@dots{}]
5628 The following example creates an environment containing Python and NumPy,
5629 building or downloading any missing package, and runs the
5630 @command{python3} command in that environment:
5633 guix shell python python-numpy -- python3
5636 Development environments can be created as in the example below, which
5637 spawns an interactive shell containing all the dependencies and
5638 environment variables needed to work on Inkscape:
5641 guix shell --development inkscape
5644 Exiting the shell places the user back in the original environment
5645 before @command{guix shell} was invoked. The next garbage collection
5646 (@pxref{Invoking guix gc}) may clean up packages that were installed in
5647 the environment and that are no longer used outside of it.
5649 As an added convenience, when running from a directory that contains a
5650 @file{manifest.scm} or a @file{guix.scm} file (in this order), possibly
5651 in a parent directory, @command{guix shell} automatically loads the
5652 file---provided the directory is listed in
5653 @file{~/.config/guix/shell-authorized-directories}, and only for
5660 This provides an easy way to define, share, and enter development
5663 By default, the shell session or command runs in an @emph{augmented}
5664 environment, where the new packages are added to search path environment
5665 variables such as @code{PATH}. You can, instead, choose to create an
5666 @emph{isolated} environment containing nothing but the packages you
5667 asked for. Passing the @option{--pure} option clears environment
5668 variable definitions found in the parent environment@footnote{Be sure to
5669 use the @option{--check} option the first time you use @command{guix
5670 shell} interactively to make sure the shell does not undo the effect of
5671 @option{--pure}.}; passing @option{--container} goes one step further by
5672 spawning a @dfn{container} isolated from the rest of the system:
5675 guix shell --container emacs gcc-toolchain
5678 The command above spawns an interactive shell in a container where
5679 nothing but @code{emacs}, @code{gcc-toolchain}, and their dependencies
5680 is available. The container lacks network access and shares no files
5681 other than the current working directory with the surrounding
5682 environment. This is useful to prevent access to system-wide resources
5683 such as @file{/usr/bin} on foreign distros.
5685 This @option{--container} option can also prove useful if you wish to
5686 run a security-sensitive application, such as a web browser, in an
5687 isolated environment. For example, the command below launches
5688 Ungoogled-Chromium in an isolated environment, this time sharing network
5689 access with the host and preserving its @code{DISPLAY} environment
5690 variable, but without even sharing the current directory:
5693 guix shell --container --network --no-cwd ungoogled-chromium \
5694 --preserve='^DISPLAY$' -- chromium
5697 @vindex GUIX_ENVIRONMENT
5698 @command{guix shell} defines the @env{GUIX_ENVIRONMENT}
5699 variable in the shell it spawns; its value is the file name of the
5700 profile of this environment. This allows users to, say, define a
5701 specific prompt for development environments in their @file{.bashrc}
5702 (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
5705 if [ -n "$GUIX_ENVIRONMENT" ]
5707 export PS1="\u@@\h \w [dev]\$ "
5712 ...@: or to browse the profile:
5715 $ ls "$GUIX_ENVIRONMENT/bin"
5718 The available options are summarized below.
5722 Set up the environment and check whether the shell would clobber
5723 environment variables. It's a good idea to use this option the first
5724 time you run @command{guix shell} for an interactive session to make
5725 sure your setup is correct.
5727 For example, if the shell modifies the @env{PATH} environment variable,
5728 report it since you would get a different environment than what you
5731 Such problems usually indicate that the shell startup files are
5732 unexpectedly modifying those environment variables. For example, if you
5733 are using Bash, make sure that environment variables are set or modified
5734 in @file{~/.bash_profile} and @emph{not} in @file{~/.bashrc}---the
5735 former is sourced only by log-in shells. @xref{Bash Startup Files,,,
5736 bash, The GNU Bash Reference Manual}, for details on Bash start-up
5741 Cause @command{guix shell} to include in the environment the
5742 dependencies of the following package rather than the package itself.
5743 This can be combined with other packages. For instance, the command
5744 below starts an interactive shell containing the build-time dependencies
5745 of GNU@tie{}Guile, plus Autoconf, Automake, and Libtool:
5748 guix shell -D guile autoconf automake libtool
5751 @item --expression=@var{expr}
5752 @itemx -e @var{expr}
5753 Create an environment for the package or list of packages that
5754 @var{expr} evaluates to.
5756 For example, running:
5759 guix shell -D -e '(@@ (gnu packages maths) petsc-openmpi)'
5762 starts a shell with the environment for this specific variant of the
5768 guix shell -e '(@@ (gnu) %base-packages)'
5771 starts a shell with all the base system packages available.
5773 The above commands only use the default output of the given packages.
5774 To select other outputs, two element tuples can be specified:
5777 guix shell -e '(list (@@ (gnu packages bash) bash) "include")'
5780 @item --file=@var{file}
5781 @itemx -f @var{file}
5782 Create an environment containing the package or list of packages that
5783 the code within @var{file} evaluates to.
5785 As an example, @var{file} might contain a definition like this
5786 (@pxref{Defining Packages}):
5789 @verbatiminclude environment-gdb.scm
5792 With the file above, you can enter a development environment for GDB by
5796 guix shell -D -f gdb-devel.scm
5799 @item --manifest=@var{file}
5800 @itemx -m @var{file}
5801 Create an environment for the packages contained in the manifest object
5802 returned by the Scheme code in @var{file}. This option can be repeated
5803 several times, in which case the manifests are concatenated.
5805 This is similar to the same-named option in @command{guix package}
5806 (@pxref{profile-manifest, @option{--manifest}}) and uses the same
5809 @item --rebuild-cache
5810 When using @option{--manifest}, @option{--file}, or when invoked without
5811 arguments, @command{guix shell} caches the environment so that
5812 subsequent uses are instantaneous. The cache is invalidated anytime the
5815 The @option{--rebuild-cache} forces the cached environment to be
5816 refreshed even if the file has not changed. This is useful if the
5817 @command{guix.scm} or @command{manifest.scm} has external dependencies,
5818 or if its behavior depends, say, on environment variables.
5821 Unset existing environment variables when building the new environment, except
5822 those specified with @option{--preserve} (see below). This has the effect of
5823 creating an environment in which search paths only contain package inputs.
5825 @item --preserve=@var{regexp}
5826 @itemx -E @var{regexp}
5827 When used alongside @option{--pure}, preserve the environment variables
5828 matching @var{regexp}---in other words, put them on a ``white list'' of
5829 environment variables that must be preserved. This option can be repeated
5833 guix shell --pure --preserve=^SLURM openmpi @dots{} \
5837 This example runs @command{mpirun} in a context where the only environment
5838 variables defined are @env{PATH}, environment variables whose name starts
5839 with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
5842 @item --search-paths
5843 Display the environment variable definitions that make up the
5846 @item --system=@var{system}
5847 @itemx -s @var{system}
5848 Attempt to build for @var{system}---e.g., @code{i686-linux}.
5853 Run @var{command} within an isolated container. The current working
5854 directory outside the container is mapped inside the container.
5855 Additionally, unless overridden with @option{--user}, a dummy home
5856 directory is created that matches the current user's home directory, and
5857 @file{/etc/passwd} is configured accordingly.
5859 The spawned process runs as the current user outside the container. Inside
5860 the container, it has the same UID and GID as the current user, unless
5861 @option{--user} is passed (see below).
5865 For containers, share the network namespace with the host system.
5866 Containers created without this flag only have access to the loopback
5869 @item --link-profile
5871 For containers, link the environment profile to @file{~/.guix-profile}
5872 within the container and set @code{GUIX_ENVIRONMENT} to that.
5873 This is equivalent to making @file{~/.guix-profile} a symlink to the
5874 actual profile within the container.
5875 Linking will fail and abort the environment if the directory already
5876 exists, which will certainly be the case if @command{guix shell}
5877 was invoked in the user's home directory.
5879 Certain packages are configured to look in @file{~/.guix-profile} for
5880 configuration files and data;@footnote{For example, the
5881 @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
5882 for additional fonts.} @option{--link-profile} allows these programs to
5883 behave as expected within the environment.
5885 @item --user=@var{user}
5886 @itemx -u @var{user}
5887 For containers, use the username @var{user} in place of the current
5888 user. The generated @file{/etc/passwd} entry within the container will
5889 contain the name @var{user}, the home directory will be
5890 @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
5891 the UID and GID inside the container are 1000. @var{user}
5892 need not exist on the system.
5894 Additionally, any shared or exposed path (see @option{--share} and
5895 @option{--expose} respectively) whose target is within the current user's
5896 home directory will be remapped relative to @file{/home/USER}; this
5897 includes the automatic mapping of the current working directory.
5900 # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
5902 guix shell --container --user=foo \
5903 --expose=$HOME/test \
5904 --expose=/tmp/target=$HOME/target
5907 While this will limit the leaking of user identity through home paths
5908 and each of the user fields, this is only one useful component of a
5909 broader privacy/anonymity solution---not one in and of itself.
5912 For containers, the default behavior is to share the current working
5913 directory with the isolated container and immediately change to that
5914 directory within the container. If this is undesirable,
5915 @option{--no-cwd} will cause the current working directory to @emph{not}
5916 be automatically shared and will change to the user's home directory
5917 within the container instead. See also @option{--user}.
5919 @item --expose=@var{source}[=@var{target}]
5920 @itemx --share=@var{source}[=@var{target}]
5921 For containers, @option{--expose} (resp. @option{--share}) exposes the
5922 file system @var{source} from the host system as the read-only
5923 (resp. writable) file system @var{target} within the container. If
5924 @var{target} is not specified, @var{source} is used as the target mount
5925 point in the container.
5927 The example below spawns a Guile REPL in a container in which the user's
5928 home directory is accessible read-only via the @file{/exchange}
5932 guix shell --container --expose=$HOME=/exchange guile -- guile
5935 @item --root=@var{file}
5936 @itemx -r @var{file}
5937 @cindex persistent environment
5938 @cindex garbage collector root, for environments
5939 Make @var{file} a symlink to the profile for this environment, and
5940 register it as a garbage collector root.
5942 This is useful if you want to protect your environment from garbage
5943 collection, to make it ``persistent''.
5945 When this option is omitted, the environment is protected from garbage
5946 collection only for the duration of the @command{guix shell}
5947 session. This means that next time you recreate the same environment,
5948 you could have to rebuild or re-download packages. @xref{Invoking guix
5949 gc}, for more on GC roots.
5952 @command{guix shell} also supports all of the common build options that
5953 @command{guix build} supports (@pxref{Common Build Options}) as well as
5954 package transformation options (@pxref{Package Transformation Options}).
5956 @node Invoking guix environment
5957 @section Invoking @command{guix environment}
5959 The purpose of @command{guix environment} is to assist in creating
5960 development environments.
5962 @quotation Deprecation warning
5963 The @command{guix environment} command is deprecated in favor of
5964 @command{guix shell}, which performs similar functions but is more
5965 convenient to use. @xref{Invoking guix shell}.
5967 Being deprecated, @command{guix environment} is slated for eventual
5968 removal, but the Guix project is committed to keeping it until May 1st,
5969 2023. Please get in touch with us at @email{guix-devel@@gnu.org} if you
5970 would like to discuss it.
5973 The general syntax is:
5976 guix environment @var{options} @var{package}@dots{}
5979 The following example spawns a new shell set up for the development of
5983 guix environment guile
5986 If the needed dependencies are not built yet, @command{guix environment}
5987 automatically builds them. The environment of the new shell is an
5988 augmented version of the environment that @command{guix environment} was
5989 run in. It contains the necessary search paths for building the given
5990 package added to the existing environment variables. To create
5991 a ``pure'' environment, in which the original environment variables have
5992 been unset, use the @option{--pure} option@footnote{Users sometimes
5993 wrongfully augment environment variables such as @env{PATH} in their
5994 @file{~/.bashrc} file. As a consequence, when @command{guix
5995 environment} launches it, Bash may read @file{~/.bashrc}, thereby
5996 introducing ``impurities'' in these environment variables. It is an
5997 error to define such environment variables in @file{.bashrc}; instead,
5998 they should be defined in @file{.bash_profile}, which is sourced only by
5999 log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference
6000 Manual}, for details on Bash start-up files.}.
6002 Exiting from a Guix environment is the same as exiting from the shell,
6003 and will place the user back in the old environment before @command{guix
6004 environment} was invoked. The next garbage collection (@pxref{Invoking
6005 guix gc}) will clean up packages that were installed from within the
6006 environment and are no longer used outside of it.
6008 @vindex GUIX_ENVIRONMENT
6009 @command{guix environment} defines the @env{GUIX_ENVIRONMENT}
6010 variable in the shell it spawns; its value is the file name of the
6011 profile of this environment. This allows users to, say, define a
6012 specific prompt for development environments in their @file{.bashrc}
6013 (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
6016 if [ -n "$GUIX_ENVIRONMENT" ]
6018 export PS1="\u@@\h \w [dev]\$ "
6023 ...@: or to browse the profile:
6026 $ ls "$GUIX_ENVIRONMENT/bin"
6029 Additionally, more than one package may be specified, in which case the
6030 union of the inputs for the given packages are used. For example, the
6031 command below spawns a shell where all of the dependencies of both Guile
6032 and Emacs are available:
6035 guix environment guile emacs
6038 Sometimes an interactive shell session is not desired. An arbitrary
6039 command may be invoked by placing the @code{--} token to separate the
6040 command from the rest of the arguments:
6043 guix environment guile -- make -j4
6046 In other situations, it is more convenient to specify the list of
6047 packages needed in the environment. For example, the following command
6048 runs @command{python} from an environment containing Python@tie{}3 and
6052 guix environment --ad-hoc python-numpy python -- python3
6055 Furthermore, one might want the dependencies of a package and also some
6056 additional packages that are not build-time or runtime dependencies, but
6057 are useful when developing nonetheless. Because of this, the
6058 @option{--ad-hoc} flag is positional. Packages appearing before
6059 @option{--ad-hoc} are interpreted as packages whose dependencies will be
6060 added to the environment. Packages appearing after are interpreted as
6061 packages that will be added to the environment directly. For example,
6062 the following command creates a Guix development environment that
6063 additionally includes Git and strace:
6066 guix environment --pure guix --ad-hoc git strace
6070 Sometimes it is desirable to isolate the environment as much as
6071 possible, for maximal purity and reproducibility. In particular, when
6072 using Guix on a host distro that is not Guix System, it is desirable to
6073 prevent access to @file{/usr/bin} and other system-wide resources from
6074 the development environment. For example, the following command spawns
6075 a Guile REPL in a ``container'' where only the store and the current
6076 working directory are mounted:
6079 guix environment --ad-hoc --container guile -- guile
6083 The @option{--container} option requires Linux-libre 3.19 or newer.
6086 @cindex certificates
6087 Another typical use case for containers is to run security-sensitive
6088 applications such as a web browser. To run Eolie, we must expose and
6089 share some files and directories; we include @code{nss-certs} and expose
6090 @file{/etc/ssl/certs/} for HTTPS authentication; finally we preserve the
6091 @env{DISPLAY} environment variable since containerized graphical
6092 applications won't display without it.
6095 guix environment --preserve='^DISPLAY$' --container --network \
6096 --expose=/etc/machine-id \
6097 --expose=/etc/ssl/certs/ \
6098 --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
6099 --ad-hoc eolie nss-certs dbus -- eolie
6102 The available options are summarized below.
6106 Set up the environment and check whether the shell would clobber
6107 environment variables. @xref{Invoking guix shell, @option{--check}},
6110 @item --root=@var{file}
6111 @itemx -r @var{file}
6112 @cindex persistent environment
6113 @cindex garbage collector root, for environments
6114 Make @var{file} a symlink to the profile for this environment, and
6115 register it as a garbage collector root.
6117 This is useful if you want to protect your environment from garbage
6118 collection, to make it ``persistent''.
6120 When this option is omitted, the environment is protected from garbage
6121 collection only for the duration of the @command{guix environment}
6122 session. This means that next time you recreate the same environment,
6123 you could have to rebuild or re-download packages. @xref{Invoking guix
6124 gc}, for more on GC roots.
6126 @item --expression=@var{expr}
6127 @itemx -e @var{expr}
6128 Create an environment for the package or list of packages that
6129 @var{expr} evaluates to.
6131 For example, running:
6134 guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
6137 starts a shell with the environment for this specific variant of the
6143 guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
6146 starts a shell with all the base system packages available.
6148 The above commands only use the default output of the given packages.
6149 To select other outputs, two element tuples can be specified:
6152 guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
6155 @item --load=@var{file}
6156 @itemx -l @var{file}
6157 Create an environment for the package or list of packages that the code
6158 within @var{file} evaluates to.
6160 As an example, @var{file} might contain a definition like this
6161 (@pxref{Defining Packages}):
6164 @verbatiminclude environment-gdb.scm
6167 @item --manifest=@var{file}
6168 @itemx -m @var{file}
6169 Create an environment for the packages contained in the manifest object
6170 returned by the Scheme code in @var{file}. This option can be repeated
6171 several times, in which case the manifests are concatenated.
6173 This is similar to the same-named option in @command{guix package}
6174 (@pxref{profile-manifest, @option{--manifest}}) and uses the same
6178 Include all specified packages in the resulting environment, as if an
6179 @i{ad hoc} package were defined with them as inputs. This option is
6180 useful for quickly creating an environment without having to write a
6181 package expression to contain the desired inputs.
6183 For instance, the command:
6186 guix environment --ad-hoc guile guile-sdl -- guile
6189 runs @command{guile} in an environment where Guile and Guile-SDL are
6192 Note that this example implicitly asks for the default output of
6193 @code{guile} and @code{guile-sdl}, but it is possible to ask for a
6194 specific output---e.g., @code{glib:bin} asks for the @code{bin} output
6195 of @code{glib} (@pxref{Packages with Multiple Outputs}).
6197 This option may be composed with the default behavior of @command{guix
6198 environment}. Packages appearing before @option{--ad-hoc} are
6199 interpreted as packages whose dependencies will be added to the
6200 environment, the default behavior. Packages appearing after are
6201 interpreted as packages that will be added to the environment directly.
6204 Unset existing environment variables when building the new environment, except
6205 those specified with @option{--preserve} (see below). This has the effect of
6206 creating an environment in which search paths only contain package inputs.
6208 @item --preserve=@var{regexp}
6209 @itemx -E @var{regexp}
6210 When used alongside @option{--pure}, preserve the environment variables
6211 matching @var{regexp}---in other words, put them on a ``white list'' of
6212 environment variables that must be preserved. This option can be repeated
6216 guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \
6220 This example runs @command{mpirun} in a context where the only environment
6221 variables defined are @env{PATH}, environment variables whose name starts
6222 with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
6225 @item --search-paths
6226 Display the environment variable definitions that make up the
6229 @item --system=@var{system}
6230 @itemx -s @var{system}
6231 Attempt to build for @var{system}---e.g., @code{i686-linux}.
6236 Run @var{command} within an isolated container. The current working
6237 directory outside the container is mapped inside the container.
6238 Additionally, unless overridden with @option{--user}, a dummy home
6239 directory is created that matches the current user's home directory, and
6240 @file{/etc/passwd} is configured accordingly.
6242 The spawned process runs as the current user outside the container. Inside
6243 the container, it has the same UID and GID as the current user, unless
6244 @option{--user} is passed (see below).
6248 For containers, share the network namespace with the host system.
6249 Containers created without this flag only have access to the loopback
6252 @item --link-profile
6254 For containers, link the environment profile to @file{~/.guix-profile}
6255 within the container and set @code{GUIX_ENVIRONMENT} to that.
6256 This is equivalent to making @file{~/.guix-profile} a symlink to the
6257 actual profile within the container.
6258 Linking will fail and abort the environment if the directory already
6259 exists, which will certainly be the case if @command{guix environment}
6260 was invoked in the user's home directory.
6262 Certain packages are configured to look in @file{~/.guix-profile} for
6263 configuration files and data;@footnote{For example, the
6264 @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
6265 for additional fonts.} @option{--link-profile} allows these programs to
6266 behave as expected within the environment.
6268 @item --user=@var{user}
6269 @itemx -u @var{user}
6270 For containers, use the username @var{user} in place of the current
6271 user. The generated @file{/etc/passwd} entry within the container will
6272 contain the name @var{user}, the home directory will be
6273 @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
6274 the UID and GID inside the container are 1000. @var{user}
6275 need not exist on the system.
6277 Additionally, any shared or exposed path (see @option{--share} and
6278 @option{--expose} respectively) whose target is within the current user's
6279 home directory will be remapped relative to @file{/home/USER}; this
6280 includes the automatic mapping of the current working directory.
6283 # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
6285 guix environment --container --user=foo \
6286 --expose=$HOME/test \
6287 --expose=/tmp/target=$HOME/target
6290 While this will limit the leaking of user identity through home paths
6291 and each of the user fields, this is only one useful component of a
6292 broader privacy/anonymity solution---not one in and of itself.
6295 For containers, the default behavior is to share the current working
6296 directory with the isolated container and immediately change to that
6297 directory within the container. If this is undesirable,
6298 @option{--no-cwd} will cause the current working directory to @emph{not}
6299 be automatically shared and will change to the user's home directory
6300 within the container instead. See also @option{--user}.
6302 @item --expose=@var{source}[=@var{target}]
6303 @itemx --share=@var{source}[=@var{target}]
6304 For containers, @option{--expose} (resp. @option{--share}) exposes the
6305 file system @var{source} from the host system as the read-only
6306 (resp. writable) file system @var{target} within the container. If
6307 @var{target} is not specified, @var{source} is used as the target mount
6308 point in the container.
6310 The example below spawns a Guile REPL in a container in which the user's
6311 home directory is accessible read-only via the @file{/exchange}
6315 guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
6320 @command{guix environment}
6321 also supports all of the common build options that @command{guix
6322 build} supports (@pxref{Common Build Options}) as well as package
6323 transformation options (@pxref{Package Transformation Options}).
6325 @node Invoking guix pack
6326 @section Invoking @command{guix pack}
6328 Occasionally you want to pass software to people who are not (yet!)
6329 lucky enough to be using Guix. You'd tell them to run @command{guix
6330 package -i @var{something}}, but that's not possible in this case. This
6331 is where @command{guix pack} comes in.
6334 If you are looking for ways to exchange binaries among machines that
6335 already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
6336 publish}, and @ref{Invoking guix archive}.
6341 @cindex application bundle
6342 @cindex software bundle
6343 The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
6344 @dfn{software bundle}: it creates a tarball or some other archive
6345 containing the binaries of the software you're interested in, and all
6346 its dependencies. The resulting archive can be used on any machine that
6347 does not have Guix, and people can run the exact same binaries as those
6348 you have with Guix. The pack itself is created in a bit-reproducible
6349 fashion, so anyone can verify that it really contains the build results
6350 that you pretend to be shipping.
6352 For example, to create a bundle containing Guile, Emacs, Geiser, and all
6353 their dependencies, you can run:
6356 $ guix pack guile emacs emacs-geiser
6358 /gnu/store/@dots{}-pack.tar.gz
6361 The result here is a tarball containing a @file{/gnu/store} directory
6362 with all the relevant packages. The resulting tarball contains a
6363 @dfn{profile} with the three packages of interest; the profile is the
6364 same as would be created by @command{guix package -i}. It is this
6365 mechanism that is used to create Guix's own standalone binary tarball
6366 (@pxref{Binary Installation}).
6368 Users of this pack would have to run
6369 @file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
6370 find inconvenient. To work around it, you can create, say, a
6371 @file{/opt/gnu/bin} symlink to the profile:
6374 guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser
6378 That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
6380 @cindex relocatable binaries, with @command{guix pack}
6381 What if the recipient of your pack does not have root privileges on
6382 their machine, and thus cannot unpack it in the root file system? In
6383 that case, you will want to use the @option{--relocatable} option (see
6384 below). This option produces @dfn{relocatable binaries}, meaning they
6385 they can be placed anywhere in the file system hierarchy: in the example
6386 above, users can unpack your tarball in their home directory and
6387 directly run @file{./opt/gnu/bin/guile}.
6389 @cindex Docker, build an image with guix pack
6390 Alternatively, you can produce a pack in the Docker image format using
6391 the following command:
6394 guix pack -f docker -S /bin=bin guile guile-readline
6398 The result is a tarball that can be passed to the @command{docker load}
6399 command, followed by @code{docker run}:
6402 docker load < @var{file}
6403 docker run -ti guile-guile-readline /bin/guile
6407 where @var{file} is the image returned by @var{guix pack}, and
6408 @code{guile-guile-readline} is its ``image tag''. See the
6409 @uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
6410 documentation} for more information.
6412 @cindex Singularity, build an image with guix pack
6413 @cindex SquashFS, build an image with guix pack
6414 Yet another option is to produce a SquashFS image with the following
6418 guix pack -f squashfs bash guile emacs emacs-geiser
6422 The result is a SquashFS file system image that can either be mounted or
6423 directly be used as a file system container image with the
6424 @uref{https://www.sylabs.io/docs/, Singularity container execution
6425 environment}, using commands like @command{singularity shell} or
6426 @command{singularity exec}.
6428 Several command-line options allow you to customize your pack:
6431 @item --format=@var{format}
6432 @itemx -f @var{format}
6433 Produce a pack in the given @var{format}.
6435 The available formats are:
6439 This is the default format. It produces a tarball containing all the
6440 specified binaries and symlinks.
6443 This produces a tarball that follows the
6444 @uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
6445 Docker Image Specification}. The ``repository name'' as it appears in
6446 the output of the @command{docker images} command is computed from
6447 package names passed on the command line or in the manifest file.
6450 This produces a SquashFS image containing all the specified binaries and
6451 symlinks, as well as empty mount points for virtual file systems like
6455 Singularity @emph{requires} you to provide @file{/bin/sh} in the image.
6456 For that reason, @command{guix pack -f squashfs} always implies @code{-S
6457 /bin=bin}. Thus, your @command{guix pack} invocation must always start
6458 with something like:
6461 guix pack -f squashfs bash @dots{}
6464 If you forget the @code{bash} (or similar) package, @command{singularity
6465 run} and @command{singularity exec} will fail with an unhelpful ``no
6466 such file or directory'' message.
6470 This produces a Debian archive (a package with the @samp{.deb} file
6471 extension) containing all the specified binaries and symbolic links,
6472 that can be installed on top of any dpkg-based GNU(/Linux) distribution.
6473 Advanced options can be revealed via the @option{--help-deb-format}
6474 option. They allow embedding control files for more fine-grained
6475 control, such as activating specific triggers or providing a maintainer
6476 configure script to run arbitrary setup code upon installation.
6479 guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello
6483 Because archives produced with @command{guix pack} contain a collection
6484 of store items and because each @command{dpkg} package must not have
6485 conflicting files, in practice that means you likely won't be able to
6486 install more than one such archive on a given system.
6490 @command{dpkg} will assume ownership of any files contained in the pack
6491 that it does @emph{not} know about. It is unwise to install
6492 Guix-produced @samp{.deb} files on a system where @file{/gnu/store} is
6493 shared by other software, such as a Guix installation or other, non-deb
6499 @cindex relocatable binaries
6502 Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
6503 anywhere in the file system hierarchy and run from there.
6505 When this option is passed once, the resulting binaries require support for
6506 @dfn{user namespaces} in the kernel Linux; when passed
6507 @emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds
6508 PRoot support, can be thought of as the abbreviation of ``Really
6509 Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to
6510 other techniques if user namespaces are unavailable, and essentially
6511 work anywhere---see below for the implications.
6513 For example, if you create a pack containing Bash with:
6516 guix pack -RR -S /mybin=bin bash
6520 ...@: you can copy that pack to a machine that lacks Guix, and from your
6521 home directory as a normal user, run:
6529 In that shell, if you type @code{ls /gnu/store}, you'll notice that
6530 @file{/gnu/store} shows up and contains all the dependencies of
6531 @code{bash}, even though the machine actually lacks @file{/gnu/store}
6532 altogether! That is probably the simplest way to deploy Guix-built
6533 software on a non-Guix machine.
6536 By default, relocatable binaries rely on the @dfn{user namespace} feature of
6537 the kernel Linux, which allows unprivileged users to mount or change root.
6538 Old versions of Linux did not support it, and some GNU/Linux distributions
6541 To produce relocatable binaries that work even in the absence of user
6542 namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In that
6543 case, binaries will try user namespace support and fall back to another
6544 @dfn{execution engine} if user namespaces are not supported. The
6545 following execution engines are supported:
6549 Try user namespaces and fall back to PRoot if user namespaces are not
6550 supported (see below).
6553 Try user namespaces and fall back to Fakechroot if user namespaces are
6554 not supported (see below).
6557 Run the program through user namespaces and abort if they are not
6561 Run through PRoot. The @uref{https://proot-me.github.io/, PRoot} program
6562 provides the necessary
6563 support for file system virtualization. It achieves that by using the
6564 @code{ptrace} system call on the running program. This approach has the
6565 advantage to work without requiring special kernel support, but it incurs
6566 run-time overhead every time a system call is made.
6569 Run through Fakechroot. @uref{https://github.com/dex4er/fakechroot/,
6570 Fakechroot} virtualizes file system accesses by intercepting calls to C
6571 library functions such as @code{open}, @code{stat}, @code{exec}, and so
6572 on. Unlike PRoot, it incurs very little overhead. However, it does not
6573 always work: for example, some file system accesses made from within the
6574 C library are not intercepted, and file system accesses made @i{via}
6575 direct syscalls are not intercepted either, leading to erratic behavior.
6578 @vindex GUIX_EXECUTION_ENGINE
6579 When running a wrapped program, you can explicitly request one of the
6580 execution engines listed above by setting the
6581 @env{GUIX_EXECUTION_ENGINE} environment variable accordingly.
6584 @cindex entry point, for Docker images
6585 @item --entry-point=@var{command}
6586 Use @var{command} as the @dfn{entry point} of the resulting pack, if the pack
6587 format supports it---currently @code{docker} and @code{squashfs} (Singularity)
6588 support it. @var{command} must be relative to the profile contained in the
6591 The entry point specifies the command that tools like @code{docker run} or
6592 @code{singularity run} automatically start by default. For example, you can
6596 guix pack -f docker --entry-point=bin/guile guile
6599 The resulting pack can easily be loaded and @code{docker run} with no extra
6600 arguments will spawn @code{bin/guile}:
6603 docker load -i pack.tar.gz
6604 docker run @var{image-id}
6607 @item --expression=@var{expr}
6608 @itemx -e @var{expr}
6609 Consider the package @var{expr} evaluates to.
6611 This has the same purpose as the same-named option in @command{guix
6612 build} (@pxref{Additional Build Options, @option{--expression} in
6613 @command{guix build}}).
6615 @item --manifest=@var{file}
6616 @itemx -m @var{file}
6617 Use the packages contained in the manifest object returned by the Scheme
6618 code in @var{file}. This option can be repeated several times, in which
6619 case the manifests are concatenated.
6621 This has a similar purpose as the same-named option in @command{guix
6622 package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
6623 same manifest files. It allows you to define a collection of packages
6624 once and use it both for creating profiles and for creating archives
6625 for use on machines that do not have Guix installed. Note that you can
6626 specify @emph{either} a manifest file @emph{or} a list of packages,
6629 @item --system=@var{system}
6630 @itemx -s @var{system}
6631 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
6632 the system type of the build host.
6634 @item --target=@var{triplet}
6635 @cindex cross-compilation
6636 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
6637 as @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets, GNU
6638 configuration triplets,, autoconf, Autoconf}).
6640 @item --compression=@var{tool}
6641 @itemx -C @var{tool}
6642 Compress the resulting tarball using @var{tool}---one of @code{gzip},
6643 @code{zstd}, @code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no
6646 @item --symlink=@var{spec}
6647 @itemx -S @var{spec}
6648 Add the symlinks specified by @var{spec} to the pack. This option can
6649 appear several times.
6651 @var{spec} has the form @code{@var{source}=@var{target}}, where
6652 @var{source} is the symlink that will be created and @var{target} is the
6655 For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
6656 symlink pointing to the @file{bin} sub-directory of the profile.
6658 @item --save-provenance
6659 Save provenance information for the packages passed on the command line.
6660 Provenance information includes the URL and commit of the channels in use
6663 Provenance information is saved in the
6664 @file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the
6665 usual package metadata---the name and version of each package, their
6666 propagated inputs, and so on. It is useful information to the recipient of
6667 the pack, who then knows how the pack was (supposedly) obtained.
6669 This option is not enabled by default because, like timestamps, provenance
6670 information contributes nothing to the build process. In other words, there
6671 is an infinity of channel URLs and commit IDs that can lead to the same pack.
6672 Recording such ``silent'' metadata in the output thus potentially breaks the
6673 source-to-binary bitwise reproducibility property.
6675 @item --root=@var{file}
6676 @itemx -r @var{file}
6677 @cindex garbage collector root, for packs
6678 Make @var{file} a symlink to the resulting pack, and register it as a garbage
6681 @item --localstatedir
6682 @itemx --profile-name=@var{name}
6683 Include the ``local state directory'', @file{/var/guix}, in the resulting
6684 pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
6685 profile---by default @var{name} is @code{guix-profile}, which corresponds to
6686 @file{~root/.guix-profile}.
6688 @file{/var/guix} contains the store database (@pxref{The Store}) as well
6689 as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in
6690 the pack means that the store is ``complete'' and manageable by Guix;
6691 not providing it pack means that the store is ``dead'': items cannot be
6692 added to it or removed from it after extraction of the pack.
6694 One use case for this is the Guix self-contained binary tarball
6695 (@pxref{Binary Installation}).
6699 Print the name of the derivation that builds the pack.
6702 Use the bootstrap binaries to build the pack. This option is only
6703 useful to Guix developers.
6706 In addition, @command{guix pack} supports all the common build options
6707 (@pxref{Common Build Options}) and all the package transformation
6708 options (@pxref{Package Transformation Options}).
6711 @node The GCC toolchain
6712 @section The GCC toolchain
6716 @cindex linker wrapper
6717 @cindex toolchain, for C development
6718 @cindex toolchain, for Fortran development
6720 If you need a complete toolchain for compiling and linking C or C++
6721 source code, use the @code{gcc-toolchain} package. This package
6722 provides a complete GCC toolchain for C/C++ development, including GCC
6723 itself, the GNU C Library (headers and binaries, plus debugging symbols
6724 in the @code{debug} output), Binutils, and a linker wrapper.
6726 The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
6727 passed to the linker, add corresponding @code{-rpath} arguments, and
6728 invoke the actual linker with this new set of arguments. You can instruct the
6729 wrapper to refuse to link against libraries not in the store by setting the
6730 @env{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
6732 The package @code{gfortran-toolchain} provides a complete GCC toolchain
6733 for Fortran development. For other languages, please use
6734 @samp{guix search gcc toolchain} (@pxref{guix-search,, Invoking guix package}).
6737 @node Invoking guix git authenticate
6738 @section Invoking @command{guix git authenticate}
6740 The @command{guix git authenticate} command authenticates a Git checkout
6741 following the same rule as for channels (@pxref{channel-authentication,
6742 channel authentication}). That is, starting from a given commit, it
6743 ensures that all subsequent commits are signed by an OpenPGP key whose
6744 fingerprint appears in the @file{.guix-authorizations} file of its
6747 You will find this command useful if you maintain a channel. But in
6748 fact, this authentication mechanism is useful in a broader context, so
6749 you might want to use it for Git repositories that have nothing to do
6752 The general syntax is:
6755 guix git authenticate @var{commit} @var{signer} [@var{options}@dots{}]
6758 By default, this command authenticates the Git checkout in the current
6759 directory; it outputs nothing and exits with exit code zero on success
6760 and non-zero on failure. @var{commit} above denotes the first commit
6761 where authentication takes place, and @var{signer} is the OpenPGP
6762 fingerprint of public key used to sign @var{commit}. Together, they
6763 form a ``channel introduction'' (@pxref{channel-authentication, channel
6764 introduction}). The options below allow you to fine-tune the process.
6767 @item --repository=@var{directory}
6768 @itemx -r @var{directory}
6769 Open the Git repository in @var{directory} instead of the current
6772 @item --keyring=@var{reference}
6773 @itemx -k @var{reference}
6774 Load OpenPGP keyring from @var{reference}, the reference of a branch
6775 such as @code{origin/keyring} or @code{my-keyring}. The branch must
6776 contain OpenPGP public keys in @file{.key} files, either in binary form
6777 or ``ASCII-armored''. By default the keyring is loaded from the branch
6778 named @code{keyring}.
6781 Display commit signing statistics upon completion.
6783 @item --cache-key=@var{key}
6784 Previously-authenticated commits are cached in a file under
6785 @file{~/.cache/guix/authentication}. This option forces the cache to be
6786 stored in file @var{key} in that directory.
6788 @item --historical-authorizations=@var{file}
6789 By default, any commit whose parent commit(s) lack the
6790 @file{.guix-authorizations} file is considered inauthentic. In
6791 contrast, this option considers the authorizations in @var{file} for any
6792 commit that lacks @file{.guix-authorizations}. The format of @var{file}
6793 is the same as that of @file{.guix-authorizations}
6794 (@pxref{channel-authorizations, @file{.guix-authorizations} format}).
6798 @c *********************************************************************
6799 @node Programming Interface
6800 @chapter Programming Interface
6802 GNU Guix provides several Scheme programming interfaces (APIs) to
6803 define, build, and query packages. The first interface allows users to
6804 write high-level package definitions. These definitions refer to
6805 familiar packaging concepts, such as the name and version of a package,
6806 its build system, and its dependencies. These definitions can then be
6807 turned into concrete build actions.
6809 Build actions are performed by the Guix daemon, on behalf of users. In a
6810 standard setup, the daemon has write access to the store---the
6811 @file{/gnu/store} directory---whereas users do not. The recommended
6812 setup also has the daemon perform builds in chroots, under specific
6813 build users, to minimize interference with the rest of the system.
6816 Lower-level APIs are available to interact with the daemon and the
6817 store. To instruct the daemon to perform a build action, users actually
6818 provide it with a @dfn{derivation}. A derivation is a low-level
6819 representation of the build actions to be taken, and the environment in
6820 which they should occur---derivations are to package definitions what
6821 assembly is to C programs. The term ``derivation'' comes from the fact
6822 that build results @emph{derive} from them.
6824 This chapter describes all these APIs in turn, starting from high-level
6825 package definitions.
6828 * Package Modules:: Packages from the programmer's viewpoint.
6829 * Defining Packages:: Defining new packages.
6830 * Defining Package Variants:: Customizing packages.
6831 * Build Systems:: Specifying how packages are built.
6832 * Build Phases:: Phases of the build process of a package.
6833 * Build Utilities:: Helpers for your package definitions and more.
6834 * The Store:: Manipulating the package store.
6835 * Derivations:: Low-level interface to package derivations.
6836 * The Store Monad:: Purely functional interface to the store.
6837 * G-Expressions:: Manipulating build expressions.
6838 * Invoking guix repl:: Programming Guix in Guile
6841 @node Package Modules
6842 @section Package Modules
6844 From a programming viewpoint, the package definitions of the
6845 GNU distribution are provided by Guile modules in the @code{(gnu packages
6846 @dots{})} name space@footnote{Note that packages under the @code{(gnu
6847 packages @dots{})} module name space are not necessarily ``GNU
6848 packages''. This module naming scheme follows the usual Guile module
6849 naming convention: @code{gnu} means that these modules are distributed
6850 as part of the GNU system, and @code{packages} identifies modules that
6851 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
6852 Reference Manual}). For instance, the @code{(gnu packages emacs)}
6853 module exports a variable named @code{emacs}, which is bound to a
6854 @code{<package>} object (@pxref{Defining Packages}).
6856 The @code{(gnu packages @dots{})} module name space is
6857 automatically scanned for packages by the command-line tools. For
6858 instance, when running @code{guix install emacs}, all the @code{(gnu
6859 packages @dots{})} modules are scanned until one that exports a package
6860 object whose name is @code{emacs} is found. This package search
6861 facility is implemented in the @code{(gnu packages)} module.
6863 @cindex customization, of packages
6864 @cindex package module search path
6865 Users can store package definitions in modules with different
6866 names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
6867 name and module name must match. For instance, the @code{(my-packages
6868 emacs)} module must be stored in a @file{my-packages/emacs.scm} file
6869 relative to the load path specified with @option{--load-path} or
6870 @env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
6871 guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
6872 these package definitions visible to the user interfaces:
6876 By adding the directory containing your package modules to the search path
6877 with the @code{-L} flag of @command{guix package} and other commands
6878 (@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH}
6879 environment variable described below.
6882 By defining a @dfn{channel} and configuring @command{guix pull} so that it
6883 pulls from it. A channel is essentially a Git repository containing package
6884 modules. @xref{Channels}, for more information on how to define and use
6888 @env{GUIX_PACKAGE_PATH} works similarly to other search path variables:
6890 @defvr {Environment Variable} GUIX_PACKAGE_PATH
6891 This is a colon-separated list of directories to search for additional
6892 package modules. Directories listed in this variable take precedence
6893 over the own modules of the distribution.
6896 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
6897 each package is built based solely on other packages in the
6898 distribution. The root of this dependency graph is a small set of
6899 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
6900 bootstrap)} module. For more information on bootstrapping,
6901 @pxref{Bootstrapping}.
6903 @node Defining Packages
6904 @section Defining Packages
6906 The high-level interface to package definitions is implemented in the
6907 @code{(guix packages)} and @code{(guix build-system)} modules. As an
6908 example, the package definition, or @dfn{recipe}, for the GNU Hello
6909 package looks like this:
6912 (define-module (gnu packages hello)
6913 #:use-module (guix packages)
6914 #:use-module (guix download)
6915 #:use-module (guix build-system gnu)
6916 #:use-module (guix licenses)
6917 #:use-module (gnu packages gawk))
6919 (define-public hello
6925 (uri (string-append "mirror://gnu/hello/hello-" version
6929 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
6930 (build-system gnu-build-system)
6931 (arguments '(#:configure-flags '("--enable-silent-rules")))
6932 (inputs (list gawk))
6933 (synopsis "Hello, GNU world: An example GNU package")
6934 (description "Guess what GNU Hello prints!")
6935 (home-page "https://www.gnu.org/software/hello/")
6940 Without being a Scheme expert, the reader may have guessed the meaning
6941 of the various fields here. This expression binds the variable
6942 @code{hello} to a @code{<package>} object, which is essentially a record
6943 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
6944 This package object can be inspected using procedures found in the
6945 @code{(guix packages)} module; for instance, @code{(package-name hello)}
6946 returns---surprise!---@code{"hello"}.
6948 With luck, you may be able to import part or all of the definition of
6949 the package you are interested in from another repository, using the
6950 @code{guix import} command (@pxref{Invoking guix import}).
6952 In the example above, @code{hello} is defined in a module of its own,
6953 @code{(gnu packages hello)}. Technically, this is not strictly
6954 necessary, but it is convenient to do so: all the packages defined in
6955 modules under @code{(gnu packages @dots{})} are automatically known to
6956 the command-line tools (@pxref{Package Modules}).
6958 There are a few points worth noting in the above package definition:
6962 The @code{source} field of the package is an @code{<origin>} object
6963 (@pxref{origin Reference}, for the complete reference).
6964 Here, the @code{url-fetch} method from @code{(guix download)} is used,
6965 meaning that the source is a file to be downloaded over FTP or HTTP.
6967 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
6968 the GNU mirrors defined in @code{(guix download)}.
6970 The @code{sha256} field specifies the expected SHA256 hash of the file
6971 being downloaded. It is mandatory, and allows Guix to check the
6972 integrity of the file. The @code{(base32 @dots{})} form introduces the
6973 base32 representation of the hash. You can obtain this information with
6974 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
6975 hash} (@pxref{Invoking guix hash}).
6978 When needed, the @code{origin} form can also have a @code{patches} field
6979 listing patches to be applied, and a @code{snippet} field giving a
6980 Scheme expression to modify the source code.
6983 @cindex GNU Build System
6984 The @code{build-system} field specifies the procedure to build the
6985 package (@pxref{Build Systems}). Here, @code{gnu-build-system}
6986 represents the familiar GNU Build System, where packages may be
6987 configured, built, and installed with the usual @code{./configure &&
6988 make && make check && make install} command sequence.
6990 When you start packaging non-trivial software, you may need tools to
6991 manipulate those build phases, manipulate files, and so on. @xref{Build
6992 Utilities}, for more on this.
6995 The @code{arguments} field specifies options for the build system
6996 (@pxref{Build Systems}). Here it is interpreted by
6997 @code{gnu-build-system} as a request run @file{configure} with the
6998 @option{--enable-silent-rules} flag.
7004 @cindex backquote (quasiquote)
7007 @cindex comma (unquote)
7010 What about these quote (@code{'}) characters? They are Scheme syntax to
7011 introduce a literal list; @code{'} is synonymous with @code{quote}.
7012 Sometimes you'll also see @code{`} (a backquote, synonymous with
7013 @code{quasiquote}) and @code{,} (a comma, synonymous with @code{unquote}).
7014 @xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
7015 for details. Here the value of the @code{arguments} field is a list of
7016 arguments passed to the build system down the road, as with @code{apply}
7017 (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
7020 The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
7021 (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
7022 @code{#:configure-flags} is a keyword used to pass a keyword argument
7023 to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
7027 The @code{inputs} field specifies inputs to the build process---i.e.,
7028 build-time or run-time dependencies of the package. Here, we add
7029 an input, a reference to the @code{gawk}
7030 variable; @code{gawk} is itself bound to a @code{<package>} object.
7032 Note that GCC, Coreutils, Bash, and other essential tools do not need to
7033 be specified as inputs here. Instead, @code{gnu-build-system} takes care
7034 of ensuring that they are present (@pxref{Build Systems}).
7036 However, any other dependencies need to be specified in the
7037 @code{inputs} field. Any dependency not specified here will simply be
7038 unavailable to the build process, possibly leading to a build failure.
7041 @xref{package Reference}, for a full description of possible fields.
7043 Once a package definition is in place, the
7044 package may actually be built using the @code{guix build} command-line
7045 tool (@pxref{Invoking guix build}), troubleshooting any build failures
7046 you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the
7047 package definition using the @command{guix edit} command
7048 (@pxref{Invoking guix edit}).
7049 @xref{Packaging Guidelines}, for
7050 more information on how to test package definitions, and
7051 @ref{Invoking guix lint}, for information on how to check a definition
7052 for style conformance.
7053 @vindex GUIX_PACKAGE_PATH
7054 Lastly, @pxref{Channels}, for information
7055 on how to extend the distribution by adding your own package definitions
7058 Finally, updating the package definition to a new upstream version
7059 can be partly automated by the @command{guix refresh} command
7060 (@pxref{Invoking guix refresh}).
7062 Behind the scenes, a derivation corresponding to the @code{<package>}
7063 object is first computed by the @code{package-derivation} procedure.
7064 That derivation is stored in a @file{.drv} file under @file{/gnu/store}.
7065 The build actions it prescribes may then be realized by using the
7066 @code{build-derivations} procedure (@pxref{The Store}).
7068 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
7069 Return the @code{<derivation>} object of @var{package} for @var{system}
7070 (@pxref{Derivations}).
7072 @var{package} must be a valid @code{<package>} object, and @var{system}
7073 must be a string denoting the target system type---e.g.,
7074 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
7075 must be a connection to the daemon, which operates on the store
7076 (@pxref{The Store}).
7080 @cindex cross-compilation
7081 Similarly, it is possible to compute a derivation that cross-builds a
7082 package for some other system:
7084 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
7085 @var{package} @var{target} [@var{system}]
7086 Return the @code{<derivation>} object of @var{package} cross-built from
7087 @var{system} to @var{target}.
7089 @var{target} must be a valid GNU triplet denoting the target hardware
7090 and operating system, such as @code{"aarch64-linux-gnu"}
7091 (@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
7094 Once you have package definitions, you can easily define @emph{variants}
7095 of those packages. @xref{Defining Package Variants}, for more on that.
7098 * package Reference:: The package data type.
7099 * origin Reference:: The origin data type.
7103 @node package Reference
7104 @subsection @code{package} Reference
7106 This section summarizes all the options available in @code{package}
7107 declarations (@pxref{Defining Packages}).
7109 @deftp {Data Type} package
7110 This is the data type representing a package recipe.
7114 The name of the package, as a string.
7116 @item @code{version}
7117 The version of the package, as a string. @xref{Version Numbers}, for
7121 An object telling how the source code for the package should be
7122 acquired. Most of the time, this is an @code{origin} object, which
7123 denotes a file fetched from the Internet (@pxref{origin Reference}). It
7124 can also be any other ``file-like'' object such as a @code{local-file},
7125 which denotes a file from the local file system (@pxref{G-Expressions,
7126 @code{local-file}}).
7128 @item @code{build-system}
7129 The build system that should be used to build the package (@pxref{Build
7132 @item @code{arguments} (default: @code{'()})
7133 The arguments that should be passed to the build system. This is a
7134 list, typically containing sequential keyword-value pairs.
7136 @item @code{inputs} (default: @code{'()})
7137 @itemx @code{native-inputs} (default: @code{'()})
7138 @itemx @code{propagated-inputs} (default: @code{'()})
7139 @cindex inputs, of packages
7140 These fields list dependencies of the package. Each element of these
7141 lists is either a package, origin, or other ``file-like object''
7142 (@pxref{G-Expressions}); to specify the output of that file-like object
7143 that should be used, pass a two-element list where the second element is
7144 the output (@pxref{Packages with Multiple Outputs}, for more on package
7145 outputs). For example, the list below specifies three inputs:
7148 (list libffi libunistring
7149 `(,glib "bin")) ;the "bin" output of GLib
7152 In the example above, the @code{"out"} output of @code{libffi} and
7153 @code{libunistring} is used.
7155 @quotation Compatibility Note
7156 Until version 1.3.0, input lists were a list of tuples,
7157 where each tuple has a label for the input (a string) as its
7158 first element, a package, origin, or derivation as its second element,
7159 and optionally the name of the output thereof that should be used, which
7160 defaults to @code{"out"}. For example, the list below is equivalent to
7161 the one above, but using the @dfn{old input style}:
7164 ;; Old input style (deprecated).
7165 `(("libffi" ,libffi)
7166 ("libunistring" ,libunistring)
7167 ("glib:bin" ,glib "bin")) ;the "bin" output of GLib
7170 This style is now deprecated; it is still supported but support will be
7171 removed in a future version. It should not be used for new package
7172 definitions. @xref{Invoking guix style}, on how to migrate to the new
7176 @cindex cross compilation, package dependencies
7177 The distinction between @code{native-inputs} and @code{inputs} is
7178 necessary when considering cross-compilation. When cross-compiling,
7179 dependencies listed in @code{inputs} are built for the @emph{target}
7180 architecture; conversely, dependencies listed in @code{native-inputs}
7181 are built for the architecture of the @emph{build} machine.
7183 @code{native-inputs} is typically used to list tools needed at
7184 build time, but not at run time, such as Autoconf, Automake, pkg-config,
7185 Gettext, or Bison. @command{guix lint} can report likely mistakes in
7186 this area (@pxref{Invoking guix lint}).
7188 @anchor{package-propagated-inputs}
7189 Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
7190 specified packages will be automatically installed to profiles
7191 (@pxref{Features, the role of profiles in Guix}) alongside the package
7192 they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
7193 package}}, for information on how @command{guix package} deals with
7196 For example this is necessary when packaging a C/C++ library that needs
7197 headers of another library to compile, or when a pkg-config file refers
7198 to another one @i{via} its @code{Requires} field.
7200 Another example where @code{propagated-inputs} is useful is for languages
7201 that lack a facility to record the run-time search path akin to the
7202 @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
7203 more. When packaging libraries written in those languages, ensure they
7204 can find library code they depend on at run time by listing run-time
7205 dependencies in @code{propagated-inputs} rather than @code{inputs}.
7207 @item @code{outputs} (default: @code{'("out")})
7208 The list of output names of the package. @xref{Packages with Multiple
7209 Outputs}, for typical uses of additional outputs.
7211 @item @code{native-search-paths} (default: @code{'()})
7212 @itemx @code{search-paths} (default: @code{'()})
7213 A list of @code{search-path-specification} objects describing
7214 search-path environment variables honored by the package.
7216 @item @code{replacement} (default: @code{#f})
7217 This must be either @code{#f} or a package object that will be used as a
7218 @dfn{replacement} for this package. @xref{Security Updates, grafts},
7221 @item @code{synopsis}
7222 A one-line description of the package.
7224 @item @code{description}
7225 A more elaborate description of the package.
7227 @item @code{license}
7228 @cindex license, of packages
7229 The license of the package; a value from @code{(guix licenses)},
7230 or a list of such values.
7232 @item @code{home-page}
7233 The URL to the home-page of the package, as a string.
7235 @item @code{supported-systems} (default: @code{%supported-systems})
7236 The list of systems supported by the package, as strings of the form
7237 @code{architecture-kernel}, for example @code{"x86_64-linux"}.
7239 @item @code{location} (default: source location of the @code{package} form)
7240 The source location of the package. It is useful to override this when
7241 inheriting from another package, in which case this field is not
7242 automatically corrected.
7246 @deffn {Scheme Syntax} this-package
7247 When used in the @emph{lexical scope} of a package field definition, this
7248 identifier resolves to the package being defined.
7250 The example below shows how to add a package as a native input of itself when
7258 ;; When cross-compiled, Guile, for example, depends on
7259 ;; a native version of itself. Add it here.
7260 (native-inputs (if (%current-target-system)
7265 It is an error to refer to @code{this-package} outside a package definition.
7268 The following helper procedures are provided to help deal with package
7271 @deffn {Scheme Procedure} lookup-package-input @var{package} @var{name}
7272 @deffnx {Scheme Procedure} lookup-package-native-input @var{package} @var{name}
7273 @deffnx {Scheme Procedure} lookup-package-propagated-input @var{package} @var{name}
7274 @deffnx {Scheme Procedure} lookup-package-direct-input @var{package} @var{name}
7275 Look up @var{name} among @var{package}'s inputs (or native, propagated,
7276 or direct inputs). Return it if found, @code{#f} otherwise.
7278 @var{name} is the name of a package depended on. Here's how you might
7282 (use-modules (guix packages) (gnu packages base))
7284 (lookup-package-direct-input coreutils "gmp")
7285 @result{} #<package gmp@@6.2.1 @dots{}>
7288 In this example we obtain the @code{gmp} package that is among the
7289 direct inputs of @code{coreutils}.
7292 @cindex development inputs, of a package
7293 @cindex implicit inputs, of a package
7294 Sometimes you will want to obtain the list of inputs needed to
7295 @emph{develop} a package---all the inputs that are visible when the
7296 package is compiled. This is what the @code{package-development-inputs}
7299 @deffn {Scheme Procedure} package-development-inputs @var{package} @
7300 [@var{system}] [#:target #f]
7301 Return the list of inputs required by @var{package} for development
7302 purposes on @var{system}. When @var{target} is true, return the inputs
7303 needed to cross-compile @var{package} from @var{system} to
7304 @var{triplet}, where @var{triplet} is a triplet such as
7305 @code{"aarch64-linux-gnu"}.
7307 Note that the result includes both explicit inputs and implicit
7308 inputs---inputs automatically added by the build system (@pxref{Build
7309 Systems}). Let us take the @code{hello} package to illustrate that:
7312 (use-modules (gnu packages base) (guix packages))
7315 @result{} #<package hello@@2.10 gnu/packages/base.scm:79 7f585d4f6790>
7317 (package-direct-inputs hello)
7320 (package-development-inputs hello)
7321 @result{} (("source" @dots{}) ("tar" #<package tar@@1.32 @dots{}>) @dots{})
7324 In this example, @code{package-direct-inputs} returns the empty list,
7325 because @code{hello} has zero explicit dependencies. Conversely,
7326 @code{package-development-inputs} includes inputs implicitly added by
7327 @code{gnu-build-system} that are required to build @code{hello}: tar,
7328 gzip, GCC, libc, Bash, and more. To visualize it, @command{guix graph
7329 hello} would show you explicit inputs, whereas @command{guix graph -t
7330 bag hello} would include implicit inputs (@pxref{Invoking guix graph}).
7333 Because packages are regular Scheme objects that capture a complete
7334 dependency graph and associated build procedures, it is often useful to
7335 write procedures that take a package and return a modified version
7336 thereof according to some parameters. Below are a few examples.
7338 @cindex tool chain, choosing a package's tool chain
7339 @deffn {Scheme Procedure} package-with-c-toolchain @var{package} @var{toolchain}
7340 Return a variant of @var{package} that uses @var{toolchain} instead of
7341 the default GNU C/C++ toolchain. @var{toolchain} must be a list of
7342 inputs (label/package tuples) providing equivalent functionality, such
7343 as the @code{gcc-toolchain} package.
7345 The example below returns a variant of the @code{hello} package built
7346 with GCC@tie{}10.x and the rest of the GNU tool chain (Binutils and the
7347 GNU C Library) instead of the default tool chain:
7350 (let ((toolchain (specification->package "gcc-toolchain@@10")))
7351 (package-with-c-toolchain hello `(("toolchain" ,toolchain))))
7354 The build tool chain is part of the @dfn{implicit inputs} of
7355 packages---it's usually not listed as part of the various ``inputs''
7356 fields and is instead pulled in by the build system. Consequently, this
7357 procedure works by changing the build system of @var{package} so that it
7358 pulls in @var{toolchain} instead of the defaults. @ref{Build Systems},
7359 for more on build systems.
7362 @node origin Reference
7363 @subsection @code{origin} Reference
7365 This section documents @dfn{origins}. An @code{origin} declaration
7366 specifies data that must be ``produced''---downloaded, usually---and
7367 whose content hash is known in advance. Origins are primarily used to
7368 represent the source code of packages (@pxref{Defining Packages}). For
7369 that reason, the @code{origin} form allows you to declare patches to
7370 apply to the original source code as well as code snippets to modify it.
7372 @deftp {Data Type} origin
7373 This is the data type representing a source code origin.
7377 An object containing the URI of the source. The object type depends on
7378 the @code{method} (see below). For example, when using the
7379 @var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
7380 values are: a URL represented as a string, or a list thereof.
7382 @cindex fixed-output derivations, for download
7384 A monadic procedure that handles the given URI@. The procedure must
7385 accept at least three arguments: the value of the @code{uri} field and
7386 the hash algorithm and hash value specified by the @code{hash} field.
7387 It must return a store item or a derivation in the store monad
7388 (@pxref{The Store Monad}); most methods return a fixed-output derivation
7389 (@pxref{Derivations}).
7391 Commonly used methods include @code{url-fetch}, which fetches data from
7392 a URL, and @code{git-fetch}, which fetches data from a Git repository
7396 A bytevector containing the SHA-256 hash of the source. This is
7397 equivalent to providing a @code{content-hash} SHA256 object in the
7398 @code{hash} field described below.
7401 The @code{content-hash} object of the source---see below for how to use
7402 @code{content-hash}.
7404 You can obtain this information using @code{guix download}
7405 (@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
7408 @item @code{file-name} (default: @code{#f})
7409 The file name under which the source code should be saved. When this is
7410 @code{#f}, a sensible default value will be used in most cases. In case
7411 the source is fetched from a URL, the file name from the URL will be
7412 used. For version control checkouts, it is recommended to provide the
7413 file name explicitly because the default is not very descriptive.
7415 @item @code{patches} (default: @code{'()})
7416 A list of file names, origins, or file-like objects (@pxref{G-Expressions,
7417 file-like objects}) pointing to patches to be applied to the source.
7419 This list of patches must be unconditional. In particular, it cannot
7420 depend on the value of @code{%current-system} or
7421 @code{%current-target-system}.
7423 @item @code{snippet} (default: @code{#f})
7424 A G-expression (@pxref{G-Expressions}) or S-expression that will be run
7425 in the source directory. This is a convenient way to modify the source,
7426 sometimes more convenient than a patch.
7428 @item @code{patch-flags} (default: @code{'("-p1")})
7429 A list of command-line flags that should be passed to the @code{patch}
7432 @item @code{patch-inputs} (default: @code{#f})
7433 Input packages or derivations to the patching process. When this is
7434 @code{#f}, the usual set of inputs necessary for patching are provided,
7435 such as GNU@tie{}Patch.
7437 @item @code{modules} (default: @code{'()})
7438 A list of Guile modules that should be loaded during the patching
7439 process and while running the code in the @code{snippet} field.
7441 @item @code{patch-guile} (default: @code{#f})
7442 The Guile package that should be used in the patching process. When
7443 this is @code{#f}, a sensible default is used.
7447 @deftp {Data Type} content-hash @var{value} [@var{algorithm}]
7448 Construct a content hash object for the given @var{algorithm}, and with
7449 @var{value} as its hash value. When @var{algorithm} is omitted, assume
7450 it is @code{sha256}.
7452 @var{value} can be a literal string, in which case it is base32-decoded,
7453 or it can be a bytevector.
7455 The following forms are all equivalent:
7458 (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
7459 (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
7461 (content-hash (base32
7462 "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
7463 (content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
7467 Technically, @code{content-hash} is currently implemented as a macro.
7468 It performs sanity checks at macro-expansion time, when possible, such
7469 as ensuring that @var{value} has the right size for @var{algorithm}.
7472 As we have seen above, how exactly the data an origin refers to is
7473 retrieved is determined by its @code{method} field. The @code{(guix
7474 download)} module provides the most common method, @code{url-fetch},
7477 @deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @
7478 [name] [#:executable? #f]
7479 Return a fixed-output derivation that fetches data from @var{url} (a
7480 string, or a list of strings denoting alternate URLs), which is expected
7481 to have hash @var{hash} of type @var{hash-algo} (a symbol). By default,
7482 the file name is the base name of URL; optionally, @var{name} can
7483 specify a different file name. When @var{executable?} is true, make the
7484 downloaded file executable.
7486 When one of the URL starts with @code{mirror://}, then its host part is
7487 interpreted as the name of a mirror scheme, taken from @file{%mirror-file}.
7489 Alternatively, when URL starts with @code{file://}, return the
7490 corresponding file name in the store.
7493 Likewise, the @code{(guix git-download)} module defines the
7494 @code{git-fetch} origin method, which fetches data from a Git version
7495 control repository, and the @code{git-reference} data type to describe
7496 the repository and revision to fetch.
7498 @deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash}
7499 Return a fixed-output derivation that fetches @var{ref}, a
7500 @code{<git-reference>} object. The output is expected to have recursive
7501 hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
7502 the file name, or a generic name if @code{#f}.
7505 @deftp {Data Type} git-reference
7506 This data type represents a Git reference for @code{git-fetch} to
7511 The URL of the Git repository to clone.
7514 This string denotes either the commit to fetch (a hexadecimal string),
7515 or the tag to fetch. You can also use a ``short'' commit ID or a
7516 @command{git describe} style identifier such as
7517 @code{v1.0.1-10-g58d7909c97}.
7519 @item @code{recursive?} (default: @code{#f})
7520 This Boolean indicates whether to recursively fetch Git sub-modules.
7523 The example below denotes the @code{v2.10} tag of the GNU@tie{}Hello
7528 (url "https://git.savannah.gnu.org/git/hello.git")
7532 This is equivalent to the reference below, which explicitly names the
7537 (url "https://git.savannah.gnu.org/git/hello.git")
7538 (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
7542 For Mercurial repositories, the module @code{(guix hg-download)} defines
7543 the @code{hg-fetch} origin method and @code{hg-reference} data type for
7544 support of the Mercurial version control system.
7546 @deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @
7548 Return a fixed-output derivation that fetches @var{ref}, a
7549 @code{<hg-reference>} object. The output is expected to have recursive
7550 hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
7551 the file name, or a generic name if @code{#false}.
7554 @node Defining Package Variants
7555 @section Defining Package Variants
7557 @cindex customizing packages
7558 @cindex variants, of packages
7559 One of the nice things with Guix is that, given a package definition,
7560 you can easily @emph{derive} variants of that package---for a different
7561 upstream version, with different dependencies, different compilation
7562 options, and so on. Some of these custom packages can be defined
7563 straight from the command line (@pxref{Package Transformation Options}).
7564 This section describes how to define package variants in code. This can
7565 be useful in ``manifests'' (@pxref{profile-manifest,
7566 @option{--manifest}}) and in your own package collection
7567 (@pxref{Creating a Channel}), among others!
7569 @cindex inherit, for package definitions
7570 As discussed earlier, packages are first-class objects in the Scheme
7571 language. The @code{(guix packages)} module provides the @code{package}
7572 construct to define new package objects (@pxref{package Reference}).
7573 The easiest way to define a package variant is using the @code{inherit}
7574 keyword together with @code{package}. This allows you to inherit from a
7575 package definition while overriding the fields you want.
7577 For example, given the @code{hello} variable, which contains a
7578 definition for the current version of GNU@tie{}Hello, here's how you
7579 would define a variant for version 2.2 (released in 2006, it's
7583 (use-modules (gnu packages base)) ;for 'hello'
7591 (uri (string-append "mirror://gnu/hello/hello-" version
7595 "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))
7598 The example above corresponds to what the @option{--with-source} package
7599 transformation option does. Essentially @code{hello-2.2} preserves all
7600 the fields of @code{hello}, except @code{version} and @code{source},
7601 which it overrides. Note that the original @code{hello} variable is
7602 still there, in the @code{(gnu packages base)} module, unchanged. When
7603 you define a custom package like this, you are really @emph{adding} a
7604 new package definition; the original one remains available.
7606 You can just as well define variants with a different set of
7607 dependencies than the original package. For example, the default
7608 @code{gdb} package depends on @code{guile}, but since that is an
7609 optional dependency, you can define a variant that removes that
7613 (use-modules (gnu packages gdb)) ;for 'gdb'
7615 (define gdb-sans-guile
7618 (inputs (modify-inputs (package-inputs gdb)
7619 (delete "guile")))))
7622 The @code{modify-inputs} form above removes the @code{"guile"} package
7623 from the @code{inputs} field of @code{gdb}. The @code{modify-inputs}
7624 macro is a helper that can prove useful anytime you want to remove, add,
7625 or replace package inputs.
7627 @deffn {Scheme Syntax} modify-inputs @var{inputs} @var{clauses}
7628 Modify the given package inputs, as returned by @code{package-inputs} & co.,
7629 according to the given clauses. Each clause must have one of the
7633 @item (delete @var{name}@dots{})
7634 Delete from the inputs packages with the given @var{name}s (strings).
7636 @item (append @var{package}@dots{})
7637 Add @var{package}s to the end of the input list.
7639 @item (prepend @var{package}@dots{})
7640 Add @var{package}s to the front of the input list.
7643 The example below removes the GMP and ACL inputs of Coreutils and adds
7644 libcap to the back of the input list:
7647 (modify-inputs (package-inputs coreutils)
7648 (delete "gmp" "acl")
7652 The example below replaces the @code{guile} package from the inputs of
7653 @code{guile-redis} with @code{guile-2.2}:
7656 (modify-inputs (package-inputs guile-redis)
7657 (replace "guile" guile-2.2))
7660 The last type of clause is @code{prepend}, to add inputs to the front of
7664 In some cases, you may find it useful to write functions
7665 (``procedures'', in Scheme parlance) that return a package based on some
7666 parameters. For example, consider the @code{luasocket} library for the
7667 Lua programming language. We want to create @code{luasocket} packages
7668 for major versions of Lua. One way to do that is to define a procedure
7669 that takes a Lua package and returns a @code{luasocket} package that
7673 (define (make-lua-socket name lua)
7674 ;; Return a luasocket package built with LUA.
7678 ;; several fields omitted
7680 (synopsis "Socket library for Lua")))
7682 (define-public lua5.1-socket
7683 (make-lua-socket "lua5.1-socket" lua-5.1))
7685 (define-public lua5.2-socket
7686 (make-lua-socket "lua5.2-socket" lua-5.2))
7689 Here we have defined packages @code{lua5.1-socket} and
7690 @code{lua5.2-socket} by calling @code{make-lua-socket} with different
7691 arguments. @xref{Procedures,,, guile, GNU Guile Reference Manual}, for
7692 more info on procedures. Having top-level public definitions for these
7693 two packages means that they can be referred to from the command line
7694 (@pxref{Package Modules}).
7696 @cindex package transformations
7697 These are pretty simple package variants. As a convenience, the
7698 @code{(guix transformations)} module provides a high-level interface
7699 that directly maps to the more sophisticated package transformation
7700 options (@pxref{Package Transformation Options}):
7702 @deffn {Scheme Procedure} options->transformation @var{opts}
7703 Return a procedure that, when passed an object to build (package,
7704 derivation, etc.), applies the transformations specified by @var{opts} and returns
7705 the resulting objects. @var{opts} must be a list of symbol/string pairs such as:
7708 ((with-branch . "guile-gcrypt=master")
7709 (without-tests . "libgcrypt"))
7712 Each symbol names a transformation and the corresponding string is an argument
7713 to that transformation.
7716 For instance, a manifest equivalent to this command:
7720 --with-branch=guile-gcrypt=master \
7721 --with-debug-info=zlib
7725 ... would look like this:
7728 (use-modules (guix transformations))
7731 ;; The package transformation procedure.
7732 (options->transformation
7733 '((with-branch . "guile-gcrypt=master")
7734 (with-debug-info . "zlib"))))
7737 (list (transform (specification->package "guix"))))
7740 @cindex input rewriting
7741 @cindex dependency graph rewriting
7742 The @code{options->transformation} procedure is convenient, but it's
7743 perhaps also not as flexible as you may like. How is it implemented?
7744 The astute reader probably noticed that most package transformation
7745 options go beyond the superficial changes shown in the first examples of
7746 this section: they involve @dfn{input rewriting}, whereby the dependency
7747 graph of a package is rewritten by replacing specific inputs by others.
7749 Dependency graph rewriting, for the purposes of swapping packages in the
7750 graph, is what the @code{package-input-rewriting} procedure in
7751 @code{(guix packages)} implements.
7753 @deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
7754 [@var{rewrite-name}] [#:deep? #t]
7755 Return a procedure that, when passed a package, replaces its direct and
7756 indirect dependencies, including implicit inputs when @var{deep?} is
7757 true, according to @var{replacements}. @var{replacements} is a list of
7758 package pairs; the first element of each pair is the package to replace,
7759 and the second one is the replacement.
7761 Optionally, @var{rewrite-name} is a one-argument procedure that takes
7762 the name of a package and returns its new name after rewrite.
7766 Consider this example:
7769 (define libressl-instead-of-openssl
7770 ;; This is a procedure to replace OPENSSL by LIBRESSL,
7772 (package-input-rewriting `((,openssl . ,libressl))))
7774 (define git-with-libressl
7775 (libressl-instead-of-openssl git))
7779 Here we first define a rewriting procedure that replaces @var{openssl}
7780 with @var{libressl}. Then we use it to define a @dfn{variant} of the
7781 @var{git} package that uses @var{libressl} instead of @var{openssl}.
7782 This is exactly what the @option{--with-input} command-line option does
7783 (@pxref{Package Transformation Options, @option{--with-input}}).
7785 The following variant of @code{package-input-rewriting} can match packages to
7786 be replaced by name rather than by identity.
7788 @deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t]
7789 Return a procedure that, given a package, applies the given
7790 @var{replacements} to all the package graph, including implicit inputs
7791 unless @var{deep?} is false. @var{replacements} is a list of
7792 spec/procedures pair; each spec is a package specification such as
7793 @code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching
7794 package and returns a replacement for that package.
7797 The example above could be rewritten this way:
7800 (define libressl-instead-of-openssl
7801 ;; Replace all the packages called "openssl" with LibreSSL.
7802 (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))
7805 The key difference here is that, this time, packages are matched by spec and
7806 not by identity. In other words, any package in the graph that is called
7807 @code{openssl} will be replaced.
7809 A more generic procedure to rewrite a package dependency graph is
7810 @code{package-mapping}: it supports arbitrary changes to nodes in the
7813 @deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] [#:deep? #f]
7814 Return a procedure that, given a package, applies @var{proc} to all the packages
7815 depended on and returns the resulting package. The procedure stops recursion
7816 when @var{cut?} returns true for a given package. When @var{deep?} is true, @var{proc} is
7817 applied to implicit inputs as well.
7822 @section Build Systems
7824 @cindex build system
7825 Each package definition specifies a @dfn{build system} and arguments for
7826 that build system (@pxref{Defining Packages}). This @code{build-system}
7827 field represents the build procedure of the package, as well as implicit
7828 dependencies of that build procedure.
7830 Build systems are @code{<build-system>} objects. The interface to
7831 create and manipulate them is provided by the @code{(guix build-system)}
7832 module, and actual build systems are exported by specific modules.
7834 @cindex bag (low-level package representation)
7835 Under the hood, build systems first compile package objects to
7836 @dfn{bags}. A @dfn{bag} is like a package, but with less
7837 ornamentation---in other words, a bag is a lower-level representation of
7838 a package, which includes all the inputs of that package, including some
7839 that were implicitly added by the build system. This intermediate
7840 representation is then compiled to a derivation (@pxref{Derivations}).
7841 The @code{package-with-c-toolchain} is an example of a way to change the
7842 implicit inputs that a package's build system pulls in (@pxref{package
7843 Reference, @code{package-with-c-toolchain}}).
7845 Build systems accept an optional list of @dfn{arguments}. In package
7846 definitions, these are passed @i{via} the @code{arguments} field
7847 (@pxref{Defining Packages}). They are typically keyword arguments
7848 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
7849 Guile Reference Manual}). The value of these arguments is usually
7850 evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
7851 by the daemon (@pxref{Derivations}).
7853 The main build system is @code{gnu-build-system}, which implements the
7854 standard build procedure for GNU and many other packages. It
7855 is provided by the @code{(guix build-system gnu)} module.
7857 @defvr {Scheme Variable} gnu-build-system
7858 @code{gnu-build-system} represents the GNU Build System, and variants
7859 thereof (@pxref{Configuration, configuration and makefile conventions,,
7860 standards, GNU Coding Standards}).
7862 @cindex build phases
7863 In a nutshell, packages using it are configured, built, and installed with
7864 the usual @code{./configure && make && make check && make install}
7865 command sequence. In practice, a few additional steps are often needed.
7866 All these steps are split up in separate @dfn{phases}.
7867 @xref{Build Phases}, for more info on build phases and ways to customize
7870 In addition, this build system ensures that the ``standard'' environment
7871 for GNU packages is available. This includes tools such as GCC, libc,
7872 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
7873 build-system gnu)} module for a complete list). We call these the
7874 @dfn{implicit inputs} of a package, because package definitions do not
7875 have to mention them.
7877 This build system supports a number of keyword arguments, which can be
7878 passed @i{via} the @code{arguments} field of a package. Here are some
7879 of the main parameters:
7883 This argument specifies build-side code that evaluates to an alist of
7884 build phases. @xref{Build Phases}, for more information.
7886 @item #:configure-flags
7887 This is a list of flags (strings) passed to the @command{configure}
7888 script. @xref{Defining Packages}, for an example.
7891 This list of strings contains flags passed as arguments to
7892 @command{make} invocations in the @code{build}, @code{check}, and
7893 @code{install} phases.
7895 @item #:out-of-source?
7896 This Boolean, @code{#f} by default, indicates whether to run builds in a
7897 build directory separate from the source tree.
7899 When it is true, the @code{configure} phase creates a separate build
7900 directory, changes to that directory, and runs the @code{configure}
7901 script from there. This is useful for packages that require it, such as
7905 This Boolean, @code{#t} by default, indicates whether the @code{check}
7906 phase should run the package's test suite.
7909 This string, @code{"check"} by default, gives the name of the makefile
7910 target used by the @code{check} phase.
7912 @item #:parallel-build?
7913 @itemx #:parallel-tests?
7914 These Boolean values specify whether to build, respectively run the test
7915 suite, in parallel, with the @code{-j} flag of @command{make}. When
7916 they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is
7917 the number specified as the @option{--cores} option of
7918 @command{guix-daemon} or that of the @command{guix} client command
7919 (@pxref{Common Build Options, @option{--cores}}).
7921 @cindex RUNPATH, validation
7922 @item #:validate-runpath?
7923 This Boolean, @code{#t} by default, determines whether to ``validate''
7924 the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
7925 as executables) previously installed by the @code{install} phase.
7927 This validation step consists in making sure that all the shared
7928 libraries needed by an ELF binary, which are listed as
7929 @code{DT_NEEDED} entries in its @code{PT_DYNAMIC} segment, appear in the
7930 @code{DT_RUNPATH} entry of that binary. In other words, it ensures that
7931 running or using those binaries will not result in a ``file not found''
7932 error at run time. @xref{Options, @option{-rpath},, ld, The GNU
7933 Linker}, for more information on @code{RUNPATH}.
7935 @item #:substitutable?
7936 This Boolean, @code{#t} by default, tells whether the package outputs
7937 should be substitutable---i.e., whether users should be able to obtain
7938 substitutes for them instead of building locally (@pxref{Substitutes}).
7940 @item #:allowed-references
7941 @itemx #:disallowed-references
7942 When true, these arguments must be a list of dependencies that must not
7943 appear among the references of the build results. If, upon build
7944 completion, some of these references are retained, the build process
7947 This is useful to ensure that a package does not erroneously keep a
7948 reference to some of it build-time inputs, in cases where doing so
7949 would, for example, unnecessarily increase its size (@pxref{Invoking
7953 Most other build systems support these keyword arguments.
7956 Other @code{<build-system>} objects are defined to support other
7957 conventions and tools used by free software packages. They inherit most
7958 of @code{gnu-build-system}, and differ mainly in the set of inputs
7959 implicitly added to the build process, and in the list of phases
7960 executed. Some of these build systems are listed below.
7962 @defvr {Scheme Variable} ant-build-system
7963 This variable is exported by @code{(guix build-system ant)}. It
7964 implements the build procedure for Java packages that can be built with
7965 @url{https://ant.apache.org/, Ant build tool}.
7967 It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
7968 provided by the @code{icedtea} package to the set of inputs. Different
7969 packages can be specified with the @code{#:ant} and @code{#:jdk}
7970 parameters, respectively.
7972 When the original package does not provide a suitable Ant build file,
7973 the parameter @code{#:jar-name} can be used to generate a minimal Ant
7974 build file @file{build.xml} with tasks to build the specified jar
7975 archive. In this case the parameter @code{#:source-dir} can be used to
7976 specify the source sub-directory, defaulting to ``src''.
7978 The @code{#:main-class} parameter can be used with the minimal ant
7979 buildfile to specify the main class of the resulting jar. This makes the
7980 jar file executable. The @code{#:test-include} parameter can be used to
7981 specify the list of junit tests to run. It defaults to
7982 @code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
7983 disable some tests. It defaults to @code{(list "**/Abstract*.java")},
7984 because abstract classes cannot be run as tests.
7986 The parameter @code{#:build-target} can be used to specify the Ant task
7987 that should be run during the @code{build} phase. By default the
7988 ``jar'' task will be run.
7992 @defvr {Scheme Variable} android-ndk-build-system
7993 @cindex Android distribution
7994 @cindex Android NDK build system
7995 This variable is exported by @code{(guix build-system android-ndk)}. It
7996 implements a build procedure for Android NDK (native development kit)
7997 packages using a Guix-specific build process.
7999 The build system assumes that packages install their public interface
8000 (header) files to the subdirectory @file{include} of the @code{out} output and
8001 their libraries to the subdirectory @file{lib} the @code{out} output.
8003 It's also assumed that the union of all the dependencies of a package
8004 has no conflicting files.
8006 For the time being, cross-compilation is not supported - so right now
8007 the libraries and header files are assumed to be host tools.
8011 @defvr {Scheme Variable} asdf-build-system/source
8012 @defvrx {Scheme Variable} asdf-build-system/sbcl
8013 @defvrx {Scheme Variable} asdf-build-system/ecl
8015 These variables, exported by @code{(guix build-system asdf)}, implement
8016 build procedures for Common Lisp packages using
8017 @url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
8018 definition facility for Common Lisp programs and libraries.
8020 The @code{asdf-build-system/source} system installs the packages in
8021 source form, and can be loaded using any common lisp implementation, via
8022 ASDF@. The others, such as @code{asdf-build-system/sbcl}, install binary
8023 systems in the format which a particular implementation understands.
8024 These build systems can also be used to produce executable programs, or
8025 lisp images which contain a set of packages pre-loaded.
8027 The build system uses naming conventions. For binary packages, the
8028 package name should be prefixed with the lisp implementation, such as
8029 @code{sbcl-} for @code{asdf-build-system/sbcl}.
8031 Additionally, the corresponding source package should be labeled using
8032 the same convention as python packages (see @ref{Python Modules}), using
8033 the @code{cl-} prefix.
8035 In order to create executable programs and images, the build-side
8036 procedures @code{build-program} and @code{build-image} can be used.
8037 They should be called in a build phase after the
8038 @code{create-asdf-configuration} phase, so that the system which was
8039 just built can be used within the resulting image. @code{build-program}
8040 requires a list of Common Lisp expressions to be passed as the
8041 @code{#:entry-program} argument.
8043 By default, all the @file{.asd} files present in the sources are read to
8044 find system definitions. The @code{#:asd-files} parameter can be used
8045 to specify the list of @file{.asd} files to read. Furthermore, if the
8046 package defines a system for its tests in a separate file, it will be
8047 loaded before the tests are run if it is specified by the
8048 @code{#:test-asd-file} parameter. If it is not set, the files
8049 @code{<system>-tests.asd}, @code{<system>-test.asd}, @code{tests.asd},
8050 and @code{test.asd} will be tried if they exist.
8052 If for some reason the package must be named in a different way than the
8053 naming conventions suggest, or if several systems must be compiled, the
8054 @code{#:asd-systems} parameter can be used to specify the list of system
8059 @defvr {Scheme Variable} cargo-build-system
8060 @cindex Rust programming language
8061 @cindex Cargo (Rust build system)
8062 This variable is exported by @code{(guix build-system cargo)}. It
8063 supports builds of packages using Cargo, the build tool of the
8064 @uref{https://www.rust-lang.org, Rust programming language}.
8066 It adds @code{rustc} and @code{cargo} to the set of inputs.
8067 A different Rust package can be specified with the @code{#:rust} parameter.
8069 Regular cargo dependencies should be added to the package definition similarly
8070 to other packages; those needed only at build time to native-inputs, others to
8071 inputs. If you need to add source-only crates then you should add them to via
8072 the @code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
8073 spec can be a package or a source definition. Note that the spec must
8074 evaluate to a path to a gzipped tarball which includes a @code{Cargo.toml}
8075 file at its root, or it will be ignored. Similarly, cargo dev-dependencies
8076 should be added to the package definition via the
8077 @code{#:cargo-development-inputs} parameter.
8079 In its @code{configure} phase, this build system will make any source inputs
8080 specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
8081 parameters available to cargo. It will also remove an included
8082 @code{Cargo.lock} file to be recreated by @code{cargo} during the
8083 @code{build} phase. The @code{package} phase will run @code{cargo package}
8084 to create a source crate for future use. The @code{install} phase installs
8085 the binaries defined by the crate. Unless @code{install-source? #f} is
8086 defined it will also install a source crate repository of itself and unpacked
8087 sources, to ease in future hacking on rust packages.
8090 @defvr {Scheme Variable} chicken-build-system
8091 This variable is exported by @code{(guix build-system chicken)}. It
8092 builds @uref{https://call-cc.org/, CHICKEN Scheme} modules, also called
8093 ``eggs'' or ``extensions''. CHICKEN generates C source code, which then
8094 gets compiled by a C compiler, in this case GCC.
8096 This build system adds @code{chicken} to the package inputs, as well as
8097 the packages of @code{gnu-build-system}.
8099 The build system can't (yet) deduce the egg's name automatically, so just like
8100 with @code{go-build-system} and its @code{#:import-path}, you should define
8101 @code{#:egg-name} in the package's @code{arguments} field.
8103 For example, if you are packaging the @code{srfi-1} egg:
8106 (arguments '(#:egg-name "srfi-1"))
8109 Egg dependencies must be defined in @code{propagated-inputs}, not @code{inputs}
8110 because CHICKEN doesn't embed absolute references in compiled eggs.
8111 Test dependencies should go to @code{native-inputs}, as usual.
8114 @defvr {Scheme Variable} copy-build-system
8115 This variable is exported by @code{(guix build-system copy)}. It
8116 supports builds of simple packages that don't require much compiling,
8117 mostly just moving files around.
8119 It adds much of the @code{gnu-build-system} packages to the set of
8120 inputs. Because of this, the @code{copy-build-system} does not require
8121 all the boilerplate code often needed for the
8122 @code{trivial-build-system}.
8124 To further simplify the file installation process, an
8125 @code{#:install-plan} argument is exposed to let the packager specify
8126 which files go where. The install plan is a list of @code{(@var{source}
8127 @var{target} [@var{filters}])}. @var{filters} are optional.
8130 @item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
8132 @item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
8133 @item Otherwise install @var{source} as @var{target}.
8136 @item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
8137 the trailing slash of @var{target} is implied with the same meaning
8140 @item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
8141 @item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
8142 @code{#:exclude-regexp}, only select files are installed depending on
8143 the filters. Each filters is specified by a list of strings.
8145 @item With @code{#:include}, install all the files which the path suffix matches
8146 at least one of the elements in the given list.
8147 @item With @code{#:include-regexp}, install all the files which the
8148 subpaths match at least one of the regular expressions in the given
8150 @item The @code{#:exclude} and @code{#:exclude-regexp} filters
8151 are the complement of their inclusion counterpart. Without @code{#:include} flags,
8152 install all files but those matching the exclusion filters.
8153 If both inclusions and exclusions are specified, the exclusions are done
8154 on top of the inclusions.
8157 In all cases, the paths relative to @var{source} are preserved within
8164 @item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
8165 @item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
8166 @item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
8167 e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
8168 @item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
8169 @file{share/my-app/sub/file}.
8170 @item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
8171 @file{share/my-app/file}.
8176 @cindex Clojure (programming language)
8177 @cindex simple Clojure build system
8178 @defvr {Scheme Variable} clojure-build-system
8179 This variable is exported by @code{(guix build-system clojure)}. It implements
8180 a simple build procedure for @uref{https://clojure.org/, Clojure} packages
8181 using plain old @code{compile} in Clojure. Cross-compilation is not supported
8184 It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
8185 Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
8186 @code{#:zip} parameters, respectively.
8188 A list of source directories, test directories and jar names can be specified
8189 with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
8190 parameters, respectively. Compile directory and main class can be specified
8191 with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
8192 Other parameters are documented below.
8194 This build system is an extension of @code{ant-build-system}, but with the
8195 following phases changed:
8200 This phase calls @code{compile} in Clojure to compile source files and runs
8201 @command{jar} to create jars from both source files and compiled files
8202 according to the include list and exclude list specified in
8203 @code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude list
8204 has priority over the include list. These lists consist of symbols
8205 representing Clojure libraries or the special keyword @code{#:all} representing
8206 all Clojure libraries found under the source directories. The parameter
8207 @code{#:omit-source?} decides if source should be included into the jars.
8210 This phase runs tests according to the include list and exclude list specified
8211 in @code{#:test-include} and @code{#:test-exclude}, respectively. Their
8212 meanings are analogous to that of @code{#:aot-include} and
8213 @code{#:aot-exclude}, except that the special keyword @code{#:all} now
8214 stands for all Clojure libraries found under the test directories. The
8215 parameter @code{#:tests?} decides if tests should be run.
8218 This phase installs all jars built previously.
8221 Apart from the above, this build system also contains an additional phase:
8226 This phase installs all top-level files with base name matching
8227 @code{%doc-regex}. A different regex can be specified with the
8228 @code{#:doc-regex} parameter. All files (recursively) inside the documentation
8229 directories specified in @code{#:doc-dirs} are installed as well.
8233 @defvr {Scheme Variable} cmake-build-system
8234 This variable is exported by @code{(guix build-system cmake)}. It
8235 implements the build procedure for packages using the
8236 @url{https://www.cmake.org, CMake build tool}.
8238 It automatically adds the @code{cmake} package to the set of inputs.
8239 Which package is used can be specified with the @code{#:cmake}
8242 The @code{#:configure-flags} parameter is taken as a list of flags
8243 passed to the @command{cmake} command. The @code{#:build-type}
8244 parameter specifies in abstract terms the flags passed to the compiler;
8245 it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
8246 debugging information''), which roughly means that code is compiled with
8247 @code{-O2 -g}, as is the case for Autoconf-based packages by default.
8250 @defvr {Scheme Variable} dune-build-system
8251 This variable is exported by @code{(guix build-system dune)}. It
8252 supports builds of packages using @uref{https://dune.build/, Dune}, a build
8253 tool for the OCaml programming language. It is implemented as an extension
8254 of the @code{ocaml-build-system} which is described below. As such, the
8255 @code{#:ocaml} and @code{#:findlib} parameters can be passed to this build
8258 It automatically adds the @code{dune} package to the set of inputs.
8259 Which package is used can be specified with the @code{#:dune}
8262 There is no @code{configure} phase because dune packages typically don't
8263 need to be configured. The @code{#:build-flags} parameter is taken as a
8264 list of flags passed to the @code{dune} command during the build.
8266 The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
8267 command instead of the more recent @code{dune} command while building
8268 a package. Its default value is @code{#f}.
8270 The @code{#:package} parameter can be passed to specify a package name, which
8271 is useful when a package contains multiple packages and you want to build
8272 only one of them. This is equivalent to passing the @code{-p} argument to
8277 @defvr {Scheme Variable} go-build-system
8278 This variable is exported by @code{(guix build-system go)}. It
8279 implements a build procedure for Go packages using the standard
8280 @url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
8281 Go build mechanisms}.
8283 The user is expected to provide a value for the key @code{#:import-path}
8284 and, in some cases, @code{#:unpack-path}. The
8285 @url{https://golang.org/doc/code.html#ImportPaths, import path}
8286 corresponds to the file system path expected by the package's build
8287 scripts and any referring packages, and provides a unique way to
8288 refer to a Go package. It is typically based on a combination of the
8289 package source code's remote URI and file system hierarchy structure. In
8290 some cases, you will need to unpack the package's source code to a
8291 different directory structure than the one indicated by the import path,
8292 and @code{#:unpack-path} should be used in such cases.
8294 Packages that provide Go libraries should install their source code into
8295 the built output. The key @code{#:install-source?}, which defaults to
8296 @code{#t}, controls whether or not the source code is installed. It can
8297 be set to @code{#f} for packages that only provide executable files.
8299 Packages can be cross-built, and if a specific architecture or operating
8300 system is desired then the keywords @code{#:goarch} and @code{#:goos}
8301 can be used to force the package to be built for that architecture and
8302 operating system. The combinations known to Go can be found
8303 @url{"https://golang.org/doc/install/source#environment", in their
8307 @defvr {Scheme Variable} glib-or-gtk-build-system
8308 This variable is exported by @code{(guix build-system glib-or-gtk)}. It
8309 is intended for use with packages making use of GLib or GTK+.
8311 This build system adds the following two phases to the ones defined by
8312 @code{gnu-build-system}:
8315 @item glib-or-gtk-wrap
8316 The phase @code{glib-or-gtk-wrap} ensures that programs in
8317 @file{bin/} are able to find GLib ``schemas'' and
8318 @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
8319 modules}. This is achieved by wrapping the programs in launch scripts
8320 that appropriately set the @env{XDG_DATA_DIRS} and @env{GTK_PATH}
8321 environment variables.
8323 It is possible to exclude specific package outputs from that wrapping
8324 process by listing their names in the
8325 @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
8326 when an output is known not to contain any GLib or GTK+ binaries, and
8327 where wrapping would gratuitously add a dependency of that output on
8330 @item glib-or-gtk-compile-schemas
8331 The phase @code{glib-or-gtk-compile-schemas} makes sure that all
8332 @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
8333 GSettings schemas} of GLib are compiled. Compilation is performed by the
8334 @command{glib-compile-schemas} program. It is provided by the package
8335 @code{glib:bin} which is automatically imported by the build system.
8336 The @code{glib} package providing @command{glib-compile-schemas} can be
8337 specified with the @code{#:glib} parameter.
8340 Both phases are executed after the @code{install} phase.
8343 @defvr {Scheme Variable} guile-build-system
8344 This build system is for Guile packages that consist exclusively of Scheme
8345 code and that are so lean that they don't even have a makefile, let alone a
8346 @file{configure} script. It compiles Scheme code using @command{guild
8347 compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
8348 installs the @file{.scm} and @file{.go} files in the right place. It also
8349 installs documentation.
8351 This build system supports cross-compilation by using the
8352 @option{--target} option of @samp{guild compile}.
8354 Packages built with @code{guile-build-system} must provide a Guile package in
8355 their @code{native-inputs} field.
8358 @defvr {Scheme Variable} julia-build-system
8359 This variable is exported by @code{(guix build-system julia)}. It
8360 implements the build procedure used by @uref{https://julialang.org/,
8361 julia} packages, which essentially is similar to running @samp{julia -e
8362 'using Pkg; Pkg.add(package)'} in an environment where
8363 @env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
8364 Tests are run by calling @code{/test/runtests.jl}.
8366 The Julia package name and uuid is read from the file
8367 @file{Project.toml}. These values can be overridden by passing the
8368 argument @code{#:julia-package-name} (which must be correctly
8369 capitalized) or @code{#:julia-package-uuid}.
8371 Julia packages usually manage their binary dependencies via
8372 @code{JLLWrappers.jl}, a Julia package that creates a module (named
8373 after the wrapped library followed by @code{_jll.jl}.
8375 To add the binary path @code{_jll.jl} packages, you need to patch the
8376 files under @file{src/wrappers/}, replacing the call to the macro
8377 @code{JLLWrappers.@@generate_wrapper_header}, adding as a second
8378 argument containing the store path the binary.
8380 As an example, in the MbedTLS Julia package, we add a build phase
8381 (@pxref{Build Phases}) to insert the absolute file name of the wrapped
8385 (add-after 'unpack 'override-binary-path
8386 (lambda* (#:key inputs #:allow-other-keys)
8387 (for-each (lambda (wrapper)
8388 (substitute* wrapper
8389 (("generate_wrapper_header.*")
8391 "generate_wrapper_header(\"MbedTLS\", \""
8392 (assoc-ref inputs "mbedtls-apache") "\")\n"))))
8393 ;; There's a Julia file for each platform, override them all.
8394 (find-files "src/wrappers/" "\\.jl$"))))
8397 Some older packages that aren't using @file{Project.toml} yet, will
8398 require this file to be created, too. It is internally done if the
8399 arguments @code{#:julia-package-name} and @code{#:julia-package-uuid}
8403 @defvr {Scheme Variable} maven-build-system
8404 This variable is exported by @code{(guix build-system maven)}. It implements
8405 a build procedure for @uref{https://maven.apache.org, Maven} packages. Maven
8406 is a dependency and lifecycle management tool for Java. A user of Maven
8407 specifies dependencies and plugins in a @file{pom.xml} file that Maven reads.
8408 When Maven does not have one of the dependencies or plugins in its repository,
8409 it will download them and use them to build the package.
8411 The maven build system ensures that maven will not try to download any
8412 dependency by running in offline mode. Maven will fail if a dependency is
8413 missing. Before running Maven, the @file{pom.xml} (and subprojects) are
8414 modified to specify the version of dependencies and plugins that match the
8415 versions available in the guix build environment. Dependencies and plugins
8416 must be installed in the fake maven repository at @file{lib/m2}, and are
8417 symlinked into a proper repository before maven is run. Maven is instructed
8418 to use that repository for the build and installs built artifacts there.
8419 Changed files are copied to the @file{lib/m2} directory of the package output.
8421 You can specify a @file{pom.xml} file with the @code{#:pom-file} argument,
8422 or let the build system use the default @file{pom.xml} file in the sources.
8424 In case you need to specify a dependency's version manually, you can use the
8425 @code{#:local-packages} argument. It takes an association list where the key
8426 is the groupId of the package and its value is an association list where the
8427 key is the artifactId of the package and its value is the version you want to
8428 override in the @file{pom.xml}.
8430 Some packages use dependencies or plugins that are not useful at runtime nor
8431 at build time in Guix. You can alter the @file{pom.xml} file to remove them
8432 using the @code{#:exclude} argument. Its value is an association list where
8433 the key is the groupId of the plugin or dependency you want to remove, and
8434 the value is a list of artifactId you want to remove.
8436 You can override the default @code{jdk} and @code{maven} packages with the
8437 corresponding argument, @code{#:jdk} and @code{#:maven}.
8439 The @code{#:maven-plugins} argument is a list of maven plugins used during
8440 the build, with the same format as the @code{inputs} fields of the package
8441 declaration. Its default value is @code{(default-maven-plugins)} which is
8445 @defvr {Scheme Variable} minetest-mod-build-system
8446 This variable is exported by @code{(guix build-system minetest)}. It
8447 implements a build procedure for @uref{https://www.minetest.net, Minetest}
8448 mods, which consists of copying Lua code, images and other resources to
8449 the location Minetest searches for mods. The build system also minimises
8450 PNG images and verifies that Minetest can load the mod without errors.
8453 @defvr {Scheme Variable} minify-build-system
8454 This variable is exported by @code{(guix build-system minify)}. It
8455 implements a minification procedure for simple JavaScript packages.
8457 It adds @code{uglify-js} to the set of inputs and uses it to compress
8458 all JavaScript files in the @file{src} directory. A different minifier
8459 package can be specified with the @code{#:uglify-js} parameter, but it
8460 is expected that the package writes the minified code to the standard
8463 When the input JavaScript files are not all located in the @file{src}
8464 directory, the parameter @code{#:javascript-files} can be used to
8465 specify a list of file names to feed to the minifier.
8468 @defvr {Scheme Variable} ocaml-build-system
8469 This variable is exported by @code{(guix build-system ocaml)}. It implements
8470 a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
8471 of choosing the correct set of commands to run for each package. OCaml
8472 packages can expect many different commands to be run. This build system will
8475 When the package has a @file{setup.ml} file present at the top-level, it will
8476 run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
8477 @code{ocaml setup.ml -install}. The build system will assume that this file
8478 was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
8479 care of setting the prefix and enabling tests if they are not disabled. You
8480 can pass configure and build flags with the @code{#:configure-flags} and
8481 @code{#:build-flags}. The @code{#:test-flags} key can be passed to change the
8482 set of flags used to enable tests. The @code{#:use-make?} key can be used to
8483 bypass this system in the build and install phases.
8485 When the package has a @file{configure} file, it is assumed that it is a
8486 hand-made configure script that requires a different argument format than
8487 in the @code{gnu-build-system}. You can add more flags with the
8488 @code{#:configure-flags} key.
8490 When the package has a @file{Makefile} file (or @code{#:use-make?} is
8491 @code{#t}), it will be used and more flags can be passed to the build and
8492 install phases with the @code{#:make-flags} key.
8494 Finally, some packages do not have these files and use a somewhat standard
8495 location for its build system. In that case, the build system will run
8496 @code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
8497 providing the path to the required findlib module. Additional flags can
8498 be passed via the @code{#:build-flags} key. Install is taken care of by
8499 @command{opam-installer}. In this case, the @code{opam} package must
8500 be added to the @code{native-inputs} field of the package definition.
8502 Note that most OCaml packages assume they will be installed in the same
8503 directory as OCaml, which is not what we want in guix. In particular, they
8504 will install @file{.so} files in their module's directory, which is usually
8505 fine because it is in the OCaml compiler directory. In guix though, these
8506 libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}. This
8507 variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
8508 @file{.so} libraries should be installed.
8511 @defvr {Scheme Variable} python-build-system
8512 This variable is exported by @code{(guix build-system python)}. It
8513 implements the more or less standard build procedure used by Python
8514 packages, which consists in running @code{python setup.py build} and
8515 then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
8517 For packages that install stand-alone Python programs under @code{bin/},
8518 it takes care of wrapping these programs so that their
8519 @env{GUIX_PYTHONPATH} environment variable points to all the Python
8520 libraries they depend on.
8522 Which Python package is used to perform the build can be specified with
8523 the @code{#:python} parameter. This is a useful way to force a package
8524 to be built for a specific version of the Python interpreter, which
8525 might be necessary if the package is only compatible with a single
8526 interpreter version.
8528 By default guix calls @code{setup.py} under control of
8529 @code{setuptools}, much like @command{pip} does. Some packages are not
8530 compatible with setuptools (and pip), thus you can disable this by
8531 setting the @code{#:use-setuptools?} parameter to @code{#f}.
8533 If a @code{"python"} output is available, the package is installed into it
8534 instead of the default @code{"out"} output. This is useful for packages that
8535 include a Python package as only a part of the software, and thus want to
8536 combine the phases of @code{python-build-system} with another build system.
8537 Python bindings are a common usecase.
8541 @defvr {Scheme Variable} perl-build-system
8542 This variable is exported by @code{(guix build-system perl)}. It
8543 implements the standard build procedure for Perl packages, which either
8544 consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
8545 followed by @code{Build} and @code{Build install}; or in running
8546 @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
8547 @code{make} and @code{make install}, depending on which of
8548 @code{Build.PL} or @code{Makefile.PL} is present in the package
8549 distribution. Preference is given to the former if both @code{Build.PL}
8550 and @code{Makefile.PL} exist in the package distribution. This
8551 preference can be reversed by specifying @code{#t} for the
8552 @code{#:make-maker?} parameter.
8554 The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
8555 passes flags specified by the @code{#:make-maker-flags} or
8556 @code{#:module-build-flags} parameter, respectively.
8558 Which Perl package is used can be specified with @code{#:perl}.
8561 @defvr {Scheme Variable} renpy-build-system
8562 This variable is exported by @code{(guix build-system renpy)}. It implements
8563 the more or less standard build procedure used by Ren'py games, which consists
8564 of loading @code{#:game} once, thereby creating bytecode for it.
8566 It further creates a wrapper script in @code{bin/} and a desktop entry in
8567 @code{share/applications}, both of which can be used to launch the game.
8569 Which Ren'py package is used can be specified with @code{#:renpy}.
8570 Games can also be installed in outputs other than ``out'' by using
8574 @defvr {Scheme Variable} qt-build-system
8575 This variable is exported by @code{(guix build-system qt)}. It
8576 is intended for use with applications using Qt or KDE.
8578 This build system adds the following two phases to the ones defined by
8579 @code{cmake-build-system}:
8583 The phase @code{check-setup} prepares the environment for running
8584 the checks as commonly used by Qt test programs.
8585 For now this only sets some environment variables:
8586 @code{QT_QPA_PLATFORM=offscreen},
8587 @code{DBUS_FATAL_WARNINGS=0} and
8588 @code{CTEST_OUTPUT_ON_FAILURE=1}.
8590 This phase is added before the @code{check} phase.
8591 It's a separate phase to ease adjusting if necessary.
8594 The phase @code{qt-wrap}
8595 searches for Qt5 plugin paths, QML paths and some XDG in the inputs
8596 and output. In case some path is found, all programs in the output's
8597 @file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
8598 are wrapped in scripts defining the necessary environment variables.
8600 It is possible to exclude specific package outputs from that wrapping process
8601 by listing their names in the @code{#:qt-wrap-excluded-outputs} parameter.
8602 This is useful when an output is known not to contain any Qt binaries, and
8603 where wrapping would gratuitously add a dependency of that output on Qt, KDE,
8606 This phase is added after the @code{install} phase.
8610 @defvr {Scheme Variable} r-build-system
8611 This variable is exported by @code{(guix build-system r)}. It
8612 implements the build procedure used by @uref{https://r-project.org, R}
8613 packages, which essentially is little more than running @samp{R CMD
8614 INSTALL --library=/gnu/store/@dots{}} in an environment where
8615 @env{R_LIBS_SITE} contains the paths to all R package inputs. Tests are
8616 run after installation using the R function
8617 @code{tools::testInstalledPackage}.
8620 @defvr {Scheme Variable} rakudo-build-system
8621 This variable is exported by @code{(guix build-system rakudo)}. It
8622 implements the build procedure used by @uref{https://rakudo.org/,
8623 Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
8624 package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
8625 installs the binaries, library files and the resources, as well as wrap
8626 the files under the @code{bin/} directory. Tests can be skipped by
8627 passing @code{#f} to the @code{tests?} parameter.
8629 Which rakudo package is used can be specified with @code{rakudo}.
8630 Which perl6-tap-harness package used for the tests can be specified with
8631 @code{#:prove6} or removed by passing @code{#f} to the
8632 @code{with-prove6?} parameter.
8633 Which perl6-zef package used for tests and installing can be specified
8634 with @code{#:zef} or removed by passing @code{#f} to the
8635 @code{with-zef?} parameter.
8638 @defvr {Scheme Variable} texlive-build-system
8639 This variable is exported by @code{(guix build-system texlive)}. It is
8640 used to build TeX packages in batch mode with a specified engine. The
8641 build system sets the @env{TEXINPUTS} variable to find all TeX source
8642 files in the inputs.
8644 By default it runs @code{luatex} on all files ending on @code{ins}. A
8645 different engine and format can be specified with the
8646 @code{#:tex-format} argument. Different build targets can be specified
8647 with the @code{#:build-targets} argument, which expects a list of file
8648 names. The build system adds only @code{texlive-bin} and
8649 @code{texlive-latex-base} (both from @code{(gnu packages tex}) to the
8650 inputs. Both can be overridden with the arguments @code{#:texlive-bin}
8651 and @code{#:texlive-latex-base}, respectively.
8653 The @code{#:tex-directory} parameter tells the build system where to
8654 install the built files under the texmf tree.
8657 @defvr {Scheme Variable} ruby-build-system
8658 This variable is exported by @code{(guix build-system ruby)}. It
8659 implements the RubyGems build procedure used by Ruby packages, which
8660 involves running @code{gem build} followed by @code{gem install}.
8662 The @code{source} field of a package that uses this build system
8663 typically references a gem archive, since this is the format that Ruby
8664 developers use when releasing their software. The build system unpacks
8665 the gem archive, potentially patches the source, runs the test suite,
8666 repackages the gem, and installs it. Additionally, directories and
8667 tarballs may be referenced to allow building unreleased gems from Git or
8668 a traditional source release tarball.
8670 Which Ruby package is used can be specified with the @code{#:ruby}
8671 parameter. A list of additional flags to be passed to the @command{gem}
8672 command can be specified with the @code{#:gem-flags} parameter.
8675 @defvr {Scheme Variable} waf-build-system
8676 This variable is exported by @code{(guix build-system waf)}. It
8677 implements a build procedure around the @code{waf} script. The common
8678 phases---@code{configure}, @code{build}, and @code{install}---are
8679 implemented by passing their names as arguments to the @code{waf}
8682 The @code{waf} script is executed by the Python interpreter. Which
8683 Python package is used to run the script can be specified with the
8684 @code{#:python} parameter.
8687 @defvr {Scheme Variable} scons-build-system
8688 This variable is exported by @code{(guix build-system scons)}. It
8689 implements the build procedure used by the SCons software construction
8690 tool. This build system runs @code{scons} to build the package,
8691 @code{scons test} to run tests, and then @code{scons install} to install
8694 Additional flags to be passed to @code{scons} can be specified with the
8695 @code{#:scons-flags} parameter. The default build and install targets
8696 can be overridden with @code{#:build-targets} and
8697 @code{#:install-targets} respectively. The version of Python used to
8698 run SCons can be specified by selecting the appropriate SCons package
8699 with the @code{#:scons} parameter.
8702 @defvr {Scheme Variable} haskell-build-system
8703 This variable is exported by @code{(guix build-system haskell)}. It
8704 implements the Cabal build procedure used by Haskell packages, which
8705 involves running @code{runhaskell Setup.hs configure
8706 --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
8707 Instead of installing the package by running @code{runhaskell Setup.hs
8708 install}, to avoid trying to register libraries in the read-only
8709 compiler store directory, the build system uses @code{runhaskell
8710 Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
8711 addition, the build system generates the package documentation by
8712 running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
8713 is passed. Optional Haddock parameters can be passed with the help of
8714 the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
8715 not found, the build system looks for @code{Setup.lhs} instead.
8717 Which Haskell compiler is used can be specified with the @code{#:haskell}
8718 parameter which defaults to @code{ghc}.
8721 @defvr {Scheme Variable} dub-build-system
8722 This variable is exported by @code{(guix build-system dub)}. It
8723 implements the Dub build procedure used by D packages, which
8724 involves running @code{dub build} and @code{dub run}.
8725 Installation is done by copying the files manually.
8727 Which D compiler is used can be specified with the @code{#:ldc}
8728 parameter which defaults to @code{ldc}.
8731 @anchor{emacs-build-system}
8732 @defvr {Scheme Variable} emacs-build-system
8733 This variable is exported by @code{(guix build-system emacs)}. It
8734 implements an installation procedure similar to the packaging system
8735 of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
8737 It first creates the @code{@code{package}-autoloads.el} file, then it
8738 byte compiles all Emacs Lisp files. Differently from the Emacs
8739 packaging system, the Info documentation files are moved to the standard
8740 documentation directory and the @file{dir} file is deleted. The Elisp
8741 package files are installed directly under @file{share/emacs/site-lisp}.
8744 @defvr {Scheme Variable} font-build-system
8745 This variable is exported by @code{(guix build-system font)}. It
8746 implements an installation procedure for font packages where upstream
8747 provides pre-compiled TrueType, OpenType, etc.@: font files that merely
8748 need to be copied into place. It copies font files to standard
8749 locations in the output directory.
8752 @defvr {Scheme Variable} meson-build-system
8753 This variable is exported by @code{(guix build-system meson)}. It
8754 implements the build procedure for packages that use
8755 @url{https://mesonbuild.com, Meson} as their build system.
8757 It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
8758 of inputs, and they can be changed with the parameters @code{#:meson}
8759 and @code{#:ninja} if needed.
8761 This build system is an extension of @code{gnu-build-system}, but with the
8762 following phases changed to some specific for Meson:
8767 The phase runs @code{meson} with the flags specified in
8768 @code{#:configure-flags}. The flag @option{--buildtype} is always set to
8769 @code{debugoptimized} unless something else is specified in
8770 @code{#:build-type}.
8773 The phase runs @code{ninja} to build the package in parallel by default, but
8774 this can be changed with @code{#:parallel-build?}.
8777 The phase runs @samp{meson test} with a base set of options that cannot
8778 be overridden. This base set of options can be extended via the
8779 @code{#:test-options} argument, for example to select or skip a specific
8783 The phase runs @code{ninja install} and can not be changed.
8786 Apart from that, the build system also adds the following phases:
8791 This phase ensures that all binaries can find the libraries they need.
8792 It searches for required libraries in subdirectories of the package
8793 being built, and adds those to @code{RUNPATH} where needed. It also
8794 removes references to libraries left over from the build phase by
8795 @code{meson}, such as test dependencies, that aren't actually required
8796 for the program to run.
8798 @item glib-or-gtk-wrap
8799 This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
8800 is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
8802 @item glib-or-gtk-compile-schemas
8803 This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
8804 is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
8808 @defvr {Scheme Variable} linux-module-build-system
8809 @code{linux-module-build-system} allows building Linux kernel modules.
8811 @cindex build phases
8812 This build system is an extension of @code{gnu-build-system}, but with the
8813 following phases changed:
8818 This phase configures the environment so that the Linux kernel's Makefile
8819 can be used to build the external kernel module.
8822 This phase uses the Linux kernel's Makefile in order to build the external
8826 This phase uses the Linux kernel's Makefile in order to install the external
8830 It is possible and useful to specify the Linux kernel to use for building
8831 the module (in the @code{arguments} form of a package using the
8832 @code{linux-module-build-system}, use the key @code{#:linux} to specify it).
8835 @defvr {Scheme Variable} node-build-system
8836 This variable is exported by @code{(guix build-system node)}. It
8837 implements the build procedure used by @uref{https://nodejs.org,
8838 Node.js}, which implements an approximation of the @code{npm install}
8839 command, followed by an @code{npm test} command.
8841 Which Node.js package is used to interpret the @code{npm} commands can
8842 be specified with the @code{#:node} parameter which defaults to
8846 Lastly, for packages that do not need anything as sophisticated, a
8847 ``trivial'' build system is provided. It is trivial in the sense that
8848 it provides basically no support: it does not pull any implicit inputs,
8849 and does not have a notion of build phases.
8851 @defvr {Scheme Variable} trivial-build-system
8852 This variable is exported by @code{(guix build-system trivial)}.
8854 This build system requires a @code{#:builder} argument. This argument
8855 must be a Scheme expression that builds the package output(s)---as
8856 with @code{build-expression->derivation} (@pxref{Derivations,
8857 @code{build-expression->derivation}}).
8861 @section Build Phases
8863 @cindex build phases, for packages
8864 Almost all package build systems implement a notion @dfn{build phases}:
8865 a sequence of actions that the build system executes, when you build the
8866 package, leading to the installed byproducts in the store. A notable
8867 exception is the ``bare-bones'' @code{trivial-build-system}
8868 (@pxref{Build Systems}).
8870 As discussed in the previous section, those build systems provide a
8871 standard list of phases. For @code{gnu-build-system}, the main build
8872 phases are the following:
8876 Unpack the source tarball, and change the current directory to the
8877 extracted source tree. If the source is actually a directory, copy it
8878 to the build tree, and enter that directory.
8880 @item patch-source-shebangs
8881 Patch shebangs encountered in source files so they refer to the right
8882 store file names. For instance, this changes @code{#!/bin/sh} to
8883 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
8886 Run the @file{configure} script with a number of default options, such
8887 as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
8888 by the @code{#:configure-flags} argument.
8891 Run @code{make} with the list of flags specified with
8892 @code{#:make-flags}. If the @code{#:parallel-build?} argument is true
8893 (the default), build with @code{make -j}.
8896 Run @code{make check}, or some other target specified with
8897 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
8898 @code{#:parallel-tests?} argument is true (the default), run @code{make
8902 Run @code{make install} with the flags listed in @code{#:make-flags}.
8904 @item patch-shebangs
8905 Patch shebangs on the installed executable files.
8908 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
8909 is false), copying them to the @code{debug} output when available
8910 (@pxref{Installing Debugging Files}).
8913 Other build systems have similar phases, with some variations. For
8914 example, @code{cmake-build-system} has same-named phases but its
8915 @code{configure} phases runs @code{cmake} instead of @code{./configure}.
8916 Others, such as @code{python-build-system}, have a wholly different list
8917 of standard phases. All this code runs on the @dfn{build side}: it is
8918 evaluated when you actually build the package, in a dedicated build
8919 process spawned by the build daemon (@pxref{Invoking guix-daemon}).
8921 Build phases are represented as association lists or ``alists''
8922 (@pxref{Association Lists,,, guile, GNU Guile Reference Manual}) where
8923 each key is a symbol for the name of the phase and the associated value
8924 is a procedure that accepts an arbitrary number of arguments. By
8925 convention, those procedures receive information about the build in the
8926 form of @dfn{keyword parameters}, which they can use or ignore.
8928 @vindex %standard-phases
8929 For example, here is how @code{(guix build gnu-build-system)} defines
8930 @code{%standard-phases}, the variable holding its alist of build
8931 phases@footnote{We present a simplified view of those build phases, but
8932 do take a look at @code{(guix build gnu-build-system)} to see all the
8936 ;; The build phases of 'gnu-build-system'.
8938 (define* (unpack #:key source #:allow-other-keys)
8939 ;; Extract the source tarball.
8940 (invoke "tar" "xvf" source))
8942 (define* (configure #:key outputs #:allow-other-keys)
8943 ;; Run the 'configure' script. Install to output "out".
8944 (let ((out (assoc-ref outputs "out")))
8945 (invoke "./configure"
8946 (string-append "--prefix=" out))))
8948 (define* (build #:allow-other-keys)
8952 (define* (check #:key (test-target "check") (tests? #true)
8954 ;; Run the test suite.
8956 (invoke "make" test-target)
8957 (display "test suite not run\n")))
8959 (define* (install #:allow-other-keys)
8960 ;; Install files to the prefix 'configure' specified.
8961 (invoke "make" "install"))
8963 (define %standard-phases
8964 ;; The list of standard phases (quite a few are omitted
8965 ;; for brevity). Each element is a symbol/procedure pair.
8966 (list (cons 'unpack unpack)
8967 (cons 'configure configure)
8970 (cons 'install install)))
8973 This shows how @code{%standard-phases} is defined as a list of
8974 symbol/procedure pairs (@pxref{Pairs,,, guile, GNU Guile Reference
8975 Manual}). The first pair associates the @code{unpack} procedure with
8976 the @code{unpack} symbol---a name; the second pair defines the
8977 @code{configure} phase similarly, and so on. When building a package
8978 that uses @code{gnu-build-system} with its default list of phases, those
8979 phases are executed sequentially. You can see the name of each phase
8980 started and completed in the build log of packages that you build.
8982 Let's now look at the procedures themselves. Each one is defined with
8983 @code{define*}: @code{#:key} lists keyword parameters the procedure
8984 accepts, possibly with a default value, and @code{#:allow-other-keys}
8985 specifies that other keyword parameters are ignored (@pxref{Optional
8986 Arguments,,, guile, GNU Guile Reference Manual}).
8988 The @code{unpack} procedure honors the @code{source} parameter, which
8989 the build system uses to pass the file name of the source tarball (or
8990 version control checkout), and it ignores other parameters. The
8991 @code{configure} phase only cares about the @code{outputs} parameter, an
8992 alist mapping package output names to their store file name
8993 (@pxref{Packages with Multiple Outputs}). It extracts the file name of
8994 for @code{out}, the default output, and passes it to
8995 @command{./configure} as the installation prefix, meaning that
8996 @command{make install} will eventually copy all the files in that
8997 directory (@pxref{Configuration, configuration and makefile
8998 conventions,, standards, GNU Coding Standards}). @code{build} and
8999 @code{install} ignore all their arguments. @code{check} honors the
9000 @code{test-target} argument, which specifies the name of the Makefile
9001 target to run tests; it prints a message and skips tests when
9002 @code{tests?} is false.
9004 @cindex build phases, customizing
9005 The list of phases used for a particular package can be changed with the
9006 @code{#:phases} parameter of the build system. Changing the set of
9007 build phases boils down to building a new alist of phases based on the
9008 @code{%standard-phases} alist described above. This can be done with
9009 standard alist procedures such as @code{alist-delete} (@pxref{SRFI-1
9010 Association Lists,,, guile, GNU Guile Reference Manual}); however, it is
9011 more convenient to do so with @code{modify-phases} (@pxref{Build
9012 Utilities, @code{modify-phases}}).
9014 Here is an example of a package definition that removes the
9015 @code{configure} phase of @code{%standard-phases} and inserts a new
9016 phase before the @code{build} phase, called
9017 @code{set-prefix-in-makefile}:
9020 (define-public example
9023 ;; other fields omitted
9024 (build-system gnu-build-system)
9026 '(#:phases (modify-phases %standard-phases
9028 (add-before 'build 'set-prefix-in-makefile
9029 (lambda* (#:key outputs #:allow-other-keys)
9030 ;; Modify the makefile so that its
9031 ;; 'PREFIX' variable points to "out".
9032 (let ((out (assoc-ref outputs "out")))
9033 (substitute* "Makefile"
9035 (string-append "PREFIX = "
9040 The new phase that is inserted is written as an anonymous procedure,
9041 introduced with @code{lambda*}; it honors the @code{outputs} parameter
9042 we have seen before. @xref{Build Utilities}, for more about the helpers
9043 used by this phase, and for more examples of @code{modify-phases}.
9045 @cindex code staging
9046 @cindex staging, of code
9047 Keep in mind that build phases are code evaluated at the time the
9048 package is actually built. This explains why the whole
9049 @code{modify-phases} expression above is quoted (it comes after the
9050 @code{'} or apostrophe): it is @dfn{staged} for later execution.
9051 @xref{G-Expressions}, for an explanation of code staging and the
9052 @dfn{code strata} involved.
9054 @node Build Utilities
9055 @section Build Utilities
9057 As soon as you start writing non-trivial package definitions
9058 (@pxref{Defining Packages}) or other build actions
9059 (@pxref{G-Expressions}), you will likely start looking for helpers for
9060 ``shell-like'' actions---creating directories, copying and deleting
9061 files recursively, manipulating build phases, and so on. The
9062 @code{(guix build utils)} module provides such utility procedures.
9064 Most build systems load @code{(guix build utils)} (@pxref{Build
9065 Systems}). Thus, when writing custom build phases for your package
9066 definitions, you can usually assume those procedures are in scope.
9068 When writing G-expressions, you can import @code{(guix build utils)} on
9069 the ``build side'' using @code{with-imported-modules} and then put it in
9070 scope with the @code{use-modules} form (@pxref{Using Guile Modules,,,
9071 guile, GNU Guile Reference Manual}):
9074 (with-imported-modules '((guix build utils)) ;import it
9075 (computed-file "empty-tree"
9078 (use-modules (guix build utils))
9080 ;; Happily use its 'mkdir-p' procedure.
9081 (mkdir-p (string-append #$output "/a/b/c")))))
9084 The remainder of this section is the reference for most of the utility
9085 procedures provided by @code{(guix build utils)}.
9087 @c TODO Document what's missing.
9089 @subsection Dealing with Store File Names
9091 This section documents procedures that deal with store file names.
9093 @deffn {Scheme Procedure} %store-directory
9094 Return the directory name of the store.
9097 @deffn {Scheme Procedure} store-file-name? @var{file}
9098 Return true if @var{file} is in the store.
9101 @deffn {Scheme Procedure} strip-store-file-name @var{file}
9102 Strip the @file{/gnu/store} and hash from @var{file}, a store file name.
9103 The result is typically a @code{"@var{package}-@var{version}"} string.
9106 @deffn {Scheme Procedure} package-name->name+version @var{name}
9107 Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two
9108 values: @code{"foo"} and @code{"0.9.1b"}. When the version part is
9109 unavailable, @var{name} and @code{#f} are returned. The first hyphen
9110 followed by a digit is considered to introduce the version part.
9113 @subsection File Types
9115 The procedures below deal with files and file types.
9117 @deffn {Scheme Procedure} directory-exists? @var{dir}
9118 Return @code{#t} if @var{dir} exists and is a directory.
9121 @deffn {Scheme Procedure} executable-file? @var{file}
9122 Return @code{#t} if @var{file} exists and is executable.
9125 @deffn {Scheme Procedure} symbolic-link? @var{file}
9126 Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
9129 @deffn {Scheme Procedure} elf-file? @var{file}
9130 @deffnx {Scheme Procedure} ar-file? @var{file}
9131 @deffnx {Scheme Procedure} gzip-file? @var{file}
9132 Return @code{#t} if @var{file} is, respectively, an ELF file, an
9133 @code{ar} archive (such as a @file{.a} static library), or a gzip file.
9136 @deffn {Scheme Procedure} reset-gzip-timestamp @var{file} [#:keep-mtime? #t]
9137 If @var{file} is a gzip file, reset its embedded timestamp (as with
9138 @command{gzip --no-name}) and return true. Otherwise return @code{#f}.
9139 When @var{keep-mtime?} is true, preserve @var{file}'s modification time.
9142 @subsection File Manipulation
9144 The following procedures and macros help create, modify, and delete
9145 files. They provide functionality comparable to common shell utilities
9146 such as @command{mkdir -p}, @command{cp -r}, @command{rm -r}, and
9147 @command{sed}. They complement Guile's extensive, but low-level, file
9148 system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}).
9150 @deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{}
9151 Run @var{body} with @var{directory} as the process's current directory.
9153 Essentially, this macro changes the current directory to @var{directory}
9154 before evaluating @var{body}, using @code{chdir} (@pxref{Processes,,,
9155 guile, GNU Guile Reference Manual}). It changes back to the initial
9156 directory when the dynamic extent of @var{body} is left, be it @i{via}
9157 normal procedure return or @i{via} a non-local exit such as an
9161 @deffn {Scheme Procedure} mkdir-p @var{dir}
9162 Create directory @var{dir} and all its ancestors.
9165 @deffn {Scheme Procedure} install-file @var{file} @var{directory}
9166 Create @var{directory} if it does not exist and copy @var{file} in there
9167 under the same name.
9170 @deffn {Scheme Procedure} make-file-writable @var{file}
9171 Make @var{file} writable for its owner.
9174 @deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @
9175 [#:log (current-output-port)] [#:follow-symlinks? #f] @
9176 [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]
9177 Copy @var{source} directory to @var{destination}. Follow symlinks if
9178 @var{follow-symlinks?} is true; otherwise, just preserve them. Call
9179 @var{copy-file} to copy regular files. When @var{keep-mtime?} is true,
9180 keep the modification time of the files in @var{source} on those of
9181 @var{destination}. When @var{keep-permissions?} is true, preserve file
9182 permissions. Write verbose output to the @var{log} port.
9185 @deffn {Scheme Procedure} delete-file-recursively @var{dir} @
9186 [#:follow-mounts? #f]
9187 Delete @var{dir} recursively, like @command{rm -rf}, without following
9188 symlinks. Don't follow mount points either, unless @var{follow-mounts?}
9189 is true. Report but ignore errors.
9192 @deffn {Scheme Syntax} substitute* @var{file} @
9193 ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{}
9194 Substitute @var{regexp} in @var{file} by the string returned by
9195 @var{body}. @var{body} is evaluated with each @var{match-var} bound to
9196 the corresponding positional regexp sub-expression. For example:
9202 (("foo([a-z]+)bar(.*)$" all letters end)
9203 (string-append "baz" letters end)))
9206 Here, anytime a line of @var{file} contains @code{hello}, it is replaced
9207 by @code{good morning}. Anytime a line of @var{file} matches the second
9208 regexp, @code{all} is bound to the complete match, @code{letters} is bound
9209 to the first sub-expression, and @code{end} is bound to the last one.
9211 When one of the @var{match-var} is @code{_}, no variable is bound to the
9212 corresponding match substring.
9214 Alternatively, @var{file} may be a list of file names, in which case
9215 they are all subject to the substitutions.
9217 Be careful about using @code{$} to match the end of a line; by itself it
9218 won't match the terminating newline of a line.
9221 @subsection File Search
9223 @cindex file, searching
9224 This section documents procedures to search and filter files.
9226 @deffn {Scheme Procedure} file-name-predicate @var{regexp}
9227 Return a predicate that returns true when passed a file name whose base
9228 name matches @var{regexp}.
9231 @deffn {Scheme Procedure} find-files @var{dir} [@var{pred}] @
9232 [#:stat lstat] [#:directories? #f] [#:fail-on-error? #f]
9233 Return the lexicographically sorted list of files under @var{dir} for
9234 which @var{pred} returns true. @var{pred} is passed two arguments: the
9235 absolute file name, and its stat buffer; the default predicate always
9236 returns true. @var{pred} can also be a regular expression, in which
9237 case it is equivalent to @code{(file-name-predicate @var{pred})}.
9238 @var{stat} is used to obtain file information; using @code{lstat} means
9239 that symlinks are not followed. If @var{directories?} is true, then
9240 directories will also be included. If @var{fail-on-error?} is true,
9241 raise an exception upon error.
9244 Here are a few examples where we assume that the current directory is
9245 the root of the Guix source tree:
9248 ;; List all the regular files in the current directory.
9250 @result{} ("./.dir-locals.el" "./.gitignore" @dots{})
9252 ;; List all the .scm files under gnu/services.
9253 (find-files "gnu/services" "\\.scm$")
9254 @result{} ("gnu/services/admin.scm" "gnu/services/audio.scm" @dots{})
9256 ;; List ar files in the current directory.
9257 (find-files "." (lambda (file stat) (ar-file? file)))
9258 @result{} ("./libformat.a" "./libstore.a" @dots{})
9261 @deffn {Scheme Procedure} which @var{program}
9262 Return the complete file name for @var{program} as found in
9263 @code{$PATH}, or @code{#f} if @var{program} could not be found.
9266 @deffn {Scheme Procedure} search-input-file @var{inputs} @var{name}
9267 @deffnx {Scheme Procedure} search-input-directory @var{inputs} @var{name}
9268 Return the complete file name for @var{name} as found in @var{inputs};
9269 @code{search-input-file} searches for a regular file and
9270 @code{search-input-directory} searches for a directory. If @var{name}
9271 could not be found, an exception is raised.
9273 Here, @var{inputs} must be an association list like @code{inputs} and
9274 @code{native-inputs} as available to build phases (@pxref{Build
9278 Here is a (simplified) example of how @code{search-input-file} is used
9279 in a build phase of the @code{wireguard-tools} package:
9282 (add-after 'install 'wrap-wg-quick
9283 (lambda* (#:key inputs outputs #:allow-other-keys)
9284 (let ((coreutils (string-append (assoc-ref inputs "coreutils")
9286 (wrap-program (search-input-file outputs "bin/wg-quick")
9287 #:sh (search-input-file inputs "bin/bash")
9288 `("PATH" ":" prefix ,(list coreutils))))))
9291 @subsection Build Phases
9293 @cindex build phases
9294 The @code{(guix build utils)} also contains tools to manipulate build
9295 phases as used by build systems (@pxref{Build Systems}). Build phases
9296 are represented as association lists or ``alists'' (@pxref{Association
9297 Lists,,, guile, GNU Guile Reference Manual}) where each key is a symbol
9298 naming the phase and the associated value is a procedure (@pxref{Build
9301 Guile core and the @code{(srfi srfi-1)} module both provide tools to
9302 manipulate alists. The @code{(guix build utils)} module complements
9303 those with tools written with build phases in mind.
9305 @cindex build phases, modifying
9306 @deffn {Scheme Syntax} modify-phases @var{phases} @var{clause}@dots{}
9307 Modify @var{phases} sequentially as per each @var{clause}, which may
9308 have one of the following forms:
9311 (delete @var{old-phase-name})
9312 (replace @var{old-phase-name} @var{new-phase})
9313 (add-before @var{old-phase-name} @var{new-phase-name} @var{new-phase})
9314 (add-after @var{old-phase-name} @var{new-phase-name} @var{new-phase})
9317 Where every @var{phase-name} above is an expression evaluating to a
9318 symbol, and @var{new-phase} an expression evaluating to a procedure.
9321 The example below is taken from the definition of the @code{grep}
9322 package. It adds a phase to run after the @code{install} phase, called
9323 @code{fix-egrep-and-fgrep}. That phase is a procedure (@code{lambda*}
9324 is for anonymous procedures) that takes a @code{#:outputs} keyword
9325 argument and ignores extra keyword arguments (@pxref{Optional
9326 Arguments,,, guile, GNU Guile Reference Manual}, for more on
9327 @code{lambda*} and optional and keyword arguments.) The phase uses
9328 @code{substitute*} to modify the installed @file{egrep} and @file{fgrep}
9329 scripts so that they refer to @code{grep} by its absolute file name:
9332 (modify-phases %standard-phases
9333 (add-after 'install 'fix-egrep-and-fgrep
9334 ;; Patch 'egrep' and 'fgrep' to execute 'grep' via its
9335 ;; absolute file name instead of searching for it in $PATH.
9336 (lambda* (#:key outputs #:allow-other-keys)
9337 (let* ((out (assoc-ref outputs "out"))
9338 (bin (string-append out "/bin")))
9339 (substitute* (list (string-append bin "/egrep")
9340 (string-append bin "/fgrep"))
9342 (string-append "exec " bin "/grep")))
9346 In the example below, phases are modified in two ways: the standard
9347 @code{configure} phase is deleted, presumably because the package does
9348 not have a @file{configure} script or anything similar, and the default
9349 @code{install} phase is replaced by one that manually copies the
9350 executable files to be installed:
9353 (modify-phases %standard-phases
9354 (delete 'configure) ;no 'configure' script
9356 (lambda* (#:key outputs #:allow-other-keys)
9357 ;; The package's Makefile doesn't provide an "install"
9358 ;; rule so do it by ourselves.
9359 (let ((bin (string-append (assoc-ref outputs "out")
9361 (install-file "footswitch" bin)
9362 (install-file "scythe" bin)
9366 @c TODO: Add more examples.
9375 Conceptually, the @dfn{store} is the place where derivations that have
9376 been built successfully are stored---by default, @file{/gnu/store}.
9377 Sub-directories in the store are referred to as @dfn{store items} or
9378 sometimes @dfn{store paths}. The store has an associated database that
9379 contains information such as the store paths referred to by each store
9380 path, and the list of @emph{valid} store items---results of successful
9381 builds. This database resides in @file{@var{localstatedir}/guix/db},
9382 where @var{localstatedir} is the state directory specified @i{via}
9383 @option{--localstatedir} at configure time, usually @file{/var}.
9385 The store is @emph{always} accessed by the daemon on behalf of its clients
9386 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
9387 connect to the daemon over a Unix-domain socket, send requests to it,
9388 and read the result---these are remote procedure calls, or RPCs.
9391 Users must @emph{never} modify files under @file{/gnu/store} directly.
9392 This would lead to inconsistencies and break the immutability
9393 assumptions of Guix's functional model (@pxref{Introduction}).
9395 @xref{Invoking guix gc, @command{guix gc --verify}}, for information on
9396 how to check the integrity of the store and attempt recovery from
9397 accidental modifications.
9400 The @code{(guix store)} module provides procedures to connect to the
9401 daemon, and to perform RPCs. These are described below. By default,
9402 @code{open-connection}, and thus all the @command{guix} commands,
9403 connect to the local daemon or to the URI specified by the
9404 @env{GUIX_DAEMON_SOCKET} environment variable.
9406 @defvr {Environment Variable} GUIX_DAEMON_SOCKET
9407 When set, the value of this variable should be a file name or a URI
9408 designating the daemon endpoint. When it is a file name, it denotes a
9409 Unix-domain socket to connect to. In addition to file names, the
9410 supported URI schemes are:
9415 These are for Unix-domain sockets.
9416 @code{file:///var/guix/daemon-socket/socket} is equivalent to
9417 @file{/var/guix/daemon-socket/socket}.
9420 @cindex daemon, remote access
9421 @cindex remote access to the daemon
9422 @cindex daemon, cluster setup
9423 @cindex clusters, daemon setup
9424 These URIs denote connections over TCP/IP, without encryption nor
9425 authentication of the remote host. The URI must specify the host name
9426 and optionally a port number (by default port 44146 is used):
9429 guix://master.guix.example.org:1234
9432 This setup is suitable on local networks, such as clusters, where only
9433 trusted nodes may connect to the build daemon at
9434 @code{master.guix.example.org}.
9436 The @option{--listen} option of @command{guix-daemon} can be used to
9437 instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
9438 @option{--listen}}).
9441 @cindex SSH access to build daemons
9442 These URIs allow you to connect to a remote daemon over SSH@. This
9443 feature requires Guile-SSH (@pxref{Requirements}) and a working
9444 @command{guile} binary in @env{PATH} on the destination machine. It
9445 supports public key and GSSAPI authentication. A typical URL might look
9449 ssh://charlie@@guix.example.org:22
9452 As for @command{guix copy}, the usual OpenSSH client configuration files
9453 are honored (@pxref{Invoking guix copy}).
9456 Additional URI schemes may be supported in the future.
9458 @c XXX: Remove this note when the protocol incurs fewer round trips
9459 @c and when (guix derivations) no longer relies on file system access.
9461 The ability to connect to remote build daemons is considered
9462 experimental as of @value{VERSION}. Please get in touch with us to
9463 share any problems or suggestions you may have (@pxref{Contributing}).
9467 @deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
9468 Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When
9469 @var{reserve-space?} is true, instruct it to reserve a little bit of
9470 extra space on the file system so that the garbage collector can still
9471 operate should the disk become full. Return a server object.
9473 @var{file} defaults to @code{%default-socket-path}, which is the normal
9474 location given the options that were passed to @command{configure}.
9477 @deffn {Scheme Procedure} close-connection @var{server}
9478 Close the connection to @var{server}.
9481 @defvr {Scheme Variable} current-build-output-port
9482 This variable is bound to a SRFI-39 parameter, which refers to the port
9483 where build and error logs sent by the daemon should be written.
9486 Procedures that make RPCs all take a server object as their first
9489 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
9490 @cindex invalid store items
9491 Return @code{#t} when @var{path} designates a valid store item and
9492 @code{#f} otherwise (an invalid item may exist on disk but still be
9493 invalid, for instance because it is the result of an aborted or failed
9496 A @code{&store-protocol-error} condition is raised if @var{path} is not
9497 prefixed by the store directory (@file{/gnu/store}).
9500 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
9501 Add @var{text} under file @var{name} in the store, and return its store
9502 path. @var{references} is the list of store paths referred to by the
9503 resulting store path.
9506 @deffn {Scheme Procedure} build-derivations @var{store} @var{derivations} @
9508 Build @var{derivations}, a list of @code{<derivation>} objects, @file{.drv}
9509 file names, or derivation/output pairs, using the specified
9510 @var{mode}---@code{(build-mode normal)} by default.
9513 Note that the @code{(guix monads)} module provides a monad as well as
9514 monadic versions of the above procedures, with the goal of making it
9515 more convenient to work with code that accesses the store (@pxref{The
9519 @i{This section is currently incomplete.}
9522 @section Derivations
9525 Low-level build actions and the environment in which they are performed
9526 are represented by @dfn{derivations}. A derivation contains the
9527 following pieces of information:
9531 The outputs of the derivation---derivations produce at least one file or
9532 directory in the store, but may produce more.
9535 @cindex build-time dependencies
9536 @cindex dependencies, build-time
9537 The inputs of the derivations---i.e., its build-time dependencies---which may
9538 be other derivations or plain files in the store (patches, build scripts,
9542 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
9545 The file name of a build script in the store, along with the arguments
9549 A list of environment variables to be defined.
9553 @cindex derivation path
9554 Derivations allow clients of the daemon to communicate build actions to
9555 the store. They exist in two forms: as an in-memory representation,
9556 both on the client- and daemon-side, and as files in the store whose
9557 name end in @file{.drv}---these files are referred to as @dfn{derivation
9558 paths}. Derivations paths can be passed to the @code{build-derivations}
9559 procedure to perform the build actions they prescribe (@pxref{The
9562 @cindex fixed-output derivations
9563 Operations such as file downloads and version-control checkouts for
9564 which the expected content hash is known in advance are modeled as
9565 @dfn{fixed-output derivations}. Unlike regular derivations, the outputs
9566 of a fixed-output derivation are independent of its inputs---e.g., a
9567 source code download produces the same result regardless of the download
9568 method and tools being used.
9571 @cindex run-time dependencies
9572 @cindex dependencies, run-time
9573 The outputs of derivations---i.e., the build results---have a set of
9574 @dfn{references}, as reported by the @code{references} RPC or the
9575 @command{guix gc --references} command (@pxref{Invoking guix gc}). References
9576 are the set of run-time dependencies of the build results. References are a
9577 subset of the inputs of the derivation; this subset is automatically computed
9578 by the build daemon by scanning all the files in the outputs.
9580 The @code{(guix derivations)} module provides a representation of
9581 derivations as Scheme objects, along with procedures to create and
9582 otherwise manipulate derivations. The lowest-level primitive to create
9583 a derivation is the @code{derivation} procedure:
9585 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
9586 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
9587 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
9588 [#:system (%current-system)] [#:references-graphs #f] @
9589 [#:allowed-references #f] [#:disallowed-references #f] @
9590 [#:leaked-env-vars #f] [#:local-build? #f] @
9591 [#:substitutable? #t] [#:properties '()]
9592 Build a derivation with the given arguments, and return the resulting
9593 @code{<derivation>} object.
9595 When @var{hash} and @var{hash-algo} are given, a
9596 @dfn{fixed-output derivation} is created---i.e., one whose result is
9597 known in advance, such as a file download. If, in addition,
9598 @var{recursive?} is true, then that fixed output may be an executable
9599 file or a directory and @var{hash} must be the hash of an archive
9600 containing this output.
9602 When @var{references-graphs} is true, it must be a list of file
9603 name/store path pairs. In that case, the reference graph of each store
9604 path is exported in the build environment in the corresponding file, in
9605 a simple text format.
9607 When @var{allowed-references} is true, it must be a list of store items
9608 or outputs that the derivation's output may refer to. Likewise,
9609 @var{disallowed-references}, if true, must be a list of things the
9610 outputs may @emph{not} refer to.
9612 When @var{leaked-env-vars} is true, it must be a list of strings
9613 denoting environment variables that are allowed to ``leak'' from the
9614 daemon's environment to the build environment. This is only applicable
9615 to fixed-output derivations---i.e., when @var{hash} is true. The main
9616 use is to allow variables such as @code{http_proxy} to be passed to
9617 derivations that download files.
9619 When @var{local-build?} is true, declare that the derivation is not a
9620 good candidate for offloading and should rather be built locally
9621 (@pxref{Daemon Offload Setup}). This is the case for small derivations
9622 where the costs of data transfers would outweigh the benefits.
9624 When @var{substitutable?} is false, declare that substitutes of the
9625 derivation's output should not be used (@pxref{Substitutes}). This is
9626 useful, for instance, when building packages that capture details of the
9627 host CPU instruction set.
9629 @var{properties} must be an association list describing ``properties'' of the
9630 derivation. It is kept as-is, uninterpreted, in the derivation.
9634 Here's an example with a shell script as its builder, assuming
9635 @var{store} is an open connection to the daemon, and @var{bash} points
9636 to a Bash executable in the store:
9639 (use-modules (guix utils)
9643 (let ((builder ; add the Bash script to the store
9644 (add-text-to-store store "my-builder.sh"
9645 "echo hello world > $out\n" '())))
9646 (derivation store "foo"
9647 bash `("-e" ,builder)
9648 #:inputs `((,bash) (,builder))
9649 #:env-vars '(("HOME" . "/homeless"))))
9650 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
9653 As can be guessed, this primitive is cumbersome to use directly. A
9654 better approach is to write build scripts in Scheme, of course! The
9655 best course of action for that is to write the build code as a
9656 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
9657 information, @pxref{G-Expressions}.
9659 Once upon a time, @code{gexp->derivation} did not exist and constructing
9660 derivations with build code written in Scheme was achieved with
9661 @code{build-expression->derivation}, documented below. This procedure
9662 is now deprecated in favor of the much nicer @code{gexp->derivation}.
9664 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
9665 @var{name} @var{exp} @
9666 [#:system (%current-system)] [#:inputs '()] @
9667 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
9668 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
9669 [#:references-graphs #f] [#:allowed-references #f] @
9670 [#:disallowed-references #f] @
9671 [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
9672 Return a derivation that executes Scheme expression @var{exp} as a
9673 builder for derivation @var{name}. @var{inputs} must be a list of
9674 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
9675 @code{"out"} is assumed. @var{modules} is a list of names of Guile
9676 modules from the current search path to be copied in the store,
9677 compiled, and made available in the load path during the execution of
9678 @var{exp}---e.g., @code{((guix build utils) (guix build
9679 gnu-build-system))}.
9681 @var{exp} is evaluated in an environment where @code{%outputs} is bound
9682 to a list of output/path pairs, and where @code{%build-inputs} is bound
9683 to a list of string/output-path pairs made from @var{inputs}.
9684 Optionally, @var{env-vars} is a list of string pairs specifying the name
9685 and value of environment variables visible to the builder. The builder
9686 terminates by passing the result of @var{exp} to @code{exit}; thus, when
9687 @var{exp} returns @code{#f}, the build is considered to have failed.
9689 @var{exp} is built using @var{guile-for-build} (a derivation). When
9690 @var{guile-for-build} is omitted or is @code{#f}, the value of the
9691 @code{%guile-for-build} fluid is used instead.
9693 See the @code{derivation} procedure for the meaning of
9694 @var{references-graphs}, @var{allowed-references},
9695 @var{disallowed-references}, @var{local-build?}, and
9696 @var{substitutable?}.
9700 Here's an example of a single-output derivation that creates a directory
9701 containing one file:
9704 (let ((builder '(let ((out (assoc-ref %outputs "out")))
9705 (mkdir out) ; create /gnu/store/@dots{}-goo
9706 (call-with-output-file (string-append out "/test")
9708 (display '(hello guix) p))))))
9709 (build-expression->derivation store "goo" builder))
9711 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
9715 @node The Store Monad
9716 @section The Store Monad
9720 The procedures that operate on the store described in the previous
9721 sections all take an open connection to the build daemon as their first
9722 argument. Although the underlying model is functional, they either have
9723 side effects or depend on the current state of the store.
9725 The former is inconvenient: the connection to the build daemon has to be
9726 carried around in all those functions, making it impossible to compose
9727 functions that do not take that parameter with functions that do. The
9728 latter can be problematic: since store operations have side effects
9729 and/or depend on external state, they have to be properly sequenced.
9731 @cindex monadic values
9732 @cindex monadic functions
9733 This is where the @code{(guix monads)} module comes in. This module
9734 provides a framework for working with @dfn{monads}, and a particularly
9735 useful monad for our uses, the @dfn{store monad}. Monads are a
9736 construct that allows two things: associating ``context'' with values
9737 (in our case, the context is the store), and building sequences of
9738 computations (here computations include accesses to the store). Values
9739 in a monad---values that carry this additional context---are called
9740 @dfn{monadic values}; procedures that return such values are called
9741 @dfn{monadic procedures}.
9743 Consider this ``normal'' procedure:
9746 (define (sh-symlink store)
9747 ;; Return a derivation that symlinks the 'bash' executable.
9748 (let* ((drv (package-derivation store bash))
9749 (out (derivation->output-path drv))
9750 (sh (string-append out "/bin/bash")))
9751 (build-expression->derivation store "sh"
9752 `(symlink ,sh %output))))
9755 Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
9756 as a monadic function:
9759 (define (sh-symlink)
9760 ;; Same, but return a monadic value.
9761 (mlet %store-monad ((drv (package->derivation bash)))
9762 (gexp->derivation "sh"
9763 #~(symlink (string-append #$drv "/bin/bash")
9767 There are several things to note in the second version: the @code{store}
9768 parameter is now implicit and is ``threaded'' in the calls to the
9769 @code{package->derivation} and @code{gexp->derivation} monadic
9770 procedures, and the monadic value returned by @code{package->derivation}
9771 is @dfn{bound} using @code{mlet} instead of plain @code{let}.
9773 As it turns out, the call to @code{package->derivation} can even be
9774 omitted since it will take place implicitly, as we will see later
9775 (@pxref{G-Expressions}):
9778 (define (sh-symlink)
9779 (gexp->derivation "sh"
9780 #~(symlink (string-append #$bash "/bin/bash")
9785 @c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
9786 @c for the funny quote.
9787 Calling the monadic @code{sh-symlink} has no effect. As someone once
9788 said, ``you exit a monad like you exit a building on fire: by running''.
9789 So, to exit the monad and get the desired effect, one must use
9790 @code{run-with-store}:
9793 (run-with-store (open-connection) (sh-symlink))
9794 @result{} /gnu/store/...-sh-symlink
9797 Note that the @code{(guix monad-repl)} module extends the Guile REPL with
9798 new ``meta-commands'' to make it easier to deal with monadic procedures:
9799 @code{run-in-store}, and @code{enter-store-monad}. The former is used
9800 to ``run'' a single monadic value through the store:
9803 scheme@@(guile-user)> ,run-in-store (package->derivation hello)
9804 $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
9807 The latter enters a recursive REPL, where all the return values are
9808 automatically run through the store:
9811 scheme@@(guile-user)> ,enter-store-monad
9812 store-monad@@(guile-user) [1]> (package->derivation hello)
9813 $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
9814 store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
9815 $3 = "/gnu/store/@dots{}-foo"
9816 store-monad@@(guile-user) [1]> ,q
9817 scheme@@(guile-user)>
9821 Note that non-monadic values cannot be returned in the
9822 @code{store-monad} REPL.
9824 The main syntactic forms to deal with monads in general are provided by
9825 the @code{(guix monads)} module and are described below.
9827 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
9828 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
9832 @deffn {Scheme Syntax} return @var{val}
9833 Return a monadic value that encapsulates @var{val}.
9836 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
9837 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
9838 procedures @var{mproc}@dots{}@footnote{This operation is commonly
9839 referred to as ``bind'', but that name denotes an unrelated procedure in
9840 Guile. Thus we use this somewhat cryptic symbol inherited from the
9841 Haskell language.}. There can be one @var{mproc} or several of them, as
9846 (with-monad %state-monad
9848 (lambda (x) (return (+ 1 x)))
9849 (lambda (x) (return (* 2 x)))))
9853 @result{} some-state
9857 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
9859 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
9861 Bind the variables @var{var} to the monadic values @var{mval} in
9862 @var{body}, which is a sequence of expressions. As with the bind
9863 operator, this can be thought of as ``unpacking'' the raw, non-monadic
9864 value ``contained'' in @var{mval} and making @var{var} refer to that
9865 raw, non-monadic value within the scope of the @var{body}. The form
9866 (@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
9867 @var{val}, as per @code{let}. The binding operations occur in sequence
9868 from left to right. The last expression of @var{body} must be a monadic
9869 expression, and its result will become the result of the @code{mlet} or
9870 @code{mlet*} when run in the @var{monad}.
9872 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
9873 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
9876 @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
9877 Bind @var{mexp} and the following monadic expressions in sequence,
9878 returning the result of the last expression. Every expression in the
9879 sequence must be a monadic expression.
9881 This is akin to @code{mlet}, except that the return values of the
9882 monadic expressions are ignored. In that sense, it is analogous to
9883 @code{begin}, but applied to monadic expressions.
9886 @deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
9887 When @var{condition} is true, evaluate the sequence of monadic
9888 expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
9889 @var{condition} is false, return @code{*unspecified*} in the current
9890 monad. Every expression in the sequence must be a monadic expression.
9893 @deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ...
9894 When @var{condition} is false, evaluate the sequence of monadic
9895 expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
9896 @var{condition} is true, return @code{*unspecified*} in the current
9897 monad. Every expression in the sequence must be a monadic expression.
9901 The @code{(guix monads)} module provides the @dfn{state monad}, which
9902 allows an additional value---the state---to be @emph{threaded} through
9903 monadic procedure calls.
9905 @defvr {Scheme Variable} %state-monad
9906 The state monad. Procedures in the state monad can access and change
9907 the state that is threaded.
9909 Consider the example below. The @code{square} procedure returns a value
9910 in the state monad. It returns the square of its argument, but also
9911 increments the current state value:
9915 (mlet %state-monad ((count (current-state)))
9916 (mbegin %state-monad
9917 (set-current-state (+ 1 count))
9920 (run-with-state (sequence %state-monad (map square (iota 3))) 0)
9925 When ``run'' through @code{%state-monad}, we obtain that additional state
9926 value, which is the number of @code{square} calls.
9929 @deffn {Monadic Procedure} current-state
9930 Return the current state as a monadic value.
9933 @deffn {Monadic Procedure} set-current-state @var{value}
9934 Set the current state to @var{value} and return the previous state as a
9938 @deffn {Monadic Procedure} state-push @var{value}
9939 Push @var{value} to the current state, which is assumed to be a list,
9940 and return the previous state as a monadic value.
9943 @deffn {Monadic Procedure} state-pop
9944 Pop a value from the current state and return it as a monadic value.
9945 The state is assumed to be a list.
9948 @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
9949 Run monadic value @var{mval} starting with @var{state} as the initial
9950 state. Return two values: the resulting value, and the resulting state.
9953 The main interface to the store monad, provided by the @code{(guix
9954 store)} module, is as follows.
9956 @defvr {Scheme Variable} %store-monad
9957 The store monad---an alias for @code{%state-monad}.
9959 Values in the store monad encapsulate accesses to the store. When its
9960 effect is needed, a value of the store monad must be ``evaluated'' by
9961 passing it to the @code{run-with-store} procedure (see below).
9964 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
9965 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
9966 open store connection.
9969 @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
9970 Return as a monadic value the absolute file name in the store of the file
9971 containing @var{text}, a string. @var{references} is a list of store items that the
9972 resulting text file refers to; it defaults to the empty list.
9975 @deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}]
9976 Return as a monadic value the absolute file name in the store of the file
9977 containing @var{data}, a bytevector. @var{references} is a list of store
9978 items that the resulting binary file refers to; it defaults to the empty list.
9981 @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
9982 [#:recursive? #t] [#:select? (const #t)]
9983 Return the name of @var{file} once interned in the store. Use
9984 @var{name} as its store name, or the basename of @var{file} if
9985 @var{name} is omitted.
9987 When @var{recursive?} is true, the contents of @var{file} are added
9988 recursively; if @var{file} designates a flat file and @var{recursive?}
9989 is true, its contents are added, and its permission bits are kept.
9991 When @var{recursive?} is true, call @code{(@var{select?} @var{file}
9992 @var{stat})} for each directory entry, where @var{file} is the entry's
9993 absolute file name and @var{stat} is the result of @code{lstat}; exclude
9994 entries for which @var{select?} does not return true.
9996 The example below adds a file to the store, under two different names:
9999 (run-with-store (open-connection)
10000 (mlet %store-monad ((a (interned-file "README"))
10001 (b (interned-file "README" "LEGU-MIN")))
10002 (return (list a b))))
10004 @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
10009 The @code{(guix packages)} module exports the following package-related
10010 monadic procedures:
10012 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
10013 [#:system (%current-system)] [#:target #f] @
10015 Return as a monadic
10016 value in the absolute file name of @var{file} within the @var{output}
10017 directory of @var{package}. When @var{file} is omitted, return the name
10018 of the @var{output} directory of @var{package}. When @var{target} is
10019 true, use it as a cross-compilation target triplet.
10021 Note that this procedure does @emph{not} build @var{package}. Thus, the
10022 result might or might not designate an existing file. We recommend not
10023 using this procedure unless you know what you are doing.
10026 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
10027 @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
10028 @var{target} [@var{system}]
10029 Monadic version of @code{package-derivation} and
10030 @code{package-cross-derivation} (@pxref{Defining Packages}).
10034 @node G-Expressions
10035 @section G-Expressions
10037 @cindex G-expression
10038 @cindex build code quoting
10039 So we have ``derivations'', which represent a sequence of build actions
10040 to be performed to produce an item in the store (@pxref{Derivations}).
10041 These build actions are performed when asking the daemon to actually
10042 build the derivations; they are run by the daemon in a container
10043 (@pxref{Invoking guix-daemon}).
10045 @cindex code staging
10046 @cindex staging, of code
10047 @cindex strata of code
10048 It should come as no surprise that we like to write these build actions
10049 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
10050 code@footnote{The term @dfn{stratum} in this context was coined by
10051 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
10052 Kiselyov, who has written insightful
10053 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
10054 on this topic}, refers to this kind of code generation as
10055 @dfn{staging}.}: the ``host code''---code that defines packages, talks
10056 to the daemon, etc.---and the ``build code''---code that actually
10057 performs build actions, such as making directories, invoking
10058 @command{make}, and so on (@pxref{Build Phases}).
10060 To describe a derivation and its build actions, one typically needs to
10061 embed build code inside host code. It boils down to manipulating build
10062 code as data, and the homoiconicity of Scheme---code has a direct
10063 representation as data---comes in handy for that. But we need more than
10064 the normal @code{quasiquote} mechanism in Scheme to construct build
10067 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
10068 S-expressions adapted to build expressions. G-expressions, or
10069 @dfn{gexps}, consist essentially of three syntactic forms: @code{gexp},
10070 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
10071 @code{#$}, and @code{#$@@}), which are comparable to
10072 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing},
10073 respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
10074 GNU Guile Reference Manual}). However, there are major differences:
10078 Gexps are meant to be written to a file and run or manipulated by other
10082 When a high-level object such as a package or derivation is unquoted
10083 inside a gexp, the result is as if its output file name had been
10087 Gexps carry information about the packages or derivations they refer to,
10088 and these dependencies are automatically added as inputs to the build
10089 processes that use them.
10092 @cindex lowering, of high-level objects in gexps
10093 This mechanism is not limited to package and derivation
10094 objects: @dfn{compilers} able to ``lower'' other high-level objects to
10095 derivations or files in the store can be defined,
10096 such that these objects can also be inserted
10097 into gexps. For example, a useful type of high-level objects that can be
10098 inserted in a gexp is ``file-like objects'', which make it easy to
10099 add files to the store and to refer to them in
10100 derivations and such (see @code{local-file} and @code{plain-file}
10103 To illustrate the idea, here is an example of a gexp:
10110 (symlink (string-append #$coreutils "/bin/ls")
10114 This gexp can be passed to @code{gexp->derivation}; we obtain a
10115 derivation that builds a directory containing exactly one symlink to
10116 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
10119 (gexp->derivation "the-thing" build-exp)
10122 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
10123 substituted to the reference to the @var{coreutils} package in the
10124 actual build code, and @var{coreutils} is automatically made an input to
10125 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
10126 output)}) is replaced by a string containing the directory name of the
10127 output of the derivation.
10129 @cindex cross compilation
10130 In a cross-compilation context, it is useful to distinguish between
10131 references to the @emph{native} build of a package---that can run on the
10132 host---versus references to cross builds of a package. To that end, the
10133 @code{#+} plays the same role as @code{#$}, but is a reference to a
10134 native package build:
10137 (gexp->derivation "vi"
10140 (mkdir (string-append #$output "/bin"))
10141 (system* (string-append #+coreutils "/bin/ln")
10143 (string-append #$emacs "/bin/emacs")
10144 (string-append #$output "/bin/vi")))
10145 #:target "aarch64-linux-gnu")
10149 In the example above, the native build of @var{coreutils} is used, so
10150 that @command{ln} can actually run on the host; but then the
10151 cross-compiled build of @var{emacs} is referenced.
10153 @cindex imported modules, for gexps
10154 @findex with-imported-modules
10155 Another gexp feature is @dfn{imported modules}: sometimes you want to be
10156 able to use certain Guile modules from the ``host environment'' in the
10157 gexp, so those modules should be imported in the ``build environment''.
10158 The @code{with-imported-modules} form allows you to express that:
10161 (let ((build (with-imported-modules '((guix build utils))
10163 (use-modules (guix build utils))
10164 (mkdir-p (string-append #$output "/bin"))))))
10165 (gexp->derivation "empty-dir"
10168 (display "success!\n")
10173 In this example, the @code{(guix build utils)} module is automatically
10174 pulled into the isolated build environment of our gexp, such that
10175 @code{(use-modules (guix build utils))} works as expected.
10177 @cindex module closure
10178 @findex source-module-closure
10179 Usually you want the @emph{closure} of the module to be imported---i.e.,
10180 the module itself and all the modules it depends on---rather than just
10181 the module; failing to do that, attempts to use the module will fail
10182 because of missing dependent modules. The @code{source-module-closure}
10183 procedure computes the closure of a module by looking at its source file
10184 headers, which comes in handy in this case:
10187 (use-modules (guix modules)) ;for 'source-module-closure'
10189 (with-imported-modules (source-module-closure
10190 '((guix build utils)
10191 (gnu build image)))
10192 (gexp->derivation "something-with-vms"
10194 (use-modules (guix build utils)
10199 @cindex extensions, for gexps
10200 @findex with-extensions
10201 In the same vein, sometimes you want to import not just pure-Scheme
10202 modules, but also ``extensions'' such as Guile bindings to C libraries
10203 or other ``full-blown'' packages. Say you need the @code{guile-json}
10204 package available on the build side, here's how you would do it:
10207 (use-modules (gnu packages guile)) ;for 'guile-json'
10209 (with-extensions (list guile-json)
10210 (gexp->derivation "something-with-json"
10212 (use-modules (json))
10216 The syntactic form to construct gexps is summarized below.
10218 @deffn {Scheme Syntax} #~@var{exp}
10219 @deffnx {Scheme Syntax} (gexp @var{exp})
10220 Return a G-expression containing @var{exp}. @var{exp} may contain one
10221 or more of the following forms:
10225 @itemx (ungexp @var{obj})
10226 Introduce a reference to @var{obj}. @var{obj} may have one of the
10227 supported types, for example a package or a
10228 derivation, in which case the @code{ungexp} form is replaced by its
10229 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
10231 If @var{obj} is a list, it is traversed and references to supported
10232 objects are substituted similarly.
10234 If @var{obj} is another gexp, its contents are inserted and its
10235 dependencies are added to those of the containing gexp.
10237 If @var{obj} is another kind of object, it is inserted as is.
10239 @item #$@var{obj}:@var{output}
10240 @itemx (ungexp @var{obj} @var{output})
10241 This is like the form above, but referring explicitly to the
10242 @var{output} of @var{obj}---this is useful when @var{obj} produces
10243 multiple outputs (@pxref{Packages with Multiple Outputs}).
10246 @itemx #+@var{obj}:output
10247 @itemx (ungexp-native @var{obj})
10248 @itemx (ungexp-native @var{obj} @var{output})
10249 Same as @code{ungexp}, but produces a reference to the @emph{native}
10250 build of @var{obj} when used in a cross compilation context.
10252 @item #$output[:@var{output}]
10253 @itemx (ungexp output [@var{output}])
10254 Insert a reference to derivation output @var{output}, or to the main
10255 output when @var{output} is omitted.
10257 This only makes sense for gexps passed to @code{gexp->derivation}.
10259 @item #$@@@var{lst}
10260 @itemx (ungexp-splicing @var{lst})
10261 Like the above, but splices the contents of @var{lst} inside the
10264 @item #+@@@var{lst}
10265 @itemx (ungexp-native-splicing @var{lst})
10266 Like the above, but refers to native builds of the objects listed in
10271 G-expressions created by @code{gexp} or @code{#~} are run-time objects
10272 of the @code{gexp?} type (see below).
10275 @deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{}
10276 Mark the gexps defined in @var{body}@dots{} as requiring @var{modules}
10277 in their execution environment.
10279 Each item in @var{modules} can be the name of a module, such as
10280 @code{(guix build utils)}, or it can be a module name, followed by an
10281 arrow, followed by a file-like object:
10284 `((guix build utils)
10286 ((guix config) => ,(scheme-file "config.scm"
10287 #~(define-module @dots{}))))
10291 In the example above, the first two modules are taken from the search
10292 path, and the last one is created from the given file-like object.
10294 This form has @emph{lexical} scope: it has an effect on the gexps
10295 directly defined in @var{body}@dots{}, but not on those defined, say, in
10296 procedures called from @var{body}@dots{}.
10299 @deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
10300 Mark the gexps defined in @var{body}@dots{} as requiring
10301 @var{extensions} in their build and execution environment.
10302 @var{extensions} is typically a list of package objects such as those
10303 defined in the @code{(gnu packages guile)} module.
10305 Concretely, the packages listed in @var{extensions} are added to the
10306 load path while compiling imported modules in @var{body}@dots{}; they
10307 are also added to the load path of the gexp returned by
10311 @deffn {Scheme Procedure} gexp? @var{obj}
10312 Return @code{#t} if @var{obj} is a G-expression.
10315 G-expressions are meant to be written to disk, either as code building
10316 some derivation, or as plain files in the store. The monadic procedures
10317 below allow you to do that (@pxref{The Store Monad}, for more
10318 information about monads).
10320 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
10321 [#:system (%current-system)] [#:target #f] [#:graft? #t] @
10322 [#:hash #f] [#:hash-algo #f] @
10323 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
10324 [#:module-path @code{%load-path}] @
10325 [#:effective-version "2.2"] @
10326 [#:references-graphs #f] [#:allowed-references #f] @
10327 [#:disallowed-references #f] @
10328 [#:leaked-env-vars #f] @
10329 [#:script-name (string-append @var{name} "-builder")] @
10330 [#:deprecation-warnings #f] @
10331 [#:local-build? #f] [#:substitutable? #t] @
10332 [#:properties '()] [#:guile-for-build #f]
10333 Return a derivation @var{name} that runs @var{exp} (a gexp) with
10334 @var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
10335 stored in a file called @var{script-name}. When @var{target} is true,
10336 it is used as the cross-compilation target triplet for packages referred
10339 @var{modules} is deprecated in favor of @code{with-imported-modules}.
10341 make @var{modules} available in the evaluation context of @var{exp};
10342 @var{modules} is a list of names of Guile modules searched in
10343 @var{module-path} to be copied in the store, compiled, and made available in
10344 the load path during the execution of @var{exp}---e.g., @code{((guix
10345 build utils) (guix build gnu-build-system))}.
10347 @var{effective-version} determines the string to use when adding extensions of
10348 @var{exp} (see @code{with-extensions}) to the search path---e.g., @code{"2.2"}.
10350 @var{graft?} determines whether packages referred to by @var{exp} should be grafted when
10353 When @var{references-graphs} is true, it must be a list of tuples of one of the
10357 (@var{file-name} @var{package})
10358 (@var{file-name} @var{package} @var{output})
10359 (@var{file-name} @var{derivation})
10360 (@var{file-name} @var{derivation} @var{output})
10361 (@var{file-name} @var{store-item})
10364 The right-hand-side of each element of @var{references-graphs} is automatically made
10365 an input of the build process of @var{exp}. In the build environment, each
10366 @var{file-name} contains the reference graph of the corresponding item, in a simple
10369 @var{allowed-references} must be either @code{#f} or a list of output names and packages.
10370 In the latter case, the list denotes store items that the result is allowed to
10371 refer to. Any reference to another store item will lead to a build error.
10372 Similarly for @var{disallowed-references}, which can list items that must not be
10373 referenced by the outputs.
10375 @var{deprecation-warnings} determines whether to show deprecation warnings while
10376 compiling modules. It can be @code{#f}, @code{#t}, or @code{'detailed}.
10378 The other arguments are as for @code{derivation} (@pxref{Derivations}).
10381 @cindex file-like objects
10382 The @code{local-file}, @code{plain-file}, @code{computed-file},
10383 @code{program-file}, and @code{scheme-file} procedures below return
10384 @dfn{file-like objects}. That is, when unquoted in a G-expression,
10385 these objects lead to a file in the store. Consider this G-expression:
10388 #~(system* #$(file-append glibc "/sbin/nscd") "-f"
10389 #$(local-file "/tmp/my-nscd.conf"))
10392 The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
10393 to the store. Once expanded, for instance @i{via}
10394 @code{gexp->derivation}, the G-expression refers to that copy under
10395 @file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
10396 does not have any effect on what the G-expression does.
10397 @code{plain-file} can be used similarly; it differs in that the file
10398 content is directly passed as a string.
10400 @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
10401 [#:recursive? #f] [#:select? (const #t)]
10402 Return an object representing local file @var{file} to add to the store;
10403 this object can be used in a gexp. If @var{file} is a literal string
10404 denoting a relative file name, it is looked up relative to the source
10405 file where it appears; if @var{file} is not a literal string, it is
10406 looked up relative to the current working directory at run time.
10407 @var{file} will be added to the store under @var{name}--by default the
10408 base name of @var{file}.
10410 When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
10411 designates a flat file and @var{recursive?} is true, its contents are added, and its
10412 permission bits are kept.
10414 When @var{recursive?} is true, call @code{(@var{select?} @var{file}
10415 @var{stat})} for each directory entry, where @var{file} is the entry's
10416 absolute file name and @var{stat} is the result of @code{lstat}; exclude
10417 entries for which @var{select?} does not return true.
10419 This is the declarative counterpart of the @code{interned-file} monadic
10420 procedure (@pxref{The Store Monad, @code{interned-file}}).
10423 @deffn {Scheme Procedure} plain-file @var{name} @var{content}
10424 Return an object representing a text file called @var{name} with the given
10425 @var{content} (a string or a bytevector) to be added to the store.
10427 This is the declarative counterpart of @code{text-file}.
10430 @deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
10431 [#:local-build? #t]
10433 Return an object representing the store item @var{name}, a file or
10434 directory computed by @var{gexp}. When @var{local-build?} is true (the
10435 default), the derivation is built locally. @var{options} is a list of
10436 additional arguments to pass to @code{gexp->derivation}.
10438 This is the declarative counterpart of @code{gexp->derivation}.
10441 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
10442 [#:guile (default-guile)] [#:module-path %load-path] @
10443 [#:system (%current-system)] [#:target #f]
10444 Return an executable script @var{name} that runs @var{exp} using
10445 @var{guile}, with @var{exp}'s imported modules in its search path.
10446 Look up @var{exp}'s modules in @var{module-path}.
10448 The example below builds a script that simply invokes the @command{ls}
10452 (use-modules (guix gexp) (gnu packages base))
10454 (gexp->script "list-files"
10455 #~(execl #$(file-append coreutils "/bin/ls")
10459 When ``running'' it through the store (@pxref{The Store Monad,
10460 @code{run-with-store}}), we obtain a derivation that produces an
10461 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
10464 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
10466 (execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
10470 @deffn {Scheme Procedure} program-file @var{name} @var{exp} @
10471 [#:guile #f] [#:module-path %load-path]
10472 Return an object representing the executable store item @var{name} that
10473 runs @var{gexp}. @var{guile} is the Guile package used to execute that
10474 script. Imported modules of @var{gexp} are looked up in @var{module-path}.
10476 This is the declarative counterpart of @code{gexp->script}.
10479 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
10480 [#:set-load-path? #t] [#:module-path %load-path] @
10482 [#:guile (default-guile)]
10483 Return a derivation that builds a file @var{name} containing @var{exp}.
10484 When @var{splice?} is true, @var{exp} is considered to be a list of
10485 expressions that will be spliced in the resulting file.
10487 When @var{set-load-path?} is true, emit code in the resulting file to
10488 set @code{%load-path} and @code{%load-compiled-path} to honor
10489 @var{exp}'s imported modules. Look up @var{exp}'s modules in
10492 The resulting file holds references to all the dependencies of @var{exp}
10493 or a subset thereof.
10496 @deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @
10497 [#:splice? #f] [#:set-load-path? #t]
10498 Return an object representing the Scheme file @var{name} that contains
10501 This is the declarative counterpart of @code{gexp->file}.
10504 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
10505 Return as a monadic value a derivation that builds a text file
10506 containing all of @var{text}. @var{text} may list, in addition to
10507 strings, objects of any type that can be used in a gexp: packages,
10508 derivations, local file objects, etc. The resulting store file holds
10509 references to all these.
10511 This variant should be preferred over @code{text-file} anytime the file
10512 to create will reference items from the store. This is typically the
10513 case when building a configuration file that embeds store file names,
10517 (define (profile.sh)
10518 ;; Return the name of a shell script in the store that
10519 ;; initializes the 'PATH' environment variable.
10520 (text-file* "profile.sh"
10521 "export PATH=" coreutils "/bin:"
10522 grep "/bin:" sed "/bin\n"))
10525 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
10526 will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
10527 preventing them from being garbage-collected during its lifetime.
10530 @deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
10531 Return an object representing store file @var{name} containing
10532 @var{text}. @var{text} is a sequence of strings and file-like objects,
10536 (mixed-text-file "profile"
10537 "export PATH=" coreutils "/bin:" grep "/bin")
10540 This is the declarative counterpart of @code{text-file*}.
10543 @deffn {Scheme Procedure} file-union @var{name} @var{files}
10544 Return a @code{<computed-file>} that builds a directory containing all of @var{files}.
10545 Each item in @var{files} must be a two-element list where the first element is the
10546 file name to use in the new directory, and the second element is a gexp
10547 denoting the target file. Here's an example:
10551 `(("hosts" ,(plain-file "hosts"
10552 "127.0.0.1 localhost"))
10553 ("bashrc" ,(plain-file "bashrc"
10554 "alias ls='ls --color=auto'"))))
10557 This yields an @code{etc} directory containing these two files.
10560 @deffn {Scheme Procedure} directory-union @var{name} @var{things}
10561 Return a directory that is the union of @var{things}, where @var{things} is a list of
10562 file-like objects denoting directories. For example:
10565 (directory-union "guile+emacs" (list guile emacs))
10568 yields a directory that is the union of the @code{guile} and @code{emacs} packages.
10571 @deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
10572 Return a file-like object that expands to the concatenation of @var{obj}
10573 and @var{suffix}, where @var{obj} is a lowerable object and each
10574 @var{suffix} is a string.
10576 As an example, consider this gexp:
10579 (gexp->script "run-uname"
10580 #~(system* #$(file-append coreutils
10584 The same effect could be achieved with:
10587 (gexp->script "run-uname"
10588 #~(system* (string-append #$coreutils
10592 There is one difference though: in the @code{file-append} case, the
10593 resulting script contains the absolute file name as a string, whereas in
10594 the second case, the resulting script contains a @code{(string-append
10595 @dots{})} expression to construct the file name @emph{at run time}.
10598 @deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{}
10599 @deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{}
10600 Bind @var{system} to the currently targeted system---e.g.,
10601 @code{"x86_64-linux"}---within @var{body}.
10603 In the second case, additionally bind @var{target} to the current
10604 cross-compilation target---a GNU triplet such as
10605 @code{"arm-linux-gnueabihf"}---or @code{#f} if we are not
10608 @code{let-system} is useful in the occasional case where the object
10609 spliced into the gexp depends on the target system, as in this example:
10613 #+(let-system system
10614 (cond ((string-prefix? "armhf-" system)
10615 (file-append qemu "/bin/qemu-system-arm"))
10616 ((string-prefix? "x86_64-" system)
10617 (file-append qemu "/bin/qemu-system-x86_64"))
10619 (error "dunno!"))))
10620 "-net" "user" #$image)
10624 @deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
10625 This macro is similar to the @code{parameterize} form for
10626 dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU
10627 Guile Reference Manual}). The key difference is that it takes effect
10628 when the file-like object returned by @var{exp} is lowered to a
10629 derivation or store item.
10631 A typical use of @code{with-parameters} is to force the system in effect
10632 for a given object:
10635 (with-parameters ((%current-system "i686-linux"))
10639 The example above returns an object that corresponds to the i686 build
10640 of Coreutils, regardless of the current value of @code{%current-system}.
10644 Of course, in addition to gexps embedded in ``host'' code, there are
10645 also modules containing build tools. To make it clear that they are
10646 meant to be used in the build stratum, these modules are kept in the
10647 @code{(guix build @dots{})} name space.
10649 @cindex lowering, of high-level objects in gexps
10650 Internally, high-level objects are @dfn{lowered}, using their compiler,
10651 to either derivations or store items. For instance, lowering a package
10652 yields a derivation, and lowering a @code{plain-file} yields a store
10653 item. This is achieved using the @code{lower-object} monadic procedure.
10655 @deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
10657 Return as a value in @code{%store-monad} the derivation or store item
10658 corresponding to @var{obj} for @var{system}, cross-compiling for
10659 @var{target} if @var{target} is true. @var{obj} must be an object that
10660 has an associated gexp compiler, such as a @code{<package>}.
10663 @deffn {Procedure} gexp->approximate-sexp @var{gexp}
10664 Sometimes, it may be useful to convert a G-exp into a S-exp. For
10665 example, some linters (@pxref{Invoking guix lint}) peek into the build
10666 phases of a package to detect potential problems. This conversion can
10667 be achieved with this procedure. However, some information can be lost
10668 in the process. More specifically, lowerable objects will be silently
10669 replaced with some arbitrary object -- currently the list
10670 @code{(*approximate*)}, but this may change.
10673 @node Invoking guix repl
10674 @section Invoking @command{guix repl}
10676 @cindex REPL, read-eval-print loop, script
10677 The @command{guix repl} command makes it easier to program Guix in Guile
10678 by launching a Guile @dfn{read-eval-print loop} (REPL) for interactive
10679 programming (@pxref{Using Guile Interactively,,, guile,
10680 GNU Guile Reference Manual}), or by running Guile scripts
10681 (@pxref{Running Guile Scripts,,, guile,
10682 GNU Guile Reference Manual}).
10683 Compared to just launching the @command{guile}
10684 command, @command{guix repl} guarantees that all the Guix modules and all its
10685 dependencies are available in the search path.
10687 The general syntax is:
10690 guix repl @var{options} [@var{file} @var{args}]
10693 When a @var{file} argument is provided, @var{file} is
10694 executed as a Guile scripts:
10697 guix repl my-script.scm
10700 To pass arguments to the script, use @code{--} to prevent them from
10701 being interpreted as arguments to @command{guix repl} itself:
10704 guix repl -- my-script.scm --input=foo.txt
10707 To make a script executable directly from the shell, using the guix
10708 executable that is on the user's search path, add the following two
10709 lines at the top of the script:
10712 @code{#!/usr/bin/env -S guix repl --}
10716 Without a file name argument, a Guile REPL is started:
10720 scheme@@(guile-user)> ,use (gnu packages base)
10721 scheme@@(guile-user)> coreutils
10722 $1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
10726 In addition, @command{guix repl} implements a simple machine-readable REPL
10727 protocol for use by @code{(guix inferior)}, a facility to interact with
10728 @dfn{inferiors}, separate processes running a potentially different revision
10731 The available options are as follows:
10734 @item --type=@var{type}
10735 @itemx -t @var{type}
10736 Start a REPL of the given @var{TYPE}, which can be one of the following:
10740 This is default, and it spawns a standard full-featured Guile REPL.
10742 Spawn a REPL that uses the machine-readable protocol. This is the protocol
10743 that the @code{(guix inferior)} module speaks.
10746 @item --listen=@var{endpoint}
10747 By default, @command{guix repl} reads from standard input and writes to
10748 standard output. When this option is passed, it will instead listen for
10749 connections on @var{endpoint}. Here are examples of valid options:
10752 @item --listen=tcp:37146
10753 Accept connections on localhost on port 37146.
10755 @item --listen=unix:/tmp/socket
10756 Accept connections on the Unix-domain socket @file{/tmp/socket}.
10759 @item --load-path=@var{directory}
10760 @itemx -L @var{directory}
10761 Add @var{directory} to the front of the package module search path
10762 (@pxref{Package Modules}).
10764 This allows users to define their own packages and make them visible to
10765 the script or REPL.
10768 Inhibit loading of the @file{~/.guile} file. By default, that
10769 configuration file is loaded when spawning a @code{guile} REPL.
10772 @c *********************************************************************
10776 This section describes Guix command-line utilities. Some of them are
10777 primarily targeted at developers and users who write new package
10778 definitions, while others are more generally useful. They complement
10779 the Scheme programming interface of Guix in a convenient way.
10782 * Invoking guix build:: Building packages from the command line.
10783 * Invoking guix edit:: Editing package definitions.
10784 * Invoking guix download:: Downloading a file and printing its hash.
10785 * Invoking guix hash:: Computing the cryptographic hash of a file.
10786 * Invoking guix import:: Importing package definitions.
10787 * Invoking guix refresh:: Updating package definitions.
10788 * Invoking guix style:: Styling package definitions.
10789 * Invoking guix lint:: Finding errors in package definitions.
10790 * Invoking guix size:: Profiling disk usage.
10791 * Invoking guix graph:: Visualizing the graph of packages.
10792 * Invoking guix publish:: Sharing substitutes.
10793 * Invoking guix challenge:: Challenging substitute servers.
10794 * Invoking guix copy:: Copying to and from a remote store.
10795 * Invoking guix container:: Process isolation.
10796 * Invoking guix weather:: Assessing substitute availability.
10797 * Invoking guix processes:: Listing client processes.
10800 @node Invoking guix build
10801 @section Invoking @command{guix build}
10803 @cindex package building
10804 @cindex @command{guix build}
10805 The @command{guix build} command builds packages or derivations and
10806 their dependencies, and prints the resulting store paths. Note that it
10807 does not modify the user's profile---this is the job of the
10808 @command{guix package} command (@pxref{Invoking guix package}). Thus,
10809 it is mainly useful for distribution developers.
10811 The general syntax is:
10814 guix build @var{options} @var{package-or-derivation}@dots{}
10817 As an example, the following command builds the latest versions of Emacs
10818 and of Guile, displays their build logs, and finally displays the
10819 resulting directories:
10822 guix build emacs guile
10825 Similarly, the following command builds all the available packages:
10828 guix build --quiet --keep-going \
10829 $(guix package -A | awk '@{ print $1 "@@" $2 @}')
10832 @var{package-or-derivation} may be either the name of a package found in
10833 the software distribution such as @code{coreutils} or
10834 @code{coreutils@@8.20}, or a derivation such as
10835 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
10836 package with the corresponding name (and optionally version) is searched
10837 for among the GNU distribution modules (@pxref{Package Modules}).
10839 Alternatively, the @option{--expression} option may be used to specify a
10840 Scheme expression that evaluates to a package; this is useful when
10841 disambiguating among several same-named packages or package variants is
10844 There may be zero or more @var{options}. The available options are
10845 described in the subsections below.
10848 * Common Build Options:: Build options for most commands.
10849 * Package Transformation Options:: Creating variants of packages.
10850 * Additional Build Options:: Options specific to 'guix build'.
10851 * Debugging Build Failures:: Real life packaging experience.
10854 @node Common Build Options
10855 @subsection Common Build Options
10857 A number of options that control the build process are common to
10858 @command{guix build} and other commands that can spawn builds, such as
10859 @command{guix package} or @command{guix archive}. These are the
10864 @item --load-path=@var{directory}
10865 @itemx -L @var{directory}
10866 Add @var{directory} to the front of the package module search path
10867 (@pxref{Package Modules}).
10869 This allows users to define their own packages and make them visible to
10870 the command-line tools.
10872 @item --keep-failed
10874 Keep the build tree of failed builds. Thus, if a build fails, its build
10875 tree is kept under @file{/tmp}, in a directory whose name is shown at
10876 the end of the build log. This is useful when debugging build issues.
10877 @xref{Debugging Build Failures}, for tips and tricks on how to debug
10880 This option implies @option{--no-offload}, and it has no effect when
10881 connecting to a remote daemon with a @code{guix://} URI (@pxref{The
10882 Store, the @env{GUIX_DAEMON_SOCKET} variable}).
10886 Keep going when some of the derivations fail to build; return only once
10887 all the builds have either completed or failed.
10889 The default behavior is to stop as soon as one of the specified
10890 derivations has failed.
10894 Do not build the derivations.
10896 @anchor{fallback-option}
10898 When substituting a pre-built binary fails, fall back to building
10899 packages locally (@pxref{Substitution Failure}).
10901 @item --substitute-urls=@var{urls}
10902 @anchor{client-substitute-urls}
10903 Consider @var{urls} the whitespace-separated list of substitute source
10904 URLs, overriding the default list of URLs of @command{guix-daemon}
10905 (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
10907 This means that substitutes may be downloaded from @var{urls}, provided
10908 they are signed by a key authorized by the system administrator
10909 (@pxref{Substitutes}).
10911 When @var{urls} is the empty string, substitutes are effectively
10914 @item --no-substitutes
10915 Do not use substitutes for build products. That is, always build things
10916 locally instead of allowing downloads of pre-built binaries
10917 (@pxref{Substitutes}).
10920 Do not ``graft'' packages. In practice, this means that package updates
10921 available as grafts are not applied. @xref{Security Updates}, for more
10922 information on grafts.
10924 @item --rounds=@var{n}
10925 Build each derivation @var{n} times in a row, and raise an error if
10926 consecutive build results are not bit-for-bit identical.
10928 This is a useful way to detect non-deterministic builds processes.
10929 Non-deterministic build processes are a problem because they make it
10930 practically impossible for users to @emph{verify} whether third-party
10931 binaries are genuine. @xref{Invoking guix challenge}, for more.
10933 When used in conjunction with @option{--keep-failed}, the differing
10934 output is kept in the store, under @file{/gnu/store/@dots{}-check}.
10935 This makes it easy to look for differences between the two results.
10938 Do not use offload builds to other machines (@pxref{Daemon Offload
10939 Setup}). That is, always build things locally instead of offloading
10940 builds to remote machines.
10942 @item --max-silent-time=@var{seconds}
10943 When the build or substitution process remains silent for more than
10944 @var{seconds}, terminate it and report a build failure.
10946 By default, the daemon's setting is honored (@pxref{Invoking
10947 guix-daemon, @option{--max-silent-time}}).
10949 @item --timeout=@var{seconds}
10950 Likewise, when the build or substitution process lasts for more than
10951 @var{seconds}, terminate it and report a build failure.
10953 By default, the daemon's setting is honored (@pxref{Invoking
10954 guix-daemon, @option{--timeout}}).
10956 @c Note: This option is actually not part of %standard-build-options but
10957 @c most programs honor it.
10958 @cindex verbosity, of the command-line tools
10959 @cindex build logs, verbosity
10960 @item -v @var{level}
10961 @itemx --verbosity=@var{level}
10962 Use the given verbosity @var{level}, an integer. Choosing 0 means that
10963 no output is produced, 1 is for quiet output; 2 is similar to 1 but it
10964 additionally displays download URLs; 3 shows all the build log output on
10967 @item --cores=@var{n}
10969 Allow the use of up to @var{n} CPU cores for the build. The special
10970 value @code{0} means to use as many CPU cores as available.
10972 @item --max-jobs=@var{n}
10974 Allow at most @var{n} build jobs in parallel. @xref{Invoking
10975 guix-daemon, @option{--max-jobs}}, for details about this option and the
10976 equivalent @command{guix-daemon} option.
10978 @item --debug=@var{level}
10979 Produce debugging output coming from the build daemon. @var{level} must be an
10980 integer between 0 and 5; higher means more verbose output. Setting a level of
10981 4 or more may be helpful when debugging setup issues with the build daemon.
10985 Behind the scenes, @command{guix build} is essentially an interface to
10986 the @code{package-derivation} procedure of the @code{(guix packages)}
10987 module, and to the @code{build-derivations} procedure of the @code{(guix
10988 derivations)} module.
10990 In addition to options explicitly passed on the command line,
10991 @command{guix build} and other @command{guix} commands that support
10992 building honor the @env{GUIX_BUILD_OPTIONS} environment variable.
10994 @defvr {Environment Variable} GUIX_BUILD_OPTIONS
10995 Users can define this variable to a list of command line options that
10996 will automatically be used by @command{guix build} and other
10997 @command{guix} commands that can perform builds, as in the example
11001 $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
11004 These options are parsed independently, and the result is appended to
11005 the parsed command-line options.
11009 @node Package Transformation Options
11010 @subsection Package Transformation Options
11012 @cindex package variants
11013 Another set of command-line options supported by @command{guix build}
11014 and also @command{guix package} are @dfn{package transformation
11015 options}. These are options that make it possible to define @dfn{package
11016 variants}---for instance, packages built from different source code.
11017 This is a convenient way to create customized packages on the fly
11018 without having to type in the definitions of package variants
11019 (@pxref{Defining Packages}).
11021 Package transformation options are preserved across upgrades:
11022 @command{guix upgrade} attempts to apply transformation options
11023 initially used when creating the profile to the upgraded packages.
11025 The available options are listed below. Most commands support them and
11026 also support a @option{--help-transform} option that lists all the
11027 available options and a synopsis (these options are not shown in the
11028 @option{--help} output for brevity).
11032 @cindex performance, tuning code
11033 @cindex optimization, of package code
11034 @cindex tuning, of package code
11035 @cindex SIMD support
11036 @cindex tunable packages
11037 @cindex package multi-versioning
11038 @item --tune[=@var{cpu}]
11039 Use versions of the packages marked as ``tunable'' optimized for
11040 @var{cpu}. When @var{cpu} is @code{native}, or when it is omitted, tune
11041 for the CPU on which the @command{guix} command is running.
11043 Valid @var{cpu} names are those recognized by the underlying compiler,
11044 by default the GNU Compiler Collection. On x86_64 processors, this
11045 includes CPU names such as @code{nehalem}, @code{haswell}, and
11046 @code{skylake} (@pxref{x86 Options, @code{-march},, gcc, Using the GNU
11047 Compiler Collection (GCC)}).
11049 As new generations of CPUs come out, they augment the standard
11050 instruction set architecture (ISA) with additional instructions, in
11051 particular instructions for single-instruction/multiple-data (SIMD)
11052 parallel processing. For example, while Core2 and Skylake CPUs both
11053 implement the x86_64 ISA, only the latter supports AVX2 SIMD
11056 The primary gain one can expect from @option{--tune} is for programs
11057 that can make use of those SIMD capabilities @emph{and} that do not
11058 already have a mechanism to select the right optimized code at run time.
11059 Packages that have the @code{tunable?} property set are considered
11060 @dfn{tunable packages} by the @option{--tune} option; a package
11061 definition with the property set looks like this:
11065 (name "hello-simd")
11068 ;; This package may benefit from SIMD extensions so
11069 ;; mark it as "tunable".
11070 (properties '((tunable? . #t))))
11073 Other packages are not considered tunable. This allows Guix to use
11074 generic binaries in the cases where tuning for a specific CPU is
11075 unlikely to provide any gain.
11077 Tuned packages are built with @code{-march=@var{CPU}}; under the hood,
11078 the @option{-march} option is passed to the actual wrapper by a compiler
11079 wrapper. Since the build machine may not be able to run code for the
11080 target CPU micro-architecture, the test suite is not run when building a
11083 To reduce rebuilds to the minimum, tuned packages are @emph{grafted}
11084 onto packages that depend on them (@pxref{Security Updates, grafts}).
11085 Thus, using @option{--no-grafts} cancels the effect of @option{--tune}.
11087 We call this technique @dfn{package multi-versioning}: several variants
11088 of tunable packages may be built, one for each CPU variant. It is the
11089 coarse-grain counterpart of @dfn{function multi-versioning} as
11090 implemented by the GNU tool chain (@pxref{Function Multiversioning,,,
11091 gcc, Using the GNU Compiler Collection (GCC)}).
11093 @item --with-source=@var{source}
11094 @itemx --with-source=@var{package}=@var{source}
11095 @itemx --with-source=@var{package}@@@var{version}=@var{source}
11096 Use @var{source} as the source of @var{package}, and @var{version} as
11097 its version number.
11098 @var{source} must be a file name or a URL, as for @command{guix
11099 download} (@pxref{Invoking guix download}).
11101 When @var{package} is omitted,
11102 it is taken to be the package name specified on the
11103 command line that matches the base of @var{source}---e.g.,
11104 if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
11105 package is @code{guile}.
11107 Likewise, when @var{version} is omitted, the version string is inferred from
11108 @var{source}; in the previous example, it is @code{2.0.10}.
11110 This option allows users to try out versions of packages other than the
11111 one provided by the distribution. The example below downloads
11112 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
11113 the @code{ed} package:
11116 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
11119 As a developer, @option{--with-source} makes it easy to test release
11123 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
11126 @dots{} or to build from a checkout in a pristine environment:
11129 $ git clone git://git.sv.gnu.org/guix.git
11130 $ guix build guix --with-source=guix@@1.0=./guix
11133 @item --with-input=@var{package}=@var{replacement}
11134 Replace dependency on @var{package} by a dependency on
11135 @var{replacement}. @var{package} must be a package name, and
11136 @var{replacement} must be a package specification such as @code{guile}
11137 or @code{guile@@1.8}.
11139 For instance, the following command builds Guix, but replaces its
11140 dependency on the current stable version of Guile with a dependency on
11141 the legacy version of Guile, @code{guile@@2.0}:
11144 guix build --with-input=guile=guile@@2.0 guix
11147 This is a recursive, deep replacement. So in this example, both
11148 @code{guix} and its dependency @code{guile-json} (which also depends on
11149 @code{guile}) get rebuilt against @code{guile@@2.0}.
11151 This is implemented using the @code{package-input-rewriting} Scheme
11152 procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
11154 @item --with-graft=@var{package}=@var{replacement}
11155 This is similar to @option{--with-input} but with an important difference:
11156 instead of rebuilding the whole dependency chain, @var{replacement} is
11157 built and then @dfn{grafted} onto the binaries that were initially
11158 referring to @var{package}. @xref{Security Updates}, for more
11159 information on grafts.
11161 For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
11162 and all its dependencies, replacing references to the version of GnuTLS
11163 they currently refer to:
11166 guix build --with-graft=gnutls=gnutls@@3.5.4 wget
11169 This has the advantage of being much faster than rebuilding everything.
11170 But there is a caveat: it works if and only if @var{package} and
11171 @var{replacement} are strictly compatible---for example, if they provide
11172 a library, the application binary interface (ABI) of those libraries
11173 must be compatible. If @var{replacement} is somehow incompatible with
11174 @var{package}, then the resulting package may be unusable. Use with
11177 @cindex debugging info, rebuilding
11178 @item --with-debug-info=@var{package}
11179 Build @var{package} in a way that preserves its debugging info and graft
11180 it onto packages that depend on it. This is useful if @var{package}
11181 does not already provide debugging info as a @code{debug} output
11182 (@pxref{Installing Debugging Files}).
11184 For example, suppose you're experiencing a crash in Inkscape and would
11185 like to see what's up in GLib, a library deep down in Inkscape's
11186 dependency graph. GLib lacks a @code{debug} output, so debugging is
11187 tough. Fortunately, you rebuild GLib with debugging info and tack it on
11191 guix install inkscape --with-debug-info=glib
11194 Only GLib needs to be recompiled so this takes a reasonable amount of
11195 time. @xref{Installing Debugging Files}, for more info.
11198 Under the hood, this option works by passing the @samp{#:strip-binaries?
11199 #f} to the build system of the package of interest (@pxref{Build
11200 Systems}). Most build systems support that option but some do not. In
11201 that case, an error is raised.
11203 Likewise, if a C/C++ package is built without @code{-g} (which is rarely
11204 the case), debugging info will remain unavailable even when
11205 @code{#:strip-binaries?} is false.
11208 @cindex tool chain, changing the build tool chain of a package
11209 @item --with-c-toolchain=@var{package}=@var{toolchain}
11210 This option changes the compilation of @var{package} and everything that
11211 depends on it so that they get built with @var{toolchain} instead of the
11212 default GNU tool chain for C/C++.
11214 Consider this example:
11217 guix build octave-cli \
11218 --with-c-toolchain=fftw=gcc-toolchain@@10 \
11219 --with-c-toolchain=fftwf=gcc-toolchain@@10
11222 The command above builds a variant of the @code{fftw} and @code{fftwf}
11223 packages using version 10 of @code{gcc-toolchain} instead of the default
11224 tool chain, and then builds a variant of the GNU@tie{}Octave
11225 command-line interface using them. GNU@tie{}Octave itself is also built
11226 with @code{gcc-toolchain@@10}.
11228 This other example builds the Hardware Locality (@code{hwloc}) library
11229 and its dependents up to @code{intel-mpi-benchmarks} with the Clang C
11233 guix build --with-c-toolchain=hwloc=clang-toolchain \
11234 intel-mpi-benchmarks
11238 There can be application binary interface (ABI) incompatibilities among
11239 tool chains. This is particularly true of the C++ standard library and
11240 run-time support libraries such as that of OpenMP@. By rebuilding all
11241 dependents with the same tool chain, @option{--with-c-toolchain} minimizes
11242 the risks of incompatibility but cannot entirely eliminate them. Choose
11243 @var{package} wisely.
11246 @item --with-git-url=@var{package}=@var{url}
11247 @cindex Git, using the latest commit
11248 @cindex latest commit, building
11249 Build @var{package} from the latest commit of the @code{master} branch of the
11250 Git repository at @var{url}. Git sub-modules of the repository are fetched,
11253 For example, the following command builds the NumPy Python library against the
11254 latest commit of the master branch of Python itself:
11257 guix build python-numpy \
11258 --with-git-url=python=https://github.com/python/cpython
11261 This option can also be combined with @option{--with-branch} or
11262 @option{--with-commit} (see below).
11264 @cindex continuous integration
11265 Obviously, since it uses the latest commit of the given branch, the result of
11266 such a command varies over time. Nevertheless it is a convenient way to
11267 rebuild entire software stacks against the latest commit of one or more
11268 packages. This is particularly useful in the context of continuous
11271 Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
11272 consecutive accesses to the same repository. You may want to clean it up once
11273 in a while to save disk space.
11275 @item --with-branch=@var{package}=@var{branch}
11276 Build @var{package} from the latest commit of @var{branch}. If the
11277 @code{source} field of @var{package} is an origin with the @code{git-fetch}
11278 method (@pxref{origin Reference}) or a @code{git-checkout} object, the
11279 repository URL is taken from that @code{source}. Otherwise you have to use
11280 @option{--with-git-url} to specify the URL of the Git repository.
11282 For instance, the following command builds @code{guile-sqlite3} from the
11283 latest commit of its @code{master} branch, and then builds @code{guix} (which
11284 depends on it) and @code{cuirass} (which depends on @code{guix}) against this
11285 specific @code{guile-sqlite3} build:
11288 guix build --with-branch=guile-sqlite3=master cuirass
11291 @item --with-commit=@var{package}=@var{commit}
11292 This is similar to @option{--with-branch}, except that it builds from
11293 @var{commit} rather than the tip of a branch. @var{commit} must be a valid
11294 Git commit SHA1 identifier, a tag, or a @command{git describe} style
11295 identifier such as @code{1.0-3-gabc123}.
11297 @item --with-patch=@var{package}=@var{file}
11298 Add @var{file} to the list of patches applied to @var{package}, where
11299 @var{package} is a spec such as @code{python@@3.8} or @code{glibc}.
11300 @var{file} must contain a patch; it is applied with the flags specified
11301 in the @code{origin} of @var{package} (@pxref{origin Reference}), which
11302 by default includes @code{-p1} (@pxref{patch Directories,,, diffutils,
11303 Comparing and Merging Files}).
11305 As an example, the command below rebuilds Coreutils with the GNU C
11306 Library (glibc) patched with the given patch:
11309 guix build coreutils --with-patch=glibc=./glibc-frob.patch
11312 In this example, glibc itself as well as everything that leads to
11313 Coreutils in the dependency graph is rebuilt.
11315 @cindex upstream, latest version
11316 @item --with-latest=@var{package}
11317 So you like living on the bleeding edge? This option is for you! It
11318 replaces occurrences of @var{package} in the dependency graph with its
11319 latest upstream version, as reported by @command{guix refresh}
11320 (@pxref{Invoking guix refresh}).
11322 It does so by determining the latest upstream release of @var{package}
11323 (if possible), downloading it, and authenticating it @emph{if} it comes
11324 with an OpenPGP signature.
11326 As an example, the command below builds Guix against the latest version
11330 guix build guix --with-latest=guile-json
11333 There are limitations. First, in cases where the tool cannot or does
11334 not know how to authenticate source code, you are at risk of running
11335 malicious code; a warning is emitted in this case. Second, this option
11336 simply changes the source used in the existing package definitions,
11337 which is not always sufficient: there might be additional dependencies
11338 that need to be added, patches to apply, and more generally the quality
11339 assurance work that Guix developers normally do will be missing.
11341 You've been warned! In all the other cases, it's a snappy way to stay
11342 on top. We encourage you to submit patches updating the actual package
11343 definitions once you have successfully tested an upgrade
11344 (@pxref{Contributing}).
11346 @cindex test suite, skipping
11347 @item --without-tests=@var{package}
11348 Build @var{package} without running its tests. This can be useful in
11349 situations where you want to skip the lengthy test suite of a
11350 intermediate package, or if a package's test suite fails in a
11351 non-deterministic fashion. It should be used with care because running
11352 the test suite is a good way to ensure a package is working as intended.
11354 Turning off tests leads to a different store item. Consequently, when
11355 using this option, anything that depends on @var{package} must be
11356 rebuilt, as in this example:
11359 guix install --without-tests=python python-notebook
11362 The command above installs @code{python-notebook} on top of
11363 @code{python} built without running its test suite. To do so, it also
11364 rebuilds everything that depends on @code{python}, including
11365 @code{python-notebook} itself.
11367 Internally, @option{--without-tests} relies on changing the
11368 @code{#:tests?} option of a package's @code{check} phase (@pxref{Build
11369 Systems}). Note that some packages use a customized @code{check} phase
11370 that does not respect a @code{#:tests? #f} setting. Therefore,
11371 @option{--without-tests} has no effect on these packages.
11375 Wondering how to achieve the same effect using Scheme code, for example
11376 in your manifest, or how to write your own package transformation?
11377 @xref{Defining Package Variants}, for an overview of the programming
11378 interfaces available.
11380 @node Additional Build Options
11381 @subsection Additional Build Options
11383 The command-line options presented below are specific to @command{guix
11390 Build quietly, without displaying the build log; this is equivalent to
11391 @option{--verbosity=0}. Upon completion, the build log is kept in @file{/var}
11392 (or similar) and can always be retrieved using the @option{--log-file} option.
11394 @item --file=@var{file}
11395 @itemx -f @var{file}
11396 Build the package, derivation, or other file-like object that the code within
11397 @var{file} evaluates to (@pxref{G-Expressions, file-like objects}).
11399 As an example, @var{file} might contain a package definition like this
11400 (@pxref{Defining Packages}):
11403 @include package-hello.scm
11406 The @var{file} may also contain a JSON representation of one or more
11407 package definitions. Running @code{guix build -f} on @file{hello.json}
11408 with the following contents would result in building the packages
11409 @code{myhello} and @code{greeter}:
11412 @verbatiminclude package-hello.json
11415 @item --manifest=@var{manifest}
11416 @itemx -m @var{manifest}
11417 Build all packages listed in the given @var{manifest}
11418 (@pxref{profile-manifest, @option{--manifest}}).
11420 @item --expression=@var{expr}
11421 @itemx -e @var{expr}
11422 Build the package or derivation @var{expr} evaluates to.
11424 For example, @var{expr} may be @code{(@@ (gnu packages guile)
11425 guile-1.8)}, which unambiguously designates this specific variant of
11426 version 1.8 of Guile.
11428 Alternatively, @var{expr} may be a G-expression, in which case it is used
11429 as a build program passed to @code{gexp->derivation}
11430 (@pxref{G-Expressions}).
11432 Lastly, @var{expr} may refer to a zero-argument monadic procedure
11433 (@pxref{The Store Monad}). The procedure must return a derivation as a
11434 monadic value, which is then passed through @code{run-with-store}.
11438 Build the source derivations of the packages, rather than the packages
11441 For instance, @code{guix build -S gcc} returns something like
11442 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
11445 The returned source tarball is the result of applying any patches and
11446 code snippets specified in the package @code{origin} (@pxref{Defining
11449 @cindex source, verification
11450 As with other derivations, the result of building a source derivation
11451 can be verified using the @option{--check} option (@pxref{build-check}).
11452 This is useful to validate that a (potentially already built or
11453 substituted, thus cached) package source matches against its declared
11456 Note that @command{guix build -S} compiles the sources only of the
11457 specified packages. They do not include the sources of statically
11458 linked dependencies and by themselves are insufficient for reproducing
11462 Fetch and return the source of @var{package-or-derivation} and all their
11463 dependencies, recursively. This is a handy way to obtain a local copy
11464 of all the source code needed to build @var{packages}, allowing you to
11465 eventually build them even without network access. It is an extension
11466 of the @option{--source} option and can accept one of the following
11467 optional argument values:
11471 This value causes the @option{--sources} option to behave in the same way
11472 as the @option{--source} option.
11475 Build the source derivations of all packages, including any source that
11476 might be listed as @code{inputs}. This is the default value.
11479 $ guix build --sources tzdata
11480 The following derivations will be built:
11481 /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
11482 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
11486 Build the source derivations of all packages, as well of all transitive
11487 inputs to the packages. This can be used e.g.@: to
11488 prefetch package source for later offline building.
11491 $ guix build --sources=transitive tzdata
11492 The following derivations will be built:
11493 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
11494 /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
11495 /gnu/store/@dots{}-grep-2.21.tar.xz.drv
11496 /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
11497 /gnu/store/@dots{}-make-4.1.tar.xz.drv
11498 /gnu/store/@dots{}-bash-4.3.tar.xz.drv
11504 @item --system=@var{system}
11505 @itemx -s @var{system}
11506 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
11507 the system type of the build host. The @command{guix build} command allows
11508 you to repeat this option several times, in which case it builds for all the
11509 specified systems; other commands ignore extraneous @option{-s} options.
11512 The @option{--system} flag is for @emph{native} compilation and must not
11513 be confused with cross-compilation. See @option{--target} below for
11514 information on cross-compilation.
11517 An example use of this is on Linux-based systems, which can emulate
11518 different personalities. For instance, passing
11519 @option{--system=i686-linux} on an @code{x86_64-linux} system or
11520 @option{--system=armhf-linux} on an @code{aarch64-linux} system allows
11521 you to build packages in a complete 32-bit environment.
11524 Building for an @code{armhf-linux} system is unconditionally enabled on
11525 @code{aarch64-linux} machines, although certain aarch64 chipsets do not
11526 allow for this functionality, notably the ThunderX.
11529 Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
11530 is enabled (@pxref{Virtualization Services,
11531 @code{qemu-binfmt-service-type}}), you can build for any system for
11532 which a QEMU @code{binfmt_misc} handler is installed.
11534 Builds for a system other than that of the machine you are using can
11535 also be offloaded to a remote machine of the right architecture.
11536 @xref{Daemon Offload Setup}, for more information on offloading.
11538 @item --target=@var{triplet}
11539 @cindex cross-compilation
11540 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
11541 as @code{"aarch64-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
11542 configuration triplets,, autoconf, Autoconf}).
11544 @anchor{build-check}
11546 @cindex determinism, checking
11547 @cindex reproducibility, checking
11548 Rebuild @var{package-or-derivation}, which are already available in the
11549 store, and raise an error if the build results are not bit-for-bit
11552 This mechanism allows you to check whether previously installed
11553 substitutes are genuine (@pxref{Substitutes}), or whether the build result
11554 of a package is deterministic. @xref{Invoking guix challenge}, for more
11555 background information and tools.
11557 When used in conjunction with @option{--keep-failed}, the differing
11558 output is kept in the store, under @file{/gnu/store/@dots{}-check}.
11559 This makes it easy to look for differences between the two results.
11562 @cindex repairing store items
11563 @cindex corruption, recovering from
11564 Attempt to repair the specified store items, if they are corrupt, by
11565 re-downloading or rebuilding them.
11567 This operation is not atomic and thus restricted to @code{root}.
11569 @item --derivations
11571 Return the derivation paths, not the output paths, of the given
11574 @item --root=@var{file}
11575 @itemx -r @var{file}
11576 @cindex GC roots, adding
11577 @cindex garbage collector roots, adding
11578 Make @var{file} a symlink to the result, and register it as a garbage
11581 Consequently, the results of this @command{guix build} invocation are
11582 protected from garbage collection until @var{file} is removed. When
11583 that option is omitted, build results are eligible for garbage
11584 collection as soon as the build completes. @xref{Invoking guix gc}, for
11588 @cindex build logs, access
11589 Return the build log file names or URLs for the given
11590 @var{package-or-derivation}, or raise an error if build logs are
11593 This works regardless of how packages or derivations are specified. For
11594 instance, the following invocations are equivalent:
11597 guix build --log-file $(guix build -d guile)
11598 guix build --log-file $(guix build guile)
11599 guix build --log-file guile
11600 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
11603 If a log is unavailable locally, and unless @option{--no-substitutes} is
11604 passed, the command looks for a corresponding log on one of the
11605 substitute servers (as specified with @option{--substitute-urls}).
11607 So for instance, imagine you want to see the build log of GDB on MIPS,
11608 but you are actually on an @code{x86_64} machine:
11611 $ guix build --log-file gdb -s aarch64-linux
11612 https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
11615 You can freely access a huge library of build logs!
11618 @node Debugging Build Failures
11619 @subsection Debugging Build Failures
11621 @cindex build failures, debugging
11622 When defining a new package (@pxref{Defining Packages}), you will
11623 probably find yourself spending some time debugging and tweaking the
11624 build until it succeeds. To do that, you need to operate the build
11625 commands yourself in an environment as close as possible to the one the
11628 To that end, the first thing to do is to use the @option{--keep-failed}
11629 or @option{-K} option of @command{guix build}, which will keep the
11630 failed build tree in @file{/tmp} or whatever directory you specified as
11631 @env{TMPDIR} (@pxref{Common Build Options, @option{--keep-failed}}).
11633 From there on, you can @command{cd} to the failed build tree and source
11634 the @file{environment-variables} file, which contains all the
11635 environment variable definitions that were in place when the build
11636 failed. So let's say you're debugging a build failure in package
11637 @code{foo}; a typical session would look like this:
11640 $ guix build foo -K
11641 @dots{} @i{build fails}
11642 $ cd /tmp/guix-build-foo.drv-0
11643 $ source ./environment-variables
11647 Now, you can invoke commands as if you were the daemon (almost) and
11648 troubleshoot your build process.
11650 Sometimes it happens that, for example, a package's tests pass when you
11651 run them manually but they fail when the daemon runs them. This can
11652 happen because the daemon runs builds in containers where, unlike in our
11653 environment above, network access is missing, @file{/bin/sh} does not
11654 exist, etc. (@pxref{Build Environment Setup}).
11656 In such cases, you may need to run inspect the build process from within
11657 a container similar to the one the build daemon creates:
11660 $ guix build -K foo
11662 $ cd /tmp/guix-build-foo.drv-0
11663 $ guix shell --no-grafts -C -D foo strace gdb
11664 [env]# source ./environment-variables
11668 Here, @command{guix shell -C} creates a container and spawns a new
11669 shell in it (@pxref{Invoking guix shell}). The @command{strace gdb}
11670 part adds the @command{strace} and @command{gdb} commands to
11671 the container, which you may find handy while debugging. The
11672 @option{--no-grafts} option makes sure we get the exact same
11673 environment, with ungrafted packages (@pxref{Security Updates}, for more
11676 To get closer to a container like that used by the build daemon, we can
11677 remove @file{/bin/sh}:
11683 (Don't worry, this is harmless: this is all happening in the throw-away
11684 container created by @command{guix shell}.)
11686 The @command{strace} command is probably not in the search path, but we
11690 [env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
11693 In this way, not only you will have reproduced the environment variables
11694 the daemon uses, you will also be running the build process in a container
11695 similar to the one the daemon uses.
11698 @node Invoking guix edit
11699 @section Invoking @command{guix edit}
11701 @cindex @command{guix edit}
11702 @cindex package definition, editing
11703 So many packages, so many source files! The @command{guix edit} command
11704 facilitates the life of users and packagers by pointing their editor at
11705 the source file containing the definition of the specified packages.
11709 guix edit gcc@@4.9 vim
11713 launches the program specified in the @env{VISUAL} or in the
11714 @env{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
11717 If you are using a Guix Git checkout (@pxref{Building from Git}), or
11718 have created your own packages on @env{GUIX_PACKAGE_PATH}
11719 (@pxref{Package Modules}), you will be able to edit the package
11720 recipes. In other cases, you will be able to examine the read-only recipes
11721 for packages currently in the store.
11723 Instead of @env{GUIX_PACKAGE_PATH}, the command-line option
11724 @option{--load-path=@var{directory}} (or in short @option{-L
11725 @var{directory}}) allows you to add @var{directory} to the front of the
11726 package module search path and so make your own packages visible.
11728 @node Invoking guix download
11729 @section Invoking @command{guix download}
11731 @cindex @command{guix download}
11732 @cindex downloading package sources
11733 When writing a package definition, developers typically need to download
11734 a source tarball, compute its SHA256 hash, and write that
11735 hash in the package definition (@pxref{Defining Packages}). The
11736 @command{guix download} tool helps with this task: it downloads a file
11737 from the given URI, adds it to the store, and prints both its file name
11738 in the store and its SHA256 hash.
11740 The fact that the downloaded file is added to the store saves bandwidth:
11741 when the developer eventually tries to build the newly defined package
11742 with @command{guix build}, the source tarball will not have to be
11743 downloaded again because it is already in the store. It is also a
11744 convenient way to temporarily stash files, which may be deleted
11745 eventually (@pxref{Invoking guix gc}).
11747 The @command{guix download} command supports the same URIs as used in
11748 package definitions. In particular, it supports @code{mirror://} URIs.
11749 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
11750 Guile bindings for GnuTLS are available in the user's environment; when
11751 they are not available, an error is raised. @xref{Guile Preparations,
11752 how to install the GnuTLS bindings for Guile,, gnutls-guile,
11753 GnuTLS-Guile}, for more information.
11755 @command{guix download} verifies HTTPS server certificates by loading
11756 the certificates of X.509 authorities from the directory pointed to by
11757 the @env{SSL_CERT_DIR} environment variable (@pxref{X.509
11758 Certificates}), unless @option{--no-check-certificate} is used.
11760 The following options are available:
11763 @item --hash=@var{algorithm}
11764 @itemx -H @var{algorithm}
11765 Compute a hash using the specified @var{algorithm}. @xref{Invoking guix
11766 hash}, for more information.
11768 @item --format=@var{fmt}
11769 @itemx -f @var{fmt}
11770 Write the hash in the format specified by @var{fmt}. For more
11771 information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
11773 @item --no-check-certificate
11774 Do not validate the X.509 certificates of HTTPS servers.
11776 When using this option, you have @emph{absolutely no guarantee} that you
11777 are communicating with the authentic server responsible for the given
11778 URL, which makes you vulnerable to ``man-in-the-middle'' attacks.
11780 @item --output=@var{file}
11781 @itemx -o @var{file}
11782 Save the downloaded file to @var{file} instead of adding it to the
11786 @node Invoking guix hash
11787 @section Invoking @command{guix hash}
11789 @cindex @command{guix hash}
11790 The @command{guix hash} command computes the hash of a file.
11791 It is primarily a convenience tool for anyone contributing to the
11792 distribution: it computes the cryptographic hash of one or more files, which can be
11793 used in the definition of a package (@pxref{Defining Packages}).
11795 The general syntax is:
11798 guix hash @var{option} @var{file} ...
11801 When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
11802 hash of data read from standard input. @command{guix hash} has the
11807 @item --hash=@var{algorithm}
11808 @itemx -H @var{algorithm}
11809 Compute a hash using the specified @var{algorithm}, @code{sha256} by
11812 @var{algorithm} must be the name of a cryptographic hash algorithm
11813 supported by Libgcrypt @i{via} Guile-Gcrypt---e.g., @code{sha512} or
11814 @code{sha3-256} (@pxref{Hash Functions,,, guile-gcrypt, Guile-Gcrypt
11815 Reference Manual}).
11817 @item --format=@var{fmt}
11818 @itemx -f @var{fmt}
11819 Write the hash in the format specified by @var{fmt}.
11821 Supported formats: @code{base64}, @code{nix-base32}, @code{base32}, @code{base16}
11822 (@code{hex} and @code{hexadecimal} can be used as well).
11824 If the @option{--format} option is not specified, @command{guix hash}
11825 will output the hash in @code{nix-base32}. This representation is used
11826 in the definitions of packages.
11830 This option is deprecated in favor of @option{--serializer}. It is a
11831 legacy alias for that with @var{type} set to @code{nar}.
11833 @item --serializer=@var{type}
11835 Compute the hash on @var{file} using @var{type} serialization.
11837 @var{type} may be one of the following:
11841 This is the default: it computes the hash of a file's contents.
11844 Compute the hash of a ``normalized archive'' (or ``nar'') containing
11845 @var{file}, including its children if it is a directory. Some of the
11846 metadata of @var{file} is part of the archive; for instance, when
11847 @var{file} is a regular file, the hash is different depending on whether
11848 @var{file} is executable or not. Metadata such as time stamps have no
11849 impact on the hash (@pxref{Invoking guix archive}, for more info on the
11851 @c FIXME: Replace xref above with xref to an ``Archive'' section when
11855 Compute the hash of the file or directory as a Git ``tree'', following
11856 the same method as the Git version control system.
11859 @item --exclude-vcs
11861 When combined with @option{--recursive}, exclude version control system
11862 directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.).
11865 As an example, here is how you would compute the hash of a Git checkout,
11866 which is useful when using the @code{git-fetch} method (@pxref{origin
11870 $ git clone http://example.org/foo.git
11872 $ guix hash -x --serializer=nar .
11876 @node Invoking guix import
11877 @section Invoking @command{guix import}
11879 @cindex importing packages
11880 @cindex package import
11881 @cindex package conversion
11882 @cindex Invoking @command{guix import}
11883 The @command{guix import} command is useful for people who would like to
11884 add a package to the distribution with as little work as
11885 possible---a legitimate demand. The command knows of a few
11886 repositories from which it can ``import'' package metadata. The result
11887 is a package definition, or a template thereof, in the format we know
11888 (@pxref{Defining Packages}).
11890 The general syntax is:
11893 guix import @var{importer} @var{options}@dots{}
11896 @var{importer} specifies the source from which to import package
11897 metadata, and @var{options} specifies a package identifier and other
11898 options specific to @var{importer}.
11900 Some of the importers rely on the ability to run the @command{gpgv} command.
11901 For these, GnuPG must be installed and in @code{$PATH}; run @code{guix install
11904 Currently, the available ``importers'' are:
11908 Import metadata for the given GNU package. This provides a template
11909 for the latest version of that GNU package, including the hash of its
11910 source tarball, and its canonical synopsis and description.
11912 Additional information such as the package dependencies and its
11913 license needs to be figured out manually.
11915 For example, the following command returns a package definition for
11919 guix import gnu hello
11922 Specific command-line options are:
11925 @item --key-download=@var{policy}
11926 As for @command{guix refresh}, specify the policy to handle missing
11927 OpenPGP keys when verifying the package signature. @xref{Invoking guix
11928 refresh, @option{--key-download}}.
11933 Import metadata from the @uref{https://pypi.python.org/, Python Package
11934 Index}. Information is taken from the JSON-formatted description
11935 available at @code{pypi.python.org} and usually includes all the relevant
11936 information, including package dependencies. For maximum efficiency, it
11937 is recommended to install the @command{unzip} utility, so that the
11938 importer can unzip Python wheels and gather data from them.
11940 The command below imports metadata for the latest version of the
11941 @code{itsdangerous} Python package:
11944 guix import pypi itsdangerous
11947 You can also ask for a specific version:
11950 guix import pypi itsdangerous@@1.1.0
11956 Traverse the dependency graph of the given upstream package recursively
11957 and generate package expressions for all those packages that are not yet
11963 Import metadata from @uref{https://rubygems.org/, RubyGems}. Information
11964 is taken from the JSON-formatted description available at
11965 @code{rubygems.org} and includes most relevant information, including
11966 runtime dependencies. There are some caveats, however. The metadata
11967 doesn't distinguish between synopses and descriptions, so the same string
11968 is used for both fields. Additionally, the details of non-Ruby
11969 dependencies required to build native extensions is unavailable and left
11970 as an exercise to the packager.
11972 The command below imports metadata for the @code{rails} Ruby package:
11975 guix import gem rails
11981 Traverse the dependency graph of the given upstream package recursively
11982 and generate package expressions for all those packages that are not yet
11989 Import metadata from @uref{https://content.minetest.net, ContentDB}.
11990 Information is taken from the JSON-formatted metadata provided through
11991 @uref{https://content.minetest.net/help/api/, ContentDB's API} and
11992 includes most relevant information, including dependencies. There are
11993 some caveats, however. The license information is often incomplete.
11994 The commit hash is sometimes missing. The descriptions are in the
11995 Markdown format, but Guix uses Texinfo instead. Texture packs and
11996 subgames are unsupported.
11998 The command below imports metadata for the Mesecons mod by Jeija:
12001 guix import minetest Jeija/mesecons
12004 The author name can also be left out:
12007 guix import minetest mesecons
12013 Traverse the dependency graph of the given upstream package recursively
12014 and generate package expressions for all those packages that are not yet
12020 Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
12021 Information is taken from the JSON-formatted metadata provided through
12022 @uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
12023 relevant information, such as module dependencies. License information
12024 should be checked closely. If Perl is available in the store, then the
12025 @code{corelist} utility will be used to filter core modules out of the
12026 list of dependencies.
12028 The command command below imports metadata for the Acme::Boolean Perl
12032 guix import cpan Acme::Boolean
12037 @cindex Bioconductor
12038 Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
12039 central repository for the @uref{https://r-project.org, GNU@tie{}R
12040 statistical and graphical environment}.
12042 Information is extracted from the @file{DESCRIPTION} file of the package.
12044 The command command below imports metadata for the Cairo R package:
12047 guix import cran Cairo
12050 You can also ask for a specific version:
12053 guix import cran rasterVis@@0.50.3
12056 When @option{--recursive} is added, the importer will traverse the
12057 dependency graph of the given upstream package recursively and generate
12058 package expressions for all those packages that are not yet in Guix.
12060 When @option{--style=specification} is added, the importer will generate
12061 package definitions whose inputs are package specifications instead of
12062 references to package variables. This is useful when generated package
12063 definitions are to be appended to existing user modules, as the list of
12064 used package modules need not be changed. The default is
12065 @option{--style=variable}.
12067 When @option{--archive=bioconductor} is added, metadata is imported from
12068 @uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
12069 packages for the analysis and comprehension of high-throughput
12070 genomic data in bioinformatics.
12072 Information is extracted from the @file{DESCRIPTION} file contained in the
12075 The command below imports metadata for the GenomicRanges R package:
12078 guix import cran --archive=bioconductor GenomicRanges
12081 Finally, you can also import R packages that have not yet been published on
12082 CRAN or Bioconductor as long as they are in a git repository. Use
12083 @option{--archive=git} followed by the URL of the git repository:
12086 guix import cran --archive=git https://github.com/immunogenomics/harmony
12092 Import TeX package information from the TeX Live package database for
12093 TeX packages that are part of the @uref{https://www.tug.org/texlive/,
12094 TeX Live distribution}.
12096 Information about the package is obtained from the TeX Live package
12097 database, a plain text file that is included in the @code{texlive-bin}
12098 package. The source code is downloaded from possibly multiple locations
12099 in the SVN repository of the Tex Live project.
12101 The command command below imports metadata for the @code{fontspec}
12105 guix import texlive fontspec
12109 @cindex JSON, import
12110 Import package metadata from a local JSON file. Consider the following
12111 example package definition in JSON format:
12117 "source": "mirror://gnu/hello/hello-2.10.tar.gz",
12118 "build-system": "gnu",
12119 "home-page": "https://www.gnu.org/software/hello/",
12120 "synopsis": "Hello, GNU world: An example GNU package",
12121 "description": "GNU Hello prints a greeting.",
12122 "license": "GPL-3.0+",
12123 "native-inputs": ["gettext"]
12127 The field names are the same as for the @code{<package>} record
12128 (@xref{Defining Packages}). References to other packages are provided
12129 as JSON lists of quoted package specification strings such as
12130 @code{guile} or @code{guile@@2.0}.
12132 The importer also supports a more explicit source definition using the
12133 common fields for @code{<origin>} records:
12139 "method": "url-fetch",
12140 "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
12142 "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
12149 The command below reads metadata from the JSON file @code{hello.json}
12150 and outputs a package expression:
12153 guix import json hello.json
12158 Import metadata from the Haskell community's central package archive
12159 @uref{https://hackage.haskell.org/, Hackage}. Information is taken from
12160 Cabal files and includes all the relevant information, including package
12163 Specific command-line options are:
12168 Read a Cabal file from standard input.
12169 @item --no-test-dependencies
12171 Do not include dependencies required only by the test suites.
12172 @item --cabal-environment=@var{alist}
12173 @itemx -e @var{alist}
12174 @var{alist} is a Scheme alist defining the environment in which the
12175 Cabal conditionals are evaluated. The accepted keys are: @code{os},
12176 @code{arch}, @code{impl} and a string representing the name of a flag.
12177 The value associated with a flag has to be either the symbol
12178 @code{true} or @code{false}. The value associated with other keys
12179 has to conform to the Cabal file format definition. The default value
12180 associated with the keys @code{os}, @code{arch} and @code{impl} is
12181 @samp{linux}, @samp{x86_64} and @samp{ghc}, respectively.
12184 Traverse the dependency graph of the given upstream package recursively
12185 and generate package expressions for all those packages that are not yet
12189 The command below imports metadata for the latest version of the
12190 HTTP Haskell package without including test dependencies and
12191 specifying the value of the flag @samp{network-uri} as @code{false}:
12194 guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
12197 A specific package version may optionally be specified by following the
12198 package name by an at-sign and a version number as in the following example:
12201 guix import hackage mtl@@2.1.3.1
12206 The @code{stackage} importer is a wrapper around the @code{hackage} one.
12207 It takes a package name, looks up the package version included in a
12208 long-term support (LTS) @uref{https://www.stackage.org, Stackage}
12209 release and uses the @code{hackage} importer to retrieve its metadata.
12210 Note that it is up to you to select an LTS release compatible with the
12211 GHC compiler used by Guix.
12213 Specific command-line options are:
12216 @item --no-test-dependencies
12218 Do not include dependencies required only by the test suites.
12219 @item --lts-version=@var{version}
12220 @itemx -l @var{version}
12221 @var{version} is the desired LTS release version. If omitted the latest
12225 Traverse the dependency graph of the given upstream package recursively
12226 and generate package expressions for all those packages that are not yet
12230 The command below imports metadata for the HTTP Haskell package
12231 included in the LTS Stackage release version 7.18:
12234 guix import stackage --lts-version=7.18 HTTP
12239 Import metadata from an Emacs Lisp Package Archive (ELPA) package
12240 repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
12242 Specific command-line options are:
12245 @item --archive=@var{repo}
12246 @itemx -a @var{repo}
12247 @var{repo} identifies the archive repository from which to retrieve the
12248 information. Currently the supported repositories and their identifiers
12252 @uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
12253 identifier. This is the default.
12255 Packages from @code{elpa.gnu.org} are signed with one of the keys
12256 contained in the GnuPG keyring at
12257 @file{share/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
12258 @code{emacs} package (@pxref{Package Installation, ELPA package
12259 signatures,, emacs, The GNU Emacs Manual}).
12262 @uref{https://elpa.nongnu.org/nongnu/, NonGNU}, selected by the
12263 @code{nongnu} identifier.
12266 @uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
12267 @code{melpa-stable} identifier.
12270 @uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa}
12276 Traverse the dependency graph of the given upstream package recursively
12277 and generate package expressions for all those packages that are not yet
12283 Import metadata from the crates.io Rust package repository
12284 @uref{https://crates.io, crates.io}, as in this example:
12287 guix import crate blake2-rfc
12290 The crate importer also allows you to specify a version string:
12293 guix import crate constant-time-eq@@0.1.0
12296 Additional options include:
12301 Traverse the dependency graph of the given upstream package recursively
12302 and generate package expressions for all those packages that are not yet
12309 Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
12310 repository used by the OCaml community.
12312 Additional options include:
12317 Traverse the dependency graph of the given upstream package recursively
12318 and generate package expressions for all those packages that are not yet
12321 By default, packages are searched in the official OPAM repository. This
12322 option, which can be used more than once, lets you add other repositories
12323 which will be searched for packages. It accepts as valid arguments:
12326 @item the name of a known repository - can be one of @code{opam},
12327 @code{coq} (equivalent to @code{coq-released}),
12328 @code{coq-core-dev}, @code{coq-extra-dev} or @code{grew}.
12329 @item the URL of a repository as expected by the
12330 @code{opam repository add} command (for instance, the URL equivalent
12331 of the above @code{opam} name would be
12332 @uref{https://opam.ocaml.org}).
12333 @item the path to a local copy of a repository (a directory containing a
12334 @file{packages/} sub-directory).
12337 Repositories are assumed to be passed to this option by order of
12338 preference. The additional repositories will not replace the default
12339 @code{opam} repository, which is always kept as a fallback.
12341 Also, please note that versions are not compared across repositories.
12342 The first repository (from left to right) that has at least one version
12343 of a given package will prevail over any others, and the version
12344 imported will be the latest one found @emph{in this repository only}.
12350 Import metadata for a Go module using
12351 @uref{https://proxy.golang.org, proxy.golang.org}.
12354 guix import go gopkg.in/yaml.v2
12357 It is possible to use a package specification with a @code{@@VERSION}
12358 suffix to import a specific version.
12360 Additional options include:
12365 Traverse the dependency graph of the given upstream package recursively
12366 and generate package expressions for all those packages that are not yet
12368 @item --pin-versions
12369 When using this option, the importer preserves the exact versions of the
12370 Go modules dependencies instead of using their latest available
12371 versions. This can be useful when attempting to import packages that
12372 recursively depend on former versions of themselves to build. When
12373 using this mode, the symbol of the package is made by appending the
12374 version to its name, so that multiple versions of the same package can
12380 Import metadata for @uref{https://wiki.call-cc.org/eggs, CHICKEN eggs}.
12381 The information is taken from @file{PACKAGE.egg} files found in the
12382 @uref{git://code.call-cc.org/eggs-5-all, eggs-5-all} Git
12383 repository. However, it does not provide all the information that we
12384 need, there is no ``description'' field, and the licenses used are not
12385 always precise (BSD is often used instead of BSD-N).
12388 guix import egg sourcehut
12391 You can also ask for a specific version:
12394 guix import egg arrays@@1.0
12397 Additional options include:
12401 Traverse the dependency graph of the given upstream package recursively
12402 and generate package expressions for all those packages that are not yet
12407 The structure of the @command{guix import} code is modular. It would be
12408 useful to have more importers for other package formats, and your help
12409 is welcome here (@pxref{Contributing}).
12411 @node Invoking guix refresh
12412 @section Invoking @command{guix refresh}
12414 @cindex @command {guix refresh}
12415 The primary audience of the @command{guix refresh} command is packagers.
12416 As a user, you may be interested in the @option{--with-latest} option,
12417 which can bring you package update superpowers built upon @command{guix
12418 refresh} (@pxref{Package Transformation Options,
12419 @option{--with-latest}}). By default, @command{guix refresh} reports
12420 any packages provided by the distribution that are outdated compared to
12421 the latest upstream version, like this:
12425 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
12426 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
12429 Alternatively, one can specify packages to consider, in which case a
12430 warning is emitted for packages that lack an updater:
12433 $ guix refresh coreutils guile guile-ssh
12434 gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
12435 gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
12438 @command{guix refresh} browses the upstream repository of each package and determines
12439 the highest version number of the releases therein. The command
12440 knows how to update specific types of packages: GNU packages, ELPA
12441 packages, etc.---see the documentation for @option{--type} below. There
12442 are many packages, though, for which it lacks a method to determine
12443 whether a new upstream release is available. However, the mechanism is
12444 extensible, so feel free to get in touch with us to add a new method!
12449 Consider the packages specified, and all the packages upon which they depend.
12452 $ guix refresh --recursive coreutils
12453 gnu/packages/acl.scm:40:13: acl would be upgraded from 2.2.53 to 2.3.1
12454 gnu/packages/m4.scm:30:12: 1.4.18 is already the latest version of m4
12455 gnu/packages/xml.scm:68:2: warning: no updater for expat
12456 gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gmp
12462 Sometimes the upstream name differs from the package name used in Guix,
12463 and @command{guix refresh} needs a little help. Most updaters honor the
12464 @code{upstream-name} property in package definitions, which can be used
12468 (define-public network-manager
12470 (name "network-manager")
12472 (properties '((upstream-name . "NetworkManager")))))
12475 When passed @option{--update}, it modifies distribution source files to
12476 update the version numbers and source tarball hashes of those package
12477 recipes (@pxref{Defining Packages}). This is achieved by downloading
12478 each package's latest source tarball and its associated OpenPGP
12479 signature, authenticating the downloaded tarball against its signature
12480 using @command{gpgv}, and finally computing its hash---note that GnuPG must be
12481 installed and in @code{$PATH}; run @code{guix install gnupg} if needed.
12484 key used to sign the tarball is missing from the user's keyring, an
12485 attempt is made to automatically retrieve it from a public key server;
12486 when this is successful, the key is added to the user's keyring; otherwise,
12487 @command{guix refresh} reports an error.
12489 The following options are supported:
12493 @item --expression=@var{expr}
12494 @itemx -e @var{expr}
12495 Consider the package @var{expr} evaluates to.
12497 This is useful to precisely refer to a package, as in this example:
12500 guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
12503 This command lists the dependents of the ``final'' libc (essentially all
12508 Update distribution source files (package recipes) in place. This is
12509 usually run from a checkout of the Guix source tree (@pxref{Running
12510 Guix Before It Is Installed}):
12513 $ ./pre-inst-env guix refresh -s non-core -u
12516 @xref{Defining Packages}, for more information on package definitions.
12518 @item --select=[@var{subset}]
12519 @itemx -s @var{subset}
12520 Select all the packages in @var{subset}, one of @code{core} or
12523 The @code{core} subset refers to all the packages at the core of the
12524 distribution---i.e., packages that are used to build ``everything
12525 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
12526 changing one of these packages in the distribution entails a rebuild of
12527 all the others. Thus, such updates are an inconvenience to users in
12528 terms of build time or bandwidth used to achieve the upgrade.
12530 The @code{non-core} subset refers to the remaining packages. It is
12531 typically useful in cases where an update of the core packages would be
12534 @item --manifest=@var{file}
12535 @itemx -m @var{file}
12536 Select all the packages from the manifest in @var{file}. This is useful to
12537 check if any packages of the user manifest can be updated.
12539 @item --type=@var{updater}
12540 @itemx -t @var{updater}
12541 Select only packages handled by @var{updater} (may be a comma-separated
12542 list of updaters). Currently, @var{updater} may be one of:
12546 the updater for GNU packages;
12548 the updater for packages hosted at @uref{https://savannah.gnu.org, Savannah};
12550 the updater for packages hosted at @uref{https://sourceforge.net, SourceForge};
12552 the updater for GNOME packages;
12554 the updater for KDE packages;
12556 the updater for X.org packages;
12558 the updater for packages hosted on kernel.org;
12560 the updater for @uref{https://wiki.call-cc.org/eggs/, Egg} packages;
12562 the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
12564 the updater for @uref{https://cran.r-project.org/, CRAN} packages;
12566 the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
12568 the updater for @uref{https://www.cpan.org/, CPAN} packages;
12570 the updater for @uref{https://pypi.python.org, PyPI} packages.
12572 the updater for @uref{https://rubygems.org, RubyGems} packages.
12574 the updater for @uref{https://github.com, GitHub} packages.
12576 the updater for @uref{https://hackage.haskell.org, Hackage} packages.
12578 the updater for @uref{https://www.stackage.org, Stackage} packages.
12580 the updater for @uref{https://crates.io, Crates} packages.
12582 the updater for @uref{https://launchpad.net, Launchpad} packages.
12584 a generic updater that crawls the HTML page where the source tarball of
12585 the package is hosted, when applicable.
12588 a generic updater for packages hosted on Git repositories. It tries to
12589 be smart about parsing Git tag names, but if it is not able to parse the
12590 tag name and compare tags correctly, users can define the following
12591 properties for a package.
12594 @item @code{release-tag-prefix}: a regular expression for matching a prefix of
12597 @item @code{release-tag-suffix}: a regular expression for matching a suffix of
12600 @item @code{release-tag-version-delimiter}: a string used as the delimiter in
12601 the tag name for separating the numbers of the version.
12603 @item @code{accept-pre-releases}: by default, the updater will ignore
12604 pre-releases; to make it also look for pre-releases, set the this
12605 property to @code{#t}.
12614 '((release-tag-prefix . "^release0-")
12615 (release-tag-suffix . "[a-z]?$")
12616 (release-tag-version-delimiter . ":"))))
12622 For instance, the following command only checks for updates of Emacs
12623 packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
12626 $ guix refresh --type=elpa,cran
12627 gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
12628 gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
12631 @item --list-updaters
12633 List available updaters and exit (see @option{--type} above).
12635 For each updater, display the fraction of packages it covers; at the
12636 end, display the fraction of packages covered by all these updaters.
12639 In addition, @command{guix refresh} can be passed one or more package
12640 names, as in this example:
12643 $ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
12647 The command above specifically updates the @code{emacs} and
12648 @code{idutils} packages. The @option{--select} option would have no
12649 effect in this case. You might also want to update definitions that
12650 correspond to the packages installed in your profile:
12653 $ ./pre-inst-env guix refresh -u \
12654 $(guix package --list-installed | cut -f1)
12657 When considering whether to upgrade a package, it is sometimes
12658 convenient to know which packages would be affected by the upgrade and
12659 should be checked for compatibility. For this the following option may
12660 be used when passing @command{guix refresh} one or more package names:
12664 @item --list-dependent
12666 List top-level dependent packages that would need to be rebuilt as a
12667 result of upgrading one or more packages.
12669 @xref{Invoking guix graph, the @code{reverse-package} type of
12670 @command{guix graph}}, for information on how to visualize the list of
12671 dependents of a package.
12675 Be aware that the @option{--list-dependent} option only
12676 @emph{approximates} the rebuilds that would be required as a result of
12677 an upgrade. More rebuilds might be required under some circumstances.
12680 $ guix refresh --list-dependent flex
12681 Building the following 120 packages would ensure 213 dependent packages are rebuilt:
12682 hop@@2.4.0 emacs-geiser@@0.13 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
12685 The command above lists a set of packages that could be built to check
12686 for compatibility with an upgraded @code{flex} package.
12690 @item --list-transitive
12691 List all the packages which one or more packages depend upon.
12694 $ guix refresh --list-transitive flex
12695 flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
12696 bison@@3.0.5 indent@@2.2.10 tar@@1.30 gzip@@1.9 bzip2@@1.0.6 xz@@5.2.4 file@@5.33 @dots{}
12701 The command above lists a set of packages which, when changed, would cause
12702 @code{flex} to be rebuilt.
12704 The following options can be used to customize GnuPG operation:
12708 @item --gpg=@var{command}
12709 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
12710 for in @code{$PATH}.
12712 @item --keyring=@var{file}
12713 Use @var{file} as the keyring for upstream keys. @var{file} must be in the
12714 @dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx}
12715 and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
12716 (@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
12717 information on a tool to manipulate keybox files).
12719 When this option is omitted, @command{guix refresh} uses
12720 @file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
12721 signing keys. OpenPGP signatures are checked against keys from this keyring;
12722 missing keys are downloaded to this keyring as well (see
12723 @option{--key-download} below).
12725 You can export keys from your default GPG keyring into a keybox file using
12726 commands like this one:
12729 gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
12732 Likewise, you can fetch keys to a specific keybox file like this:
12735 gpg --no-default-keyring --keyring mykeyring.kbx \
12736 --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
12739 @xref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
12740 Privacy Guard}, for more information on GPG's @option{--keyring} option.
12742 @item --key-download=@var{policy}
12743 Handle missing OpenPGP keys according to @var{policy}, which may be one
12748 Always download missing OpenPGP keys from the key server, and add them
12749 to the user's GnuPG keyring.
12752 Never try to download missing OpenPGP keys. Instead just bail out.
12755 When a package signed with an unknown OpenPGP key is encountered, ask
12756 the user whether to download it or not. This is the default behavior.
12759 @item --key-server=@var{host}
12760 Use @var{host} as the OpenPGP key server when importing a public key.
12762 @item --load-path=@var{directory}
12763 Add @var{directory} to the front of the package module search path
12764 (@pxref{Package Modules}).
12766 This allows users to define their own packages and make them visible to
12767 the command-line tools.
12771 The @code{github} updater uses the
12772 @uref{https://developer.github.com/v3/, GitHub API} to query for new
12773 releases. When used repeatedly e.g.@: when refreshing all packages,
12774 GitHub will eventually refuse to answer any further API requests. By
12775 default 60 API requests per hour are allowed, and a full refresh on all
12776 GitHub packages in Guix requires more than this. Authentication with
12777 GitHub through the use of an API token alleviates these limits. To use
12778 an API token, set the environment variable @env{GUIX_GITHUB_TOKEN} to a
12779 token procured from @uref{https://github.com/settings/tokens} or
12783 @node Invoking guix style
12784 @section Invoking @command{guix style}
12786 The @command{guix style} command helps packagers style their package
12787 definitions according to the latest fashionable trends. The command
12788 currently provides the providing styling rules:
12792 formatting package definitions according to the project's conventions
12793 (@pxref{Formatting Code});
12796 rewriting package inputs to the ``new style'', as explained below.
12799 The way package inputs are written is going through a transition
12800 (@pxref{package Reference}, for more on package inputs). Until version
12801 1.3.0, package inputs were written using the ``old style'', where each
12802 input was given an explicit label, most of the time the package name:
12807 ;; The "old style" (deprecated).
12808 (inputs `(("libunistring" ,libunistring)
12809 ("libffi" ,libffi))))
12812 Today, the old style is deprecated and the preferred style looks like
12818 ;; The "new style".
12819 (inputs (list libunistring libffi)))
12822 Likewise, uses of @code{alist-delete} and friends to manipulate inputs
12823 is now deprecated in favor of @code{modify-inputs} (@pxref{Defining
12824 Package Variants}, for more info on @code{modify-inputs}).
12826 In the vast majority of cases, this is a purely mechanical change on the
12827 surface syntax that does not even incur a package rebuild. Running
12828 @command{guix style -S inputs} can do that for you, whether you're working on
12829 packages in Guix proper or in an external channel.
12831 The general syntax is:
12834 guix style [@var{options}] @var{package}@dots{}
12837 This causes @command{guix style} to analyze and rewrite the definition
12838 of @var{package}@dots{} or, when @var{package} is omitted, of @emph{all}
12839 the packages. The @option{--styling} or @option{-S} option allows you
12840 to select the style rule, the default rule being @code{format}---see
12843 The available options are listed below.
12848 Show source file locations that would be edited but do not modify them.
12850 @item --styling=@var{rule}
12851 @itemx -S @var{rule}
12852 Apply @var{rule}, one of the following styling rules:
12856 Format the given package definition(s)---this is the default styling
12857 rule. For example, a packager running Guix on a checkout
12858 (@pxref{Running Guix Before It Is Installed}) might want to reformat the
12859 definition of the Coreutils package like so:
12862 ./pre-inst-env guix style coreutils
12866 Rewrite package inputs to the ``new style'', as described above. This
12867 is how you would rewrite inputs of package @code{whatnot} in your own
12871 guix style -L ~/my/channel -S inputs whatnot
12874 Rewriting is done in a conservative way: preserving comments and bailing
12875 out if it cannot make sense of the code that appears in an inputs field.
12876 The @option{--input-simplification} option described below provides
12877 fine-grain control over when inputs should be simplified.
12880 @item --load-path=@var{directory}
12881 @itemx -L @var{directory}
12882 Add @var{directory} to the front of the package module search path
12883 (@pxref{Package Modules}).
12885 @item --expression=@var{expr}
12886 @itemx -e @var{expr}
12887 Style the package @var{expr} evaluates to.
12889 For example, running:
12892 guix style -e '(@@ (gnu packages gcc) gcc-5)'
12895 styles the @code{gcc-5} package definition.
12897 @item --input-simplification=@var{policy}
12898 When using the @code{inputs} styling rule, with @samp{-S inputs}, this
12899 option specifies the package input simplification policy for cases where
12900 an input label does not match the corresponding package name.
12901 @var{policy} may be one of the following:
12905 Simplify inputs only when the change is ``silent'', meaning that the
12906 package does not need to be rebuilt (its derivation is unchanged).
12909 Simplify inputs only when that is ``safe'' to do: the package might need
12910 to be rebuilt, but the change is known to have no observable effect.
12913 Simplify inputs even when input labels do not match package names, and
12914 even if that might have an observable effect.
12917 The default is @code{silent}, meaning that input simplifications do not
12918 trigger any package rebuild.
12921 @node Invoking guix lint
12922 @section Invoking @command{guix lint}
12924 @cindex @command{guix lint}
12925 @cindex package, checking for errors
12926 The @command{guix lint} command is meant to help package developers avoid
12927 common errors and use a consistent style. It runs a number of checks on
12928 a given set of packages in order to find common mistakes in their
12929 definitions. Available @dfn{checkers} include (see
12930 @option{--list-checkers} for a complete list):
12935 Validate certain typographical and stylistic rules about package
12936 descriptions and synopses.
12938 @item inputs-should-be-native
12939 Identify inputs that should most likely be native inputs.
12945 @itemx source-file-name
12946 Probe @code{home-page} and @code{source} URLs and report those that are
12947 invalid. Suggest a @code{mirror://} URL when applicable. If the
12948 @code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
12949 URL@. Check that the source file name is meaningful, e.g.@: is not just a
12950 version number or ``git-checkout'', without a declared @code{file-name}
12951 (@pxref{origin Reference}).
12953 @item source-unstable-tarball
12954 Parse the @code{source} URL to determine if a tarball from GitHub is
12955 autogenerated or if it is a release tarball. Unfortunately GitHub's
12956 autogenerated tarballs are sometimes regenerated.
12959 Check that the derivation of the given packages can be successfully
12960 computed for all the supported systems (@pxref{Derivations}).
12962 @item profile-collisions
12963 Check whether installing the given packages in a profile would lead to
12964 collisions. Collisions occur when several packages with the same name
12965 but a different version or a different store file name are propagated.
12966 @xref{package Reference, @code{propagated-inputs}}, for more information
12967 on propagated inputs.
12970 @cindex Software Heritage, source code archive
12971 @cindex archival of source code, Software Heritage
12972 Checks whether the package's source code is archived at
12973 @uref{https://www.softwareheritage.org, Software Heritage}.
12975 When the source code that is not archived comes from a version-control system
12976 (VCS)---e.g., it's obtained with @code{git-fetch}, send Software Heritage a
12977 ``save'' request so that it eventually archives it. This ensures that the
12978 source will remain available in the long term, and that Guix can fall back to
12979 Software Heritage should the source code disappear from its original host.
12980 The status of recent ``save'' requests can be
12981 @uref{https://archive.softwareheritage.org/save/#requests, viewed on-line}.
12983 When source code is a tarball obtained with @code{url-fetch}, simply print a
12984 message when it is not archived. As of this writing, Software Heritage does
12985 not allow requests to save arbitrary tarballs; we are working on ways to
12986 ensure that non-VCS source code is also archived.
12989 @uref{https://archive.softwareheritage.org/api/#rate-limiting, limits the
12990 request rate per IP address}. When the limit is reached, @command{guix lint}
12991 prints a message and the @code{archival} checker stops doing anything until
12992 that limit has been reset.
12995 @cindex security vulnerabilities
12996 @cindex CVE, Common Vulnerabilities and Exposures
12997 Report known vulnerabilities found in the Common Vulnerabilities and
12998 Exposures (CVE) databases of the current and past year
12999 @uref{https://nvd.nist.gov/vuln/data-feeds, published by the US
13002 To view information about a particular vulnerability, visit pages such as:
13006 @indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
13008 @indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
13012 where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
13013 @code{CVE-2015-7554}.
13015 Package developers can specify in package recipes the
13016 @uref{https://nvd.nist.gov/products/cpe,Common Platform Enumeration (CPE)}
13017 name and version of the package when they differ from the name or version
13018 that Guix uses, as in this example:
13024 ;; CPE calls this package "grub2".
13025 (properties '((cpe-name . "grub2")
13026 (cpe-version . "2.3"))))
13029 @c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
13030 Some entries in the CVE database do not specify which version of a
13031 package they apply to, and would thus ``stick around'' forever. Package
13032 developers who found CVE alerts and verified they can be ignored can
13033 declare them as in this example:
13039 ;; These CVEs no longer apply and can be safely ignored.
13040 (properties `((lint-hidden-cve . ("CVE-2011-0433"
13043 "CVE-2011-5244")))))
13047 Warn about obvious source code formatting issues: trailing white space,
13048 use of tabulations, etc.
13051 Report old-style input labels that do not match the name of the
13052 corresponding package. This aims to help migrate from the ``old input
13053 style''. @xref{package Reference}, for more information on package
13054 inputs and input styles. @xref{Invoking guix style}, on how to migrate
13058 The general syntax is:
13061 guix lint @var{options} @var{package}@dots{}
13064 If no package is given on the command line, then all packages are checked.
13065 The @var{options} may be zero or more of the following:
13068 @item --list-checkers
13070 List and describe all the available checkers that will be run on packages
13075 Only enable the checkers specified in a comma-separated list using the
13076 names returned by @option{--list-checkers}.
13080 Only disable the checkers specified in a comma-separated list using the
13081 names returned by @option{--list-checkers}.
13085 Only enable the checkers that do not depend on Internet access.
13087 @item --load-path=@var{directory}
13088 @itemx -L @var{directory}
13089 Add @var{directory} to the front of the package module search path
13090 (@pxref{Package Modules}).
13092 This allows users to define their own packages and make them visible to
13093 the command-line tools.
13097 @node Invoking guix size
13098 @section Invoking @command{guix size}
13101 @cindex package size
13103 @cindex @command{guix size}
13104 The @command{guix size} command helps package developers profile the
13105 disk usage of packages. It is easy to overlook the impact of an
13106 additional dependency added to a package, or the impact of using a
13107 single output for a package that could easily be split (@pxref{Packages
13108 with Multiple Outputs}). Such are the typical issues that
13109 @command{guix size} can highlight.
13111 The command can be passed one or more package specifications
13112 such as @code{gcc@@4.8}
13113 or @code{guile:debug}, or a file name in the store. Consider this
13117 $ guix size coreutils
13118 store item total self
13119 /gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
13120 /gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
13121 /gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
13122 /gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
13123 /gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
13124 /gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
13125 /gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
13126 /gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
13131 The store items listed here constitute the @dfn{transitive closure} of
13132 Coreutils---i.e., Coreutils and all its dependencies, recursively---as
13133 would be returned by:
13136 $ guix gc -R /gnu/store/@dots{}-coreutils-8.23
13139 Here the output shows three columns next to store items. The first column,
13140 labeled ``total'', shows the size in mebibytes (MiB) of the closure of
13141 the store item---that is, its own size plus the size of all its
13142 dependencies. The next column, labeled ``self'', shows the size of the
13143 item itself. The last column shows the ratio of the size of the item
13144 itself to the space occupied by all the items listed here.
13146 In this example, we see that the closure of Coreutils weighs in at
13147 79@tie{}MiB, most of which is taken by libc and GCC's run-time support
13148 libraries. (That libc and GCC's libraries represent a large fraction of
13149 the closure is not a problem @i{per se} because they are always available
13150 on the system anyway.)
13152 Since the command also accepts store file names, assessing the size of
13153 a build result is straightforward:
13156 guix size $(guix system build config.scm)
13159 When the package(s) passed to @command{guix size} are available in the
13160 store@footnote{More precisely, @command{guix size} looks for the
13161 @emph{ungrafted} variant of the given package(s), as returned by
13162 @code{guix build @var{package} --no-grafts}. @xref{Security Updates},
13163 for information on grafts.}, @command{guix size} queries the daemon to determine its
13164 dependencies, and measures its size in the store, similar to @command{du
13165 -ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
13168 When the given packages are @emph{not} in the store, @command{guix size}
13169 reports information based on the available substitutes
13170 (@pxref{Substitutes}). This makes it possible it to profile disk usage of
13171 store items that are not even on disk, only available remotely.
13173 You can also specify several package names:
13176 $ guix size coreutils grep sed bash
13177 store item total self
13178 /gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
13179 /gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
13180 /gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
13181 /gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
13187 In this example we see that the combination of the four packages takes
13188 102.3@tie{}MiB in total, which is much less than the sum of each closure
13189 since they have a lot of dependencies in common.
13191 When looking at the profile returned by @command{guix size}, you may
13192 find yourself wondering why a given package shows up in the profile at
13193 all. To understand it, you can use @command{guix graph --path -t
13194 references} to display the shortest path between the two packages
13195 (@pxref{Invoking guix graph}).
13197 The available options are:
13201 @item --substitute-urls=@var{urls}
13202 Use substitute information from @var{urls}.
13203 @xref{client-substitute-urls, the same option for @code{guix build}}.
13205 @item --sort=@var{key}
13206 Sort lines according to @var{key}, one of the following options:
13210 the size of each item (the default);
13212 the total size of the item's closure.
13215 @item --map-file=@var{file}
13216 Write a graphical map of disk usage in PNG format to @var{file}.
13218 For the example above, the map looks like this:
13220 @image{images/coreutils-size-map,5in,, map of Coreutils disk usage
13221 produced by @command{guix size}}
13223 This option requires that
13224 @uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
13225 installed and visible in Guile's module search path. When that is not
13226 the case, @command{guix size} fails as it tries to load it.
13228 @item --system=@var{system}
13229 @itemx -s @var{system}
13230 Consider packages for @var{system}---e.g., @code{x86_64-linux}.
13232 @item --load-path=@var{directory}
13233 @itemx -L @var{directory}
13234 Add @var{directory} to the front of the package module search path
13235 (@pxref{Package Modules}).
13237 This allows users to define their own packages and make them visible to
13238 the command-line tools.
13241 @node Invoking guix graph
13242 @section Invoking @command{guix graph}
13245 @cindex @command{guix graph}
13246 @cindex package dependencies
13247 Packages and their dependencies form a @dfn{graph}, specifically a
13248 directed acyclic graph (DAG). It can quickly become difficult to have a
13249 mental model of the package DAG, so the @command{guix graph} command
13250 provides a visual representation of the DAG@. By default,
13251 @command{guix graph} emits a DAG representation in the input format of
13252 @uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
13253 directly to the @command{dot} command of Graphviz. It can also emit an
13254 HTML page with embedded JavaScript code to display a ``chord diagram''
13255 in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
13256 emit Cypher queries to construct a graph in a graph database supporting
13257 the @uref{https://www.opencypher.org/, openCypher} query language. With
13258 @option{--path}, it simply displays the shortest path between two
13259 packages. The general syntax is:
13262 guix graph @var{options} @var{package}@dots{}
13265 For example, the following command generates a PDF file representing the
13266 package DAG for the GNU@tie{}Core Utilities, showing its build-time
13270 guix graph coreutils | dot -Tpdf > dag.pdf
13273 The output looks like this:
13275 @image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
13277 Nice little graph, no?
13279 You may find it more pleasant to navigate the graph interactively with
13280 @command{xdot} (from the @code{xdot} package):
13283 guix graph coreutils | xdot -
13286 But there is more than one graph! The one above is concise: it is the
13287 graph of package objects, omitting implicit inputs such as GCC, libc,
13288 grep, etc. It is often useful to have such a concise graph, but
13289 sometimes one may want to see more details. @command{guix graph} supports
13290 several types of graphs, allowing you to choose the level of detail:
13294 This is the default type used in the example above. It shows the DAG of
13295 package objects, excluding implicit dependencies. It is concise, but
13296 filters out many details.
13298 @item reverse-package
13299 This shows the @emph{reverse} DAG of packages. For example:
13302 guix graph --type=reverse-package ocaml
13305 ...@: yields the graph of packages that @emph{explicitly} depend on OCaml (if
13306 you are also interested in cases where OCaml is an implicit dependency, see
13307 @code{reverse-bag} below).
13309 Note that for core packages this can yield huge graphs. If all you want
13310 is to know the number of packages that depend on a given package, use
13311 @command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
13312 @option{--list-dependent}}).
13315 This is the package DAG, @emph{including} implicit inputs.
13317 For instance, the following command:
13320 guix graph --type=bag-emerged coreutils
13323 ...@: yields this bigger graph:
13325 @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
13327 At the bottom of the graph, we see all the implicit inputs of
13328 @var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
13330 Now, note that the dependencies of these implicit inputs---that is, the
13331 @dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
13332 here, for conciseness.
13335 Similar to @code{bag-emerged}, but this time including all the bootstrap
13338 @item bag-with-origins
13339 Similar to @code{bag}, but also showing origins and their dependencies.
13342 This shows the @emph{reverse} DAG of packages. Unlike @code{reverse-package},
13343 it also takes implicit dependencies into account. For example:
13346 guix graph -t reverse-bag dune
13350 ...@: yields the graph of all packages that depend on Dune, directly or
13351 indirectly. Since Dune is an @emph{implicit} dependency of many packages
13352 @i{via} @code{dune-build-system}, this shows a large number of packages,
13353 whereas @code{reverse-package} would show very few if any.
13356 This is the most detailed representation: It shows the DAG of
13357 derivations (@pxref{Derivations}) and plain store items. Compared to
13358 the above representation, many additional nodes are visible, including
13359 build scripts, patches, Guile modules, etc.
13361 For this type of graph, it is also possible to pass a @file{.drv} file
13362 name instead of a package name, as in:
13365 guix graph -t derivation $(guix system build -d my-config.scm)
13369 This is the graph of @dfn{package modules} (@pxref{Package Modules}).
13370 For example, the following command shows the graph for the package
13371 module that defines the @code{guile} package:
13374 guix graph -t module guile | xdot -
13378 All the types above correspond to @emph{build-time dependencies}. The
13379 following graph type represents the @emph{run-time dependencies}:
13383 This is the graph of @dfn{references} of a package output, as returned
13384 by @command{guix gc --references} (@pxref{Invoking guix gc}).
13386 If the given package output is not available in the store, @command{guix
13387 graph} attempts to obtain dependency information from substitutes.
13389 Here you can also pass a store file name instead of a package name. For
13390 example, the command below produces the reference graph of your profile
13391 (which can be big!):
13394 guix graph -t references $(readlink -f ~/.guix-profile)
13398 This is the graph of the @dfn{referrers} of a store item, as returned by
13399 @command{guix gc --referrers} (@pxref{Invoking guix gc}).
13401 This relies exclusively on local information from your store. For
13402 instance, let us suppose that the current Inkscape is available in 10
13403 profiles on your machine; @command{guix graph -t referrers inkscape}
13404 will show a graph rooted at Inkscape and with those 10 profiles linked
13407 It can help determine what is preventing a store item from being garbage
13412 @cindex shortest path, between packages
13413 Often, the graph of the package you are interested in does not fit on
13414 your screen, and anyway all you want to know is @emph{why} that package
13415 actually depends on some seemingly unrelated package. The
13416 @option{--path} option instructs @command{guix graph} to display the
13417 shortest path between two packages (or derivations, or store items,
13421 $ guix graph --path emacs libunistring
13424 libunistring@@0.9.10
13425 $ guix graph --path -t derivation emacs libunistring
13426 /gnu/store/@dots{}-emacs-26.3.drv
13427 /gnu/store/@dots{}-mailutils-3.9.drv
13428 /gnu/store/@dots{}-libunistring-0.9.10.drv
13429 $ guix graph --path -t references emacs libunistring
13430 /gnu/store/@dots{}-emacs-26.3
13431 /gnu/store/@dots{}-libidn2-2.2.0
13432 /gnu/store/@dots{}-libunistring-0.9.10
13435 Sometimes you still want to visualize the graph but would like to trim
13436 it so it can actually be displayed. One way to do it is via the
13437 @option{--max-depth} (or @option{-M}) option, which lets you specify the
13438 maximum depth of the graph. In the example below, we visualize only
13439 @code{libreoffice} and the nodes whose distance to @code{libreoffice} is
13443 guix graph -M 2 libreoffice | xdot -f fdp -
13446 Mind you, that's still a big ball of spaghetti, but at least
13447 @command{dot} can render it quickly and it can be browsed somewhat.
13449 The available options are the following:
13452 @item --type=@var{type}
13453 @itemx -t @var{type}
13454 Produce a graph output of @var{type}, where @var{type} must be one of
13455 the values listed above.
13458 List the supported graph types.
13460 @item --backend=@var{backend}
13461 @itemx -b @var{backend}
13462 Produce a graph using the selected @var{backend}.
13464 @item --list-backends
13465 List the supported graph backends.
13467 Currently, the available backends are Graphviz and d3.js.
13470 Display the shortest path between two nodes of the type specified by
13471 @option{--type}. The example below shows the shortest path between
13472 @code{libreoffice} and @code{llvm} according to the references of
13473 @code{libreoffice}:
13476 $ guix graph --path -t references libreoffice llvm
13477 /gnu/store/@dots{}-libreoffice-6.4.2.2
13478 /gnu/store/@dots{}-libepoxy-1.5.4
13479 /gnu/store/@dots{}-mesa-19.3.4
13480 /gnu/store/@dots{}-llvm-9.0.1
13483 @item --expression=@var{expr}
13484 @itemx -e @var{expr}
13485 Consider the package @var{expr} evaluates to.
13487 This is useful to precisely refer to a package, as in this example:
13490 guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
13493 @item --system=@var{system}
13494 @itemx -s @var{system}
13495 Display the graph for @var{system}---e.g., @code{i686-linux}.
13497 The package dependency graph is largely architecture-independent, but there
13498 are some architecture-dependent bits that this option allows you to visualize.
13500 @item --load-path=@var{directory}
13501 @itemx -L @var{directory}
13502 Add @var{directory} to the front of the package module search path
13503 (@pxref{Package Modules}).
13505 This allows users to define their own packages and make them visible to
13506 the command-line tools.
13509 On top of that, @command{guix graph} supports all the usual package
13510 transformation options (@pxref{Package Transformation Options}). This
13511 makes it easy to view the effect of a graph-rewriting transformation
13512 such as @option{--with-input}. For example, the command below outputs
13513 the graph of @code{git} once @code{openssl} has been replaced by
13514 @code{libressl} everywhere in the graph:
13517 guix graph git --with-input=openssl=libressl
13520 So many possibilities, so much fun!
13522 @node Invoking guix publish
13523 @section Invoking @command{guix publish}
13525 @cindex @command{guix publish}
13526 The purpose of @command{guix publish} is to enable users to easily share
13527 their store with others, who can then use it as a substitute server
13528 (@pxref{Substitutes}).
13530 When @command{guix publish} runs, it spawns an HTTP server which allows
13531 anyone with network access to obtain substitutes from it. This means
13532 that any machine running Guix can also act as if it were a build farm,
13533 since the HTTP interface is compatible with Cuirass, the software behind
13534 the @code{@value{SUBSTITUTE-SERVER-1}} build farm.
13536 For security, each substitute is signed, allowing recipients to check
13537 their authenticity and integrity (@pxref{Substitutes}). Because
13538 @command{guix publish} uses the signing key of the system, which is only
13539 readable by the system administrator, it must be started as root; the
13540 @option{--user} option makes it drop root privileges early on.
13542 The signing key pair must be generated before @command{guix publish} is
13543 launched, using @command{guix archive --generate-key} (@pxref{Invoking
13546 When the @option{--advertise} option is passed, the server advertises
13547 its availability on the local network using multicast DNS (mDNS) and DNS
13548 service discovery (DNS-SD), currently @i{via} Guile-Avahi (@pxref{Top,,,
13549 guile-avahi, Using Avahi in Guile Scheme Programs}).
13551 The general syntax is:
13554 guix publish @var{options}@dots{}
13557 Running @command{guix publish} without any additional arguments will
13558 spawn an HTTP server on port 8080:
13564 Once a publishing server has been authorized, the daemon may download
13565 substitutes from it. @xref{Getting Substitutes from Other Servers}.
13567 By default, @command{guix publish} compresses archives on the fly as it
13568 serves them. This ``on-the-fly'' mode is convenient in that it requires
13569 no setup and is immediately available. However, when serving lots of
13570 clients, we recommend using the @option{--cache} option, which enables
13571 caching of the archives before they are sent to clients---see below for
13572 details. The @command{guix weather} command provides a handy way to
13573 check what a server provides (@pxref{Invoking guix weather}).
13575 As a bonus, @command{guix publish} also serves as a content-addressed
13576 mirror for source files referenced in @code{origin} records
13577 (@pxref{origin Reference}). For instance, assuming @command{guix
13578 publish} is running on @code{example.org}, the following URL returns the
13579 raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
13580 (represented in @code{nix-base32} format, @pxref{Invoking guix hash}):
13583 http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
13586 Obviously, these URLs only work for files that are in the store; in
13587 other cases, they return 404 (``Not Found'').
13589 @cindex build logs, publication
13590 Build logs are available from @code{/log} URLs like:
13593 http://example.org/log/gwspk@dots{}-guile-2.2.3
13597 When @command{guix-daemon} is configured to save compressed build logs,
13598 as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
13599 URLs return the compressed log as-is, with an appropriate
13600 @code{Content-Type} and/or @code{Content-Encoding} header. We recommend
13601 running @command{guix-daemon} with @option{--log-compression=gzip} since
13602 Web browsers can automatically decompress it, which is not the case with
13605 The following options are available:
13608 @item --port=@var{port}
13609 @itemx -p @var{port}
13610 Listen for HTTP requests on @var{port}.
13612 @item --listen=@var{host}
13613 Listen on the network interface for @var{host}. The default is to
13614 accept connections from any interface.
13616 @item --user=@var{user}
13617 @itemx -u @var{user}
13618 Change privileges to @var{user} as soon as possible---i.e., once the
13619 server socket is open and the signing key has been read.
13621 @item --compression[=@var{method}[:@var{level}]]
13622 @itemx -C [@var{method}[:@var{level}]]
13623 Compress data using the given @var{method} and @var{level}. @var{method} is
13624 one of @code{lzip}, @code{zstd}, and @code{gzip}; when @var{method} is
13625 omitted, @code{gzip} is used.
13627 When @var{level} is zero, disable compression. The range 1 to 9 corresponds
13628 to different compression levels: 1 is the fastest, and 9 is the best
13629 (CPU-intensive). The default is 3.
13631 Usually, @code{lzip} compresses noticeably better than @code{gzip} for a
13632 small increase in CPU usage; see
13633 @uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip
13634 Web page}. However, @code{lzip} achieves low decompression throughput
13635 (on the order of 50@tie{}MiB/s on modern hardware), which can be a
13636 bottleneck for someone who downloads over a fast network connection.
13638 The compression ratio of @code{zstd} is between that of @code{lzip} and
13639 that of @code{gzip}; its main advantage is a
13640 @uref{https://facebook.github.io/zstd/,high decompression speed}.
13642 Unless @option{--cache} is used, compression occurs on the fly and
13643 the compressed streams are not
13644 cached. Thus, to reduce load on the machine that runs @command{guix
13645 publish}, it may be a good idea to choose a low compression level, to
13646 run @command{guix publish} behind a caching proxy, or to use
13647 @option{--cache}. Using @option{--cache} has the advantage that it
13648 allows @command{guix publish} to add @code{Content-Length} HTTP header
13651 This option can be repeated, in which case every substitute gets compressed
13652 using all the selected methods, and all of them are advertised. This is
13653 useful when users may not support all the compression methods: they can select
13654 the one they support.
13656 @item --cache=@var{directory}
13657 @itemx -c @var{directory}
13658 Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
13659 and only serve archives that are in cache.
13661 When this option is omitted, archives and meta-data are created
13662 on-the-fly. This can reduce the available bandwidth, especially when
13663 compression is enabled, since this may become CPU-bound. Another
13664 drawback of the default mode is that the length of archives is not known
13665 in advance, so @command{guix publish} does not add a
13666 @code{Content-Length} HTTP header to its responses, which in turn
13667 prevents clients from knowing the amount of data being downloaded.
13669 Conversely, when @option{--cache} is used, the first request for a store
13670 item (@i{via} a @code{.narinfo} URL) triggers a
13671 background process to @dfn{bake} the archive---computing its
13672 @code{.narinfo} and compressing the archive, if needed. Once the
13673 archive is cached in @var{directory}, subsequent requests succeed and
13674 are served directly from the cache, which guarantees that clients get
13675 the best possible bandwidth.
13677 That first @code{.narinfo} request nonetheless returns 200, provided the
13678 requested store item is ``small enough'', below the cache bypass
13679 threshold---see @option{--cache-bypass-threshold} below. That way,
13680 clients do not have to wait until the archive is baked. For larger
13681 store items, the first @code{.narinfo} request returns 404, meaning that
13682 clients have to wait until the archive is baked.
13684 The ``baking'' process is performed by worker threads. By default, one
13685 thread per CPU core is created, but this can be customized. See
13686 @option{--workers} below.
13688 When @option{--ttl} is used, cached entries are automatically deleted
13689 when they have expired.
13691 @item --workers=@var{N}
13692 When @option{--cache} is used, request the allocation of @var{N} worker
13693 threads to ``bake'' archives.
13695 @item --ttl=@var{ttl}
13696 Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
13697 (TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
13698 days, @code{1m} means 1 month, and so on.
13700 This allows the user's Guix to keep substitute information in cache for
13701 @var{ttl}. However, note that @code{guix publish} does not itself
13702 guarantee that the store items it provides will indeed remain available
13703 for as long as @var{ttl}.
13705 Additionally, when @option{--cache} is used, cached entries that have
13706 not been accessed for @var{ttl} and that no longer have a corresponding
13707 item in the store, may be deleted.
13709 @item --negative-ttl=@var{ttl}
13710 Similarly produce @code{Cache-Control} HTTP headers to advertise the
13711 time-to-live (TTL) of @emph{negative} lookups---missing store items, for
13712 which the HTTP 404 code is returned. By default, no negative TTL is
13715 This parameter can help adjust server load and substitute latency by
13716 instructing cooperating clients to be more or less patient when a store
13719 @item --cache-bypass-threshold=@var{size}
13720 When used in conjunction with @option{--cache}, store items smaller than
13721 @var{size} are immediately available, even when they are not yet in
13722 cache. @var{size} is a size in bytes, or it can be suffixed by @code{M}
13723 for megabytes and so on. The default is @code{10M}.
13725 ``Cache bypass'' allows you to reduce the publication delay for clients
13726 at the expense of possibly additional I/O and CPU use on the server
13727 side: depending on the client access patterns, those store items can end
13728 up being baked several times until a copy is available in cache.
13730 Increasing the threshold may be useful for sites that have few users, or
13731 to guarantee that users get substitutes even for store items that are
13734 @item --nar-path=@var{path}
13735 Use @var{path} as the prefix for the URLs of ``nar'' files
13736 (@pxref{Invoking guix archive, normalized archives}).
13738 By default, nars are served at a URL such as
13739 @code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to
13740 change the @code{/nar} part to @var{path}.
13742 @item --public-key=@var{file}
13743 @itemx --private-key=@var{file}
13744 Use the specific @var{file}s as the public/private key pair used to sign
13745 the store items being published.
13747 The files must correspond to the same key pair (the private key is used
13748 for signing and the public key is merely advertised in the signature
13749 metadata). They must contain keys in the canonical s-expression format
13750 as produced by @command{guix archive --generate-key} (@pxref{Invoking
13751 guix archive}). By default, @file{/etc/guix/signing-key.pub} and
13752 @file{/etc/guix/signing-key.sec} are used.
13754 @item --repl[=@var{port}]
13755 @itemx -r [@var{port}]
13756 Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
13757 Reference Manual}) on @var{port} (37146 by default). This is used
13758 primarily for debugging a running @command{guix publish} server.
13761 Enabling @command{guix publish} on Guix System is a one-liner: just
13762 instantiate a @code{guix-publish-service-type} service in the @code{services} field
13763 of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
13764 @code{guix-publish-service-type}}).
13766 If you are instead running Guix on a ``foreign distro'', follow these
13771 If your host distro uses the systemd init system:
13774 # ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
13775 /etc/systemd/system/
13776 # systemctl start guix-publish && systemctl enable guix-publish
13780 If your host distro uses the Upstart init system:
13783 # ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
13784 # start guix-publish
13788 Otherwise, proceed similarly with your distro's init system.
13791 @node Invoking guix challenge
13792 @section Invoking @command{guix challenge}
13794 @cindex reproducible builds
13795 @cindex verifiable builds
13796 @cindex @command{guix challenge}
13798 Do the binaries provided by this server really correspond to the source
13799 code it claims to build? Is a package build process deterministic?
13800 These are the questions the @command{guix challenge} command attempts to
13803 The former is obviously an important question: Before using a substitute
13804 server (@pxref{Substitutes}), one had better @emph{verify} that it
13805 provides the right binaries, and thus @emph{challenge} it. The latter
13806 is what enables the former: If package builds are deterministic, then
13807 independent builds of the package should yield the exact same result,
13808 bit for bit; if a server provides a binary different from the one
13809 obtained locally, it may be either corrupt or malicious.
13811 We know that the hash that shows up in @file{/gnu/store} file names is
13812 the hash of all the inputs of the process that built the file or
13813 directory---compilers, libraries, build scripts,
13814 etc. (@pxref{Introduction}). Assuming deterministic build processes,
13815 one store file name should map to exactly one build output.
13816 @command{guix challenge} checks whether there is, indeed, a single
13817 mapping by comparing the build outputs of several independent builds of
13818 any given store item.
13820 The command output looks like this:
13823 $ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
13824 updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
13825 updating list of substitutes from 'https://guix.example.org'... 100.0%
13826 /gnu/store/@dots{}-openssl-1.0.2d contents differ:
13827 local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
13828 https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
13829 https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
13831 /lib/libcrypto.so.1.1
13834 /gnu/store/@dots{}-git-2.5.0 contents differ:
13835 local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
13836 https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
13837 https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
13839 /libexec/git-core/git-fsck
13841 /gnu/store/@dots{}-pius-2.1.1 contents differ:
13842 local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
13843 https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
13844 https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
13846 /share/man/man1/pius.1.gz
13850 6,406 store items were analyzed:
13851 - 4,749 (74.1%) were identical
13852 - 525 (8.2%) differed
13853 - 1,132 (17.7%) were inconclusive
13857 In this example, @command{guix challenge} first scans the store to
13858 determine the set of locally-built derivations---as opposed to store
13859 items that were downloaded from a substitute server---and then queries
13860 all the substitute servers. It then reports those store items for which
13861 the servers obtained a result different from the local build.
13863 @cindex non-determinism, in package builds
13864 As an example, @code{guix.example.org} always gets a different answer.
13865 Conversely, @code{@value{SUBSTITUTE-SERVER-1}} agrees with local builds, except in the
13866 case of Git. This might indicate that the build process of Git is
13867 non-deterministic, meaning that its output varies as a function of
13868 various things that Guix does not fully control, in spite of building
13869 packages in isolated environments (@pxref{Features}). Most common
13870 sources of non-determinism include the addition of timestamps in build
13871 results, the inclusion of random numbers, and directory listings sorted
13872 by inode number. See @uref{https://reproducible-builds.org/docs/}, for
13875 To find out what is wrong with this Git binary, the easiest approach is
13879 guix challenge git \
13880 --diff=diffoscope \
13881 --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
13884 This automatically invokes @command{diffoscope}, which displays detailed
13885 information about files that differ.
13887 Alternatively, we can do something along these lines (@pxref{Invoking guix
13891 $ wget -q -O - https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-git-2.5.0 \
13892 | lzip -d | guix archive -x /tmp/git
13893 $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
13896 This command shows the difference between the files resulting from the
13897 local build, and the files resulting from the build on
13898 @code{@value{SUBSTITUTE-SERVER-1}} (@pxref{Overview, Comparing and Merging Files,,
13899 diffutils, Comparing and Merging Files}). The @command{diff} command
13900 works great for text files. When binary files differ, a better option
13901 is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
13902 visualize differences for all kinds of files.
13904 Once you have done that work, you can tell whether the differences are due
13905 to a non-deterministic build process or to a malicious server. We try
13906 hard to remove sources of non-determinism in packages to make it easier
13907 to verify substitutes, but of course, this is a process that
13908 involves not just Guix, but a large part of the free software community.
13909 In the meantime, @command{guix challenge} is one tool to help address
13912 If you are writing packages for Guix, you are encouraged to check
13913 whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain the
13914 same build result as you did with:
13917 $ guix challenge @var{package}
13921 where @var{package} is a package specification such as
13922 @code{guile@@2.0} or @code{glibc:debug}.
13924 The general syntax is:
13927 guix challenge @var{options} [@var{packages}@dots{}]
13930 When a difference is found between the hash of a locally-built item and
13931 that of a server-provided substitute, or among substitutes provided by
13932 different servers, the command displays it as in the example above and
13933 its exit code is 2 (other non-zero exit codes denote other kinds of
13936 The one option that matters is:
13940 @item --substitute-urls=@var{urls}
13941 Consider @var{urls} the whitespace-separated list of substitute source
13942 URLs to compare to.
13944 @item --diff=@var{mode}
13945 Upon mismatches, show differences according to @var{mode}, one of:
13948 @item @code{simple} (the default)
13949 Show the list of files that differ.
13951 @item @code{diffoscope}
13952 @itemx @var{command}
13953 Invoke @uref{https://diffoscope.org/, Diffoscope}, passing it
13954 two directories whose contents do not match.
13956 When @var{command} is an absolute file name, run @var{command} instead
13960 Do not show further details about the differences.
13963 Thus, unless @option{--diff=none} is passed, @command{guix challenge}
13964 downloads the store items from the given substitute servers so that it
13969 Show details about matches (identical contents) in addition to
13970 information about mismatches.
13974 @node Invoking guix copy
13975 @section Invoking @command{guix copy}
13977 @cindex copy, of store items, over SSH
13978 @cindex SSH, copy of store items
13979 @cindex sharing store items across machines
13980 @cindex transferring store items across machines
13981 The @command{guix copy} command copies items from the store of one
13982 machine to that of another machine over a secure shell (SSH)
13983 connection@footnote{This command is available only when Guile-SSH was
13984 found. @xref{Requirements}, for details.}. For example, the following
13985 command copies the @code{coreutils} package, the user's profile, and all
13986 their dependencies over to @var{host}, logged in as @var{user}:
13989 guix copy --to=@var{user}@@@var{host} \
13990 coreutils $(readlink -f ~/.guix-profile)
13993 If some of the items to be copied are already present on @var{host},
13994 they are not actually sent.
13996 The command below retrieves @code{libreoffice} and @code{gimp} from
13997 @var{host}, assuming they are available there:
14000 guix copy --from=@var{host} libreoffice gimp
14003 The SSH connection is established using the Guile-SSH client, which is
14004 compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
14005 @file{~/.ssh/config}, and uses the SSH agent for authentication.
14007 The key used to sign items that are sent must be accepted by the remote
14008 machine. Likewise, the key used by the remote machine to sign items you
14009 are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
14010 own daemon. @xref{Invoking guix archive}, for more information about
14011 store item authentication.
14013 The general syntax is:
14016 guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
14019 You must always specify one of the following options:
14022 @item --to=@var{spec}
14023 @itemx --from=@var{spec}
14024 Specify the host to send to or receive from. @var{spec} must be an SSH
14025 spec such as @code{example.org}, @code{charlie@@example.org}, or
14026 @code{charlie@@example.org:2222}.
14029 The @var{items} can be either package names, such as @code{gimp}, or
14030 store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
14032 When specifying the name of a package to send, it is first built if
14033 needed, unless @option{--dry-run} was specified. Common build options
14034 are supported (@pxref{Common Build Options}).
14037 @node Invoking guix container
14038 @section Invoking @command{guix container}
14040 @cindex @command{guix container}
14042 As of version @value{VERSION}, this tool is experimental. The interface
14043 is subject to radical change in the future.
14046 The purpose of @command{guix container} is to manipulate processes
14047 running within an isolated environment, commonly known as a
14048 ``container'', typically created by the @command{guix shell}
14049 (@pxref{Invoking guix shell}) and @command{guix system container}
14050 (@pxref{Invoking guix system}) commands.
14052 The general syntax is:
14055 guix container @var{action} @var{options}@dots{}
14058 @var{action} specifies the operation to perform with a container, and
14059 @var{options} specifies the context-specific arguments for the action.
14061 The following actions are available:
14065 Execute a command within the context of a running container.
14070 guix container exec @var{pid} @var{program} @var{arguments}@dots{}
14073 @var{pid} specifies the process ID of the running container.
14074 @var{program} specifies an executable file name within the root file
14075 system of the container. @var{arguments} are the additional options that
14076 will be passed to @var{program}.
14078 The following command launches an interactive login shell inside a
14079 Guix system container, started by @command{guix system container}, and whose
14080 process ID is 9001:
14083 guix container exec 9001 /run/current-system/profile/bin/bash --login
14086 Note that the @var{pid} cannot be the parent process of a container. It
14087 must be PID 1 of the container or one of its child processes.
14091 @node Invoking guix weather
14092 @section Invoking @command{guix weather}
14094 Occasionally you're grumpy because substitutes are lacking and you end
14095 up building packages by yourself (@pxref{Substitutes}). The
14096 @command{guix weather} command reports on substitute availability on the
14097 specified servers so you can have an idea of whether you'll be grumpy
14098 today. It can sometimes be useful info as a user, but it is primarily
14099 useful to people running @command{guix publish} (@pxref{Invoking guix
14102 @cindex statistics, for substitutes
14103 @cindex availability of substitutes
14104 @cindex substitute availability
14105 @cindex weather, substitute availability
14106 Here's a sample run:
14109 $ guix weather --substitute-urls=https://guix.example.org
14110 computing 5,872 package derivations for x86_64-linux...
14111 looking for 6,128 store items on https://guix.example.org..
14112 updating list of substitutes from 'https://guix.example.org'... 100.0%
14113 https://guix.example.org
14114 43.4% substitutes available (2,658 out of 6,128)
14115 7,032.5 MiB of nars (compressed)
14116 19,824.2 MiB on disk (uncompressed)
14117 0.030 seconds per request (182.9 seconds in total)
14118 33.5 requests per second
14120 9.8% (342 out of 3,470) of the missing items are queued
14122 x86_64-linux: 518 (59.7%)
14123 i686-linux: 221 (25.5%)
14124 aarch64-linux: 128 (14.8%)
14125 build rate: 23.41 builds per hour
14126 x86_64-linux: 11.16 builds per hour
14127 i686-linux: 6.03 builds per hour
14128 aarch64-linux: 6.41 builds per hour
14131 @cindex continuous integration, statistics
14132 As you can see, it reports the fraction of all the packages for which
14133 substitutes are available on the server---regardless of whether
14134 substitutes are enabled, and regardless of whether this server's signing
14135 key is authorized. It also reports the size of the compressed archives
14136 (``nars'') provided by the server, the size the corresponding store
14137 items occupy in the store (assuming deduplication is turned off), and
14138 the server's throughput. The second part gives continuous integration
14139 (CI) statistics, if the server supports it. In addition, using the
14140 @option{--coverage} option, @command{guix weather} can list ``important''
14141 package substitutes missing on the server (see below).
14143 To achieve that, @command{guix weather} queries over HTTP(S) meta-data
14144 (@dfn{narinfos}) for all the relevant store items. Like @command{guix
14145 challenge}, it ignores signatures on those substitutes, which is
14146 innocuous since the command only gathers statistics and cannot install
14149 The general syntax is:
14152 guix weather @var{options}@dots{} [@var{packages}@dots{}]
14155 When @var{packages} is omitted, @command{guix weather} checks the availability
14156 of substitutes for @emph{all} the packages, or for those specified with
14157 @option{--manifest}; otherwise it only considers the specified packages. It
14158 is also possible to query specific system types with @option{--system}.
14159 @command{guix weather} exits with a non-zero code when the fraction of
14160 available substitutes is below 100%.
14162 The available options are listed below.
14165 @item --substitute-urls=@var{urls}
14166 @var{urls} is the space-separated list of substitute server URLs to
14167 query. When this option is omitted, the default set of substitute
14168 servers is queried.
14170 @item --system=@var{system}
14171 @itemx -s @var{system}
14172 Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
14173 option can be repeated, in which case @command{guix weather} will query
14174 substitutes for several system types.
14176 @item --manifest=@var{file}
14177 Instead of querying substitutes for all the packages, only ask for those
14178 specified in @var{file}. @var{file} must contain a @dfn{manifest}, as
14179 with the @code{-m} option of @command{guix package} (@pxref{Invoking
14182 This option can be repeated several times, in which case the manifests
14185 @item --coverage[=@var{count}]
14186 @itemx -c [@var{count}]
14187 Report on substitute coverage for packages: list packages with at least
14188 @var{count} dependents (zero by default) for which substitutes are
14189 unavailable. Dependent packages themselves are not listed: if @var{b} depends
14190 on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though
14191 @var{b} usually lacks substitutes as well. The result looks like this:
14194 $ guix weather --substitute-urls=@value{SUBSTITUTE-URLS} -c 10
14195 computing 8,983 package derivations for x86_64-linux...
14196 looking for 9,343 store items on @value{SUBSTITUTE-URLS}...
14197 updating substitutes from '@value{SUBSTITUTE-URLS}'... 100.0%
14198 @value{SUBSTITUTE-URLS}
14199 64.7% substitutes available (6,047 out of 9,343)
14201 2502 packages are missing from '@value{SUBSTITUTE-URLS}' for 'x86_64-linux', among which:
14202 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
14203 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
14204 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
14208 What this example shows is that @code{kcoreaddons} and presumably the 58
14209 packages that depend on it have no substitutes at
14210 @code{@value{SUBSTITUTE-SERVER-1}}; likewise for @code{qgpgme} and the 46
14211 packages that depend on it.
14213 If you are a Guix developer, or if you are taking care of this build farm,
14214 you'll probably want to have a closer look at these packages: they may simply
14217 @item --display-missing
14218 Display the list of store items for which substitutes are missing.
14221 @node Invoking guix processes
14222 @section Invoking @command{guix processes}
14224 The @command{guix processes} command can be useful to developers and system
14225 administrators, especially on multi-user machines and on build farms: it lists
14226 the current sessions (connections to the daemon), as well as information about
14227 the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
14228 started with @option{--listen} specifying a TCP endpoint, are @emph{not}
14229 listed.}. Here's an example of the information it returns:
14232 $ sudo guix processes
14235 ClientCommand: guix shell python
14239 ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
14243 ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
14244 LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
14245 LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
14246 LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
14248 ChildCommand: guix offload x86_64-linux 7200 1 28800
14250 ChildCommand: guix offload x86_64-linux 7200 1 28800
14252 ChildCommand: guix offload x86_64-linux 7200 1 28800
14255 In this example we see that @command{guix-daemon} has three clients:
14256 @command{guix environment}, @command{guix publish}, and the Cuirass continuous
14257 integration tool; their process identifier (PID) is given by the
14258 @code{ClientPID} field. The @code{SessionPID} field gives the PID of the
14259 @command{guix-daemon} sub-process of this particular session.
14261 The @code{LockHeld} fields show which store items are currently locked
14262 by this session, which corresponds to store items being built or
14263 substituted (the @code{LockHeld} field is not displayed when
14264 @command{guix processes} is not running as root). Last, by looking at
14265 the @code{ChildPID} and @code{ChildCommand} fields, we understand that
14266 these three builds are being offloaded (@pxref{Daemon Offload Setup}).
14268 The output is in Recutils format so we can use the handy @command{recsel}
14269 command to select sessions of interest (@pxref{Selection Expressions,,,
14270 recutils, GNU recutils manual}). As an example, the command shows the command
14271 line and PID of the client that triggered the build of a Perl package:
14274 $ sudo guix processes | \
14275 recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
14277 ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
14280 Additional options are listed below.
14283 @item --format=@var{format}
14284 @itemx -f @var{format}
14285 Produce output in the specified @var{format}, one of:
14289 The default option. It outputs a set of Session recutils records
14290 that include each @code{ChildProcess} as a field.
14293 Normalize the output records into record sets (@pxref{Record Sets,,,
14294 recutils, GNU recutils manual}). Normalizing into record sets allows
14295 joins across record types. The example below lists the PID of each
14296 @code{ChildProcess} and the associated PID for @code{Session} that
14297 spawned the @code{ChildProcess} where the @code{Session} was started
14298 using @command{guix build}.
14301 $ guix processes --format=normalized | \
14305 -p Session.PID,PID \
14306 -e 'Session.ClientCommand ~ "guix build"'
14319 @node System Configuration
14320 @chapter System Configuration
14322 @cindex system configuration
14323 Guix System supports a consistent whole-system configuration
14324 mechanism. By that we mean that all aspects of the global system
14325 configuration---such as the available system services, timezone and
14326 locale settings, user accounts---are declared in a single place. Such
14327 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
14329 One of the advantages of putting all the system configuration under the
14330 control of Guix is that it supports transactional system upgrades, and
14331 makes it possible to roll back to a previous system instantiation,
14332 should something go wrong with the new one (@pxref{Features}). Another
14333 advantage is that it makes it easy to replicate the exact same configuration
14334 across different machines, or at different points in time, without
14335 having to resort to additional administration tools layered on top of
14336 the own tools of the system.
14337 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
14339 This section describes this mechanism. First we focus on the system
14340 administrator's viewpoint---explaining how the system is configured and
14341 instantiated. Then we show how this mechanism can be extended, for
14342 instance to support new system services.
14345 * Using the Configuration System:: Customizing your GNU system.
14346 * operating-system Reference:: Detail of operating-system declarations.
14347 * File Systems:: Configuring file system mounts.
14348 * Mapped Devices:: Block device extra processing.
14349 * Swap Space:: Backing RAM with disk space.
14350 * User Accounts:: Specifying user accounts.
14351 * Keyboard Layout:: How the system interprets key strokes.
14352 * Locales:: Language and cultural convention settings.
14353 * Services:: Specifying system services.
14354 * Setuid Programs:: Programs running with root privileges.
14355 * X.509 Certificates:: Authenticating HTTPS servers.
14356 * Name Service Switch:: Configuring libc's name service switch.
14357 * Initial RAM Disk:: Linux-Libre bootstrapping.
14358 * Bootloader Configuration:: Configuring the boot loader.
14359 * Invoking guix system:: Instantiating a system configuration.
14360 * Invoking guix deploy:: Deploying a system configuration to a remote host.
14361 * Running Guix in a VM:: How to run Guix System in a virtual machine.
14362 * Defining Services:: Adding new service definitions.
14365 @node Using the Configuration System
14366 @section Using the Configuration System
14368 The operating system is configured by providing an
14369 @code{operating-system} declaration in a file that can then be passed to
14370 the @command{guix system} command (@pxref{Invoking guix system}). A
14371 simple setup, with the default system services, the default Linux-Libre
14372 kernel, initial RAM disk, and boot loader looks like this:
14374 @findex operating-system
14376 @include os-config-bare-bones.texi
14379 This example should be self-describing. Some of the fields defined
14380 above, such as @code{host-name} and @code{bootloader}, are mandatory.
14381 Others, such as @code{packages} and @code{services}, can be omitted, in
14382 which case they get a default value.
14384 Below we discuss the effect of some of the most important fields
14385 (@pxref{operating-system Reference}, for details about all the available
14386 fields), and how to @dfn{instantiate} the operating system using
14387 @command{guix system}.
14389 @unnumberedsubsec Bootloader
14391 @cindex legacy boot, on Intel machines
14392 @cindex BIOS boot, on Intel machines
14395 The @code{bootloader} field describes the method that will be used to boot
14396 your system. Machines based on Intel processors can boot in ``legacy'' BIOS
14397 mode, as in the example above. However, more recent machines rely instead on
14398 the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case,
14399 the @code{bootloader} field should contain something along these lines:
14402 (bootloader-configuration
14403 (bootloader grub-efi-bootloader)
14404 (targets '("/boot/efi")))
14407 @xref{Bootloader Configuration}, for more information on the available
14408 configuration options.
14410 @unnumberedsubsec Globally-Visible Packages
14412 @vindex %base-packages
14413 The @code{packages} field lists packages that will be globally visible
14414 on the system, for all user accounts---i.e., in every user's @env{PATH}
14415 environment variable---in addition to the per-user profiles
14416 (@pxref{Invoking guix package}). The @code{%base-packages} variable
14417 provides all the tools one would expect for basic user and administrator
14418 tasks---including the GNU Core Utilities, the GNU Networking Utilities,
14419 the @command{mg} lightweight text editor, @command{find}, @command{grep},
14420 etc. The example above adds GNU@tie{}Screen to those,
14421 taken from the @code{(gnu packages screen)}
14422 module (@pxref{Package Modules}). The
14423 @code{(list package output)} syntax can be used to add a specific output
14427 (use-modules (gnu packages))
14428 (use-modules (gnu packages dns))
14432 (packages (cons (list isc-bind "utils")
14436 @findex specification->package
14437 Referring to packages by variable name, like @code{isc-bind} above, has
14438 the advantage of being unambiguous; it also allows typos and such to be
14439 diagnosed right away as ``unbound variables''. The downside is that one
14440 needs to know which module defines which package, and to augment the
14441 @code{use-package-modules} line accordingly. To avoid that, one can use
14442 the @code{specification->package} procedure of the @code{(gnu packages)}
14443 module, which returns the best package for a given name or name and
14447 (use-modules (gnu packages))
14451 (packages (append (map specification->package
14452 '("tcpdump" "htop" "gnupg@@2.0"))
14456 @unnumberedsubsec System Services
14459 @vindex %base-services
14460 The @code{services} field lists @dfn{system services} to be made
14461 available when the system starts (@pxref{Services}).
14462 The @code{operating-system} declaration above specifies that, in
14463 addition to the basic services, we want the OpenSSH secure shell
14464 daemon listening on port 2222 (@pxref{Networking Services,
14465 @code{openssh-service-type}}). Under the hood,
14466 @code{openssh-service-type} arranges so that @command{sshd} is started with the
14467 right command-line options, possibly with supporting configuration files
14468 generated as needed (@pxref{Defining Services}).
14470 @cindex customization, of services
14471 @findex modify-services
14472 Occasionally, instead of using the base services as is, you will want to
14473 customize them. To do this, use @code{modify-services} (@pxref{Service
14474 Reference, @code{modify-services}}) to modify the list.
14476 @anchor{auto-login to TTY} For example, suppose you want to modify
14477 @code{guix-daemon} and Mingetty (the console log-in) in the
14478 @code{%base-services} list (@pxref{Base Services,
14479 @code{%base-services}}). To do that, you can write the following in
14480 your operating system declaration:
14483 (define %my-services
14484 ;; My very own list of services.
14485 (modify-services %base-services
14486 (guix-service-type config =>
14487 (guix-configuration
14489 ;; Fetch substitutes from example.org.
14491 (list "https://example.org/guix"
14492 "https://ci.guix.gnu.org"))))
14493 (mingetty-service-type config =>
14494 (mingetty-configuration
14496 ;; Automatially log in as "guest".
14497 (auto-login "guest")))))
14501 (services %my-services))
14504 This changes the configuration---i.e., the service parameters---of the
14505 @code{guix-service-type} instance, and that of all the
14506 @code{mingetty-service-type} instances in the @code{%base-services} list
14507 (@pxref{Auto-Login to a Specific TTY, see the cookbook for how to
14508 auto-login one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})).
14509 Observe how this is accomplished: first, we arrange for the original
14510 configuration to be bound to the identifier @code{config} in the
14511 @var{body}, and then we write the @var{body} so that it evaluates to the
14512 desired configuration. In particular, notice how we use @code{inherit}
14513 to create a new configuration which has the same values as the old
14514 configuration, but with a few modifications.
14516 @cindex encrypted disk
14517 The configuration for a typical ``desktop'' usage, with an encrypted
14518 root partition, a swap file on the root partition, the X11 display
14519 server, GNOME and Xfce (users can choose which of these desktop
14520 environments to use at the log-in screen by pressing @kbd{F1}), network
14521 management, power management, and more, would look like this:
14524 @include os-config-desktop.texi
14527 A graphical system with a choice of lightweight window managers
14528 instead of full-blown desktop environments would look like this:
14531 @include os-config-lightweight-desktop.texi
14534 This example refers to the @file{/boot/efi} file system by its UUID,
14535 @code{1234-ABCD}. Replace this UUID with the right UUID on your system,
14536 as returned by the @command{blkid} command.
14538 @xref{Desktop Services}, for the exact list of services provided by
14539 @code{%desktop-services}. @xref{X.509 Certificates}, for background
14540 information about the @code{nss-certs} package that is used here.
14542 Again, @code{%desktop-services} is just a list of service objects. If
14543 you want to remove services from there, you can do so using the
14544 procedures for list filtering (@pxref{SRFI-1 Filtering and
14545 Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the
14546 following expression returns a list that contains all the services in
14547 @code{%desktop-services} minus the Avahi service:
14550 (remove (lambda (service)
14551 (eq? (service-kind service) avahi-service-type))
14555 Alternatively, the @code{modify-services} macro can be used:
14558 (modify-services %desktop-services
14559 (delete avahi-service-type))
14563 @unnumberedsubsec Instantiating the System
14565 Assuming the @code{operating-system} declaration
14566 is stored in the @file{my-system-config.scm}
14567 file, the @command{guix system reconfigure my-system-config.scm} command
14568 instantiates that configuration, and makes it the default GRUB boot
14569 entry (@pxref{Invoking guix system}).
14571 The normal way to change the system configuration is by updating this
14572 file and re-running @command{guix system reconfigure}. One should never
14573 have to touch files in @file{/etc} or to run commands that modify the
14574 system state such as @command{useradd} or @command{grub-install}. In
14575 fact, you must avoid that since that would not only void your warranty
14576 but also prevent you from rolling back to previous versions of your
14577 system, should you ever need to.
14579 @cindex roll-back, of the operating system
14580 Speaking of roll-back, each time you run @command{guix system
14581 reconfigure}, a new @dfn{generation} of the system is created---without
14582 modifying or deleting previous generations. Old system generations get
14583 an entry in the bootloader boot menu, allowing you to boot them in case
14584 something went wrong with the latest generation. Reassuring, no? The
14585 @command{guix system list-generations} command lists the system
14586 generations available on disk. It is also possible to roll back the
14587 system via the commands @command{guix system roll-back} and
14588 @command{guix system switch-generation}.
14590 Although the @command{guix system reconfigure} command will not modify
14591 previous generations, you must take care when the current generation is not
14592 the latest (e.g., after invoking @command{guix system roll-back}), since
14593 the operation might overwrite a later generation (@pxref{Invoking guix
14596 @unnumberedsubsec The Programming Interface
14598 At the Scheme level, the bulk of an @code{operating-system} declaration
14599 is instantiated with the following monadic procedure (@pxref{The Store
14602 @deffn {Monadic Procedure} operating-system-derivation os
14603 Return a derivation that builds @var{os}, an @code{operating-system}
14604 object (@pxref{Derivations}).
14606 The output of the derivation is a single directory that refers to all
14607 the packages, configuration files, and other supporting files needed to
14608 instantiate @var{os}.
14611 This procedure is provided by the @code{(gnu system)} module. Along
14612 with @code{(gnu services)} (@pxref{Services}), this module contains the
14613 guts of Guix System. Make sure to visit it!
14616 @node operating-system Reference
14617 @section @code{operating-system} Reference
14619 This section summarizes all the options available in
14620 @code{operating-system} declarations (@pxref{Using the Configuration
14623 @deftp {Data Type} operating-system
14624 This is the data type representing an operating system configuration.
14625 By that, we mean all the global system configuration, not per-user
14626 configuration (@pxref{Using the Configuration System}).
14629 @item @code{kernel} (default: @code{linux-libre})
14630 The package object of the operating system kernel to
14631 use@footnote{Currently only the Linux-libre kernel is fully supported.
14632 Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only
14633 available when building a virtual machine disk image.}.
14636 @item @code{hurd} (default: @code{#f})
14637 The package object of the Hurd to be started by the kernel. When this
14638 field is set, produce a GNU/Hurd operating system. In that case,
14639 @code{kernel} must also be set to the @code{gnumach} package---the
14640 microkernel the Hurd runs on.
14643 This feature is experimental and only supported for disk images.
14646 @item @code{kernel-loadable-modules} (default: '())
14647 A list of objects (usually packages) to collect loadable kernel modules
14648 from--e.g. @code{(list ddcci-driver-linux)}.
14650 @item @code{kernel-arguments} (default: @code{%default-kernel-arguments})
14651 List of strings or gexps representing additional arguments to pass on
14652 the command-line of the kernel---e.g., @code{("console=ttyS0")}.
14654 @item @code{bootloader}
14655 The system bootloader configuration object. @xref{Bootloader Configuration}.
14658 This is the label (a string) as it appears in the bootloader's menu entry.
14659 The default label includes the kernel name and version.
14661 @item @code{keyboard-layout} (default: @code{#f})
14662 This field specifies the keyboard layout to use in the console. It can be
14663 either @code{#f}, in which case the default keyboard layout is used (usually
14664 US English), or a @code{<keyboard-layout>} record. @xref{Keyboard Layout},
14665 for more information.
14667 This keyboard layout is in effect as soon as the kernel has booted. For
14668 instance, it is the keyboard layout in effect when you type a passphrase if
14669 your root file system is on a @code{luks-device-mapping} mapped device
14670 (@pxref{Mapped Devices}).
14673 This does @emph{not} specify the keyboard layout used by the bootloader, nor
14674 that used by the graphical display server. @xref{Bootloader Configuration},
14675 for information on how to specify the bootloader's keyboard layout. @xref{X
14676 Window}, for information on how to specify the keyboard layout used by the X
14680 @item @code{initrd-modules} (default: @code{%base-initrd-modules})
14682 @cindex initial RAM disk
14683 The list of Linux kernel modules that need to be available in the
14684 initial RAM disk. @xref{Initial RAM Disk}.
14686 @item @code{initrd} (default: @code{base-initrd})
14687 A procedure that returns an initial RAM disk for the Linux
14688 kernel. This field is provided to support low-level customization and
14689 should rarely be needed for casual use. @xref{Initial RAM Disk}.
14691 @item @code{firmware} (default: @code{%base-firmware})
14693 List of firmware packages loadable by the operating system kernel.
14695 The default includes firmware needed for Atheros- and Broadcom-based
14696 WiFi devices (Linux-libre modules @code{ath9k} and @code{b43-open},
14697 respectively). @xref{Hardware Considerations}, for more info on
14698 supported hardware.
14700 @item @code{host-name}
14703 @item @code{hosts-file}
14705 A file-like object (@pxref{G-Expressions, file-like objects}) for use as
14706 @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
14707 Reference Manual}). The default is a file with entries for
14708 @code{localhost} and @var{host-name}.
14710 @item @code{mapped-devices} (default: @code{'()})
14711 A list of mapped devices. @xref{Mapped Devices}.
14713 @item @code{file-systems}
14714 A list of file systems. @xref{File Systems}.
14716 @item @code{swap-devices} (default: @code{'()})
14717 @cindex swap devices
14718 A list of swap spaces. @xref{Swap Space}.
14720 @item @code{users} (default: @code{%base-user-accounts})
14721 @itemx @code{groups} (default: @code{%base-groups})
14722 List of user accounts and groups. @xref{User Accounts}.
14724 If the @code{users} list lacks a user account with UID@tie{}0, a
14725 ``root'' account with UID@tie{}0 is automatically added.
14727 @item @code{skeletons} (default: @code{(default-skeletons)})
14728 A list of target file name/file-like object tuples (@pxref{G-Expressions,
14729 file-like objects}). These are the skeleton files that will be added to
14730 the home directory of newly-created user accounts.
14732 For instance, a valid value may look like this:
14735 `((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
14736 (".guile" ,(plain-file "guile"
14737 "(use-modules (ice-9 readline))
14738 (activate-readline)")))
14741 @item @code{issue} (default: @code{%default-issue})
14742 A string denoting the contents of the @file{/etc/issue} file, which is
14743 displayed when users log in on a text console.
14745 @item @code{packages} (default: @code{%base-packages})
14746 A list of packages to be installed in the global profile, which is accessible
14747 at @file{/run/current-system/profile}. Each element is either a package
14748 variable or a package/output tuple. Here's a simple example of both:
14751 (cons* git ; the default "out" output
14752 (list git "send-email") ; another output of git
14753 %base-packages) ; the default set
14756 The default set includes core utilities and it is good practice to
14757 install non-core utilities in user profiles (@pxref{Invoking guix
14760 @item @code{timezone}
14761 A timezone identifying string---e.g., @code{"Europe/Paris"}.
14763 You can run the @command{tzselect} command to find out which timezone
14764 string corresponds to your region. Choosing an invalid timezone name
14765 causes @command{guix system} to fail.
14767 @item @code{locale} (default: @code{"en_US.utf8"})
14768 The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
14769 Library Reference Manual}). @xref{Locales}, for more information.
14771 @item @code{locale-definitions} (default: @code{%default-locale-definitions})
14772 The list of locale definitions to be compiled and that may be used at
14773 run time. @xref{Locales}.
14775 @item @code{locale-libcs} (default: @code{(list @var{glibc})})
14776 The list of GNU@tie{}libc packages whose locale data and tools are used
14777 to build the locale definitions. @xref{Locales}, for compatibility
14778 considerations that justify this option.
14780 @item @code{name-service-switch} (default: @code{%default-nss})
14781 Configuration of the libc name service switch (NSS)---a
14782 @code{<name-service-switch>} object. @xref{Name Service Switch}, for
14785 @item @code{services} (default: @code{%base-services})
14786 A list of service objects denoting system services. @xref{Services}.
14788 @cindex essential services
14789 @item @code{essential-services} (default: ...)
14790 The list of ``essential services''---i.e., things like instances of
14791 @code{system-service-type} and @code{host-name-service-type} (@pxref{Service
14792 Reference}), which are derived from the operating system definition itself.
14793 As a user you should @emph{never} need to touch this field.
14795 @item @code{pam-services} (default: @code{(base-pam-services)})
14797 @cindex pluggable authentication modules
14798 Linux @dfn{pluggable authentication module} (PAM) services.
14799 @c FIXME: Add xref to PAM services section.
14801 @item @code{setuid-programs} (default: @code{%setuid-programs})
14802 List of @code{<setuid-program>}. @xref{Setuid Programs}, for more
14805 @item @code{sudoers-file} (default: @code{%sudoers-specification})
14806 @cindex sudoers file
14807 The contents of the @file{/etc/sudoers} file as a file-like object
14808 (@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
14810 This file specifies which users can use the @command{sudo} command, what
14811 they are allowed to do, and what privileges they may gain. The default
14812 is that only @code{root} and members of the @code{wheel} group may use
14817 @deffn {Scheme Syntax} this-operating-system
14818 When used in the @emph{lexical scope} of an operating system field definition,
14819 this identifier resolves to the operating system being defined.
14821 The example below shows how to refer to the operating system being defined in
14822 the definition of the @code{label} field:
14825 (use-modules (gnu) (guix))
14829 (label (package-full-name
14830 (operating-system-kernel this-operating-system))))
14833 It is an error to refer to @code{this-operating-system} outside an operating
14840 @section File Systems
14842 The list of file systems to be mounted is specified in the
14843 @code{file-systems} field of the operating system declaration
14844 (@pxref{Using the Configuration System}). Each file system is declared
14845 using the @code{file-system} form, like this:
14849 (mount-point "/home")
14850 (device "/dev/sda3")
14854 As usual, some of the fields are mandatory---those shown in the example
14855 above---while others can be omitted. These are described below.
14857 @deftp {Data Type} file-system
14858 Objects of this type represent file systems to be mounted. They
14859 contain the following members:
14863 This is a string specifying the type of the file system---e.g.,
14866 @item @code{mount-point}
14867 This designates the place where the file system is to be mounted.
14869 @item @code{device}
14870 This names the ``source'' of the file system. It can be one of three
14871 things: a file system label, a file system UUID, or the name of a
14872 @file{/dev} node. Labels and UUIDs offer a way to refer to file
14873 systems without having to hard-code their actual device
14874 name@footnote{Note that, while it is tempting to use
14875 @file{/dev/disk/by-uuid} and similar device names to achieve the same
14876 result, this is not recommended: These special device nodes are created
14877 by the udev daemon and may be unavailable at the time the device is
14880 @findex file-system-label
14881 File system labels are created using the @code{file-system-label}
14882 procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
14883 plain strings. Here's an example of a file system referred to by its
14884 label, as shown by the @command{e2label} command:
14888 (mount-point "/home")
14890 (device (file-system-label "my-home")))
14894 UUIDs are converted from their string representation (as shown by the
14895 @command{tune2fs -l} command) using the @code{uuid} form@footnote{The
14896 @code{uuid} form expects 16-byte UUIDs as defined in
14897 @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
14898 form of UUID used by the ext2 family of file systems and others, but it
14899 is different from ``UUIDs'' found in FAT file systems, for instance.},
14904 (mount-point "/home")
14906 (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
14909 When the source of a file system is a mapped device (@pxref{Mapped
14910 Devices}), its @code{device} field @emph{must} refer to the mapped
14911 device name---e.g., @file{"/dev/mapper/root-partition"}.
14912 This is required so that
14913 the system knows that mounting the file system depends on having the
14914 corresponding device mapping established.
14916 @item @code{flags} (default: @code{'()})
14917 This is a list of symbols denoting mount flags. Recognized flags
14918 include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
14919 access to special files), @code{no-suid} (ignore setuid and setgid
14920 bits), @code{no-atime} (do not update file access times),
14921 @code{strict-atime} (update file access time), @code{lazy-time} (only
14922 update time on the in-memory version of the file inode), and
14923 @code{no-exec} (disallow program execution).
14924 @xref{Mount-Unmount-Remount,,, libc, The GNU C Library Reference
14925 Manual}, for more information on these flags.
14927 @item @code{options} (default: @code{#f})
14928 This is either @code{#f}, or a string denoting mount options passed to
14929 the file system driver. @xref{Mount-Unmount-Remount,,, libc, The GNU C
14930 Library Reference Manual}, for details and run @command{man 8 mount} for
14931 options for various file systems. Note that the
14932 @code{file-system-options->alist} and @code{alist->file-system-options}
14933 procedures from @code{(gnu system file-systems)} can be used to convert
14934 file system options given as an association list to the string
14935 representation, and vice-versa.
14937 @item @code{mount?} (default: @code{#t})
14938 This value indicates whether to automatically mount the file system when
14939 the system is brought up. When set to @code{#f}, the file system gets
14940 an entry in @file{/etc/fstab} (read by the @command{mount} command) but
14941 is not automatically mounted.
14943 @item @code{needed-for-boot?} (default: @code{#f})
14944 This Boolean value indicates whether the file system is needed when
14945 booting. If that is true, then the file system is mounted when the
14946 initial RAM disk (initrd) is loaded. This is always the case, for
14947 instance, for the root file system.
14949 @item @code{check?} (default: @code{#t})
14950 This Boolean indicates whether the file system should be checked for
14951 errors before being mounted. How and when this happens can be further
14952 adjusted with the following options.
14954 @item @code{skip-check-if-clean?} (default: @code{#t})
14955 When true, this Boolean indicates that a file system check triggered
14956 by @code{check?} may exit early if the file system is marked as
14957 ``clean'', meaning that it was previously correctly unmounted and
14958 should not contain errors.
14960 Setting this to false will always force a full consistency check when
14961 @code{check?} is true. This may take a very long time and is not
14962 recommended on healthy systems---in fact, it may reduce reliability!
14964 Conversely, some primitive file systems like @code{fat} do not keep
14965 track of clean shutdowns and will perform a full scan regardless of the
14966 value of this option.
14968 @item @code{repair} (default: @code{'preen})
14969 When @code{check?} finds errors, it can (try to) repair them and
14970 continue booting. This option controls when and how to do so.
14972 If false, try not to modify the file system at all. Checking certain
14973 file systems like @code{jfs} may still write to the device to replay
14974 the journal. No repairs will be attempted.
14976 If @code{#t}, try to repair any errors found and assume ``yes'' to
14977 all questions. This will fix the most errors, but may be risky.
14979 If @code{'preen}, repair only errors that are safe to fix without
14980 human interaction. What that means is left up to the developers of
14981 each file system and may be equivalent to ``none'' or ``all''.
14983 @item @code{create-mount-point?} (default: @code{#f})
14984 When true, the mount point is created if it does not exist yet.
14986 @item @code{mount-may-fail?} (default: @code{#f})
14987 When true, this indicates that mounting this file system can fail but
14988 that should not be considered an error. This is useful in unusual
14989 cases; an example of this is @code{efivarfs}, a file system that can
14990 only be mounted on EFI/UEFI systems.
14992 @item @code{dependencies} (default: @code{'()})
14993 This is a list of @code{<file-system>} or @code{<mapped-device>} objects
14994 representing file systems that must be mounted or mapped devices that
14995 must be opened before (and unmounted or closed after) this one.
14997 As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
14998 a dependency of @file{/sys/fs/cgroup/cpu} and
14999 @file{/sys/fs/cgroup/memory}.
15001 Another example is a file system that depends on a mapped device, for
15002 example for an encrypted partition (@pxref{Mapped Devices}).
15006 @deffn {Scheme Procedure} file-system-label @var{str}
15007 This procedure returns an opaque file system label from @var{str}, a
15011 (file-system-label "home")
15012 @result{} #<file-system-label "home">
15015 File system labels are used to refer to file systems by label rather
15016 than by device name. See above for examples.
15019 The @code{(gnu system file-systems)} exports the following useful
15022 @defvr {Scheme Variable} %base-file-systems
15023 These are essential file systems that are required on normal systems,
15024 such as @code{%pseudo-terminal-file-system} and @code{%immutable-store} (see
15025 below). Operating system declarations should always contain at least
15029 @defvr {Scheme Variable} %pseudo-terminal-file-system
15030 This is the file system to be mounted as @file{/dev/pts}. It supports
15031 @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
15032 functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
15033 Manual}). Pseudo-terminals are used by terminal emulators such as
15037 @defvr {Scheme Variable} %shared-memory-file-system
15038 This file system is mounted as @file{/dev/shm} and is used to support
15039 memory sharing across processes (@pxref{Memory-mapped I/O,
15040 @code{shm_open},, libc, The GNU C Library Reference Manual}).
15043 @defvr {Scheme Variable} %immutable-store
15044 This file system performs a read-only ``bind mount'' of
15045 @file{/gnu/store}, making it read-only for all the users including
15046 @code{root}. This prevents against accidental modification by software
15047 running as @code{root} or by system administrators.
15049 The daemon itself is still able to write to the store: it remounts it
15050 read-write in its own ``name space.''
15053 @defvr {Scheme Variable} %binary-format-file-system
15054 The @code{binfmt_misc} file system, which allows handling of arbitrary
15055 executable file types to be delegated to user space. This requires the
15056 @code{binfmt.ko} kernel module to be loaded.
15059 @defvr {Scheme Variable} %fuse-control-file-system
15060 The @code{fusectl} file system, which allows unprivileged users to mount
15061 and unmount user-space FUSE file systems. This requires the
15062 @code{fuse.ko} kernel module to be loaded.
15065 The @code{(gnu system uuid)} module provides tools to deal with file
15066 system ``unique identifiers'' (UUIDs).
15068 @deffn {Scheme Procedure} uuid @var{str} [@var{type}]
15069 Return an opaque UUID (unique identifier) object of the given @var{type}
15070 (a symbol) by parsing @var{str} (a string):
15073 (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")
15074 @result{} #<<uuid> type: dce bv: @dots{}>
15076 (uuid "1234-ABCD" 'fat)
15077 @result{} #<<uuid> type: fat bv: @dots{}>
15080 @var{type} may be one of @code{dce}, @code{iso9660}, @code{fat},
15081 @code{ntfs}, or one of the commonly found synonyms for these.
15083 UUIDs are another way to unambiguously refer to file systems in
15084 operating system configuration. See the examples above.
15088 @node Btrfs file system
15089 @subsection Btrfs file system
15091 The Btrfs has special features, such as subvolumes, that merit being
15092 explained in more details. The following section attempts to cover
15093 basic as well as complex uses of a Btrfs file system with the Guix
15096 In its simplest usage, a Btrfs file system can be described, for
15101 (mount-point "/home")
15103 (device (file-system-label "my-home")))
15106 The example below is more complex, as it makes use of a Btrfs
15107 subvolume, named @code{rootfs}. The parent Btrfs file system is labeled
15108 @code{my-btrfs-pool}, and is located on an encrypted device (hence the
15109 dependency on @code{mapped-devices}):
15113 (device (file-system-label "my-btrfs-pool"))
15116 (options "subvol=rootfs")
15117 (dependencies mapped-devices))
15120 Some bootloaders, for example GRUB, only mount a Btrfs partition at its
15121 top level during the early boot, and rely on their configuration to
15122 refer to the correct subvolume path within that top level. The
15123 bootloaders operating in this way typically produce their configuration
15124 on a running system where the Btrfs partitions are already mounted and
15125 where the subvolume information is readily available. As an example,
15126 @command{grub-mkconfig}, the configuration generator command shipped
15127 with GRUB, reads @file{/proc/self/mountinfo} to determine the top-level
15128 path of a subvolume.
15130 The Guix System produces a bootloader configuration using the operating
15131 system configuration as its sole input; it is therefore necessary to
15132 extract the subvolume name on which @file{/gnu/store} lives (if any)
15133 from that operating system configuration. To better illustrate,
15134 consider a subvolume named 'rootfs' which contains the root file system
15135 data. In such situation, the GRUB bootloader would only see the top
15136 level of the root Btrfs partition, e.g.:
15140 ├── rootfs (subvolume directory)
15141 ├── gnu (normal directory)
15142 ├── store (normal directory)
15146 Thus, the subvolume name must be prepended to the @file{/gnu/store} path
15147 of the kernel, initrd binaries and any other files referred to in the
15148 GRUB configuration that must be found during the early boot.
15150 The next example shows a nested hierarchy of subvolumes and
15155 ├── rootfs (subvolume)
15156 ├── gnu (normal directory)
15157 ├── store (subvolume)
15161 This scenario would work without mounting the 'store' subvolume.
15162 Mounting 'rootfs' is sufficient, since the subvolume name matches its
15163 intended mount point in the file system hierarchy. Alternatively, the
15164 'store' subvolume could be referred to by setting the @code{subvol}
15165 option to either @code{/rootfs/gnu/store} or @code{rootfs/gnu/store}.
15167 Finally, a more contrived example of nested subvolumes:
15171 ├── root-snapshots (subvolume)
15172 ├── root-current (subvolume)
15173 ├── guix-store (subvolume)
15177 Here, the 'guix-store' subvolume doesn't match its intended mount point,
15178 so it is necessary to mount it. The subvolume must be fully specified,
15179 by passing its file name to the @code{subvol} option. To illustrate,
15180 the 'guix-store' subvolume could be mounted on @file{/gnu/store} by using
15181 a file system declaration such as:
15185 (device (file-system-label "btrfs-pool-1"))
15186 (mount-point "/gnu/store")
15188 (options "subvol=root-snapshots/root-current/guix-store,\
15189 compress-force=zstd,space_cache=v2"))
15192 @node Mapped Devices
15193 @section Mapped Devices
15195 @cindex device mapping
15196 @cindex mapped devices
15197 The Linux kernel has a notion of @dfn{device mapping}: a block device,
15198 such as a hard disk partition, can be @dfn{mapped} into another device,
15199 usually in @code{/dev/mapper/},
15200 with additional processing over the data that flows through
15201 it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
15202 concept of a ``mapped device'' and that of a file system: both boil down
15203 to @emph{translating} input/output operations made on a file to
15204 operations on its backing store. Thus, the Hurd implements mapped
15205 devices, like file systems, using the generic @dfn{translator} mechanism
15206 (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
15207 typical example is encryption device mapping: all writes to the mapped
15208 device are encrypted, and all reads are deciphered, transparently.
15209 Guix extends this notion by considering any device or set of devices that
15210 are @dfn{transformed} in some way to create a new device; for instance,
15211 RAID devices are obtained by @dfn{assembling} several other devices, such
15212 as hard disks or partitions, into a new one that behaves as one partition.
15214 Mapped devices are declared using the @code{mapped-device} form,
15215 defined as follows; for examples, see below.
15217 @deftp {Data Type} mapped-device
15218 Objects of this type represent device mappings that will be made when
15219 the system boots up.
15223 This is either a string specifying the name of the block device to be mapped,
15224 such as @code{"/dev/sda3"}, or a list of such strings when several devices
15225 need to be assembled for creating a new one. In case of LVM this is a
15226 string specifying name of the volume group to be mapped.
15229 This string specifies the name of the resulting mapped device. For
15230 kernel mappers such as encrypted devices of type @code{luks-device-mapping},
15231 specifying @code{"my-partition"} leads to the creation of
15232 the @code{"/dev/mapper/my-partition"} device.
15233 For RAID devices of type @code{raid-device-mapping}, the full device name
15234 such as @code{"/dev/md0"} needs to be given.
15235 LVM logical volumes of type @code{lvm-device-mapping} need to
15236 be specified as @code{"VGNAME-LVNAME"}.
15239 This list of strings specifies names of the resulting mapped devices in case
15240 there are several. The format is identical to @var{target}.
15243 This must be a @code{mapped-device-kind} object, which specifies how
15244 @var{source} is mapped to @var{target}.
15248 @defvr {Scheme Variable} luks-device-mapping
15249 This defines LUKS block device encryption using the @command{cryptsetup}
15250 command from the package with the same name. It relies on the
15251 @code{dm-crypt} Linux kernel module.
15254 @defvr {Scheme Variable} raid-device-mapping
15255 This defines a RAID device, which is assembled using the @code{mdadm}
15256 command from the package with the same name. It requires a Linux kernel
15257 module for the appropriate RAID level to be loaded, such as @code{raid456}
15258 for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
15261 @cindex LVM, logical volume manager
15262 @defvr {Scheme Variable} lvm-device-mapping
15263 This defines one or more logical volumes for the Linux
15264 @uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.
15265 The volume group is activated by the @command{vgchange} command from the
15266 @code{lvm2} package.
15269 @cindex disk encryption
15271 The following example specifies a mapping from @file{/dev/sda3} to
15272 @file{/dev/mapper/home} using LUKS---the
15273 @url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a
15274 standard mechanism for disk encryption.
15275 The @file{/dev/mapper/home}
15276 device can then be used as the @code{device} of a @code{file-system}
15277 declaration (@pxref{File Systems}).
15281 (source "/dev/sda3")
15283 (type luks-device-mapping))
15286 Alternatively, to become independent of device numbering, one may obtain
15287 the LUKS UUID (@dfn{unique identifier}) of the source device by a
15291 cryptsetup luksUUID /dev/sda3
15294 and use it as follows:
15298 (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
15300 (type luks-device-mapping))
15303 @cindex swap encryption
15304 It is also desirable to encrypt swap space, since swap space may contain
15305 sensitive data. One way to accomplish that is to use a swap file in a
15306 file system on a device mapped via LUKS encryption. In this way, the
15307 swap file is encrypted because the entire device is encrypted.
15308 @xref{Swap Space}, or @xref{Preparing for Installation,,Disk
15309 Partitioning}, for an example.
15311 A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
15312 may be declared as follows:
15316 (source (list "/dev/sda1" "/dev/sdb1"))
15317 (target "/dev/md0")
15318 (type raid-device-mapping))
15321 The @file{/dev/md0} device can then be used as the @code{device} of a
15322 @code{file-system} declaration (@pxref{File Systems}).
15323 Note that the RAID level need not be given; it is chosen during the
15324 initial creation and formatting of the RAID device and is determined
15325 automatically later.
15327 LVM logical volumes ``alpha'' and ``beta'' from volume group ``vg0'' can
15328 be declared as follows:
15333 (targets (list "vg0-alpha" "vg0-beta"))
15334 (type lvm-device-mapping))
15337 Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can
15338 then be used as the @code{device} of a @code{file-system} declaration
15339 (@pxref{File Systems}).
15342 @section Swap Space
15345 Swap space, as it is commonly called, is a disk area specifically
15346 designated for paging: the process in charge of memory management
15347 (the Linux kernel or Hurd's default pager) can decide that some memory
15348 pages stored in RAM which belong to a running program but are unused
15349 should be stored on disk instead. It unloads those from the RAM,
15350 freeing up precious fast memory, and writes them to the swap space. If
15351 the program tries to access that very page, the memory management
15352 process loads it back into memory for the program to use.
15354 A common misconception about swap is that it is only useful when small
15355 amounts of RAM are available to the system. However, it should be noted
15356 that kernels often use all available RAM for disk access caching to make
15357 I/O faster, and thus paging out unused portions of program memory will
15358 expand the RAM available for such caching.
15360 For a more detailed description of how memory is managed from the
15361 viewpoint of a monolithic kernel, @xref{Memory
15362 Concepts,,, libc, The GNU C Library Reference Manual}.
15364 The Linux kernel has support for swap partitions and swap files: the
15365 former uses a whole disk partition for paging, whereas the second uses a
15366 file on a file system for that (the file system driver needs to support
15367 it). On a comparable setup, both have the same performance, so one
15368 should consider ease of use when deciding between them. Partitions are
15369 ``simpler'' and do not need file system support, but need to be
15370 allocated at disk formatting time (logical volumes notwithstanding),
15371 whereas files can be allocated and deallocated at any time.
15373 Note that swap space is not zeroed on shutdown, so sensitive data (such
15374 as passwords) may linger on it if it was paged out. As such, you should
15375 consider having your swap reside on an encrypted device (@pxref{Mapped
15378 @deftp {Data Type} swap-space
15379 Objects of this type represent swap spaces. They contain the following
15383 @item @code{target}
15384 The device or file to use, either a UUID, a @code{file-system-label} or
15385 a string, as in the definition of a @code{file-system} (@pxref{File
15388 @item @code{dependencies} (default: @code{'()})
15389 A list of @code{file-system} or @code{mapped-device} objects, upon which
15390 the availability of the space depends. Note that just like for
15391 @code{file-system} objects, dependencies which are needed for boot and
15392 mounted in early userspace are not managed by the Shepherd, and so
15393 automatically filtered out for you.
15395 @item @code{priority} (default: @code{#f})
15396 Only supported by the Linux kernel. Either @code{#f} to disable swap
15397 priority, or an integer between 0 and 32767. The kernel will first use
15398 swap spaces of higher priority when paging, and use same priority spaces
15399 on a round-robin basis. The kernel will use swap spaces without a set
15400 priority after prioritized spaces, and in the order that they appeared in
15403 @item @code{discard?} (default: @code{#f})
15404 Only supported by the Linux kernel. When true, the kernel will notify
15405 the disk controller of discarded pages, for example with the TRIM
15406 operation on Solid State Drives.
15411 Here are some examples:
15414 (swap-space (target (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
15417 Use the swap partition with the given UUID@. You can learn the UUID of a
15418 Linux swap partition by running @command{swaplabel @var{device}}, where
15419 @var{device} is the @file{/dev} file name of that partition.
15423 (target (file-system-label "swap"))
15424 (dependencies (list lvm-device)))
15427 Use the partition with label @code{swap}, which can be found after the
15428 @var{lvm-device} mapped device has been opened. Again, the
15429 @command{swaplabel} command allows you to view and change the label of a
15430 Linux swap partition.
15434 (target "/btrfs/swapfile")
15435 (dependencies (list btrfs-fs)))
15438 Use the file @file{/btrfs/swapfile} as swap space, which is present on the
15439 @var{btrfs-fs} filesystem.
15441 @node User Accounts
15442 @section User Accounts
15446 @cindex user accounts
15447 User accounts and groups are entirely managed through the
15448 @code{operating-system} declaration. They are specified with the
15449 @code{user-account} and @code{user-group} forms:
15455 (supplementary-groups '("wheel" ;allow use of sudo, etc.
15456 "audio" ;sound card
15457 "video" ;video devices such as webcams
15458 "cdrom")) ;the good ol' CD-ROM
15459 (comment "Bob's sister"))
15462 Here's a user account that uses a different shell and a custom home
15463 directory (the default would be @file{"/home/bob"}):
15469 (comment "Alice's bro")
15470 (shell (file-append zsh "/bin/zsh"))
15471 (home-directory "/home/robert"))
15474 When booting or upon completion of @command{guix system reconfigure},
15475 the system ensures that only the user accounts and groups specified in
15476 the @code{operating-system} declaration exist, and with the specified
15477 properties. Thus, account or group creations or modifications made by
15478 directly invoking commands such as @command{useradd} are lost upon
15479 reconfiguration or reboot. This ensures that the system remains exactly
15482 @deftp {Data Type} user-account
15483 Objects of this type represent user accounts. The following members may
15488 The name of the user account.
15492 This is the name (a string) or identifier (a number) of the user group
15493 this account belongs to.
15495 @item @code{supplementary-groups} (default: @code{'()})
15496 Optionally, this can be defined as a list of group names that this
15497 account belongs to.
15499 @item @code{uid} (default: @code{#f})
15500 This is the user ID for this account (a number), or @code{#f}. In the
15501 latter case, a number is automatically chosen by the system when the
15502 account is created.
15504 @item @code{comment} (default: @code{""})
15505 A comment about the account, such as the account owner's full name.
15507 Note that, for non-system accounts, users are free to change their real
15508 name as it appears in @file{/etc/passwd} using the @command{chfn}
15509 command. When they do, their choice prevails over the system
15510 administrator's choice; reconfiguring does @emph{not} change their name.
15512 @item @code{home-directory}
15513 This is the name of the home directory for the account.
15515 @item @code{create-home-directory?} (default: @code{#t})
15516 Indicates whether the home directory of this account should be created
15517 if it does not exist yet.
15519 @item @code{shell} (default: Bash)
15520 This is a G-expression denoting the file name of a program to be used as
15521 the shell (@pxref{G-Expressions}). For example, you would refer to the
15522 Bash executable like this:
15525 (file-append bash "/bin/bash")
15529 ... and to the Zsh executable like that:
15532 (file-append zsh "/bin/zsh")
15535 @item @code{system?} (default: @code{#f})
15536 This Boolean value indicates whether the account is a ``system''
15537 account. System accounts are sometimes treated specially; for instance,
15538 graphical login managers do not list them.
15540 @anchor{user-account-password}
15541 @cindex password, for user accounts
15542 @item @code{password} (default: @code{#f})
15543 You would normally leave this field to @code{#f}, initialize user
15544 passwords as @code{root} with the @command{passwd} command, and then let
15545 users change it with @command{passwd}. Passwords set with
15546 @command{passwd} are of course preserved across reboot and
15549 If you @emph{do} want to set an initial password for an account, then
15550 this field must contain the encrypted password, as a string. You can use the
15551 @code{crypt} procedure for this purpose:
15558 ;; Specify a SHA-512-hashed initial password.
15559 (password (crypt "InitialPassword!" "$6$abc")))
15563 The hash of this initial password will be available in a file in
15564 @file{/gnu/store}, readable by all the users, so this method must be used with
15568 @xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for
15569 more information on password encryption, and @ref{Encryption,,, guile, GNU
15570 Guile Reference Manual}, for information on Guile's @code{crypt} procedure.
15576 User group declarations are even simpler:
15579 (user-group (name "students"))
15582 @deftp {Data Type} user-group
15583 This type is for, well, user groups. There are just a few fields:
15587 The name of the group.
15589 @item @code{id} (default: @code{#f})
15590 The group identifier (a number). If @code{#f}, a new number is
15591 automatically allocated when the group is created.
15593 @item @code{system?} (default: @code{#f})
15594 This Boolean value indicates whether the group is a ``system'' group.
15595 System groups have low numerical IDs.
15597 @item @code{password} (default: @code{#f})
15598 What, user groups can have a password? Well, apparently yes. Unless
15599 @code{#f}, this field specifies the password of the group.
15604 For convenience, a variable lists all the basic user groups one may
15607 @defvr {Scheme Variable} %base-groups
15608 This is the list of basic user groups that users and/or packages expect
15609 to be present on the system. This includes groups such as ``root'',
15610 ``wheel'', and ``users'', as well as groups used to control access to
15611 specific devices such as ``audio'', ``disk'', and ``cdrom''.
15614 @defvr {Scheme Variable} %base-user-accounts
15615 This is the list of basic system accounts that programs may expect to
15616 find on a GNU/Linux system, such as the ``nobody'' account.
15618 Note that the ``root'' account is not included here. It is a
15619 special-case and is automatically added whether or not it is specified.
15622 @node Keyboard Layout
15623 @section Keyboard Layout
15625 @cindex keyboard layout
15627 To specify what each key of your keyboard does, you need to tell the operating
15628 system what @dfn{keyboard layout} you want to use. The default, when nothing
15629 is specified, is the US English QWERTY layout for 105-key PC keyboards.
15630 However, German speakers will usually prefer the German QWERTZ layout, French
15631 speakers will want the AZERTY layout, and so on; hackers might prefer Dvorak
15632 or bépo, and they might even want to further customize the effect of some of
15633 the keys. This section explains how to get that done.
15635 @cindex keyboard layout, definition
15636 There are three components that will want to know about your keyboard layout:
15640 The @emph{bootloader} may want to know what keyboard layout you want to use
15641 (@pxref{Bootloader Configuration, @code{keyboard-layout}}). This is useful if
15642 you want, for instance, to make sure that you can type the passphrase of your
15643 encrypted root partition using the right layout.
15646 The @emph{operating system kernel}, Linux, will need that so that the console
15647 is properly configured (@pxref{operating-system Reference,
15648 @code{keyboard-layout}}).
15651 The @emph{graphical display server}, usually Xorg, also has its own idea of
15652 the keyboard layout (@pxref{X Window, @code{keyboard-layout}}).
15655 Guix allows you to configure all three separately but, fortunately, it allows
15656 you to share the same keyboard layout for all three components.
15658 @cindex XKB, keyboard layouts
15659 Keyboard layouts are represented by records created by the
15660 @code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following
15661 the X Keyboard extension (XKB), each layout has four attributes: a name (often
15662 a language code such as ``fi'' for Finnish or ``jp'' for Japanese), an
15663 optional variant name, an optional keyboard model name, and a possibly empty
15664 list of additional options. In most cases the layout name is all you care
15667 @deffn {Scheme Procedure} keyboard-layout @var{name} [@var{variant}] @
15668 [#:model] [#:options '()]
15669 Return a new keyboard layout with the given @var{name} and @var{variant}.
15671 @var{name} must be a string such as @code{"fr"}; @var{variant} must be a
15672 string such as @code{"bepo"} or @code{"nodeadkeys"}. See the
15673 @code{xkeyboard-config} package for valid options.
15676 Here are a few examples:
15679 ;; The German QWERTZ layout. Here we assume a standard
15680 ;; "pc105" keyboard model.
15681 (keyboard-layout "de")
15683 ;; The bépo variant of the French layout.
15684 (keyboard-layout "fr" "bepo")
15686 ;; The Catalan layout.
15687 (keyboard-layout "es" "cat")
15689 ;; Arabic layout with "Alt-Shift" to switch to US layout.
15690 (keyboard-layout "ar,us" #:options '("grp:alt_shift_toggle"))
15692 ;; The Latin American Spanish layout. In addition, the
15693 ;; "Caps Lock" key is used as an additional "Ctrl" key,
15694 ;; and the "Menu" key is used as a "Compose" key to enter
15695 ;; accented letters.
15696 (keyboard-layout "latam"
15697 #:options '("ctrl:nocaps" "compose:menu"))
15699 ;; The Russian layout for a ThinkPad keyboard.
15700 (keyboard-layout "ru" #:model "thinkpad")
15702 ;; The "US international" layout, which is the US layout plus
15703 ;; dead keys to enter accented characters. This is for an
15704 ;; Apple MacBook keyboard.
15705 (keyboard-layout "us" "intl" #:model "macbook78")
15708 See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package
15709 for a complete list of supported layouts, variants, and models.
15711 @cindex keyboard layout, configuration
15712 Let's say you want your system to use the Turkish keyboard layout throughout
15713 your system---bootloader, console, and Xorg. Here's what your system
15714 configuration would look like:
15716 @findex set-xorg-configuration
15718 ;; Using the Turkish layout for the bootloader, the console,
15723 (keyboard-layout (keyboard-layout "tr")) ;for the console
15724 (bootloader (bootloader-configuration
15725 (bootloader grub-efi-bootloader)
15726 (targets '("/boot/efi"))
15727 (keyboard-layout keyboard-layout))) ;for GRUB
15728 (services (cons (set-xorg-configuration
15729 (xorg-configuration ;for Xorg
15730 (keyboard-layout keyboard-layout)))
15731 %desktop-services)))
15734 In the example above, for GRUB and for Xorg, we just refer to the
15735 @code{keyboard-layout} field defined above, but we could just as well refer to
15736 a different layout. The @code{set-xorg-configuration} procedure communicates
15737 the desired Xorg configuration to the graphical log-in manager, by default
15740 We've discussed how to specify the @emph{default} keyboard layout of your
15741 system when it starts, but you can also adjust it at run time:
15745 If you're using GNOME, its settings panel has a ``Region & Language'' entry
15746 where you can select one or more keyboard layouts.
15749 Under Xorg, the @command{setxkbmap} command (from the same-named package)
15750 allows you to change the current layout. For example, this is how you would
15751 change the layout to US Dvorak:
15754 setxkbmap us dvorak
15758 The @code{loadkeys} command changes the keyboard layout in effect in the Linux
15759 console. However, note that @code{loadkeys} does @emph{not} use the XKB
15760 keyboard layout categorization described above. The command below loads the
15761 French bépo layout:
15772 A @dfn{locale} defines cultural conventions for a particular language
15773 and region of the world (@pxref{Locales,,, libc, The GNU C Library
15774 Reference Manual}). Each locale has a name that typically has the form
15775 @code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
15776 @code{fr_LU.utf8} designates the locale for the French language, with
15777 cultural conventions from Luxembourg, and using the UTF-8 encoding.
15779 @cindex locale definition
15780 Usually, you will want to specify the default locale for the machine
15781 using the @code{locale} field of the @code{operating-system} declaration
15782 (@pxref{operating-system Reference, @code{locale}}).
15784 The selected locale is automatically added to the @dfn{locale
15785 definitions} known to the system if needed, with its codeset inferred
15786 from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
15787 @code{UTF-8} codeset. Additional locale definitions can be specified in
15788 the @code{locale-definitions} slot of @code{operating-system}---this is
15789 useful, for instance, if the codeset could not be inferred from the
15790 locale name. The default set of locale definitions includes some widely
15791 used locales, but not all the available locales, in order to save space.
15793 For instance, to add the North Frisian locale for Germany, the value of
15797 (cons (locale-definition
15798 (name "fy_DE.utf8") (source "fy_DE"))
15799 %default-locale-definitions)
15802 Likewise, to save space, one might want @code{locale-definitions} to
15803 list only the locales that are actually used, as in:
15806 (list (locale-definition
15807 (name "ja_JP.eucjp") (source "ja_JP")
15808 (charset "EUC-JP")))
15812 The compiled locale definitions are available at
15813 @file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
15814 version, which is the default location where the GNU@tie{}libc provided
15815 by Guix looks for locale data. This can be overridden using the
15816 @env{LOCPATH} environment variable (@pxref{locales-and-locpath,
15817 @env{LOCPATH} and locale packages}).
15819 The @code{locale-definition} form is provided by the @code{(gnu system
15820 locale)} module. Details are given below.
15822 @deftp {Data Type} locale-definition
15823 This is the data type of a locale definition.
15828 The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
15829 Reference Manual}, for more information on locale names.
15831 @item @code{source}
15832 The name of the source for that locale. This is typically the
15833 @code{@var{language}_@var{territory}} part of the locale name.
15835 @item @code{charset} (default: @code{"UTF-8"})
15836 The ``character set'' or ``code set'' for that locale,
15837 @uref{https://www.iana.org/assignments/character-sets, as defined by
15843 @defvr {Scheme Variable} %default-locale-definitions
15844 A list of commonly used UTF-8 locales, used as the default
15845 value of the @code{locale-definitions} field of @code{operating-system}
15848 @cindex locale name
15849 @cindex normalized codeset in locale names
15850 These locale definitions use the @dfn{normalized codeset} for the part
15851 that follows the dot in the name (@pxref{Using gettextized software,
15852 normalized codeset,, libc, The GNU C Library Reference Manual}). So for
15853 instance it has @code{uk_UA.utf8} but @emph{not}, say,
15854 @code{uk_UA.UTF-8}.
15857 @subsection Locale Data Compatibility Considerations
15859 @cindex incompatibility, of locale data
15860 @code{operating-system} declarations provide a @code{locale-libcs} field
15861 to specify the GNU@tie{}libc packages that are used to compile locale
15862 declarations (@pxref{operating-system Reference}). ``Why would I
15863 care?'', you may ask. Well, it turns out that the binary format of
15864 locale data is occasionally incompatible from one libc version to
15867 @c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
15868 @c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
15869 For instance, a program linked against libc version 2.21 is unable to
15870 read locale data produced with libc 2.22; worse, that program
15871 @emph{aborts} instead of simply ignoring the incompatible locale
15872 data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
15873 the incompatible locale data, which is already an improvement.}.
15874 Similarly, a program linked against libc 2.22 can read most, but not
15875 all, of the locale data from libc 2.21 (specifically, @env{LC_COLLATE}
15876 data is incompatible); thus calls to @code{setlocale} may fail, but
15877 programs will not abort.
15879 The ``problem'' with Guix is that users have a lot of freedom: They can
15880 choose whether and when to upgrade software in their profiles, and might
15881 be using a libc version different from the one the system administrator
15882 used to build the system-wide locale data.
15884 Fortunately, unprivileged users can also install their own locale data
15885 and define @env{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
15886 @env{GUIX_LOCPATH} and locale packages}).
15888 Still, it is best if the system-wide locale data at
15889 @file{/run/current-system/locale} is built for all the libc versions
15890 actually in use on the system, so that all the programs can access
15891 it---this is especially crucial on a multi-user system. To do that, the
15892 administrator can specify several libc packages in the
15893 @code{locale-libcs} field of @code{operating-system}:
15896 (use-package-modules base)
15900 (locale-libcs (list glibc-2.21 (canonical-package glibc))))
15903 This example would lead to a system containing locale definitions for
15904 both libc 2.21 and the current version of libc in
15905 @file{/run/current-system/locale}.
15911 @cindex system services
15912 An important part of preparing an @code{operating-system} declaration is
15913 listing @dfn{system services} and their configuration (@pxref{Using the
15914 Configuration System}). System services are typically daemons launched
15915 when the system boots, or other actions needed at that time---e.g.,
15916 configuring network access.
15918 Guix has a broad definition of ``service'' (@pxref{Service
15919 Composition}), but many services are managed by the GNU@tie{}Shepherd
15920 (@pxref{Shepherd Services}). On a running system, the @command{herd}
15921 command allows you to list the available services, show their status,
15922 start and stop them, or do other specific operations (@pxref{Jump
15923 Start,,, shepherd, The GNU Shepherd Manual}). For example:
15929 The above command, run as @code{root}, lists the currently defined
15930 services. The @command{herd doc} command shows a synopsis of the given
15931 service and its associated actions:
15935 Run libc's name service cache daemon (nscd).
15937 # herd doc nscd action invalidate
15938 invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
15941 The @command{start}, @command{stop}, and @command{restart} sub-commands
15942 have the effect you would expect. For instance, the commands below stop
15943 the nscd service and restart the Xorg display server:
15947 Service nscd has been stopped.
15948 # herd restart xorg-server
15949 Service xorg-server has been stopped.
15950 Service xorg-server has been started.
15953 The following sections document the available services, starting with
15954 the core services, that may be used in an @code{operating-system}
15958 * Base Services:: Essential system services.
15959 * Scheduled Job Execution:: The mcron service.
15960 * Log Rotation:: The rottlog service.
15961 * Networking Setup:: Setting up network interfaces.
15962 * Networking Services:: Firewall, SSH daemon, etc.
15963 * Unattended Upgrades:: Automated system upgrades.
15964 * X Window:: Graphical display.
15965 * Printing Services:: Local and remote printer support.
15966 * Desktop Services:: D-Bus and desktop services.
15967 * Sound Services:: ALSA and Pulseaudio services.
15968 * Database Services:: SQL databases, key-value stores, etc.
15969 * Mail Services:: IMAP, POP3, SMTP, and all that.
15970 * Messaging Services:: Messaging services.
15971 * Telephony Services:: Telephony services.
15972 * File-Sharing Services:: File-sharing services.
15973 * Monitoring Services:: Monitoring services.
15974 * Kerberos Services:: Kerberos services.
15975 * LDAP Services:: LDAP services.
15976 * Web Services:: Web servers.
15977 * Certificate Services:: TLS certificates via Let's Encrypt.
15978 * DNS Services:: DNS daemons.
15979 * VPN Services:: VPN daemons.
15980 * Network File System:: NFS related services.
15981 * Continuous Integration:: Cuirass and Laminar services.
15982 * Power Management Services:: Extending battery life.
15983 * Audio Services:: The MPD.
15984 * Virtualization Services:: Virtualization services.
15985 * Version Control Services:: Providing remote access to Git repositories.
15986 * Game Services:: Game servers.
15987 * PAM Mount Service:: Service to mount volumes when logging in.
15988 * Guix Services:: Services relating specifically to Guix.
15989 * Linux Services:: Services tied to the Linux kernel.
15990 * Hurd Services:: Services specific for a Hurd System.
15991 * Miscellaneous Services:: Other services.
15994 @node Base Services
15995 @subsection Base Services
15997 The @code{(gnu services base)} module provides definitions for the basic
15998 services that one expects from the system. The services exported by
15999 this module are listed below.
16001 @defvr {Scheme Variable} %base-services
16002 This variable contains a list of basic services (@pxref{Service Types
16003 and Services}, for more information on service objects) one would
16004 expect from the system: a login service (mingetty) on each tty, syslogd,
16005 the libc name service cache daemon (nscd), the udev device manager, and
16008 This is the default value of the @code{services} field of
16009 @code{operating-system} declarations. Usually, when customizing a
16010 system, you will want to append services to @code{%base-services}, like
16014 (append (list (service avahi-service-type)
16015 (service openssh-service-type))
16020 @defvr {Scheme Variable} special-files-service-type
16021 This is the service that sets up ``special files'' such as
16022 @file{/bin/sh}; an instance of it is part of @code{%base-services}.
16024 The value associated with @code{special-files-service-type} services
16025 must be a list of tuples where the first element is the ``special file''
16026 and the second element is its target. By default it is:
16028 @cindex @file{/bin/sh}
16029 @cindex @file{sh}, in @file{/bin}
16031 `(("/bin/sh" ,(file-append bash "/bin/sh")))
16034 @cindex @file{/usr/bin/env}
16035 @cindex @file{env}, in @file{/usr/bin}
16036 If you want to add, say, @code{/usr/bin/env} to your system, you can
16040 `(("/bin/sh" ,(file-append bash "/bin/sh"))
16041 ("/usr/bin/env" ,(file-append coreutils "/bin/env")))
16044 Since this is part of @code{%base-services}, you can use
16045 @code{modify-services} to customize the set of special files
16046 (@pxref{Service Reference, @code{modify-services}}). But the simple way
16047 to add a special file is @i{via} the @code{extra-special-file} procedure
16051 @deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
16052 Use @var{target} as the ``special file'' @var{file}.
16054 For example, adding the following lines to the @code{services} field of
16055 your operating system declaration leads to a @file{/usr/bin/env}
16059 (extra-special-file "/usr/bin/env"
16060 (file-append coreutils "/bin/env"))
16064 @deffn {Scheme Procedure} host-name-service @var{name}
16065 Return a service that sets the host name to @var{name}.
16068 @defvr {Scheme Variable} console-font-service-type
16069 Install the given fonts on the specified ttys (fonts are per
16070 virtual console on the kernel Linux). The value of this service is a list of
16071 tty/font pairs. The font can be the name of a font provided by the @code{kbd}
16072 package or any valid argument to @command{setfont}, as in this example:
16075 `(("tty1" . "LatGrkCyr-8x16")
16076 ("tty2" . ,(file-append
16078 "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
16079 ("tty3" . ,(file-append
16081 "/share/consolefonts/ter-132n"))) ; for HDPI
16085 @deffn {Scheme Procedure} login-service @var{config}
16086 Return a service to run login according to @var{config}, a
16087 @code{<login-configuration>} object, which specifies the message of the day,
16088 among other things.
16091 @deftp {Data Type} login-configuration
16092 This is the data type representing the configuration of login.
16097 @cindex message of the day
16098 A file-like object containing the ``message of the day''.
16100 @item @code{allow-empty-passwords?} (default: @code{#t})
16101 Allow empty passwords by default so that first-time users can log in when
16102 the 'root' account has just been created.
16107 @deffn {Scheme Procedure} mingetty-service @var{config}
16108 Return a service to run mingetty according to @var{config}, a
16109 @code{<mingetty-configuration>} object, which specifies the tty to run, among
16113 @deftp {Data Type} mingetty-configuration
16114 This is the data type representing the configuration of Mingetty, which
16115 provides the default implementation of virtual console log-in.
16120 The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
16122 @item @code{auto-login} (default: @code{#f})
16123 When true, this field must be a string denoting the user name under
16124 which the system automatically logs in. When it is @code{#f}, a
16125 user name and password must be entered to log in.
16127 @item @code{login-program} (default: @code{#f})
16128 This must be either @code{#f}, in which case the default log-in program
16129 is used (@command{login} from the Shadow tool suite), or a gexp denoting
16130 the name of the log-in program.
16132 @item @code{login-pause?} (default: @code{#f})
16133 When set to @code{#t} in conjunction with @var{auto-login}, the user
16134 will have to press a key before the log-in shell is launched.
16136 @item @code{clear-on-logout?} (default: @code{#t})
16137 When set to @code{#t}, the screen will be cleared after logout.
16139 @item @code{mingetty} (default: @var{mingetty})
16140 The Mingetty package to use.
16145 @deffn {Scheme Procedure} agetty-service @var{config}
16146 Return a service to run agetty according to @var{config}, an
16147 @code{<agetty-configuration>} object, which specifies the tty to run,
16148 among other things.
16151 @deftp {Data Type} agetty-configuration
16152 This is the data type representing the configuration of agetty, which
16153 implements virtual and serial console log-in. See the @code{agetty(8)}
16154 man page for more information.
16159 The name of the console this agetty runs on, as a string---e.g.,
16160 @code{"ttyS0"}. This argument is optional, it will default to
16161 a reasonable default serial port used by the kernel Linux.
16163 For this, if there is a value for an option @code{agetty.tty} in the kernel
16164 command line, agetty will extract the device name of the serial port
16165 from it and use that.
16167 If not and if there is a value for an option @code{console} with a tty in
16168 the Linux command line, agetty will extract the device name of the
16169 serial port from it and use that.
16171 In both cases, agetty will leave the other serial device settings
16172 (baud rate etc.)@: alone---in the hope that Linux pinned them to the
16175 @item @code{baud-rate} (default: @code{#f})
16176 A string containing a comma-separated list of one or more baud rates, in
16179 @item @code{term} (default: @code{#f})
16180 A string containing the value used for the @env{TERM} environment
16183 @item @code{eight-bits?} (default: @code{#f})
16184 When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection is
16187 @item @code{auto-login} (default: @code{#f})
16188 When passed a login name, as a string, the specified user will be logged
16189 in automatically without prompting for their login name or password.
16191 @item @code{no-reset?} (default: @code{#f})
16192 When @code{#t}, don't reset terminal cflags (control modes).
16194 @item @code{host} (default: @code{#f})
16195 This accepts a string containing the ``login_host'', which will be written
16196 into the @file{/var/run/utmpx} file.
16198 @item @code{remote?} (default: @code{#f})
16199 When set to @code{#t} in conjunction with @var{host}, this will add an
16200 @code{-r} fakehost option to the command line of the login program
16201 specified in @var{login-program}.
16203 @item @code{flow-control?} (default: @code{#f})
16204 When set to @code{#t}, enable hardware (RTS/CTS) flow control.
16206 @item @code{no-issue?} (default: @code{#f})
16207 When set to @code{#t}, the contents of the @file{/etc/issue} file will
16208 not be displayed before presenting the login prompt.
16210 @item @code{init-string} (default: @code{#f})
16211 This accepts a string that will be sent to the tty or modem before
16212 sending anything else. It can be used to initialize a modem.
16214 @item @code{no-clear?} (default: @code{#f})
16215 When set to @code{#t}, agetty will not clear the screen before showing
16218 @item @code{login-program} (default: (file-append shadow "/bin/login"))
16219 This must be either a gexp denoting the name of a log-in program, or
16220 unset, in which case the default value is the @command{login} from the
16223 @item @code{local-line} (default: @code{#f})
16224 Control the CLOCAL line flag. This accepts one of three symbols as
16225 arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
16226 the default value chosen by agetty is @code{'auto}.
16228 @item @code{extract-baud?} (default: @code{#f})
16229 When set to @code{#t}, instruct agetty to try to extract the baud rate
16230 from the status messages produced by certain types of modems.
16232 @item @code{skip-login?} (default: @code{#f})
16233 When set to @code{#t}, do not prompt the user for a login name. This
16234 can be used with @var{login-program} field to use non-standard login
16237 @item @code{no-newline?} (default: @code{#f})
16238 When set to @code{#t}, do not print a newline before printing the
16239 @file{/etc/issue} file.
16241 @c Is this dangerous only when used with login-program, or always?
16242 @item @code{login-options} (default: @code{#f})
16243 This option accepts a string containing options that are passed to the
16244 login program. When used with the @var{login-program}, be aware that a
16245 malicious user could try to enter a login name containing embedded
16246 options that could be parsed by the login program.
16248 @item @code{login-pause} (default: @code{#f})
16249 When set to @code{#t}, wait for any key before showing the login prompt.
16250 This can be used in conjunction with @var{auto-login} to save memory by
16251 lazily spawning shells.
16253 @item @code{chroot} (default: @code{#f})
16254 Change root to the specified directory. This option accepts a directory
16257 @item @code{hangup?} (default: @code{#f})
16258 Use the Linux system call @code{vhangup} to do a virtual hangup of the
16259 specified terminal.
16261 @item @code{keep-baud?} (default: @code{#f})
16262 When set to @code{#t}, try to keep the existing baud rate. The baud
16263 rates from @var{baud-rate} are used when agetty receives a @key{BREAK}
16266 @item @code{timeout} (default: @code{#f})
16267 When set to an integer value, terminate if no user name could be read
16268 within @var{timeout} seconds.
16270 @item @code{detect-case?} (default: @code{#f})
16271 When set to @code{#t}, turn on support for detecting an uppercase-only
16272 terminal. This setting will detect a login name containing only
16273 uppercase letters as indicating an uppercase-only terminal and turn on
16274 some upper-to-lower case conversions. Note that this will not support
16275 Unicode characters.
16277 @item @code{wait-cr?} (default: @code{#f})
16278 When set to @code{#t}, wait for the user or modem to send a
16279 carriage-return or linefeed character before displaying
16280 @file{/etc/issue} or login prompt. This is typically used with the
16281 @var{init-string} option.
16283 @item @code{no-hints?} (default: @code{#f})
16284 When set to @code{#t}, do not print hints about Num, Caps, and Scroll
16287 @item @code{no-hostname?} (default: @code{#f})
16288 By default, the hostname is printed. When this option is set to
16289 @code{#t}, no hostname will be shown at all.
16291 @item @code{long-hostname?} (default: @code{#f})
16292 By default, the hostname is only printed until the first dot. When this
16293 option is set to @code{#t}, the fully qualified hostname by
16294 @code{gethostname} or @code{getaddrinfo} is shown.
16296 @item @code{erase-characters} (default: @code{#f})
16297 This option accepts a string of additional characters that should be
16298 interpreted as backspace when the user types their login name.
16300 @item @code{kill-characters} (default: @code{#f})
16301 This option accepts a string that should be interpreted to mean ``ignore
16302 all previous characters'' (also called a ``kill'' character) when the user
16303 types their login name.
16305 @item @code{chdir} (default: @code{#f})
16306 This option accepts, as a string, a directory path that will be changed
16309 @item @code{delay} (default: @code{#f})
16310 This options accepts, as an integer, the number of seconds to sleep
16311 before opening the tty and displaying the login prompt.
16313 @item @code{nice} (default: @code{#f})
16314 This option accepts, as an integer, the nice value with which to run the
16315 @command{login} program.
16317 @item @code{extra-options} (default: @code{'()})
16318 This option provides an ``escape hatch'' for the user to provide arbitrary
16319 command-line arguments to @command{agetty} as a list of strings.
16324 @deffn {Scheme Procedure} kmscon-service-type @var{config}
16325 Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
16326 according to @var{config}, a @code{<kmscon-configuration>} object, which
16327 specifies the tty to run, among other things.
16330 @deftp {Data Type} kmscon-configuration
16331 This is the data type representing the configuration of Kmscon, which
16332 implements virtual console log-in.
16336 @item @code{virtual-terminal}
16337 The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
16339 @item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
16340 A gexp denoting the name of the log-in program. The default log-in program is
16341 @command{login} from the Shadow tool suite.
16343 @item @code{login-arguments} (default: @code{'("-p")})
16344 A list of arguments to pass to @command{login}.
16346 @item @code{auto-login} (default: @code{#f})
16347 When passed a login name, as a string, the specified user will be logged
16348 in automatically without prompting for their login name or password.
16350 @item @code{hardware-acceleration?} (default: #f)
16351 Whether to use hardware acceleration.
16353 @item @code{font-engine} (default: @code{"pango"})
16354 Font engine used in Kmscon.
16356 @item @code{font-size} (default: @code{12})
16357 Font size used in Kmscon.
16359 @item @code{keyboard-layout} (default: @code{#f})
16360 If this is @code{#f}, Kmscon uses the default keyboard layout---usually US
16361 English (``qwerty'') for a 105-key PC keyboard.
16363 Otherwise this must be a @code{keyboard-layout} object specifying the
16364 keyboard layout. @xref{Keyboard Layout}, for more information on how to
16365 specify the keyboard layout.
16367 @item @code{kmscon} (default: @var{kmscon})
16368 The Kmscon package to use.
16373 @cindex name service cache daemon
16375 @deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
16376 [#:name-services '()]
16377 Return a service that runs the libc name service cache daemon (nscd) with the
16378 given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
16379 Service Switch}, for an example.
16381 For convenience, the Shepherd service for nscd provides the following actions:
16385 @cindex cache invalidation, nscd
16386 @cindex nscd, cache invalidation
16387 This invalidate the given cache. For instance, running:
16390 herd invalidate nscd hosts
16394 invalidates the host name lookup cache of nscd.
16397 Running @command{herd statistics nscd} displays information about nscd usage
16403 @defvr {Scheme Variable} %nscd-default-configuration
16404 This is the default @code{<nscd-configuration>} value (see below) used
16405 by @code{nscd-service}. It uses the caches defined by
16406 @code{%nscd-default-caches}; see below.
16409 @deftp {Data Type} nscd-configuration
16410 This is the data type representing the name service cache daemon (nscd)
16415 @item @code{name-services} (default: @code{'()})
16416 List of packages denoting @dfn{name services} that must be visible to
16417 the nscd---e.g., @code{(list @var{nss-mdns})}.
16419 @item @code{glibc} (default: @var{glibc})
16420 Package object denoting the GNU C Library providing the @command{nscd}
16423 @item @code{log-file} (default: @code{"/var/log/nscd.log"})
16424 Name of the nscd log file. This is where debugging output goes when
16425 @code{debug-level} is strictly positive.
16427 @item @code{debug-level} (default: @code{0})
16428 Integer denoting the debugging levels. Higher numbers mean that more
16429 debugging output is logged.
16431 @item @code{caches} (default: @code{%nscd-default-caches})
16432 List of @code{<nscd-cache>} objects denoting things to be cached; see
16438 @deftp {Data Type} nscd-cache
16439 Data type representing a cache database of nscd and its parameters.
16443 @item @code{database}
16444 This is a symbol representing the name of the database to be cached.
16445 Valid values are @code{passwd}, @code{group}, @code{hosts}, and
16446 @code{services}, which designate the corresponding NSS database
16447 (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
16449 @item @code{positive-time-to-live}
16450 @itemx @code{negative-time-to-live} (default: @code{20})
16451 A number representing the number of seconds during which a positive or
16452 negative lookup result remains in cache.
16454 @item @code{check-files?} (default: @code{#t})
16455 Whether to check for updates of the files corresponding to
16458 For instance, when @var{database} is @code{hosts}, setting this flag
16459 instructs nscd to check for updates in @file{/etc/hosts} and to take
16462 @item @code{persistent?} (default: @code{#t})
16463 Whether the cache should be stored persistently on disk.
16465 @item @code{shared?} (default: @code{#t})
16466 Whether the cache should be shared among users.
16468 @item @code{max-database-size} (default: 32@tie{}MiB)
16469 Maximum size in bytes of the database cache.
16471 @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
16472 @c settings, so leave them out.
16477 @defvr {Scheme Variable} %nscd-default-caches
16478 List of @code{<nscd-cache>} objects used by default by
16479 @code{nscd-configuration} (see above).
16481 It enables persistent and aggressive caching of service and host name
16482 lookups. The latter provides better host name lookup performance,
16483 resilience in the face of unreliable name servers, and also better
16484 privacy---often the result of host name lookups is in local cache, so
16485 external name servers do not even need to be queried.
16488 @anchor{syslog-configuration-type}
16491 @deftp {Data Type} syslog-configuration
16492 This data type represents the configuration of the syslog daemon.
16495 @item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
16496 The syslog daemon to use.
16498 @item @code{config-file} (default: @code{%default-syslog.conf})
16499 The syslog configuration file to use.
16504 @anchor{syslog-service}
16506 @deffn {Scheme Procedure} syslog-service @var{config}
16507 Return a service that runs a syslog daemon according to @var{config}.
16509 @xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
16510 information on the configuration file syntax.
16513 @defvr {Scheme Variable} guix-service-type
16514 This is the type of the service that runs the build daemon,
16515 @command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a
16516 @code{guix-configuration} record as described below.
16519 @anchor{guix-configuration-type}
16520 @deftp {Data Type} guix-configuration
16521 This data type represents the configuration of the Guix build daemon.
16522 @xref{Invoking guix-daemon}, for more information.
16525 @item @code{guix} (default: @var{guix})
16526 The Guix package to use.
16528 @item @code{build-group} (default: @code{"guixbuild"})
16529 Name of the group for build user accounts.
16531 @item @code{build-accounts} (default: @code{10})
16532 Number of build user accounts to create.
16534 @item @code{authorize-key?} (default: @code{#t})
16535 @cindex substitutes, authorization thereof
16536 Whether to authorize the substitute keys listed in
16537 @code{authorized-keys}---by default that of
16538 @code{@value{SUBSTITUTE-SERVER-1}} and
16539 @code{@value{SUBSTITUTE-SERVER-2}}
16540 (@pxref{Substitutes}).
16542 When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be
16543 changed by invoking @command{guix archive --authorize}. You must
16544 instead adjust @code{guix-configuration} as you wish and reconfigure the
16545 system. This ensures that your operating system configuration file is
16549 When booting or reconfiguring to a system where @code{authorize-key?}
16550 is true, the existing @file{/etc/guix/acl} file is backed up as
16551 @file{/etc/guix/acl.bak} if it was determined to be a manually modified
16552 file. This is to facilitate migration from earlier versions, which
16553 allowed for in-place modifications to @file{/etc/guix/acl}.
16556 @vindex %default-authorized-guix-keys
16557 @item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
16558 The list of authorized key files for archive imports, as a list of
16559 string-valued gexps (@pxref{Invoking guix archive}). By default, it
16560 contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
16561 @code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutes}). See
16562 @code{substitute-urls} below for an example on how to change it.
16564 @item @code{use-substitutes?} (default: @code{#t})
16565 Whether to use substitutes.
16567 @item @code{substitute-urls} (default: @code{%default-substitute-urls})
16568 The list of URLs where to look for substitutes by default.
16570 Suppose you would like to fetch substitutes from @code{guix.example.org}
16571 in addition to @code{@value{SUBSTITUTE-SERVER-1}}. You will need to do
16572 two things: (1) add @code{guix.example.org} to @code{substitute-urls},
16573 and (2) authorize its signing key, having done appropriate checks
16574 (@pxref{Substitute Server Authorization}). The configuration below does
16578 (guix-configuration
16580 (append (list "https://guix.example.org")
16581 %default-substitute-urls))
16583 (append (list (local-file "./guix.example.org-key.pub"))
16584 %default-authorized-guix-keys)))
16587 This example assumes that the file @file{./guix.example.org-key.pub}
16588 contains the public key that @code{guix.example.org} uses to sign
16591 @item @code{max-silent-time} (default: @code{0})
16592 @itemx @code{timeout} (default: @code{0})
16593 The number of seconds of silence and the number of seconds of activity,
16594 respectively, after which a build process times out. A value of zero
16595 disables the timeout.
16597 @item @code{log-compression} (default: @code{'bzip2})
16598 The type of compression used for build logs---one of @code{gzip},
16599 @code{bzip2}, or @code{none}.
16601 @item @code{discover?} (default: @code{#f})
16602 Whether to discover substitute servers on the local network using mDNS
16605 @item @code{extra-options} (default: @code{'()})
16606 List of extra command-line options for @command{guix-daemon}.
16608 @item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
16609 File where @command{guix-daemon}'s standard output and standard error
16612 @cindex HTTP proxy, for @code{guix-daemon}
16613 @cindex proxy, for @code{guix-daemon} HTTP access
16614 @item @code{http-proxy} (default: @code{#f})
16615 The URL of the HTTP and HTTPS proxy used for downloading fixed-output
16616 derivations and substitutes.
16618 It is also possible to change the daemon's proxy at run time through the
16619 @code{set-http-proxy} action, which restarts it:
16622 herd set-http-proxy guix-daemon http://localhost:8118
16625 To clear the proxy settings, run:
16628 herd set-http-proxy guix-daemon
16631 @item @code{tmpdir} (default: @code{#f})
16632 A directory path where the @command{guix-daemon} will perform builds.
16637 @deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
16638 Run @var{udev}, which populates the @file{/dev} directory dynamically.
16639 udev rules can be provided as a list of files through the @var{rules}
16640 variable. The procedures @code{udev-rule}, @code{udev-rules-service}
16641 and @code{file->udev-rule} from @code{(gnu services base)} simplify the
16642 creation of such rule files.
16644 The @command{herd rules udev} command, as root, returns the name of the
16645 directory containing all the active udev rules.
16648 @deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
16649 Return a udev-rule file named @var{file-name} containing the rules
16650 defined by the @var{contents} literal.
16652 In the following example, a rule for a USB device is defined to be
16653 stored in the file @file{90-usb-thing.rules}. The rule runs a script
16654 upon detecting a USB device with a given product identifier.
16657 (define %example-udev-rule
16659 "90-usb-thing.rules"
16660 (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
16661 "ATTR@{product@}==\"Example\", "
16662 "RUN+=\"/path/to/script\"")))
16666 @deffn {Scheme Procedure} udev-rules-service [@var{name} @var{rules}] @
16667 [#:groups @var{groups}]
16668 Return a service that extends @code{udev-service-type } with @var{rules}
16669 and @code{account-service-type} with @var{groups} as system groups.
16670 This works by creating a singleton service type
16671 @code{@var{name}-udev-rules}, of which the returned service is an
16674 Here we show how it can be used to extend @code{udev-service-type} with the
16675 previously defined rule @code{%example-udev-rule}.
16681 (cons (udev-rules-service 'usb-thing %example-udev-rule)
16682 %desktop-services)))
16686 @deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
16687 Return a udev file named @var{file-name} containing the rules defined
16688 within @var{file}, a file-like object.
16690 The following example showcases how we can use an existing rule file.
16693 (use-modules (guix download) ;for url-fetch
16694 (guix packages) ;for origin
16697 (define %android-udev-rules
16699 "51-android-udev.rules"
16700 (let ((version "20170910"))
16703 (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
16704 "android-udev-rules/" version "/51-android.rules"))
16706 (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
16710 Additionally, Guix package definitions can be included in @var{rules} in
16711 order to extend the udev rules with the definitions found under their
16712 @file{lib/udev/rules.d} sub-directory. In lieu of the previous
16713 @var{file->udev-rule} example, we could have used the
16714 @var{android-udev-rules} package which exists in Guix in the @code{(gnu
16715 packages android)} module.
16717 The following example shows how to use the @var{android-udev-rules}
16718 package so that the Android tool @command{adb} can detect devices
16719 without root privileges. It also details how to create the
16720 @code{adbusers} group, which is required for the proper functioning of
16721 the rules defined within the @code{android-udev-rules} package. To
16722 create such a group, we must define it both as part of the
16723 @code{supplementary-groups} of our @code{user-account} declaration, as
16724 well as in the @var{groups} of the @code{udev-rules-service} procedure.
16727 (use-modules (gnu packages android) ;for android-udev-rules
16728 (gnu system shadow) ;for user-group
16733 (users (cons (user-account
16735 (supplementary-groups
16736 '("adbusers" ;for adb
16737 "wheel" "netdev" "audio" "video")))))
16740 (cons (udev-rules-service 'android android-udev-rules
16741 #:groups '("adbusers"))
16742 %desktop-services)))
16745 @defvr {Scheme Variable} urandom-seed-service-type
16746 Save some entropy in @code{%random-seed-file} to seed @file{/dev/urandom}
16747 when rebooting. It also tries to seed @file{/dev/urandom} from
16748 @file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
16752 @defvr {Scheme Variable} %random-seed-file
16753 This is the name of the file where some random bytes are saved by
16754 @var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting.
16755 It defaults to @file{/var/lib/random-seed}.
16760 @defvr {Scheme Variable} gpm-service-type
16761 This is the type of the service that runs GPM, the @dfn{general-purpose
16762 mouse daemon}, which provides mouse support to the Linux console. GPM
16763 allows users to use the mouse in the console, notably to select, copy,
16766 The value for services of this type must be a @code{gpm-configuration}
16767 (see below). This service is not part of @code{%base-services}.
16770 @deftp {Data Type} gpm-configuration
16771 Data type representing the configuration of GPM.
16774 @item @code{options} (default: @code{%default-gpm-options})
16775 Command-line options passed to @command{gpm}. The default set of
16776 options instruct @command{gpm} to listen to mouse events on
16777 @file{/dev/input/mice}. @xref{Command Line,,, gpm, gpm manual}, for
16780 @item @code{gpm} (default: @code{gpm})
16781 The GPM package to use.
16786 @anchor{guix-publish-service-type}
16787 @deffn {Scheme Variable} guix-publish-service-type
16788 This is the service type for @command{guix publish} (@pxref{Invoking
16789 guix publish}). Its value must be a @code{guix-publish-configuration}
16790 object, as described below.
16792 This assumes that @file{/etc/guix} already contains a signing key pair as
16793 created by @command{guix archive --generate-key} (@pxref{Invoking guix
16794 archive}). If that is not the case, the service will fail to start.
16797 @deftp {Data Type} guix-publish-configuration
16798 Data type representing the configuration of the @code{guix publish}
16802 @item @code{guix} (default: @code{guix})
16803 The Guix package to use.
16805 @item @code{port} (default: @code{80})
16806 The TCP port to listen for connections.
16808 @item @code{host} (default: @code{"localhost"})
16809 The host (and thus, network interface) to listen to. Use
16810 @code{"0.0.0.0"} to listen on all the network interfaces.
16812 @item @code{advertise?} (default: @code{#f})
16813 When true, advertise the service on the local network @i{via} the DNS-SD
16814 protocol, using Avahi.
16816 This allows neighboring Guix devices with discovery on (see
16817 @code{guix-configuration} above) to discover this @command{guix publish}
16818 instance and to automatically download substitutes from it.
16820 @item @code{compression} (default: @code{'(("gzip" 3) ("zstd" 3))})
16821 This is a list of compression method/level tuple used when compressing
16822 substitutes. For example, to compress all substitutes with @emph{both} lzip
16823 at level 7 and gzip at level 9, write:
16826 '(("lzip" 7) ("gzip" 9))
16829 Level 9 achieves the best compression ratio at the expense of increased CPU
16830 usage, whereas level 1 achieves fast compression. @xref{Invoking guix
16831 publish}, for more information on the available compression methods and
16832 the tradeoffs involved.
16834 An empty list disables compression altogether.
16836 @item @code{nar-path} (default: @code{"nar"})
16837 The URL path at which ``nars'' can be fetched. @xref{Invoking guix
16838 publish, @option{--nar-path}}, for details.
16840 @item @code{cache} (default: @code{#f})
16841 When it is @code{#f}, disable caching and instead generate archives on
16842 demand. Otherwise, this should be the name of a directory---e.g.,
16843 @code{"/var/cache/guix/publish"}---where @command{guix publish} caches
16844 archives and meta-data ready to be sent. @xref{Invoking guix publish,
16845 @option{--cache}}, for more information on the tradeoffs involved.
16847 @item @code{workers} (default: @code{#f})
16848 When it is an integer, this is the number of worker threads used for
16849 caching; when @code{#f}, the number of processors is used.
16850 @xref{Invoking guix publish, @option{--workers}}, for more information.
16852 @item @code{cache-bypass-threshold} (default: 10 MiB)
16853 When @code{cache} is true, this is the maximum size in bytes of a store
16854 item for which @command{guix publish} may bypass its cache in case of a
16855 cache miss. @xref{Invoking guix publish,
16856 @option{--cache-bypass-threshold}}, for more information.
16858 @item @code{ttl} (default: @code{#f})
16859 When it is an integer, this denotes the @dfn{time-to-live} in seconds
16860 of the published archives. @xref{Invoking guix publish, @option{--ttl}},
16861 for more information.
16865 @anchor{rngd-service}
16866 @deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
16867 [#:device "/dev/hwrng"]
16868 Return a service that runs the @command{rngd} program from @var{rng-tools}
16869 to add @var{device} to the kernel's entropy pool. The service will fail if
16870 @var{device} does not exist.
16873 @anchor{pam-limits-service}
16874 @cindex session limits
16880 @cindex open file descriptors
16881 @deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
16883 Return a service that installs a configuration file for the
16884 @uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
16885 @code{pam_limits} module}. The procedure optionally takes a list of
16886 @code{pam-limits-entry} values, which can be used to specify
16887 @code{ulimit} limits and @code{nice} priority limits to user sessions.
16889 The following limits definition sets two hard and soft limits for all
16890 login sessions of users in the @code{realtime} group:
16893 (pam-limits-service
16895 (pam-limits-entry "@@realtime" 'both 'rtprio 99)
16896 (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
16899 The first entry increases the maximum realtime priority for
16900 non-privileged processes; the second entry lifts any restriction of the
16901 maximum address space that can be locked in memory. These settings are
16902 commonly used for real-time audio systems.
16904 Another useful example is raising the maximum number of open file
16905 descriptors that can be used:
16908 (pam-limits-service
16910 (pam-limits-entry "*" 'both 'nofile 100000)))
16913 In the above example, the asterisk means the limit should apply to any
16914 user. It is important to ensure the chosen value doesn't exceed the
16915 maximum system value visible in the @file{/proc/sys/fs/file-max} file,
16916 else the users would be prevented from login in. For more information
16917 about the Pluggable Authentication Module (PAM) limits, refer to the
16918 @samp{pam_limits} man page from the @code{linux-pam} package.
16921 @node Scheduled Job Execution
16922 @subsection Scheduled Job Execution
16926 @cindex scheduling jobs
16927 The @code{(gnu services mcron)} module provides an interface to
16928 GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
16929 mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional
16930 Unix @command{cron} daemon; the main difference is that it is
16931 implemented in Guile Scheme, which provides a lot of flexibility when
16932 specifying the scheduling of jobs and their actions.
16934 The example below defines an operating system that runs the
16935 @command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files})
16936 and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as
16937 well as the @command{mkid} command on behalf of an unprivileged user
16938 (@pxref{mkid invocation,,, idutils, ID Database Utilities}). It uses
16939 gexps to introduce job definitions that are passed to mcron
16940 (@pxref{G-Expressions}).
16943 (use-modules (guix) (gnu) (gnu services mcron))
16944 (use-package-modules base idutils)
16946 (define updatedb-job
16947 ;; Run 'updatedb' at 3AM every day. Here we write the
16948 ;; job's action as a Scheme procedure.
16949 #~(job '(next-hour '(3))
16951 (execl (string-append #$findutils "/bin/updatedb")
16953 "--prunepaths=/tmp /var/tmp /gnu/store"))
16956 (define garbage-collector-job
16957 ;; Collect garbage 5 minutes after midnight every day.
16958 ;; The job's action is a shell command.
16959 #~(job "5 0 * * *" ;Vixie cron syntax
16962 (define idutils-job
16963 ;; Update the index database as user "charlie" at 12:15PM
16964 ;; and 19:15PM. This runs from the user's home directory.
16965 #~(job '(next-minute-from (next-hour '(12 19)) '(15))
16966 (string-append #$idutils "/bin/mkid src")
16972 ;; %BASE-SERVICES already includes an instance of
16973 ;; 'mcron-service-type', which we extend with additional
16974 ;; jobs using 'simple-service'.
16975 (services (cons (simple-service 'my-cron-jobs
16977 (list garbage-collector-job
16984 When providing the action of a job specification as a procedure, you
16985 should provide an explicit name for the job via the optional 3rd
16986 argument as done in the @code{updatedb-job} example above. Otherwise,
16987 the job would appear as ``Lambda function'' in the output of
16988 @command{herd schedule mcron}, which is not nearly descriptive enough!
16991 For more complex jobs defined in Scheme where you need control over the top
16992 level, for instance to introduce a @code{use-modules} form, you can move your
16993 code to a separate program using the @code{program-file} procedure of the
16994 @code{(guix gexp)} module (@pxref{G-Expressions}). The example below
16998 (define %battery-alert-job
16999 ;; Beep when the battery percentage falls below %MIN-LEVEL.
17001 '(next-minute (range 0 60 1))
17003 "battery-alert.scm"
17004 (with-imported-modules (source-module-closure
17005 '((guix build utils)))
17007 (use-modules (guix build utils)
17010 (ice-9 textual-ports)
17013 (define %min-level 20)
17015 (setenv "LC_ALL" "C") ;ensure English output
17016 (and-let* ((input-pipe (open-pipe*
17018 #$(file-append acpi "/bin/acpi")))
17019 (output (get-string-all input-pipe))
17020 (m (string-match "Discharging, ([0-9]+)%" output))
17021 (level (string->number (match:substring m 1)))
17022 ((< level %min-level)))
17023 (format #t "warning: Battery level is low (~a%)~%" level)
17024 (invoke #$(file-append beep "/bin/beep") "-r5")))))))
17027 @xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
17028 for more information on mcron job specifications. Below is the
17029 reference of the mcron service.
17031 On a running system, you can use the @code{schedule} action of the service to
17032 visualize the mcron jobs that will be executed next:
17035 # herd schedule mcron
17039 The example above lists the next five tasks that will be executed, but you can
17040 also specify the number of tasks to display:
17043 # herd schedule mcron 10
17046 @defvr {Scheme Variable} mcron-service-type
17047 This is the type of the @code{mcron} service, whose value is an
17048 @code{mcron-configuration} object.
17050 This service type can be the target of a service extension that provides
17051 additional job specifications (@pxref{Service Composition}). In other
17052 words, it is possible to define services that provide additional mcron
17056 @deftp {Data Type} mcron-configuration
17057 Data type representing the configuration of mcron.
17060 @item @code{mcron} (default: @var{mcron})
17061 The mcron package to use.
17064 This is a list of gexps (@pxref{G-Expressions}), where each gexp
17065 corresponds to an mcron job specification (@pxref{Syntax, mcron job
17066 specifications,, mcron, GNU@tie{}mcron}).
17072 @subsection Log Rotation
17075 @cindex log rotation
17077 Log files such as those found in @file{/var/log} tend to grow endlessly,
17078 so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
17079 their contents in separate files, possibly compressed. The @code{(gnu
17080 services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
17081 log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
17083 This service is part of @code{%base-services}, and thus enabled by
17084 default, with the default settings, for commonly encountered log files.
17085 The example below shows how to extend it with an additional
17086 @dfn{rotation}, should you need to do that (usually, services that
17087 produce log files already take care of that):
17090 (use-modules (guix) (gnu))
17091 (use-service-modules admin)
17093 (define my-log-files
17094 ;; Log files that I want to rotate.
17095 '("/var/log/something.log" "/var/log/another.log"))
17099 (services (cons (simple-service 'rotate-my-stuff
17100 rottlog-service-type
17101 (list (log-rotation
17103 (files my-log-files))))
17107 @defvr {Scheme Variable} rottlog-service-type
17108 This is the type of the Rottlog service, whose value is a
17109 @code{rottlog-configuration} object.
17111 Other services can extend this one with new @code{log-rotation} objects
17112 (see below), thereby augmenting the set of files to be rotated.
17114 This service type can define mcron jobs (@pxref{Scheduled Job
17115 Execution}) to run the rottlog service.
17118 @deftp {Data Type} rottlog-configuration
17119 Data type representing the configuration of rottlog.
17122 @item @code{rottlog} (default: @code{rottlog})
17123 The Rottlog package to use.
17125 @item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
17126 The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
17127 rottlog, GNU Rot[t]log Manual}).
17129 @item @code{rotations} (default: @code{%default-rotations})
17130 A list of @code{log-rotation} objects as defined below.
17133 This is a list of gexps where each gexp corresponds to an mcron job
17134 specification (@pxref{Scheduled Job Execution}).
17138 @deftp {Data Type} log-rotation
17139 Data type representing the rotation of a group of log files.
17141 Taking an example from the Rottlog manual (@pxref{Period Related File
17142 Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be
17148 (files '("/var/log/apache/*"))
17149 (options '("storedir apache-archives"
17155 The list of fields is as follows:
17158 @item @code{frequency} (default: @code{'weekly})
17159 The log rotation frequency, a symbol.
17162 The list of files or file glob patterns to rotate.
17164 @item @code{options} (default: @code{'()})
17165 The list of rottlog options for this rotation (@pxref{Configuration
17166 parameters,,, rottlog, GNU Rot[t]lg Manual}).
17168 @item @code{post-rotate} (default: @code{#f})
17169 Either @code{#f} or a gexp to execute once the rotation has completed.
17173 @defvr {Scheme Variable} %default-rotations
17174 Specifies weekly rotation of @code{%rotated-files} and of
17175 @file{/var/log/guix-daemon.log}.
17178 @defvr {Scheme Variable} %rotated-files
17179 The list of syslog-controlled files to be rotated. By default it is:
17180 @code{'("/var/log/messages" "/var/log/secure" "/var/log/debug" \
17181 "/var/log/maillog")}.
17184 @node Networking Setup
17185 @subsection Networking Setup
17187 The @code{(gnu services networking)} module provides services to
17188 configure network interfaces and set up networking on your machine.
17189 Those services provide different ways for you to set up your machine: by
17190 declaring a static network configuration, by running a Dynamic Host
17191 Configuration Protocol (DHCP) client, or by running daemons such as
17192 NetworkManager and Connman that automate the whole process,
17193 automatically adapt to connectivity changes, and provide a high-level
17196 On a laptop, NetworkManager and Connman are by far the most convenient
17197 options, which is why the default desktop services include
17198 NetworkManager (@pxref{Desktop Services, @code{%desktop-services}}).
17199 For a server, or for a virtual machine or a container, static network
17200 configuration or a simple DHCP client are often more appropriate.
17202 This section describes the various network setup services available,
17203 starting with static network configuration.
17205 @defvr {Scheme Variable} static-networking-service-type
17206 This is the type for statically-configured network interfaces. Its
17207 value must be a list of @code{static-networking} records. Each of them
17208 declares a set of @dfn{addresses}, @dfn{routes}, and @dfn{links}, as
17211 @cindex network interface controller (NIC)
17212 @cindex NIC, networking interface controller
17213 Here is the simplest configuration, with only one network interface
17214 controller (NIC) and only IPv4 connectivity:
17217 ;; Static networking for one NIC, IPv4-only.
17218 (service static-networking-service-type
17219 (list (static-networking
17221 (list (network-address
17223 (value "10.0.2.15/24"))))
17225 (list (network-route
17226 (destination "default")
17227 (gateway "10.0.2.2"))))
17228 (name-servers '("10.0.2.3")))))
17231 The snippet above can be added to the @code{services} field of your
17232 operating system configuration (@pxref{Using the Configuration System}).
17233 It will configure your machine to have 10.0.2.15 as its IP address, with
17234 a 24-bit netmask for the local network---meaning that any 10.0.2.@var{x}
17235 address is on the local area network (LAN). Traffic to addresses
17236 outside the local network is routed @i{via} 10.0.2.2. Host names are
17237 resolved by sending domain name system (DNS) queries to 10.0.2.3.
17240 @deftp {Data Type} static-networking
17241 This is the data type representing a static network configuration.
17243 As an example, here is how you would declare the configuration of a
17244 machine with a single network interface controller (NIC) available as
17245 @code{eno1}, and with one IPv4 and one IPv6 address:
17248 ;; Network configuration for one NIC, IPv4 + IPv6.
17250 (addresses (list (network-address
17252 (value "10.0.2.15/24"))
17255 (value "2001:123:4567:101::1/64"))))
17256 (routes (list (network-route
17257 (destination "default")
17258 (gateway "10.0.2.2"))
17260 (destination "default")
17261 (gateway "2020:321:4567:42::1"))))
17262 (name-servers '("10.0.2.3")))
17265 If you are familiar with the @command{ip} command of the
17266 @uref{https://wiki.linuxfoundation.org/networking/iproute2,
17267 @code{iproute2} package} found on Linux-based systems, the declaration
17268 above is equivalent to typing:
17271 ip address add 10.0.2.15/24 dev eno1
17272 ip address add 2001:123:4567:101::1/64 dev eno1
17273 ip route add default via inet 10.0.2.2
17274 ip route add default via inet6 2020:321:4567:42::1
17277 Run @command{man 8 ip} for more info. Venerable GNU/Linux users will
17278 certainly know how to do it with @command{ifconfig} and @command{route},
17279 but we'll spare you that.
17281 The available fields of this data type are as follows:
17284 @item @code{addresses}
17285 @itemx @code{links} (default: @code{'()})
17286 @itemx @code{routes} (default: @code{'()})
17287 The list of @code{network-address}, @code{network-link}, and
17288 @code{network-route} records for this network (see below).
17290 @item @code{name-servers} (default: @code{'()})
17291 The list of IP addresses (strings) of domain name servers. These IP
17292 addresses go to @file{/etc/resolv.conf}.
17294 @item @code{provision} (default: @code{'(networking)})
17295 If true, this should be a list of symbols for the Shepherd service
17296 corresponding to this network configuration.
17298 @item @code{requirement} (default @code{'()})
17299 The list of Shepherd services depended on.
17303 @deftp {Data Type} network-address
17304 This is the data type representing the IP address of a network
17309 The name of the network interface for this address---e.g.,
17313 The actual IP address and network mask, in
17314 @uref{https://en.wikipedia.org/wiki/CIDR#CIDR_notation, @acronym{CIDR,
17315 Classless Inter-Domain Routing} notation}, as a string.
17317 For example, @code{"10.0.2.15/24"} denotes IPv4 address 10.0.2.15 on a
17318 24-bit sub-network---all 10.0.2.@var{x} addresses are on the same local
17322 Whether @code{value} denotes an IPv6 address. By default this is
17323 automatically determined.
17327 @deftp {Data Type} network-route
17328 This is the data type representing a network route.
17331 @item @code{destination}
17332 The route destination (a string), either an IP address or
17333 @code{"default"} to denote the default route.
17335 @item @code{source} (default: @code{#f})
17338 @item @code{device} (default: @code{#f})
17339 The device used for this route---e.g., @code{"eno2"}.
17341 @item @code{ipv6?} (default: auto)
17342 Whether this is an IPv6 route. By default this is automatically
17343 determined based on @code{destination} or @code{gateway}.
17345 @item @code{gateway} (default: @code{#f})
17346 IP address (a string) through which traffic is routed.
17350 @deftp {Data Type} network-link
17351 Data type for a network link (@pxref{Link,,, guile-netlink,
17352 Guile-Netlink Manual}).
17356 The name of the link---e.g., @code{"v0p0"}.
17359 A symbol denoting the type of the link---e.g., @code{'veth}.
17362 List of arguments for this type of link.
17366 @cindex loopback device
17367 @defvr {Scheme Variable} %loopback-static-networking
17368 This is the @code{static-networking} record representing the ``loopback
17369 device'', @code{lo}, for IP addresses 127.0.0.1 and ::1, and providing
17370 the @code{loopback} Shepherd service.
17373 @cindex networking, with QEMU
17374 @cindex QEMU, networking
17375 @defvr {Scheme Variable} %qemu-static-networking
17376 This is the @code{static-networking} record representing network setup
17377 when using QEMU's user-mode network stack on @code{eth0} (@pxref{Using
17378 the user mode network stack,,, QEMU, QEMU Documentation}).
17381 @cindex DHCP, networking service
17382 @defvr {Scheme Variable} dhcp-client-service-type
17383 This is the type of services that run @var{dhcp}, a Dynamic Host Configuration
17384 Protocol (DHCP) client, on all the non-loopback network interfaces. Its value
17385 is the DHCP client package to use, @code{isc-dhcp} by default.
17388 @cindex NetworkManager
17390 @defvr {Scheme Variable} network-manager-service-type
17391 This is the service type for the
17392 @uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
17393 service. The value for this service type is a
17394 @code{network-manager-configuration} record.
17396 This service is part of @code{%desktop-services} (@pxref{Desktop
17400 @deftp {Data Type} network-manager-configuration
17401 Data type representing the configuration of NetworkManager.
17404 @item @code{network-manager} (default: @code{network-manager})
17405 The NetworkManager package to use.
17407 @item @code{dns} (default: @code{"default"})
17408 Processing mode for DNS, which affects how NetworkManager uses the
17409 @code{resolv.conf} configuration file.
17413 NetworkManager will update @code{resolv.conf} to reflect the nameservers
17414 provided by currently active connections.
17417 NetworkManager will run @code{dnsmasq} as a local caching nameserver, using a
17418 @dfn{conditional forwarding} configuration if you are connected to a VPN, and
17419 then update @code{resolv.conf} to point to the local nameserver.
17421 With this setting, you can share your network connection. For example when
17422 you want to share your network connection to another laptop @i{via} an
17423 Ethernet cable, you can open @command{nm-connection-editor} and configure the
17424 Wired connection's method for IPv4 and IPv6 to be ``Shared to other computers''
17425 and reestablish the connection (or reboot).
17427 You can also set up a @dfn{host-to-guest connection} to QEMU VMs
17428 (@pxref{Installing Guix in a VM}). With a host-to-guest connection, you can
17429 e.g.@: access a Web server running on the VM (@pxref{Web Services}) from a Web
17430 browser on your host system, or connect to the VM @i{via} SSH
17431 (@pxref{Networking Services, @code{openssh-service-type}}). To set up a
17432 host-to-guest connection, run this command once:
17435 nmcli connection add type tun \
17436 connection.interface-name tap0 \
17437 tun.mode tap tun.owner $(id -u) \
17438 ipv4.method shared \
17439 ipv4.addresses 172.28.112.1/24
17442 Then each time you launch your QEMU VM (@pxref{Running Guix in a VM}), pass
17443 @option{-nic tap,ifname=tap0,script=no,downscript=no} to
17444 @command{qemu-system-...}.
17447 NetworkManager will not modify @code{resolv.conf}.
17450 @item @code{vpn-plugins} (default: @code{'()})
17451 This is the list of available plugins for virtual private networks
17452 (VPNs). An example of this is the @code{network-manager-openvpn}
17453 package, which allows NetworkManager to manage VPNs @i{via} OpenVPN.
17459 @deffn {Scheme Variable} connman-service-type
17460 This is the service type to run @url{https://01.org/connman,Connman},
17461 a network connection manager.
17463 Its value must be an
17464 @code{connman-configuration} record as in this example:
17467 (service connman-service-type
17468 (connman-configuration
17469 (disable-vpn? #t)))
17472 See below for details about @code{connman-configuration}.
17475 @deftp {Data Type} connman-configuration
17476 Data Type representing the configuration of connman.
17479 @item @code{connman} (default: @var{connman})
17480 The connman package to use.
17482 @item @code{disable-vpn?} (default: @code{#f})
17483 When true, disable connman's vpn plugin.
17487 @cindex WPA Supplicant
17488 @defvr {Scheme Variable} wpa-supplicant-service-type
17489 This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
17490 supplicant}, an authentication daemon required to authenticate against
17491 encrypted WiFi or ethernet networks.
17494 @deftp {Data Type} wpa-supplicant-configuration
17495 Data type representing the configuration of WPA Supplicant.
17497 It takes the following parameters:
17500 @item @code{wpa-supplicant} (default: @code{wpa-supplicant})
17501 The WPA Supplicant package to use.
17503 @item @code{requirement} (default: @code{'(user-processes loopback syslogd)}
17504 List of services that should be started before WPA Supplicant starts.
17506 @item @code{dbus?} (default: @code{#t})
17507 Whether to listen for requests on D-Bus.
17509 @item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"})
17510 Where to store the PID file.
17512 @item @code{interface} (default: @code{#f})
17513 If this is set, it must specify the name of a network interface that
17514 WPA supplicant will control.
17516 @item @code{config-file} (default: @code{#f})
17517 Optional configuration file to use.
17519 @item @code{extra-options} (default: @code{'()})
17520 List of additional command-line arguments to pass to the daemon.
17527 @cindex network management
17528 @deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
17529 Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
17530 management daemon that aims to simplify wired and wireless networking.
17532 This service adds the @var{wicd} package to the global profile, providing
17533 several commands to interact with the daemon and configure networking:
17534 @command{wicd-client}, a graphical user interface, and the @command{wicd-cli}
17535 and @command{wicd-curses} user interfaces.
17538 @cindex ModemManager
17539 Some networking devices such as modems require special care, and this is
17540 what the services below focus on.
17542 @defvr {Scheme Variable} modem-manager-service-type
17543 This is the service type for the
17544 @uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
17545 service. The value for this service type is a
17546 @code{modem-manager-configuration} record.
17548 This service is part of @code{%desktop-services} (@pxref{Desktop
17552 @deftp {Data Type} modem-manager-configuration
17553 Data type representing the configuration of ModemManager.
17556 @item @code{modem-manager} (default: @code{modem-manager})
17557 The ModemManager package to use.
17562 @cindex USB_ModeSwitch
17563 @cindex Modeswitching
17565 @defvr {Scheme Variable} usb-modeswitch-service-type
17566 This is the service type for the
17567 @uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch}
17568 service. The value for this service type is
17569 a @code{usb-modeswitch-configuration} record.
17571 When plugged in, some USB modems (and other USB devices) initially present
17572 themselves as a read-only storage medium and not as a modem. They need to be
17573 @dfn{modeswitched} before they are usable. The USB_ModeSwitch service type
17574 installs udev rules to automatically modeswitch these devices when they are
17577 This service is part of @code{%desktop-services} (@pxref{Desktop
17581 @deftp {Data Type} usb-modeswitch-configuration
17582 Data type representing the configuration of USB_ModeSwitch.
17585 @item @code{usb-modeswitch} (default: @code{usb-modeswitch})
17586 The USB_ModeSwitch package providing the binaries for modeswitching.
17588 @item @code{usb-modeswitch-data} (default: @code{usb-modeswitch-data})
17589 The package providing the device data and udev rules file used by
17592 @item @code{config-file} (default: @code{#~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf")})
17593 Which config file to use for the USB_ModeSwitch dispatcher. By default the
17594 config file shipped with USB_ModeSwitch is used which disables logging to
17595 @file{/var/log} among other default settings. If set to @code{#f}, no config
17602 @node Networking Services
17603 @subsection Networking Services
17605 The @code{(gnu services networking)} module discussed in the previous
17606 section provides services for more advanced setups: providing a DHCP
17607 service for others to use, filtering packets with iptables or nftables,
17608 running a WiFi access point with @command{hostapd}, running the
17609 @command{inetd} ``superdaemon'', and more. This section describes
17612 @deffn {Scheme Procedure} dhcpd-service-type
17613 This type defines a service that runs a DHCP daemon. To create a
17614 service of this type, you must supply a @code{<dhcpd-configuration>}.
17618 (service dhcpd-service-type
17619 (dhcpd-configuration
17620 (config-file (local-file "my-dhcpd.conf"))
17621 (interfaces '("enp0s25"))))
17625 @deftp {Data Type} dhcpd-configuration
17627 @item @code{package} (default: @code{isc-dhcp})
17628 The package that provides the DHCP daemon. This package is expected to
17629 provide the daemon at @file{sbin/dhcpd} relative to its output
17630 directory. The default package is the
17631 @uref{https://www.isc.org/products/DHCP, ISC's DHCP server}.
17632 @item @code{config-file} (default: @code{#f})
17633 The configuration file to use. This is required. It will be passed to
17634 @code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
17635 object (@pxref{G-Expressions, file-like objects}). See @code{man
17636 dhcpd.conf} for details on the configuration file syntax.
17637 @item @code{version} (default: @code{"4"})
17638 The DHCP version to use. The ISC DHCP server supports the values ``4'',
17639 ``6'', and ``4o6''. These correspond to the @code{dhcpd} program
17640 options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for
17642 @item @code{run-directory} (default: @code{"/run/dhcpd"})
17643 The run directory to use. At service activation time, this directory
17644 will be created if it does not exist.
17645 @item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
17646 The PID file to use. This corresponds to the @code{-pf} option of
17647 @code{dhcpd}. See @code{man dhcpd} for details.
17648 @item @code{interfaces} (default: @code{'()})
17649 The names of the network interfaces on which dhcpd should listen for
17650 broadcasts. If this list is not empty, then its elements (which must be
17651 strings) will be appended to the @code{dhcpd} invocation when starting
17652 the daemon. It may not be necessary to explicitly specify any
17653 interfaces here; see @code{man dhcpd} for details.
17657 @cindex hostapd service, for Wi-Fi access points
17658 @cindex Wi-Fi access points, hostapd service
17659 @defvr {Scheme Variable} hostapd-service-type
17660 This is the service type to run the @uref{https://w1.fi/hostapd/,
17661 hostapd} daemon to set up WiFi (IEEE 802.11) access points and
17662 authentication servers. Its associated value must be a
17663 @code{hostapd-configuration} as shown below:
17666 ;; Use wlan1 to run the access point for "My Network".
17667 (service hostapd-service-type
17668 (hostapd-configuration
17669 (interface "wlan1")
17670 (ssid "My Network")
17675 @deftp {Data Type} hostapd-configuration
17676 This data type represents the configuration of the hostapd service, with
17677 the following fields:
17680 @item @code{package} (default: @code{hostapd})
17681 The hostapd package to use.
17683 @item @code{interface} (default: @code{"wlan0"})
17684 The network interface to run the WiFi access point.
17687 The SSID (@dfn{service set identifier}), a string that identifies this
17690 @item @code{broadcast-ssid?} (default: @code{#t})
17691 Whether to broadcast this SSID.
17693 @item @code{channel} (default: @code{1})
17694 The WiFi channel to use.
17696 @item @code{driver} (default: @code{"nl80211"})
17697 The driver interface type. @code{"nl80211"} is used with all Linux
17698 mac80211 drivers. Use @code{"none"} if building hostapd as a standalone
17699 RADIUS server that does # not control any wireless/wired driver.
17701 @item @code{extra-settings} (default: @code{""})
17702 Extra settings to append as-is to the hostapd configuration file. See
17703 @uref{https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf} for the
17704 configuration file reference.
17708 @defvr {Scheme Variable} simulated-wifi-service-type
17709 This is the type of a service to simulate WiFi networking, which can be
17710 useful in virtual machines for testing purposes. The service loads the
17712 @uref{https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html,
17713 @code{mac80211_hwsim} module} and starts hostapd to create a pseudo WiFi
17714 network that can be seen on @code{wlan0}, by default.
17716 The service's value is a @code{hostapd-configuration} record.
17721 @defvr {Scheme Variable} iptables-service-type
17722 This is the service type to set up an iptables configuration. iptables is a
17723 packet filtering framework supported by the Linux kernel. This service
17724 supports configuring iptables for both IPv4 and IPv6. A simple example
17725 configuration rejecting all incoming connections except those to the ssh port
17729 (service iptables-service-type
17730 (iptables-configuration
17731 (ipv4-rules (plain-file "iptables.rules" "*filter
17735 -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
17736 -A INPUT -p tcp --dport 22 -j ACCEPT
17737 -A INPUT -j REJECT --reject-with icmp-port-unreachable
17740 (ipv6-rules (plain-file "ip6tables.rules" "*filter
17744 -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
17745 -A INPUT -p tcp --dport 22 -j ACCEPT
17746 -A INPUT -j REJECT --reject-with icmp6-port-unreachable
17752 @deftp {Data Type} iptables-configuration
17753 The data type representing the configuration of iptables.
17756 @item @code{iptables} (default: @code{iptables})
17757 The iptables package that provides @code{iptables-restore} and
17758 @code{ip6tables-restore}.
17759 @item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules})
17760 The iptables rules to use. It will be passed to @code{iptables-restore}.
17761 This may be any ``file-like'' object (@pxref{G-Expressions, file-like
17763 @item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules})
17764 The ip6tables rules to use. It will be passed to @code{ip6tables-restore}.
17765 This may be any ``file-like'' object (@pxref{G-Expressions, file-like
17771 @defvr {Scheme Variable} nftables-service-type
17772 This is the service type to set up a nftables configuration. nftables is a
17773 netfilter project that aims to replace the existing iptables, ip6tables,
17774 arptables and ebtables framework. It provides a new packet filtering
17775 framework, a new user-space utility @command{nft}, and a compatibility layer
17776 for iptables. This service comes with a default ruleset
17777 @code{%default-nftables-ruleset} that rejecting all incoming connections
17778 except those to the ssh port 22. To use it, simply write:
17781 (service nftables-service-type)
17785 @deftp {Data Type} nftables-configuration
17786 The data type representing the configuration of nftables.
17789 @item @code{package} (default: @code{nftables})
17790 The nftables package that provides @command{nft}.
17791 @item @code{ruleset} (default: @code{%default-nftables-ruleset})
17792 The nftables ruleset to use. This may be any ``file-like'' object
17793 (@pxref{G-Expressions, file-like objects}).
17797 @cindex NTP (Network Time Protocol), service
17798 @cindex ntpd, service for the Network Time Protocol daemon
17799 @cindex real time clock
17800 @defvr {Scheme Variable} ntp-service-type
17801 This is the type of the service running the @uref{https://www.ntp.org,
17802 Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the
17803 system clock synchronized with that of the specified NTP servers.
17805 The value of this service is an @code{ntpd-configuration} object, as described
17809 @deftp {Data Type} ntp-configuration
17810 This is the data type for the NTP service configuration.
17813 @item @code{servers} (default: @code{%ntp-servers})
17814 This is the list of servers (@code{<ntp-server>} records) with which
17815 @command{ntpd} will be synchronized. See the @code{ntp-server} data type
17818 @item @code{allow-large-adjustment?} (default: @code{#t})
17819 This determines whether @command{ntpd} is allowed to make an initial
17820 adjustment of more than 1,000 seconds.
17822 @item @code{ntp} (default: @code{ntp})
17823 The NTP package to use.
17827 @defvr {Scheme Variable} %ntp-servers
17828 List of host names used as the default NTP servers. These are servers of the
17829 @uref{https://www.ntppool.org/en/, NTP Pool Project}.
17832 @deftp {Data Type} ntp-server
17833 The data type representing the configuration of a NTP server.
17836 @item @code{type} (default: @code{'server})
17837 The type of the NTP server, given as a symbol. One of @code{'pool},
17838 @code{'server}, @code{'peer}, @code{'broadcast} or @code{'manycastclient}.
17840 @item @code{address}
17841 The address of the server, as a string.
17843 @item @code{options}
17844 NTPD options to use with that specific server, given as a list of option names
17845 and/or of option names and values tuples. The following example define a server
17846 to use with the options @option{iburst} and @option{prefer}, as well as
17847 @option{version} 3 and a @option{maxpoll} time of 16 seconds.
17852 (address "some.ntp.server.org")
17853 (options `(iburst (version 3) (maxpoll 16) prefer))))
17859 @deffn {Scheme Procedure} openntpd-service-type
17860 Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
17861 by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system
17862 clock synchronized with that of the given servers.
17866 openntpd-service-type
17867 (openntpd-configuration
17868 (listen-on '("127.0.0.1" "::1"))
17869 (sensor '("udcf0 correction 70000"))
17870 (constraint-from '("www.gnu.org"))
17871 (constraints-from '("https://www.google.com/"))))
17876 @defvr {Scheme Variable} %openntpd-servers
17877 This variable is a list of the server addresses defined in
17878 @code{%ntp-servers}.
17881 @deftp {Data Type} openntpd-configuration
17883 @item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
17884 The openntpd executable to use.
17885 @item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
17886 A list of local IP addresses or hostnames the ntpd daemon should listen on.
17887 @item @code{query-from} (default: @code{'()})
17888 A list of local IP address the ntpd daemon should use for outgoing queries.
17889 @item @code{sensor} (default: @code{'()})
17890 Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
17891 will listen to each sensor that actually exists and ignore non-existent ones.
17892 See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
17894 @item @code{server} (default: @code{'()})
17895 Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
17896 @item @code{servers} (default: @code{%openntp-servers})
17897 Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
17898 @item @code{constraint-from} (default: @code{'()})
17899 @code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
17900 This time information is not used for precision but acts as an authenticated
17901 constraint, thereby reducing the impact of unauthenticated NTP
17902 man-in-the-middle attacks.
17903 Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide
17905 @item @code{constraints-from} (default: @code{'()})
17906 As with constraint from, specify a list of URLs, IP addresses or hostnames of
17907 HTTPS servers to provide a constraint. Should the hostname resolve to multiple
17908 IP addresses, @code{ntpd} will calculate a median constraint from all of them.
17913 @deffn {Scheme variable} inetd-service-type
17914 This service runs the @command{inetd} (@pxref{inetd invocation,,,
17915 inetutils, GNU Inetutils}) daemon. @command{inetd} listens for
17916 connections on internet sockets, and lazily starts the specified server
17917 program when a connection is made on one of these sockets.
17919 The value of this service is an @code{inetd-configuration} object. The
17920 following example configures the @command{inetd} daemon to provide the
17921 built-in @command{echo} service, as well as an smtp service which
17922 forwards smtp traffic over ssh to a server @code{smtp-server} behind a
17923 gateway @code{hostname}:
17928 (inetd-configuration
17932 (socket-type 'stream)
17939 (socket-type 'stream)
17943 (program (file-append openssh "/bin/ssh"))
17945 '("ssh" "-qT" "-i" "/path/to/ssh_key"
17946 "-W" "smtp-server:25" "user@@hostname")))))))
17949 See below for more details about @code{inetd-configuration}.
17952 @deftp {Data Type} inetd-configuration
17953 Data type representing the configuration of @command{inetd}.
17956 @item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
17957 The @command{inetd} executable to use.
17959 @item @code{entries} (default: @code{'()})
17960 A list of @command{inetd} service entries. Each entry should be created
17961 by the @code{inetd-entry} constructor.
17965 @deftp {Data Type} inetd-entry
17966 Data type representing an entry in the @command{inetd} configuration.
17967 Each entry corresponds to a socket where @command{inetd} will listen for
17971 @item @code{node} (default: @code{#f})
17972 Optional string, a comma-separated list of local addresses
17973 @command{inetd} should use when listening for this service.
17974 @xref{Configuration file,,, inetutils, GNU Inetutils} for a complete
17975 description of all options.
17977 A string, the name must correspond to an entry in @code{/etc/services}.
17978 @item @code{socket-type}
17979 One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
17981 @item @code{protocol}
17982 A string, must correspond to an entry in @code{/etc/protocols}.
17983 @item @code{wait?} (default: @code{#t})
17984 Whether @command{inetd} should wait for the server to exit before
17985 listening to new service requests.
17987 A string containing the user (and, optionally, group) name of the user
17988 as whom the server should run. The group name can be specified in a
17989 suffix, separated by a colon or period, i.e.@: @code{"user"},
17990 @code{"user:group"} or @code{"user.group"}.
17991 @item @code{program} (default: @code{"internal"})
17992 The server program which will serve the requests, or @code{"internal"}
17993 if @command{inetd} should use a built-in service.
17994 @item @code{arguments} (default: @code{'()})
17995 A list strings or file-like objects, which are the server program's
17996 arguments, starting with the zeroth argument, i.e.@: the name of the
17997 program itself. For @command{inetd}'s internal services, this entry
17998 must be @code{'()} or @code{'("internal")}.
18001 @xref{Configuration file,,, inetutils, GNU Inetutils} for a more
18002 detailed discussion of each configuration field.
18005 @cindex opendht, distributed hash table network service
18006 @cindex dhtproxy, for use with jami
18007 @defvr {Scheme Variable} opendht-service-type
18008 This is the type of the service running a @uref{https://opendht.net,
18009 OpenDHT} node, @command{dhtnode}. The daemon can be used to host your
18010 own proxy service to the distributed hash table (DHT), for example to
18011 connect to with Jami, among other applications.
18013 @quotation Important
18014 When using the OpenDHT proxy server, the IP addresses it ``sees'' from
18015 the clients should be addresses reachable from other peers. In practice
18016 this means that a publicly reachable address is best suited for a proxy
18017 server, outside of your private network. For example, hosting the proxy
18018 server on a IPv4 private local network and exposing it via port
18019 forwarding could work for external peers, but peers local to the proxy
18020 would have their private addresses shared with the external peers,
18021 leading to connectivity problems.
18024 The value of this service is a @code{opendht-configuration} object, as
18028 @deftp {Data Type} opendht-configuration
18029 This is the data type for the OpenDHT service configuration.
18031 @c The fields documentation has been auto-generated using the
18032 @c configuration->documentation procedure from
18033 @c (gnu services configuration).
18034 Available @code{opendht-configuration} fields are:
18036 @deftypevr {@code{opendht-configuration} parameter} package opendht
18037 The @code{opendht} package to use.
18041 @deftypevr {@code{opendht-configuration} parameter} boolean peer-discovery?
18042 Whether to enable the multicast local peer discovery mechanism.
18044 Defaults to @samp{#f}.
18048 @deftypevr {@code{opendht-configuration} parameter} boolean enable-logging?
18049 Whether to enable logging messages to syslog. It is disabled by default
18050 as it is rather verbose.
18052 Defaults to @samp{#f}.
18056 @deftypevr {@code{opendht-configuration} parameter} boolean debug?
18057 Whether to enable debug-level logging messages. This has no effect if
18058 logging is disabled.
18060 Defaults to @samp{#f}.
18064 @deftypevr {@code{opendht-configuration} parameter} maybe-string bootstrap-host
18065 The node host name that is used to make the first connection to the
18066 network. A specific port value can be provided by appending the
18067 @code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
18068 any host can be specified here. It's also possible to disable
18069 bootsrapping by setting this to the @code{'disabled} symbol.
18071 Defaults to @samp{"bootstrap.jami.net:4222"}.
18075 @deftypevr {@code{opendht-configuration} parameter} maybe-number port
18076 The UDP port to bind to. When set to @code{'disabled}, an available
18077 port is automatically selected.
18079 Defaults to @samp{4222}.
18083 @deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port
18084 Spawn a proxy server listening on the specified port.
18086 Defaults to @samp{disabled}.
18090 @deftypevr {@code{opendht-configuration} parameter} maybe-number proxy-server-port-tls
18091 Spawn a proxy server listening to TLS connections on the specified port.
18093 Defaults to @samp{disabled}.
18099 @defvr {Scheme Variable} tor-service-type
18100 This is the type for a service that runs the @uref{https://torproject.org,
18101 Tor} anonymous networking daemon. The service is configured using a
18102 @code{<tor-configuration>} record. By default, the Tor daemon runs as the
18103 @code{tor} unprivileged user, which is a member of the @code{tor} group.
18107 @deftp {Data Type} tor-configuration
18109 @item @code{tor} (default: @code{tor})
18110 The package that provides the Tor daemon. This package is expected to provide
18111 the daemon at @file{bin/tor} relative to its output directory. The default
18112 package is the @uref{https://www.torproject.org, Tor Project's}
18115 @item @code{config-file} (default: @code{(plain-file "empty" "")})
18116 The configuration file to use. It will be appended to a default configuration
18117 file, and the final configuration file will be passed to @code{tor} via its
18118 @code{-f} option. This may be any ``file-like'' object (@pxref{G-Expressions,
18119 file-like objects}). See @code{man tor} for details on the configuration file
18122 @item @code{hidden-services} (default: @code{'()})
18123 The list of @code{<hidden-service>} records to use. For any hidden service
18124 you include in this list, appropriate configuration to enable the hidden
18125 service will be automatically added to the default configuration file. You
18126 may conveniently create @code{<hidden-service>} records using the
18127 @code{tor-hidden-service} procedure described below.
18129 @item @code{socks-socket-type} (default: @code{'tcp})
18130 The default socket type that Tor should use for its SOCKS socket. This must
18131 be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by default
18132 Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost).
18133 If it is @code{'unix}, then Tor will listen on the UNIX domain socket
18134 @file{/var/run/tor/socks-sock}, which will be made writable by members of the
18137 If you want to customize the SOCKS socket in more detail, leave
18138 @code{socks-socket-type} at its default value of @code{'tcp} and use
18139 @code{config-file} to override the default by providing your own
18140 @code{SocksPort} option.
18142 @item @code{control-socket?} (default: @code{#f})
18143 Whether or not to provide a ``control socket'' by which Tor can be
18144 controlled to, for instance, dynamically instantiate tor onion services.
18145 If @code{#t}, Tor will listen for control commands on the UNIX domain socket
18146 @file{/var/run/tor/control-sock}, which will be made writable by members of the
18152 @cindex hidden service
18153 @deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
18154 Define a new Tor @dfn{hidden service} called @var{name} and implementing
18155 @var{mapping}. @var{mapping} is a list of port/host tuples, such as:
18158 '((22 "127.0.0.1:22")
18159 (80 "127.0.0.1:8080"))
18162 In this example, port 22 of the hidden service is mapped to local port 22, and
18163 port 80 is mapped to local port 8080.
18165 This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
18166 the @file{hostname} file contains the @code{.onion} host name for the hidden
18169 See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
18170 project's documentation} for more information.
18173 The @code{(gnu services rsync)} module provides the following services:
18175 You might want an rsync daemon if you have files that you want available
18176 so anyone (or just yourself) can download existing files or upload new
18179 @deffn {Scheme Variable} rsync-service-type
18180 This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
18181 The value for this service type is a
18182 @command{rsync-configuration} record as in this example:
18185 ;; Export two directories over rsync. By default rsync listens on
18186 ;; all the network interfaces.
18187 (service rsync-service-type
18188 (rsync-configuration
18189 (modules (list (rsync-module
18191 (file-name "/srv/zik")
18195 (file-name "/home/charlie/movies"))))))
18198 See below for details about @code{rsync-configuration}.
18201 @deftp {Data Type} rsync-configuration
18202 Data type representing the configuration for @code{rsync-service}.
18205 @item @code{package} (default: @var{rsync})
18206 @code{rsync} package to use.
18208 @item @code{address} (default: @code{#f})
18209 IP address on which @command{rsync} listens for incoming connections.
18210 If unspecified, it defaults to listening on all available addresses.
18212 @item @code{port-number} (default: @code{873})
18213 TCP port on which @command{rsync} listens for incoming connections. If port
18214 is less than @code{1024} @command{rsync} needs to be started as the
18215 @code{root} user and group.
18217 @item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
18218 Name of the file where @command{rsync} writes its PID.
18220 @item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
18221 Name of the file where @command{rsync} writes its lock file.
18223 @item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
18224 Name of the file where @command{rsync} writes its log file.
18226 @item @code{user} (default: @code{"root"})
18227 Owner of the @code{rsync} process.
18229 @item @code{group} (default: @code{"root"})
18230 Group of the @code{rsync} process.
18232 @item @code{uid} (default: @code{"rsyncd"})
18233 User name or user ID that file transfers to and from that module should take
18234 place as when the daemon was run as @code{root}.
18236 @item @code{gid} (default: @code{"rsyncd"})
18237 Group name or group ID that will be used when accessing the module.
18239 @item @code{modules} (default: @code{%default-modules})
18240 List of ``modules''---i.e., directories exported over rsync. Each
18241 element must be a @code{rsync-module} record, as described below.
18245 @deftp {Data Type} rsync-module
18246 This is the data type for rsync ``modules''. A module is a directory
18247 exported over the rsync protocol. The available fields are as follows:
18251 The module name. This is the name that shows up in URLs. For example,
18252 if the module is called @code{music}, the corresponding URL will be
18253 @code{rsync://host.example.org/music}.
18255 @item @code{file-name}
18256 Name of the directory being exported.
18258 @item @code{comment} (default: @code{""})
18259 Comment associated with the module. Client user interfaces may display
18260 it when they obtain the list of available modules.
18262 @item @code{read-only?} (default: @code{#t})
18263 Whether or not client will be able to upload files. If this is false,
18264 the uploads will be authorized if permissions on the daemon side permit
18267 @item @code{chroot?} (default: @code{#t})
18268 When this is true, the rsync daemon changes root to the module's
18269 directory before starting file transfers with the client. This improves
18270 security, but requires rsync to run as root.
18272 @item @code{timeout} (default: @code{300})
18273 Idle time in seconds after which the daemon closes a connection with the
18278 The @code{(gnu services syncthing)} module provides the following services:
18281 You might want a syncthing daemon if you have files between two or more
18282 computers and want to sync them in real time, safely protected from
18285 @deffn {Scheme Variable} syncthing-service-type
18286 This is the service type for the @uref{https://syncthing.net/,
18287 syncthing} daemon, The value for this service type is a
18288 @command{syncthing-configuration} record as in this example:
18291 (service syncthing-service-type
18292 (syncthing-configuration (user "alice")))
18295 See below for details about @code{syncthing-configuration}.
18297 @deftp {Data Type} syncthing-configuration
18298 Data type representing the configuration for @code{syncthing-service-type}.
18301 @item @code{syncthing} (default: @var{syncthing})
18302 @code{syncthing} package to use.
18304 @item @code{arguments} (default: @var{'()})
18305 List of command-line arguments passing to @code{syncthing} binary.
18307 @item @code{logflags} (default: @var{0})
18308 Sum of logging flags, see
18309 @uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags, Syncthing documentation logflags}.
18311 @item @code{user} (default: @var{#f})
18312 The user as which the Syncthing service is to be run.
18313 This assumes that the specified user exists.
18315 @item @code{group} (default: @var{"users"})
18316 The group as which the Syncthing service is to be run.
18317 This assumes that the specified group exists.
18319 @item @code{home} (default: @var{#f})
18320 Common configuration and data directory. The default configuration
18321 directory is @file{$HOME} of the specified Syncthing @code{user}.
18327 Furthermore, @code{(gnu services ssh)} provides the following services.
18331 @deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
18332 [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
18333 [#:allow-empty-passwords? #f] [#:root-login? #f] @
18334 [#:syslog-output? #t] [#:x11-forwarding? #t] @
18335 [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
18336 [#:public-key-authentication? #t] [#:initialize? #t]
18337 Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
18338 @var{host-key} must designate a file containing the host key, and readable
18341 When @var{daemonic?} is true, @command{lshd} will detach from the
18342 controlling terminal and log its output to syslogd, unless one sets
18343 @var{syslog-output?} to false. Obviously, it also makes lsh-service
18344 depend on existence of syslogd service. When @var{pid-file?} is true,
18345 @command{lshd} writes its PID to the file called @var{pid-file}.
18347 When @var{initialize?} is true, automatically create the seed and host key
18348 upon service activation if they do not exist yet. This may take long and
18349 require interaction.
18351 When @var{initialize?} is false, it is up to the user to initialize the
18352 randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
18353 a key pair with the private key stored in file @var{host-key} (@pxref{lshd
18354 basics,,, lsh, LSH Manual}).
18356 When @var{interfaces} is empty, lshd listens for connections on all the
18357 network interfaces; otherwise, @var{interfaces} must be a list of host names
18360 @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
18361 passwords, and @var{root-login?} specifies whether to accept log-ins as
18364 The other options should be self-descriptive.
18369 @deffn {Scheme Variable} openssh-service-type
18370 This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
18371 shell daemon, @command{sshd}. Its value must be an
18372 @code{openssh-configuration} record as in this example:
18375 (service openssh-service-type
18376 (openssh-configuration
18377 (x11-forwarding? #t)
18378 (permit-root-login 'prohibit-password)
18380 `(("alice" ,(local-file "alice.pub"))
18381 ("bob" ,(local-file "bob.pub"))))))
18384 See below for details about @code{openssh-configuration}.
18386 This service can be extended with extra authorized keys, as in this
18390 (service-extension openssh-service-type
18391 (const `(("charlie"
18392 ,(local-file "charlie.pub")))))
18396 @deftp {Data Type} openssh-configuration
18397 This is the configuration record for OpenSSH's @command{sshd}.
18400 @item @code{openssh} (default @var{openssh})
18401 The Openssh package to use.
18403 @item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
18404 Name of the file where @command{sshd} writes its PID.
18406 @item @code{port-number} (default: @code{22})
18407 TCP port on which @command{sshd} listens for incoming connections.
18409 @item @code{permit-root-login} (default: @code{#f})
18410 This field determines whether and when to allow logins as root. If
18411 @code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
18412 If it's the symbol @code{'prohibit-password}, then root logins are
18413 permitted but not with password-based authentication.
18415 @item @code{allow-empty-passwords?} (default: @code{#f})
18416 When true, users with empty passwords may log in. When false, they may
18419 @item @code{password-authentication?} (default: @code{#t})
18420 When true, users may log in with their password. When false, they have
18421 other authentication methods.
18423 @item @code{public-key-authentication?} (default: @code{#t})
18424 When true, users may log in using public key authentication. When
18425 false, users have to use other authentication method.
18427 Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
18428 This is used only by protocol version 2.
18430 @item @code{x11-forwarding?} (default: @code{#f})
18431 When true, forwarding of X11 graphical client connections is
18432 enabled---in other words, @command{ssh} options @option{-X} and
18433 @option{-Y} will work.
18435 @item @code{allow-agent-forwarding?} (default: @code{#t})
18436 Whether to allow agent forwarding.
18438 @item @code{allow-tcp-forwarding?} (default: @code{#t})
18439 Whether to allow TCP forwarding.
18441 @item @code{gateway-ports?} (default: @code{#f})
18442 Whether to allow gateway ports.
18444 @item @code{challenge-response-authentication?} (default: @code{#f})
18445 Specifies whether challenge response authentication is allowed (e.g.@: via
18448 @item @code{use-pam?} (default: @code{#t})
18449 Enables the Pluggable Authentication Module interface. If set to
18450 @code{#t}, this will enable PAM authentication using
18451 @code{challenge-response-authentication?} and
18452 @code{password-authentication?}, in addition to PAM account and session
18453 module processing for all authentication types.
18455 Because PAM challenge response authentication usually serves an
18456 equivalent role to password authentication, you should disable either
18457 @code{challenge-response-authentication?} or
18458 @code{password-authentication?}.
18460 @item @code{print-last-log?} (default: @code{#t})
18461 Specifies whether @command{sshd} should print the date and time of the
18462 last user login when a user logs in interactively.
18464 @item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
18465 Configures external subsystems (e.g.@: file transfer daemon).
18467 This is a list of two-element lists, each of which containing the
18468 subsystem name and a command (with optional arguments) to execute upon
18471 The command @command{internal-sftp} implements an in-process SFTP
18472 server. Alternatively, one can specify the @command{sftp-server} command:
18474 (service openssh-service-type
18475 (openssh-configuration
18477 `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
18480 @item @code{accepted-environment} (default: @code{'()})
18481 List of strings describing which environment variables may be exported.
18483 Each string gets on its own line. See the @code{AcceptEnv} option in
18484 @code{man sshd_config}.
18486 This example allows ssh-clients to export the @env{COLORTERM} variable.
18487 It is set by terminal emulators, which support colors. You can use it in
18488 your shell's resource file to enable colors for the prompt and commands
18489 if this variable is set.
18492 (service openssh-service-type
18493 (openssh-configuration
18494 (accepted-environment '("COLORTERM"))))
18497 @item @code{authorized-keys} (default: @code{'()})
18498 @cindex authorized keys, SSH
18499 @cindex SSH authorized keys
18500 This is the list of authorized keys. Each element of the list is a user
18501 name followed by one or more file-like objects that represent SSH public
18505 (openssh-configuration
18507 `(("rekado" ,(local-file "rekado.pub"))
18508 ("chris" ,(local-file "chris.pub"))
18509 ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
18513 registers the specified public keys for user accounts @code{rekado},
18514 @code{chris}, and @code{root}.
18516 Additional authorized keys can be specified @i{via}
18517 @code{service-extension}.
18519 Note that this does @emph{not} interfere with the use of
18520 @file{~/.ssh/authorized_keys}.
18522 @item @code{log-level} (default: @code{'info})
18523 This is a symbol specifying the logging level: @code{quiet}, @code{fatal},
18524 @code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man
18525 page for @file{sshd_config} for the full list of level names.
18527 @item @code{extra-content} (default: @code{""})
18528 This field can be used to append arbitrary text to the configuration file. It
18529 is especially useful for elaborate configurations that cannot be expressed
18530 otherwise. This configuration, for example, would generally disable root
18531 logins, but permit them from one specific IP address:
18534 (openssh-configuration
18536 Match Address 192.168.0.1
18537 PermitRootLogin yes"))
18543 @deffn {Scheme Procedure} dropbear-service [@var{config}]
18544 Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
18545 daemon} with the given @var{config}, a @code{<dropbear-configuration>}
18548 For example, to specify a Dropbear service listening on port 1234, add
18549 this call to the operating system's @code{services} field:
18552 (dropbear-service (dropbear-configuration
18553 (port-number 1234)))
18557 @deftp {Data Type} dropbear-configuration
18558 This data type represents the configuration of a Dropbear SSH daemon.
18561 @item @code{dropbear} (default: @var{dropbear})
18562 The Dropbear package to use.
18564 @item @code{port-number} (default: 22)
18565 The TCP port where the daemon waits for incoming connections.
18567 @item @code{syslog-output?} (default: @code{#t})
18568 Whether to enable syslog output.
18570 @item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
18571 File name of the daemon's PID file.
18573 @item @code{root-login?} (default: @code{#f})
18574 Whether to allow @code{root} logins.
18576 @item @code{allow-empty-passwords?} (default: @code{#f})
18577 Whether to allow empty passwords.
18579 @item @code{password-authentication?} (default: @code{#t})
18580 Whether to enable password-based authentication.
18585 @deffn {Scheme Variable} autossh-service-type
18586 This is the type for the @uref{https://www.harding.motd.ca/autossh,
18587 AutoSSH} program that runs a copy of @command{ssh} and monitors it,
18588 restarting it as necessary should it die or stop passing traffic.
18589 AutoSSH can be run manually from the command-line by passing arguments
18590 to the binary @command{autossh} from the package @code{autossh}, but it
18591 can also be run as a Guix service. This latter use case is documented
18594 AutoSSH can be used to forward local traffic to a remote machine using
18595 an SSH tunnel, and it respects the @file{~/.ssh/config} of the user it
18598 For example, to specify a service running autossh as the user
18599 @code{pino} and forwarding all local connections to port @code{8081} to
18600 @code{remote:8081} using an SSH tunnel, add this call to the operating
18601 system's @code{services} field:
18604 (service autossh-service-type
18605 (autossh-configuration
18607 (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))
18611 @deftp {Data Type} autossh-configuration
18612 This data type represents the configuration of an AutoSSH service.
18616 @item @code{user} (default @code{"autossh"})
18617 The user as which the AutoSSH service is to be run.
18618 This assumes that the specified user exists.
18620 @item @code{poll} (default @code{600})
18621 Specifies the connection poll time in seconds.
18623 @item @code{first-poll} (default @code{#f})
18624 Specifies how many seconds AutoSSH waits before the first connection
18625 test. After this first test, polling is resumed at the pace defined in
18626 @code{poll}. When set to @code{#f}, the first poll is not treated
18627 specially and will also use the connection poll specified in
18630 @item @code{gate-time} (default @code{30})
18631 Specifies how many seconds an SSH connection must be active before it is
18632 considered successful.
18634 @item @code{log-level} (default @code{1})
18635 The log level, corresponding to the levels used by syslog---so @code{0}
18636 is the most silent while @code{7} is the chattiest.
18638 @item @code{max-start} (default @code{#f})
18639 The maximum number of times SSH may be (re)started before AutoSSH exits.
18640 When set to @code{#f}, no maximum is configured and AutoSSH may restart indefinitely.
18642 @item @code{message} (default @code{""})
18643 The message to append to the echo message sent when testing connections.
18645 @item @code{port} (default @code{"0"})
18646 The ports used for monitoring the connection. When set to @code{"0"},
18647 monitoring is disabled. When set to @code{"@var{n}"} where @var{n} is
18648 a positive integer, ports @var{n} and @var{n}+1 are used for
18649 monitoring the connection, such that port @var{n} is the base
18650 monitoring port and @code{n+1} is the echo port. When set to
18651 @code{"@var{n}:@var{m}"} where @var{n} and @var{m} are positive
18652 integers, the ports @var{n} and @var{m} are used for monitoring the
18653 connection, such that port @var{n} is the base monitoring port and
18654 @var{m} is the echo port.
18656 @item @code{ssh-options} (default @code{'()})
18657 The list of command-line arguments to pass to @command{ssh} when it is
18658 run. Options @option{-f} and @option{-M} are reserved for AutoSSH and
18659 may cause undefined behaviour.
18665 @deffn {Scheme Variable} webssh-service-type
18666 This is the type for the @uref{https://webssh.huashengdun.org/, WebSSH}
18667 program that runs a web SSH client. WebSSH can be run manually from the
18668 command-line by passing arguments to the binary @command{wssh} from the
18669 package @code{webssh}, but it can also be run as a Guix service. This
18670 latter use case is documented here.
18672 For example, to specify a service running WebSSH on loopback interface
18673 on port @code{8888} with reject policy with a list of allowed to
18674 connection hosts, and NGINX as a reverse-proxy to this service listening
18675 for HTTPS connection, add this call to the operating system's
18676 @code{services} field:
18679 (service webssh-service-type
18680 (webssh-configuration (address "127.0.0.1")
18683 (known-hosts '("localhost ecdsa-sha2-nistp256 AAAA…"
18684 "127.0.0.1 ecdsa-sha2-nistp256 AAAA…"))))
18686 (service nginx-service-type
18687 (nginx-configuration
18690 (nginx-server-configuration
18691 (inherit %webssh-configuration-nginx)
18692 (server-name '("webssh.example.com"))
18693 (listen '("443 ssl"))
18694 (ssl-certificate (letsencrypt-certificate "webssh.example.com"))
18695 (ssl-certificate-key (letsencrypt-key "webssh.example.com"))
18697 (cons (nginx-location-configuration
18698 (uri "/.well-known")
18699 (body '("root /var/www;")))
18700 (nginx-server-configuration-locations %webssh-configuration-nginx))))))))
18704 @deftp {Data Type} webssh-configuration
18705 Data type representing the configuration for @code{webssh-service}.
18708 @item @code{package} (default: @var{webssh})
18709 @code{webssh} package to use.
18711 @item @code{user-name} (default: @var{"webssh"})
18712 User name or user ID that file transfers to and from that module should take
18715 @item @code{group-name} (default: @var{"webssh"})
18716 Group name or group ID that will be used when accessing the module.
18718 @item @code{address} (default: @var{#f})
18719 IP address on which @command{webssh} listens for incoming connections.
18721 @item @code{port} (default: @var{8888})
18722 TCP port on which @command{webssh} listens for incoming connections.
18724 @item @code{policy} (default: @var{#f})
18725 Connection policy. @var{reject} policy requires to specify @var{known-hosts}.
18727 @item @code{known-hosts} (default: @var{'()})
18728 List of hosts which allowed for SSH connection from @command{webssh}.
18730 @item @code{log-file} (default: @file{"/var/log/webssh.log"})
18731 Name of the file where @command{webssh} writes its log file.
18733 @item @code{log-level} (default: @var{#f})
18739 @defvr {Scheme Variable} %facebook-host-aliases
18740 This variable contains a string for use in @file{/etc/hosts}
18741 (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
18742 line contains a entry that maps a known server name of the Facebook
18743 on-line service---e.g., @code{www.facebook.com}---to the local
18744 host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
18746 This variable is typically used in the @code{hosts-file} field of an
18747 @code{operating-system} declaration (@pxref{operating-system Reference,
18748 @file{/etc/hosts}}):
18751 (use-modules (gnu) (guix))
18754 (host-name "mymachine")
18757 ;; Create a /etc/hosts file with aliases for "localhost"
18758 ;; and "mymachine", as well as for Facebook servers.
18759 (plain-file "hosts"
18760 (string-append (local-host-aliases host-name)
18761 %facebook-host-aliases))))
18764 This mechanism can prevent programs running locally, such as Web
18765 browsers, from accessing Facebook.
18768 The @code{(gnu services avahi)} provides the following definition.
18770 @defvr {Scheme Variable} avahi-service-type
18771 This is the service that runs @command{avahi-daemon}, a system-wide
18772 mDNS/DNS-SD responder that allows for service discovery and
18773 ``zero-configuration'' host name lookups (see @uref{https://avahi.org/}).
18774 Its value must be an @code{avahi-configuration} record---see below.
18776 This service extends the name service cache daemon (nscd) so that it can
18777 resolve @code{.local} host names using
18778 @uref{https://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name
18779 Service Switch}, for information on host name resolution.
18781 Additionally, add the @var{avahi} package to the system profile so that
18782 commands such as @command{avahi-browse} are directly usable.
18785 @deftp {Data Type} avahi-configuration
18786 Data type representation the configuration for Avahi.
18790 @item @code{host-name} (default: @code{#f})
18791 If different from @code{#f}, use that as the host name to
18792 publish for this machine; otherwise, use the machine's actual host name.
18794 @item @code{publish?} (default: @code{#t})
18795 When true, allow host names and services to be published (broadcast) over the
18798 @item @code{publish-workstation?} (default: @code{#t})
18799 When true, @command{avahi-daemon} publishes the machine's host name and IP
18800 address via mDNS on the local network. To view the host names published on
18801 your local network, you can run:
18804 avahi-browse _workstation._tcp
18807 @item @code{wide-area?} (default: @code{#f})
18808 When true, DNS-SD over unicast DNS is enabled.
18810 @item @code{ipv4?} (default: @code{#t})
18811 @itemx @code{ipv6?} (default: @code{#t})
18812 These fields determine whether to use IPv4/IPv6 sockets.
18814 @item @code{domains-to-browse} (default: @code{'()})
18815 This is a list of domains to browse.
18819 @deffn {Scheme Variable} openvswitch-service-type
18820 This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
18821 service, whose value should be an @code{openvswitch-configuration}
18825 @deftp {Data Type} openvswitch-configuration
18826 Data type representing the configuration of Open vSwitch, a multilayer
18827 virtual switch which is designed to enable massive network automation
18828 through programmatic extension.
18831 @item @code{package} (default: @var{openvswitch})
18832 Package object of the Open vSwitch.
18837 @defvr {Scheme Variable} pagekite-service-type
18838 This is the service type for the @uref{https://pagekite.net, PageKite} service,
18839 a tunneling solution for making localhost servers publicly visible, even from
18840 behind restrictive firewalls or NAT without forwarded ports. The value for
18841 this service type is a @code{pagekite-configuration} record.
18843 Here's an example exposing the local HTTP and SSH daemons:
18846 (service pagekite-service-type
18847 (pagekite-configuration
18848 (kites '("http:@@kitename:localhost:80:@@kitesecret"
18849 "raw/22:@@kitename:localhost:22:@@kitesecret"))
18850 (extra-file "/etc/pagekite.rc")))
18854 @deftp {Data Type} pagekite-configuration
18855 Data type representing the configuration of PageKite.
18858 @item @code{package} (default: @var{pagekite})
18859 Package object of PageKite.
18861 @item @code{kitename} (default: @code{#f})
18862 PageKite name for authenticating to the frontend server.
18864 @item @code{kitesecret} (default: @code{#f})
18865 Shared secret for authenticating to the frontend server. You should probably
18866 put this inside @code{extra-file} instead.
18868 @item @code{frontend} (default: @code{#f})
18869 Connect to the named PageKite frontend server instead of the
18870 @uref{https://pagekite.net,,pagekite.net} service.
18872 @item @code{kites} (default: @code{'("http:@@kitename:localhost:80:@@kitesecret")})
18873 List of service kites to use. Exposes HTTP on port 80 by default. The format
18874 is @code{proto:kitename:host:port:secret}.
18876 @item @code{extra-file} (default: @code{#f})
18877 Extra configuration file to read, which you are expected to create manually.
18878 Use this to add additional options and manage shared secrets out-of-band.
18883 @defvr {Scheme Variable} yggdrasil-service-type
18884 The service type for connecting to the @uref{https://yggdrasil-network.github.io/,
18885 Yggdrasil network}, an early-stage implementation of a fully end-to-end
18886 encrypted IPv6 network.
18889 Yggdrasil provides name-independent routing with cryptographically generated
18890 addresses. Static addressing means you can keep the same address as long as
18891 you want, even if you move to a new location, or generate a new address (by
18892 generating new keys) whenever you want.
18893 @uref{https://yggdrasil-network.github.io/2018/07/28/addressing.html}
18896 Pass it a value of @code{yggdrasil-configuration} to connect it to public
18897 peers and/or local peers.
18899 Here is an example using public peers and a static address. The static
18900 signing and encryption keys are defined in @file{/etc/yggdrasil-private.conf}
18901 (the default value for @code{config-file}).
18904 ;; part of the operating-system declaration
18905 (service yggdrasil-service-type
18906 (yggdrasil-configuration
18907 (autoconf? #f) ;; use only the public peers
18910 ;; https://github.com/yggdrasil-network/public-peers
18911 '((peers . #("tcp://1.2.3.4:1337"))))
18912 ;; /etc/yggdrasil-private.conf is the default value for config-file
18916 # sample content for /etc/yggdrasil-private.conf
18918 # Your public encryption key. Your peers may ask you for this to put
18919 # into their AllowedEncryptionPublicKeys configuration.
18920 EncryptionPublicKey: 378dc5...
18922 # Your private encryption key. DO NOT share this with anyone!
18923 EncryptionPrivateKey: 0777...
18925 # Your public signing key. You should not ordinarily need to share
18926 # this with anyone.
18927 SigningPublicKey: e1664...
18929 # Your private signing key. DO NOT share this with anyone!
18930 SigningPrivateKey: 0589d...
18935 @deftp {Data Type} yggdrasil-configuration
18936 Data type representing the configuration of Yggdrasil.
18939 @item @code{package} (default: @code{yggdrasil})
18940 Package object of Yggdrasil.
18942 @item @code{json-config} (default: @code{'()})
18943 Contents of @file{/etc/yggdrasil.conf}. Will be merged with
18944 @file{/etc/yggdrasil-private.conf}. Note that these settings are stored in
18945 the Guix store, which is readable to all users. @strong{Do not store your
18946 private keys in it}. See the output of @code{yggdrasil -genconf} for a
18947 quick overview of valid keys and their default values.
18949 @item @code{autoconf?} (default: @code{#f})
18950 Whether to use automatic mode. Enabling it makes Yggdrasil use adynamic IP
18951 and peer with IPv6 neighbors.
18953 @item @code{log-level} (default: @code{'info})
18954 How much detail to include in logs. Use @code{'debug} for more detail.
18956 @item @code{log-to} (default: @code{'stdout})
18957 Where to send logs. By default, the service logs standard output to
18958 @file{/var/log/yggdrasil.log}. The alternative is @code{'syslog}, which
18959 sends output to the running syslog service.
18961 @item @code{config-file} (default: @code{"/etc/yggdrasil-private.conf"})
18962 What HJSON file to load sensitive data from. This is where private keys
18963 should be stored, which are necessary to specify if you don't want a
18964 randomized address after each restart. Use @code{#f} to disable. Options
18965 defined in this file take precedence over @code{json-config}. Use the output
18966 of @code{yggdrasil -genconf} as a starting point. To configure a static
18967 address, delete everything except these options:
18970 @item @code{EncryptionPublicKey}
18971 @item @code{EncryptionPrivateKey}
18972 @item @code{SigningPublicKey}
18973 @item @code{SigningPrivateKey}
18979 @defvr {Scheme Variable} ipfs-service-type
18980 The service type for connecting to the @uref{https://ipfs.io,IPFS network},
18981 a global, versioned, peer-to-peer file system. Pass it a
18982 @code{ipfs-configuration} to change the ports used for the gateway and API.
18984 Here's an example configuration, using some non-standard ports:
18987 (service ipfs-service-type
18988 (ipfs-configuration
18989 (gateway "/ip4/127.0.0.1/tcp/8880")
18990 (api "/ip4/127.0.0.1/tcp/8881")))
18994 @deftp {Data Type} ipfs-configuration
18995 Data type representing the configuration of IPFS.
18998 @item @code{package} (default: @code{go-ipfs})
18999 Package object of IPFS.
19001 @item @code{gateway} (default: @code{"/ip4/127.0.0.1/tcp/8082"})
19002 Address of the gateway, in ‘multiaddress’ format.
19004 @item @code{api} (default: @code{"/ip4/127.0.0.1/tcp/5001"})
19005 Address of the API endpoint, in ‘multiaddress’ format.
19010 @deffn {Scheme Variable} keepalived-service-type
19011 This is the type for the @uref{https://www.keepalived.org/, Keepalived}
19012 routing software, @command{keepalived}. Its value must be an
19013 @code{keepalived-configuration} record as in this example for master
19017 (service keepalived-service-type
19018 (keepalived-configuration
19019 (config-file (local-file "keepalived-master.conf"))))
19022 where @file{keepalived-master.conf}:
19025 vrrp_instance my-group @{
19028 virtual_router_id 100
19030 unicast_peer @{ 10.0.0.2 @}
19031 virtual_ipaddress @{
19037 and for backup machine:
19040 (service keepalived-service-type
19041 (keepalived-configuration
19042 (config-file (local-file "keepalived-backup.conf"))))
19045 where @file{keepalived-backup.conf}:
19048 vrrp_instance my-group @{
19051 virtual_router_id 100
19053 unicast_peer @{ 10.0.0.3 @}
19054 virtual_ipaddress @{
19061 @node Unattended Upgrades
19062 @subsection Unattended Upgrades
19064 @cindex unattended upgrades
19065 @cindex upgrades, unattended
19066 Guix provides a service to perform @emph{unattended upgrades}:
19067 periodically, the system automatically reconfigures itself from the
19068 latest Guix. Guix System has several properties that make unattended
19073 upgrades are transactional (either the upgrade succeeds or it fails, but
19074 you cannot end up with an ``in-between'' system state);
19076 the upgrade log is kept---you can view it with @command{guix system
19077 list-generations}---and you can roll back to any previous generation,
19078 should the upgraded system fail to behave as intended;
19080 channel code is authenticated so you know you can only run genuine code
19081 (@pxref{Channels});
19083 @command{guix system reconfigure} prevents downgrades, which makes it
19084 immune to @dfn{downgrade attacks}.
19087 To set up unattended upgrades, add an instance of
19088 @code{unattended-upgrade-service-type} like the one below to the list of
19089 your operating system services:
19092 (service unattended-upgrade-service-type)
19095 The defaults above set up weekly upgrades: every Sunday at midnight.
19096 You do not need to provide the operating system configuration file: it
19097 uses @file{/run/current-system/configuration.scm}, which ensures it
19098 always uses your latest configuration---@pxref{provenance-service-type},
19099 for more information about this file.
19101 There are several things that can be configured, in particular the
19102 periodicity and services (daemons) to be restarted upon completion.
19103 When the upgrade is successful, the service takes care of deleting
19104 system generations older that some threshold, as per @command{guix
19105 system delete-generations}. See the reference below for details.
19107 To ensure that upgrades are actually happening, you can run
19108 @command{guix system describe}. To investigate upgrade failures, visit
19109 the unattended upgrade log file (see below).
19111 @defvr {Scheme Variable} unattended-upgrade-service-type
19112 This is the service type for unattended upgrades. It sets up an mcron
19113 job (@pxref{Scheduled Job Execution}) that runs @command{guix system
19114 reconfigure} from the latest version of the specified channels.
19116 Its value must be a @code{unattended-upgrade-configuration} record (see
19120 @deftp {Data Type} unattended-upgrade-configuration
19121 This data type represents the configuration of the unattended upgrade
19122 service. The following fields are available:
19125 @item @code{schedule} (default: @code{"30 01 * * 0"})
19126 This is the schedule of upgrades, expressed as a gexp containing an
19127 mcron job schedule (@pxref{Guile Syntax, mcron job specifications,,
19128 mcron, GNU@tie{}mcron}).
19130 @item @code{channels} (default: @code{#~%default-channels})
19131 This gexp specifies the channels to use for the upgrade
19132 (@pxref{Channels}). By default, the tip of the official @code{guix}
19135 @item @code{operating-system-file} (default: @code{"/run/current-system/configuration.scm"})
19136 This field specifies the operating system configuration file to use.
19137 The default is to reuse the config file of the current configuration.
19139 There are cases, though, where referring to
19140 @file{/run/current-system/configuration.scm} is not enough, for instance
19141 because that file refers to extra files (SSH public keys, extra
19142 configuration files, etc.) @i{via} @code{local-file} and similar
19143 constructs. For those cases, we recommend something along these lines:
19146 (unattended-upgrade-configuration
19147 (operating-system-file
19148 (file-append (local-file "." "config-dir" #:recursive? #t)
19152 The effect here is to import all of the current directory into the
19153 store, and to refer to @file{config.scm} within that directory.
19154 Therefore, uses of @code{local-file} within @file{config.scm} will work
19155 as expected. @xref{G-Expressions}, for information about
19156 @code{local-file} and @code{file-append}.
19158 @item @code{services-to-restart} (default: @code{'(mcron)})
19159 This field specifies the Shepherd services to restart when the upgrade
19162 Those services are restarted right away upon completion, as with
19163 @command{herd restart}, which ensures that the latest version is
19164 running---remember that by default @command{guix system reconfigure}
19165 only restarts services that are not currently running, which is
19166 conservative: it minimizes disruption but leaves outdated services
19169 Use @command{herd status} to find out candidates for restarting.
19170 @xref{Services}, for general information about services. Common
19171 services to restart would include @code{ntpd} and @code{ssh-daemon}.
19173 By default, the @code{mcron} service is restarted. This ensures that
19174 the latest version of the unattended upgrade job will be used next time.
19176 @item @code{system-expiration} (default: @code{(* 3 30 24 3600)})
19177 This is the expiration time in seconds for system generations. System
19178 generations older that this amount of time are deleted with
19179 @command{guix system delete-generations} when an upgrade completes.
19182 The unattended upgrade service does not run the garbage collector. You
19183 will probably want to set up your own mcron job to run @command{guix gc}
19187 @item @code{maximum-duration} (default: @code{3600})
19188 Maximum duration in seconds for the upgrade; past that time, the upgrade
19191 This is primarily useful to ensure the upgrade does not end up
19192 rebuilding or re-downloading ``the world''.
19194 @item @code{log-file} (default: @code{"/var/log/unattended-upgrade.log"})
19195 File where unattended upgrades are logged.
19200 @subsection X Window
19203 @cindex X Window System
19204 @cindex login manager
19205 Support for the X Window graphical display system---specifically
19206 Xorg---is provided by the @code{(gnu services xorg)} module. Note that
19207 there is no @code{xorg-service} procedure. Instead, the X server is
19208 started by the @dfn{login manager}, by default the GNOME Display Manager (GDM).
19211 @cindex GNOME, login manager
19212 GDM of course allows users to log in into window managers and desktop
19213 environments other than GNOME; for those using GNOME, GDM is required for
19214 features such as automatic screen locking.
19216 @cindex window manager
19217 To use X11, you must install at least one @dfn{window manager}---for
19218 example the @code{windowmaker} or @code{openbox} packages---preferably
19219 by adding it to the @code{packages} field of your operating system
19220 definition (@pxref{operating-system Reference, system-wide packages}).
19222 @anchor{wayland-gdm}
19223 GDM also supports Wayland: it can itself use Wayland instead of X11 for
19224 its user interface, and it can also start Wayland sessions. The former is
19225 required for the latter, to enable, set @code{wayland?} to @code{#t} in
19226 @code{gdm-configuration}.
19228 @defvr {Scheme Variable} gdm-service-type
19229 This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME
19230 Desktop Manager} (GDM), a program that manages graphical display servers and
19231 handles graphical user logins. Its value must be a @code{gdm-configuration}
19234 @cindex session types
19235 GDM looks for @dfn{session types} described by the @file{.desktop} files in
19236 @file{/run/current-system/profile/share/xsessions} (for X11 sessions) and
19237 @file{/run/current-system/profile/share/wayland-sessions} (for Wayland
19238 sessions) and allows users to choose a session from the log-in screen.
19239 Packages such as @code{gnome}, @code{xfce}, @code{i3} and @code{sway} provide
19240 @file{.desktop} files; adding them to the system-wide set of packages
19241 automatically makes them available at the log-in screen.
19243 In addition, @file{~/.xsession} files are honored. When available,
19244 @file{~/.xsession} must be an executable that starts a window manager
19245 and/or other X clients.
19248 @deftp {Data Type} gdm-configuration
19250 @item @code{auto-login?} (default: @code{#f})
19251 @itemx @code{default-user} (default: @code{#f})
19252 When @code{auto-login?} is false, GDM presents a log-in screen.
19254 When @code{auto-login?} is true, GDM logs in directly as
19255 @code{default-user}.
19257 @item @code{debug?} (default: @code{#f})
19258 When true, GDM writes debug messages to its log.
19260 @item @code{gnome-shell-assets} (default: ...)
19261 List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.
19263 @item @code{xorg-configuration} (default: @code{(xorg-configuration)})
19264 Configuration of the Xorg graphical server.
19266 @item @code{xsession} (default: @code{(xinitrc)})
19267 Script to run before starting a X session.
19269 @item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
19270 File name of the @code{dbus-daemon} executable.
19272 @item @code{gdm} (default: @code{gdm})
19273 The GDM package to use.
19275 @item @code{wayland?} (default: @code{#f})
19276 When true, enables Wayland in GDM, necessary to use Wayland sessions.
19278 @item @code{wayland-session} (default: @code{gdm-wayland-session-wrapper})
19279 The Wayland session wrapper to use, needed to setup the
19284 @defvr {Scheme Variable} slim-service-type
19285 This is the type for the SLiM graphical login manager for X11.
19287 Like GDM, SLiM looks for session types described by @file{.desktop} files and
19288 allows users to choose a session from the log-in screen using @kbd{F1}. It
19289 also honors @file{~/.xsession} files.
19291 Unlike GDM, SLiM does not spawn the user session on a different VT after
19292 logging in, which means that you can only start one graphical session. If you
19293 want to be able to run multiple graphical sessions at the same time you have
19294 to add multiple SLiM services to your system services. The following example
19295 shows how to replace the default GDM service with two SLiM services on tty7
19299 (use-modules (gnu services)
19300 (gnu services desktop)
19301 (gnu services xorg))
19305 (services (cons* (service slim-service-type (slim-configuration
19308 (service slim-service-type (slim-configuration
19311 (modify-services %desktop-services
19312 (delete gdm-service-type)))))
19317 @deftp {Data Type} slim-configuration
19318 Data type representing the configuration of @code{slim-service-type}.
19321 @item @code{allow-empty-passwords?} (default: @code{#t})
19322 Whether to allow logins with empty passwords.
19324 @item @code{gnupg?} (default: @code{#f})
19325 If enabled, @code{pam-gnupg} will attempt to automatically unlock the
19326 user's GPG keys with the login password via @code{gpg-agent}. The
19327 keygrips of all keys to be unlocked should be written to
19328 @file{~/.pam-gnupg}, and can be queried with @code{gpg -K
19329 --with-keygrip}. Presetting passphrases must be enabled by adding
19330 @code{allow-preset-passphrase} in @file{~/.gnupg/gpg-agent.conf}.
19332 @item @code{auto-login?} (default: @code{#f})
19333 @itemx @code{default-user} (default: @code{""})
19334 When @code{auto-login?} is false, SLiM presents a log-in screen.
19336 When @code{auto-login?} is true, SLiM logs in directly as
19337 @code{default-user}.
19339 @item @code{theme} (default: @code{%default-slim-theme})
19340 @itemx @code{theme-name} (default: @code{%default-slim-theme-name})
19341 The graphical theme to use and its name.
19343 @item @code{auto-login-session} (default: @code{#f})
19344 If true, this must be the name of the executable to start as the default
19345 session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.
19347 If false, a session described by one of the available @file{.desktop}
19348 files in @code{/run/current-system/profile} and @code{~/.guix-profile}
19352 You must install at least one window manager in the system profile or in
19353 your user profile. Failing to do that, if @code{auto-login-session} is
19354 false, you will be unable to log in.
19357 @item @code{xorg-configuration} (default @code{(xorg-configuration)})
19358 Configuration of the Xorg graphical server.
19360 @item @code{display} (default @code{":0"})
19361 The display on which to start the Xorg graphical server.
19363 @item @code{vt} (default @code{"vt7"})
19364 The VT on which to start the Xorg graphical server.
19366 @item @code{xauth} (default: @code{xauth})
19367 The XAuth package to use.
19369 @item @code{shepherd} (default: @code{shepherd})
19370 The Shepherd package used when invoking @command{halt} and
19373 @item @code{sessreg} (default: @code{sessreg})
19374 The sessreg package used in order to register the session.
19376 @item @code{slim} (default: @code{slim})
19377 The SLiM package to use.
19381 @defvr {Scheme Variable} %default-theme
19382 @defvrx {Scheme Variable} %default-theme-name
19383 The default SLiM theme and its name.
19387 @deftp {Data Type} sddm-configuration
19388 This is the data type representing the SDDM service configuration.
19391 @item @code{display-server} (default: "x11")
19392 Select display server to use for the greeter. Valid values are
19393 @samp{"x11"} or @samp{"wayland"}.
19395 @item @code{numlock} (default: "on")
19396 Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.
19398 @item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
19399 Command to run when halting.
19401 @item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
19402 Command to run when rebooting.
19404 @item @code{theme} (default "maldives")
19405 Theme to use. Default themes provided by SDDM are @samp{"elarun"},
19406 @samp{"maldives"} or @samp{"maya"}.
19408 @item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
19409 Directory to look for themes.
19411 @item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
19412 Directory to look for faces.
19414 @item @code{default-path} (default "/run/current-system/profile/bin")
19415 Default PATH to use.
19417 @item @code{minimum-uid} (default: 1000)
19418 Minimum UID displayed in SDDM and allowed for log-in.
19420 @item @code{maximum-uid} (default: 2000)
19421 Maximum UID to display in SDDM.
19423 @item @code{remember-last-user?} (default #t)
19424 Remember last user.
19426 @item @code{remember-last-session?} (default #t)
19427 Remember last session.
19429 @item @code{hide-users} (default "")
19430 Usernames to hide from SDDM greeter.
19432 @item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
19433 Users with shells listed will be hidden from the SDDM greeter.
19435 @item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
19436 Script to run before starting a wayland session.
19438 @item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
19439 Directory to look for desktop files starting wayland sessions.
19441 @item @code{xorg-configuration} (default @code{(xorg-configuration)})
19442 Configuration of the Xorg graphical server.
19444 @item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
19447 @item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
19450 @item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
19451 Script to run after starting xorg-server.
19453 @item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
19454 Script to run before stopping xorg-server.
19456 @item @code{xsession-command} (default: @code{xinitrc})
19457 Script to run before starting a X session.
19459 @item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
19460 Directory to look for desktop files starting X sessions.
19462 @item @code{minimum-vt} (default: 7)
19465 @item @code{auto-login-user} (default "")
19466 User to use for auto-login.
19468 @item @code{auto-login-session} (default "")
19469 Desktop file to use for auto-login.
19471 @item @code{relogin?} (default #f)
19472 Relogin after logout.
19477 @cindex login manager
19479 @defvr {Scheme Variable} sddm-service-type
19480 This is the type of the service to run the
19481 @uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
19482 must be a @code{sddm-configuration} record (see below).
19484 Here's an example use:
19487 (service sddm-service-type
19488 (sddm-configuration
19489 (auto-login-user "alice")
19490 (auto-login-session "xfce.desktop")))
19494 @deftp {Data Type} sddm-configuration
19495 This data type represents the configuration of the SDDM login manager.
19496 The available fields are:
19499 @item @code{sddm} (default: @code{sddm})
19500 The SDDM package to use.
19502 @item @code{display-server} (default: @code{"x11"})
19503 This must be either @code{"x11"} or @code{"wayland"}.
19505 @c FIXME: Add more fields.
19507 @item @code{auto-login-user} (default: @code{""})
19508 If non-empty, this is the user account under which to log in
19511 @item @code{auto-login-session} (default: @code{""})
19512 If non-empty, this is the @file{.desktop} file name to use as the
19513 auto-login session.
19517 @cindex Xorg, configuration
19518 @deftp {Data Type} xorg-configuration
19519 This data type represents the configuration of the Xorg graphical display
19520 server. Note that there is no Xorg service; instead, the X server is started
19521 by a ``display manager'' such as GDM, SDDM, and SLiM@. Thus, the configuration
19522 of these display managers aggregates an @code{xorg-configuration} record.
19525 @item @code{modules} (default: @code{%default-xorg-modules})
19526 This is a list of @dfn{module packages} loaded by the Xorg
19527 server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on.
19529 @item @code{fonts} (default: @code{%default-xorg-fonts})
19530 This is a list of font directories to add to the server's @dfn{font path}.
19532 @item @code{drivers} (default: @code{'()})
19533 This must be either the empty list, in which case Xorg chooses a graphics
19534 driver automatically, or a list of driver names that will be tried in this
19535 order---e.g., @code{("modesetting" "vesa")}.
19537 @item @code{resolutions} (default: @code{'()})
19538 When @code{resolutions} is the empty list, Xorg chooses an appropriate screen
19539 resolution. Otherwise, it must be a list of resolutions---e.g., @code{((1024
19542 @cindex keyboard layout, for Xorg
19543 @cindex keymap, for Xorg
19544 @item @code{keyboard-layout} (default: @code{#f})
19545 If this is @code{#f}, Xorg uses the default keyboard layout---usually US
19546 English (``qwerty'') for a 105-key PC keyboard.
19548 Otherwise this must be a @code{keyboard-layout} object specifying the keyboard
19549 layout in use when Xorg is running. @xref{Keyboard Layout}, for more
19550 information on how to specify the keyboard layout.
19552 @item @code{extra-config} (default: @code{'()})
19553 This is a list of strings or objects appended to the configuration file. It
19554 is used to pass extra text to be added verbatim to the configuration file.
19556 @item @code{server} (default: @code{xorg-server})
19557 This is the package providing the Xorg server.
19559 @item @code{server-arguments} (default: @code{%default-xorg-server-arguments})
19560 This is the list of command-line arguments to pass to the X server. The
19561 default is @code{-nolisten tcp}.
19565 @deffn {Scheme Procedure} set-xorg-configuration @var{config} @
19566 [@var{login-manager-service-type}]
19567 Tell the log-in manager (of type @var{login-manager-service-type}) to use
19568 @var{config}, an @code{<xorg-configuration>} record.
19570 Since the Xorg configuration is embedded in the log-in manager's
19571 configuration---e.g., @code{gdm-configuration}---this procedure provides a
19572 shorthand to set the Xorg configuration.
19575 @deffn {Scheme Procedure} xorg-start-command [@var{config}]
19576 Return a @code{startx} script in which the modules, fonts, etc. specified
19577 in @var{config}, are available. The result should be used in place of
19580 Usually the X server is started by a login manager.
19584 @deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
19585 Add @var{package}, a package for a screen locker or screen saver whose
19586 command is @var{program}, to the set of setuid programs and add a PAM entry
19587 for it. For example:
19590 (screen-locker-service xlockmore "xlock")
19593 makes the good ol' XlockMore usable.
19597 @node Printing Services
19598 @subsection Printing Services
19600 @cindex printer support with CUPS
19601 The @code{(gnu services cups)} module provides a Guix service definition
19602 for the CUPS printing service. To add printer support to a Guix
19603 system, add a @code{cups-service} to the operating system definition:
19605 @deffn {Scheme Variable} cups-service-type
19606 The service type for the CUPS print server. Its value should be a valid
19607 CUPS configuration (see below). To use the default settings, simply
19610 (service cups-service-type)
19614 The CUPS configuration controls the basic things about your CUPS
19615 installation: what interfaces it listens on, what to do if a print job
19616 fails, how much logging to do, and so on. To actually add a printer,
19617 you have to visit the @url{http://localhost:631} URL, or use a tool such
19618 as GNOME's printer configuration services. By default, configuring a
19619 CUPS service will generate a self-signed certificate if needed, for
19620 secure connections to the print server.
19622 Suppose you want to enable the Web interface of CUPS and also add
19623 support for Epson printers @i{via} the @code{epson-inkjet-printer-escpr}
19624 package and for HP printers @i{via} the @code{hplip-minimal} package.
19625 You can do that directly, like this (you need to use the
19626 @code{(gnu packages cups)} module):
19629 (service cups-service-type
19630 (cups-configuration
19631 (web-interface? #t)
19633 (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))
19636 Note: If you wish to use the Qt5 based GUI which comes with the hplip
19637 package then it is suggested that you install the @code{hplip} package,
19638 either in your OS configuration file or as your user.
19640 The available configuration parameters follow. Each parameter
19641 definition is preceded by its type; for example, @samp{string-list foo}
19642 indicates that the @code{foo} parameter should be specified as a list of
19643 strings. There is also a way to specify the configuration as a string,
19644 if you have an old @code{cupsd.conf} file that you want to port over
19645 from some other system; see the end for more details.
19647 @c The following documentation was initially generated by
19648 @c (generate-documentation) in (gnu services cups). Manually maintained
19649 @c documentation is better, so we shouldn't hesitate to edit below as
19650 @c needed. However if the change you want to make to this documentation
19651 @c can be done in an automated way, it's probably easier to change
19652 @c (generate-documentation) than to make it below and have to deal with
19653 @c the churn as CUPS updates.
19656 Available @code{cups-configuration} fields are:
19658 @deftypevr {@code{cups-configuration} parameter} package cups
19662 @deftypevr {@code{cups-configuration} parameter} package-list extensions (default: @code{(list brlaser cups-filters epson-inkjet-printer-escpr foomatic-filters hplip-minimal splix)})
19663 Drivers and other extensions to the CUPS package.
19666 @deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
19667 Configuration of where to write logs, what directories to use for print
19668 spools, and related privileged configuration parameters.
19670 Available @code{files-configuration} fields are:
19672 @deftypevr {@code{files-configuration} parameter} log-location access-log
19673 Defines the access log filename. Specifying a blank filename disables
19674 access log generation. The value @code{stderr} causes log entries to be
19675 sent to the standard error file when the scheduler is running in the
19676 foreground, or to the system log daemon when run in the background. The
19677 value @code{syslog} causes log entries to be sent to the system log
19678 daemon. The server name may be included in filenames using the string
19679 @code{%s}, as in @code{/var/log/cups/%s-access_log}.
19681 Defaults to @samp{"/var/log/cups/access_log"}.
19684 @deftypevr {@code{files-configuration} parameter} file-name cache-dir
19685 Where CUPS should cache data.
19687 Defaults to @samp{"/var/cache/cups"}.
19690 @deftypevr {@code{files-configuration} parameter} string config-file-perm
19691 Specifies the permissions for all configuration files that the scheduler
19694 Note that the permissions for the printers.conf file are currently
19695 masked to only allow access from the scheduler user (typically root).
19696 This is done because printer device URIs sometimes contain sensitive
19697 authentication information that should not be generally known on the
19698 system. There is no way to disable this security feature.
19700 Defaults to @samp{"0640"}.
19703 @deftypevr {@code{files-configuration} parameter} log-location error-log
19704 Defines the error log filename. Specifying a blank filename disables
19705 error log generation. The value @code{stderr} causes log entries to be
19706 sent to the standard error file when the scheduler is running in the
19707 foreground, or to the system log daemon when run in the background. The
19708 value @code{syslog} causes log entries to be sent to the system log
19709 daemon. The server name may be included in filenames using the string
19710 @code{%s}, as in @code{/var/log/cups/%s-error_log}.
19712 Defaults to @samp{"/var/log/cups/error_log"}.
19715 @deftypevr {@code{files-configuration} parameter} string fatal-errors
19716 Specifies which errors are fatal, causing the scheduler to exit. The
19721 No errors are fatal.
19724 All of the errors below are fatal.
19727 Browsing initialization errors are fatal, for example failed connections
19728 to the DNS-SD daemon.
19731 Configuration file syntax errors are fatal.
19734 Listen or Port errors are fatal, except for IPv6 failures on the
19735 loopback or @code{any} addresses.
19738 Log file creation or write errors are fatal.
19741 Bad startup file permissions are fatal, for example shared TLS
19742 certificate and key files with world-read permissions.
19745 Defaults to @samp{"all -browse"}.
19748 @deftypevr {@code{files-configuration} parameter} boolean file-device?
19749 Specifies whether the file pseudo-device can be used for new printer
19750 queues. The URI @uref{file:///dev/null} is always allowed.
19752 Defaults to @samp{#f}.
19755 @deftypevr {@code{files-configuration} parameter} string group
19756 Specifies the group name or ID that will be used when executing external
19759 Defaults to @samp{"lp"}.
19762 @deftypevr {@code{files-configuration} parameter} string log-file-group
19763 Specifies the group name or ID that will be used for log files.
19765 Defaults to @samp{"lpadmin"}.
19768 @deftypevr {@code{files-configuration} parameter} string log-file-perm
19769 Specifies the permissions for all log files that the scheduler writes.
19771 Defaults to @samp{"0644"}.
19774 @deftypevr {@code{files-configuration} parameter} log-location page-log
19775 Defines the page log filename. Specifying a blank filename disables
19776 page log generation. The value @code{stderr} causes log entries to be
19777 sent to the standard error file when the scheduler is running in the
19778 foreground, or to the system log daemon when run in the background. The
19779 value @code{syslog} causes log entries to be sent to the system log
19780 daemon. The server name may be included in filenames using the string
19781 @code{%s}, as in @code{/var/log/cups/%s-page_log}.
19783 Defaults to @samp{"/var/log/cups/page_log"}.
19786 @deftypevr {@code{files-configuration} parameter} string remote-root
19787 Specifies the username that is associated with unauthenticated accesses
19788 by clients claiming to be the root user. The default is @code{remroot}.
19790 Defaults to @samp{"remroot"}.
19793 @deftypevr {@code{files-configuration} parameter} file-name request-root
19794 Specifies the directory that contains print jobs and other HTTP request
19797 Defaults to @samp{"/var/spool/cups"}.
19800 @deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
19801 Specifies the level of security sandboxing that is applied to print
19802 filters, backends, and other child processes of the scheduler; either
19803 @code{relaxed} or @code{strict}. This directive is currently only
19804 used/supported on macOS.
19806 Defaults to @samp{strict}.
19809 @deftypevr {@code{files-configuration} parameter} file-name server-keychain
19810 Specifies the location of TLS certificates and private keys. CUPS will
19811 look for public and private keys in this directory: @file{.crt} files
19812 for PEM-encoded certificates and corresponding @file{.key} files for
19813 PEM-encoded private keys.
19815 Defaults to @samp{"/etc/cups/ssl"}.
19818 @deftypevr {@code{files-configuration} parameter} file-name server-root
19819 Specifies the directory containing the server configuration files.
19821 Defaults to @samp{"/etc/cups"}.
19824 @deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
19825 Specifies whether the scheduler calls fsync(2) after writing
19826 configuration or state files.
19828 Defaults to @samp{#f}.
19831 @deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
19832 Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
19835 @deftypevr {@code{files-configuration} parameter} file-name temp-dir
19836 Specifies the directory where temporary files are stored.
19838 Defaults to @samp{"/var/spool/cups/tmp"}.
19841 @deftypevr {@code{files-configuration} parameter} string user
19842 Specifies the user name or ID that is used when running external
19845 Defaults to @samp{"lp"}.
19848 @deftypevr {@code{files-configuration} parameter} string set-env
19849 Set the specified environment variable to be passed to child processes.
19851 Defaults to @samp{"variable value"}.
19855 @deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
19856 Specifies the logging level for the AccessLog file. The @code{config}
19857 level logs when printers and classes are added, deleted, or modified and
19858 when configuration files are accessed or updated. The @code{actions}
19859 level logs when print jobs are submitted, held, released, modified, or
19860 canceled, and any of the conditions for @code{config}. The @code{all}
19861 level logs all requests.
19863 Defaults to @samp{actions}.
19866 @deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
19867 Specifies whether to purge job history data automatically when it is no
19868 longer required for quotas.
19870 Defaults to @samp{#f}.
19873 @deftypevr {@code{cups-configuration} parameter} comma-separated-string-list browse-dns-sd-sub-types
19874 Specifies a list of DNS-SD sub-types to advertise for each shared printer.
19875 For example, @samp{"_cups" "_print"} will tell network clients that both
19876 CUPS sharing and IPP Everywhere are supported.
19878 Defaults to @samp{"_cups"}.
19881 @deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
19882 Specifies which protocols to use for local printer sharing.
19884 Defaults to @samp{dnssd}.
19887 @deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
19888 Specifies whether the CUPS web interface is advertised.
19890 Defaults to @samp{#f}.
19893 @deftypevr {@code{cups-configuration} parameter} boolean browsing?
19894 Specifies whether shared printers are advertised.
19896 Defaults to @samp{#f}.
19899 @deftypevr {@code{cups-configuration} parameter} string classification
19900 Specifies the security classification of the server. Any valid banner
19901 name can be used, including @samp{"classified"}, @samp{"confidential"},
19902 @samp{"secret"}, @samp{"topsecret"}, and @samp{"unclassified"}, or the
19903 banner can be omitted to disable secure printing functions.
19905 Defaults to @samp{""}.
19908 @deftypevr {@code{cups-configuration} parameter} boolean classify-override?
19909 Specifies whether users may override the classification (cover page) of
19910 individual print jobs using the @code{job-sheets} option.
19912 Defaults to @samp{#f}.
19915 @deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
19916 Specifies the default type of authentication to use.
19918 Defaults to @samp{Basic}.
19921 @deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
19922 Specifies whether encryption will be used for authenticated requests.
19924 Defaults to @samp{Required}.
19927 @deftypevr {@code{cups-configuration} parameter} string default-language
19928 Specifies the default language to use for text and web content.
19930 Defaults to @samp{"en"}.
19933 @deftypevr {@code{cups-configuration} parameter} string default-paper-size
19934 Specifies the default paper size for new print queues. @samp{"Auto"}
19935 uses a locale-specific default, while @samp{"None"} specifies there is
19936 no default paper size. Specific size names are typically
19937 @samp{"Letter"} or @samp{"A4"}.
19939 Defaults to @samp{"Auto"}.
19942 @deftypevr {@code{cups-configuration} parameter} string default-policy
19943 Specifies the default access policy to use.
19945 Defaults to @samp{"default"}.
19948 @deftypevr {@code{cups-configuration} parameter} boolean default-shared?
19949 Specifies whether local printers are shared by default.
19951 Defaults to @samp{#t}.
19954 @deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
19955 Specifies the delay for updating of configuration and state files, in
19956 seconds. A value of 0 causes the update to happen as soon as possible,
19957 typically within a few milliseconds.
19959 Defaults to @samp{30}.
19962 @deftypevr {@code{cups-configuration} parameter} error-policy error-policy
19963 Specifies what to do when an error occurs. Possible values are
19964 @code{abort-job}, which will discard the failed print job;
19965 @code{retry-job}, which will retry the job at a later time;
19966 @code{retry-current-job}, which retries the failed job immediately; and
19967 @code{stop-printer}, which stops the printer.
19969 Defaults to @samp{stop-printer}.
19972 @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
19973 Specifies the maximum cost of filters that are run concurrently, which
19974 can be used to minimize disk, memory, and CPU resource problems. A
19975 limit of 0 disables filter limiting. An average print to a
19976 non-PostScript printer needs a filter limit of about 200. A PostScript
19977 printer needs about half that (100). Setting the limit below these
19978 thresholds will effectively limit the scheduler to printing a single job
19981 Defaults to @samp{0}.
19984 @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
19985 Specifies the scheduling priority of filters that are run to print a
19986 job. The nice value ranges from 0, the highest priority, to 19, the
19989 Defaults to @samp{0}.
19992 @deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
19993 Specifies whether to do reverse lookups on connecting clients. The
19994 @code{double} setting causes @code{cupsd} to verify that the hostname
19995 resolved from the address matches one of the addresses returned for that
19996 hostname. Double lookups also prevent clients with unregistered
19997 addresses from connecting to your server. Only set this option to
19998 @code{#t} or @code{double} if absolutely required.
20000 Defaults to @samp{#f}.
20003 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
20004 Specifies the number of seconds to wait before killing the filters and
20005 backend associated with a canceled or held job.
20007 Defaults to @samp{30}.
20010 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
20011 Specifies the interval between retries of jobs in seconds. This is
20012 typically used for fax queues but can also be used with normal print
20013 queues whose error policy is @code{retry-job} or
20014 @code{retry-current-job}.
20016 Defaults to @samp{30}.
20019 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
20020 Specifies the number of retries that are done for jobs. This is
20021 typically used for fax queues but can also be used with normal print
20022 queues whose error policy is @code{retry-job} or
20023 @code{retry-current-job}.
20025 Defaults to @samp{5}.
20028 @deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
20029 Specifies whether to support HTTP keep-alive connections.
20031 Defaults to @samp{#t}.
20034 @deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
20035 Specifies the maximum size of print files, IPP requests, and HTML form
20036 data. A limit of 0 disables the limit check.
20038 Defaults to @samp{0}.
20041 @deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
20042 Listens on the specified interfaces for connections. Valid values are
20043 of the form @var{address}:@var{port}, where @var{address} is either an
20044 IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
20045 indicate all addresses. Values can also be file names of local UNIX
20046 domain sockets. The Listen directive is similar to the Port directive
20047 but allows you to restrict access to specific interfaces or networks.
20050 @deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
20051 Specifies the number of pending connections that will be allowed. This
20052 normally only affects very busy servers that have reached the MaxClients
20053 limit, but can also be triggered by large numbers of simultaneous
20054 connections. When the limit is reached, the operating system will
20055 refuse additional connections until the scheduler can accept the pending
20058 Defaults to @samp{128}.
20061 @deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
20062 Specifies a set of additional access controls.
20064 Available @code{location-access-controls} fields are:
20066 @deftypevr {@code{location-access-controls} parameter} file-name path
20067 Specifies the URI path to which the access control applies.
20070 @deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
20071 Access controls for all access to this path, in the same format as the
20072 @code{access-controls} of @code{operation-access-control}.
20074 Defaults to @samp{()}.
20077 @deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
20078 Access controls for method-specific access to this path.
20080 Defaults to @samp{()}.
20082 Available @code{method-access-controls} fields are:
20084 @deftypevr {@code{method-access-controls} parameter} boolean reverse?
20085 If @code{#t}, apply access controls to all methods except the listed
20086 methods. Otherwise apply to only the listed methods.
20088 Defaults to @samp{#f}.
20091 @deftypevr {@code{method-access-controls} parameter} method-list methods
20092 Methods to which this access control applies.
20094 Defaults to @samp{()}.
20097 @deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
20098 Access control directives, as a list of strings. Each string should be
20099 one directive, such as @samp{"Order allow,deny"}.
20101 Defaults to @samp{()}.
20106 @deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
20107 Specifies the number of debugging messages that are retained for logging
20108 if an error occurs in a print job. Debug messages are logged regardless
20109 of the LogLevel setting.
20111 Defaults to @samp{100}.
20114 @deftypevr {@code{cups-configuration} parameter} log-level log-level
20115 Specifies the level of logging for the ErrorLog file. The value
20116 @code{none} stops all logging while @code{debug2} logs everything.
20118 Defaults to @samp{info}.
20121 @deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
20122 Specifies the format of the date and time in the log files. The value
20123 @code{standard} logs whole seconds while @code{usecs} logs microseconds.
20125 Defaults to @samp{standard}.
20128 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
20129 Specifies the maximum number of simultaneous clients that are allowed by
20132 Defaults to @samp{100}.
20135 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
20136 Specifies the maximum number of simultaneous clients that are allowed
20137 from a single address.
20139 Defaults to @samp{100}.
20142 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
20143 Specifies the maximum number of copies that a user can print of each
20146 Defaults to @samp{9999}.
20149 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
20150 Specifies the maximum time a job may remain in the @code{indefinite}
20151 hold state before it is canceled. A value of 0 disables cancellation of
20154 Defaults to @samp{0}.
20157 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
20158 Specifies the maximum number of simultaneous jobs that are allowed. Set
20159 to 0 to allow an unlimited number of jobs.
20161 Defaults to @samp{500}.
20164 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
20165 Specifies the maximum number of simultaneous jobs that are allowed per
20166 printer. A value of 0 allows up to MaxJobs jobs per printer.
20168 Defaults to @samp{0}.
20171 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
20172 Specifies the maximum number of simultaneous jobs that are allowed per
20173 user. A value of 0 allows up to MaxJobs jobs per user.
20175 Defaults to @samp{0}.
20178 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
20179 Specifies the maximum time a job may take to print before it is
20180 canceled, in seconds. Set to 0 to disable cancellation of ``stuck'' jobs.
20182 Defaults to @samp{10800}.
20185 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
20186 Specifies the maximum size of the log files before they are rotated, in
20187 bytes. The value 0 disables log rotation.
20189 Defaults to @samp{1048576}.
20192 @deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
20193 Specifies the maximum amount of time to allow between files in a
20194 multiple file print job, in seconds.
20196 Defaults to @samp{900}.
20199 @deftypevr {@code{cups-configuration} parameter} string page-log-format
20200 Specifies the format of PageLog lines. Sequences beginning with percent
20201 (@samp{%}) characters are replaced with the corresponding information,
20202 while all other characters are copied literally. The following percent
20203 sequences are recognized:
20207 insert a single percent character
20210 insert the value of the specified IPP attribute
20213 insert the number of copies for the current page
20216 insert the current page number
20219 insert the current date and time in common log format
20225 insert the printer name
20228 insert the username
20231 A value of the empty string disables page logging. The string @code{%p
20232 %u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@}
20233 %@{job-name@} %@{media@} %@{sides@}} creates a page log with the
20236 Defaults to @samp{""}.
20239 @deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
20240 Passes the specified environment variable(s) to child processes; a list
20243 Defaults to @samp{()}.
20246 @deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
20247 Specifies named access control policies.
20249 Available @code{policy-configuration} fields are:
20251 @deftypevr {@code{policy-configuration} parameter} string name
20252 Name of the policy.
20255 @deftypevr {@code{policy-configuration} parameter} string job-private-access
20256 Specifies an access list for a job's private values. @code{@@ACL} maps
20257 to the printer's requesting-user-name-allowed or
20258 requesting-user-name-denied values. @code{@@OWNER} maps to the job's
20259 owner. @code{@@SYSTEM} maps to the groups listed for the
20260 @code{system-group} field of the @code{files-configuration},
20261 which is reified into the @code{cups-files.conf(5)} file. Other
20262 possible elements of the access list include specific user names, and
20263 @code{@@@var{group}} to indicate members of a specific group. The
20264 access list may also be simply @code{all} or @code{default}.
20266 Defaults to @samp{"@@OWNER @@SYSTEM"}.
20269 @deftypevr {@code{policy-configuration} parameter} string job-private-values
20270 Specifies the list of job values to make private, or @code{all},
20271 @code{default}, or @code{none}.
20273 Defaults to @samp{"job-name job-originating-host-name
20274 job-originating-user-name phone"}.
20277 @deftypevr {@code{policy-configuration} parameter} string subscription-private-access
20278 Specifies an access list for a subscription's private values.
20279 @code{@@ACL} maps to the printer's requesting-user-name-allowed or
20280 requesting-user-name-denied values. @code{@@OWNER} maps to the job's
20281 owner. @code{@@SYSTEM} maps to the groups listed for the
20282 @code{system-group} field of the @code{files-configuration},
20283 which is reified into the @code{cups-files.conf(5)} file. Other
20284 possible elements of the access list include specific user names, and
20285 @code{@@@var{group}} to indicate members of a specific group. The
20286 access list may also be simply @code{all} or @code{default}.
20288 Defaults to @samp{"@@OWNER @@SYSTEM"}.
20291 @deftypevr {@code{policy-configuration} parameter} string subscription-private-values
20292 Specifies the list of job values to make private, or @code{all},
20293 @code{default}, or @code{none}.
20295 Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
20296 notify-subscriber-user-name notify-user-data"}.
20299 @deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
20300 Access control by IPP operation.
20302 Defaults to @samp{()}.
20306 @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
20307 Specifies whether job files (documents) are preserved after a job is
20308 printed. If a numeric value is specified, job files are preserved for
20309 the indicated number of seconds after printing. Otherwise a boolean
20310 value applies indefinitely.
20312 Defaults to @samp{86400}.
20315 @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
20316 Specifies whether the job history is preserved after a job is printed.
20317 If a numeric value is specified, the job history is preserved for the
20318 indicated number of seconds after printing. If @code{#t}, the job
20319 history is preserved until the MaxJobs limit is reached.
20321 Defaults to @samp{#t}.
20324 @deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
20325 Specifies the amount of time to wait for job completion before
20326 restarting the scheduler.
20328 Defaults to @samp{30}.
20331 @deftypevr {@code{cups-configuration} parameter} string rip-cache
20332 Specifies the maximum amount of memory to use when converting documents
20333 into bitmaps for a printer.
20335 Defaults to @samp{"128m"}.
20338 @deftypevr {@code{cups-configuration} parameter} string server-admin
20339 Specifies the email address of the server administrator.
20341 Defaults to @samp{"root@@localhost.localdomain"}.
20344 @deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
20345 The ServerAlias directive is used for HTTP Host header validation when
20346 clients connect to the scheduler from external interfaces. Using the
20347 special name @code{*} can expose your system to known browser-based DNS
20348 rebinding attacks, even when accessing sites through a firewall. If the
20349 auto-discovery of alternate names does not work, we recommend listing
20350 each alternate name with a ServerAlias directive instead of using
20353 Defaults to @samp{*}.
20356 @deftypevr {@code{cups-configuration} parameter} string server-name
20357 Specifies the fully-qualified host name of the server.
20359 Defaults to @samp{"localhost"}.
20362 @deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
20363 Specifies what information is included in the Server header of HTTP
20364 responses. @code{None} disables the Server header. @code{ProductOnly}
20365 reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
20366 reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
20367 @code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
20368 the output of the @code{uname} command. @code{Full} reports @code{CUPS
20369 2.0.0 (@var{uname}) IPP/2.0}.
20371 Defaults to @samp{Minimal}.
20374 @deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
20375 Listens on the specified interfaces for encrypted connections. Valid
20376 values are of the form @var{address}:@var{port}, where @var{address} is
20377 either an IPv6 address enclosed in brackets, an IPv4 address, or
20378 @code{*} to indicate all addresses.
20380 Defaults to @samp{()}.
20383 @deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
20384 Sets encryption options. By default, CUPS only supports encryption
20385 using TLS v1.0 or higher using known secure cipher suites. Security is
20386 reduced when @code{Allow} options are used, and enhanced when @code{Deny}
20387 options are used. The @code{AllowRC4} option enables the 128-bit RC4 cipher
20388 suites, which are required for some older clients. The @code{AllowSSL3} option
20389 enables SSL v3.0, which is required for some older clients that do not support
20390 TLS v1.0. The @code{DenyCBC} option disables all CBC cipher suites. The
20391 @code{DenyTLS1.0} option disables TLS v1.0 support - this sets the minimum
20392 protocol version to TLS v1.1.
20394 Defaults to @samp{()}.
20397 @deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
20398 Specifies whether the scheduler requires clients to strictly adhere to
20399 the IPP specifications.
20401 Defaults to @samp{#f}.
20404 @deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
20405 Specifies the HTTP request timeout, in seconds.
20407 Defaults to @samp{900}.
20411 @deftypevr {@code{cups-configuration} parameter} boolean web-interface?
20412 Specifies whether the web interface is enabled.
20414 Defaults to @samp{#f}.
20417 At this point you're probably thinking ``oh dear, Guix manual, I like
20418 you but you can stop already with the configuration options''. Indeed.
20419 However, one more point: it could be that you have an existing
20420 @code{cupsd.conf} that you want to use. In that case, you can pass an
20421 @code{opaque-cups-configuration} as the configuration of a
20422 @code{cups-service-type}.
20424 Available @code{opaque-cups-configuration} fields are:
20426 @deftypevr {@code{opaque-cups-configuration} parameter} package cups
20430 @deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
20431 The contents of the @code{cupsd.conf}, as a string.
20434 @deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
20435 The contents of the @code{cups-files.conf} file, as a string.
20438 For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
20439 strings of the same name, you could instantiate a CUPS service like
20443 (service cups-service-type
20444 (opaque-cups-configuration
20445 (cupsd.conf cupsd.conf)
20446 (cups-files.conf cups-files.conf)))
20450 @node Desktop Services
20451 @subsection Desktop Services
20453 The @code{(gnu services desktop)} module provides services that are
20454 usually useful in the context of a ``desktop'' setup---that is, on a
20455 machine running a graphical display server, possibly with graphical user
20456 interfaces, etc. It also defines services that provide specific desktop
20457 environments like GNOME, Xfce or MATE.
20459 To simplify things, the module defines a variable containing the set of
20460 services that users typically expect on a machine with a graphical
20461 environment and networking:
20463 @defvr {Scheme Variable} %desktop-services
20464 This is a list of services that builds upon @code{%base-services} and
20465 adds or adjusts services for a typical ``desktop'' setup.
20467 In particular, it adds a graphical login manager (@pxref{X Window,
20468 @code{gdm-service-type}}), screen lockers, a network management tool
20469 (@pxref{Networking Services, @code{network-manager-service-type}}) with modem
20470 support (@pxref{Networking Services, @code{modem-manager-service-type}}),
20471 energy and color management services, the @code{elogind} login and seat
20472 manager, the Polkit privilege service, the GeoClue location service, the
20473 AccountsService daemon that allows authorized users change system passwords,
20474 an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the
20475 name service switch service configured to be able to use @code{nss-mdns}
20476 (@pxref{Name Service Switch, mDNS}).
20479 The @code{%desktop-services} variable can be used as the @code{services}
20480 field of an @code{operating-system} declaration (@pxref{operating-system
20481 Reference, @code{services}}).
20483 Additionally, the @code{gnome-desktop-service-type},
20484 @code{xfce-desktop-service}, @code{mate-desktop-service-type},
20485 @code{lxqt-desktop-service-type} and @code{enlightenment-desktop-service-type}
20486 procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system. To
20487 ``add GNOME'' means that system-level services like the backlight adjustment
20488 helpers and the power management utilities are added to the system, extending
20489 @code{polkit} and @code{dbus} appropriately, allowing GNOME to operate with
20490 elevated privileges on a limited number of special-purpose system interfaces.
20491 Additionally, adding a service made by @code{gnome-desktop-service-type} adds
20492 the GNOME metapackage to the system profile. Likewise, adding the Xfce
20493 service not only adds the @code{xfce} metapackage to the system profile, but
20494 it also gives the Thunar file manager the ability to open a ``root-mode'' file
20495 management window, if the user authenticates using the administrator's
20496 password via the standard polkit graphical interface. To ``add MATE'' means
20497 that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE
20498 to operate with elevated privileges on a limited number of special-purpose
20499 system interfaces. Additionally, adding a service of type
20500 @code{mate-desktop-service-type} adds the MATE metapackage to the system
20501 profile. ``Adding Enlightenment'' means that @code{dbus} is extended
20502 appropriately, and several of Enlightenment's binaries are set as setuid,
20503 allowing Enlightenment's screen locker and other functionality to work as
20506 The desktop environments in Guix use the Xorg display server by
20507 default. If you'd like to use the newer display server protocol
20508 called Wayland, you need to enable Wayland support in GDM
20509 (@pxref{wayland-gdm}). Another solution is to use the
20510 @code{sddm-service} instead of GDM as the graphical login manager.
20511 You should then select the ``GNOME (Wayland)'' session in SDDM@.
20512 Alternatively you can also try starting GNOME on Wayland manually from a
20513 TTY with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
20514 gnome-session``. Currently only GNOME has support for Wayland.
20516 @defvr {Scheme Variable} gnome-desktop-service-type
20517 This is the type of the service that adds the @uref{https://www.gnome.org,
20518 GNOME} desktop environment. Its value is a @code{gnome-desktop-configuration}
20519 object (see below).
20521 This service adds the @code{gnome} package to the system profile, and extends
20522 polkit with the actions from @code{gnome-settings-daemon}.
20525 @deftp {Data Type} gnome-desktop-configuration
20526 Configuration record for the GNOME desktop environment.
20529 @item @code{gnome} (default: @code{gnome})
20530 The GNOME package to use.
20534 @defvr {Scheme Variable} xfce-desktop-service-type
20535 This is the type of a service to run the @uref{Xfce, https://xfce.org/}
20536 desktop environment. Its value is an @code{xfce-desktop-configuration} object
20539 This service adds the @code{xfce} package to the system profile, and
20540 extends polkit with the ability for @code{thunar} to manipulate the file
20541 system as root from within a user session, after the user has authenticated
20542 with the administrator's password.
20544 Note that @code{xfce4-panel} and its plugin packages should be installed in
20545 the same profile to ensure compatibility. When using this service, you should
20546 add extra plugins (@code{xfce4-whiskermenu-plugin},
20547 @code{xfce4-weather-plugin}, etc.) to the @code{packages} field of your
20548 @code{operating-system}.
20551 @deftp {Data Type} xfce-desktop-configuration
20552 Configuration record for the Xfce desktop environment.
20555 @item @code{xfce} (default: @code{xfce})
20556 The Xfce package to use.
20560 @deffn {Scheme Variable} mate-desktop-service-type
20561 This is the type of the service that runs the @uref{https://mate-desktop.org/,
20562 MATE desktop environment}. Its value is a @code{mate-desktop-configuration}
20563 object (see below).
20565 This service adds the @code{mate} package to the system
20566 profile, and extends polkit with the actions from
20567 @code{mate-settings-daemon}.
20570 @deftp {Data Type} mate-desktop-configuration
20571 Configuration record for the MATE desktop environment.
20574 @item @code{mate} (default: @code{mate})
20575 The MATE package to use.
20579 @deffn {Scheme Variable} lxqt-desktop-service-type
20580 This is the type of the service that runs the @uref{https://lxqt-project.org,
20581 LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
20582 object (see below).
20584 This service adds the @code{lxqt} package to the system
20588 @deftp {Data Type} lxqt-desktop-configuration
20589 Configuration record for the LXQt desktop environment.
20592 @item @code{lxqt} (default: @code{lxqt})
20593 The LXQT package to use.
20597 @deffn {Scheme Variable} enlightenment-desktop-service-type
20598 Return a service that adds the @code{enlightenment} package to the system
20599 profile, and extends dbus with actions from @code{efl}.
20602 @deftp {Data Type} enlightenment-desktop-service-configuration
20604 @item @code{enlightenment} (default: @code{enlightenment})
20605 The enlightenment package to use.
20609 Because the GNOME, Xfce and MATE desktop services pull in so many packages,
20610 the default @code{%desktop-services} variable doesn't include any of
20611 them by default. To add GNOME, Xfce or MATE, just @code{cons} them onto
20612 @code{%desktop-services} in the @code{services} field of your
20613 @code{operating-system}:
20616 (use-modules (gnu))
20617 (use-service-modules desktop)
20620 ;; cons* adds items to the list given as its last argument.
20621 (services (cons* (service gnome-desktop-service-type)
20622 (service xfce-desktop-service)
20623 %desktop-services))
20627 These desktop environments will then be available as options in the
20628 graphical login window.
20630 The actual service definitions included in @code{%desktop-services} and
20631 provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
20632 are described below.
20634 @deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
20635 Return a service that runs the ``system bus'', using @var{dbus}, with
20636 support for @var{services}.
20638 @uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
20639 facility. Its system bus is used to allow system services to communicate
20640 and to be notified of system-wide events.
20642 @var{services} must be a list of packages that provide an
20643 @file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
20644 and policy files. For example, to allow avahi-daemon to use the system bus,
20645 @var{services} must be equal to @code{(list avahi)}.
20648 @deffn {Scheme Procedure} elogind-service [#:config @var{config}]
20649 Return a service that runs the @code{elogind} login and
20650 seat management daemon. @uref{https://github.com/elogind/elogind,
20651 Elogind} exposes a D-Bus interface that can be used to know which users
20652 are logged in, know what kind of sessions they have open, suspend the
20653 system, inhibit system suspend, reboot the system, and other tasks.
20655 Elogind handles most system-level power events for a computer, for
20656 example suspending the system when a lid is closed, or shutting it down
20657 when the power button is pressed.
20659 The @var{config} keyword argument specifies the configuration for
20660 elogind, and should be the result of an @code{(elogind-configuration
20661 (@var{parameter} @var{value})...)} invocation. Available parameters and
20662 their default values are:
20665 @item kill-user-processes?
20667 @item kill-only-users
20669 @item kill-exclude-users
20671 @item inhibit-delay-max-seconds
20673 @item handle-power-key
20675 @item handle-suspend-key
20677 @item handle-hibernate-key
20679 @item handle-lid-switch
20681 @item handle-lid-switch-docked
20683 @item handle-lid-switch-external-power
20685 @item power-key-ignore-inhibited?
20687 @item suspend-key-ignore-inhibited?
20689 @item hibernate-key-ignore-inhibited?
20691 @item lid-switch-ignore-inhibited?
20693 @item holdoff-timeout-seconds
20697 @item idle-action-seconds
20699 @item runtime-directory-size-percent
20701 @item runtime-directory-size
20705 @item suspend-state
20706 @code{("mem" "standby" "freeze")}
20709 @item hibernate-state
20711 @item hibernate-mode
20712 @code{("platform" "shutdown")}
20713 @item hybrid-sleep-state
20715 @item hybrid-sleep-mode
20716 @code{("suspend" "platform" "shutdown")}
20720 @deffn {Scheme Procedure} accountsservice-service @
20721 [#:accountsservice @var{accountsservice}]
20722 Return a service that runs AccountsService, a system service that can
20723 list available accounts, change their passwords, and so on.
20724 AccountsService integrates with PolicyKit to enable unprivileged users
20725 to acquire the capability to modify their system configuration.
20726 @uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
20727 accountsservice web site} for more information.
20729 The @var{accountsservice} keyword argument is the @code{accountsservice}
20730 package to expose as a service.
20733 @deffn {Scheme Procedure} polkit-service @
20734 [#:polkit @var{polkit}]
20735 Return a service that runs the
20736 @uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
20737 management service}, which allows system administrators to grant access to
20738 privileged operations in a structured way. By querying the Polkit service, a
20739 privileged system component can know when it should grant additional
20740 capabilities to ordinary users. For example, an ordinary user can be granted
20741 the capability to suspend the system if the user is logged in locally.
20744 @defvr {Scheme Variable} polkit-wheel-service
20745 Service that adds the @code{wheel} group as admins to the Polkit
20746 service. This makes it so that users in the @code{wheel} group are queried
20747 for their own passwords when performing administrative actions instead of
20748 @code{root}'s, similar to the behaviour used by @code{sudo}.
20751 @defvr {Scheme Variable} upower-service-type
20752 Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
20753 system-wide monitor for power consumption and battery levels, with the given
20754 configuration settings.
20756 It implements the @code{org.freedesktop.UPower} D-Bus interface, and is
20757 notably used by GNOME.
20760 @deftp {Data Type} upower-configuration
20761 Data type representation the configuration for UPower.
20765 @item @code{upower} (default: @var{upower})
20766 Package to use for @code{upower}.
20768 @item @code{watts-up-pro?} (default: @code{#f})
20769 Enable the Watts Up Pro device.
20771 @item @code{poll-batteries?} (default: @code{#t})
20772 Enable polling the kernel for battery level changes.
20774 @item @code{ignore-lid?} (default: @code{#f})
20775 Ignore the lid state, this can be useful if it's incorrect on a device.
20777 @item @code{use-percentage-for-policy?} (default: @code{#f})
20778 Whether battery percentage based policy should be used. The default is to use
20779 the time left, change to @code{#t} to use the percentage.
20781 @item @code{percentage-low} (default: @code{10})
20782 When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
20783 at which the battery is considered low.
20785 @item @code{percentage-critical} (default: @code{3})
20786 When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
20787 at which the battery is considered critical.
20789 @item @code{percentage-action} (default: @code{2})
20790 When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
20791 at which action will be taken.
20793 @item @code{time-low} (default: @code{1200})
20794 When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
20795 seconds at which the battery is considered low.
20797 @item @code{time-critical} (default: @code{300})
20798 When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
20799 seconds at which the battery is considered critical.
20801 @item @code{time-action} (default: @code{120})
20802 When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
20803 seconds at which action will be taken.
20805 @item @code{critical-power-action} (default: @code{'hybrid-sleep})
20806 The action taken when @code{percentage-action} or @code{time-action} is
20807 reached (depending on the configuration of @code{use-percentage-for-policy?}).
20809 Possible values are:
20819 @code{'hybrid-sleep}.
20825 @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
20826 Return a service for @uref{https://udisks.freedesktop.org/docs/latest/,
20827 UDisks}, a @dfn{disk management} daemon that provides user interfaces
20828 with notifications and ways to mount/unmount disks. Programs that talk
20829 to UDisks include the @command{udisksctl} command, part of UDisks, and
20830 GNOME Disks. Note that Udisks relies on the @command{mount} command, so
20831 it will only be able to use the file-system utilities installed in the
20832 system profile. For example if you want to be able to mount NTFS
20833 file-systems in read and write fashion, you'll need to have
20834 @code{ntfs-3g} installed system-wide.
20837 @deffn {Scheme Variable} colord-service-type
20838 This is the type of the service that runs @command{colord}, a system
20839 service with a D-Bus
20840 interface to manage the color profiles of input and output devices such as
20841 screens and scanners. It is notably used by the GNOME Color Manager graphical
20842 tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
20843 site} for more information.
20846 @cindex scanner access
20847 @defvr {Scheme Variable} sane-service-type
20848 This service provides access to scanners @i{via}
20849 @uref{http://www.sane-project.org, SANE} by installing the necessary
20850 udev rules. It is included in @code{%desktop-services} (@pxref{Desktop
20851 Services}) and relies by default on @code{sane-backends-minimal} package
20852 (see below) for hardware support.
20855 @defvr {Scheme Variable} sane-backends-minimal
20856 The default package which the @code{sane-service-type} installs. It
20857 supports many recent scanners.
20860 @defvr {Scheme Variable} sane-backends
20861 This package includes support for all scanners that
20862 @code{sane-backends-minimal} supports, plus older Hewlett-Packard
20863 scanners supported by @code{hplip} package. In order to use this on
20864 a system which relies on @code{%desktop-services}, you may use
20865 @code{modify-services} (@pxref{Service Reference,
20866 @code{modify-services}}) as illustrated below:
20869 (use-modules (gnu))
20870 (use-service-modules
20873 (use-package-modules
20877 (define %my-desktop-services
20878 ;; List of desktop services that supports a broader range of scanners.
20879 (modify-services %desktop-services
20880 (sane-service-type _ => sane-backends)))
20884 (services %my-desktop-services))
20888 @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
20889 Return a configuration allowing an application to access GeoClue
20890 location data. @var{name} is the Desktop ID of the application, without
20891 the @code{.desktop} part. If @var{allowed?} is true, the application
20892 will have access to location information by default. The boolean
20893 @var{system?} value indicates whether an application is a system component
20894 or not. Finally @var{users} is a list of UIDs of all users for which
20895 this application is allowed location info access. An empty users list
20896 means that all users are allowed.
20899 @defvr {Scheme Variable} %standard-geoclue-applications
20900 The standard list of well-known GeoClue application configurations,
20901 granting authority to the GNOME date-and-time utility to ask for the
20902 current location in order to set the time zone, and allowing the
20903 IceCat and Epiphany web browsers to request location information.
20904 IceCat and Epiphany both query the user before allowing a web page to
20905 know the user's location.
20908 @deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
20909 [#:whitelist '()] @
20910 [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
20911 [#:submit-data? #f]
20912 [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
20913 [#:submission-nick "geoclue"] @
20914 [#:applications %standard-geoclue-applications]
20915 Return a service that runs the GeoClue location service. This service
20916 provides a D-Bus interface to allow applications to request access to a
20917 user's physical location, and optionally to add information to online
20918 location databases. See
20919 @uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
20920 web site} for more information.
20923 @deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
20924 [@w{#:auto-enable? #f}]
20925 Return a service that runs the @command{bluetoothd} daemon, which
20926 manages all the Bluetooth devices and provides a number of D-Bus
20927 interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
20928 powered automatically at boot, which can be useful when using a
20929 bluetooth keyboard or mouse.
20931 Users need to be in the @code{lp} group to access the D-Bus service.
20934 @defvr {Scheme Variable} gnome-keyring-service-type
20935 This is the type of the service that adds the
20936 @uref{https://wiki.gnome.org/Projects/GnomeKeyring, GNOME Keyring}. Its
20937 value is a @code{gnome-keyring-configuration} object (see below).
20939 This service adds the @code{gnome-keyring} package to the system profile
20940 and extends PAM with entries using @code{pam_gnome_keyring.so}, unlocking
20941 a user's login keyring when they log in or setting its password with passwd.
20944 @deftp {Data Type} gnome-keyring-configuration
20945 Configuration record for the GNOME Keyring service.
20948 @item @code{keyring} (default: @code{gnome-keyring})
20949 The GNOME keyring package to use.
20951 @item @code{pam-services}
20952 A list of @code{(@var{service} . @var{kind})} pairs denoting PAM
20953 services to extend, where @var{service} is the name of an existing
20954 service to extend and @var{kind} is one of @code{login} or
20957 If @code{login} is given, it adds an optional
20958 @code{pam_gnome_keyring.so} to the auth block without arguments and to
20959 the session block with @code{auto_start}. If @code{passwd} is given, it
20960 adds an optional @code{pam_gnome_keyring.so} to the password block
20963 By default, this field contains ``gdm-password'' with the value @code{login}
20964 and ``passwd'' is with the value @code{passwd}.
20969 @node Sound Services
20970 @subsection Sound Services
20972 @cindex sound support
20974 @cindex PulseAudio, sound support
20976 The @code{(gnu services sound)} module provides a service to configure the
20977 Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
20978 preferred ALSA output driver.
20980 @deffn {Scheme Variable} alsa-service-type
20981 This is the type for the @uref{https://alsa-project.org/, Advanced Linux Sound
20982 Architecture} (ALSA) system, which generates the @file{/etc/asound.conf}
20983 configuration file. The value for this type is a @command{alsa-configuration}
20984 record as in this example:
20987 (service alsa-service-type)
20990 See below for details about @code{alsa-configuration}.
20993 @deftp {Data Type} alsa-configuration
20994 Data type representing the configuration for @code{alsa-service}.
20997 @item @code{alsa-plugins} (default: @var{alsa-plugins})
20998 @code{alsa-plugins} package to use.
21000 @item @code{pulseaudio?} (default: @var{#t})
21001 Whether ALSA applications should transparently be made to use the
21002 @uref{https://www.pulseaudio.org/, PulseAudio} sound server.
21004 Using PulseAudio allows you to run several sound-producing applications
21005 at the same time and to individual control them @i{via}
21006 @command{pavucontrol}, among other things.
21008 @item @code{extra-options} (default: @var{""})
21009 String to append to the @file{/etc/asound.conf} file.
21014 Individual users who want to override the system configuration of ALSA can do
21015 it with the @file{~/.asoundrc} file:
21018 # In guix, we have to specify the absolute path for plugins.
21020 lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
21023 # Routing ALSA to jack:
21024 # <http://jackaudio.org/faq/routing_alsa.html>.
21028 0 system:playback_1
21029 1 system:playback_2
21046 See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
21049 @deffn {Scheme Variable} pulseaudio-service-type
21050 This is the type for the @uref{https://www.pulseaudio.org/, PulseAudio}
21051 sound server. It exists to allow system overrides of the default settings
21052 via @code{pulseaudio-configuration}, see below.
21055 This service overrides per-user configuration files. If you want
21056 PulseAudio to honor configuration files in @file{~/.config/pulse} you
21057 have to unset the environment variables @env{PULSE_CONFIG} and
21058 @env{PULSE_CLIENTCONFIG} in your @file{~/.bash_profile}.
21062 This service on its own does not ensure, that the @code{pulseaudio} package
21063 exists on your machine. It merely adds configuration files for it, as
21064 detailed below. In the (admittedly unlikely) case, that you find yourself
21065 without a @code{pulseaudio} package, consider enabling it through the
21066 @code{alsa-service-type} above.
21070 @deftp {Data Type} pulseaudio-configuration
21071 Data type representing the configuration for @code{pulseaudio-service}.
21074 @item @code{client-conf} (default: @code{'()})
21075 List of settings to set in @file{client.conf}.
21076 Accepts a list of strings or a symbol-value pairs. A string will be
21077 inserted as-is with a newline added. A pair will be formatted as
21078 ``key = value'', again with a newline added.
21080 @item @code{daemon-conf} (default: @code{'((flat-volumes . no))})
21081 List of settings to set in @file{daemon.conf}, formatted just like
21084 @item @code{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
21085 Script file to use as @file{default.pa}.
21087 @item @code{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
21088 Script file to use as @file{system.pa}.
21092 @deffn {Scheme Variable} ladspa-service-type
21093 This service sets the @var{LADSPA_PATH} variable, so that programs, which
21094 respect it, e.g. PulseAudio, can load LADSPA plugins.
21096 The following example will setup the service to enable modules from the
21097 @code{swh-plugins} package:
21100 (service ladspa-service-type
21101 (ladspa-configuration (plugins (list swh-plugins))))
21104 See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the
21109 @node Database Services
21110 @subsection Database Services
21114 The @code{(gnu services databases)} module provides the following services.
21116 @subsubheading PostgreSQL
21118 The following example describes a PostgreSQL service with the default
21122 (service postgresql-service-type
21123 (postgresql-configuration
21124 (postgresql postgresql-10)))
21127 If the services fails to start, it may be due to an incompatible
21128 cluster already present in @var{data-directory}. Adjust it (or, if you
21129 don't need the cluster anymore, delete @var{data-directory}), then
21130 restart the service.
21132 Peer authentication is used by default and the @code{postgres} user
21133 account has no shell, which prevents the direct execution of @code{psql}
21134 commands as this user. To use @code{psql}, you can temporarily log in
21135 as @code{postgres} using a shell, create a PostgreSQL superuser with the
21136 same name as one of the system users and then create the associated
21140 sudo -u postgres -s /bin/sh
21141 createuser --interactive
21142 createdb $MY_USER_LOGIN # Replace appropriately.
21145 @deftp {Data Type} postgresql-configuration
21146 Data type representing the configuration for the
21147 @code{postgresql-service-type}.
21150 @item @code{postgresql}
21151 PostgreSQL package to use for the service.
21153 @item @code{port} (default: @code{5432})
21154 Port on which PostgreSQL should listen.
21156 @item @code{locale} (default: @code{"en_US.utf8"})
21157 Locale to use as the default when creating the database cluster.
21159 @item @code{config-file} (default: @code{(postgresql-config-file)})
21160 The configuration file to use when running PostgreSQL@. The default
21161 behaviour uses the postgresql-config-file record with the default values
21164 @item @code{log-directory} (default: @code{"/var/log/postgresql"})
21165 The directory where @command{pg_ctl} output will be written in a file
21166 named @code{"pg_ctl.log"}. This file can be useful to debug PostgreSQL
21167 configuration errors for instance.
21169 @item @code{data-directory} (default: @code{"/var/lib/postgresql/data"})
21170 Directory in which to store the data.
21172 @item @code{extension-packages} (default: @code{'()})
21173 @cindex postgresql extension-packages
21174 Additional extensions are loaded from packages listed in
21175 @var{extension-packages}. Extensions are available at runtime. For instance,
21176 to create a geographic database using the @code{postgis} extension, a user can
21177 configure the postgresql-service as in this example:
21181 (use-package-modules databases geo)
21185 ;; postgresql is required to run `psql' but postgis is not required for
21186 ;; proper operation.
21187 (packages (cons* postgresql %base-packages))
21190 (service postgresql-service-type
21191 (postgresql-configuration
21192 (postgresql postgresql-10)
21193 (extension-packages (list postgis))))
21197 Then the extension becomes visible and you can initialise an empty geographic
21198 database in this way:
21202 > create database postgistest;
21203 > \connect postgistest;
21204 > create extension postgis;
21205 > create extension postgis_topology;
21208 There is no need to add this field for contrib extensions such as hstore or
21209 dblink as they are already loadable by postgresql. This field is only
21210 required to add extensions provided by other packages.
21215 @deftp {Data Type} postgresql-config-file
21216 Data type representing the PostgreSQL configuration file. As shown in
21217 the following example, this can be used to customize the configuration
21218 of PostgreSQL@. Note that you can use any G-expression or filename in
21219 place of this record, if you already have a configuration file you'd
21220 like to use for example.
21223 (service postgresql-service-type
21224 (postgresql-configuration
21226 (postgresql-config-file
21227 (log-destination "stderr")
21229 (plain-file "pg_hba.conf"
21231 local all all trust
21232 host all all 127.0.0.1/32 md5
21233 host all all ::1/128 md5"))
21235 '(("session_preload_libraries" "auto_explain")
21236 ("random_page_cost" 2)
21237 ("auto_explain.log_min_duration" "100 ms")
21238 ("work_mem" "500 MB")
21239 ("logging_collector" #t)
21240 ("log_directory" "/var/log/postgresql")))))))
21244 @item @code{log-destination} (default: @code{"syslog"})
21245 The logging method to use for PostgreSQL@. Multiple values are accepted,
21246 separated by commas.
21248 @item @code{hba-file} (default: @code{%default-postgres-hba})
21249 Filename or G-expression for the host-based authentication
21252 @item @code{ident-file} (default: @code{%default-postgres-ident})
21253 Filename or G-expression for the user name mapping configuration.
21255 @item @code{socket-directory} (default: @code{"/var/run/postgresql"})
21256 Specifies the directory of the Unix-domain socket(s) on which PostgreSQL
21257 is to listen for connections from client applications. If set to
21258 @code{""} PostgreSQL does not listen on any Unix-domain sockets, in
21259 which case only TCP/IP sockets can be used to connect to the server.
21261 By default, the @code{#false} value means the PostgreSQL default value
21262 will be used, which is currently @samp{/tmp}.
21264 @item @code{extra-config} (default: @code{'()})
21265 List of additional keys and values to include in the PostgreSQL config
21266 file. Each entry in the list should be a list where the first element
21267 is the key, and the remaining elements are the values.
21269 The values can be numbers, booleans or strings and will be mapped to
21270 PostgreSQL parameters types @code{Boolean}, @code{String},
21271 @code{Numeric}, @code{Numeric with Unit} and @code{Enumerated} described
21272 @uref{https://www.postgresql.org/docs/current/config-setting.html,
21278 @deffn {Scheme Variable} postgresql-role-service-type
21279 This service allows to create PostgreSQL roles and databases after
21280 PostgreSQL service start. Here is an example of its use.
21283 (service postgresql-role-service-type
21284 (postgresql-role-configuration
21286 (list (postgresql-role
21288 (create-database? #t))))))
21291 This service can be extended with extra roles, as in this
21295 (service-extension postgresql-role-service-type
21296 (const (postgresql-role
21298 (create-database? #t))))
21302 @deftp {Data Type} postgresql-role
21303 PostgreSQL manages database access permissions using the concept of
21304 roles. A role can be thought of as either a database user, or a group
21305 of database users, depending on how the role is set up. Roles can own
21306 database objects (for example, tables) and can assign privileges on
21307 those objects to other roles to control who has access to which objects.
21313 @item @code{permissions} (default: @code{'(createdb login)})
21314 The role permissions list. Supported permissions are @code{bypassrls},
21315 @code{createdb}, @code{createrole}, @code{login}, @code{replication} and
21318 @item @code{create-database?} (default: @code{#f})
21319 Whether to create a database with the same name as the role.
21324 @deftp {Data Type} postgresql-role-configuration
21325 Data type representing the configuration of
21326 @var{postgresql-role-service-type}.
21329 @item @code{host} (default: @code{"/var/run/postgresql"})
21330 The PostgreSQL host to connect to.
21332 @item @code{log} (default: @code{"/var/log/postgresql_roles.log"})
21333 File name of the log file.
21335 @item @code{roles} (default: @code{'()})
21336 The initial PostgreSQL roles to create.
21340 @subsubheading MariaDB/MySQL
21342 @defvr {Scheme Variable} mysql-service-type
21343 This is the service type for a MySQL or MariaDB database server. Its value
21344 is a @code{mysql-configuration} object that specifies which package to use,
21345 as well as various settings for the @command{mysqld} daemon.
21348 @deftp {Data Type} mysql-configuration
21349 Data type representing the configuration of @var{mysql-service-type}.
21352 @item @code{mysql} (default: @var{mariadb})
21353 Package object of the MySQL database server, can be either @var{mariadb}
21356 For MySQL, a temporary root password will be displayed at activation time.
21357 For MariaDB, the root password is empty.
21359 @item @code{bind-address} (default: @code{"127.0.0.1"})
21360 The IP on which to listen for network connections. Use @code{"0.0.0.0"}
21361 to bind to all available network interfaces.
21363 @item @code{port} (default: @code{3306})
21364 TCP port on which the database server listens for incoming connections.
21366 @item @code{socket} (default: @code{"/run/mysqld/mysqld.sock"})
21367 Socket file to use for local (non-network) connections.
21369 @item @code{extra-content} (default: @code{""})
21370 Additional settings for the @file{my.cnf} configuration file.
21372 @item @code{extra-environment} (default: @code{#~'()})
21373 List of environment variables passed to the @command{mysqld} process.
21375 @item @code{auto-upgrade?} (default: @code{#t})
21376 Whether to automatically run @command{mysql_upgrade} after starting the
21377 service. This is necessary to upgrade the @dfn{system schema} after
21378 ``major'' updates (such as switching from MariaDB 10.4 to 10.5), but can
21379 be disabled if you would rather do that manually.
21384 @subsubheading Memcached
21386 @defvr {Scheme Variable} memcached-service-type
21387 This is the service type for the @uref{https://memcached.org/,
21388 Memcached} service, which provides a distributed in memory cache. The
21389 value for the service type is a @code{memcached-configuration} object.
21393 (service memcached-service-type)
21396 @deftp {Data Type} memcached-configuration
21397 Data type representing the configuration of memcached.
21400 @item @code{memcached} (default: @code{memcached})
21401 The Memcached package to use.
21403 @item @code{interfaces} (default: @code{'("0.0.0.0")})
21404 Network interfaces on which to listen.
21406 @item @code{tcp-port} (default: @code{11211})
21407 Port on which to accept connections.
21409 @item @code{udp-port} (default: @code{11211})
21410 Port on which to accept UDP connections on, a value of 0 will disable
21411 listening on a UDP socket.
21413 @item @code{additional-options} (default: @code{'()})
21414 Additional command line options to pass to @code{memcached}.
21418 @subsubheading Redis
21420 @defvr {Scheme Variable} redis-service-type
21421 This is the service type for the @uref{https://redis.io/, Redis}
21422 key/value store, whose value is a @code{redis-configuration} object.
21425 @deftp {Data Type} redis-configuration
21426 Data type representing the configuration of redis.
21429 @item @code{redis} (default: @code{redis})
21430 The Redis package to use.
21432 @item @code{bind} (default: @code{"127.0.0.1"})
21433 Network interface on which to listen.
21435 @item @code{port} (default: @code{6379})
21436 Port on which to accept connections on, a value of 0 will disable
21437 listening on a TCP socket.
21439 @item @code{working-directory} (default: @code{"/var/lib/redis"})
21440 Directory in which to store the database and related files.
21444 @node Mail Services
21445 @subsection Mail Services
21449 The @code{(gnu services mail)} module provides Guix service definitions
21450 for email services: IMAP, POP3, and LMTP servers, as well as mail
21451 transport agents (MTAs). Lots of acronyms! These services are detailed
21452 in the subsections below.
21454 @subsubheading Dovecot Service
21456 @deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
21457 Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
21460 By default, Dovecot does not need much configuration; the default
21461 configuration object created by @code{(dovecot-configuration)} will
21462 suffice if your mail is delivered to @code{~/Maildir}. A self-signed
21463 certificate will be generated for TLS-protected connections, though
21464 Dovecot will also listen on cleartext ports by default. There are a
21465 number of options, though, which mail administrators might need to change,
21466 and as is the case with other services, Guix allows the system
21467 administrator to specify these parameters via a uniform Scheme interface.
21469 For example, to specify that mail is located at @code{maildir~/.mail},
21470 one would instantiate the Dovecot service like this:
21473 (dovecot-service #:config
21474 (dovecot-configuration
21475 (mail-location "maildir:~/.mail")))
21478 The available configuration parameters follow. Each parameter
21479 definition is preceded by its type; for example, @samp{string-list foo}
21480 indicates that the @code{foo} parameter should be specified as a list of
21481 strings. There is also a way to specify the configuration as a string,
21482 if you have an old @code{dovecot.conf} file that you want to port over
21483 from some other system; see the end for more details.
21485 @c The following documentation was initially generated by
21486 @c (generate-documentation) in (gnu services mail). Manually maintained
21487 @c documentation is better, so we shouldn't hesitate to edit below as
21488 @c needed. However if the change you want to make to this documentation
21489 @c can be done in an automated way, it's probably easier to change
21490 @c (generate-documentation) than to make it below and have to deal with
21491 @c the churn as dovecot updates.
21493 Available @code{dovecot-configuration} fields are:
21495 @deftypevr {@code{dovecot-configuration} parameter} package dovecot
21496 The dovecot package.
21499 @deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
21500 A list of IPs or hosts where to listen for connections. @samp{*}
21501 listens on all IPv4 interfaces, @samp{::} listens on all IPv6
21502 interfaces. If you want to specify non-default ports or anything more
21503 complex, customize the address and port fields of the
21504 @samp{inet-listener} of the specific services you are interested in.
21507 @deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
21508 List of protocols we want to serve. Available protocols include
21509 @samp{imap}, @samp{pop3}, and @samp{lmtp}.
21511 Available @code{protocol-configuration} fields are:
21513 @deftypevr {@code{protocol-configuration} parameter} string name
21514 The name of the protocol.
21517 @deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
21518 UNIX socket path to the master authentication server to find users.
21519 This is used by imap (for shared users) and lda.
21520 It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
21523 @deftypevr {@code{protocol-configuration} parameter} boolean imap-metadata?
21524 Whether to enable the @code{IMAP METADATA} extension as defined in
21525 @uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides
21526 a means for clients to set and retrieve per-mailbox, per-user metadata
21527 and annotations over IMAP.
21529 If this is @samp{#t}, you must also specify a dictionary @i{via} the
21530 @code{mail-attribute-dict} setting.
21532 Defaults to @samp{#f}.
21536 @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-notify-capabilities
21537 Which NOTIFY capabilities to report to clients that first connect to
21538 the ManageSieve service, before authentication. These may differ from the
21539 capabilities offered to authenticated users. If this field is left empty,
21540 report what the Sieve interpreter supports by default.
21542 Defaults to @samp{()}.
21545 @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-sieve-capability
21546 Which SIEVE capabilities to report to clients that first connect to
21547 the ManageSieve service, before authentication. These may differ from the
21548 capabilities offered to authenticated users. If this field is left empty,
21549 report what the Sieve interpreter supports by default.
21551 Defaults to @samp{()}.
21555 @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
21556 Space separated list of plugins to load.
21559 @deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
21560 Maximum number of IMAP connections allowed for a user from each IP
21561 address. NOTE: The username is compared case-sensitively.
21562 Defaults to @samp{10}.
21567 @deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
21568 List of services to enable. Available services include @samp{imap},
21569 @samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
21572 Available @code{service-configuration} fields are:
21574 @deftypevr {@code{service-configuration} parameter} string kind
21575 The service kind. Valid values include @code{director},
21576 @code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap},
21577 @code{pop3}, @code{auth}, @code{auth-worker}, @code{dict},
21578 @code{tcpwrap}, @code{quota-warning}, or anything else.
21581 @deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
21582 Listeners for the service. A listener is either a
21583 @code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
21584 an @code{inet-listener-configuration}.
21585 Defaults to @samp{()}.
21587 Available @code{unix-listener-configuration} fields are:
21589 @deftypevr {@code{unix-listener-configuration} parameter} string path
21590 Path to the file, relative to @code{base-dir} field. This is also used as
21594 @deftypevr {@code{unix-listener-configuration} parameter} string mode
21595 The access mode for the socket.
21596 Defaults to @samp{"0600"}.
21599 @deftypevr {@code{unix-listener-configuration} parameter} string user
21600 The user to own the socket.
21601 Defaults to @samp{""}.
21604 @deftypevr {@code{unix-listener-configuration} parameter} string group
21605 The group to own the socket.
21606 Defaults to @samp{""}.
21610 Available @code{fifo-listener-configuration} fields are:
21612 @deftypevr {@code{fifo-listener-configuration} parameter} string path
21613 Path to the file, relative to @code{base-dir} field. This is also used as
21617 @deftypevr {@code{fifo-listener-configuration} parameter} string mode
21618 The access mode for the socket.
21619 Defaults to @samp{"0600"}.
21622 @deftypevr {@code{fifo-listener-configuration} parameter} string user
21623 The user to own the socket.
21624 Defaults to @samp{""}.
21627 @deftypevr {@code{fifo-listener-configuration} parameter} string group
21628 The group to own the socket.
21629 Defaults to @samp{""}.
21633 Available @code{inet-listener-configuration} fields are:
21635 @deftypevr {@code{inet-listener-configuration} parameter} string protocol
21636 The protocol to listen for.
21639 @deftypevr {@code{inet-listener-configuration} parameter} string address
21640 The address on which to listen, or empty for all addresses.
21641 Defaults to @samp{""}.
21644 @deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
21645 The port on which to listen.
21648 @deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
21649 Whether to use SSL for this service; @samp{yes}, @samp{no}, or
21651 Defaults to @samp{#t}.
21656 @deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
21657 Maximum number of simultaneous client connections per process. Once
21658 this number of connections is received, the next incoming connection
21659 will prompt Dovecot to spawn another process. If set to 0,
21660 @code{default-client-limit} is used instead.
21662 Defaults to @samp{0}.
21666 @deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
21667 Number of connections to handle before starting a new process.
21668 Typically the only useful values are 0 (unlimited) or 1. 1 is more
21669 secure, but 0 is faster. <doc/wiki/LoginProcess.txt>.
21670 Defaults to @samp{1}.
21674 @deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
21675 Maximum number of processes that can exist for this service. If set to
21676 0, @code{default-process-limit} is used instead.
21678 Defaults to @samp{0}.
21682 @deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
21683 Number of processes to always keep waiting for more connections.
21684 Defaults to @samp{0}.
21687 @deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
21688 If you set @samp{service-count 0}, you probably need to grow
21690 Defaults to @samp{256000000}.
21695 @deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
21696 Dict configuration, as created by the @code{dict-configuration}
21699 Available @code{dict-configuration} fields are:
21701 @deftypevr {@code{dict-configuration} parameter} free-form-fields entries
21702 A list of key-value pairs that this dict should hold.
21703 Defaults to @samp{()}.
21708 @deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
21709 A list of passdb configurations, each one created by the
21710 @code{passdb-configuration} constructor.
21712 Available @code{passdb-configuration} fields are:
21714 @deftypevr {@code{passdb-configuration} parameter} string driver
21715 The driver that the passdb should use. Valid values include
21716 @samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
21718 Defaults to @samp{"pam"}.
21721 @deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
21722 Space separated list of arguments to the passdb driver.
21723 Defaults to @samp{""}.
21728 @deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
21729 List of userdb configurations, each one created by the
21730 @code{userdb-configuration} constructor.
21732 Available @code{userdb-configuration} fields are:
21734 @deftypevr {@code{userdb-configuration} parameter} string driver
21735 The driver that the userdb should use. Valid values include
21736 @samp{passwd} and @samp{static}.
21737 Defaults to @samp{"passwd"}.
21740 @deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
21741 Space separated list of arguments to the userdb driver.
21742 Defaults to @samp{""}.
21745 @deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
21746 Override fields from passwd.
21747 Defaults to @samp{()}.
21752 @deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
21753 Plug-in configuration, created by the @code{plugin-configuration}
21757 @deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
21758 List of namespaces. Each item in the list is created by the
21759 @code{namespace-configuration} constructor.
21761 Available @code{namespace-configuration} fields are:
21763 @deftypevr {@code{namespace-configuration} parameter} string name
21764 Name for this namespace.
21767 @deftypevr {@code{namespace-configuration} parameter} string type
21768 Namespace type: @samp{private}, @samp{shared} or @samp{public}.
21769 Defaults to @samp{"private"}.
21772 @deftypevr {@code{namespace-configuration} parameter} string separator
21773 Hierarchy separator to use. You should use the same separator for
21774 all namespaces or some clients get confused. @samp{/} is usually a good
21775 one. The default however depends on the underlying mail storage
21777 Defaults to @samp{""}.
21780 @deftypevr {@code{namespace-configuration} parameter} string prefix
21781 Prefix required to access this namespace. This needs to be
21782 different for all namespaces. For example @samp{Public/}.
21783 Defaults to @samp{""}.
21786 @deftypevr {@code{namespace-configuration} parameter} string location
21787 Physical location of the mailbox. This is in the same format as
21788 mail_location, which is also the default for it.
21789 Defaults to @samp{""}.
21792 @deftypevr {@code{namespace-configuration} parameter} boolean inbox?
21793 There can be only one INBOX, and this setting defines which
21795 Defaults to @samp{#f}.
21798 @deftypevr {@code{namespace-configuration} parameter} boolean hidden?
21799 If namespace is hidden, it's not advertised to clients via NAMESPACE
21800 extension. You'll most likely also want to set @samp{list? #f}. This is mostly
21801 useful when converting from another server with different namespaces
21802 which you want to deprecate but still keep working. For example you can
21803 create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/}
21805 Defaults to @samp{#f}.
21808 @deftypevr {@code{namespace-configuration} parameter} boolean list?
21809 Show the mailboxes under this namespace with the LIST command. This
21810 makes the namespace visible for clients that do not support the NAMESPACE
21811 extension. The special @code{children} value lists child mailboxes, but
21812 hides the namespace prefix.
21813 Defaults to @samp{#t}.
21816 @deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
21817 Namespace handles its own subscriptions. If set to @code{#f}, the
21818 parent namespace handles them. The empty prefix should always have this
21820 Defaults to @samp{#t}.
21823 @deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
21824 List of predefined mailboxes in this namespace.
21825 Defaults to @samp{()}.
21827 Available @code{mailbox-configuration} fields are:
21829 @deftypevr {@code{mailbox-configuration} parameter} string name
21830 Name for this mailbox.
21833 @deftypevr {@code{mailbox-configuration} parameter} string auto
21834 @samp{create} will automatically create this mailbox.
21835 @samp{subscribe} will both create and subscribe to the mailbox.
21836 Defaults to @samp{"no"}.
21839 @deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
21840 List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154.
21841 Valid values are @code{\All}, @code{\Archive}, @code{\Drafts},
21842 @code{\Flagged}, @code{\Junk}, @code{\Sent}, and @code{\Trash}.
21843 Defaults to @samp{()}.
21850 @deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
21851 Base directory where to store runtime data.
21852 Defaults to @samp{"/var/run/dovecot/"}.
21855 @deftypevr {@code{dovecot-configuration} parameter} string login-greeting
21856 Greeting message for clients.
21857 Defaults to @samp{"Dovecot ready."}.
21860 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
21861 List of trusted network ranges. Connections from these IPs are
21862 allowed to override their IP addresses and ports (for logging and for
21863 authentication checks). @samp{disable-plaintext-auth} is also ignored
21864 for these networks. Typically you would specify your IMAP proxy servers
21866 Defaults to @samp{()}.
21869 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
21870 List of login access check sockets (e.g.@: tcpwrap).
21871 Defaults to @samp{()}.
21874 @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
21875 Show more verbose process titles (in ps). Currently shows user name
21876 and IP address. Useful for seeing who is actually using the IMAP
21877 processes (e.g.@: shared mailboxes or if the same uid is used for multiple
21879 Defaults to @samp{#f}.
21882 @deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
21883 Should all processes be killed when Dovecot master process shuts down.
21884 Setting this to @code{#f} means that Dovecot can be upgraded without
21885 forcing existing client connections to close (although that could also
21886 be a problem if the upgrade is e.g.@: due to a security fix).
21887 Defaults to @samp{#t}.
21890 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
21891 If non-zero, run mail commands via this many connections to doveadm
21892 server, instead of running them directly in the same process.
21893 Defaults to @samp{0}.
21896 @deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
21897 UNIX socket or host:port used for connecting to doveadm server.
21898 Defaults to @samp{"doveadm-server"}.
21901 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
21902 List of environment variables that are preserved on Dovecot startup
21903 and passed down to all of its child processes. You can also give
21904 key=value pairs to always set specific settings.
21907 @deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
21908 Disable LOGIN command and all other plaintext authentications unless
21909 SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP
21910 matches the local IP (i.e.@: you're connecting from the same computer),
21911 the connection is considered secure and plaintext authentication is
21912 allowed. See also ssl=required setting.
21913 Defaults to @samp{#t}.
21916 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size
21917 Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled.
21918 Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set
21919 for caching to be used.
21920 Defaults to @samp{0}.
21923 @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl
21924 Time to live for cached data. After TTL expires the cached record
21925 is no longer used, *except* if the main database lookup returns internal
21926 failure. We also try to handle password changes automatically: If
21927 user's previous authentication was successful, but this one wasn't, the
21928 cache isn't used. For now this works only with plaintext
21930 Defaults to @samp{"1 hour"}.
21933 @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl
21934 TTL for negative hits (user not found, password mismatch).
21935 0 disables caching them completely.
21936 Defaults to @samp{"1 hour"}.
21939 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms
21940 List of realms for SASL authentication mechanisms that need them.
21941 You can leave it empty if you don't want to support multiple realms.
21942 Many clients simply use the first one listed here, so keep the default
21944 Defaults to @samp{()}.
21947 @deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
21948 Default realm/domain to use if none was specified. This is used for
21949 both SASL realms and appending @@domain to username in plaintext
21951 Defaults to @samp{""}.
21954 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
21955 List of allowed characters in username. If the user-given username
21956 contains a character not listed in here, the login automatically fails.
21957 This is just an extra check to make sure user can't exploit any
21958 potential quote escaping vulnerabilities with SQL/LDAP databases. If
21959 you want to allow all characters, set this value to empty.
21960 Defaults to @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.
21963 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation
21964 Username character translations before it's looked up from
21965 databases. The value contains series of from -> to characters. For
21966 example @samp{#@@/@@} means that @samp{#} and @samp{/} characters are
21967 translated to @samp{@@}.
21968 Defaults to @samp{""}.
21971 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-format
21972 Username formatting before it's looked up from databases. You can
21973 use the standard variables here, e.g.@: %Lu would lowercase the username,
21974 %n would drop away the domain if it was given, or @samp{%n-AT-%d} would
21975 change the @samp{@@} into @samp{-AT-}. This translation is done after
21976 @samp{auth-username-translation} changes.
21977 Defaults to @samp{"%Lu"}.
21980 @deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
21981 If you want to allow master users to log in by specifying the master
21982 username within the normal username string (i.e.@: not using SASL
21983 mechanism's support for it), you can specify the separator character
21984 here. The format is then <username><separator><master username>.
21985 UW-IMAP uses @samp{*} as the separator, so that could be a good
21987 Defaults to @samp{""}.
21990 @deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username
21991 Username to use for users logging in with ANONYMOUS SASL
21993 Defaults to @samp{"anonymous"}.
21996 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
21997 Maximum number of dovecot-auth worker processes. They're used to
21998 execute blocking passdb and userdb queries (e.g.@: MySQL and PAM).
21999 They're automatically created and destroyed as needed.
22000 Defaults to @samp{30}.
22003 @deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname
22004 Host name to use in GSSAPI principal names. The default is to use
22005 the name returned by gethostname(). Use @samp{$ALL} (with quotes) to
22006 allow all keytab entries.
22007 Defaults to @samp{""}.
22010 @deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
22011 Kerberos keytab to use for the GSSAPI mechanism. Will use the
22012 system default (usually @file{/etc/krb5.keytab}) if not specified. You may
22013 need to change the auth service to run as root to be able to read this
22015 Defaults to @samp{""}.
22018 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind?
22019 Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon
22020 and @samp{ntlm-auth} helper.
22021 <doc/wiki/Authentication/Mechanisms/Winbind.txt>.
22022 Defaults to @samp{#f}.
22025 @deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path
22026 Path for Samba's @samp{ntlm-auth} helper binary.
22027 Defaults to @samp{"/usr/bin/ntlm_auth"}.
22030 @deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay
22031 Time to delay before replying to failed authentications.
22032 Defaults to @samp{"2 secs"}.
22035 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert?
22036 Require a valid SSL client certificate or the authentication
22038 Defaults to @samp{#f}.
22041 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
22042 Take the username from client's SSL certificate, using
22043 @code{X509_NAME_get_text_by_NID()} which returns the subject's DN's
22045 Defaults to @samp{#f}.
22048 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms
22049 List of wanted authentication mechanisms. Supported mechanisms are:
22050 @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
22051 @samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
22052 @samp{otp}, @samp{skey}, and @samp{gss-spnego}. NOTE: See also
22053 @samp{disable-plaintext-auth} setting.
22056 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
22057 List of IPs or hostnames to all director servers, including ourself.
22058 Ports can be specified as ip:port. The default port is the same as what
22059 director service's @samp{inet-listener} is using.
22060 Defaults to @samp{()}.
22063 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
22064 List of IPs or hostnames to all backend mail servers. Ranges are
22065 allowed too, like 10.0.0.10-10.0.0.30.
22066 Defaults to @samp{()}.
22069 @deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
22070 How long to redirect users to a specific server after it no longer
22071 has any connections.
22072 Defaults to @samp{"15 min"}.
22075 @deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
22076 How the username is translated before being hashed. Useful values
22077 include %Ln if user can log in with or without @@domain, %Ld if mailboxes
22078 are shared within domain.
22079 Defaults to @samp{"%Lu"}.
22082 @deftypevr {@code{dovecot-configuration} parameter} string log-path
22083 Log file to use for error messages. @samp{syslog} logs to syslog,
22084 @samp{/dev/stderr} logs to stderr.
22085 Defaults to @samp{"syslog"}.
22088 @deftypevr {@code{dovecot-configuration} parameter} string info-log-path
22089 Log file to use for informational messages. Defaults to
22091 Defaults to @samp{""}.
22094 @deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
22095 Log file to use for debug messages. Defaults to
22096 @samp{info-log-path}.
22097 Defaults to @samp{""}.
22100 @deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
22101 Syslog facility to use if you're logging to syslog. Usually if you
22102 don't want to use @samp{mail}, you'll use local0..local7. Also other
22103 standard facilities are supported.
22104 Defaults to @samp{"mail"}.
22107 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
22108 Log unsuccessful authentication attempts and the reasons why they
22110 Defaults to @samp{#f}.
22113 @deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
22114 In case of password mismatches, log the attempted password. Valid
22115 values are no, plain and sha1. sha1 can be useful for detecting brute
22116 force password attempts vs. user simply trying the same password over
22117 and over again. You can also truncate the value to n chars by appending
22118 ":n" (e.g.@: sha1:6).
22119 Defaults to @samp{"no"}.
22122 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
22123 Even more verbose logging for debugging purposes. Shows for example
22125 Defaults to @samp{#f}.
22128 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
22129 In case of password mismatches, log the passwords and used scheme so
22130 the problem can be debugged. Enabling this also enables
22132 Defaults to @samp{#f}.
22135 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
22136 Enable mail process debugging. This can help you figure out why
22137 Dovecot isn't finding your mails.
22138 Defaults to @samp{#f}.
22141 @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
22142 Show protocol level SSL errors.
22143 Defaults to @samp{#f}.
22146 @deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
22147 Prefix for each line written to log file. % codes are in
22148 strftime(3) format.
22149 Defaults to @samp{"\"%b %d %H:%M:%S \""}.
22152 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
22153 List of elements we want to log. The elements which have a
22154 non-empty variable value are joined together to form a comma-separated
22158 @deftypevr {@code{dovecot-configuration} parameter} string login-log-format
22159 Login log format. %s contains @samp{login-log-format-elements}
22160 string, %$ contains the data we want to log.
22161 Defaults to @samp{"%$: %s"}.
22164 @deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
22165 Log prefix for mail processes. See doc/wiki/Variables.txt for list
22166 of possible variables you can use.
22167 Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
22170 @deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
22171 Format to use for logging mail deliveries. You can use variables:
22174 Delivery status message (e.g.@: @samp{saved to INBOX})
22186 Defaults to @samp{"msgid=%m: %$"}.
22189 @deftypevr {@code{dovecot-configuration} parameter} string mail-location
22190 Location for users' mailboxes. The default is empty, which means
22191 that Dovecot tries to find the mailboxes automatically. This won't work
22192 if the user doesn't yet have any mail, so you should explicitly tell
22193 Dovecot the full location.
22195 If you're using mbox, giving a path to the INBOX
22196 file (e.g.@: @file{/var/mail/%u}) isn't enough. You'll also need to tell Dovecot
22197 where the other mailboxes are kept. This is called the @emph{root mail
22198 directory}, and it must be the first path given in the
22199 @samp{mail-location} setting.
22201 There are a few special variables you can use, e.g.:
22207 user part in user@@domain, same as %u if there's no domain
22209 domain part in user@@domain, empty if there's no domain
22214 See doc/wiki/Variables.txt for full list. Some examples:
22216 @item maildir:~/Maildir
22217 @item mbox:~/mail:INBOX=/var/mail/%u
22218 @item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
22220 Defaults to @samp{""}.
22223 @deftypevr {@code{dovecot-configuration} parameter} string mail-uid
22224 System user and group used to access mails. If you use multiple,
22225 userdb can override these by returning uid or gid fields. You can use
22226 either numbers or names. <doc/wiki/UserIds.txt>.
22227 Defaults to @samp{""}.
22230 @deftypevr {@code{dovecot-configuration} parameter} string mail-gid
22232 Defaults to @samp{""}.
22235 @deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
22236 Group to enable temporarily for privileged operations. Currently
22237 this is used only with INBOX when either its initial creation or
22238 dotlocking fails. Typically this is set to @samp{"mail"} to give access to
22240 Defaults to @samp{""}.
22243 @deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
22244 Grant access to these supplementary groups for mail processes.
22245 Typically these are used to set up access to shared mailboxes. Note
22246 that it may be dangerous to set these if users can create symlinks
22247 (e.g.@: if @samp{mail} group is set here, @code{ln -s /var/mail ~/mail/var}
22248 could allow a user to delete others' mailboxes, or @code{ln -s
22249 /secret/shared/box ~/mail/mybox} would allow reading it). Defaults to
22253 @deftypevr {@code{dovecot-configuration} parameter} string mail-attribute-dict
22254 The location of a dictionary used to store @code{IMAP METADATA}
22255 as defined by @uref{https://tools.ietf.org/html/rfc5464, RFC@tie{}5464}.
22257 The IMAP METADATA commands are available only if the ``imap''
22258 protocol configuration's @code{imap-metadata?} field is @samp{#t}.
22260 Defaults to @samp{""}.
22264 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
22265 Allow full file system access to clients. There's no access checks
22266 other than what the operating system does for the active UID/GID@. It
22267 works with both maildir and mboxes, allowing you to prefix mailboxes
22268 names with e.g.@: @file{/path/} or @file{~user/}.
22269 Defaults to @samp{#f}.
22272 @deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
22273 Don't use @code{mmap()} at all. This is required if you store indexes to
22274 shared file systems (NFS or clustered file system).
22275 Defaults to @samp{#f}.
22278 @deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
22279 Rely on @samp{O_EXCL} to work when creating dotlock files. NFS
22280 supports @samp{O_EXCL} since version 3, so this should be safe to use
22281 nowadays by default.
22282 Defaults to @samp{#t}.
22285 @deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
22286 When to use fsync() or fdatasync() calls:
22289 Whenever necessary to avoid losing important data
22291 Useful with e.g.@: NFS when @code{write()}s are delayed
22293 Never use it (best performance, but crashes can lose data).
22295 Defaults to @samp{"optimized"}.
22298 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
22299 Mail storage exists in NFS@. Set this to yes to make Dovecot flush
22300 NFS caches whenever needed. If you're using only a single mail server
22302 Defaults to @samp{#f}.
22305 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
22306 Mail index files also exist in NFS@. Setting this to yes requires
22307 @samp{mmap-disable? #t} and @samp{fsync-disable? #f}.
22308 Defaults to @samp{#f}.
22311 @deftypevr {@code{dovecot-configuration} parameter} string lock-method
22312 Locking method for index files. Alternatives are fcntl, flock and
22313 dotlock. Dotlocking uses some tricks which may create more disk I/O
22314 than other locking methods. NFS users: flock doesn't work, remember to
22315 change @samp{mmap-disable}.
22316 Defaults to @samp{"fcntl"}.
22319 @deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
22320 Directory in which LDA/LMTP temporarily stores incoming mails >128
22322 Defaults to @samp{"/tmp"}.
22325 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
22326 Valid UID range for users. This is mostly to make sure that users can't
22327 log in as daemons or other system users. Note that denying root logins is
22328 hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
22330 Defaults to @samp{500}.
22333 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid
22335 Defaults to @samp{0}.
22338 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
22339 Valid GID range for users. Users having non-valid GID as primary group ID
22340 aren't allowed to log in. If user belongs to supplementary groups with
22341 non-valid GIDs, those groups are not set.
22342 Defaults to @samp{1}.
22345 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid
22347 Defaults to @samp{0}.
22350 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
22351 Maximum allowed length for mail keyword name. It's only forced when
22352 trying to create new keywords.
22353 Defaults to @samp{50}.
22356 @deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
22357 List of directories under which chrooting is allowed for mail
22358 processes (i.e.@: @file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}
22359 too). This setting doesn't affect @samp{login-chroot}
22360 @samp{mail-chroot} or auth chroot settings. If this setting is empty,
22361 @samp{/./} in home dirs are ignored. WARNING: Never add directories here
22362 which local users can modify, that may lead to root exploit. Usually
22363 this should be done only if you don't allow shell access for users.
22364 <doc/wiki/Chrooting.txt>.
22365 Defaults to @samp{()}.
22368 @deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
22369 Default chroot directory for mail processes. This can be overridden
22370 for specific users in user database by giving @samp{/./} in user's home
22371 directory (e.g.@: @samp{/home/./user} chroots into @file{/home}). Note that usually
22372 there is no real need to do chrooting, Dovecot doesn't allow users to
22373 access files outside their mail directory anyway. If your home
22374 directories are prefixed with the chroot directory, append @samp{/.} to
22375 @samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
22376 Defaults to @samp{""}.
22379 @deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path
22380 UNIX socket path to master authentication server to find users.
22381 This is used by imap (for shared users) and lda.
22382 Defaults to @samp{"/var/run/dovecot/auth-userdb"}.
22385 @deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
22386 Directory where to look up mail plugins.
22387 Defaults to @samp{"/usr/lib/dovecot"}.
22390 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
22391 List of plugins to load for all services. Plugins specific to IMAP,
22392 LDA, etc.@: are added to this list in their own .conf files.
22393 Defaults to @samp{()}.
22396 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
22397 The minimum number of mails in a mailbox before updates are done to
22398 cache file. This allows optimizing Dovecot's behavior to do less disk
22399 writes at the cost of more disk reads.
22400 Defaults to @samp{0}.
22403 @deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
22404 When IDLE command is running, mailbox is checked once in a while to
22405 see if there are any new mails or other changes. This setting defines
22406 the minimum time to wait between those checks. Dovecot can also use
22407 dnotify, inotify and kqueue to find out immediately when changes
22409 Defaults to @samp{"30 secs"}.
22412 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
22413 Save mails with CR+LF instead of plain LF@. This makes sending those
22414 mails take less CPU, especially with sendfile() syscall with Linux and
22415 FreeBSD@. But it also creates a bit more disk I/O which may just make it
22416 slower. Also note that if other software reads the mboxes/maildirs,
22417 they may handle the extra CRs wrong and cause problems.
22418 Defaults to @samp{#f}.
22421 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
22422 By default LIST command returns all entries in maildir beginning
22423 with a dot. Enabling this option makes Dovecot return only entries
22424 which are directories. This is done by stat()ing each entry, so it
22425 causes more disk I/O.
22426 (For systems setting struct @samp{dirent->d_type} this check is free
22427 and it's done always regardless of this setting).
22428 Defaults to @samp{#f}.
22431 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
22432 When copying a message, do it with hard links whenever possible.
22433 This makes the performance much better, and it's unlikely to have any
22435 Defaults to @samp{#t}.
22438 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
22439 Assume Dovecot is the only MUA accessing Maildir: Scan cur/
22440 directory only when its mtime changes unexpectedly or when we can't find
22441 the mail otherwise.
22442 Defaults to @samp{#f}.
22445 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
22446 Which locking methods to use for locking mbox. There are four
22451 Create <mailbox>.lock file. This is the oldest and most NFS-safe
22452 solution. If you want to use /var/mail/ like directory, the users will
22453 need write access to that directory.
22455 Same as dotlock, but if it fails because of permissions or because there
22456 isn't enough disk space, just skip it.
22458 Use this if possible. Works with NFS too if lockd is used.
22460 May not exist in all systems. Doesn't work with NFS.
22462 May not exist in all systems. Doesn't work with NFS.
22465 You can use multiple locking methods; if you do the order they're declared
22466 in is important to avoid deadlocks if other MTAs/MUAs are using multiple
22467 locking methods as well. Some operating systems don't allow using some of
22468 them simultaneously.
22471 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks
22475 @deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
22476 Maximum time to wait for lock (all of them) before aborting.
22477 Defaults to @samp{"5 mins"}.
22480 @deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
22481 If dotlock exists but the mailbox isn't modified in any way,
22482 override the lock file after this much time.
22483 Defaults to @samp{"2 mins"}.
22486 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
22487 When mbox changes unexpectedly we have to fully read it to find out
22488 what changed. If the mbox is large this can take a long time. Since
22489 the change is usually just a newly appended mail, it'd be faster to
22490 simply read the new mails. If this setting is enabled, Dovecot does
22491 this but still safely fallbacks to re-reading the whole mbox file
22492 whenever something in mbox isn't how it's expected to be. The only real
22493 downside to this setting is that if some other MUA changes message
22494 flags, Dovecot doesn't notice it immediately. Note that a full sync is
22495 done with SELECT, EXAMINE, EXPUNGE and CHECK commands.
22496 Defaults to @samp{#t}.
22499 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
22500 Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
22501 EXAMINE, EXPUNGE or CHECK commands. If this is set,
22502 @samp{mbox-dirty-syncs} is ignored.
22503 Defaults to @samp{#f}.
22506 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
22507 Delay writing mbox headers until doing a full write sync (EXPUNGE
22508 and CHECK commands and when closing the mailbox). This is especially
22509 useful for POP3 where clients often delete all mails. The downside is
22510 that our changes aren't immediately visible to other MUAs.
22511 Defaults to @samp{#t}.
22514 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
22515 If mbox size is smaller than this (e.g.@: 100k), don't write index
22516 files. If an index file already exists it's still read, just not
22518 Defaults to @samp{0}.
22521 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
22522 Maximum dbox file size until it's rotated.
22523 Defaults to @samp{10000000}.
22526 @deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
22527 Maximum dbox file age until it's rotated. Typically in days. Day
22528 begins from midnight, so 1d = today, 2d = yesterday, etc. 0 = check
22530 Defaults to @samp{"1d"}.
22533 @deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
22534 When creating new mdbox files, immediately preallocate their size to
22535 @samp{mdbox-rotate-size}. This setting currently works only in Linux
22536 with some file systems (ext4, xfs).
22537 Defaults to @samp{#f}.
22540 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
22541 sdbox and mdbox support saving mail attachments to external files,
22542 which also allows single instance storage for them. Other backends
22543 don't support this for now.
22545 WARNING: This feature hasn't been tested much yet. Use at your own risk.
22547 Directory root where to store mail attachments. Disabled, if empty.
22548 Defaults to @samp{""}.
22551 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
22552 Attachments smaller than this aren't saved externally. It's also
22553 possible to write a plugin to disable saving specific attachments
22555 Defaults to @samp{128000}.
22558 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
22559 File system backend to use for saving attachments:
22562 No SiS done by Dovecot (but this might help FS's own deduplication)
22564 SiS with immediate byte-by-byte comparison during saving
22565 @item sis-queue posix
22566 SiS with delayed comparison and deduplication.
22568 Defaults to @samp{"sis posix"}.
22571 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
22572 Hash format to use in attachment filenames. You can add any text and
22573 variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
22574 @code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be
22575 truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
22576 Defaults to @samp{"%@{sha1@}"}.
22579 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit
22581 Defaults to @samp{100}.
22584 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit
22586 Defaults to @samp{1000}.
22589 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
22590 Default VSZ (virtual memory size) limit for service processes.
22591 This is mainly intended to catch and kill processes that leak memory
22592 before they eat up everything.
22593 Defaults to @samp{256000000}.
22596 @deftypevr {@code{dovecot-configuration} parameter} string default-login-user
22597 Login user is internally used by login processes. This is the most
22598 untrusted user in Dovecot system. It shouldn't have access to anything
22600 Defaults to @samp{"dovenull"}.
22603 @deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
22604 Internal user is used by unprivileged processes. It should be
22605 separate from login user, so that login processes can't disturb other
22607 Defaults to @samp{"dovecot"}.
22610 @deftypevr {@code{dovecot-configuration} parameter} string ssl?
22611 SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>.
22612 Defaults to @samp{"required"}.
22615 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
22616 PEM encoded X.509 SSL/TLS certificate (public key).
22617 Defaults to @samp{"</etc/dovecot/default.pem"}.
22620 @deftypevr {@code{dovecot-configuration} parameter} string ssl-key
22621 PEM encoded SSL/TLS private key. The key is opened before
22622 dropping root privileges, so keep the key file unreadable by anyone but
22624 Defaults to @samp{"</etc/dovecot/private/default.pem"}.
22627 @deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
22628 If key file is password protected, give the password here.
22629 Alternatively give it when starting dovecot with -p parameter. Since
22630 this file is often world-readable, you may want to place this setting
22631 instead to a different.
22632 Defaults to @samp{""}.
22635 @deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
22636 PEM encoded trusted certificate authority. Set this only if you
22637 intend to use @samp{ssl-verify-client-cert? #t}. The file should
22638 contain the CA certificate(s) followed by the matching
22639 CRL(s). (e.g.@: @samp{ssl-ca </etc/ssl/certs/ca.pem}).
22640 Defaults to @samp{""}.
22643 @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
22644 Require that CRL check succeeds for client certificates.
22645 Defaults to @samp{#t}.
22648 @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
22649 Request client to send a certificate. If you also want to require
22650 it, set @samp{auth-ssl-require-client-cert? #t} in auth section.
22651 Defaults to @samp{#f}.
22654 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
22655 Which field from certificate to use for username. commonName and
22656 x500UniqueIdentifier are the usual choices. You'll also need to set
22657 @samp{auth-ssl-username-from-cert? #t}.
22658 Defaults to @samp{"commonName"}.
22661 @deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
22662 Minimum SSL protocol version to accept.
22663 Defaults to @samp{"TLSv1"}.
22666 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
22667 SSL ciphers to use.
22668 Defaults to @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
22671 @deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
22672 SSL crypto device to use, for valid values run "openssl engine".
22673 Defaults to @samp{""}.
22676 @deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
22677 Address to use when sending rejection mails.
22678 %d expands to recipient domain.
22679 Defaults to @samp{"postmaster@@%d"}.
22682 @deftypevr {@code{dovecot-configuration} parameter} string hostname
22683 Hostname to use in various parts of sent mails (e.g.@: in Message-Id)
22684 and in LMTP replies. Default is the system's real hostname@@domain.
22685 Defaults to @samp{""}.
22688 @deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
22689 If user is over quota, return with temporary failure instead of
22691 Defaults to @samp{#f}.
22694 @deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
22695 Binary to use for sending mails.
22696 Defaults to @samp{"/usr/sbin/sendmail"}.
22699 @deftypevr {@code{dovecot-configuration} parameter} string submission-host
22700 If non-empty, send mails via this SMTP host[:port] instead of
22702 Defaults to @samp{""}.
22705 @deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
22706 Subject: header to use for rejection mails. You can use the same
22707 variables as for @samp{rejection-reason} below.
22708 Defaults to @samp{"Rejected: %s"}.
22711 @deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
22712 Human readable error message for rejection mails. You can use
22725 Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
22728 @deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
22729 Delimiter character between local-part and detail in email
22731 Defaults to @samp{"+"}.
22734 @deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
22735 Header where the original recipient address (SMTP's RCPT TO:
22736 address) is taken from if not available elsewhere. With dovecot-lda -a
22737 parameter overrides this. A commonly used header for this is
22739 Defaults to @samp{""}.
22742 @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
22743 Should saving a mail to a nonexistent mailbox automatically create
22745 Defaults to @samp{#f}.
22748 @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
22749 Should automatically created mailboxes be also automatically
22751 Defaults to @samp{#f}.
22754 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
22755 Maximum IMAP command line length. Some clients generate very long
22756 command lines with huge mailboxes, so you may need to raise this if you
22757 get "Too long argument" or "IMAP command line too large" errors
22759 Defaults to @samp{64000}.
22762 @deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
22763 IMAP logout format string:
22766 total number of bytes read from client
22768 total number of bytes sent to client.
22770 See @file{doc/wiki/Variables.txt} for a list of all the variables you can use.
22771 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@}"}.
22774 @deftypevr {@code{dovecot-configuration} parameter} string imap-capability
22775 Override the IMAP CAPABILITY response. If the value begins with '+',
22776 add the given capabilities on top of the defaults (e.g.@: +XFOO XBAR).
22777 Defaults to @samp{""}.
22780 @deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
22781 How long to wait between "OK Still here" notifications when client
22783 Defaults to @samp{"2 mins"}.
22786 @deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
22787 ID field names and values to send to clients. Using * as the value
22788 makes Dovecot use the default value. The following fields have default
22789 values currently: name, version, os, os-version, support-url,
22791 Defaults to @samp{""}.
22794 @deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
22795 ID fields sent by client to log. * means everything.
22796 Defaults to @samp{""}.
22799 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
22800 Workarounds for various client bugs:
22803 @item delay-newmail
22804 Send EXISTS/RECENT new mail notifications only when replying to NOOP and
22805 CHECK commands. Some clients ignore them otherwise, for example OSX
22806 Mail (<v2.1). Outlook Express breaks more badly though, without this it
22807 may show user "Message no longer in server" errors. Note that OE6
22808 still breaks even with this workaround if synchronization is set to
22811 @item tb-extra-mailbox-sep
22812 Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and
22813 adds extra @samp{/} suffixes to mailbox names. This option causes Dovecot to
22814 ignore the extra @samp{/} instead of treating it as invalid mailbox name.
22816 @item tb-lsub-flags
22817 Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox).
22818 This makes Thunderbird realize they aren't selectable and show them
22819 greyed out, instead of only later giving "not selectable" popup error.
22821 Defaults to @samp{()}.
22824 @deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
22825 Host allowed in URLAUTH URLs sent by client. "*" allows all.
22826 Defaults to @samp{""}.
22830 Whew! Lots of configuration options. The nice thing about it though is
22831 that Guix has a complete interface to Dovecot's configuration
22832 language. This allows not only a nice way to declare configurations,
22833 but also offers reflective capabilities as well: users can write code to
22834 inspect and transform configurations from within Scheme.
22836 However, it could be that you just want to get a @code{dovecot.conf} up
22837 and running. In that case, you can pass an
22838 @code{opaque-dovecot-configuration} as the @code{#:config} parameter to
22839 @code{dovecot-service}. As its name indicates, an opaque configuration
22840 does not have easy reflective capabilities.
22842 Available @code{opaque-dovecot-configuration} fields are:
22844 @deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
22845 The dovecot package.
22848 @deftypevr {@code{opaque-dovecot-configuration} parameter} string string
22849 The contents of the @code{dovecot.conf}, as a string.
22852 For example, if your @code{dovecot.conf} is just the empty string, you
22853 could instantiate a dovecot service like this:
22856 (dovecot-service #:config
22857 (opaque-dovecot-configuration
22861 @subsubheading OpenSMTPD Service
22863 @deffn {Scheme Variable} opensmtpd-service-type
22864 This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD}
22865 service, whose value should be an @code{opensmtpd-configuration} object
22866 as in this example:
22869 (service opensmtpd-service-type
22870 (opensmtpd-configuration
22871 (config-file (local-file "./my-smtpd.conf"))))
22875 @deftp {Data Type} opensmtpd-configuration
22876 Data type representing the configuration of opensmtpd.
22879 @item @code{package} (default: @var{opensmtpd})
22880 Package object of the OpenSMTPD SMTP server.
22882 @item @code{config-file} (default: @code{%default-opensmtpd-file})
22883 File-like object of the OpenSMTPD configuration file to use. By default
22884 it listens on the loopback network interface, and allows for mail from
22885 users and daemons on the local machine, as well as permitting email to
22886 remote servers. Run @command{man smtpd.conf} for more information.
22891 @subsubheading Exim Service
22893 @cindex mail transfer agent (MTA)
22894 @cindex MTA (mail transfer agent)
22897 @deffn {Scheme Variable} exim-service-type
22898 This is the type of the @uref{https://exim.org, Exim} mail transfer
22899 agent (MTA), whose value should be an @code{exim-configuration} object
22900 as in this example:
22903 (service exim-service-type
22904 (exim-configuration
22905 (config-file (local-file "./my-exim.conf"))))
22909 In order to use an @code{exim-service-type} service you must also have a
22910 @code{mail-aliases-service-type} service present in your
22911 @code{operating-system} (even if it has no aliases).
22913 @deftp {Data Type} exim-configuration
22914 Data type representing the configuration of exim.
22917 @item @code{package} (default: @var{exim})
22918 Package object of the Exim server.
22920 @item @code{config-file} (default: @code{#f})
22921 File-like object of the Exim configuration file to use. If its value is
22922 @code{#f} then use the default configuration file from the package
22923 provided in @code{package}. The resulting configuration file is loaded
22924 after setting the @code{exim_user} and @code{exim_group} configuration
22930 @subsubheading Getmail service
22935 @deffn {Scheme Variable} getmail-service-type
22936 This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail}
22937 mail retriever, whose value should be an @code{getmail-configuration}.
22940 Available @code{getmail-configuration} fields are:
22942 @deftypevr {@code{getmail-configuration} parameter} symbol name
22943 A symbol to identify the getmail service.
22945 Defaults to @samp{"unset"}.
22949 @deftypevr {@code{getmail-configuration} parameter} package package
22950 The getmail package to use.
22954 @deftypevr {@code{getmail-configuration} parameter} string user
22955 The user to run getmail as.
22957 Defaults to @samp{"getmail"}.
22961 @deftypevr {@code{getmail-configuration} parameter} string group
22962 The group to run getmail as.
22964 Defaults to @samp{"getmail"}.
22968 @deftypevr {@code{getmail-configuration} parameter} string directory
22969 The getmail directory to use.
22971 Defaults to @samp{"/var/lib/getmail/default"}.
22975 @deftypevr {@code{getmail-configuration} parameter} getmail-configuration-file rcfile
22976 The getmail configuration file to use.
22978 Available @code{getmail-configuration-file} fields are:
22980 @deftypevr {@code{getmail-configuration-file} parameter} getmail-retriever-configuration retriever
22981 What mail account to retrieve mail from, and how to access that account.
22983 Available @code{getmail-retriever-configuration} fields are:
22985 @deftypevr {@code{getmail-retriever-configuration} parameter} string type
22986 The type of mail retriever to use. Valid values include @samp{passwd}
22989 Defaults to @samp{"SimpleIMAPSSLRetriever"}.
22993 @deftypevr {@code{getmail-retriever-configuration} parameter} string server
22994 Username to login to the mail server with.
22996 Defaults to @samp{unset}.
23000 @deftypevr {@code{getmail-retriever-configuration} parameter} string username
23001 Username to login to the mail server with.
23003 Defaults to @samp{unset}.
23007 @deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
23008 Port number to connect to.
23010 Defaults to @samp{#f}.
23014 @deftypevr {@code{getmail-retriever-configuration} parameter} string password
23015 Override fields from passwd.
23017 Defaults to @samp{""}.
23021 @deftypevr {@code{getmail-retriever-configuration} parameter} list password-command
23022 Override fields from passwd.
23024 Defaults to @samp{()}.
23028 @deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
23029 PEM-formatted key file to use for the TLS negotiation.
23031 Defaults to @samp{""}.
23035 @deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
23036 PEM-formatted certificate file to use for the TLS negotiation.
23038 Defaults to @samp{""}.
23042 @deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
23043 CA certificates to use.
23045 Defaults to @samp{""}.
23049 @deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
23050 Extra retriever parameters.
23052 Defaults to @samp{()}.
23058 @deftypevr {@code{getmail-configuration-file} parameter} getmail-destination-configuration destination
23059 What to do with retrieved messages.
23061 Available @code{getmail-destination-configuration} fields are:
23063 @deftypevr {@code{getmail-destination-configuration} parameter} string type
23064 The type of mail destination. Valid values include @samp{Maildir},
23065 @samp{Mboxrd} and @samp{MDA_external}.
23067 Defaults to @samp{unset}.
23071 @deftypevr {@code{getmail-destination-configuration} parameter} string-or-filelike path
23072 The path option for the mail destination. The behaviour depends on the
23075 Defaults to @samp{""}.
23079 @deftypevr {@code{getmail-destination-configuration} parameter} parameter-alist extra-parameters
23080 Extra destination parameters
23082 Defaults to @samp{()}.
23088 @deftypevr {@code{getmail-configuration-file} parameter} getmail-options-configuration options
23091 Available @code{getmail-options-configuration} fields are:
23093 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer verbose
23094 If set to @samp{0}, getmail will only print warnings and errors. A
23095 value of @samp{1} means that messages will be printed about retrieving
23096 and deleting messages. If set to @samp{2}, getmail will print messages
23097 about each of its actions.
23099 Defaults to @samp{1}.
23103 @deftypevr {@code{getmail-options-configuration} parameter} boolean read-all
23104 If true, getmail will retrieve all available messages. Otherwise it
23105 will only retrieve messages it hasn't seen previously.
23107 Defaults to @samp{#t}.
23111 @deftypevr {@code{getmail-options-configuration} parameter} boolean delete
23112 If set to true, messages will be deleted from the server after
23113 retrieving and successfully delivering them. Otherwise, messages will
23114 be left on the server.
23116 Defaults to @samp{#f}.
23120 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-after
23121 Getmail will delete messages this number of days after seeing them, if
23122 they have been delivered. This means messages will be left on the
23123 server this number of days after delivering them. A value of @samp{0}
23124 disabled this feature.
23126 Defaults to @samp{0}.
23130 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-bigger-than
23131 Delete messages larger than this of bytes after retrieving them, even if
23132 the delete and delete-after options are disabled. A value of @samp{0}
23133 disables this feature.
23135 Defaults to @samp{0}.
23139 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-bytes-per-session
23140 Retrieve messages totalling up to this number of bytes before closing
23141 the session with the server. A value of @samp{0} disables this feature.
23143 Defaults to @samp{0}.
23147 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-message-size
23148 Don't retrieve messages larger than this number of bytes. A value of
23149 @samp{0} disables this feature.
23151 Defaults to @samp{0}.
23155 @deftypevr {@code{getmail-options-configuration} parameter} boolean delivered-to
23156 If true, getmail will add a Delivered-To header to messages.
23158 Defaults to @samp{#t}.
23162 @deftypevr {@code{getmail-options-configuration} parameter} boolean received
23163 If set, getmail adds a Received header to the messages.
23165 Defaults to @samp{#t}.
23169 @deftypevr {@code{getmail-options-configuration} parameter} string message-log
23170 Getmail will record a log of its actions to the named file. A value of
23171 @samp{""} disables this feature.
23173 Defaults to @samp{""}.
23177 @deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-syslog
23178 If true, getmail will record a log of its actions using the system
23181 Defaults to @samp{#f}.
23185 @deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-verbose
23186 If true, getmail will log information about messages not retrieved and
23187 the reason for not retrieving them, as well as starting and ending
23190 Defaults to @samp{#f}.
23194 @deftypevr {@code{getmail-options-configuration} parameter} parameter-alist extra-parameters
23195 Extra options to include.
23197 Defaults to @samp{()}.
23205 @deftypevr {@code{getmail-configuration} parameter} list idle
23206 A list of mailboxes that getmail should wait on the server for new mail
23207 notifications. This depends on the server supporting the IDLE
23210 Defaults to @samp{()}.
23214 @deftypevr {@code{getmail-configuration} parameter} list environment-variables
23215 Environment variables to set for getmail.
23217 Defaults to @samp{()}.
23221 @subsubheading Mail Aliases Service
23223 @cindex email aliases
23224 @cindex aliases, for email addresses
23226 @deffn {Scheme Variable} mail-aliases-service-type
23227 This is the type of the service which provides @code{/etc/aliases},
23228 specifying how to deliver mail to users on this system.
23231 (service mail-aliases-service-type
23232 '(("postmaster" "bob")
23233 ("bob" "bob@@example.com" "bob@@example2.com")))
23237 The configuration for a @code{mail-aliases-service-type} service is an
23238 association list denoting how to deliver mail that comes to this
23239 system. Each entry is of the form @code{(alias addresses ...)}, with
23240 @code{alias} specifying the local alias and @code{addresses} specifying
23241 where to deliver this user's mail.
23243 The aliases aren't required to exist as users on the local system. In
23244 the above example, there doesn't need to be a @code{postmaster} entry in
23245 the @code{operating-system}'s @code{user-accounts} in order to deliver
23246 the @code{postmaster} mail to @code{bob} (which subsequently would
23247 deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
23249 @subsubheading GNU Mailutils IMAP4 Daemon
23250 @cindex GNU Mailutils IMAP4 Daemon
23252 @deffn {Scheme Variable} imap4d-service-type
23253 This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,,
23254 mailutils, GNU Mailutils Manual}), whose value should be an
23255 @code{imap4d-configuration} object as in this example:
23258 (service imap4d-service-type
23259 (imap4d-configuration
23260 (config-file (local-file "imap4d.conf"))))
23264 @deftp {Data Type} imap4d-configuration
23265 Data type representing the configuration of @command{imap4d}.
23268 @item @code{package} (default: @code{mailutils})
23269 The package that provides @command{imap4d}.
23271 @item @code{config-file} (default: @code{%default-imap4d-config-file})
23272 File-like object of the configuration file to use, by default it will listen
23273 on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU
23274 Mailutils Manual}, for details.
23279 @subsubheading Radicale Service
23283 @deffn {Scheme Variable} radicale-service-type
23284 This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV
23285 server whose value should be a @code{radicale-configuration}.
23288 @deftp {Data Type} radicale-configuration
23289 Data type representing the configuration of @command{radicale}.
23292 @item @code{package} (default: @code{radicale})
23293 The package that provides @command{radicale}.
23295 @item @code{config-file} (default: @code{%default-radicale-config-file})
23296 File-like object of the configuration file to use, by default it will listen
23297 on TCP port 5232 of @code{localhost} and use the @code{htpasswd} file at
23298 @file{/var/lib/radicale/users} with no (@code{plain}) encryption.
23303 @node Messaging Services
23304 @subsection Messaging Services
23309 The @code{(gnu services messaging)} module provides Guix service
23310 definitions for messaging services. Currently it provides the following
23313 @subsubheading Prosody Service
23315 @deffn {Scheme Variable} prosody-service-type
23316 This is the type for the @uref{https://prosody.im, Prosody XMPP
23317 communication server}. Its value must be a @code{prosody-configuration}
23318 record as in this example:
23321 (service prosody-service-type
23322 (prosody-configuration
23323 (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
23326 (int-component-configuration
23327 (hostname "conference.example.net")
23329 (mod-muc (mod-muc-configuration)))))
23332 (virtualhost-configuration
23333 (domain "example.net"))))))
23336 See below for details about @code{prosody-configuration}.
23340 By default, Prosody does not need much configuration. Only one
23341 @code{virtualhosts} field is needed: it specifies the domain you wish
23344 You can perform various sanity checks on the generated configuration
23345 with the @code{prosodyctl check} command.
23347 Prosodyctl will also help you to import certificates from the
23348 @code{letsencrypt} directory so that the @code{prosody} user can access
23349 them. See @url{https://prosody.im/doc/letsencrypt}.
23352 prosodyctl --root cert import /etc/letsencrypt/live
23355 The available configuration parameters follow. Each parameter
23356 definition is preceded by its type; for example, @samp{string-list foo}
23357 indicates that the @code{foo} parameter should be specified as a list of
23358 strings. Types starting with @code{maybe-} denote parameters that won't
23359 show up in @code{prosody.cfg.lua} when their value is @code{'disabled}.
23361 There is also a way to specify the configuration as a string, if you
23362 have an old @code{prosody.cfg.lua} file that you want to port over from
23363 some other system; see the end for more details.
23365 The @code{file-object} type designates either a file-like object
23366 (@pxref{G-Expressions, file-like objects}) or a file name.
23368 @c The following documentation was initially generated by
23369 @c (generate-documentation) in (gnu services messaging). Manually maintained
23370 @c documentation is better, so we shouldn't hesitate to edit below as
23371 @c needed. However if the change you want to make to this documentation
23372 @c can be done in an automated way, it's probably easier to change
23373 @c (generate-documentation) than to make it below and have to deal with
23374 @c the churn as Prosody updates.
23376 Available @code{prosody-configuration} fields are:
23378 @deftypevr {@code{prosody-configuration} parameter} package prosody
23379 The Prosody package.
23382 @deftypevr {@code{prosody-configuration} parameter} file-name data-path
23383 Location of the Prosody data storage directory. See
23384 @url{https://prosody.im/doc/configure}.
23385 Defaults to @samp{"/var/lib/prosody"}.
23388 @deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
23389 Additional plugin directories. They are searched in all the specified
23390 paths in order. See @url{https://prosody.im/doc/plugins_directory}.
23391 Defaults to @samp{()}.
23394 @deftypevr {@code{prosody-configuration} parameter} file-name certificates
23395 Every virtual host and component needs a certificate so that clients and
23396 servers can securely verify its identity. Prosody will automatically load
23397 certificates/keys from the directory specified here.
23398 Defaults to @samp{"/etc/prosody/certs"}.
23401 @deftypevr {@code{prosody-configuration} parameter} string-list admins
23402 This is a list of accounts that are admins for the server. Note that you
23403 must create the accounts separately. See @url{https://prosody.im/doc/admins} and
23404 @url{https://prosody.im/doc/creating_accounts}.
23405 Example: @code{(admins '("user1@@example.com" "user2@@example.net"))}
23406 Defaults to @samp{()}.
23409 @deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
23410 Enable use of libevent for better performance under high load. See
23411 @url{https://prosody.im/doc/libevent}.
23412 Defaults to @samp{#f}.
23415 @deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
23416 This is the list of modules Prosody will load on startup. It looks for
23417 @code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
23418 Documentation on modules can be found at:
23419 @url{https://prosody.im/doc/modules}.
23420 Defaults to @samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
23423 @deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
23424 @samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but
23425 should you want to disable them then add them to this list.
23426 Defaults to @samp{()}.
23429 @deftypevr {@code{prosody-configuration} parameter} file-object groups-file
23430 Path to a text file where the shared groups are defined. If this path is
23431 empty then @samp{mod_groups} does nothing. See
23432 @url{https://prosody.im/doc/modules/mod_groups}.
23433 Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}.
23436 @deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
23437 Disable account creation by default, for security. See
23438 @url{https://prosody.im/doc/creating_accounts}.
23439 Defaults to @samp{#f}.
23442 @deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
23443 These are the SSL/TLS-related settings. Most of them are disabled so to
23444 use Prosody's defaults. If you do not completely understand these options, do
23445 not add them to your config, it is easy to lower the security of your server
23446 using them. See @url{https://prosody.im/doc/advanced_ssl_config}.
23448 Available @code{ssl-configuration} fields are:
23450 @deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
23451 This determines what handshake to use.
23454 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name key
23455 Path to your private key file.
23458 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate
23459 Path to your certificate file.
23462 @deftypevr {@code{ssl-configuration} parameter} file-object capath
23463 Path to directory containing root certificates that you wish Prosody to
23464 trust when verifying the certificates of remote servers.
23465 Defaults to @samp{"/etc/ssl/certs"}.
23468 @deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
23469 Path to a file containing root certificates that you wish Prosody to trust.
23470 Similar to @code{capath} but with all certificates concatenated together.
23473 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
23474 A list of verification options (these mostly map to OpenSSL's
23475 @code{set_verify()} flags).
23478 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
23479 A list of general options relating to SSL/TLS@. These map to OpenSSL's
23480 @code{set_options()}. For a full list of options available in LuaSec, see the
23484 @deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
23485 How long a chain of certificate authorities to check when looking for a
23486 trusted root certificate.
23489 @deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
23490 An OpenSSL cipher string. This selects what ciphers Prosody will offer to
23491 clients, and in what order.
23494 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
23495 A path to a file containing parameters for Diffie-Hellman key exchange. You
23496 can create such a file with:
23497 @code{openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048}
23500 @deftypevr {@code{ssl-configuration} parameter} maybe-string curve
23501 Curve for Elliptic curve Diffie-Hellman. Prosody's default is
23502 @samp{"secp384r1"}.
23505 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
23506 A list of ``extra'' verification options.
23509 @deftypevr {@code{ssl-configuration} parameter} maybe-string password
23510 Password for encrypted private keys.
23515 @deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
23516 Whether to force all client-to-server connections to be encrypted or not.
23517 See @url{https://prosody.im/doc/modules/mod_tls}.
23518 Defaults to @samp{#f}.
23521 @deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
23522 Set of mechanisms that will never be offered. See
23523 @url{https://prosody.im/doc/modules/mod_saslauth}.
23524 Defaults to @samp{("DIGEST-MD5")}.
23527 @deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
23528 Whether to force all server-to-server connections to be encrypted or not.
23529 See @url{https://prosody.im/doc/modules/mod_tls}.
23530 Defaults to @samp{#f}.
23533 @deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
23534 Whether to require encryption and certificate authentication. This
23535 provides ideal security, but requires servers you communicate with to support
23536 encryption AND present valid, trusted certificates. See
23537 @url{https://prosody.im/doc/s2s#security}.
23538 Defaults to @samp{#f}.
23541 @deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
23542 Many servers don't support encryption or have invalid or self-signed
23543 certificates. You can list domains here that will not be required to
23544 authenticate using certificates. They will be authenticated using DNS@. See
23545 @url{https://prosody.im/doc/s2s#security}.
23546 Defaults to @samp{()}.
23549 @deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
23550 Even if you leave @code{s2s-secure-auth?} disabled, you can still require
23551 valid certificates for some domains by specifying a list here. See
23552 @url{https://prosody.im/doc/s2s#security}.
23553 Defaults to @samp{()}.
23556 @deftypevr {@code{prosody-configuration} parameter} string authentication
23557 Select the authentication backend to use. The default provider stores
23558 passwords in plaintext and uses Prosody's configured data storage to store the
23559 authentication data. If you do not trust your server please see
23560 @url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for information
23561 about using the hashed backend. See also
23562 @url{https://prosody.im/doc/authentication}
23563 Defaults to @samp{"internal_plain"}.
23566 @deftypevr {@code{prosody-configuration} parameter} maybe-string log
23567 Set logging options. Advanced logging configuration is not yet supported
23568 by the Prosody service. See @url{https://prosody.im/doc/logging}.
23569 Defaults to @samp{"*syslog"}.
23572 @deftypevr {@code{prosody-configuration} parameter} file-name pidfile
23573 File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}.
23574 Defaults to @samp{"/var/run/prosody/prosody.pid"}.
23577 @deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size
23578 Maximum allowed size of the HTTP body (in bytes).
23581 @deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url
23582 Some modules expose their own URL in various ways. This URL is built
23583 from the protocol, host and port used. If Prosody sits behind a proxy, the
23584 public URL will be @code{http-external-url} instead. See
23585 @url{https://prosody.im/doc/http#external_url}.
23588 @deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
23589 A host in Prosody is a domain on which user accounts can be created. For
23590 example if you want your users to have addresses like
23591 @samp{"john.smith@@example.com"} then you need to add a host
23592 @samp{"example.com"}. All options in this list will apply only to this host.
23594 Note: the name @emph{virtual} host is used in configuration to avoid confusion with
23595 the actual physical host that Prosody is installed on. A single Prosody
23596 instance can serve many domains, each one defined as a VirtualHost entry in
23597 Prosody's configuration. Conversely a server that hosts a single domain would
23598 have just one VirtualHost entry.
23600 See @url{https://prosody.im/doc/configure#virtual_host_settings}.
23602 Available @code{virtualhost-configuration} fields are:
23604 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:
23605 @deftypevr {@code{virtualhost-configuration} parameter} string domain
23606 Domain you wish Prosody to serve.
23611 @deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components
23612 Components are extra services on a server which are available to clients,
23613 usually on a subdomain of the main server (such as
23614 @samp{"mycomponent.example.com"}). Example components might be chatroom
23615 servers, user directories, or gateways to other protocols.
23617 Internal components are implemented with Prosody-specific plugins. To add an
23618 internal component, you simply fill the hostname field, and the plugin you wish
23619 to use for the component.
23621 See @url{https://prosody.im/doc/components}.
23622 Defaults to @samp{()}.
23624 Available @code{int-component-configuration} fields are:
23626 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:
23627 @deftypevr {@code{int-component-configuration} parameter} string hostname
23628 Hostname of the component.
23631 @deftypevr {@code{int-component-configuration} parameter} string plugin
23632 Plugin you wish to use for the component.
23635 @deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc
23636 Multi-user chat (MUC) is Prosody's module for allowing you to create
23637 hosted chatrooms/conferences for XMPP users.
23639 General information on setting up and using multi-user chatrooms can be found
23640 in the ``Chatrooms'' documentation (@url{https://prosody.im/doc/chatrooms}),
23641 which you should read if you are new to XMPP chatrooms.
23643 See also @url{https://prosody.im/doc/modules/mod_muc}.
23645 Available @code{mod-muc-configuration} fields are:
23647 @deftypevr {@code{mod-muc-configuration} parameter} string name
23648 The name to return in service discovery responses.
23649 Defaults to @samp{"Prosody Chatrooms"}.
23652 @deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation
23653 If @samp{#t}, this will only allow admins to create new chatrooms.
23654 Otherwise anyone can create a room. The value @samp{"local"} restricts room
23655 creation to users on the service's parent domain. E.g.@: @samp{user@@example.com}
23656 can create rooms on @samp{rooms.example.com}. The value @samp{"admin"}
23657 restricts to service administrators only.
23658 Defaults to @samp{#f}.
23661 @deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages
23662 Maximum number of history messages that will be sent to the member that has
23663 just joined the room.
23664 Defaults to @samp{20}.
23671 @deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
23672 External components use XEP-0114, which most standalone components
23673 support. To add an external component, you simply fill the hostname field. See
23674 @url{https://prosody.im/doc/components}.
23675 Defaults to @samp{()}.
23677 Available @code{ext-component-configuration} fields are:
23679 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:
23680 @deftypevr {@code{ext-component-configuration} parameter} string component-secret
23681 Password which the component will use to log in.
23684 @deftypevr {@code{ext-component-configuration} parameter} string hostname
23685 Hostname of the component.
23690 @deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
23691 Port(s) Prosody listens on for component connections.
23692 Defaults to @samp{(5347)}.
23695 @deftypevr {@code{prosody-configuration} parameter} string component-interface
23696 Interface Prosody listens on for component connections.
23697 Defaults to @samp{"127.0.0.1"}.
23700 @deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content
23701 Raw content that will be added to the configuration file.
23704 It could be that you just want to get a @code{prosody.cfg.lua}
23705 up and running. In that case, you can pass an
23706 @code{opaque-prosody-configuration} record as the value of
23707 @code{prosody-service-type}. As its name indicates, an opaque configuration
23708 does not have easy reflective capabilities.
23709 Available @code{opaque-prosody-configuration} fields are:
23711 @deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
23712 The prosody package.
23715 @deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
23716 The contents of the @code{prosody.cfg.lua} to use.
23719 For example, if your @code{prosody.cfg.lua} is just the empty
23720 string, you could instantiate a prosody service like this:
23723 (service prosody-service-type
23724 (opaque-prosody-configuration
23725 (prosody.cfg.lua "")))
23728 @c end of Prosody auto-generated documentation
23730 @subsubheading BitlBee Service
23732 @cindex IRC (Internet Relay Chat)
23733 @cindex IRC gateway
23734 @url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC
23735 interface to a variety of messaging protocols such as XMPP.
23737 @defvr {Scheme Variable} bitlbee-service-type
23738 This is the service type for the @url{https://bitlbee.org,BitlBee} IRC
23739 gateway daemon. Its value is a @code{bitlbee-configuration} (see
23742 To have BitlBee listen on port 6667 on localhost, add this line to your
23746 (service bitlbee-service-type)
23750 @deftp {Data Type} bitlbee-configuration
23751 This is the configuration for BitlBee, with the following fields:
23754 @item @code{interface} (default: @code{"127.0.0.1"})
23755 @itemx @code{port} (default: @code{6667})
23756 Listen on the network interface corresponding to the IP address
23757 specified in @var{interface}, on @var{port}.
23759 When @var{interface} is @code{127.0.0.1}, only local clients can
23760 connect; when it is @code{0.0.0.0}, connections can come from any
23761 networking interface.
23763 @item @code{bitlbee} (default: @code{bitlbee})
23764 The BitlBee package to use.
23766 @item @code{plugins} (default: @code{'()})
23767 List of plugin packages to use---e.g., @code{bitlbee-discord}.
23769 @item @code{extra-settings} (default: @code{""})
23770 Configuration snippet added as-is to the BitlBee configuration file.
23774 @subsubheading Quassel Service
23776 @cindex IRC (Internet Relay Chat)
23777 @url{https://quassel-irc.org/,Quassel} is a distributed IRC client,
23778 meaning that one or more clients can attach to and detach from the
23781 @defvr {Scheme Variable} quassel-service-type
23782 This is the service type for the @url{https://quassel-irc.org/,Quassel}
23783 IRC backend daemon. Its value is a @code{quassel-configuration}
23787 @deftp {Data Type} quassel-configuration
23788 This is the configuration for Quassel, with the following fields:
23791 @item @code{quassel} (default: @code{quassel})
23792 The Quassel package to use.
23794 @item @code{interface} (default: @code{"::,0.0.0.0"})
23795 @item @code{port} (default: @code{4242})
23796 Listen on the network interface(s) corresponding to the IPv4 or IPv6
23797 interfaces specified in the comma delimited @var{interface}, on
23800 @item @code{loglevel} (default: @code{"Info"})
23801 The level of logging desired. Accepted values are Debug, Info, Warning
23806 @node Telephony Services
23807 @subsection Telephony Services
23809 @cindex telephony, services
23810 The @code{(gnu services telephony)} module contains Guix service
23811 definitions for telephony services. Currently it provides the following
23814 @subsubheading Jami
23816 @cindex jami, service
23818 This section describes how to configure a Jami server that can be used
23819 to host video (or audio) conferences, among other uses. The following
23820 example demonstrates how to specify Jami account archives (backups) to
23821 be provisioned automatically:
23824 (service jami-service-type
23825 (jami-configuration
23827 (list (jami-account
23828 (archive "/etc/jami/unencrypted-account-1.gz"))
23830 (archive "/etc/jami/unencrypted-account-2.gz"))))))
23833 When the accounts field is specified, the Jami account files of the
23834 service found under @file{/var/lib/jami} are recreated every time the
23837 Jami accounts and their corresponding backup archives can be generated
23838 using either the @code{jami-qt} or @code{jami-gnome} Jami clients. The
23839 accounts should not be password-protected, but it is wise to ensure
23840 their files are only readable by @samp{root}.
23842 The next example shows how to declare that only some contacts should be
23843 allowed to communicate with a given account:
23846 (service jami-service-type
23847 (jami-configuration
23849 (list (jami-account
23850 (archive "/etc/jami/unencrypted-account-1.gz")
23851 (peer-discovery? #t)
23852 (rendezvous-point? #t)
23854 '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
23855 "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))
23858 In this mode, only the declared @code{allowed-contacts} can initiate
23859 communication with the Jami account. This can be used, for example,
23860 with rendezvous point accounts to create a private video conferencing
23863 To put the system administrator in full control of the conferences
23864 hosted on their system, the Jami service supports the following actions:
23867 # herd doc jami list-actions
23869 list-account-details
23870 list-banned-contacts
23879 The above actions aim to provide the most valuable actions for
23880 moderation purposes, not to cover the whole Jami API. Users wanting to
23881 interact with the Jami daemon from Guile may be interested in
23882 experimenting with the @code{(gnu build jami-service)} module, which
23883 powers the above Shepherd actions.
23885 @c TODO: This should be auto-generated from the doc already defined on
23886 @c the shepherd-actions themselves in (gnu services telephony).
23887 The @code{add-moderator} and @code{ban-contact} actions accept a contact
23888 @emph{fingerprint} (40 characters long hash) as first argument and an
23889 account fingerprint or username as second argument:
23892 # herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
23893 f3345f2775ddfe07a4b0d95daea111d15fbc1199
23895 # herd list-moderators jami
23896 Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
23897 - 1dbcb0f5f37324228235564b79f2b9737e9a008f
23901 In the case of @code{ban-contact}, the second username argument is
23902 optional; when omitted, the account is banned from all Jami accounts:
23905 # herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f
23907 # herd list-banned-contacts jami
23908 Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
23909 - 1dbcb0f5f37324228235564b79f2b9737e9a008f
23913 Banned contacts are also stripped from their moderation privileges.
23915 The @code{disable-account} action allows to completely disconnect an
23916 account from the network, making it unreachable, while
23917 @code{enable-account} does the inverse. They accept a single account
23918 username or fingerprint as first argument:
23921 # herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199
23923 # herd list-accounts jami
23924 The following Jami accounts are available:
23925 - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]
23929 The @code{list-account-details} action prints the detailed parameters of
23930 each accounts in the Recutils format, which means the @command{recsel}
23931 command can be used to select accounts of interest (@pxref{Selection
23932 Expressions,,,recutils, GNU recutils manual}). Note that period
23933 characters (@samp{.}) found in the account parameter keys are mapped to
23934 underscores (@samp{_}) in the output, to meet the requirements of the
23935 Recutils format. The following example shows how to print the account
23936 fingerprints for all accounts operating in the rendezvous point mode:
23939 # herd list-account-details jami | \
23940 recsel -p Account.username -e 'Account.rendezVous ~ "true"'
23941 Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199
23944 The remaining actions should be self-explanatory.
23946 The complete set of available configuration options is detailed below.
23948 @c TODO: Ideally, the following fragments would be auto-generated at
23949 @c build time, so that they needn't be manually duplicated.
23950 @c Auto-generated via (configuration->documentation 'jami-configuration)
23951 @deftp {Data Type} jami-configuration
23952 Available @code{jami-configuration} fields are:
23955 @item @code{jamid} (default: @code{libring}) (type: package)
23956 The Jami daemon package to use.
23958 @item @code{dbus} (default: @code{dbus}) (type: package)
23959 The D-Bus package to use to start the required D-Bus session.
23961 @item @code{nss-certs} (default: @code{nss-certs}) (type: package)
23962 The nss-certs package to use to provide TLS certificates.
23964 @item @code{enable-logging?} (default: @code{#t}) (type: boolean)
23965 Whether to enable logging to syslog.
23967 @item @code{debug?} (default: @code{#f}) (type: boolean)
23968 Whether to enable debug level messages.
23970 @item @code{auto-answer?} (default: @code{#f}) (type: boolean)
23971 Whether to force automatic answer to incoming calls.
23973 @item @code{accounts} (default: @code{disabled}) (type: maybe-jami-account-list)
23974 A list of Jami accounts to be (re-)provisioned every time the Jami
23975 daemon service starts. When providing this field, the account
23976 directories under @file{/var/lib/jami/} are recreated every time the
23977 service starts, ensuring a consistent state.
23983 @c Auto-generated via (configuration->documentation 'jami-account)
23984 @deftp {Data Type} jami-account
23985 Available @code{jami-account} fields are:
23988 @item @code{archive} (type: string-or-computed-file)
23989 The account archive (backup) file name of the account. This is used to
23990 provision the account when the service starts. The account archive
23991 should @emph{not} be encrypted. It is highly recommended to make it
23992 readable only to the @samp{root} user (i.e., not in the store), to guard
23993 against leaking the secret key material of the Jami account it contains.
23995 @item @code{allowed-contacts} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
23996 The list of allowed contacts for the account, entered as their 40
23997 characters long fingerprint. Messages or calls from accounts not in
23998 that list will be rejected. When unspecified, the configuration of the
23999 account archive is used as-is with respect to contacts and public
24000 inbound calls/messaging allowance, which typically defaults to allow any
24001 contact to communicate with the account.
24003 @item @code{moderators} (default: @code{disabled}) (type: maybe-account-fingerprint-list)
24004 The list of contacts that should have moderation privileges (to ban,
24005 mute, etc. other users) in rendezvous conferences, entered as their 40
24006 characters long fingerprint. When unspecified, the configuration of the
24007 account archive is used as-is with respect to moderation, which
24008 typically defaults to allow anyone to moderate.
24010 @item @code{rendezvous-point?} (default: @code{disabled}) (type: maybe-boolean)
24011 Whether the account should operate in the rendezvous mode. In this
24012 mode, all the incoming audio/video calls are mixed into a conference.
24013 When left unspecified, the value from the account archive prevails.
24015 @item @code{peer-discovery?} (default: @code{disabled}) (type: maybe-boolean)
24016 Whether peer discovery should be enabled. Peer discovery is used to
24017 discover other OpenDHT nodes on the local network, which can be useful
24018 to maintain communication between devices on such network even when the
24019 connection to the the Internet has been lost. When left unspecified,
24020 the value from the account archive prevails.
24022 @item @code{bootstrap-hostnames} (default: @code{disabled}) (type: maybe-string-list)
24023 A list of hostnames or IPs pointing to OpenDHT nodes, that should be
24024 used to initially join the OpenDHT network. When left unspecified, the
24025 value from the account archive prevails.
24027 @item @code{name-server-uri} (default: @code{disabled}) (type: maybe-string)
24028 The URI of the name server to use, that can be used to retrieve the
24029 account fingerprint for a registered username.
24035 @subsubheading Murmur (VoIP server)
24037 @cindex Murmur (VoIP server)
24038 @cindex VoIP server
24039 This section describes how to set up and run a Murmur server. Murmur is
24040 the server of the @uref{https://mumble.info, Mumble} voice-over-IP
24043 @deftp {Data Type} murmur-configuration
24044 The service type for the Murmur server. An example configuration can
24048 (service murmur-service-type
24049 (murmur-configuration
24051 "Welcome to this Mumble server running on Guix!")
24052 (cert-required? #t) ;disallow text password logins
24053 (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
24054 (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
24057 After reconfiguring your system, you can manually set the murmur @code{SuperUser}
24058 password with the command that is printed during the activation phase.
24060 It is recommended to register a normal Mumble user account
24061 and grant it admin or moderator rights.
24062 You can use the @code{mumble} client to
24063 login as new normal user, register yourself, and log out.
24064 For the next step login with the name @code{SuperUser} use
24065 the @code{SuperUser} password that you set previously,
24066 and grant your newly registered mumble user administrator or moderator
24067 rights and create some channels.
24069 Available @code{murmur-configuration} fields are:
24072 @item @code{package} (default: @code{mumble})
24073 Package that contains @code{bin/murmurd}.
24075 @item @code{user} (default: @code{"murmur"})
24076 User who will run the Murmur server.
24078 @item @code{group} (default: @code{"murmur"})
24079 Group of the user who will run the murmur server.
24081 @item @code{port} (default: @code{64738})
24082 Port on which the server will listen.
24084 @item @code{welcome-text} (default: @code{""})
24085 Welcome text sent to clients when they connect.
24087 @item @code{server-password} (default: @code{""})
24088 Password the clients have to enter in order to connect.
24090 @item @code{max-users} (default: @code{100})
24091 Maximum of users that can be connected to the server at once.
24093 @item @code{max-user-bandwidth} (default: @code{#f})
24094 Maximum voice traffic a user can send per second.
24096 @item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"})
24097 File name of the sqlite database.
24098 The service's user will become the owner of the directory.
24100 @item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"})
24101 File name of the log file.
24102 The service's user will become the owner of the directory.
24104 @item @code{autoban-attempts} (default: @code{10})
24105 Maximum number of logins a user can make in @code{autoban-timeframe}
24106 without getting auto banned for @code{autoban-time}.
24108 @item @code{autoban-timeframe} (default: @code{120})
24109 Timeframe for autoban in seconds.
24111 @item @code{autoban-time} (default: @code{300})
24112 Amount of time in seconds for which a client gets banned
24113 when violating the autoban limits.
24115 @item @code{opus-threshold} (default: @code{100})
24116 Percentage of clients that need to support opus
24117 before switching over to opus audio codec.
24119 @item @code{channel-nesting-limit} (default: @code{10})
24120 How deep channels can be nested at maximum.
24122 @item @code{channelname-regex} (default: @code{#f})
24123 A string in form of a Qt regular expression that channel names must conform to.
24125 @item @code{username-regex} (default: @code{#f})
24126 A string in form of a Qt regular expression that user names must conform to.
24128 @item @code{text-message-length} (default: @code{5000})
24129 Maximum size in bytes that a user can send in one text chat message.
24131 @item @code{image-message-length} (default: @code{(* 128 1024)})
24132 Maximum size in bytes that a user can send in one image message.
24134 @item @code{cert-required?} (default: @code{#f})
24135 If it is set to @code{#t} clients that use weak password authentication
24136 will not be accepted. Users must have completed the certificate wizard to join.
24138 @item @code{remember-channel?} (default: @code{#f})
24139 Should murmur remember the last channel each user was in when they disconnected
24140 and put them into the remembered channel when they rejoin.
24142 @item @code{allow-html?} (default: @code{#f})
24143 Should html be allowed in text messages, user comments, and channel descriptions.
24145 @item @code{allow-ping?} (default: @code{#f})
24146 Setting to true exposes the current user count, the maximum user count, and
24147 the server's maximum bandwidth per client to unauthenticated users. In the
24148 Mumble client, this information is shown in the Connect dialog.
24150 Disabling this setting will prevent public listing of the server.
24152 @item @code{bonjour?} (default: @code{#f})
24153 Should the server advertise itself in the local network through the bonjour protocol.
24155 @item @code{send-version?} (default: @code{#f})
24156 Should the murmur server version be exposed in ping requests.
24158 @item @code{log-days} (default: @code{31})
24159 Murmur also stores logs in the database, which are accessible via RPC.
24160 The default is 31 days of months, but you can set this setting to 0 to keep logs forever,
24161 or -1 to disable logging to the database.
24163 @item @code{obfuscate-ips?} (default: @code{#t})
24164 Should logged ips be obfuscated to protect the privacy of users.
24166 @item @code{ssl-cert} (default: @code{#f})
24167 File name of the SSL/TLS certificate used for encrypted connections.
24170 (ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")
24172 @item @code{ssl-key} (default: @code{#f})
24173 Filepath to the ssl private key used for encrypted connections.
24175 (ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")
24178 @item @code{ssl-dh-params} (default: @code{#f})
24179 File name of a PEM-encoded file with Diffie-Hellman parameters
24180 for the SSL/TLS encryption. Alternatively you set it to
24181 @code{"@@ffdhe2048"}, @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"}
24182 or @code{"@@ffdhe8192"} to use bundled parameters from RFC 7919.
24184 @item @code{ssl-ciphers} (default: @code{#f})
24185 The @code{ssl-ciphers} option chooses the cipher suites to make available for use
24188 This option is specified using
24189 @uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
24190 OpenSSL cipher list notation}.
24192 It is recommended that you try your cipher string using 'openssl ciphers <string>'
24193 before setting it here, to get a feel for which cipher suites you will get.
24194 After setting this option, it is recommend that you inspect your Murmur log
24195 to ensure that Murmur is using the cipher suites that you expected it to.
24197 Note: Changing this option may impact the backwards compatibility of your
24198 Murmur server, and can remove the ability for older Mumble clients to be able
24201 @item @code{public-registration} (default: @code{#f})
24202 Must be a @code{<murmur-public-registration-configuration>} record or @code{#f}.
24204 You can optionally register your server in the public server list that the
24205 @code{mumble} client shows on startup.
24206 You cannot register your server if you have set a @code{server-password},
24207 or set @code{allow-ping} to @code{#f}.
24209 It might take a few hours until it shows up in the public list.
24211 @item @code{file} (default: @code{#f})
24212 Optional alternative override for this configuration.
24216 @deftp {Data Type} murmur-public-registration-configuration
24217 Configuration for public registration of a murmur service.
24221 This is a display name for your server. Not to be confused with the hostname.
24223 @item @code{password}
24224 A password to identify your registration.
24225 Subsequent updates will need the same password. Don't lose your password.
24228 This should be a @code{http://} or @code{https://} link to your web
24231 @item @code{hostname} (default: @code{#f})
24232 By default your server will be listed by its IP address.
24233 If it is set your server will be linked by this host name instead.
24239 @node File-Sharing Services
24240 @subsection File-Sharing Services
24242 The @code{(gnu services file-sharing)} module provides services that
24243 assist with transferring files over peer-to-peer file-sharing networks.
24245 @subsubheading Transmission Daemon Service
24247 @uref{https://transmissionbt.com/, Transmission} is a flexible
24248 BitTorrent client that offers a variety of graphical and command-line
24249 interfaces. A @code{transmission-daemon-service-type} service provides
24250 Transmission's headless variant, @command{transmission-daemon}, as a
24251 system service, allowing users to share files via BitTorrent even when
24252 they are not logged in.
24254 @deffn {Scheme Variable} transmission-daemon-service-type
24255 The service type for the Transmission Daemon BitTorrent client. Its
24256 value must be a @code{transmission-daemon-configuration} object as in
24260 (service transmission-daemon-service-type
24261 (transmission-daemon-configuration
24262 ;; Restrict access to the RPC ("control") interface
24263 (rpc-authentication-required? #t)
24264 (rpc-username "transmission")
24266 (transmission-password-hash
24267 "transmission" ; desired password
24268 "uKd1uMs9")) ; arbitrary salt value
24270 ;; Accept requests from this and other hosts on the
24272 (rpc-whitelist-enabled? #t)
24273 (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*"))
24275 ;; Limit bandwidth use during work hours
24276 (alt-speed-down (* 1024 2)) ; 2 MB/s
24277 (alt-speed-up 512) ; 512 kB/s
24279 (alt-speed-time-enabled? #t)
24280 (alt-speed-time-day 'weekdays)
24281 (alt-speed-time-begin
24282 (+ (* 60 8) 30)) ; 8:30 am
24283 (alt-speed-time-end
24284 (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm
24288 Once the service is started, users can interact with the daemon through
24289 its Web interface (at @code{http://localhost:9091/}) or by using the
24290 @command{transmission-remote} command-line tool, available in the
24291 @code{transmission} package. (Emacs users may want to also consider the
24292 @code{emacs-transmission} package.) Both communicate with the daemon
24293 through its remote procedure call (RPC) interface, which by default is
24294 available to all users on the system; you may wish to change this by
24295 assigning values to the @code{rpc-authentication-required?},
24296 @code{rpc-username} and @code{rpc-password} settings, as shown in the
24297 example above and documented further below.
24299 The value for @code{rpc-password} must be a password hash of the type
24300 generated and used by Transmission clients. This can be copied verbatim
24301 from an existing @file{settings.json} file, if another Transmission
24302 client is already being used. Otherwise, the
24303 @code{transmission-password-hash} and @code{transmission-random-salt}
24304 procedures provided by this module can be used to obtain a suitable hash
24307 @deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt}
24308 Returns a string containing the result of hashing @var{password}
24309 together with @var{salt}, in the format recognized by Transmission
24310 clients for their @code{rpc-password} configuration setting.
24312 @var{salt} must be an eight-character string. The
24313 @code{transmission-random-salt} procedure can be used to generate a
24314 suitable salt value at random.
24317 @deffn {Scheme Procedure} transmission-random-salt
24318 Returns a string containing a random, eight-character salt value of the
24319 type generated and used by Transmission clients, suitable for passing to
24320 the @code{transmission-password-hash} procedure.
24323 These procedures are accessible from within a Guile REPL started with
24324 the @command{guix repl} command (@pxref{Invoking guix repl}). This is
24325 useful for obtaining a random salt value to provide as the second
24326 parameter to `transmission-password-hash`, as in this example session:
24330 scheme@@(guix-user)> ,use (gnu services file-sharing)
24331 scheme@@(guix-user)> (transmission-random-salt)
24335 Alternatively, a complete password hash can generated in a single step:
24338 scheme@@(guix-user)> (transmission-password-hash "transmission"
24339 (transmission-random-salt))
24340 $2 = "@{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"
24343 The resulting string can be used as-is for the value of
24344 @code{rpc-password}, allowing the password to be kept hidden even in the
24345 operating-system configuration.
24347 Torrent files downloaded by the daemon are directly accessible only to
24348 users in the ``transmission'' user group, who receive read-only access
24349 to the directory specified by the @code{download-dir} configuration
24350 setting (and also the directory specified by @code{incomplete-dir}, if
24351 @code{incomplete-dir-enabled?} is @code{#t}). Downloaded files can be
24352 moved to another directory or deleted altogether using
24353 @command{transmission-remote} with its @code{--move} and
24354 @code{--remove-and-delete} options.
24356 If the @code{watch-dir-enabled?} setting is set to @code{#t}, users in
24357 the ``transmission'' group are able also to place @file{.torrent} files
24358 in the directory specified by @code{watch-dir} to have the corresponding
24359 torrents added by the daemon. (The @code{trash-original-torrent-files?}
24360 setting controls whether the daemon deletes these files after processing
24363 Some of the daemon's configuration settings can be changed temporarily
24364 by @command{transmission-remote} and similar tools. To undo these
24365 changes, use the service's @code{reload} action to have the daemon
24366 reload its settings from disk:
24369 # herd reload transmission-daemon
24372 The full set of available configuration settings is defined by the
24373 @code{transmission-daemon-configuration} data type.
24375 @deftp {Data Type} transmission-daemon-configuration
24376 The data type representing configuration settings for Transmission
24377 Daemon. These correspond directly to the settings recognized by
24378 Transmission clients in their @file{settings.json} file.
24381 @c The following documentation was initially generated by
24382 @c (generate-transmission-daemon-documentation) in (gnu services
24383 @c file-sharing). Manually maintained documentation is better, so we
24384 @c shouldn't hesitate to edit below as needed. However if the change
24385 @c you want to make to this documentation can be done in an automated
24386 @c way, it's probably easier to change (generate-documentation) than to
24387 @c make it below and have to deal with the churn as Transmission Daemon
24390 @c %start of fragment
24392 Available @code{transmission-daemon-configuration} fields are:
24394 @deftypevr {@code{transmission-daemon-configuration} parameter} package transmission
24395 The Transmission package to use.
24399 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer stop-wait-period
24400 The period, in seconds, to wait when stopping the service for
24401 @command{transmission-daemon} to exit before killing its process. This
24402 allows the daemon time to complete its housekeeping and send a final
24403 update to trackers as it shuts down. On slow hosts, or hosts with a
24404 slow network connection, this value may need to be increased.
24406 Defaults to @samp{10}.
24410 @deftypevr {@code{transmission-daemon-configuration} parameter} string download-dir
24411 The directory to which torrent files are downloaded.
24413 Defaults to @samp{"/var/lib/transmission-daemon/downloads"}.
24417 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean incomplete-dir-enabled?
24418 If @code{#t}, files will be held in @code{incomplete-dir} while their
24419 torrent is being downloaded, then moved to @code{download-dir} once the
24420 torrent is complete. Otherwise, files for all torrents (including those
24421 still being downloaded) will be placed in @code{download-dir}.
24423 Defaults to @samp{#f}.
24427 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string incomplete-dir
24428 The directory in which files from incompletely downloaded torrents will
24429 be held when @code{incomplete-dir-enabled?} is @code{#t}.
24431 Defaults to @samp{disabled}.
24435 @deftypevr {@code{transmission-daemon-configuration} parameter} umask umask
24436 The file mode creation mask used for downloaded files. (See the
24437 @command{umask} man page for more information.)
24439 Defaults to @samp{18}.
24443 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rename-partial-files?
24444 When @code{#t}, ``.part'' is appended to the name of partially
24447 Defaults to @samp{#t}.
24451 @deftypevr {@code{transmission-daemon-configuration} parameter} preallocation-mode preallocation
24452 The mode by which space should be preallocated for downloaded files, one
24453 of @code{none}, @code{fast} (or @code{sparse}) and @code{full}.
24454 Specifying @code{full} will minimize disk fragmentation at a cost to
24455 file-creation speed.
24457 Defaults to @samp{fast}.
24461 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean watch-dir-enabled?
24462 If @code{#t}, the directory specified by @code{watch-dir} will be
24463 watched for new @file{.torrent} files and the torrents they describe
24464 added automatically (and the original files removed, if
24465 @code{trash-original-torrent-files?} is @code{#t}).
24467 Defaults to @samp{#f}.
24471 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string watch-dir
24472 The directory to be watched for @file{.torrent} files indicating new
24473 torrents to be added, when @code{watch-dir-enabled} is @code{#t}.
24475 Defaults to @samp{disabled}.
24479 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean trash-original-torrent-files?
24480 When @code{#t}, @file{.torrent} files will be deleted from the watch
24481 directory once their torrent has been added (see
24482 @code{watch-directory-enabled?}).
24484 Defaults to @samp{#f}.
24488 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-down-enabled?
24489 When @code{#t}, the daemon's download speed will be limited to the rate
24490 specified by @code{speed-limit-down}.
24492 Defaults to @samp{#f}.
24496 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-down
24497 The default global-maximum download speed, in kilobytes per second.
24499 Defaults to @samp{100}.
24503 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-up-enabled?
24504 When @code{#t}, the daemon's upload speed will be limited to the rate
24505 specified by @code{speed-limit-up}.
24507 Defaults to @samp{#f}.
24511 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-up
24512 The default global-maximum upload speed, in kilobytes per second.
24514 Defaults to @samp{100}.
24518 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-enabled?
24519 When @code{#t}, the alternate speed limits @code{alt-speed-down} and
24520 @code{alt-speed-up} are used (in place of @code{speed-limit-down} and
24521 @code{speed-limit-up}, if they are enabled) to constrain the daemon's
24522 bandwidth usage. This can be scheduled to occur automatically at
24523 certain times during the week; see @code{alt-speed-time-enabled?}.
24525 Defaults to @samp{#f}.
24529 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-down
24530 The alternate global-maximum download speed, in kilobytes per second.
24532 Defaults to @samp{50}.
24536 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-up
24537 The alternate global-maximum upload speed, in kilobytes per second.
24539 Defaults to @samp{50}.
24543 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-time-enabled?
24544 When @code{#t}, the alternate speed limits @code{alt-speed-down} and
24545 @code{alt-speed-up} will be enabled automatically during the periods
24546 specified by @code{alt-speed-time-day}, @code{alt-speed-time-begin} and
24547 @code{alt-time-speed-end}.
24549 Defaults to @samp{#f}.
24553 @deftypevr {@code{transmission-daemon-configuration} parameter} day-list alt-speed-time-day
24554 The days of the week on which the alternate-speed schedule should be
24555 used, specified either as a list of days (@code{sunday}, @code{monday},
24556 and so on) or using one of the symbols @code{weekdays}, @code{weekends}
24559 Defaults to @samp{all}.
24563 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-begin
24564 The time of day at which to enable the alternate speed limits, expressed
24565 as a number of minutes since midnight.
24567 Defaults to @samp{540}.
24571 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-end
24572 The time of day at which to disable the alternate speed limits,
24573 expressed as a number of minutes since midnight.
24575 Defaults to @samp{1020}.
24579 @deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv4
24580 The IP address at which to listen for peer connections, or ``0.0.0.0''
24581 to listen at all available IP addresses.
24583 Defaults to @samp{"0.0.0.0"}.
24587 @deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv6
24588 The IPv6 address at which to listen for peer connections, or ``::'' to
24589 listen at all available IPv6 addresses.
24591 Defaults to @samp{"::"}.
24595 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean peer-port-random-on-start?
24596 If @code{#t}, when the daemon starts it will select a port at random on
24597 which to listen for peer connections, from the range specified
24598 (inclusively) by @code{peer-port-random-low} and
24599 @code{peer-port-random-high}. Otherwise, it listens on the port
24600 specified by @code{peer-port}.
24602 Defaults to @samp{#f}.
24606 @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-low
24607 The lowest selectable port number when @code{peer-port-random-on-start?}
24610 Defaults to @samp{49152}.
24614 @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-high
24615 The highest selectable port number when @code{peer-port-random-on-start}
24618 Defaults to @samp{65535}.
24622 @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port
24623 The port on which to listen for peer connections when
24624 @code{peer-port-random-on-start?} is @code{#f}.
24626 Defaults to @samp{51413}.
24630 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean port-forwarding-enabled?
24631 If @code{#t}, the daemon will attempt to configure port-forwarding on an
24632 upstream gateway automatically using @acronym{UPnP} and
24635 Defaults to @samp{#t}.
24639 @deftypevr {@code{transmission-daemon-configuration} parameter} encryption-mode encryption
24640 The encryption preference for peer connections, one of
24641 @code{prefer-unencrypted-connections},
24642 @code{prefer-encrypted-connections} or
24643 @code{require-encrypted-connections}.
24645 Defaults to @samp{prefer-encrypted-connections}.
24649 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
24650 The TCP congestion-control algorithm to use for peer connections,
24651 specified using a string recognized by the operating system in calls to
24652 @code{setsockopt} (or set to @code{disabled}, in which case the
24653 operating-system default is used).
24655 Note that on GNU/Linux systems, the kernel must be configured to allow
24656 processes to use a congestion-control algorithm not in the default set;
24657 otherwise, it will deny these requests with ``Operation not permitted''.
24658 To see which algorithms are available on your system and which are
24659 currently permitted for use, look at the contents of the files
24660 @file{tcp_available_congestion_control} and
24661 @file{tcp_allowed_congestion_control} in the @file{/proc/sys/net/ipv4}
24664 As an example, to have Transmission Daemon use
24665 @uref{http://www-ece.rice.edu/networks/TCP-LP/,the TCP Low Priority
24666 congestion-control algorithm}, you'll need to modify your kernel
24667 configuration to build in support for the algorithm, then update your
24668 operating-system configuration to allow its use by adding a
24669 @code{sysctl-service-type} service (or updating the existing one's
24670 configuration) with lines like the following:
24673 (service sysctl-service-type
24674 (sysctl-configuration
24676 ("net.ipv4.tcp_allowed_congestion_control" .
24677 "reno cubic lp"))))
24680 The Transmission Daemon configuration can then be updated with
24683 (peer-congestion-algorithm "lp")
24686 and the system reconfigured to have the changes take effect.
24688 Defaults to @samp{disabled}.
24692 @deftypevr {@code{transmission-daemon-configuration} parameter} tcp-type-of-service peer-socket-tos
24693 The type of service to request in outgoing @acronym{TCP} packets, one of
24694 @code{default}, @code{low-cost}, @code{throughput}, @code{low-delay} and
24695 @code{reliability}.
24697 Defaults to @samp{default}.
24701 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-global
24702 The global limit on the number of connected peers.
24704 Defaults to @samp{200}.
24708 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-per-torrent
24709 The per-torrent limit on the number of connected peers.
24711 Defaults to @samp{50}.
24715 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer upload-slots-per-torrent
24716 The maximum number of peers to which the daemon will upload data
24717 simultaneously for each torrent.
24719 Defaults to @samp{14}.
24723 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-id-ttl-hours
24724 The maximum lifespan, in hours, of the peer ID associated with each
24725 public torrent before it is regenerated.
24727 Defaults to @samp{6}.
24731 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean blocklist-enabled?
24732 When @code{#t}, the daemon will ignore peers mentioned in the blocklist
24733 it has most recently downloaded from @code{blocklist-url}.
24735 Defaults to @samp{#f}.
24739 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string blocklist-url
24740 The URL of a peer blocklist (in @acronym{P2P}-plaintext or eMule
24741 @file{.dat} format) to be periodically downloaded and applied when
24742 @code{blocklist-enabled?} is @code{#t}.
24744 Defaults to @samp{disabled}.
24748 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean download-queue-enabled?
24749 If @code{#t}, the daemon will be limited to downloading at most
24750 @code{download-queue-size} non-stalled torrents simultaneously.
24752 Defaults to @samp{#t}.
24756 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer download-queue-size
24757 The size of the daemon's download queue, which limits the number of
24758 non-stalled torrents it will download at any one time when
24759 @code{download-queue-enabled?} is @code{#t}.
24761 Defaults to @samp{5}.
24765 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean seed-queue-enabled?
24766 If @code{#t}, the daemon will be limited to seeding at most
24767 @code{seed-queue-size} non-stalled torrents simultaneously.
24769 Defaults to @samp{#f}.
24773 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer seed-queue-size
24774 The size of the daemon's seed queue, which limits the number of
24775 non-stalled torrents it will seed at any one time when
24776 @code{seed-queue-enabled?} is @code{#t}.
24778 Defaults to @samp{10}.
24782 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean queue-stalled-enabled?
24783 When @code{#t}, the daemon will consider torrents for which it has not
24784 shared data in the past @code{queue-stalled-minutes} minutes to be
24785 stalled and not count them against its @code{download-queue-size} and
24786 @code{seed-queue-size} limits.
24788 Defaults to @samp{#t}.
24792 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer queue-stalled-minutes
24793 The maximum period, in minutes, a torrent may be idle before it is
24794 considered to be stalled, when @code{queue-stalled-enabled?} is
24797 Defaults to @samp{30}.
24801 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean ratio-limit-enabled?
24802 When @code{#t}, a torrent being seeded will automatically be paused once
24803 it reaches the ratio specified by @code{ratio-limit}.
24805 Defaults to @samp{#f}.
24809 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-rational ratio-limit
24810 The ratio at which a torrent being seeded will be paused, when
24811 @code{ratio-limit-enabled?} is @code{#t}.
24813 Defaults to @samp{2.0}.
24817 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean idle-seeding-limit-enabled?
24818 When @code{#t}, a torrent being seeded will automatically be paused once
24819 it has been idle for @code{idle-seeding-limit} minutes.
24821 Defaults to @samp{#f}.
24825 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer idle-seeding-limit
24826 The maximum period, in minutes, a torrent being seeded may be idle
24827 before it is paused, when @code{idle-seeding-limit-enabled?} is
24830 Defaults to @samp{30}.
24834 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean dht-enabled?
24835 Enable @uref{http://bittorrent.org/beps/bep_0005.html,the distributed
24836 hash table (@acronym{DHT}) protocol}, which supports the use of
24837 trackerless torrents.
24839 Defaults to @samp{#t}.
24843 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean lpd-enabled?
24844 Enable @uref{https://en.wikipedia.org/wiki/Local_Peer_Discovery,local
24845 peer discovery} (@acronym{LPD}), which allows the discovery of peers on
24846 the local network and may reduce the amount of data sent over the public
24849 Defaults to @samp{#f}.
24853 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean pex-enabled?
24854 Enable @uref{https://en.wikipedia.org/wiki/Peer_exchange,peer exchange}
24855 (@acronym{PEX}), which reduces the daemon's reliance on external
24856 trackers and may improve its performance.
24858 Defaults to @samp{#t}.
24862 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean utp-enabled?
24863 Enable @uref{http://bittorrent.org/beps/bep_0029.html,the micro
24864 transport protocol} (@acronym{uTP}), which aims to reduce the impact of
24865 BitTorrent traffic on other users of the local network while maintaining
24866 full utilization of the available bandwidth.
24868 Defaults to @samp{#t}.
24872 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-enabled?
24873 If @code{#t}, enable the remote procedure call (@acronym{RPC})
24874 interface, which allows remote control of the daemon via its Web
24875 interface, the @command{transmission-remote} command-line client, and
24878 Defaults to @samp{#t}.
24882 @deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-bind-address
24883 The IP address at which to listen for @acronym{RPC} connections, or
24884 ``0.0.0.0'' to listen at all available IP addresses.
24886 Defaults to @samp{"0.0.0.0"}.
24890 @deftypevr {@code{transmission-daemon-configuration} parameter} port-number rpc-port
24891 The port on which to listen for @acronym{RPC} connections.
24893 Defaults to @samp{9091}.
24897 @deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-url
24898 The path prefix to use in the @acronym{RPC}-endpoint @acronym{URL}.
24900 Defaults to @samp{"/transmission/"}.
24904 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-authentication-required?
24905 When @code{#t}, clients must authenticate (see @code{rpc-username} and
24906 @code{rpc-password}) when using the @acronym{RPC} interface. Note this
24907 has the side effect of disabling host-name whitelisting (see
24908 @code{rpc-host-whitelist-enabled?}.
24910 Defaults to @samp{#f}.
24914 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string rpc-username
24915 The username required by clients to access the @acronym{RPC} interface
24916 when @code{rpc-authentication-required?} is @code{#t}.
24918 Defaults to @samp{disabled}.
24922 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-transmission-password-hash rpc-password
24923 The password required by clients to access the @acronym{RPC} interface
24924 when @code{rpc-authentication-required?} is @code{#t}. This must be
24925 specified using a password hash in the format recognized by Transmission
24926 clients, either copied from an existing @file{settings.json} file or
24927 generated using the @code{transmission-password-hash} procedure.
24929 Defaults to @samp{disabled}.
24933 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-whitelist-enabled?
24934 When @code{#t}, @acronym{RPC} requests will be accepted only when they
24935 originate from an address specified in @code{rpc-whitelist}.
24937 Defaults to @samp{#t}.
24941 @deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-whitelist
24942 The list of IP and IPv6 addresses from which @acronym{RPC} requests will
24943 be accepted when @code{rpc-whitelist-enabled?} is @code{#t}. Wildcards
24944 may be specified using @samp{*}.
24946 Defaults to @samp{("127.0.0.1" "::1")}.
24950 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-host-whitelist-enabled?
24951 When @code{#t}, @acronym{RPC} requests will be accepted only when they
24952 are addressed to a host named in @code{rpc-host-whitelist}. Note that
24953 requests to ``localhost'' or ``localhost.'', or to a numeric address,
24954 are always accepted regardless of these settings.
24956 Note also this functionality is disabled when
24957 @code{rpc-authentication-required?} is @code{#t}.
24959 Defaults to @samp{#t}.
24963 @deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-host-whitelist
24964 The list of host names recognized by the @acronym{RPC} server when
24965 @code{rpc-host-whitelist-enabled?} is @code{#t}.
24967 Defaults to @samp{()}.
24971 @deftypevr {@code{transmission-daemon-configuration} parameter} message-level message-level
24972 The minimum severity level of messages to be logged (to
24973 @file{/var/log/transmission.log}) by the daemon, one of @code{none} (no
24974 logging), @code{error}, @code{info} and @code{debug}.
24976 Defaults to @samp{info}.
24980 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean start-added-torrents?
24981 When @code{#t}, torrents are started as soon as they are added;
24982 otherwise, they are added in ``paused'' state.
24984 Defaults to @samp{#t}.
24988 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean script-torrent-done-enabled?
24989 When @code{#t}, the script specified by
24990 @code{script-torrent-done-filename} will be invoked each time a torrent
24993 Defaults to @samp{#f}.
24997 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-file-object script-torrent-done-filename
24998 A file name or file-like object specifying a script to run each time a
24999 torrent completes, when @code{script-torrent-done-enabled?} is
25002 Defaults to @samp{disabled}.
25006 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean scrape-paused-torrents-enabled?
25007 When @code{#t}, the daemon will scrape trackers for a torrent even when
25008 the torrent is paused.
25010 Defaults to @samp{#t}.
25014 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer cache-size-mb
25015 The amount of memory, in megabytes, to allocate for the daemon's
25016 in-memory cache. A larger value may increase performance by reducing
25017 the frequency of disk I/O.
25019 Defaults to @samp{4}.
25023 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean prefetch-enabled?
25024 When @code{#t}, the daemon will try to improve I/O performance by
25025 hinting to the operating system which data is likely to be read next
25026 from disk to satisfy requests from peers.
25028 Defaults to @samp{#t}.
25033 @c %end of fragment
25037 @node Monitoring Services
25038 @subsection Monitoring Services
25040 @subsubheading Tailon Service
25042 @uref{https://tailon.readthedocs.io/, Tailon} is a web application for
25043 viewing and searching log files.
25045 The following example will configure the service with default values.
25046 By default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
25049 (service tailon-service-type)
25052 The following example customises more of the Tailon configuration,
25053 adding @command{sed} to the list of allowed commands.
25056 (service tailon-service-type
25057 (tailon-configuration
25059 (tailon-configuration-file
25060 (allowed-commands '("tail" "grep" "awk" "sed"))))))
25064 @deftp {Data Type} tailon-configuration
25065 Data type representing the configuration of Tailon.
25066 This type has the following parameters:
25069 @item @code{config-file} (default: @code{(tailon-configuration-file)})
25070 The configuration file to use for Tailon. This can be set to a
25071 @dfn{tailon-configuration-file} record value, or any gexp
25072 (@pxref{G-Expressions}).
25074 For example, to instead use a local file, the @code{local-file} function
25078 (service tailon-service-type
25079 (tailon-configuration
25080 (config-file (local-file "./my-tailon.conf"))))
25083 @item @code{package} (default: @code{tailon})
25084 The tailon package to use.
25089 @deftp {Data Type} tailon-configuration-file
25090 Data type representing the configuration options for Tailon.
25091 This type has the following parameters:
25094 @item @code{files} (default: @code{(list "/var/log")})
25095 List of files to display. The list can include strings for a single file
25096 or directory, or a list, where the first item is the name of a
25097 subsection, and the remaining items are the files or directories in that
25100 @item @code{bind} (default: @code{"localhost:8080"})
25101 Address and port to which Tailon should bind on.
25103 @item @code{relative-root} (default: @code{#f})
25104 URL path to use for Tailon, set to @code{#f} to not use a path.
25106 @item @code{allow-transfers?} (default: @code{#t})
25107 Allow downloading the log files in the web interface.
25109 @item @code{follow-names?} (default: @code{#t})
25110 Allow tailing of not-yet existent files.
25112 @item @code{tail-lines} (default: @code{200})
25113 Number of lines to read initially from each file.
25115 @item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
25116 Commands to allow running. By default, @code{sed} is disabled.
25118 @item @code{debug?} (default: @code{#f})
25119 Set @code{debug?} to @code{#t} to show debug messages.
25121 @item @code{wrap-lines} (default: @code{#t})
25122 Initial line wrapping state in the web interface. Set to @code{#t} to
25123 initially wrap lines (the default), or to @code{#f} to initially not
25126 @item @code{http-auth} (default: @code{#f})
25127 HTTP authentication type to use. Set to @code{#f} to disable
25128 authentication (the default). Supported values are @code{"digest"} or
25131 @item @code{users} (default: @code{#f})
25132 If HTTP authentication is enabled (see @code{http-auth}), access will be
25133 restricted to the credentials provided here. To configure users, use a
25134 list of pairs, where the first element of the pair is the username, and
25135 the 2nd element of the pair is the password.
25138 (tailon-configuration-file
25139 (http-auth "basic")
25140 (users '(("user1" . "password1")
25141 ("user2" . "password2"))))
25148 @subsubheading Darkstat Service
25150 Darkstat is a packet sniffer that captures network traffic, calculates
25151 statistics about usage, and serves reports over HTTP.
25153 @defvar {Scheme Variable} darkstat-service-type
25154 This is the service type for the
25155 @uref{https://unix4lyfe.org/darkstat/, darkstat}
25156 service, its value must be a @code{darkstat-configuration} record as in
25160 (service darkstat-service-type
25161 (darkstat-configuration
25162 (interface "eno1")))
25166 @deftp {Data Type} darkstat-configuration
25167 Data type representing the configuration of @command{darkstat}.
25170 @item @code{package} (default: @code{darkstat})
25171 The darkstat package to use.
25173 @item @code{interface}
25174 Capture traffic on the specified network interface.
25176 @item @code{port} (default: @code{"667"})
25177 Bind the web interface to the specified port.
25179 @item @code{bind-address} (default: @code{"127.0.0.1"})
25180 Bind the web interface to the specified address.
25182 @item @code{base} (default: @code{"/"})
25183 Specify the path of the base URL@. This can be useful if
25184 @command{darkstat} is accessed via a reverse proxy.
25189 @subsubheading Prometheus Node Exporter Service
25191 @cindex prometheus-node-exporter
25192 The Prometheus ``node exporter'' makes hardware and operating system statistics
25193 provided by the Linux kernel available for the Prometheus monitoring system.
25194 This service should be deployed on all physical nodes and virtual machines,
25195 where monitoring these statistics is desirable.
25197 @defvar {Scheme variable} prometheus-node-exporter-service-type
25198 This is the service type for the
25199 @uref{https://github.com/prometheus/node_exporter/, prometheus-node-exporter}
25200 service, its value must be a @code{prometheus-node-exporter-configuration}.
25203 (service prometheus-node-exporter-service-type)
25207 @deftp {Data Type} prometheus-node-exporter-configuration
25208 Data type representing the configuration of @command{node_exporter}.
25211 @item @code{package} (default: @code{go-github-com-prometheus-node-exporter})
25212 The prometheus-node-exporter package to use.
25214 @item @code{web-listen-address} (default: @code{":9100"})
25215 Bind the web interface to the specified address.
25217 @item @code{textfile-directory} (default: @code{"/var/lib/prometheus/node-exporter"})
25218 This directory can be used to export metrics specific to this machine.
25219 Files containing metrics in the text format, with the filename ending in
25220 @code{.prom} should be placed in this directory.
25222 @item @code{extra-options} (default: @code{'()})
25223 Extra options to pass to the Prometheus node exporter.
25228 @subsubheading Zabbix server
25229 @cindex zabbix zabbix-server
25230 Zabbix provides monitoring metrics, among others network utilization, CPU load
25231 and disk space consumption:
25234 @item High performance, high capacity (able to monitor hundreds of thousands of devices).
25235 @item Auto-discovery of servers and network devices and interfaces.
25236 @item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others.
25237 @item Distributed monitoring with centralized web administration.
25238 @item Native high performance agents.
25239 @item SLA, and ITIL KPI metrics on reporting.
25240 @item High-level (business) view of monitored resources through user-defined visual console screens and dashboards.
25241 @item Remote command execution through Zabbix proxies.
25244 @c %start of fragment
25246 Available @code{zabbix-server-configuration} fields are:
25248 @deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server
25249 The zabbix-server package.
25253 @deftypevr {@code{zabbix-server-configuration} parameter} string user
25254 User who will run the Zabbix server.
25256 Defaults to @samp{"zabbix"}.
25260 @deftypevr {@code{zabbix-server-configuration} parameter} group group
25261 Group who will run the Zabbix server.
25263 Defaults to @samp{"zabbix"}.
25267 @deftypevr {@code{zabbix-server-configuration} parameter} string db-host
25268 Database host name.
25270 Defaults to @samp{"127.0.0.1"}.
25274 @deftypevr {@code{zabbix-server-configuration} parameter} string db-name
25277 Defaults to @samp{"zabbix"}.
25281 @deftypevr {@code{zabbix-server-configuration} parameter} string db-user
25284 Defaults to @samp{"zabbix"}.
25288 @deftypevr {@code{zabbix-server-configuration} parameter} string db-password
25289 Database password. Please, use @code{include-files} with
25290 @code{DBPassword=SECRET} inside a specified file instead.
25292 Defaults to @samp{""}.
25296 @deftypevr {@code{zabbix-server-configuration} parameter} number db-port
25299 Defaults to @samp{5432}.
25303 @deftypevr {@code{zabbix-server-configuration} parameter} string log-type
25304 Specifies where log messages are written to:
25308 @code{system} - syslog.
25311 @code{file} - file specified with @code{log-file} parameter.
25314 @code{console} - standard output.
25318 Defaults to @samp{""}.
25322 @deftypevr {@code{zabbix-server-configuration} parameter} string log-file
25323 Log file name for @code{log-type} @code{file} parameter.
25325 Defaults to @samp{"/var/log/zabbix/server.log"}.
25329 @deftypevr {@code{zabbix-server-configuration} parameter} string pid-file
25332 Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}.
25336 @deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location
25337 The location of certificate authority (CA) files for SSL server
25338 certificate verification.
25340 Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}.
25344 @deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location
25345 Location of SSL client certificates.
25347 Defaults to @samp{"/etc/ssl/certs"}.
25351 @deftypevr {@code{zabbix-server-configuration} parameter} string extra-options
25352 Extra options will be appended to Zabbix server configuration file.
25354 Defaults to @samp{""}.
25358 @deftypevr {@code{zabbix-server-configuration} parameter} include-files include-files
25359 You may include individual files or all files in a directory in the
25360 configuration file.
25362 Defaults to @samp{()}.
25366 @c %end of fragment
25368 @subsubheading Zabbix agent
25369 @cindex zabbix zabbix-agent
25371 Zabbix agent gathers information for Zabbix server.
25373 @c %start of fragment
25375 Available @code{zabbix-agent-configuration} fields are:
25377 @deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent
25378 The zabbix-agent package.
25382 @deftypevr {@code{zabbix-agent-configuration} parameter} string user
25383 User who will run the Zabbix agent.
25385 Defaults to @samp{"zabbix"}.
25389 @deftypevr {@code{zabbix-agent-configuration} parameter} group group
25390 Group who will run the Zabbix agent.
25392 Defaults to @samp{"zabbix"}.
25396 @deftypevr {@code{zabbix-agent-configuration} parameter} string hostname
25397 Unique, case sensitive hostname which is required for active checks and
25398 must match hostname as configured on the server.
25400 Defaults to @samp{""}.
25404 @deftypevr {@code{zabbix-agent-configuration} parameter} string log-type
25405 Specifies where log messages are written to:
25409 @code{system} - syslog.
25412 @code{file} - file specified with @code{log-file} parameter.
25415 @code{console} - standard output.
25419 Defaults to @samp{""}.
25423 @deftypevr {@code{zabbix-agent-configuration} parameter} string log-file
25424 Log file name for @code{log-type} @code{file} parameter.
25426 Defaults to @samp{"/var/log/zabbix/agent.log"}.
25430 @deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file
25433 Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}.
25437 @deftypevr {@code{zabbix-agent-configuration} parameter} list server
25438 List of IP addresses, optionally in CIDR notation, or hostnames of
25439 Zabbix servers and Zabbix proxies. Incoming connections will be
25440 accepted only from the hosts listed here.
25442 Defaults to @samp{("127.0.0.1")}.
25446 @deftypevr {@code{zabbix-agent-configuration} parameter} list server-active
25447 List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix
25448 proxies for active checks. If port is not specified, default port is
25449 used. If this parameter is not specified, active checks are disabled.
25451 Defaults to @samp{("127.0.0.1")}.
25455 @deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options
25456 Extra options will be appended to Zabbix server configuration file.
25458 Defaults to @samp{""}.
25462 @deftypevr {@code{zabbix-agent-configuration} parameter} include-files include-files
25463 You may include individual files or all files in a directory in the
25464 configuration file.
25466 Defaults to @samp{()}.
25470 @c %end of fragment
25472 @subsubheading Zabbix front-end
25473 @cindex zabbix zabbix-front-end
25475 This service provides a WEB interface to Zabbix server.
25477 @c %start of fragment
25479 Available @code{zabbix-front-end-configuration} fields are:
25481 @deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx
25482 NGINX configuration.
25486 @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host
25487 Database host name.
25489 Defaults to @samp{"localhost"}.
25493 @deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port
25496 Defaults to @samp{5432}.
25500 @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name
25503 Defaults to @samp{"zabbix"}.
25507 @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user
25510 Defaults to @samp{"zabbix"}.
25514 @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password
25515 Database password. Please, use @code{db-secret-file} instead.
25517 Defaults to @samp{""}.
25521 @deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file
25522 Secret file containing the credentials for the Zabbix front-end. The value
25523 must be a local file name, not a G-expression. You are expected to create
25524 this file manually. Its contents will be copied into @file{zabbix.conf.php}
25525 as the value of @code{$DB['PASSWORD']}.
25527 Defaults to @samp{""}.
25531 @deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host
25532 Zabbix server hostname.
25534 Defaults to @samp{"localhost"}.
25538 @deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port
25539 Zabbix server port.
25541 Defaults to @samp{10051}.
25546 @c %end of fragment
25548 @node Kerberos Services
25549 @subsection Kerberos Services
25552 The @code{(gnu services kerberos)} module provides services relating to
25553 the authentication protocol @dfn{Kerberos}.
25555 @subsubheading Krb5 Service
25557 Programs using a Kerberos client library normally
25558 expect a configuration file in @file{/etc/krb5.conf}.
25559 This service generates such a file from a definition provided in the
25560 operating system declaration.
25561 It does not cause any daemon to be started.
25563 No ``keytab'' files are provided by this service---you must explicitly create them.
25564 This service is known to work with the MIT client library, @code{mit-krb5}.
25565 Other implementations have not been tested.
25567 @defvr {Scheme Variable} krb5-service-type
25568 A service type for Kerberos 5 clients.
25572 Here is an example of its use:
25574 (service krb5-service-type
25575 (krb5-configuration
25576 (default-realm "EXAMPLE.COM")
25577 (allow-weak-crypto? #t)
25580 (name "EXAMPLE.COM")
25581 (admin-server "groucho.example.com")
25582 (kdc "karl.example.com"))
25585 (admin-server "kerb-admin.argrx.edu")
25586 (kdc "keys.argrx.edu"))))))
25590 This example provides a Kerberos@tie{}5 client configuration which:
25592 @item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both
25593 of which have distinct administration servers and key distribution centers;
25594 @item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly
25595 specified by clients;
25596 @item Accepts services which only support encryption types known to be weak.
25599 The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
25600 Only the most commonly used ones are described here.
25601 For a full list, and more detailed explanation of each, see the MIT
25602 @uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
25606 @deftp {Data Type} krb5-realm
25607 @cindex realm, kerberos
25610 This field is a string identifying the name of the realm.
25611 A common convention is to use the fully qualified DNS name of your organization,
25612 converted to upper case.
25614 @item @code{admin-server}
25615 This field is a string identifying the host where the administration server is
25619 This field is a string identifying the key distribution center
25624 @deftp {Data Type} krb5-configuration
25627 @item @code{allow-weak-crypto?} (default: @code{#f})
25628 If this flag is @code{#t} then services which only offer encryption algorithms
25629 known to be weak will be accepted.
25631 @item @code{default-realm} (default: @code{#f})
25632 This field should be a string identifying the default Kerberos
25633 realm for the client.
25634 You should set this field to the name of your Kerberos realm.
25635 If this value is @code{#f}
25636 then a realm must be specified with every Kerberos principal when invoking programs
25637 such as @command{kinit}.
25639 @item @code{realms}
25640 This should be a non-empty list of @code{krb5-realm} objects, which clients may
25642 Normally, one of them will have a @code{name} field matching the @code{default-realm}
25648 @subsubheading PAM krb5 Service
25651 The @code{pam-krb5} service allows for login authentication and password
25652 management via Kerberos.
25653 You will need this service if you want PAM enabled applications to authenticate
25654 users using Kerberos.
25656 @defvr {Scheme Variable} pam-krb5-service-type
25657 A service type for the Kerberos 5 PAM module.
25660 @deftp {Data Type} pam-krb5-configuration
25661 Data type representing the configuration of the Kerberos 5 PAM module.
25662 This type has the following parameters:
25664 @item @code{pam-krb5} (default: @code{pam-krb5})
25665 The pam-krb5 package to use.
25667 @item @code{minimum-uid} (default: @code{1000})
25668 The smallest user ID for which Kerberos authentications should be attempted.
25669 Local accounts with lower values will silently fail to authenticate.
25674 @node LDAP Services
25675 @subsection LDAP Services
25677 @cindex nslcd, LDAP service
25679 The @code{(gnu services authentication)} module provides the
25680 @code{nslcd-service-type}, which can be used to authenticate against an LDAP
25681 server. In addition to configuring the service itself, you may want to add
25682 @code{ldap} as a name service to the Name Service Switch. @xref{Name Service
25683 Switch} for detailed information.
25685 Here is a simple operating system declaration with a default configuration of
25686 the @code{nslcd-service-type} and a Name Service Switch configuration that
25687 consults the @code{ldap} name service last:
25690 (use-service-modules authentication)
25691 (use-modules (gnu system nss))
25697 (service nslcd-service-type)
25698 (service dhcp-client-service-type)
25700 (name-service-switch
25701 (let ((services (list (name-service (name "db"))
25702 (name-service (name "files"))
25703 (name-service (name "ldap")))))
25704 (name-service-switch
25705 (inherit %mdns-host-lookup-nss)
25706 (password services)
25709 (netgroup services)
25710 (gshadow services)))))
25713 @c %start of generated documentation for nslcd-configuration
25715 Available @code{nslcd-configuration} fields are:
25717 @deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd
25718 The @code{nss-pam-ldapd} package to use.
25722 @deftypevr {@code{nslcd-configuration} parameter} maybe-number threads
25723 The number of threads to start that can handle requests and perform LDAP
25724 queries. Each thread opens a separate connection to the LDAP server.
25725 The default is to start 5 threads.
25727 Defaults to @samp{disabled}.
25731 @deftypevr {@code{nslcd-configuration} parameter} string uid
25732 This specifies the user id with which the daemon should be run.
25734 Defaults to @samp{"nslcd"}.
25738 @deftypevr {@code{nslcd-configuration} parameter} string gid
25739 This specifies the group id with which the daemon should be run.
25741 Defaults to @samp{"nslcd"}.
25745 @deftypevr {@code{nslcd-configuration} parameter} log-option log
25746 This option controls the way logging is done via a list containing
25747 SCHEME and LEVEL@. The SCHEME argument may either be the symbols
25748 @samp{none} or @samp{syslog}, or an absolute file name. The LEVEL
25749 argument is optional and specifies the log level. The log level may be
25750 one of the following symbols: @samp{crit}, @samp{error}, @samp{warning},
25751 @samp{notice}, @samp{info} or @samp{debug}. All messages with the
25752 specified log level or higher are logged.
25754 Defaults to @samp{("/var/log/nslcd" info)}.
25758 @deftypevr {@code{nslcd-configuration} parameter} list uri
25759 The list of LDAP server URIs. Normally, only the first server will be
25760 used with the following servers as fall-back.
25762 Defaults to @samp{("ldap://localhost:389/")}.
25766 @deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version
25767 The version of the LDAP protocol to use. The default is to use the
25768 maximum version supported by the LDAP library.
25770 Defaults to @samp{disabled}.
25774 @deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn
25775 Specifies the distinguished name with which to bind to the directory
25776 server for lookups. The default is to bind anonymously.
25778 Defaults to @samp{disabled}.
25782 @deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw
25783 Specifies the credentials with which to bind. This option is only
25784 applicable when used with binddn.
25786 Defaults to @samp{disabled}.
25790 @deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn
25791 Specifies the distinguished name to use when the root user tries to
25792 modify a user's password using the PAM module.
25794 Defaults to @samp{disabled}.
25798 @deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw
25799 Specifies the credentials with which to bind if the root user tries to
25800 change a user's password. This option is only applicable when used with
25803 Defaults to @samp{disabled}.
25807 @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech
25808 Specifies the SASL mechanism to be used when performing SASL
25811 Defaults to @samp{disabled}.
25815 @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm
25816 Specifies the SASL realm to be used when performing SASL authentication.
25818 Defaults to @samp{disabled}.
25822 @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid
25823 Specifies the authentication identity to be used when performing SASL
25826 Defaults to @samp{disabled}.
25830 @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid
25831 Specifies the authorization identity to be used when performing SASL
25834 Defaults to @samp{disabled}.
25838 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize?
25839 Determines whether the LDAP server host name should be canonicalised. If
25840 this is enabled the LDAP library will do a reverse host name lookup. By
25841 default, it is left up to the LDAP library whether this check is
25844 Defaults to @samp{disabled}.
25848 @deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname
25849 Set the name for the GSS-API Kerberos credentials cache.
25851 Defaults to @samp{disabled}.
25855 @deftypevr {@code{nslcd-configuration} parameter} string base
25856 The directory search base.
25858 Defaults to @samp{"dc=example,dc=com"}.
25862 @deftypevr {@code{nslcd-configuration} parameter} scope-option scope
25863 Specifies the search scope (subtree, onelevel, base or children). The
25864 default scope is subtree; base scope is almost never useful for name
25865 service lookups; children scope is not supported on all servers.
25867 Defaults to @samp{(subtree)}.
25871 @deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref
25872 Specifies the policy for dereferencing aliases. The default policy is
25873 to never dereference aliases.
25875 Defaults to @samp{disabled}.
25879 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals
25880 Specifies whether automatic referral chasing should be enabled. The
25881 default behaviour is to chase referrals.
25883 Defaults to @samp{disabled}.
25887 @deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps
25888 This option allows for custom attributes to be looked up instead of the
25889 default RFC 2307 attributes. It is a list of maps, each consisting of
25890 the name of a map, the RFC 2307 attribute to match and the query
25891 expression for the attribute as it is available in the directory.
25893 Defaults to @samp{()}.
25897 @deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters
25898 A list of filters consisting of the name of a map to which the filter
25899 applies and an LDAP search filter expression.
25901 Defaults to @samp{()}.
25905 @deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit
25906 Specifies the time limit in seconds to use when connecting to the
25907 directory server. The default value is 10 seconds.
25909 Defaults to @samp{disabled}.
25913 @deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit
25914 Specifies the time limit (in seconds) to wait for a response from the
25915 LDAP server. A value of zero, which is the default, is to wait
25916 indefinitely for searches to be completed.
25918 Defaults to @samp{disabled}.
25922 @deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit
25923 Specifies the period if inactivity (in seconds) after which the con‐
25924 nection to the LDAP server will be closed. The default is not to time
25927 Defaults to @samp{disabled}.
25931 @deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime
25932 Specifies the number of seconds to sleep when connecting to all LDAP
25933 servers fails. By default one second is waited between the first
25934 failure and the first retry.
25936 Defaults to @samp{disabled}.
25940 @deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime
25941 Specifies the time after which the LDAP server is considered to be
25942 permanently unavailable. Once this time is reached retries will be done
25943 only once per this time period. The default value is 10 seconds.
25945 Defaults to @samp{disabled}.
25949 @deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl
25950 Specifies whether to use SSL/TLS or not (the default is not to). If
25951 'start-tls is specified then StartTLS is used rather than raw LDAP over
25954 Defaults to @samp{disabled}.
25958 @deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert
25959 Specifies what checks to perform on a server-supplied certificate. The
25960 meaning of the values is described in the ldap.conf(5) manual page.
25962 Defaults to @samp{disabled}.
25966 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir
25967 Specifies the directory containing X.509 certificates for peer authen‐
25968 tication. This parameter is ignored when using GnuTLS.
25970 Defaults to @samp{disabled}.
25974 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile
25975 Specifies the path to the X.509 certificate for peer authentication.
25977 Defaults to @samp{disabled}.
25981 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile
25982 Specifies the path to an entropy source. This parameter is ignored when
25985 Defaults to @samp{disabled}.
25989 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers
25990 Specifies the ciphers to use for TLS as a string.
25992 Defaults to @samp{disabled}.
25996 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert
25997 Specifies the path to the file containing the local certificate for
25998 client TLS authentication.
26000 Defaults to @samp{disabled}.
26004 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key
26005 Specifies the path to the file containing the private key for client TLS
26008 Defaults to @samp{disabled}.
26012 @deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize
26013 Set this to a number greater than 0 to request paged results from the
26014 LDAP server in accordance with RFC2696. The default (0) is to not
26015 request paged results.
26017 Defaults to @samp{disabled}.
26021 @deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers
26022 This option prevents group membership lookups through LDAP for the
26023 specified users. Alternatively, the value 'all-local may be used. With
26024 that value nslcd builds a full list of non-LDAP users on startup.
26026 Defaults to @samp{disabled}.
26030 @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid
26031 This option ensures that LDAP users with a numeric user id lower than
26032 the specified value are ignored.
26034 Defaults to @samp{disabled}.
26038 @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset
26039 This option specifies an offset that is added to all LDAP numeric user
26040 ids. This can be used to avoid user id collisions with local users.
26042 Defaults to @samp{disabled}.
26046 @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset
26047 This option specifies an offset that is added to all LDAP numeric group
26048 ids. This can be used to avoid user id collisions with local groups.
26050 Defaults to @samp{disabled}.
26054 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups
26055 If this option is set, the member attribute of a group may point to
26056 another group. Members of nested groups are also returned in the higher
26057 level group and parent groups are returned when finding groups for a
26058 specific user. The default is not to perform extra searches for nested
26061 Defaults to @samp{disabled}.
26065 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers
26066 If this option is set, the group member list is not retrieved when
26067 looking up groups. Lookups for finding which groups a user belongs to
26068 will remain functional so the user will likely still get the correct
26069 groups assigned on login.
26071 Defaults to @samp{disabled}.
26075 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration
26076 If this option is set, functions which cause all user/group entries to
26077 be loaded from the directory will not succeed in doing so. This can
26078 dramatically reduce LDAP server load in situations where there are a
26079 great number of users and/or groups. This option is not recommended for
26080 most configurations.
26082 Defaults to @samp{disabled}.
26086 @deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames
26087 This option can be used to specify how user and group names are verified
26088 within the system. This pattern is used to check all user and group
26089 names that are requested and returned from LDAP.
26091 Defaults to @samp{disabled}.
26095 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase
26096 This specifies whether or not to perform searches using case-insensitive
26097 matching. Enabling this could open up the system to authorization
26098 bypass vulnerabilities and introduce nscd cache poisoning
26099 vulnerabilities which allow denial of service.
26101 Defaults to @samp{disabled}.
26105 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy
26106 This option specifies whether password policy controls are requested and
26107 handled from the LDAP server when performing user authentication.
26109 Defaults to @samp{disabled}.
26113 @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search
26114 By default nslcd performs an LDAP search with the user's credentials
26115 after BIND (authentication) to ensure that the BIND operation was
26116 successful. The default search is a simple check to see if the user's
26117 DN exists. A search filter can be specified that will be used instead.
26118 It should return at least one entry.
26120 Defaults to @samp{disabled}.
26124 @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search
26125 This option allows flexible fine tuning of the authorisation check that
26126 should be performed. The search filter specified is executed and if any
26127 entries match, access is granted, otherwise access is denied.
26129 Defaults to @samp{disabled}.
26133 @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message
26134 If this option is set password modification using pam_ldap will be
26135 denied and the specified message will be presented to the user instead.
26136 The message can be used to direct the user to an alternative means of
26137 changing their password.
26139 Defaults to @samp{disabled}.
26143 @deftypevr {@code{nslcd-configuration} parameter} list pam-services
26144 List of pam service names for which LDAP authentication should suffice.
26146 Defaults to @samp{()}.
26150 @c %end of generated documentation for nslcd-configuration
26154 @subsection Web Services
26159 The @code{(gnu services web)} module provides the Apache HTTP Server,
26160 the nginx web server, and also a fastcgi wrapper daemon.
26162 @subsubheading Apache HTTP Server
26164 @deffn {Scheme Variable} httpd-service-type
26165 Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
26166 (@dfn{httpd}). The value for this service type is a
26167 @code{httpd-configuration} record.
26169 A simple example configuration is given below.
26172 (service httpd-service-type
26173 (httpd-configuration
26176 (server-name "www.example.com")
26177 (document-root "/srv/http/www.example.com")))))
26180 Other services can also extend the @code{httpd-service-type} to add to
26184 (simple-service 'www.example.com-server httpd-service-type
26188 (list (string-join '("ServerName www.example.com"
26189 "DocumentRoot /srv/http/www.example.com")
26194 The details for the @code{httpd-configuration}, @code{httpd-module},
26195 @code{httpd-config-file} and @code{httpd-virtualhost} record types are
26198 @deffn {Data Type} httpd-configuration
26199 This data type represents the configuration for the httpd service.
26202 @item @code{package} (default: @code{httpd})
26203 The httpd package to use.
26205 @item @code{pid-file} (default: @code{"/var/run/httpd"})
26206 The pid file used by the shepherd-service.
26208 @item @code{config} (default: @code{(httpd-config-file)})
26209 The configuration file to use with the httpd service. The default value
26210 is a @code{httpd-config-file} record, but this can also be a different
26211 G-expression that generates a file, for example a @code{plain-file}. A
26212 file outside of the store can also be specified through a string.
26217 @deffn {Data Type} httpd-module
26218 This data type represents a module for the httpd service.
26222 The name of the module.
26225 The file for the module. This can be relative to the httpd package being
26226 used, the absolute location of a file, or a G-expression for a file
26227 within the store, for example @code{(file-append mod-wsgi
26228 "/modules/mod_wsgi.so")}.
26233 @defvr {Scheme Variable} %default-httpd-modules
26234 A default list of @code{httpd-module} objects.
26237 @deffn {Data Type} httpd-config-file
26238 This data type represents a configuration file for the httpd service.
26241 @item @code{modules} (default: @code{%default-httpd-modules})
26242 The modules to load. Additional modules can be added here, or loaded by
26243 additional configuration.
26245 For example, in order to handle requests for PHP files, you can use Apache’s
26246 @code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}:
26249 (service httpd-service-type
26250 (httpd-configuration
26255 (name "proxy_module")
26256 (file "modules/mod_proxy.so"))
26258 (name "proxy_fcgi_module")
26259 (file "modules/mod_proxy_fcgi.so"))
26260 %default-httpd-modules))
26261 (extra-config (list "\
26262 <FilesMatch \\.php$>
26263 SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
26264 </FilesMatch>"))))))
26265 (service php-fpm-service-type
26266 (php-fpm-configuration
26267 (socket "/var/run/php-fpm.sock")
26268 (socket-group "httpd")))
26271 @item @code{server-root} (default: @code{httpd})
26272 The @code{ServerRoot} in the configuration file, defaults to the httpd
26273 package. Directives including @code{Include} and @code{LoadModule} are
26274 taken as relative to the server root.
26276 @item @code{server-name} (default: @code{#f})
26277 The @code{ServerName} in the configuration file, used to specify the
26278 request scheme, hostname and port that the server uses to identify
26281 This doesn't need to be set in the server config, and can be specified
26282 in virtual hosts. The default is @code{#f} to not specify a
26285 @item @code{document-root} (default: @code{"/srv/http"})
26286 The @code{DocumentRoot} from which files will be served.
26288 @item @code{listen} (default: @code{'("80")})
26289 The list of values for the @code{Listen} directives in the config
26290 file. The value should be a list of strings, when each string can
26291 specify the port number to listen on, and optionally the IP address and
26294 @item @code{pid-file} (default: @code{"/var/run/httpd"})
26295 The @code{PidFile} to use. This should match the @code{pid-file} set in
26296 the @code{httpd-configuration} so that the Shepherd service is
26297 configured correctly.
26299 @item @code{error-log} (default: @code{"/var/log/httpd/error_log"})
26300 The @code{ErrorLog} to which the server will log errors.
26302 @item @code{user} (default: @code{"httpd"})
26303 The @code{User} which the server will answer requests as.
26305 @item @code{group} (default: @code{"httpd"})
26306 The @code{Group} which the server will answer requests as.
26308 @item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")})
26309 A flat list of strings and G-expressions which will be added to the end
26310 of the configuration file.
26312 Any values which the service is extended with will be appended to this
26318 @deffn {Data Type} httpd-virtualhost
26319 This data type represents a virtualhost configuration block for the httpd service.
26321 These should be added to the extra-config for the httpd-service.
26324 (simple-service 'www.example.com-server httpd-service-type
26328 (list (string-join '("ServerName www.example.com"
26329 "DocumentRoot /srv/http/www.example.com")
26334 @item @code{addresses-and-ports}
26335 The addresses and ports for the @code{VirtualHost} directive.
26337 @item @code{contents}
26338 The contents of the @code{VirtualHost} directive, this should be a list
26339 of strings and G-expressions.
26345 @subsubheading NGINX
26347 @deffn {Scheme Variable} nginx-service-type
26348 Service type for the @uref{https://nginx.org/,NGinx} web server. The
26349 value for this service type is a @code{<nginx-configuration>} record.
26351 A simple example configuration is given below.
26354 (service nginx-service-type
26355 (nginx-configuration
26357 (list (nginx-server-configuration
26358 (server-name '("www.example.com"))
26359 (root "/srv/http/www.example.com"))))))
26362 In addition to adding server blocks to the service configuration
26363 directly, this service can be extended by other services to add server
26364 blocks, as in this example:
26367 (simple-service 'my-extra-server nginx-service-type
26368 (list (nginx-server-configuration
26369 (root "/srv/http/extra-website")
26370 (try-files (list "$uri" "$uri/index.html")))))
26374 At startup, @command{nginx} has not yet read its configuration file, so
26375 it uses a default file to log error messages. If it fails to load its
26376 configuration file, that is where error messages are logged. After the
26377 configuration file is loaded, the default error log file changes as per
26378 configuration. In our case, startup error messages can be found in
26379 @file{/var/run/nginx/logs/error.log}, and after configuration in
26380 @file{/var/log/nginx/error.log}. The second location can be changed
26381 with the @var{log-directory} configuration option.
26383 @deffn {Data Type} nginx-configuration
26384 This data type represents the configuration for NGinx. Some
26385 configuration can be done through this and the other provided record
26386 types, or alternatively, a config file can be provided.
26389 @item @code{nginx} (default: @code{nginx})
26390 The nginx package to use.
26392 @item @code{log-directory} (default: @code{"/var/log/nginx"})
26393 The directory to which NGinx will write log files.
26395 @item @code{run-directory} (default: @code{"/var/run/nginx"})
26396 The directory in which NGinx will create a pid file, and write temporary
26399 @item @code{server-blocks} (default: @code{'()})
26400 A list of @dfn{server blocks} to create in the generated configuration
26401 file, the elements should be of type
26402 @code{<nginx-server-configuration>}.
26404 The following example would setup NGinx to serve @code{www.example.com}
26405 from the @code{/srv/http/www.example.com} directory, without using
26408 (service nginx-service-type
26409 (nginx-configuration
26411 (list (nginx-server-configuration
26412 (server-name '("www.example.com"))
26413 (root "/srv/http/www.example.com"))))))
26416 @item @code{upstream-blocks} (default: @code{'()})
26417 A list of @dfn{upstream blocks} to create in the generated configuration
26418 file, the elements should be of type
26419 @code{<nginx-upstream-configuration>}.
26421 Configuring upstreams through the @code{upstream-blocks} can be useful
26422 when combined with @code{locations} in the
26423 @code{<nginx-server-configuration>} records. The following example
26424 creates a server configuration with one location configuration, that
26425 will proxy requests to a upstream configuration, which will handle
26426 requests with two servers.
26431 (nginx-configuration
26433 (list (nginx-server-configuration
26434 (server-name '("www.example.com"))
26435 (root "/srv/http/www.example.com")
26438 (nginx-location-configuration
26440 (body '("proxy_pass http://server-proxy;"))))))))
26442 (list (nginx-upstream-configuration
26443 (name "server-proxy")
26444 (servers (list "server1.example.com"
26445 "server2.example.com")))))))
26448 @item @code{file} (default: @code{#f})
26449 If a configuration @var{file} is provided, this will be used, rather than
26450 generating a configuration file from the provided @code{log-directory},
26451 @code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For
26452 proper operation, these arguments should match what is in @var{file} to ensure
26453 that the directories are created when the service is activated.
26455 This can be useful if you have an existing configuration file, or it's
26456 not possible to do what is required through the other parts of the
26457 nginx-configuration record.
26459 @item @code{server-names-hash-bucket-size} (default: @code{#f})
26460 Bucket size for the server names hash tables, defaults to @code{#f} to
26461 use the size of the processors cache line.
26463 @item @code{server-names-hash-bucket-max-size} (default: @code{#f})
26464 Maximum bucket size for the server names hash tables.
26466 @item @code{modules} (default: @code{'()})
26467 List of nginx dynamic modules to load. This should be a list of file
26468 names of loadable modules, as in this example:
26473 (file-append nginx-accept-language-module "\
26474 /etc/nginx/modules/ngx_http_accept_language_module.so")
26475 (file-append nginx-lua-module "\
26476 /etc/nginx/modules/ngx_http_lua_module.so")))
26479 @item @code{lua-package-path} (default: @code{'()})
26480 List of nginx lua packages to load. This should be a list of package
26481 names of loadable lua modules, as in this example:
26484 (lua-package-path (list lua-resty-core
26491 @item @code{lua-package-cpath} (default: @code{'()})
26492 List of nginx lua C packages to load. This should be a list of package
26493 names of loadable lua C modules, as in this example:
26496 (lua-package-cpath (list lua-resty-signal))
26499 @item @code{global-directives} (default: @code{'((events . ()))})
26500 Association list of global directives for the top level of the nginx
26501 configuration. Values may themselves be association lists.
26505 `((worker_processes . 16)
26507 (events . ((worker_connections . 1024)))))
26510 @item @code{extra-content} (default: @code{""})
26511 Extra content for the @code{http} block. Should be string or a string
26512 valued G-expression.
26517 @deftp {Data Type} nginx-server-configuration
26518 Data type representing the configuration of an nginx server block.
26519 This type has the following parameters:
26522 @item @code{listen} (default: @code{'("80" "443 ssl")})
26523 Each @code{listen} directive sets the address and port for IP, or the
26524 path for a UNIX-domain socket on which the server will accept requests.
26525 Both address and port, or only address or only port can be specified.
26526 An address may also be a hostname, for example:
26529 '("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")
26532 @item @code{server-name} (default: @code{(list 'default)})
26533 A list of server names this server represents. @code{'default} represents the
26534 default server for connections matching no other server.
26536 @item @code{root} (default: @code{"/srv/http"})
26537 Root of the website nginx will serve.
26539 @item @code{locations} (default: @code{'()})
26540 A list of @dfn{nginx-location-configuration} or
26541 @dfn{nginx-named-location-configuration} records to use within this
26544 @item @code{index} (default: @code{(list "index.html")})
26545 Index files to look for when clients ask for a directory. If it cannot be found,
26546 Nginx will send the list of files in the directory.
26548 @item @code{try-files} (default: @code{'()})
26549 A list of files whose existence is checked in the specified order.
26550 @code{nginx} will use the first file it finds to process the request.
26552 @item @code{ssl-certificate} (default: @code{#f})
26553 Where to find the certificate for secure connections. Set it to @code{#f} if
26554 you don't have a certificate or you don't want to use HTTPS.
26556 @item @code{ssl-certificate-key} (default: @code{#f})
26557 Where to find the private key for secure connections. Set it to @code{#f} if
26558 you don't have a key or you don't want to use HTTPS.
26560 @item @code{server-tokens?} (default: @code{#f})
26561 Whether the server should add its configuration to response.
26563 @item @code{raw-content} (default: @code{'()})
26564 A list of raw lines added to the server block.
26569 @deftp {Data Type} nginx-upstream-configuration
26570 Data type representing the configuration of an nginx @code{upstream}
26571 block. This type has the following parameters:
26575 Name for this group of servers.
26577 @item @code{servers}
26578 Specify the addresses of the servers in the group. The address can be
26579 specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name
26580 (e.g.@: @samp{backend1.example.com}) or a path to a UNIX socket using the
26581 prefix @samp{unix:}. For addresses using an IP address or domain name,
26582 the default port is 80, and a different port can be specified
26588 @deftp {Data Type} nginx-location-configuration
26589 Data type representing the configuration of an nginx @code{location}
26590 block. This type has the following parameters:
26594 URI which this location block matches.
26596 @anchor{nginx-location-configuration body}
26598 Body of the location block, specified as a list of strings. This can contain
26600 configuration directives. For example, to pass requests to a upstream
26601 server group defined using an @code{nginx-upstream-configuration} block,
26602 the following directive would be specified in the body @samp{(list "proxy_pass
26603 http://upstream-name;")}.
26608 @deftp {Data Type} nginx-named-location-configuration
26609 Data type representing the configuration of an nginx named location
26610 block. Named location blocks are used for request redirection, and not
26611 used for regular request processing. This type has the following
26616 Name to identify this location block.
26619 @xref{nginx-location-configuration body}, as the body for named location
26620 blocks can be used in a similar way to the
26621 @code{nginx-location-configuration body}. One restriction is that the
26622 body of a named location block cannot contain location blocks.
26627 @subsubheading Varnish Cache
26629 Varnish is a fast cache server that sits in between web applications
26630 and end users. It proxies requests from clients and caches the
26631 accessed URLs such that multiple requests for the same resource only
26632 creates one request to the back-end.
26634 @defvr {Scheme Variable} varnish-service-type
26635 Service type for the Varnish daemon.
26638 @deftp {Data Type} varnish-configuration
26639 Data type representing the @code{varnish} service configuration.
26640 This type has the following parameters:
26643 @item @code{package} (default: @code{varnish})
26644 The Varnish package to use.
26646 @item @code{name} (default: @code{"default"})
26647 A name for this Varnish instance. Varnish will create a directory in
26648 @file{/var/varnish/} with this name and keep temporary files there. If
26649 the name starts with a forward slash, it is interpreted as an absolute
26652 Pass the @code{-n} argument to other Varnish programs to connect to the
26653 named instance, e.g.@: @command{varnishncsa -n default}.
26655 @item @code{backend} (default: @code{"localhost:8080"})
26656 The backend to use. This option has no effect if @code{vcl} is set.
26658 @item @code{vcl} (default: #f)
26659 The @dfn{VCL} (Varnish Configuration Language) program to run. If this
26660 is @code{#f}, Varnish will proxy @code{backend} using the default
26661 configuration. Otherwise this must be a file-like object with valid
26664 @c Varnish does not support HTTPS, so keep this URL to avoid confusion.
26665 For example, to mirror @url{https://www.gnu.org,www.gnu.org} with VCL you
26666 can do something along these lines:
26669 (define %gnu-mirror
26670 (plain-file "gnu.vcl"
26672 backend gnu @{ .host = \"www.gnu.org\"; @}"))
26676 (services (cons (service varnish-service-type
26677 (varnish-configuration
26679 (vcl %gnu-mirror)))
26683 The configuration of an already running Varnish instance can be inspected
26684 and changed using the @command{varnishadm} program.
26686 Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and
26687 @url{https://book.varnish-software.com/4.0/,Varnish Book} for
26688 comprehensive documentation on Varnish and its configuration language.
26690 @item @code{listen} (default: @code{'("localhost:80")})
26691 List of addresses Varnish will listen on.
26693 @item @code{storage} (default: @code{'("malloc,128m")})
26694 List of storage backends that will be available in VCL.
26696 @item @code{parameters} (default: @code{'()})
26697 List of run-time parameters in the form @code{'(("parameter" . "value"))}.
26699 @item @code{extra-options} (default: @code{'()})
26700 Additional arguments to pass to the @command{varnishd} process.
26705 @subsubheading Patchwork
26707 Patchwork is a patch tracking system. It can collect patches sent to a
26708 mailing list, and display them in a web interface.
26710 @defvr {Scheme Variable} patchwork-service-type
26711 Service type for Patchwork.
26714 The following example is an example of a minimal service for Patchwork, for
26715 the @code{patchwork.example.com} domain.
26718 (service patchwork-service-type
26719 (patchwork-configuration
26720 (domain "patchwork.example.com")
26722 (patchwork-settings-module
26723 (allowed-hosts (list domain))
26724 (default-from-email "patchwork@@patchwork.example.com")))
26725 (getmail-retriever-config
26726 (getmail-retriever-configuration
26727 (type "SimpleIMAPSSLRetriever")
26728 (server "imap.example.com")
26730 (username "patchwork")
26732 (list (file-append coreutils "/bin/cat")
26733 "/etc/getmail-patchwork-imap-password"))
26735 '((mailboxes . ("Patches"))))))))
26739 There are three records for configuring the Patchwork service. The
26740 @code{<patchwork-configuration>} relates to the configuration for Patchwork
26741 within the HTTPD service.
26743 The @code{settings-module} field within the @code{<patchwork-configuration>}
26744 record can be populated with the @code{<patchwork-settings-module>} record,
26745 which describes a settings module that is generated within the Guix store.
26747 For the @code{database-configuration} field within the
26748 @code{<patchwork-settings-module>}, the
26749 @code{<patchwork-database-configuration>} must be used.
26751 @deftp {Data Type} patchwork-configuration
26752 Data type representing the Patchwork service configuration. This type has the
26753 following parameters:
26756 @item @code{patchwork} (default: @code{patchwork})
26757 The Patchwork package to use.
26759 @item @code{domain}
26760 The domain to use for Patchwork, this is used in the HTTPD service virtual
26763 @item @code{settings-module}
26764 The settings module to use for Patchwork. As a Django application, Patchwork
26765 is configured with a Python module containing the settings. This can either be
26766 an instance of the @code{<patchwork-settings-module>} record, any other record
26767 that represents the settings in the store, or a directory outside of the
26770 @item @code{static-path} (default: @code{"/static/"})
26771 The path under which the HTTPD service should serve the static files.
26773 @item @code{getmail-retriever-config}
26774 The getmail-retriever-configuration record value to use with
26775 Patchwork. Getmail will be configured with this value, the messages will be
26776 delivered to Patchwork.
26781 @deftp {Data Type} patchwork-settings-module
26782 Data type representing a settings module for Patchwork. Some of these
26783 settings relate directly to Patchwork, but others relate to Django, the web
26784 framework used by Patchwork, or the Django Rest Framework library. This type
26785 has the following parameters:
26788 @item @code{database-configuration} (default: @code{(patchwork-database-configuration)})
26789 The database connection settings used for Patchwork. See the
26790 @code{<patchwork-database-configuration>} record type for more information.
26792 @item @code{secret-key-file} (default: @code{"/etc/patchwork/django-secret-key"})
26793 Patchwork, as a Django web application uses a secret key for cryptographically
26794 signing values. This file should contain a unique unpredictable value.
26796 If this file does not exist, it will be created and populated with a random
26797 value by the patchwork-setup shepherd service.
26799 This setting relates to Django.
26801 @item @code{allowed-hosts}
26802 A list of valid hosts for this Patchwork service. This should at least include
26803 the domain specified in the @code{<patchwork-configuration>} record.
26805 This is a Django setting.
26807 @item @code{default-from-email}
26808 The email address from which Patchwork should send email by default.
26810 This is a Patchwork setting.
26812 @item @code{static-url} (default: @code{#f})
26813 The URL to use when serving static assets. It can be part of a URL, or a full
26814 URL, but must end in a @code{/}.
26816 If the default value is used, the @code{static-path} value from the
26817 @code{<patchwork-configuration>} record will be used.
26819 This is a Django setting.
26821 @item @code{admins} (default: @code{'()})
26822 Email addresses to send the details of errors that occur. Each value should
26823 be a list containing two elements, the name and then the email address.
26825 This is a Django setting.
26827 @item @code{debug?} (default: @code{#f})
26828 Whether to run Patchwork in debug mode. If set to @code{#t}, detailed error
26829 messages will be shown.
26831 This is a Django setting.
26833 @item @code{enable-rest-api?} (default: @code{#t})
26834 Whether to enable the Patchwork REST API.
26836 This is a Patchwork setting.
26838 @item @code{enable-xmlrpc?} (default: @code{#t})
26839 Whether to enable the XML RPC API.
26841 This is a Patchwork setting.
26843 @item @code{force-https-links?} (default: @code{#t})
26844 Whether to use HTTPS links on Patchwork pages.
26846 This is a Patchwork setting.
26848 @item @code{extra-settings} (default: @code{""})
26849 Extra code to place at the end of the Patchwork settings module.
26854 @deftp {Data Type} patchwork-database-configuration
26855 Data type representing the database configuration for Patchwork.
26858 @item @code{engine} (default: @code{"django.db.backends.postgresql_psycopg2"})
26859 The database engine to use.
26861 @item @code{name} (default: @code{"patchwork"})
26862 The name of the database to use.
26864 @item @code{user} (default: @code{"httpd"})
26865 The user to connect to the database as.
26867 @item @code{password} (default: @code{""})
26868 The password to use when connecting to the database.
26870 @item @code{host} (default: @code{""})
26871 The host to make the database connection to.
26873 @item @code{port} (default: @code{""})
26874 The port on which to connect to the database.
26879 @subsubheading Mumi
26881 @cindex Mumi, Debbugs Web interface
26882 @cindex Debbugs, Mumi Web interface
26883 @uref{https://git.elephly.net/gitweb.cgi?p=software/mumi.git, Mumi} is a
26884 Web interface to the Debbugs bug tracker, by default for
26885 @uref{https://bugs.gnu.org, the GNU instance}. Mumi is a Web server,
26886 but it also fetches and indexes mail retrieved from Debbugs.
26888 @defvr {Scheme Variable} mumi-service-type
26889 This is the service type for Mumi.
26892 @deftp {Data Type} mumi-configuration
26893 Data type representing the Mumi service configuration. This type has the
26897 @item @code{mumi} (default: @code{mumi})
26898 The Mumi package to use.
26900 @item @code{mailer?} (default: @code{#true})
26901 Whether to enable or disable the mailer component.
26903 @item @code{mumi-configuration-sender}
26904 The email address used as the sender for comments.
26906 @item @code{mumi-configuration-smtp}
26907 A URI to configure the SMTP settings for Mailutils. This could be
26908 something like @code{sendmail:///path/to/bin/msmtp} or any other URI
26909 supported by Mailutils. @xref{SMTP Mailboxes, SMTP Mailboxes,,
26910 mailutils, GNU@tie{}Mailutils}.
26916 @subsubheading FastCGI
26919 FastCGI is an interface between the front-end and the back-end of a web
26920 service. It is a somewhat legacy facility; new web services should
26921 generally just talk HTTP between the front-end and the back-end.
26922 However there are a number of back-end services such as PHP or the
26923 optimized HTTP Git repository access that use FastCGI, so we have
26924 support for it in Guix.
26926 To use FastCGI, you configure the front-end web server (e.g., nginx) to
26927 dispatch some subset of its requests to the fastcgi backend, which
26928 listens on a local TCP or UNIX socket. There is an intermediary
26929 @code{fcgiwrap} program that sits between the actual backend process and
26930 the web server. The front-end indicates which backend program to run,
26931 passing that information to the @code{fcgiwrap} process.
26933 @defvr {Scheme Variable} fcgiwrap-service-type
26934 A service type for the @code{fcgiwrap} FastCGI proxy.
26937 @deftp {Data Type} fcgiwrap-configuration
26938 Data type representing the configuration of the @code{fcgiwrap} service.
26939 This type has the following parameters:
26941 @item @code{package} (default: @code{fcgiwrap})
26942 The fcgiwrap package to use.
26944 @item @code{socket} (default: @code{tcp:127.0.0.1:9000})
26945 The socket on which the @code{fcgiwrap} process should listen, as a
26946 string. Valid @var{socket} values include
26947 @code{unix:@var{/path/to/unix/socket}},
26948 @code{tcp:@var{dot.ted.qu.ad}:@var{port}} and
26949 @code{tcp6:[@var{ipv6_addr}]:port}.
26951 @item @code{user} (default: @code{fcgiwrap})
26952 @itemx @code{group} (default: @code{fcgiwrap})
26953 The user and group names, as strings, under which to run the
26954 @code{fcgiwrap} process. The @code{fastcgi} service will ensure that if
26955 the user asks for the specific user or group names @code{fcgiwrap} that
26956 the corresponding user and/or group is present on the system.
26958 It is possible to configure a FastCGI-backed web service to pass HTTP
26959 authentication information from the front-end to the back-end, and to
26960 allow @code{fcgiwrap} to run the back-end process as a corresponding
26961 local user. To enable this capability on the back-end, run
26962 @code{fcgiwrap} as the @code{root} user and group. Note that this
26963 capability also has to be configured on the front-end as well.
26968 PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation
26969 with some additional features useful for sites of any size.
26971 These features include:
26973 @item Adaptive process spawning
26974 @item Basic statistics (similar to Apache's mod_status)
26975 @item Advanced process management with graceful stop/start
26976 @item Ability to start workers with different uid/gid/chroot/environment
26977 and different php.ini (replaces safe_mode)
26978 @item Stdout & stderr logging
26979 @item Emergency restart in case of accidental opcode cache destruction
26980 @item Accelerated upload support
26981 @item Support for a "slowlog"
26982 @item Enhancements to FastCGI, such as fastcgi_finish_request() -
26983 a special function to finish request & flush all data while continuing to do
26984 something time-consuming (video converting, stats processing, etc.)
26986 ...@: and much more.
26988 @defvr {Scheme Variable} php-fpm-service-type
26989 A Service type for @code{php-fpm}.
26992 @deftp {Data Type} php-fpm-configuration
26993 Data Type for php-fpm service configuration.
26995 @item @code{php} (default: @code{php})
26996 The php package to use.
26997 @item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")})
26998 The address on which to accept FastCGI requests. Valid syntaxes are:
27000 @item @code{"ip.add.re.ss:port"}
27001 Listen on a TCP socket to a specific address on a specific port.
27002 @item @code{"port"}
27003 Listen on a TCP socket to all addresses on a specific port.
27004 @item @code{"/path/to/unix/socket"}
27005 Listen on a unix socket.
27008 @item @code{user} (default: @code{php-fpm})
27009 User who will own the php worker processes.
27010 @item @code{group} (default: @code{php-fpm})
27011 Group of the worker processes.
27012 @item @code{socket-user} (default: @code{php-fpm})
27013 User who can speak to the php-fpm socket.
27014 @item @code{socket-group} (default: @code{nginx})
27015 Group that can speak to the php-fpm socket.
27016 @item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
27017 The process id of the php-fpm process is written to this file
27018 once the service has started.
27019 @item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")})
27020 Log for the php-fpm master process.
27021 @item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
27022 Detailed settings for the php-fpm process manager.
27025 @item @code{<php-fpm-dynamic-process-manager-configuration>}
27026 @item @code{<php-fpm-static-process-manager-configuration>}
27027 @item @code{<php-fpm-on-demand-process-manager-configuration>}
27029 @item @code{display-errors} (default @code{#f})
27030 Determines whether php errors and warning should be sent to clients
27031 and displayed in their browsers.
27032 This is useful for local php development, but a security risk for public sites,
27033 as error messages can reveal passwords and personal data.
27034 @item @code{timezone} (default @code{#f})
27035 Specifies @code{php_admin_value[date.timezone]} parameter.
27036 @item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")})
27037 This file will log the @code{stderr} outputs of php worker processes.
27038 Can be set to @code{#f} to disable logging.
27039 @item @code{file} (default @code{#f})
27040 An optional override of the whole configuration.
27041 You can use the @code{mixed-text-file} function or an absolute filepath for it.
27042 @item @code{php-ini-file} (default @code{#f})
27043 An optional override of the default php settings.
27044 It may be any ``file-like'' object (@pxref{G-Expressions, file-like objects}).
27045 You can use the @code{mixed-text-file} function or an absolute filepath for it.
27047 For local development it is useful to set a higher timeout and memory
27048 limit for spawned php processes. This be accomplished with the
27049 following operating system configuration snippet:
27051 (define %local-php-ini
27052 (plain-file "php.ini"
27054 max_execution_time = 1800"))
27058 (services (cons (service php-fpm-service-type
27059 (php-fpm-configuration
27060 (php-ini-file %local-php-ini)))
27064 Consult the @url{https://www.php.net/manual/en/ini.core.php,core php.ini
27065 directives} for comprehensive documentation on the acceptable
27066 @file{php.ini} directives.
27070 @deftp {Data type} php-fpm-dynamic-process-manager-configuration
27071 Data Type for the @code{dynamic} php-fpm process manager. With the
27072 @code{dynamic} process manager, spare worker processes are kept around
27073 based on its configured limits.
27075 @item @code{max-children} (default: @code{5})
27076 Maximum of worker processes.
27077 @item @code{start-servers} (default: @code{2})
27078 How many worker processes should be started on start-up.
27079 @item @code{min-spare-servers} (default: @code{1})
27080 How many spare worker processes should be kept around at minimum.
27081 @item @code{max-spare-servers} (default: @code{3})
27082 How many spare worker processes should be kept around at maximum.
27086 @deftp {Data type} php-fpm-static-process-manager-configuration
27087 Data Type for the @code{static} php-fpm process manager. With the
27088 @code{static} process manager, an unchanging number of worker processes
27091 @item @code{max-children} (default: @code{5})
27092 Maximum of worker processes.
27096 @deftp {Data type} php-fpm-on-demand-process-manager-configuration
27097 Data Type for the @code{on-demand} php-fpm process manager. With the
27098 @code{on-demand} process manager, worker processes are only created as
27101 @item @code{max-children} (default: @code{5})
27102 Maximum of worker processes.
27103 @item @code{process-idle-timeout} (default: @code{10})
27104 The time in seconds after which a process with no requests is killed.
27109 @deffn {Scheme Procedure} nginx-php-location @
27110 [#:nginx-package nginx] @
27111 [socket (string-append "/var/run/php" @
27112 (version-major (package-version php)) @
27114 A helper function to quickly add php to an @code{nginx-server-configuration}.
27117 A simple services setup for nginx with php can look like this:
27119 (services (cons* (service dhcp-client-service-type)
27120 (service php-fpm-service-type)
27121 (service nginx-service-type
27122 (nginx-server-configuration
27123 (server-name '("example.com"))
27124 (root "/srv/http/")
27126 (list (nginx-php-location)))
27128 (ssl-certificate #f)
27129 (ssl-certificate-key #f)))
27133 @cindex cat-avatar-generator
27134 The cat avatar generator is a simple service to demonstrate the use of php-fpm
27135 in @code{Nginx}. It is used to generate cat avatar from a seed, for instance
27136 the hash of a user's email address.
27138 @deffn {Scheme Procedure} cat-avatar-generator-service @
27139 [#:cache-dir "/var/cache/cat-avatar-generator"] @
27140 [#:package cat-avatar-generator] @
27141 [#:configuration (nginx-server-configuration)]
27142 Returns an nginx-server-configuration that inherits @code{configuration}. It
27143 extends the nginx configuration to add a server block that serves @code{package},
27144 a version of cat-avatar-generator. During execution, cat-avatar-generator will
27145 be able to use @code{cache-dir} as its cache directory.
27148 A simple setup for cat-avatar-generator can look like this:
27150 (services (cons* (cat-avatar-generator-service
27152 (nginx-server-configuration
27153 (server-name '("example.com"))))
27158 @subsubheading Hpcguix-web
27160 @cindex hpcguix-web
27161 The @uref{https://github.com/UMCUGenetics/hpcguix-web/, hpcguix-web}
27162 program is a customizable web interface to browse Guix packages,
27163 initially designed for users of high-performance computing (HPC)
27166 @defvr {Scheme Variable} hpcguix-web-service-type
27167 The service type for @code{hpcguix-web}.
27170 @deftp {Data Type} hpcguix-web-configuration
27171 Data type for the hpcguix-web service configuration.
27175 A gexp (@pxref{G-Expressions}) specifying the hpcguix-web service
27176 configuration. The main items available in this spec are:
27179 @item @code{title-prefix} (default: @code{"hpcguix | "})
27180 The page title prefix.
27182 @item @code{guix-command} (default: @code{"guix"})
27183 The @command{guix} command.
27185 @item @code{package-filter-proc} (default: @code{(const #t)})
27186 A procedure specifying how to filter packages that are displayed.
27188 @item @code{package-page-extension-proc} (default: @code{(const '())})
27189 Extension package for @code{hpcguix-web}.
27191 @item @code{menu} (default: @code{'()})
27192 Additional entry in page @code{menu}.
27194 @item @code{channels} (default: @code{%default-channels})
27195 List of channels from which the package list is built (@pxref{Channels}).
27197 @item @code{package-list-expiration} (default: @code{(* 12 3600)})
27198 The expiration time, in seconds, after which the package list is rebuilt from
27199 the latest instances of the given channels.
27202 See the hpcguix-web repository for a
27203 @uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
27206 @item @code{package} (default: @code{hpcguix-web})
27207 The hpcguix-web package to use.
27209 @item @code{address} (default: @code{"127.0.0.1"})
27210 The IP address to listen to.
27212 @item @code{port} (default: @code{5000})
27213 The port number to listen to.
27217 A typical hpcguix-web service declaration looks like this:
27220 (service hpcguix-web-service-type
27221 (hpcguix-web-configuration
27223 #~(define site-config
27224 (hpcweb-configuration
27225 (title-prefix "Guix-HPC - ")
27226 (menu '(("/about" "ABOUT"))))))))
27230 The hpcguix-web service periodically updates the package list it publishes by
27231 pulling channels from Git. To that end, it needs to access X.509 certificates
27232 so that it can authenticate Git servers when communicating over HTTPS, and it
27233 assumes that @file{/etc/ssl/certs} contains those certificates.
27235 Thus, make sure to add @code{nss-certs} or another certificate package to the
27236 @code{packages} field of your configuration. @ref{X.509 Certificates}, for
27237 more information on X.509 certificates.
27240 @subsubheading gmnisrv
27243 The @uref{https://git.sr.ht/~sircmpwn/gmnisrv, gmnisrv} program is a
27244 simple @uref{https://gemini.circumlunar.space/, Gemini} protocol server.
27246 @deffn {Scheme Variable} gmnisrv-service-type
27247 This is the type of the gmnisrv service, whose value should be a
27248 @code{gmnisrv-configuration} object, as in this example:
27251 (service gmnisrv-service-type
27252 (gmnisrv-configuration
27253 (config-file (local-file "./my-gmnisrv.ini"))))
27257 @deftp {Data Type} gmnisrv-configuration
27258 Data type representing the configuration of gmnisrv.
27261 @item @code{package} (default: @var{gmnisrv})
27262 Package object of the gmnisrv server.
27264 @item @code{config-file} (default: @code{%default-gmnisrv-config-file})
27265 File-like object of the gmnisrv configuration file to use. The default
27266 configuration listens on port 1965 and serves files from
27267 @file{/srv/gemini}. Certificates are stored in
27268 @file{/var/lib/gemini/certs}. For more information, run @command{man
27269 gmnisrv} and @command{man gmnisrv.ini}.
27274 @subsubheading Agate
27277 The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate}
27278 (@uref{https://github.com/mbrubeck/agate, GitHub page over HTTPS})
27279 program is a simple @uref{https://gemini.circumlunar.space/, Gemini}
27280 protocol server written in Rust.
27282 @deffn {Scheme Variable} agate-service-type
27283 This is the type of the agate service, whose value should be an
27284 @code{agate-service-type} object, as in this example:
27287 (service agate-service-type
27288 (agate-configuration
27289 (content "/srv/gemini")
27290 (cert "/srv/cert.pem")
27291 (key "/srv/key.rsa")))
27294 The example above represents the minimal tweaking necessary to get Agate
27295 up and running. Specifying the path to the certificate and key is
27296 always necessary, as the Gemini protocol requires TLS by default.
27298 To obtain a certificate and a key, you could, for example, use OpenSSL,
27299 running a command similar to the following example:
27302 openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
27303 -days 3650 -nodes -subj "/CN=example.com"
27306 Of course, you'll have to replace @i{example.com} with your own domain
27307 name, and then point the Agate configuration towards the path of the
27308 generated key and certificate.
27312 @deftp {Data Type} agate-configuration
27313 Data type representing the configuration of Agate.
27316 @item @code{package} (default: @code{agate})
27317 The package object of the Agate server.
27319 @item @code{content} (default: @file{"/srv/gemini"})
27320 The directory from which Agate will serve files.
27322 @item @code{cert} (default: @code{#f})
27323 The path to the TLS certificate PEM file to be used for encrypted
27324 connections. Must be filled in with a value from the user.
27326 @item @code{key} (default: @code{#f})
27327 The path to the PKCS8 private key file to be used for encrypted
27328 connections. Must be filled in with a value from the user.
27330 @item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")})
27331 A list of the addresses to listen on.
27333 @item @code{hostname} (default: @code{#f})
27334 The domain name of this Gemini server. Optional.
27336 @item @code{lang} (default: @code{#f})
27337 RFC 4646 language code(s) for text/gemini documents. Optional.
27339 @item @code{silent?} (default: @code{#f})
27340 Set to @code{#t} to disable logging output.
27342 @item @code{serve-secret?} (default: @code{#f})
27343 Set to @code{#t} to serve secret files (files/directories starting with
27346 @item @code{log-ip?} (default: @code{#t})
27347 Whether or not to output IP addresses when logging.
27349 @item @code{user} (default: @code{"agate"})
27350 Owner of the @code{agate} process.
27352 @item @code{group} (default: @code{"agate"})
27353 Owner's group of the @code{agate} process.
27355 @item @code{log-file} (default: @file{"/var/log/agate.log"})
27356 The file which should store the logging output of Agate.
27361 @node Certificate Services
27362 @subsection Certificate Services
27365 @cindex HTTP, HTTPS
27366 @cindex Let's Encrypt
27367 @cindex TLS certificates
27368 The @code{(gnu services certbot)} module provides a service to
27369 automatically obtain a valid TLS certificate from the Let's Encrypt
27370 certificate authority. These certificates can then be used to serve
27371 content securely over HTTPS or other TLS-based protocols, with the
27372 knowledge that the client will be able to verify the server's
27375 @url{https://letsencrypt.org/, Let's Encrypt} provides the
27376 @code{certbot} tool to automate the certification process. This tool
27377 first securely generates a key on the server. It then makes a request
27378 to the Let's Encrypt certificate authority (CA) to sign the key. The CA
27379 checks that the request originates from the host in question by using a
27380 challenge-response protocol, requiring the server to provide its
27381 response over HTTP@. If that protocol completes successfully, the CA
27382 signs the key, resulting in a certificate. That certificate is valid
27383 for a limited period of time, and therefore to continue to provide TLS
27384 services, the server needs to periodically ask the CA to renew its
27387 The certbot service automates this process: the initial key
27388 generation, the initial certification request to the Let's Encrypt
27389 service, the web server challenge/response integration, writing the
27390 certificate to disk, the automated periodic renewals, and the deployment
27391 tasks associated with the renewal (e.g.@: reloading services, copying keys
27392 with different permissions).
27394 Certbot is run twice a day, at a random minute within the hour. It
27395 won't do anything until your certificates are due for renewal or
27396 revoked, but running it regularly would give your service a chance of
27397 staying online in case a Let's Encrypt-initiated revocation happened for
27400 By using this service, you agree to the ACME Subscriber Agreement, which
27401 can be found there:
27402 @url{https://acme-v01.api.letsencrypt.org/directory}.
27404 @defvr {Scheme Variable} certbot-service-type
27405 A service type for the @code{certbot} Let's Encrypt client. Its value
27406 must be a @code{certbot-configuration} record as in this example:
27409 (define %nginx-deploy-hook
27411 "nginx-deploy-hook"
27412 #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read)))
27413 (kill pid SIGHUP))))
27415 (service certbot-service-type
27416 (certbot-configuration
27417 (email "foo@@example.net")
27420 (certificate-configuration
27421 (domains '("example.net" "www.example.net"))
27422 (deploy-hook %nginx-deploy-hook))
27423 (certificate-configuration
27424 (domains '("bar.example.net")))))))
27427 See below for details about @code{certbot-configuration}.
27430 @deftp {Data Type} certbot-configuration
27431 Data type representing the configuration of the @code{certbot} service.
27432 This type has the following parameters:
27435 @item @code{package} (default: @code{certbot})
27436 The certbot package to use.
27438 @item @code{webroot} (default: @code{/var/www})
27439 The directory from which to serve the Let's Encrypt challenge/response
27442 @item @code{certificates} (default: @code{()})
27443 A list of @code{certificates-configuration}s for which to generate
27444 certificates and request signatures. Each certificate has a @code{name}
27445 and several @code{domains}.
27447 @item @code{email} (default: @code{#f})
27448 Optional email address used for registration and recovery contact.
27449 Setting this is encouraged as it allows you to receive important
27450 notifications about the account and issued certificates.
27452 @item @code{server} (default: @code{#f})
27453 Optional URL of ACME server. Setting this overrides certbot's default,
27454 which is the Let's Encrypt server.
27456 @item @code{rsa-key-size} (default: @code{2048})
27457 Size of the RSA key.
27459 @item @code{default-location} (default: @i{see below})
27460 The default @code{nginx-location-configuration}. Because @code{certbot}
27461 needs to be able to serve challenges and responses, it needs to be able
27462 to run a web server. It does so by extending the @code{nginx} web
27463 service with an @code{nginx-server-configuration} listening on the
27464 @var{domains} on port 80, and which has a
27465 @code{nginx-location-configuration} for the @code{/.well-known/} URI
27466 path subspace used by Let's Encrypt. @xref{Web Services}, for more on
27467 these nginx configuration data types.
27469 Requests to other URL paths will be matched by the
27470 @code{default-location}, which if present is added to all
27471 @code{nginx-server-configuration}s.
27473 By default, the @code{default-location} will issue a redirect from
27474 @code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving
27475 you to define what to serve on your site via @code{https}.
27477 Pass @code{#f} to not issue a default location.
27481 @deftp {Data Type} certificate-configuration
27482 Data type representing the configuration of a certificate.
27483 This type has the following parameters:
27486 @item @code{name} (default: @i{see below})
27487 This name is used by Certbot for housekeeping and in file paths; it
27488 doesn't affect the content of the certificate itself. To see
27489 certificate names, run @code{certbot certificates}.
27491 Its default is the first provided domain.
27493 @item @code{domains} (default: @code{()})
27494 The first domain provided will be the subject CN of the certificate, and
27495 all domains will be Subject Alternative Names on the certificate.
27497 @item @code{challenge} (default: @code{#f})
27498 The challenge type that has to be run by certbot. If @code{#f} is specified,
27499 default to the HTTP challenge. If a value is specified, defaults to the
27500 manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and
27501 the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}),
27502 and gives Let's Encrypt permission to log the public IP address of the
27503 requesting machine.
27505 @item @code{csr} (default: @code{#f})
27506 File name of Certificate Signing Request (CSR) in DER or PEM format.
27507 If @code{#f} is specified, this argument will not be passed to certbot.
27508 If a value is specified, certbot will use it to obtain a certificate, instead of
27509 using a self-generated CSR.
27510 The domain-name(s) mentioned in @code{domains}, must be consistent with the
27511 domain-name(s) mentioned in CSR file.
27513 @item @code{authentication-hook} (default: @code{#f})
27514 Command to be run in a shell once for each certificate challenge to be
27515 answered. For this command, the shell variable @code{$CERTBOT_DOMAIN}
27516 will contain the domain being authenticated, @code{$CERTBOT_VALIDATION}
27517 contains the validation string and @code{$CERTBOT_TOKEN} contains the
27518 file name of the resource requested when performing an HTTP-01 challenge.
27520 @item @code{cleanup-hook} (default: @code{#f})
27521 Command to be run in a shell once for each certificate challenge that
27522 have been answered by the @code{auth-hook}. For this command, the shell
27523 variables available in the @code{auth-hook} script are still available, and
27524 additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the standard output
27525 of the @code{auth-hook} script.
27527 @item @code{deploy-hook} (default: @code{#f})
27528 Command to be run in a shell once for each successfully issued
27529 certificate. For this command, the shell variable
27530 @code{$RENEWED_LINEAGE} will point to the config live subdirectory (for
27531 example, @samp{"/etc/letsencrypt/live/example.com"}) containing the new
27532 certificates and keys; the shell variable @code{$RENEWED_DOMAINS} will
27533 contain a space-delimited list of renewed certificate domains (for
27534 example, @samp{"example.com www.example.com"}.
27539 For each @code{certificate-configuration}, the certificate is saved to
27540 @code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is
27541 saved to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}.
27543 @subsection DNS Services
27544 @cindex DNS (domain name system)
27545 @cindex domain name system (DNS)
27547 The @code{(gnu services dns)} module provides services related to the
27548 @dfn{domain name system} (DNS). It provides a server service for hosting
27549 an @emph{authoritative} DNS server for multiple zones, slave or master.
27550 This service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a
27551 caching and forwarding DNS server for the LAN, which uses
27552 @uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}.
27554 @subsubheading Knot Service
27556 An example configuration of an authoritative server for two zones, one master
27560 (define-zone-entries example.org.zone
27561 ;; Name TTL Class Type Data
27562 ("@@" "" "IN" "A" "127.0.0.1")
27563 ("@@" "" "IN" "NS" "ns")
27564 ("ns" "" "IN" "A" "127.0.0.1"))
27566 (define master-zone
27567 (knot-zone-configuration
27568 (domain "example.org")
27570 (origin "example.org")
27571 (entries example.org.zone)))))
27574 (knot-zone-configuration
27575 (domain "plop.org")
27576 (dnssec-policy "default")
27577 (master (list "plop-master"))))
27579 (define plop-master
27580 (knot-remote-configuration
27582 (address (list "208.76.58.171"))))
27586 (services (cons* (service knot-service-type
27587 (knot-configuration
27588 (remotes (list plop-master))
27589 (zones (list master-zone slave-zone))))
27594 @deffn {Scheme Variable} knot-service-type
27595 This is the type for the Knot DNS server.
27597 Knot DNS is an authoritative DNS server, meaning that it can serve multiple
27598 zones, that is to say domain names you would buy from a registrar. This server
27599 is not a resolver, meaning that it can only resolve names for which it is
27600 authoritative. This server can be configured to serve zones as a master server
27601 or a slave server as a per-zone basis. Slave zones will get their data from
27602 masters, and will serve it as an authoritative server. From the point of view
27603 of a resolver, there is no difference between master and slave.
27605 The following data types are used to configure the Knot DNS server:
27608 @deftp {Data Type} knot-key-configuration
27609 Data type representing a key.
27610 This type has the following parameters:
27613 @item @code{id} (default: @code{""})
27614 An identifier for other configuration fields to refer to this key. IDs must
27615 be unique and must not be empty.
27617 @item @code{algorithm} (default: @code{#f})
27618 The algorithm to use. Choose between @code{#f}, @code{'hmac-md5},
27619 @code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, @code{'hmac-sha384}
27620 and @code{'hmac-sha512}.
27622 @item @code{secret} (default: @code{""})
27623 The secret key itself.
27628 @deftp {Data Type} knot-acl-configuration
27629 Data type representing an Access Control List (ACL) configuration.
27630 This type has the following parameters:
27633 @item @code{id} (default: @code{""})
27634 An identifier for other configuration fields to refer to this key. IDs must be
27635 unique and must not be empty.
27637 @item @code{address} (default: @code{'()})
27638 An ordered list of IP addresses, network subnets, or network ranges represented
27639 with strings. The query must match one of them. Empty value means that
27640 address match is not required.
27642 @item @code{key} (default: @code{'()})
27643 An ordered list of references to keys represented with strings. The string
27644 must match a key ID defined in a @code{knot-key-configuration}. No key means
27645 that a key is not require to match that ACL.
27647 @item @code{action} (default: @code{'()})
27648 An ordered list of actions that are permitted or forbidden by this ACL@. Possible
27649 values are lists of zero or more elements from @code{'transfer}, @code{'notify}
27650 and @code{'update}.
27652 @item @code{deny?} (default: @code{#f})
27653 When true, the ACL defines restrictions. Listed actions are forbidden. When
27654 false, listed actions are allowed.
27659 @deftp {Data Type} zone-entry
27660 Data type representing a record entry in a zone file.
27661 This type has the following parameters:
27664 @item @code{name} (default: @code{"@@"})
27665 The name of the record. @code{"@@"} refers to the origin of the zone. Names
27666 are relative to the origin of the zone. For example, in the @code{example.org}
27667 zone, @code{"ns.example.org"} actually refers to @code{ns.example.org.example.org}.
27668 Names ending with a dot are absolute, which means that @code{"ns.example.org."}
27669 refers to @code{ns.example.org}.
27671 @item @code{ttl} (default: @code{""})
27672 The Time-To-Live (TTL) of this record. If not set, the default TTL is used.
27674 @item @code{class} (default: @code{"IN"})
27675 The class of the record. Knot currently supports only @code{"IN"} and
27676 partially @code{"CH"}.
27678 @item @code{type} (default: @code{"A"})
27679 The type of the record. Common types include A (IPv4 address), AAAA (IPv6
27680 address), NS (Name Server) and MX (Mail eXchange). Many other types are
27683 @item @code{data} (default: @code{""})
27684 The data contained in the record. For instance an IP address associated with
27685 an A record, or a domain name associated with an NS record. Remember that
27686 domain names are relative to the origin unless they end with a dot.
27691 @deftp {Data Type} zone-file
27692 Data type representing the content of a zone file.
27693 This type has the following parameters:
27696 @item @code{entries} (default: @code{'()})
27697 The list of entries. The SOA record is taken care of, so you don't need to
27698 put it in the list of entries. This list should probably contain an entry
27699 for your primary authoritative DNS server. Other than using a list of entries
27700 directly, you can use @code{define-zone-entries} to define a object containing
27701 the list of entries more easily, that you can later pass to the @code{entries}
27702 field of the @code{zone-file}.
27704 @item @code{origin} (default: @code{""})
27705 The name of your zone. This parameter cannot be empty.
27707 @item @code{ns} (default: @code{"ns"})
27708 The domain of your primary authoritative DNS server. The name is relative to
27709 the origin, unless it ends with a dot. It is mandatory that this primary
27710 DNS server corresponds to an NS record in the zone and that it is associated
27711 to an IP address in the list of entries.
27713 @item @code{mail} (default: @code{"hostmaster"})
27714 An email address people can contact you at, as the owner of the zone. This
27715 is translated as @code{<mail>@@<origin>}.
27717 @item @code{serial} (default: @code{1})
27718 The serial number of the zone. As this is used to keep track of changes by
27719 both slaves and resolvers, it is mandatory that it @emph{never} decreases.
27720 Always increment it when you make a change in your zone.
27722 @item @code{refresh} (default: @code{(* 2 24 3600)})
27723 The frequency at which slaves will do a zone transfer. This value is a number
27724 of seconds. It can be computed by multiplications or with
27725 @code{(string->duration)}.
27727 @item @code{retry} (default: @code{(* 15 60)})
27728 The period after which a slave will retry to contact its master when it fails
27729 to do so a first time.
27731 @item @code{expiry} (default: @code{(* 14 24 3600)})
27732 Default TTL of records. Existing records are considered correct for at most
27733 this amount of time. After this period, resolvers will invalidate their cache
27734 and check again that it still exists.
27736 @item @code{nx} (default: @code{3600})
27737 Default TTL of inexistent records. This delay is usually short because you want
27738 your new domains to reach everyone quickly.
27743 @deftp {Data Type} knot-remote-configuration
27744 Data type representing a remote configuration.
27745 This type has the following parameters:
27748 @item @code{id} (default: @code{""})
27749 An identifier for other configuration fields to refer to this remote. IDs must
27750 be unique and must not be empty.
27752 @item @code{address} (default: @code{'()})
27753 An ordered list of destination IP addresses. Addresses are tried in sequence.
27754 An optional port can be given with the @@ separator. For instance:
27755 @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53.
27757 @item @code{via} (default: @code{'()})
27758 An ordered list of source IP addresses. An empty list will have Knot choose
27759 an appropriate source IP@. An optional port can be given with the @@ separator.
27760 The default is to choose at random.
27762 @item @code{key} (default: @code{#f})
27763 A reference to a key, that is a string containing the identifier of a key
27764 defined in a @code{knot-key-configuration} field.
27769 @deftp {Data Type} knot-keystore-configuration
27770 Data type representing a keystore to hold dnssec keys.
27771 This type has the following parameters:
27774 @item @code{id} (default: @code{""})
27775 The id of the keystore. It must not be empty.
27777 @item @code{backend} (default: @code{'pem})
27778 The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}.
27780 @item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
27781 The configuration string of the backend. An example for the PKCS#11 is:
27782 @code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
27783 For the pem backend, the string represents a path in the file system.
27788 @deftp {Data Type} knot-policy-configuration
27789 Data type representing a dnssec policy. Knot DNS is able to automatically
27790 sign your zones. It can either generate and manage your keys automatically or
27791 use keys that you generate.
27793 Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that is
27794 used to sign the second, and a Zone Signing Key (ZSK) that is used to sign the
27795 zone. In order to be trusted, the KSK needs to be present in the parent zone
27796 (usually a top-level domain). If your registrar supports dnssec, you will
27797 have to send them your KSK's hash so they can add a DS record in their zone.
27798 This is not automated and need to be done each time you change your KSK.
27800 The policy also defines the lifetime of keys. Usually, ZSK can be changed
27801 easily and use weaker cryptographic functions (they use lower parameters) in
27802 order to sign records quickly, so they are changed often. The KSK however
27803 requires manual interaction with the registrar, so they are changed less often
27804 and use stronger parameters because they sign only one record.
27806 This type has the following parameters:
27809 @item @code{id} (default: @code{""})
27810 The id of the policy. It must not be empty.
27812 @item @code{keystore} (default: @code{"default"})
27813 A reference to a keystore, that is a string containing the identifier of a
27814 keystore defined in a @code{knot-keystore-configuration} field. The
27815 @code{"default"} identifier means the default keystore (a kasp database that
27816 was setup by this service).
27818 @item @code{manual?} (default: @code{#f})
27819 Whether the key management is manual or automatic.
27821 @item @code{single-type-signing?} (default: @code{#f})
27822 When @code{#t}, use the Single-Type Signing Scheme.
27824 @item @code{algorithm} (default: @code{"ecdsap256sha256"})
27825 An algorithm of signing keys and issued signatures.
27827 @item @code{ksk-size} (default: @code{256})
27828 The length of the KSK@. Note that this value is correct for the default
27829 algorithm, but would be unsecure for other algorithms.
27831 @item @code{zsk-size} (default: @code{256})
27832 The length of the ZSK@. Note that this value is correct for the default
27833 algorithm, but would be unsecure for other algorithms.
27835 @item @code{dnskey-ttl} (default: @code{'default})
27836 The TTL value for DNSKEY records added into zone apex. The special
27837 @code{'default} value means same as the zone SOA TTL.
27839 @item @code{zsk-lifetime} (default: @code{(* 30 24 3600)})
27840 The period between ZSK publication and the next rollover initiation.
27842 @item @code{propagation-delay} (default: @code{(* 24 3600)})
27843 An extra delay added for each key rollover step. This value should be high
27844 enough to cover propagation of data from the master server to all slaves.
27846 @item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)})
27847 A validity period of newly issued signatures.
27849 @item @code{rrsig-refresh} (default: @code{(* 7 24 3600)})
27850 A period how long before a signature expiration the signature will be refreshed.
27852 @item @code{nsec3?} (default: @code{#f})
27853 When @code{#t}, NSEC3 will be used instead of NSEC.
27855 @item @code{nsec3-iterations} (default: @code{5})
27856 The number of additional times the hashing is performed.
27858 @item @code{nsec3-salt-length} (default: @code{8})
27859 The length of a salt field in octets, which is appended to the original owner
27860 name before hashing.
27862 @item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)})
27863 The validity period of newly issued salt field.
27868 @deftp {Data Type} knot-zone-configuration
27869 Data type representing a zone served by Knot.
27870 This type has the following parameters:
27873 @item @code{domain} (default: @code{""})
27874 The domain served by this configuration. It must not be empty.
27876 @item @code{file} (default: @code{""})
27877 The file where this zone is saved. This parameter is ignored by master zones.
27878 Empty means default location that depends on the domain name.
27880 @item @code{zone} (default: @code{(zone-file)})
27881 The content of the zone file. This parameter is ignored by slave zones. It
27882 must contain a zone-file record.
27884 @item @code{master} (default: @code{'()})
27885 A list of master remotes. When empty, this zone is a master. When set, this
27886 zone is a slave. This is a list of remotes identifiers.
27888 @item @code{ddns-master} (default: @code{#f})
27889 The main master. When empty, it defaults to the first master in the list of
27892 @item @code{notify} (default: @code{'()})
27893 A list of slave remote identifiers.
27895 @item @code{acl} (default: @code{'()})
27896 A list of acl identifiers.
27898 @item @code{semantic-checks?} (default: @code{#f})
27899 When set, this adds more semantic checks to the zone.
27901 @item @code{zonefile-sync} (default: @code{0})
27902 The delay between a modification in memory and on disk. 0 means immediate
27905 @item @code{zonefile-load} (default: @code{#f})
27906 The way the zone file contents are applied during zone load. Possible values
27910 @item @code{#f} for using the default value from Knot,
27911 @item @code{'none} for not using the zone file at all,
27912 @item @code{'difference} for computing the difference between already available
27913 contents and zone contents and applying it to the current zone contents,
27914 @item @code{'difference-no-serial} for the same as @code{'difference}, but
27915 ignoring the SOA serial in the zone file, while the server takes care of it
27917 @item @code{'whole} for loading zone contents from the zone file.
27920 @item @code{journal-content} (default: @code{#f})
27921 The way the journal is used to store zone and its changes. Possible values
27922 are @code{'none} to not use it at all, @code{'changes} to store changes and
27923 @code{'all} to store contents. @code{#f} does not set this option, so the
27924 default value from Knot is used.
27926 @item @code{max-journal-usage} (default: @code{#f})
27927 The maximum size for the journal on disk. @code{#f} does not set this option,
27928 so the default value from Knot is used.
27930 @item @code{max-journal-depth} (default: @code{#f})
27931 The maximum size of the history. @code{#f} does not set this option, so the
27932 default value from Knot is used.
27934 @item @code{max-zone-size} (default: @code{#f})
27935 The maximum size of the zone file. This limit is enforced for incoming
27936 transfer and updates. @code{#f} does not set this option, so the default
27937 value from Knot is used.
27939 @item @code{dnssec-policy} (default: @code{#f})
27940 A reference to a @code{knot-policy-configuration} record, or the special
27941 name @code{"default"}. If the value is @code{#f}, there is no dnssec signing
27944 @item @code{serial-policy} (default: @code{'increment})
27945 A policy between @code{'increment} and @code{'unixtime}.
27950 @deftp {Data Type} knot-configuration
27951 Data type representing the Knot configuration.
27952 This type has the following parameters:
27955 @item @code{knot} (default: @code{knot})
27958 @item @code{run-directory} (default: @code{"/var/run/knot"})
27959 The run directory. This directory will be used for pid file and sockets.
27961 @item @code{includes} (default: @code{'()})
27962 A list of strings or file-like objects denoting other files that must be
27963 included at the top of the configuration file.
27965 @cindex secrets, Knot service
27966 This can be used to manage secrets out-of-band. For example, secret
27967 keys may be stored in an out-of-band file not managed by Guix, and
27968 thus not visible in @file{/gnu/store}---e.g., you could store secret
27969 key configuration in @file{/etc/knot/secrets.conf} and add this file
27970 to the @code{includes} list.
27972 One can generate a secret tsig key (for nsupdate and zone transfers with the
27973 keymgr command from the knot package. Note that the package is not automatically
27974 installed by the service. The following example shows how to generate a new
27978 keymgr -t mysecret > /etc/knot/secrets.conf
27979 chmod 600 /etc/knot/secrets.conf
27982 Also note that the generated key will be named @var{mysecret}, so it is the
27983 name that needs to be used in the @var{key} field of the
27984 @code{knot-acl-configuration} record and in other places that need to refer
27987 It can also be used to add configuration not supported by this interface.
27989 @item @code{listen-v4} (default: @code{"0.0.0.0"})
27990 An ip address on which to listen.
27992 @item @code{listen-v6} (default: @code{"::"})
27993 An ip address on which to listen.
27995 @item @code{listen-port} (default: @code{53})
27996 A port on which to listen.
27998 @item @code{keys} (default: @code{'()})
27999 The list of knot-key-configuration used by this configuration.
28001 @item @code{acls} (default: @code{'()})
28002 The list of knot-acl-configuration used by this configuration.
28004 @item @code{remotes} (default: @code{'()})
28005 The list of knot-remote-configuration used by this configuration.
28007 @item @code{zones} (default: @code{'()})
28008 The list of knot-zone-configuration used by this configuration.
28013 @subsubheading Knot Resolver Service
28015 @deffn {Scheme Variable} knot-resolver-service-type
28016 This is the type of the knot resolver service, whose value should be
28017 an @code{knot-resolver-configuration} object as in this example:
28020 (service knot-resolver-service-type
28021 (knot-resolver-configuration
28022 (kresd-config-file (plain-file "kresd.conf" "
28023 net.listen('192.168.0.1', 5353)
28024 user('knot-resolver', 'knot-resolver')
28025 modules = @{ 'hints > iterate', 'stats', 'predict' @}
28026 cache.size = 100 * MB
28030 For more information, refer its @url{https://knot-resolver.readthedocs.org/en/stable/daemon.html#configuration, manual}.
28033 @deftp {Data Type} knot-resolver-configuration
28034 Data type representing the configuration of knot-resolver.
28037 @item @code{package} (default: @var{knot-resolver})
28038 Package object of the knot DNS resolver.
28040 @item @code{kresd-config-file} (default: %kresd.conf)
28041 File-like object of the kresd configuration file to use, by default it
28042 will listen on @code{127.0.0.1} and @code{::1}.
28044 @item @code{garbage-collection-interval} (default: 1000)
28045 Number of milliseconds for @code{kres-cache-gc} to periodically trim the cache.
28051 @subsubheading Dnsmasq Service
28053 @deffn {Scheme Variable} dnsmasq-service-type
28054 This is the type of the dnsmasq service, whose value should be an
28055 @code{dnsmasq-configuration} object as in this example:
28058 (service dnsmasq-service-type
28059 (dnsmasq-configuration
28061 (servers '("192.168.1.1"))))
28065 @deftp {Data Type} dnsmasq-configuration
28066 Data type representing the configuration of dnsmasq.
28069 @item @code{package} (default: @var{dnsmasq})
28070 Package object of the dnsmasq server.
28072 @item @code{no-hosts?} (default: @code{#f})
28073 When true, don't read the hostnames in /etc/hosts.
28075 @item @code{port} (default: @code{53})
28076 The port to listen on. Setting this to zero completely disables DNS
28077 responses, leaving only DHCP and/or TFTP functions.
28079 @item @code{local-service?} (default: @code{#t})
28080 Accept DNS queries only from hosts whose address is on a local subnet,
28081 ie a subnet for which an interface exists on the server.
28083 @item @code{listen-addresses} (default: @code{'()})
28084 Listen on the given IP addresses.
28086 @item @code{resolv-file} (default: @code{"/etc/resolv.conf"})
28087 The file to read the IP address of the upstream nameservers from.
28089 @item @code{no-resolv?} (default: @code{#f})
28090 When true, don't read @var{resolv-file}.
28092 @item @code{servers} (default: @code{'()})
28093 Specify IP address of upstream servers directly.
28095 @item @code{addresses} (default: @code{'()})
28096 For each entry, specify an IP address to return for any host in the
28097 given domains. Queries in the domains are never forwarded and always
28098 replied to with the specified IP address.
28100 This is useful for redirecting hosts locally, for example:
28103 (service dnsmasq-service-type
28104 (dnsmasq-configuration
28106 '(; Redirect to a local web-server.
28107 "/example.org/127.0.0.1"
28108 ; Redirect subdomain to a specific IP.
28109 "/subdomain.example.org/192.168.1.42"))))
28112 Note that rules in @file{/etc/hosts} take precedence over this.
28114 @item @code{cache-size} (default: @code{150})
28115 Set the size of dnsmasq's cache. Setting the cache size to zero
28118 @item @code{negative-cache?} (default: @code{#t})
28119 When false, disable negative caching.
28121 @item @code{tftp-enable?} (default: @code{#f})
28122 Whether to enable the built-in TFTP server.
28124 @item @code{tftp-no-fail?} (default: @code{#f})
28125 If true, does not fail dnsmasq if the TFTP server could not start up.
28127 @item @code{tftp-single-port?} (default: @code{#f})
28128 Whether to use only one single port for TFTP.
28130 @item @code{tftp-secure?} (default: @code{#f})
28131 If true, only files owned by the user running the dnsmasq process are accessible.
28133 If dnsmasq is being run as root, different rules apply:
28134 @code{tftp-secure?} has no effect, but only files which have the
28135 world-readable bit set are accessible.
28137 @item @code{tftp-max} (default: @code{#f})
28138 If set, sets the maximal number of concurrent connections allowed.
28140 @item @code{tftp-mtu} (default: @code{#f})
28141 If set, sets the MTU for TFTP packets to that value.
28143 @item @code{tftp-no-blocksize?} (default: @code{#f})
28144 If true, stops the TFTP server from negotiating the blocksize with a client.
28146 @item @code{tftp-lowercase?} (default: @code{#f})
28147 Whether to convert all filenames in TFTP requests to lowercase.
28149 @item @code{tftp-port-range} (default: @code{#f})
28150 If set, fixes the dynamical ports (one per client) to the given range
28151 (@code{"<start>,<end>"}).
28153 @item @code{tftp-root} (default: @code{/var/empty,lo})
28154 Look for files to transfer using TFTP relative to the given directory.
28155 When this is set, TFTP paths which include @samp{..} are rejected, to stop clients
28156 getting outside the specified root. Absolute paths (starting with @samp{/}) are
28157 allowed, but they must be within the TFTP-root. If the optional interface
28158 argument is given, the directory is only used for TFTP requests via that
28161 @item @code{tftp-unique-root} (default: @code{#f})
28162 If set, add the IP or hardware address of the TFTP client as a path component
28163 on the end of the TFTP-root. Only valid if a TFTP root is set and the
28164 directory exists. Defaults to adding IP address (in standard dotted-quad
28167 For instance, if @option{--tftp-root} is @samp{/tftp} and client
28168 @samp{1.2.3.4} requests file @file{myfile} then the effective path will
28169 be @file{/tftp/1.2.3.4/myfile} if @file{/tftp/1.2.3.4} exists or
28170 @file{/tftp/myfile} otherwise. When @samp{=mac} is specified it will
28171 append the MAC address instead, using lowercase zero padded digits
28172 separated by dashes, e.g.: @samp{01-02-03-04-aa-bb}. Note that
28173 resolving MAC addresses is only possible if the client is in the local
28174 network or obtained a DHCP lease from dnsmasq.
28179 @subsubheading ddclient Service
28182 The ddclient service described below runs the ddclient daemon, which takes
28183 care of automatically updating DNS entries for service providers such as
28184 @uref{https://dyn.com/dns/, Dyn}.
28186 The following example show instantiates the service with its default
28190 (service ddclient-service-type)
28193 Note that ddclient needs to access credentials that are stored in a
28194 @dfn{secret file}, by default @file{/etc/ddclient/secrets} (see
28195 @code{secret-file} below). You are expected to create this file manually, in
28196 an ``out-of-band'' fashion (you @emph{could} make this file part of the
28197 service configuration, for instance by using @code{plain-file}, but it will be
28198 world-readable @i{via} @file{/gnu/store}). See the examples in the
28199 @file{share/ddclient} directory of the @code{ddclient} package.
28201 @c %start of fragment
28203 Available @code{ddclient-configuration} fields are:
28205 @deftypevr {@code{ddclient-configuration} parameter} package ddclient
28206 The ddclient package.
28210 @deftypevr {@code{ddclient-configuration} parameter} integer daemon
28211 The period after which ddclient will retry to check IP and domain name.
28213 Defaults to @samp{300}.
28217 @deftypevr {@code{ddclient-configuration} parameter} boolean syslog
28218 Use syslog for the output.
28220 Defaults to @samp{#t}.
28224 @deftypevr {@code{ddclient-configuration} parameter} string mail
28227 Defaults to @samp{"root"}.
28231 @deftypevr {@code{ddclient-configuration} parameter} string mail-failure
28232 Mail failed update to user.
28234 Defaults to @samp{"root"}.
28238 @deftypevr {@code{ddclient-configuration} parameter} string pid
28239 The ddclient PID file.
28241 Defaults to @samp{"/var/run/ddclient/ddclient.pid"}.
28245 @deftypevr {@code{ddclient-configuration} parameter} boolean ssl
28246 Enable SSL support.
28248 Defaults to @samp{#t}.
28252 @deftypevr {@code{ddclient-configuration} parameter} string user
28253 Specifies the user name or ID that is used when running ddclient
28256 Defaults to @samp{"ddclient"}.
28260 @deftypevr {@code{ddclient-configuration} parameter} string group
28261 Group of the user who will run the ddclient program.
28263 Defaults to @samp{"ddclient"}.
28267 @deftypevr {@code{ddclient-configuration} parameter} string secret-file
28268 Secret file which will be appended to @file{ddclient.conf} file. This
28269 file contains credentials for use by ddclient. You are expected to
28270 create it manually.
28272 Defaults to @samp{"/etc/ddclient/secrets.conf"}.
28276 @deftypevr {@code{ddclient-configuration} parameter} list extra-options
28277 Extra options will be appended to @file{ddclient.conf} file.
28279 Defaults to @samp{()}.
28284 @c %end of fragment
28288 @subsection VPN Services
28289 @cindex VPN (virtual private network)
28290 @cindex virtual private network (VPN)
28292 The @code{(gnu services vpn)} module provides services related to
28293 @dfn{virtual private networks} (VPNs).
28295 @subsubheading Bitmask
28297 @defvr {Scheme Variable} bitmask-service-type
28298 A service type for the @uref{https://bitmask.net, Bitmask} VPN client. It makes
28299 the client available in the system and loads its polkit policy. Please note that
28300 the client expects an active polkit-agent, which is either run by your
28301 desktop-environment or should be run manually.
28304 @subsubheading OpenVPN
28306 It provides a @emph{client} service for your machine to connect to a
28307 VPN, and a @emph{server} service for your machine to host a VPN@.
28309 @deffn {Scheme Procedure} openvpn-client-service @
28310 [#:config (openvpn-client-configuration)]
28312 Return a service that runs @command{openvpn}, a VPN daemon, as a client.
28315 @deffn {Scheme Procedure} openvpn-server-service @
28316 [#:config (openvpn-server-configuration)]
28318 Return a service that runs @command{openvpn}, a VPN daemon, as a server.
28320 Both can be run simultaneously.
28323 @c %automatically generated documentation
28325 Available @code{openvpn-client-configuration} fields are:
28327 @deftypevr {@code{openvpn-client-configuration} parameter} package openvpn
28328 The OpenVPN package.
28332 @deftypevr {@code{openvpn-client-configuration} parameter} string pid-file
28333 The OpenVPN pid file.
28335 Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
28339 @deftypevr {@code{openvpn-client-configuration} parameter} proto proto
28340 The protocol (UDP or TCP) used to open a channel between clients and
28343 Defaults to @samp{udp}.
28347 @deftypevr {@code{openvpn-client-configuration} parameter} dev dev
28348 The device type used to represent the VPN connection.
28350 Defaults to @samp{tun}.
28354 If you do not have some of these files (eg.@: you use a username and
28355 password), you can disable any of the following three fields by setting
28356 it to @code{'disabled}.
28358 @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string ca
28359 The certificate authority to check connections against.
28361 Defaults to @samp{"/etc/openvpn/ca.crt"}.
28365 @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string cert
28366 The certificate of the machine the daemon is running on. It should be
28367 signed by the authority given in @code{ca}.
28369 Defaults to @samp{"/etc/openvpn/client.crt"}.
28373 @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string key
28374 The key of the machine the daemon is running on. It must be the key whose
28375 certificate is @code{cert}.
28377 Defaults to @samp{"/etc/openvpn/client.key"}.
28381 @deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo?
28382 Whether to use the lzo compression algorithm.
28384 Defaults to @samp{#t}.
28388 @deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key?
28389 Don't re-read key files across SIGUSR1 or --ping-restart.
28391 Defaults to @samp{#t}.
28395 @deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun?
28396 Don't close and reopen TUN/TAP device or run up/down scripts across
28397 SIGUSR1 or --ping-restart restarts.
28399 Defaults to @samp{#t}.
28403 @deftypevr {@code{openvpn-client-configuration} parameter} boolean fast-io?
28404 (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
28405 poll/epoll/select prior to the write operation.
28407 Defaults to @samp{#f}.
28410 @deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
28413 Defaults to @samp{3}.
28417 @deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth
28418 Add an additional layer of HMAC authentication on top of the TLS control
28419 channel to protect against DoS attacks.
28421 Defaults to @samp{#f}.
28425 @deftypevr {@code{openvpn-client-configuration} parameter} maybe-string auth-user-pass
28426 Authenticate with server using username/password. The option is a file
28427 containing username/password on 2 lines. Do not use a file-like object as it
28428 would be added to the store and readable by any user.
28430 Defaults to @samp{'disabled}.
28433 @deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
28434 Whether to check the server certificate has server usage extension.
28436 Defaults to @samp{#t}.
28440 @deftypevr {@code{openvpn-client-configuration} parameter} bind bind?
28441 Bind to a specific local port number.
28443 Defaults to @samp{#f}.
28447 @deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry?
28448 Retry resolving server address.
28450 Defaults to @samp{#t}.
28454 @deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote
28455 A list of remote servers to connect to.
28457 Defaults to @samp{()}.
28459 Available @code{openvpn-remote-configuration} fields are:
28461 @deftypevr {@code{openvpn-remote-configuration} parameter} string name
28464 Defaults to @samp{"my-server"}.
28468 @deftypevr {@code{openvpn-remote-configuration} parameter} number port
28469 Port number the server listens to.
28471 Defaults to @samp{1194}.
28476 @c %end of automatic openvpn-client documentation
28478 @c %automatically generated documentation
28480 Available @code{openvpn-server-configuration} fields are:
28482 @deftypevr {@code{openvpn-server-configuration} parameter} package openvpn
28483 The OpenVPN package.
28487 @deftypevr {@code{openvpn-server-configuration} parameter} string pid-file
28488 The OpenVPN pid file.
28490 Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
28494 @deftypevr {@code{openvpn-server-configuration} parameter} proto proto
28495 The protocol (UDP or TCP) used to open a channel between clients and
28498 Defaults to @samp{udp}.
28502 @deftypevr {@code{openvpn-server-configuration} parameter} dev dev
28503 The device type used to represent the VPN connection.
28505 Defaults to @samp{tun}.
28509 If you do not have some of these files (eg.@: you use a username and
28510 password), you can disable any of the following three fields by setting
28511 it to @code{'disabled}.
28513 @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string ca
28514 The certificate authority to check connections against.
28516 Defaults to @samp{"/etc/openvpn/ca.crt"}.
28520 @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string cert
28521 The certificate of the machine the daemon is running on. It should be
28522 signed by the authority given in @code{ca}.
28524 Defaults to @samp{"/etc/openvpn/client.crt"}.
28528 @deftypevr {@code{openvpn-server-configuration} parameter} maybe-string key
28529 The key of the machine the daemon is running on. It must be the key whose
28530 certificate is @code{cert}.
28532 Defaults to @samp{"/etc/openvpn/client.key"}.
28536 @deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo?
28537 Whether to use the lzo compression algorithm.
28539 Defaults to @samp{#t}.
28543 @deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key?
28544 Don't re-read key files across SIGUSR1 or --ping-restart.
28546 Defaults to @samp{#t}.
28550 @deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun?
28551 Don't close and reopen TUN/TAP device or run up/down scripts across
28552 SIGUSR1 or --ping-restart restarts.
28554 Defaults to @samp{#t}.
28558 @deftypevr {@code{openvpn-server-configuration} parameter} boolean fast-io?
28559 (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
28560 poll/epoll/select prior to the write operation.
28562 Defaults to @samp{#f}.
28565 @deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
28568 Defaults to @samp{3}.
28572 @deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth
28573 Add an additional layer of HMAC authentication on top of the TLS control
28574 channel to protect against DoS attacks.
28576 Defaults to @samp{#f}.
28580 @deftypevr {@code{openvpn-server-configuration} parameter} number port
28581 Specifies the port number on which the server listens.
28583 Defaults to @samp{1194}.
28587 @deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server
28588 An ip and mask specifying the subnet inside the virtual network.
28590 Defaults to @samp{"10.8.0.0 255.255.255.0"}.
28594 @deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6
28595 A CIDR notation specifying the IPv6 subnet inside the virtual network.
28597 Defaults to @samp{#f}.
28601 @deftypevr {@code{openvpn-server-configuration} parameter} string dh
28602 The Diffie-Hellman parameters file.
28604 Defaults to @samp{"/etc/openvpn/dh2048.pem"}.
28608 @deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist
28609 The file that records client IPs.
28611 Defaults to @samp{"/etc/openvpn/ipp.txt"}.
28615 @deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway?
28616 When true, the server will act as a gateway for its clients.
28618 Defaults to @samp{#f}.
28622 @deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client?
28623 When true, clients are allowed to talk to each other inside the VPN.
28625 Defaults to @samp{#f}.
28629 @deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive
28630 Causes ping-like messages to be sent back and forth over the link so
28631 that each side knows when the other side has gone down. @code{keepalive}
28632 requires a pair. The first element is the period of the ping sending,
28633 and the second element is the timeout before considering the other side
28638 @deftypevr {@code{openvpn-server-configuration} parameter} number max-clients
28639 The maximum number of clients.
28641 Defaults to @samp{100}.
28645 @deftypevr {@code{openvpn-server-configuration} parameter} string status
28646 The status file. This file shows a small report on current connection.
28647 It is truncated and rewritten every minute.
28649 Defaults to @samp{"/var/run/openvpn/status"}.
28653 @deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir
28654 The list of configuration for some clients.
28656 Defaults to @samp{()}.
28658 Available @code{openvpn-ccd-configuration} fields are:
28660 @deftypevr {@code{openvpn-ccd-configuration} parameter} string name
28663 Defaults to @samp{"client"}.
28667 @deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute
28670 Defaults to @samp{#f}.
28674 @deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push
28677 Defaults to @samp{#f}.
28683 @c %end of automatic openvpn-server documentation
28685 @subheading strongSwan
28687 Currently, the strongSwan service only provides legacy-style configuration with
28688 @file{ipsec.conf} and @file{ipsec.secrets} files.
28690 @defvr {Scheme Variable} strongswan-service-type
28691 A service type for configuring strongSwan for IPsec @acronym{VPN,
28692 Virtual Private Networking}. Its value must be a
28693 @code{strongswan-configuration} record as in this example:
28696 (service strongswan-service-type
28697 (strongswan-configuration
28698 (ipsec-conf "/etc/ipsec.conf")
28699 (ipsec-secrets "/etc/ipsec.secrets")))
28704 @deftp {Data Type} strongswan-configuration
28705 Data type representing the configuration of the StrongSwan service.
28708 @item @code{strongswan}
28709 The strongSwan package to use for this service.
28711 @item @code{ipsec-conf} (default: @code{#f})
28712 The file name of your @file{ipsec.conf}. If not @code{#f}, then this and
28713 @code{ipsec-secrets} must both be strings.
28715 @item @code{ipsec-secrets} (default @code{#f})
28716 The file name of your @file{ipsec.secrets}. If not @code{#f}, then this and
28717 @code{ipsec-conf} must both be strings.
28722 @subsubheading Wireguard
28724 @defvr {Scheme Variable} wireguard-service-type
28725 A service type for a Wireguard tunnel interface. Its value must be a
28726 @code{wireguard-configuration} record as in this example:
28729 (service wireguard-service-type
28730 (wireguard-configuration
28735 (endpoint "my.wireguard.com:51820")
28736 (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
28737 (allowed-ips '("10.0.0.2/32")))))))
28742 @deftp {Data Type} wireguard-configuration
28743 Data type representing the configuration of the Wireguard service.
28746 @item @code{wireguard}
28747 The wireguard package to use for this service.
28749 @item @code{interface} (default: @code{"wg0"})
28750 The interface name for the VPN.
28752 @item @code{addresses} (default: @code{'("10.0.0.1/32")})
28753 The IP addresses to be assigned to the above interface.
28755 @item @code{port} (default: @code{51820})
28756 The port on which to listen for incoming connections.
28758 @item @code{dns} (default: @code{#f})
28759 The DNS server(s) to announce to VPN clients via DHCP.
28761 @item @code{private-key} (default: @code{"/etc/wireguard/private.key"})
28762 The private key file for the interface. It is automatically generated if
28763 the file does not exist.
28765 @item @code{peers} (default: @code{'()})
28766 The authorized peers on this interface. This is a list of
28767 @var{wireguard-peer} records.
28772 @deftp {Data Type} wireguard-peer
28773 Data type representing a Wireguard peer attached to a given interface.
28779 @item @code{endpoint} (default: @code{#f})
28780 The optional endpoint for the peer, such as
28781 @code{"demo.wireguard.com:51820"}.
28783 @item @code{public-key}
28784 The peer public-key represented as a base64 string.
28786 @item @code{allowed-ips}
28787 A list of IP addresses from which incoming traffic for this peer is
28788 allowed and to which incoming traffic for this peer is directed.
28790 @item @code{keep-alive} (default: @code{#f})
28791 An optional time interval in seconds. A packet will be sent to the
28792 server endpoint once per time interval. This helps receiving
28793 incoming connections from this peer when you are behind a NAT or
28799 @node Network File System
28800 @subsection Network File System
28803 The @code{(gnu services nfs)} module provides the following services,
28804 which are most commonly used in relation to mounting or exporting
28805 directory trees as @dfn{network file systems} (NFS).
28807 While it is possible to use the individual components that together make
28808 up a Network File System service, we recommended to configure an NFS
28809 server with the @code{nfs-service-type}.
28811 @subsubheading NFS Service
28812 @cindex NFS, server
28814 The NFS service takes care of setting up all NFS component services,
28815 kernel configuration file systems, and installs configuration files in
28816 the locations that NFS expects.
28818 @defvr {Scheme Variable} nfs-service-type
28819 A service type for a complete NFS server.
28822 @deftp {Data Type} nfs-configuration
28823 This data type represents the configuration of the NFS service and all
28826 It has the following parameters:
28828 @item @code{nfs-utils} (default: @code{nfs-utils})
28829 The nfs-utils package to use.
28831 @item @code{nfs-versions} (default: @code{'("4.2" "4.1" "4.0")})
28832 If a list of string values is provided, the @command{rpc.nfsd} daemon
28833 will be limited to supporting the given versions of the NFS protocol.
28835 @item @code{exports} (default: @code{'()})
28836 This is a list of directories the NFS server should export. Each entry
28837 is a list consisting of two elements: a directory name and a string
28838 containing all options. This is an example in which the directory
28839 @file{/export} is served to all NFS clients as a read-only share:
28845 "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))
28848 @item @code{rpcmountd-port} (default: @code{#f})
28849 The network port that the @command{rpc.mountd} daemon should use.
28851 @item @code{rpcstatd-port} (default: @code{#f})
28852 The network port that the @command{rpc.statd} daemon should use.
28854 @item @code{rpcbind} (default: @code{rpcbind})
28855 The rpcbind package to use.
28857 @item @code{idmap-domain} (default: @code{"localdomain"})
28858 The local NFSv4 domain name.
28860 @item @code{nfsd-port} (default: @code{2049})
28861 The network port that the @command{nfsd} daemon should use.
28863 @item @code{nfsd-threads} (default: @code{8})
28864 The number of threads used by the @command{nfsd} daemon.
28866 @item @code{nfsd-tcp?} (default: @code{#t})
28867 Whether the @command{nfsd} daemon should listen on a TCP socket.
28869 @item @code{nfsd-udp?} (default: @code{#f})
28870 Whether the @command{nfsd} daemon should listen on a UDP socket.
28872 @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
28873 The directory where the pipefs file system is mounted.
28875 @item @code{debug} (default: @code{'()"})
28876 A list of subsystems for which debugging output should be enabled. This
28877 is a list of symbols. Any of these symbols are valid: @code{nfsd},
28878 @code{nfs}, @code{rpc}, @code{idmap}, @code{statd}, or @code{mountd}.
28882 If you don't need a complete NFS service or prefer to build it yourself
28883 you can use the individual component services that are documented below.
28885 @subsubheading RPC Bind Service
28888 The RPC Bind service provides a facility to map program numbers into
28889 universal addresses.
28890 Many NFS related services use this facility. Hence it is automatically
28891 started when a dependent service starts.
28893 @defvr {Scheme Variable} rpcbind-service-type
28894 A service type for the RPC portmapper daemon.
28898 @deftp {Data Type} rpcbind-configuration
28899 Data type representing the configuration of the RPC Bind Service.
28900 This type has the following parameters:
28902 @item @code{rpcbind} (default: @code{rpcbind})
28903 The rpcbind package to use.
28905 @item @code{warm-start?} (default: @code{#t})
28906 If this parameter is @code{#t}, then the daemon will read a
28907 state file on startup thus reloading state information saved by a previous
28913 @subsubheading Pipefs Pseudo File System
28917 The pipefs file system is used to transfer NFS related data
28918 between the kernel and user space programs.
28920 @defvr {Scheme Variable} pipefs-service-type
28921 A service type for the pipefs pseudo file system.
28924 @deftp {Data Type} pipefs-configuration
28925 Data type representing the configuration of the pipefs pseudo file system service.
28926 This type has the following parameters:
28928 @item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
28929 The directory to which the file system is to be attached.
28934 @subsubheading GSS Daemon Service
28937 @cindex global security system
28939 The @dfn{global security system} (GSS) daemon provides strong security for RPC
28941 Before exchanging RPC requests an RPC client must establish a security
28942 context. Typically this is done using the Kerberos command @command{kinit}
28943 or automatically at login time using PAM services (@pxref{Kerberos Services}).
28945 @defvr {Scheme Variable} gss-service-type
28946 A service type for the Global Security System (GSS) daemon.
28949 @deftp {Data Type} gss-configuration
28950 Data type representing the configuration of the GSS daemon service.
28951 This type has the following parameters:
28953 @item @code{nfs-utils} (default: @code{nfs-utils})
28954 The package in which the @command{rpc.gssd} command is to be found.
28956 @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
28957 The directory where the pipefs file system is mounted.
28963 @subsubheading IDMAP Daemon Service
28965 @cindex name mapper
28967 The idmap daemon service provides mapping between user IDs and user names.
28968 Typically it is required in order to access file systems mounted via NFSv4.
28970 @defvr {Scheme Variable} idmap-service-type
28971 A service type for the Identity Mapper (IDMAP) daemon.
28974 @deftp {Data Type} idmap-configuration
28975 Data type representing the configuration of the IDMAP daemon service.
28976 This type has the following parameters:
28978 @item @code{nfs-utils} (default: @code{nfs-utils})
28979 The package in which the @command{rpc.idmapd} command is to be found.
28981 @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
28982 The directory where the pipefs file system is mounted.
28984 @item @code{domain} (default: @code{#f})
28985 The local NFSv4 domain name.
28986 This must be a string or @code{#f}.
28987 If it is @code{#f} then the daemon will use the host's fully qualified domain name.
28989 @item @code{verbosity} (default: @code{0})
28990 The verbosity level of the daemon.
28995 @node Continuous Integration
28996 @subsection Continuous Integration
28998 @cindex continuous integration
28999 @uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous
29000 integration tool for Guix. It can be used both for development and for
29001 providing substitutes to others (@pxref{Substitutes}).
29003 The @code{(gnu services cuirass)} module provides the following service.
29005 @defvr {Scheme Procedure} cuirass-service-type
29006 The type of the Cuirass service. Its value must be a
29007 @code{cuirass-configuration} object, as described below.
29010 To add build jobs, you have to set the @code{specifications} field of
29011 the configuration. For instance, the following example will build all
29012 the packages provided by the @code{my-channel} channel.
29015 (define %cuirass-specs
29016 #~(list (specification
29017 (name "my-channel")
29018 (build '(channels my-channel))
29022 (url "https://my-channel.git"))
29023 %default-channels)))))
29025 (service cuirass-service-type
29026 (cuirass-configuration
29027 (specifications %cuirass-specs)))
29030 To build the @code{linux-libre} package defined by the default Guix
29031 channel, one can use the following configuration.
29034 (define %cuirass-specs
29035 #~(list (specification
29037 (build '(packages "linux-libre")))))
29039 (service cuirass-service-type
29040 (cuirass-configuration
29041 (specifications %cuirass-specs)))
29044 The other configuration possibilities, as well as the specification
29045 record itself are described in the Cuirass manual
29046 (@pxref{Specifications,,, cuirass, Cuirass}).
29048 While information related to build jobs is located directly in the
29049 specifications, global settings for the @command{cuirass} process are
29050 accessible in other @code{cuirass-configuration} fields.
29052 @deftp {Data Type} cuirass-configuration
29053 Data type representing the configuration of Cuirass.
29056 @item @code{cuirass} (default: @code{cuirass})
29057 The Cuirass package to use.
29059 @item @code{log-file} (default: @code{"/var/log/cuirass.log"})
29060 Location of the log file.
29062 @item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
29063 Location of the log file used by the web interface.
29065 @item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
29066 Location of the repository cache.
29068 @item @code{user} (default: @code{"cuirass"})
29069 Owner of the @code{cuirass} process.
29071 @item @code{group} (default: @code{"cuirass"})
29072 Owner's group of the @code{cuirass} process.
29074 @item @code{interval} (default: @code{60})
29075 Number of seconds between the poll of the repositories followed by the
29078 @item @code{parameters} (default: @code{#f})
29079 Read parameters from the given @var{parameters} file. The supported
29080 parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
29082 @item @code{remote-server} (default: @code{#f})
29083 A @code{cuirass-remote-server-configuration} record to use the build
29084 remote mechanism or @code{#f} to use the default build mechanism.
29086 @item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
29087 Use @var{database} as the database containing the jobs and the past
29088 build results. Since Cuirass uses PostgreSQL as a database engine,
29089 @var{database} must be a string such as @code{"dbname=cuirass
29092 @item @code{port} (default: @code{8081})
29093 Port number used by the HTTP server.
29095 @item @code{host} (default: @code{"localhost"})
29096 Listen on the network interface for @var{host}. The default is to
29097 accept connections from localhost.
29099 @item @code{specifications} (default: @code{#~'()})
29100 A gexp (@pxref{G-Expressions}) that evaluates to a list of
29101 specifications records. The specification record is described in the
29102 Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
29104 @item @code{use-substitutes?} (default: @code{#f})
29105 This allows using substitutes to avoid building every dependencies of a job
29108 @item @code{one-shot?} (default: @code{#f})
29109 Only evaluate specifications and build derivations once.
29111 @item @code{fallback?} (default: @code{#f})
29112 When substituting a pre-built binary fails, fall back to building
29115 @item @code{extra-options} (default: @code{'()})
29116 Extra options to pass when running the Cuirass processes.
29121 @cindex remote build
29122 @subsubheading Cuirass remote building
29124 Cuirass supports two mechanisms to build derivations.
29127 @item Using the local Guix daemon.
29128 This is the default build mechanism. Once the build jobs are
29129 evaluated, they are sent to the local Guix daemon. Cuirass then
29130 listens to the Guix daemon output to detect the various build events.
29132 @item Using the remote build mechanism.
29133 The build jobs are not submitted to the local Guix daemon. Instead, a
29134 remote server dispatches build requests to the connect remote workers,
29135 according to the build priorities.
29139 To enable this build mode a @code{cuirass-remote-server-configuration}
29140 record must be passed as @code{remote-server} argument of the
29141 @code{cuirass-configuration} record. The
29142 @code{cuirass-remote-server-configuration} record is described below.
29144 This build mode scales way better than the default build mode. This is
29145 the build mode that is used on the GNU Guix build farm at
29146 @url{https://ci.guix.gnu.org}. It should be preferred when using
29147 Cuirass to build large amount of packages.
29149 @deftp {Data Type} cuirass-remote-server-configuration
29150 Data type representing the configuration of the Cuirass remote-server.
29153 @item @code{backend-port} (default: @code{5555})
29154 The TCP port for communicating with @code{remote-worker} processes
29155 using ZMQ. It defaults to @code{5555}.
29157 @item @code{log-port} (default: @code{5556})
29158 The TCP port of the log server. It defaults to @code{5556}.
29160 @item @code{publish-port} (default: @code{5557})
29161 The TCP port of the publish server. It defaults to @code{5557}.
29163 @item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
29164 Location of the log file.
29166 @item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
29167 Use @var{cache} directory to cache build log files.
29169 @item @code{trigger-url} (default: @code{#f})
29170 Once a substitute is successfully fetched, trigger substitute baking at
29173 @item @code{publish?} (default: @code{#t})
29174 If set to false, do not start a publish server and ignore the
29175 @code{publish-port} argument. This can be useful if there is already a
29176 standalone publish server standing next to the remote server.
29178 @item @code{public-key}
29179 @item @code{private-key}
29180 Use the specific @var{file}s as the public/private key pair used to sign
29181 the store items being published.
29186 At least one remote worker must also be started on any machine of the
29187 local network to actually perform the builds and report their status.
29189 @deftp {Data Type} cuirass-remote-worker-configuration
29190 Data type representing the configuration of the Cuirass remote-worker.
29193 @item @code{cuirass} (default: @code{cuirass})
29194 The Cuirass package to use.
29196 @item @code{workers} (default: @code{1})
29197 Start @var{workers} parallel workers.
29199 @item @code{server} (default: @code{#f})
29200 Do not use Avahi discovery and connect to the given @code{server} IP
29203 @item @code{systems} (default: @code{(list (%current-system))})
29204 Only request builds for the given @var{systems}.
29206 @item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
29207 Location of the log file.
29209 @item @code{publish-port} (default: @code{5558})
29210 The TCP port of the publish server. It defaults to @code{5558}.
29212 @item @code{substitute-urls} (default: @code{%default-substitute-urls})
29213 The list of URLs where to look for substitutes by default.
29215 @item @code{public-key}
29216 @item @code{private-key}
29217 Use the specific @var{file}s as the public/private key pair used to sign
29218 the store items being published.
29223 @subsubheading Laminar
29225 @uref{https://laminar.ohwg.net/, Laminar} is a lightweight and modular
29226 Continuous Integration service. It doesn't have a configuration web UI
29227 instead uses version-controllable configuration files and scripts.
29229 Laminar encourages the use of existing tools such as bash and cron
29230 instead of reinventing them.
29232 @defvr {Scheme Procedure} laminar-service-type
29233 The type of the Laminar service. Its value must be a
29234 @code{laminar-configuration} object, as described below.
29236 All configuration values have defaults, a minimal configuration to get
29237 Laminar running is shown below. By default, the web interface is
29238 available on port 8080.
29241 (service laminar-service-type)
29245 @deftp {Data Type} laminar-configuration
29246 Data type representing the configuration of Laminar.
29249 @item @code{laminar} (default: @code{laminar})
29250 The Laminar package to use.
29252 @item @code{home-directory} (default: @code{"/var/lib/laminar"})
29253 The directory for job configurations and run directories.
29255 @item @code{bind-http} (default: @code{"*:8080"})
29256 The interface/port or unix socket on which laminard should listen for
29257 incoming connections to the web frontend.
29259 @item @code{bind-rpc} (default: @code{"unix-abstract:laminar"})
29260 The interface/port or unix socket on which laminard should listen for
29261 incoming commands such as build triggers.
29263 @item @code{title} (default: @code{"Laminar"})
29264 The page title to show in the web frontend.
29266 @item @code{keep-rundirs} (default: @code{0})
29267 Set to an integer defining how many rundirs to keep per job. The
29268 lowest-numbered ones will be deleted. The default is 0, meaning all run
29269 dirs will be immediately deleted.
29271 @item @code{archive-url} (default: @code{#f})
29272 The web frontend served by laminard will use this URL to form links to
29273 artefacts archived jobs.
29275 @item @code{base-url} (default: @code{#f})
29276 Base URL to use for links to laminar itself.
29281 @node Power Management Services
29282 @subsection Power Management Services
29285 @cindex power management with TLP
29286 @subsubheading TLP daemon
29288 The @code{(gnu services pm)} module provides a Guix service definition
29289 for the Linux power management tool TLP.
29291 TLP enables various powersaving modes in userspace and kernel.
29292 Contrary to @code{upower-service}, it is not a passive,
29293 monitoring tool, as it will apply custom settings each time a new power
29294 source is detected. More information can be found at
29295 @uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
29297 @deffn {Scheme Variable} tlp-service-type
29298 The service type for the TLP tool. The default settings are optimised
29299 for battery life on most systems, but you can tweak them to your heart's
29300 content by adding a valid @code{tlp-configuration}:
29302 (service tlp-service-type
29304 (cpu-scaling-governor-on-ac (list "performance"))
29305 (sched-powersave-on-bat? #t)))
29309 Each parameter definition is preceded by its type; for example,
29310 @samp{boolean foo} indicates that the @code{foo} parameter
29311 should be specified as a boolean. Types starting with
29312 @code{maybe-} denote parameters that won't show up in TLP config file
29313 when their value is @code{'disabled}.
29315 @c The following documentation was initially generated by
29316 @c (generate-tlp-documentation) in (gnu services pm). Manually maintained
29317 @c documentation is better, so we shouldn't hesitate to edit below as
29318 @c needed. However if the change you want to make to this documentation
29319 @c can be done in an automated way, it's probably easier to change
29320 @c (generate-documentation) than to make it below and have to deal with
29321 @c the churn as TLP updates.
29323 Available @code{tlp-configuration} fields are:
29325 @deftypevr {@code{tlp-configuration} parameter} package tlp
29330 @deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable?
29331 Set to true if you wish to enable TLP.
29333 Defaults to @samp{#t}.
29337 @deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode
29338 Default mode when no power supply can be detected. Alternatives are AC
29341 Defaults to @samp{"AC"}.
29345 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac
29346 Number of seconds Linux kernel has to wait after the disk goes idle,
29347 before syncing on AC.
29349 Defaults to @samp{0}.
29353 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat
29354 Same as @code{disk-idle-ac} but on BAT mode.
29356 Defaults to @samp{2}.
29360 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac
29361 Dirty pages flushing periodicity, expressed in seconds.
29363 Defaults to @samp{15}.
29367 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat
29368 Same as @code{max-lost-work-secs-on-ac} but on BAT mode.
29370 Defaults to @samp{60}.
29374 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac
29375 CPU frequency scaling governor on AC mode. With intel_pstate driver,
29376 alternatives are powersave and performance. With acpi-cpufreq driver,
29377 alternatives are ondemand, powersave, performance and conservative.
29379 Defaults to @samp{disabled}.
29383 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat
29384 Same as @code{cpu-scaling-governor-on-ac} but on BAT mode.
29386 Defaults to @samp{disabled}.
29390 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac
29391 Set the min available frequency for the scaling governor on AC.
29393 Defaults to @samp{disabled}.
29397 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac
29398 Set the max available frequency for the scaling governor on AC.
29400 Defaults to @samp{disabled}.
29404 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat
29405 Set the min available frequency for the scaling governor on BAT.
29407 Defaults to @samp{disabled}.
29411 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat
29412 Set the max available frequency for the scaling governor on BAT.
29414 Defaults to @samp{disabled}.
29418 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac
29419 Limit the min P-state to control the power dissipation of the CPU, in AC
29420 mode. Values are stated as a percentage of the available performance.
29422 Defaults to @samp{disabled}.
29426 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac
29427 Limit the max P-state to control the power dissipation of the CPU, in AC
29428 mode. Values are stated as a percentage of the available performance.
29430 Defaults to @samp{disabled}.
29434 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat
29435 Same as @code{cpu-min-perf-on-ac} on BAT mode.
29437 Defaults to @samp{disabled}.
29441 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat
29442 Same as @code{cpu-max-perf-on-ac} on BAT mode.
29444 Defaults to @samp{disabled}.
29448 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac?
29449 Enable CPU turbo boost feature on AC mode.
29451 Defaults to @samp{disabled}.
29455 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat?
29456 Same as @code{cpu-boost-on-ac?} on BAT mode.
29458 Defaults to @samp{disabled}.
29462 @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac?
29463 Allow Linux kernel to minimize the number of CPU cores/hyper-threads
29464 used under light load conditions.
29466 Defaults to @samp{#f}.
29470 @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat?
29471 Same as @code{sched-powersave-on-ac?} but on BAT mode.
29473 Defaults to @samp{#t}.
29477 @deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog?
29478 Enable Linux kernel NMI watchdog.
29480 Defaults to @samp{#f}.
29484 @deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls
29485 For Linux kernels with PHC patch applied, change CPU voltages. An
29486 example value would be @samp{"F:V F:V F:V F:V"}.
29488 Defaults to @samp{disabled}.
29492 @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac
29493 Set CPU performance versus energy saving policy on AC@. Alternatives are
29494 performance, normal, powersave.
29496 Defaults to @samp{"performance"}.
29500 @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat
29501 Same as @code{energy-perf-policy-ac} but on BAT mode.
29503 Defaults to @samp{"powersave"}.
29507 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices
29512 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac
29513 Hard disk advanced power management level.
29517 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat
29518 Same as @code{disk-apm-bat} but on BAT mode.
29522 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac
29523 Hard disk spin down timeout. One value has to be specified for each
29524 declared hard disk.
29526 Defaults to @samp{disabled}.
29530 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat
29531 Same as @code{disk-spindown-timeout-on-ac} but on BAT mode.
29533 Defaults to @samp{disabled}.
29537 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched
29538 Select IO scheduler for disk devices. One value has to be specified for
29539 each declared hard disk. Example alternatives are cfq, deadline and
29542 Defaults to @samp{disabled}.
29546 @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac
29547 SATA aggressive link power management (ALPM) level. Alternatives are
29548 min_power, medium_power, max_performance.
29550 Defaults to @samp{"max_performance"}.
29554 @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat
29555 Same as @code{sata-linkpwr-ac} but on BAT mode.
29557 Defaults to @samp{"min_power"}.
29561 @deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist
29562 Exclude specified SATA host devices for link power management.
29564 Defaults to @samp{disabled}.
29568 @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac?
29569 Enable Runtime Power Management for AHCI controller and disks on AC
29572 Defaults to @samp{disabled}.
29576 @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat?
29577 Same as @code{ahci-runtime-pm-on-ac} on BAT mode.
29579 Defaults to @samp{disabled}.
29583 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout
29584 Seconds of inactivity before disk is suspended.
29586 Defaults to @samp{15}.
29590 @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac
29591 PCI Express Active State Power Management level. Alternatives are
29592 default, performance, powersave.
29594 Defaults to @samp{"performance"}.
29598 @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat
29599 Same as @code{pcie-aspm-ac} but on BAT mode.
29601 Defaults to @samp{"powersave"}.
29605 @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac
29606 Radeon graphics clock speed level. Alternatives are low, mid, high,
29609 Defaults to @samp{"high"}.
29613 @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat
29614 Same as @code{radeon-power-ac} but on BAT mode.
29616 Defaults to @samp{"low"}.
29620 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac
29621 Radeon dynamic power management method (DPM). Alternatives are battery,
29624 Defaults to @samp{"performance"}.
29628 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat
29629 Same as @code{radeon-dpm-state-ac} but on BAT mode.
29631 Defaults to @samp{"battery"}.
29635 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac
29636 Radeon DPM performance level. Alternatives are auto, low, high.
29638 Defaults to @samp{"auto"}.
29642 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat
29643 Same as @code{radeon-dpm-perf-ac} but on BAT mode.
29645 Defaults to @samp{"auto"}.
29649 @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac?
29650 Wifi power saving mode.
29652 Defaults to @samp{#f}.
29656 @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat?
29657 Same as @code{wifi-power-ac?} but on BAT mode.
29659 Defaults to @samp{#t}.
29663 @deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable?
29664 Disable wake on LAN.
29666 Defaults to @samp{#t}.
29670 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac
29671 Timeout duration in seconds before activating audio power saving on
29672 Intel HDA and AC97 devices. A value of 0 disables power saving.
29674 Defaults to @samp{0}.
29678 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat
29679 Same as @code{sound-powersave-ac} but on BAT mode.
29681 Defaults to @samp{1}.
29685 @deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller?
29686 Disable controller in powersaving mode on Intel HDA devices.
29688 Defaults to @samp{#t}.
29692 @deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat?
29693 Enable optical drive in UltraBay/MediaBay on BAT mode. Drive can be
29694 powered on again by releasing (and reinserting) the eject lever or by
29695 pressing the disc eject button on newer models.
29697 Defaults to @samp{#f}.
29701 @deftypevr {@code{tlp-configuration} parameter} string bay-device
29702 Name of the optical drive device to power off.
29704 Defaults to @samp{"sr0"}.
29708 @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac
29709 Runtime Power Management for PCI(e) bus devices. Alternatives are on
29712 Defaults to @samp{"on"}.
29716 @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat
29717 Same as @code{runtime-pm-ac} but on BAT mode.
29719 Defaults to @samp{"auto"}.
29723 @deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all?
29724 Runtime Power Management for all PCI(e) bus devices, except blacklisted
29727 Defaults to @samp{#t}.
29731 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist
29732 Exclude specified PCI(e) device addresses from Runtime Power Management.
29734 Defaults to @samp{disabled}.
29738 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist
29739 Exclude PCI(e) devices assigned to the specified drivers from Runtime
29744 @deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend?
29745 Enable USB autosuspend feature.
29747 Defaults to @samp{#t}.
29751 @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist
29752 Exclude specified devices from USB autosuspend.
29754 Defaults to @samp{disabled}.
29758 @deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan?
29759 Exclude WWAN devices from USB autosuspend.
29761 Defaults to @samp{#t}.
29765 @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist
29766 Include specified devices into USB autosuspend, even if they are already
29767 excluded by the driver or via @code{usb-blacklist-wwan?}.
29769 Defaults to @samp{disabled}.
29773 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown?
29774 Enable USB autosuspend before shutdown.
29776 Defaults to @samp{disabled}.
29780 @deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup?
29781 Restore radio device state (bluetooth, wifi, wwan) from previous
29782 shutdown on system startup.
29784 Defaults to @samp{#f}.
29789 @cindex CPU frequency scaling with thermald
29790 @subsubheading Thermald daemon
29792 The @code{(gnu services pm)} module provides an interface to
29793 thermald, a CPU frequency scaling service which helps prevent overheating.
29795 @defvr {Scheme Variable} thermald-service-type
29796 This is the service type for
29797 @uref{https://01.org/linux-thermal-daemon/, thermald}, the Linux
29798 Thermal Daemon, which is responsible for controlling the thermal state
29799 of processors and preventing overheating.
29802 @deftp {Data Type} thermald-configuration
29803 Data type representing the configuration of @code{thermald-service-type}.
29806 @item @code{ignore-cpuid-check?} (default: @code{#f})
29807 Ignore cpuid check for supported CPU models.
29809 @item @code{thermald} (default: @var{thermald})
29810 Package object of thermald.
29815 @node Audio Services
29816 @subsection Audio Services
29818 The @code{(gnu services audio)} module provides a service to start MPD
29819 (the Music Player Daemon).
29822 @subsubheading Music Player Daemon
29824 The Music Player Daemon (MPD) is a service that can play music while
29825 being controlled from the local machine or over the network by a variety
29828 The following example shows how one might run @code{mpd} as user
29829 @code{"bob"} on port @code{6666}. It uses pulseaudio for output.
29832 (service mpd-service-type
29838 @defvr {Scheme Variable} mpd-service-type
29839 The service type for @command{mpd}
29842 @deftp {Data Type} mpd-configuration
29843 Data type representing the configuration of @command{mpd}.
29846 @item @code{user} (default: @code{"mpd"})
29847 The user to run mpd as.
29849 @item @code{music-dir} (default: @code{"~/Music"})
29850 The directory to scan for music files.
29852 @item @code{playlist-dir} (default: @code{"~/.mpd/playlists"})
29853 The directory to store playlists.
29855 @item @code{db-file} (default: @code{"~/.mpd/tag_cache"})
29856 The location of the music database.
29858 @item @code{state-file} (default: @code{"~/.mpd/state"})
29859 The location of the file that stores current MPD's state.
29861 @item @code{sticker-file} (default: @code{"~/.mpd/sticker.sql"})
29862 The location of the sticker database.
29864 @item @code{port} (default: @code{"6600"})
29865 The port to run mpd on.
29867 @item @code{address} (default: @code{"any"})
29868 The address that mpd will bind to. To use a Unix domain socket,
29869 an absolute path can be specified here.
29871 @item @code{outputs} (default: @code{"(list (mpd-output))"})
29872 The audio outputs that MPD can use. By default this is a single output using pulseaudio.
29877 @deftp {Data Type} mpd-output
29878 Data type representing an @command{mpd} audio output.
29881 @item @code{name} (default: @code{"MPD"})
29882 The name of the audio output.
29884 @item @code{type} (default: @code{"pulse"})
29885 The type of audio output.
29887 @item @code{enabled?} (default: @code{#t})
29888 Specifies whether this audio output is enabled when MPD is started. By
29889 default, all audio outputs are enabled. This is just the default
29890 setting when there is no state file; with a state file, the previous
29893 @item @code{tags?} (default: @code{#t})
29894 If set to @code{#f}, then MPD will not send tags to this output. This
29895 is only useful for output plugins that can receive tags, for example the
29896 @code{httpd} output plugin.
29898 @item @code{always-on?} (default: @code{#f})
29899 If set to @code{#t}, then MPD attempts to keep this audio output always
29900 open. This may be useful for streaming servers, when you don’t want to
29901 disconnect all listeners even when playback is accidentally stopped.
29903 @item @code{mixer-type}
29904 This field accepts a symbol that specifies which mixer should be used
29905 for this audio output: the @code{hardware} mixer, the @code{software}
29906 mixer, the @code{null} mixer (allows setting the volume, but with no
29907 effect; this can be used as a trick to implement an external mixer
29908 External Mixer) or no mixer (@code{none}).
29910 @item @code{extra-options} (default: @code{'()})
29911 An association list of option symbols to string values to be appended to
29912 the audio output configuration.
29917 The following example shows a configuration of @code{mpd} that provides
29918 an HTTP audio streaming output.
29921 (service mpd-service-type
29929 `((encoder . "vorbis")
29930 (port . "8080"))))))))
29934 @node Virtualization Services
29935 @subsection Virtualization Services
29937 The @code{(gnu services virtualization)} module provides services for
29938 the libvirt and virtlog daemons, as well as other virtualization-related
29941 @subsubheading Libvirt daemon
29943 @code{libvirtd} is the server side daemon component of the libvirt
29944 virtualization management system. This daemon runs on host servers
29945 and performs required management tasks for virtualized guests.
29947 @deffn {Scheme Variable} libvirt-service-type
29948 This is the type of the @uref{https://libvirt.org, libvirt daemon}.
29949 Its value must be a @code{libvirt-configuration}.
29952 (service libvirt-service-type
29953 (libvirt-configuration
29954 (unix-sock-group "libvirt")
29955 (tls-port "16555")))
29959 @c Auto-generated with (generate-libvirt-documentation)
29960 Available @code{libvirt-configuration} fields are:
29962 @deftypevr {@code{libvirt-configuration} parameter} package libvirt
29967 @deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls?
29968 Flag listening for secure TLS connections on the public TCP/IP port.
29969 You must set @code{listen} for this to have any effect.
29971 It is necessary to setup a CA and issue server certificates before using
29974 Defaults to @samp{#t}.
29978 @deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp?
29979 Listen for unencrypted TCP connections on the public TCP/IP port. You must
29980 set @code{listen} for this to have any effect.
29982 Using the TCP socket requires SASL authentication by default. Only SASL
29983 mechanisms which support data encryption are allowed. This is
29984 DIGEST_MD5 and GSSAPI (Kerberos5).
29986 Defaults to @samp{#f}.
29990 @deftypevr {@code{libvirt-configuration} parameter} string tls-port
29991 Port for accepting secure TLS connections. This can be a port number,
29994 Defaults to @samp{"16514"}.
29998 @deftypevr {@code{libvirt-configuration} parameter} string tcp-port
29999 Port for accepting insecure TCP connections. This can be a port number,
30002 Defaults to @samp{"16509"}.
30006 @deftypevr {@code{libvirt-configuration} parameter} string listen-addr
30007 IP address or hostname used for client connections.
30009 Defaults to @samp{"0.0.0.0"}.
30013 @deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv?
30014 Flag toggling mDNS advertisement of the libvirt service.
30016 Alternatively can disable for all services on a host by stopping the
30019 Defaults to @samp{#f}.
30023 @deftypevr {@code{libvirt-configuration} parameter} string mdns-name
30024 Default mDNS advertisement name. This must be unique on the immediate
30027 Defaults to @samp{"Virtualization Host <hostname>"}.
30031 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group
30032 UNIX domain socket group ownership. This can be used to allow a
30033 'trusted' set of users access to management capabilities without
30036 Defaults to @samp{"root"}.
30040 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms
30041 UNIX socket permissions for the R/O socket. This is used for monitoring
30044 Defaults to @samp{"0777"}.
30048 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms
30049 UNIX socket permissions for the R/W socket. Default allows only root.
30050 If PolicyKit is enabled on the socket, the default will change to allow
30051 everyone (eg, 0777)
30053 Defaults to @samp{"0770"}.
30057 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms
30058 UNIX socket permissions for the admin socket. Default allows only owner
30059 (root), do not change it unless you are sure to whom you are exposing
30062 Defaults to @samp{"0777"}.
30066 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir
30067 The directory in which sockets will be found/created.
30069 Defaults to @samp{"/var/run/libvirt"}.
30073 @deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro
30074 Authentication scheme for UNIX read-only sockets. By default socket
30075 permissions allow anyone to connect
30077 Defaults to @samp{"polkit"}.
30081 @deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw
30082 Authentication scheme for UNIX read-write sockets. By default socket
30083 permissions only allow root. If PolicyKit support was compiled into
30084 libvirt, the default will be to use 'polkit' auth.
30086 Defaults to @samp{"polkit"}.
30090 @deftypevr {@code{libvirt-configuration} parameter} string auth-tcp
30091 Authentication scheme for TCP sockets. If you don't enable SASL, then
30092 all TCP traffic is cleartext. Don't do this outside of a dev/test
30095 Defaults to @samp{"sasl"}.
30099 @deftypevr {@code{libvirt-configuration} parameter} string auth-tls
30100 Authentication scheme for TLS sockets. TLS sockets already have
30101 encryption provided by the TLS layer, and limited authentication is done
30104 It is possible to make use of any SASL authentication mechanism as well,
30105 by using 'sasl' for this option
30107 Defaults to @samp{"none"}.
30111 @deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers
30112 API access control scheme.
30114 By default an authenticated user is allowed access to all APIs. Access
30115 drivers can place restrictions on this.
30117 Defaults to @samp{()}.
30121 @deftypevr {@code{libvirt-configuration} parameter} string key-file
30122 Server key file path. If set to an empty string, then no private key is
30125 Defaults to @samp{""}.
30129 @deftypevr {@code{libvirt-configuration} parameter} string cert-file
30130 Server key file path. If set to an empty string, then no certificate is
30133 Defaults to @samp{""}.
30137 @deftypevr {@code{libvirt-configuration} parameter} string ca-file
30138 Server key file path. If set to an empty string, then no CA certificate
30141 Defaults to @samp{""}.
30145 @deftypevr {@code{libvirt-configuration} parameter} string crl-file
30146 Certificate revocation list path. If set to an empty string, then no
30149 Defaults to @samp{""}.
30153 @deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert
30154 Disable verification of our own server certificates.
30156 When libvirtd starts it performs some sanity checks against its own
30159 Defaults to @samp{#f}.
30163 @deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert
30164 Disable verification of client certificates.
30166 Client certificate verification is the primary authentication mechanism.
30167 Any client which does not present a certificate signed by the CA will be
30170 Defaults to @samp{#f}.
30174 @deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list
30175 Whitelist of allowed x509 Distinguished Name.
30177 Defaults to @samp{()}.
30181 @deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames
30182 Whitelist of allowed SASL usernames. The format for username depends on
30183 the SASL authentication mechanism.
30185 Defaults to @samp{()}.
30189 @deftypevr {@code{libvirt-configuration} parameter} string tls-priority
30190 Override the compile time default TLS priority string. The default is
30191 usually @samp{"NORMAL"} unless overridden at build time. Only set this is it
30192 is desired for libvirt to deviate from the global default settings.
30194 Defaults to @samp{"NORMAL"}.
30198 @deftypevr {@code{libvirt-configuration} parameter} integer max-clients
30199 Maximum number of concurrent client connections to allow over all
30202 Defaults to @samp{5000}.
30206 @deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients
30207 Maximum length of queue of connections waiting to be accepted by the
30208 daemon. Note, that some protocols supporting retransmission may obey
30209 this so that a later reattempt at connection succeeds.
30211 Defaults to @samp{1000}.
30215 @deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients
30216 Maximum length of queue of accepted but not yet authenticated clients.
30217 Set this to zero to turn this feature off
30219 Defaults to @samp{20}.
30223 @deftypevr {@code{libvirt-configuration} parameter} integer min-workers
30224 Number of workers to start up initially.
30226 Defaults to @samp{5}.
30230 @deftypevr {@code{libvirt-configuration} parameter} integer max-workers
30231 Maximum number of worker threads.
30233 If the number of active clients exceeds @code{min-workers}, then more
30234 threads are spawned, up to max_workers limit. Typically you'd want
30235 max_workers to equal maximum number of clients allowed.
30237 Defaults to @samp{20}.
30241 @deftypevr {@code{libvirt-configuration} parameter} integer prio-workers
30242 Number of priority workers. If all workers from above pool are stuck,
30243 some calls marked as high priority (notably domainDestroy) can be
30244 executed in this pool.
30246 Defaults to @samp{5}.
30250 @deftypevr {@code{libvirt-configuration} parameter} integer max-requests
30251 Total global limit on concurrent RPC calls.
30253 Defaults to @samp{20}.
30257 @deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests
30258 Limit on concurrent requests from a single client connection. To avoid
30259 one client monopolizing the server this should be a small fraction of
30260 the global max_requests and max_workers parameter.
30262 Defaults to @samp{5}.
30266 @deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers
30267 Same as @code{min-workers} but for the admin interface.
30269 Defaults to @samp{1}.
30273 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers
30274 Same as @code{max-workers} but for the admin interface.
30276 Defaults to @samp{5}.
30280 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients
30281 Same as @code{max-clients} but for the admin interface.
30283 Defaults to @samp{5}.
30287 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients
30288 Same as @code{max-queued-clients} but for the admin interface.
30290 Defaults to @samp{5}.
30294 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests
30295 Same as @code{max-client-requests} but for the admin interface.
30297 Defaults to @samp{5}.
30301 @deftypevr {@code{libvirt-configuration} parameter} integer log-level
30302 Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
30304 Defaults to @samp{3}.
30308 @deftypevr {@code{libvirt-configuration} parameter} string log-filters
30311 A filter allows to select a different logging level for a given category
30312 of logs. The format for a filter is one of:
30323 where @code{name} is a string which is matched against the category
30324 given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
30325 file, e.g., @samp{"remote"}, @samp{"qemu"}, or @samp{"util.json"} (the
30326 name in the filter can be a substring of the full category name, in
30327 order to match multiple similar categories), the optional @samp{"+"}
30328 prefix tells libvirt to log stack trace for each message matching name,
30329 and @code{x} is the minimal level where matching messages should be
30347 Multiple filters can be defined in a single filters statement, they just
30348 need to be separated by spaces.
30350 Defaults to @samp{"3:remote 4:event"}.
30354 @deftypevr {@code{libvirt-configuration} parameter} string log-outputs
30357 An output is one of the places to save logging information. The format
30358 for an output can be:
30362 output goes to stderr
30364 @item x:syslog:name
30365 use syslog for the output and use the given name as the ident
30367 @item x:file:file_path
30368 output to a file, with the given filepath
30371 output to journald logging system
30375 In all case the x prefix is the minimal level, acting as a filter
30392 Multiple outputs can be defined, they just need to be separated by
30395 Defaults to @samp{"3:stderr"}.
30399 @deftypevr {@code{libvirt-configuration} parameter} integer audit-level
30400 Allows usage of the auditing subsystem to be altered
30404 0: disable all auditing
30407 1: enable auditing, only if enabled on host
30410 2: enable auditing, and exit if disabled on host.
30414 Defaults to @samp{1}.
30418 @deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging
30419 Send audit messages via libvirt logging infrastructure.
30421 Defaults to @samp{#f}.
30425 @deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid
30426 Host UUID@. UUID must not have all digits be the same.
30428 Defaults to @samp{""}.
30432 @deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source
30433 Source to read host UUID.
30437 @code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid}
30440 @code{machine-id}: fetch the UUID from @code{/etc/machine-id}
30444 If @code{dmidecode} does not provide a valid UUID a temporary UUID will
30447 Defaults to @samp{"smbios"}.
30451 @deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval
30452 A keepalive message is sent to a client after @code{keepalive_interval}
30453 seconds of inactivity to check if the client is still responding. If
30454 set to -1, libvirtd will never send keepalive requests; however clients
30455 can still send them and the daemon will send responses.
30457 Defaults to @samp{5}.
30461 @deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count
30462 Maximum number of keepalive messages that are allowed to be sent to the
30463 client without getting any response before the connection is considered
30466 In other words, the connection is automatically closed approximately
30467 after @code{keepalive_interval * (keepalive_count + 1)} seconds since
30468 the last message received from the client. When @code{keepalive-count}
30469 is set to 0, connections will be automatically closed after
30470 @code{keepalive-interval} seconds of inactivity without sending any
30471 keepalive messages.
30473 Defaults to @samp{5}.
30477 @deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval
30478 Same as above but for admin interface.
30480 Defaults to @samp{5}.
30484 @deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count
30485 Same as above but for admin interface.
30487 Defaults to @samp{5}.
30491 @deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout
30492 Timeout for Open vSwitch calls.
30494 The @code{ovs-vsctl} utility is used for the configuration and its
30495 timeout option is set by default to 5 seconds to avoid potential
30496 infinite waits blocking libvirt.
30498 Defaults to @samp{5}.
30502 @c %end of autogenerated docs
30504 @subsubheading Virtlog daemon
30505 The virtlogd service is a server side daemon component of libvirt that is
30506 used to manage logs from virtual machine consoles.
30508 This daemon is not used directly by libvirt client applications, rather it
30509 is called on their behalf by @code{libvirtd}. By maintaining the logs in a
30510 standalone daemon, the main @code{libvirtd} daemon can be restarted without
30511 risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec()
30512 itself upon receiving @code{SIGUSR1}, to allow live upgrades without downtime.
30514 @deffn {Scheme Variable} virtlog-service-type
30515 This is the type of the virtlog daemon.
30516 Its value must be a @code{virtlog-configuration}.
30519 (service virtlog-service-type
30520 (virtlog-configuration
30521 (max-clients 1000)))
30525 @deftypevr {@code{virtlog-configuration} parameter} integer log-level
30526 Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
30528 Defaults to @samp{3}.
30532 @deftypevr {@code{virtlog-configuration} parameter} string log-filters
30535 A filter allows to select a different logging level for a given category
30536 of logs The format for a filter is one of:
30547 where @code{name} is a string which is matched against the category
30548 given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
30549 file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
30550 be a substring of the full category name, in order to match multiple
30551 similar categories), the optional "+" prefix tells libvirt to log stack
30552 trace for each message matching name, and @code{x} is the minimal level
30553 where matching messages should be logged:
30570 Multiple filters can be defined in a single filters statement, they just
30571 need to be separated by spaces.
30573 Defaults to @samp{"3:remote 4:event"}.
30577 @deftypevr {@code{virtlog-configuration} parameter} string log-outputs
30580 An output is one of the places to save logging information The format
30581 for an output can be:
30585 output goes to stderr
30587 @item x:syslog:name
30588 use syslog for the output and use the given name as the ident
30590 @item x:file:file_path
30591 output to a file, with the given filepath
30594 output to journald logging system
30598 In all case the x prefix is the minimal level, acting as a filter
30615 Multiple outputs can be defined, they just need to be separated by
30618 Defaults to @samp{"3:stderr"}.
30622 @deftypevr {@code{virtlog-configuration} parameter} integer max-clients
30623 Maximum number of concurrent client connections to allow over all
30626 Defaults to @samp{1024}.
30630 @deftypevr {@code{virtlog-configuration} parameter} integer max-size
30631 Maximum file size before rolling over.
30633 Defaults to @samp{2MB}
30637 @deftypevr {@code{virtlog-configuration} parameter} integer max-backups
30638 Maximum number of backup files to keep.
30640 Defaults to @samp{3}
30644 @anchor{transparent-emulation-qemu}
30645 @subsubheading Transparent Emulation with QEMU
30648 @cindex @code{binfmt_misc}
30649 @code{qemu-binfmt-service-type} provides support for transparent
30650 emulation of program binaries built for different architectures---e.g.,
30651 it allows you to transparently execute an ARMv7 program on an x86_64
30652 machine. It achieves this by combining the @uref{https://www.qemu.org,
30653 QEMU} emulator and the @code{binfmt_misc} feature of the kernel Linux.
30654 This feature only allows you to emulate GNU/Linux on a different
30655 architecture, but see below for GNU/Hurd support.
30657 @defvr {Scheme Variable} qemu-binfmt-service-type
30658 This is the type of the QEMU/binfmt service for transparent emulation.
30659 Its value must be a @code{qemu-binfmt-configuration} object, which
30660 specifies the QEMU package to use as well as the architecture we want to
30664 (service qemu-binfmt-service-type
30665 (qemu-binfmt-configuration
30666 (platforms (lookup-qemu-platforms "arm" "aarch64"))))
30669 In this example, we enable transparent emulation for the ARM and aarch64
30670 platforms. Running @code{herd stop qemu-binfmt} turns it off, and
30671 running @code{herd start qemu-binfmt} turns it back on (@pxref{Invoking
30672 herd, the @command{herd} command,, shepherd, The GNU Shepherd Manual}).
30675 @deftp {Data Type} qemu-binfmt-configuration
30676 This is the configuration for the @code{qemu-binfmt} service.
30679 @item @code{platforms} (default: @code{'()})
30680 The list of emulated QEMU platforms. Each item must be a @dfn{platform
30681 object} as returned by @code{lookup-qemu-platforms} (see below).
30683 For example, let's suppose you're on an x86_64 machine and you have this
30687 (service qemu-binfmt-service-type
30688 (qemu-binfmt-configuration
30689 (platforms (lookup-qemu-platforms "arm"))))
30695 guix build -s armhf-linux inkscape
30699 and it will build Inkscape for ARMv7 @emph{as if it were a native
30700 build}, transparently using QEMU to emulate the ARMv7 CPU@. Pretty handy
30701 if you'd like to test a package build for an architecture you don't have
30704 @item @code{qemu} (default: @code{qemu})
30705 The QEMU package to use.
30709 @deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{}
30710 Return the list of QEMU platform objects corresponding to
30711 @var{platforms}@dots{}. @var{platforms} must be a list of strings
30712 corresponding to platform names, such as @code{"arm"}, @code{"sparc"},
30713 @code{"mips64el"}, and so on.
30716 @deffn {Scheme Procedure} qemu-platform? @var{obj}
30717 Return true if @var{obj} is a platform object.
30720 @deffn {Scheme Procedure} qemu-platform-name @var{platform}
30721 Return the name of @var{platform}---a string such as @code{"arm"}.
30725 @subsubheading QEMU Guest Agent
30729 The QEMU guest agent provides control over the emulated system to the
30730 host. The @code{qemu-guest-agent} service runs the agent on Guix
30731 guests. To control the agent from the host, open a socket by invoking
30732 QEMU with the following arguments:
30735 qemu-system-x86_64 \
30736 -chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \
30737 -device virtio-serial \
30738 -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \
30742 This creates a socket at @file{/tmp/qga.sock} on the host. Once the
30743 guest agent is running, you can issue commands with @code{socat}:
30746 $ guix shell socat -- socat unix-connect:/tmp/qga.sock stdio
30747 @{"execute": "guest-get-host-name"@}
30748 @{"return": @{"host-name": "guix"@}@}
30751 See @url{https://wiki.qemu.org/Features/GuestAgent,QEMU guest agent
30752 documentation} for more options and commands.
30754 @defvr {Scheme Variable} qemu-guest-agent-service-type
30755 Service type for the QEMU guest agent service.
30758 @deftp {Data Type} qemu-guest-agent-configuration
30759 Configuration for the @code{qemu-guest-agent} service.
30762 @item @code{qemu} (default: @code{qemu-minimal})
30763 The QEMU package to use.
30765 @item @code{device} (default: @code{""})
30766 File name of the device or socket the agent uses to communicate with the
30767 host. If empty, QEMU uses a default file name.
30772 @subsubheading The Hurd in a Virtual Machine
30774 @cindex @code{hurd}
30778 Service @code{hurd-vm} provides support for running GNU/Hurd in a
30779 virtual machine (VM), a so-called @dfn{childhurd}. This service is meant
30780 to be used on GNU/Linux and the given GNU/Hurd operating system
30781 configuration is cross-compiled. The virtual machine is a Shepherd
30782 service that can be referred to by the names @code{hurd-vm} and
30783 @code{childhurd} and be controlled with commands such as:
30787 herd stop childhurd
30790 When the service is running, you can view its console by connecting to
30791 it with a VNC client, for example with:
30794 guix shell tigervnc-client -- vncviewer localhost:5900
30797 The default configuration (see @code{hurd-vm-configuration} below)
30798 spawns a secure shell (SSH) server in your GNU/Hurd system, which QEMU
30799 (the virtual machine emulator) redirects to port 10222 on the host.
30800 Thus, you can connect over SSH to the childhurd with:
30803 ssh root@@localhost -p 10022
30806 The childhurd is volatile and stateless: it starts with a fresh root
30807 file system every time you restart it. By default though, all the files
30808 under @file{/etc/childhurd} on the host are copied as is to the root
30809 file system of the childhurd when it boots. This allows you to
30810 initialize ``secrets'' inside the VM: SSH host keys, authorized
30811 substitute keys, and so on---see the explanation of @code{secret-root}
30814 @defvr {Scheme Variable} hurd-vm-service-type
30815 This is the type of the Hurd in a Virtual Machine service. Its value
30816 must be a @code{hurd-vm-configuration} object, which specifies the
30817 operating system (@pxref{operating-system Reference}) and the disk size
30818 for the Hurd Virtual Machine, the QEMU package to use as well as the
30819 options for running it.
30824 (service hurd-vm-service-type
30825 (hurd-vm-configuration
30826 (disk-size (* 5000 (expt 2 20))) ;5G
30827 (memory-size 1024))) ;1024MiB
30830 would create a disk image big enough to build GNU@tie{}Hello, with some
30834 @deftp {Data Type} hurd-vm-configuration
30835 The data type representing the configuration for
30836 @code{hurd-vm-service-type}.
30839 @item @code{os} (default: @var{%hurd-vm-operating-system})
30840 The operating system to instantiate. This default is bare-bones with a
30841 permissive OpenSSH secure shell daemon listening on port 2222
30842 (@pxref{Networking Services, @code{openssh-service-type}}).
30844 @item @code{qemu} (default: @code{qemu-minimal})
30845 The QEMU package to use.
30847 @item @code{image} (default: @var{hurd-vm-disk-image})
30848 The procedure used to build the disk-image built from this
30851 @item @code{disk-size} (default: @code{'guess})
30852 The size of the disk image.
30854 @item @code{memory-size} (default: @code{512})
30855 The memory size of the Virtual Machine in mebibytes.
30857 @item @code{options} (default: @code{'("--snapshot")})
30858 The extra options for running QEMU.
30860 @item @code{id} (default: @code{#f})
30861 If set, a non-zero positive integer used to parameterize Childhurd
30862 instances. It is appended to the service's name,
30863 e.g. @code{childhurd1}.
30865 @item @code{net-options} (default: @var{hurd-vm-net-options})
30866 The procedure used to produce the list of QEMU networking options.
30868 By default, it produces
30871 '("--device" "rtl8139,netdev=net0"
30872 "--netdev" (string-append
30874 "hostfwd=tcp:127.0.0.1:@var{secrets-port}-:1004,"
30875 "hostfwd=tcp:127.0.0.1:@var{ssh-port}-:2222,"
30876 "hostfwd=tcp:127.0.0.1:@var{vnc-port}-:5900"))
30879 with forwarded ports:
30882 @var{secrets-port}: @code{(+ 11004 (* 1000 @var{ID}))}
30883 @var{ssh-port}: @code{(+ 10022 (* 1000 @var{ID}))}
30884 @var{vnc-port}: @code{(+ 15900 (* 1000 @var{ID}))}
30887 @item @code{secret-root} (default: @file{/etc/childhurd})
30888 The root directory with out-of-band secrets to be installed into the
30889 childhurd once it runs. Childhurds are volatile which means that on
30890 every startup, secrets such as the SSH host keys and Guix signing key
30893 If the @file{/etc/childhurd} directory does not exist, the
30894 @code{secret-service} running in the Childhurd will be sent an empty
30897 By default, the service automatically populates @file{/etc/childhurd}
30898 with the following non-volatile secrets, unless they already exist:
30901 /etc/childhurd/etc/guix/acl
30902 /etc/childhurd/etc/guix/signing-key.pub
30903 /etc/childhurd/etc/guix/signing-key.sec
30904 /etc/childhurd/etc/ssh/ssh_host_ed25519_key
30905 /etc/childhurd/etc/ssh/ssh_host_ecdsa_key
30906 /etc/childhurd/etc/ssh/ssh_host_ed25519_key.pub
30907 /etc/childhurd/etc/ssh/ssh_host_ecdsa_key.pub
30910 These files are automatically sent to the guest Hurd VM when it boots,
30911 including permissions.
30913 @cindex childhurd, offloading
30914 @cindex Hurd, offloading
30915 Having these files in place means that only a couple of things are
30916 missing to allow the host to offload @code{i586-gnu} builds to the
30921 Authorizing the childhurd's key on the host so that the host accepts
30922 build results coming from the childhurd, which can be done like so:
30925 guix archive --authorize < \
30926 /etc/childhurd/etc/guix/signing-key.pub
30930 Adding the childhurd to @file{/etc/guix/machines.scm} (@pxref{Daemon
30934 We're working towards making that happen automatically---get in touch
30935 with us at @email{guix-devel@@gnu.org} to discuss it!
30939 Note that by default the VM image is volatile, i.e., once stopped the
30940 contents are lost. If you want a stateful image instead, override the
30941 configuration's @code{image} and @code{options} without
30942 the @code{--snapshot} flag using something along these lines:
30945 (service hurd-vm-service-type
30946 (hurd-vm-configuration
30947 (image (const "/out/of/store/writable/hurd.img"))
30951 @subsubheading Ganeti
30956 This service is considered experimental. Configuration options may be changed
30957 in a backwards-incompatible manner, and not all features have been thorougly
30958 tested. Users of this service are encouraged to share their experience at
30959 @email{guix-devel@@gnu.org}.
30962 Ganeti is a virtual machine management system. It is designed to keep virtual
30963 machines running on a cluster of servers even in the event of hardware failures,
30964 and to make maintenance and recovery tasks easy. It consists of multiple
30965 services which are described later in this section. In addition to the Ganeti
30966 service, you will need the OpenSSH service (@pxref{Networking Services,
30967 @code{openssh-service-type}}), and update the @file{/etc/hosts} file
30968 (@pxref{operating-system Reference, @code{hosts-file}}) with the cluster name
30969 and address (or use a DNS server).
30971 All nodes participating in a Ganeti cluster should have the same Ganeti and
30972 @file{/etc/hosts} configuration. Here is an example configuration for a Ganeti
30973 cluster node that supports multiple storage backends, and installs the
30974 @code{debootstrap} and @code{guix} @dfn{OS providers}:
30977 (use-package-modules virtualization)
30978 (use-service-modules base ganeti networking ssh)
30981 (host-name "node1")
30982 (hosts-file (plain-file "hosts" (format #f "
30983 127.0.0.1 localhost
30986 192.168.1.200 ganeti.example.com
30987 192.168.1.201 node1.example.com node1
30988 192.168.1.202 node2.example.com node2
30991 ;; Install QEMU so we can use KVM-based instances, and LVM, DRBD and Ceph
30992 ;; in order to use the "plain", "drbd" and "rbd" storage backends.
30993 (packages (append (map specification->package
30994 '("qemu" "lvm2" "drbd-utils" "ceph"
30995 ;; Add the debootstrap and guix OS providers.
30996 "ganeti-instance-guix" "ganeti-instance-debootstrap"))
30999 (append (list (service static-networking-service-type
31000 (list (static-networking
31002 (list (network-address
31004 (value "192.168.1.201/24"))))
31006 (list (network-route
31007 (destination "default")
31008 (gateway "192.168.1.254"))))
31009 (name-servers '("192.168.1.252"
31010 "192.168.1.253")))))
31012 ;; Ganeti uses SSH to communicate between nodes.
31013 (service openssh-service-type
31014 (openssh-configuration
31015 (permit-root-login 'prohibit-password)))
31017 (service ganeti-service-type
31018 (ganeti-configuration
31019 ;; This list specifies allowed file system paths
31020 ;; for storing virtual machine images.
31021 (file-storage-paths '("/srv/ganeti/file-storage"))
31022 ;; This variable configures a single "variant" for
31023 ;; both Debootstrap and Guix that works with KVM.
31024 (os %default-ganeti-os))))
31028 Users are advised to read the
31029 @url{http://docs.ganeti.org/ganeti/master/html/admin.html,Ganeti
31030 administrators guide} to learn about the various cluster options and
31031 day-to-day operations. There is also a
31032 @url{https://guix.gnu.org/blog/2020/running-a-ganeti-cluster-on-guix/,blog post}
31033 describing how to configure and initialize a small cluster.
31035 @defvr {Scheme Variable} ganeti-service-type
31036 This is a service type that includes all the various services that Ganeti
31039 Its value is a @code{ganeti-configuration} object that defines the package
31040 to use for CLI operations, as well as configuration for the various daemons.
31041 Allowed file storage paths and available guest operating systems are also
31042 configured through this data type.
31045 @deftp {Data Type} ganeti-configuration
31046 The @code{ganeti} service takes the following configuration options:
31049 @item @code{ganeti} (default: @code{ganeti})
31050 The @code{ganeti} package to use. It will be installed to the system profile
31051 and make @command{gnt-cluster}, @command{gnt-instance}, etc available. Note
31052 that the value specified here does not affect the other services as each refer
31053 to a specific @code{ganeti} package (see below).
31055 @item @code{noded-configuration} (default: @code{(ganeti-noded-configuration)})
31056 @itemx @code{confd-configuration} (default: @code{(ganeti-confd-configuration)})
31057 @itemx @code{wconfd-configuration} (default: @code{(ganeti-wconfd-configuration)})
31058 @itemx @code{luxid-configuration} (default: @code{(ganeti-luxid-configuration)})
31059 @itemx @code{rapi-configuration} (default: @code{(ganeti-rapi-configuration)})
31060 @itemx @code{kvmd-configuration} (default: @code{(ganeti-kvmd-configuration)})
31061 @itemx @code{mond-configuration} (default: @code{(ganeti-mond-configuration)})
31062 @itemx @code{metad-configuration} (default: @code{(ganeti-metad-configuration)})
31063 @itemx @code{watcher-configuration} (default: @code{(ganeti-watcher-configuration)})
31064 @itemx @code{cleaner-configuration} (default: @code{(ganeti-cleaner-configuration)})
31066 These options control the various daemons and cron jobs that are distributed
31067 with Ganeti. The possible values for these are described in detail below.
31068 To override a setting, you must use the configuration type for that service:
31071 (service ganeti-service-type
31072 (ganeti-configuration
31073 (rapi-configuration
31074 (ganeti-rapi-configuration
31075 (interface "eth1"))))
31076 (watcher-configuration
31077 (ganeti-watcher-configuration
31078 (rapi-ip "10.0.0.1"))))
31081 @item @code{file-storage-paths} (default: @code{'()})
31082 List of allowed directories for file storage backend.
31084 @item @code{os} (default: @code{%default-ganeti-os})
31085 List of @code{<ganeti-os>} records.
31088 In essence @code{ganeti-service-type} is shorthand for declaring each service
31092 (service ganeti-noded-service-type)
31093 (service ganeti-confd-service-type)
31094 (service ganeti-wconfd-service-type)
31095 (service ganeti-luxid-service-type)
31096 (service ganeti-kvmd-service-type)
31097 (service ganeti-mond-service-type)
31098 (service ganeti-metad-service-type)
31099 (service ganeti-watcher-service-type)
31100 (service ganeti-cleaner-service-type)
31103 Plus a service extension for @code{etc-service-type} that configures the file
31104 storage backend and OS variants.
31108 @deftp {Data Type} ganeti-os
31109 This data type is suitable for passing to the @code{os} parameter of
31110 @code{ganeti-configuration}. It takes the following parameters:
31114 The name for this OS provider. It is only used to specify where the
31115 configuration ends up. Setting it to ``debootstrap'' will create
31116 @file{/etc/ganeti/instance-debootstrap}.
31118 @item @code{extension}
31119 The file extension for variants of this OS type. For example
31120 @file{.conf} or @file{.scm}.
31122 @item @code{variants} (default: @code{'()})
31123 List of @code{ganeti-os-variant} objects for this OS.
31128 @deftp {Data Type} ganeti-os-variant
31129 This is the data type for a Ganeti OS variant. It takes the following
31134 The name of this variant.
31136 @item @code{configuration}
31137 A configuration file for this variant.
31141 @defvr {Scheme Variable} %default-debootstrap-hooks
31142 This variable contains hooks to configure networking and the GRUB bootloader.
31145 @defvr {Scheme Variable} %default-debootstrap-extra-pkgs
31146 This variable contains a list of packages suitable for a fully-virtualized guest.
31149 @deftp {Data Type} debootstrap-configuration
31151 This data type creates configuration files suitable for the debootstrap OS provider.
31154 @item @code{hooks} (default: @code{%default-debootstrap-hooks})
31155 When not @code{#f}, this must be a G-expression that specifies a directory with
31156 scripts that will run when the OS is installed. It can also be a list of
31157 @code{(name . file-like)} pairs. For example:
31160 `((99-hello-world . ,(plain-file "#!/bin/sh\necho Hello, World")))
31163 That will create a directory with one executable named @code{99-hello-world}
31164 and run it every time this variant is installed. If set to @code{#f}, hooks
31165 in @file{/etc/ganeti/instance-debootstrap/hooks} will be used, if any.
31166 @item @code{proxy} (default: @code{#f})
31167 Optional HTTP proxy to use.
31168 @item @code{mirror} (default: @code{#f})
31169 The Debian mirror. Typically something like @code{http://ftp.no.debian.org/debian}.
31170 The default varies depending on the distribution.
31171 @item @code{arch} (default: @code{#f})
31172 The dpkg architecture. Set to @code{armhf} to debootstrap an ARMv7 instance
31173 on an AArch64 host. Default is to use the current system architecture.
31174 @item @code{suite} (default: @code{"stable"})
31175 When set, this must be a Debian distribution ``suite'' such as @code{buster}
31176 or @code{focal}. If set to @code{#f}, the default for the OS provider is used.
31177 @item @code{extra-pkgs} (default: @code{%default-debootstrap-extra-pkgs})
31178 List of extra packages that will get installed by dpkg in addition
31179 to the minimal system.
31180 @item @code{components} (default: @code{#f})
31181 When set, must be a list of Debian repository ``components''. For example
31182 @code{'("main" "contrib")}.
31183 @item @code{generate-cache?} (default: @code{#t})
31184 Whether to automatically cache the generated debootstrap archive.
31185 @item @code{clean-cache} (default: @code{14})
31186 Discard the cache after this amount of days. Use @code{#f} to never
31188 @item @code{partition-style} (default: @code{'msdos})
31189 The type of partition to create. When set, it must be one of
31190 @code{'msdos}, @code{'none} or a string.
31191 @item @code{partition-alignment} (default: @code{2048})
31192 Alignment of the partition in sectors.
31196 @deffn {Scheme Procedure} debootstrap-variant @var{name} @var{configuration}
31197 This is a helper procedure that creates a @code{ganeti-os-variant} record. It
31198 takes two parameters: a name and a @code{debootstrap-configuration} object.
31201 @deffn {Scheme Procedure} debootstrap-os @var{variants}@dots{}
31202 This is a helper procedure that creates a @code{ganeti-os} record. It takes
31203 a list of variants created with @code{debootstrap-variant}.
31206 @deffn {Scheme Procedure} guix-variant @var{name} @var{configuration}
31207 This is a helper procedure that creates a @code{ganeti-os-variant} record for
31208 use with the Guix OS provider. It takes a name and a G-expression that returns
31209 a ``file-like'' (@pxref{G-Expressions, file-like objects}) object containing a
31210 Guix System configuration.
31213 @deffn {Scheme Procedure} guix-os @var{variants}@dots{}
31214 This is a helper procedure that creates a @code{ganeti-os} record. It
31215 takes a list of variants produced by @code{guix-variant}.
31218 @defvr {Scheme Variable} %default-debootstrap-variants
31219 This is a convenience variable to make the debootstrap provider work
31220 ``out of the box'' without users having to declare variants manually. It
31221 contains a single debootstrap variant with the default configuration:
31224 (list (debootstrap-variant
31226 (debootstrap-configuration)))
31230 @defvr {Scheme Variable} %default-guix-variants
31231 This is a convenience variable to make the Guix OS provider work without
31232 additional configuration. It creates a virtual machine that has an SSH
31233 server, a serial console, and authorizes the Ganeti hosts SSH keys.
31236 (list (guix-variant
31238 (file-append ganeti-instance-guix
31239 "/share/doc/ganeti-instance-guix/examples/dynamic.scm")))
31243 Users can implement support for OS providers unbeknownst to Guix by extending
31244 the @code{ganeti-os} and @code{ganeti-os-variant} records appropriately.
31250 (extension ".conf")
31252 (list (ganeti-os-variant
31254 (configuration (plain-file "bar" "this is fine"))))))
31257 That creates @file{/etc/ganeti/instance-custom/variants/foo.conf} which points
31258 to a file in the store with contents @code{this is fine}. It also creates
31259 @file{/etc/ganeti/instance-custom/variants/variants.list} with contents @code{foo}.
31261 Obviously this may not work for all OS providers out there. If you find the
31262 interface limiting, please reach out to @email{guix-devel@@gnu.org}.
31264 The rest of this section documents the various services that are included by
31265 @code{ganeti-service-type}.
31267 @defvr {Scheme Variable} ganeti-noded-service-type
31268 @command{ganeti-noded} is the daemon responsible for node-specific functions
31269 within the Ganeti system. The value of this service must be a
31270 @code{ganeti-noded-configuration} object.
31273 @deftp {Data Type} ganeti-noded-configuration
31274 This is the configuration for the @code{ganeti-noded} service.
31277 @item @code{ganeti} (default: @code{ganeti})
31278 The @code{ganeti} package to use for this service.
31280 @item @code{port} (default: @code{1811})
31281 The TCP port on which the node daemon listens for network requests.
31283 @item @code{address} (default: @code{"0.0.0.0"})
31284 The network address that the daemon will bind to. The default address means
31285 bind to all available addresses.
31287 @item @code{interface} (default: @code{#f})
31288 When this is set, it must be a specific network interface (e.g.@: @code{eth0})
31289 that the daemon will bind to.
31291 @item @code{max-clients} (default: @code{20})
31292 This sets a limit on the maximum number of simultaneous client connections
31293 that the daemon will handle. Connections above this count are accepted, but
31294 no responses will be sent until enough connections have closed.
31296 @item @code{ssl?} (default: @code{#t})
31297 Whether to use SSL/TLS to encrypt network communications. The certificate
31298 is automatically provisioned by the cluster and can be rotated with
31299 @command{gnt-cluster renew-crypto}.
31301 @item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
31302 This can be used to provide a specific encryption key for TLS communications.
31304 @item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
31305 This can be used to provide a specific certificate for TLS communications.
31307 @item @code{debug?} (default: @code{#f})
31308 When true, the daemon performs additional logging for debugging purposes.
31309 Note that this will leak encryption details to the log files, use with caution.
31314 @defvr {Scheme Variable} ganeti-confd-service-type
31315 @command{ganeti-confd} answers queries related to the configuration of a
31316 Ganeti cluster. The purpose of this daemon is to have a highly available
31317 and fast way to query cluster configuration values. It is automatically
31318 active on all @dfn{master candidates}. The value of this service must be a
31319 @code{ganeti-confd-configuration} object.
31323 @deftp {Data Type} ganeti-confd-configuration
31324 This is the configuration for the @code{ganeti-confd} service.
31327 @item @code{ganeti} (default: @code{ganeti})
31328 The @code{ganeti} package to use for this service.
31330 @item @code{port} (default: @code{1814})
31331 The UDP port on which to listen for network requests.
31333 @item @code{address} (default: @code{"0.0.0.0"})
31334 Network address that the daemon will bind to.
31336 @item @code{debug?} (default: @code{#f})
31337 When true, the daemon performs additional logging for debugging purposes.
31342 @defvr {Scheme Variable} ganeti-wconfd-service-type
31343 @command{ganeti-wconfd} is the daemon that has authoritative knowledge
31344 about the cluster configuration and is the only entity that can accept
31345 changes to it. All jobs that need to modify the configuration will do so
31346 by sending appropriate requests to this daemon. It only runs on the
31347 @dfn{master node} and will automatically disable itself on other nodes.
31349 The value of this service must be a
31350 @code{ganeti-wconfd-configuration} object.
31353 @deftp {Data Type} ganeti-wconfd-configuration
31354 This is the configuration for the @code{ganeti-wconfd} service.
31357 @item @code{ganeti} (default: @code{ganeti})
31358 The @code{ganeti} package to use for this service.
31360 @item @code{no-voting?} (default: @code{#f})
31361 The daemon will refuse to start if the majority of cluster nodes does not
31362 agree that it is running on the master node. Set to @code{#t} to start
31363 even if a quorum can not be reached (dangerous, use with caution).
31365 @item @code{debug?} (default: @code{#f})
31366 When true, the daemon performs additional logging for debugging purposes.
31371 @defvr {Scheme Variable} ganeti-luxid-service-type
31372 @command{ganeti-luxid} is a daemon used to answer queries related to the
31373 configuration and the current live state of a Ganeti cluster. Additionally,
31374 it is the authoritative daemon for the Ganeti job queue. Jobs can be
31375 submitted via this daemon and it schedules and starts them.
31377 It takes a @code{ganeti-luxid-configuration} object.
31380 @deftp {Data Type} ganeti-luxid-configuration
31381 This is the configuration for the @code{ganeti-luxid} service.
31384 @item @code{ganeti} (default: @code{ganeti})
31385 The @code{ganeti} package to use for this service.
31387 @item @code{no-voting?} (default: @code{#f})
31388 The daemon will refuse to start if it cannot verify that the majority of
31389 cluster nodes believes that it is running on the master node. Set to
31390 @code{#t} to ignore such checks and start anyway (this can be dangerous).
31392 @item @code{debug?} (default: @code{#f})
31393 When true, the daemon performs additional logging for debugging purposes.
31398 @defvr {Scheme Variable} ganeti-rapi-service-type
31399 @command{ganeti-rapi} provides a remote API for Ganeti clusters. It runs on
31400 the master node and can be used to perform cluster actions programmatically
31401 via a JSON-based RPC protocol.
31403 Most query operations are allowed without authentication (unless
31404 @var{require-authentication?} is set), whereas write operations require
31405 explicit authorization via the @file{/var/lib/ganeti/rapi/users} file. See
31406 the @url{http://docs.ganeti.org/ganeti/master/html/rapi.html, Ganeti Remote
31407 API documentation} for more information.
31409 The value of this service must be a @code{ganeti-rapi-configuration} object.
31412 @deftp {Data Type} ganeti-rapi-configuration
31413 This is the configuration for the @code{ganeti-rapi} service.
31416 @item @code{ganeti} (default: @code{ganeti})
31417 The @code{ganeti} package to use for this service.
31419 @item @code{require-authentication?} (default: @code{#f})
31420 Whether to require authentication even for read-only operations.
31422 @item @code{port} (default: @code{5080})
31423 The TCP port on which to listen to API requests.
31425 @item @code{address} (default: @code{"0.0.0.0"})
31426 The network address that the service will bind to. By default it listens
31427 on all configured addresses.
31429 @item @code{interface} (default: @code{#f})
31430 When set, it must specify a specific network interface such as @code{eth0}
31431 that the daemon will bind to.
31433 @item @code{max-clients} (default: @code{20})
31434 The maximum number of simultaneous client requests to handle. Further
31435 connections are allowed, but no responses are sent until enough connections
31438 @item @code{ssl?} (default: @code{#t})
31439 Whether to use SSL/TLS encryption on the RAPI port.
31441 @item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
31442 This can be used to provide a specific encryption key for TLS communications.
31444 @item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
31445 This can be used to provide a specific certificate for TLS communications.
31447 @item @code{debug?} (default: @code{#f})
31448 When true, the daemon performs additional logging for debugging purposes.
31449 Note that this will leak encryption details to the log files, use with caution.
31454 @defvr {Scheme Variable} ganeti-kvmd-service-type
31455 @command{ganeti-kvmd} is responsible for determining whether a given KVM
31456 instance was shut down by an administrator or a user. Normally Ganeti will
31457 restart an instance that was not stopped through Ganeti itself. If the
31458 cluster option @code{user_shutdown} is true, this daemon monitors the
31459 @code{QMP} socket provided by QEMU and listens for shutdown events, and
31460 marks the instance as @dfn{USER_down} instead of @dfn{ERROR_down} when
31461 it shuts down gracefully by itself.
31463 It takes a @code{ganeti-kvmd-configuration} object.
31466 @deftp {Data Type} ganeti-kvmd-configuration
31469 @item @code{ganeti} (default: @code{ganeti})
31470 The @code{ganeti} package to use for this service.
31472 @item @code{debug?} (default: @code{#f})
31473 When true, the daemon performs additional logging for debugging purposes.
31478 @defvr {Scheme Variable} ganeti-mond-service-type
31479 @command{ganeti-mond} is an optional daemon that provides Ganeti monitoring
31480 functionality. It is responsible for running data collectors and publish the
31481 collected information through a HTTP interface.
31483 It takes a @code{ganeti-mond-configuration} object.
31486 @deftp {Data Type} ganeti-mond-configuration
31489 @item @code{ganeti} (default: @code{ganeti})
31490 The @code{ganeti} package to use for this service.
31492 @item @code{port} (default: @code{1815})
31493 The port on which the daemon will listen.
31495 @item @code{address} (default: @code{"0.0.0.0"})
31496 The network address that the daemon will bind to. By default it binds to all
31497 available interfaces.
31499 @item @code{debug?} (default: @code{#f})
31500 When true, the daemon performs additional logging for debugging purposes.
31505 @defvr {Scheme Variable} ganeti-metad-service-type
31506 @command{ganeti-metad} is an optional daemon that can be used to provide
31507 information about the cluster to instances or OS install scripts.
31509 It takes a @code{ganeti-metad-configuration} object.
31512 @deftp {Data Type} ganeti-metad-configuration
31515 @item @code{ganeti} (default: @code{ganeti})
31516 The @code{ganeti} package to use for this service.
31518 @item @code{port} (default: @code{80})
31519 The port on which the daemon will listen.
31521 @item @code{address} (default: @code{#f})
31522 If set, the daemon will bind to this address only. If left unset, the behavior
31523 depends on the cluster configuration.
31525 @item @code{debug?} (default: @code{#f})
31526 When true, the daemon performs additional logging for debugging purposes.
31531 @defvr {Scheme Variable} ganeti-watcher-service-type
31532 @command{ganeti-watcher} is a script designed to run periodically and ensure
31533 the health of a cluster. It will automatically restart instances that have
31534 stopped without Ganeti's consent, and repairs DRBD links in case a node has
31535 rebooted. It also archives old cluster jobs and restarts Ganeti daemons
31536 that are not running. If the cluster parameter @code{ensure_node_health}
31537 is set, the watcher will also shutdown instances and DRBD devices if the
31538 node it is running on is declared offline by known master candidates.
31540 It can be paused on all nodes with @command{gnt-cluster watcher pause}.
31542 The service takes a @code{ganeti-watcher-configuration} object.
31545 @deftp {Data Type} ganeti-watcher-configuration
31548 @item @code{ganeti} (default: @code{ganeti})
31549 The @code{ganeti} package to use for this service.
31551 @item @code{schedule} (default: @code{'(next-second-from (next-minute (range 0 60 5)))})
31552 How often to run the script. The default is every five minutes.
31554 @item @code{rapi-ip} (default: @code{#f})
31555 This option needs to be specified only if the RAPI daemon is configured to use
31556 a particular interface or address. By default the cluster address is used.
31558 @item @code{job-age} (default: @code{(* 6 3600)})
31559 Archive cluster jobs older than this age, specified in seconds. The default
31560 is 6 hours. This keeps @command{gnt-job list} manageable.
31562 @item @code{verify-disks?} (default: @code{#t})
31563 If this is @code{#f}, the watcher will not try to repair broken DRBD links
31564 automatically. Administrators will need to use @command{gnt-cluster verify-disks}
31567 @item @code{debug?} (default: @code{#f})
31568 When @code{#t}, the script performs additional logging for debugging purposes.
31573 @defvr {Scheme Variable} ganeti-cleaner-service-type
31574 @command{ganeti-cleaner} is a script designed to run periodically and remove
31575 old files from the cluster. This service type controls two @dfn{cron jobs}:
31576 one intended for the master node that permanently purges old cluster jobs,
31577 and one intended for every node that removes expired X509 certificates, keys,
31578 and outdated @command{ganeti-watcher} information. Like all Ganeti services,
31579 it is safe to include even on non-master nodes as it will disable itself as
31582 It takes a @code{ganeti-cleaner-configuration} object.
31585 @deftp {Data Type} ganeti-cleaner-configuration
31588 @item @code{ganeti} (default: @code{ganeti})
31589 The @code{ganeti} package to use for the @command{gnt-cleaner} command.
31591 @item @code{master-schedule} (default: @code{"45 1 * * *"})
31592 How often to run the master cleaning job. The default is once per day, at
31595 @item @code{node-schedule} (default: @code{"45 2 * * *"})
31596 How often to run the node cleaning job. The default is once per day, at
31602 @node Version Control Services
31603 @subsection Version Control Services
31605 The @code{(gnu services version-control)} module provides a service to
31606 allow remote access to local Git repositories. There are three options:
31607 the @code{git-daemon-service}, which provides access to repositories via
31608 the @code{git://} unsecured TCP-based protocol, extending the
31609 @code{nginx} web server to proxy some requests to
31610 @code{git-http-backend}, or providing a web interface with
31611 @code{cgit-service-type}.
31613 @deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)]
31615 Return a service that runs @command{git daemon}, a simple TCP server to
31616 expose repositories over the Git protocol for anonymous access.
31618 The optional @var{config} argument should be a
31619 @code{<git-daemon-configuration>} object, by default it allows read-only
31620 access to exported@footnote{By creating the magic file
31621 @file{git-daemon-export-ok} in the repository directory.} repositories under
31626 @deftp {Data Type} git-daemon-configuration
31627 Data type representing the configuration for @code{git-daemon-service}.
31630 @item @code{package} (default: @code{git})
31631 Package object of the Git distributed version control system.
31633 @item @code{export-all?} (default: @code{#f})
31634 Whether to allow access for all Git repositories, even if they do not
31635 have the @file{git-daemon-export-ok} file.
31637 @item @code{base-path} (default: @file{/srv/git})
31638 Whether to remap all the path requests as relative to the given path.
31639 If you run @command{git daemon} with @code{(base-path "/srv/git")} on
31640 @samp{example.com}, then if you later try to pull
31641 @indicateurl{git://example.com/hello.git}, git daemon will interpret the
31642 path as @file{/srv/git/hello.git}.
31644 @item @code{user-path} (default: @code{#f})
31645 Whether to allow @code{~user} notation to be used in requests. When
31646 specified with empty string, requests to
31647 @indicateurl{git://host/~alice/foo} is taken as a request to access
31648 @code{foo} repository in the home directory of user @code{alice}. If
31649 @code{(user-path "@var{path}")} is specified, the same request is taken
31650 as a request to access @file{@var{path}/foo} repository in the home
31651 directory of user @code{alice}.
31653 @item @code{listen} (default: @code{'()})
31654 Whether to listen on specific IP addresses or hostnames, defaults to
31657 @item @code{port} (default: @code{#f})
31658 Whether to listen on an alternative port, which defaults to 9418.
31660 @item @code{whitelist} (default: @code{'()})
31661 If not empty, only allow access to this list of directories.
31663 @item @code{extra-options} (default: @code{'()})
31664 Extra options will be passed to @command{git daemon}, please run
31665 @command{man git-daemon} for more information.
31670 The @code{git://} protocol lacks authentication. When you pull from a
31671 repository fetched via @code{git://}, you don't know whether the data you
31672 receive was modified or is even coming from the specified host, and your
31673 connection is subject to eavesdropping. It's better to use an authenticated
31674 and encrypted transport, such as @code{https}. Although Git allows you
31675 to serve repositories using unsophisticated file-based web servers,
31676 there is a faster protocol implemented by the @code{git-http-backend}
31677 program. This program is the back-end of a proper Git web service. It
31678 is designed to sit behind a FastCGI proxy. @xref{Web Services}, for more
31679 on running the necessary @code{fcgiwrap} daemon.
31681 Guix has a separate configuration data type for serving Git repositories
31684 @deftp {Data Type} git-http-configuration
31685 Data type representing the configuration for a future
31686 @code{git-http-service-type}; can currently be used to configure Nginx
31687 through @code{git-http-nginx-location-configuration}.
31690 @item @code{package} (default: @var{git})
31691 Package object of the Git distributed version control system.
31693 @item @code{git-root} (default: @file{/srv/git})
31694 Directory containing the Git repositories to expose to the world.
31696 @item @code{export-all?} (default: @code{#f})
31697 Whether to expose access for all Git repositories in @var{git-root},
31698 even if they do not have the @file{git-daemon-export-ok} file.
31700 @item @code{uri-path} (default: @samp{/git/})
31701 Path prefix for Git access. With the default @samp{/git/} prefix, this
31702 will map @indicateurl{http://@var{server}/git/@var{repo}.git} to
31703 @file{/srv/git/@var{repo}.git}. Requests whose URI paths do not begin
31704 with this prefix are not passed on to this Git instance.
31706 @item @code{fcgiwrap-socket} (default: @code{127.0.0.1:9000})
31707 The socket on which the @code{fcgiwrap} daemon is listening. @xref{Web
31712 There is no @code{git-http-service-type}, currently; instead you can
31713 create an @code{nginx-location-configuration} from a
31714 @code{git-http-configuration} and then add that location to a web
31717 @deffn {Scheme Procedure} git-http-nginx-location-configuration @
31718 [config=(git-http-configuration)]
31719 Compute an @code{nginx-location-configuration} that corresponds to the
31720 given Git http configuration. An example nginx service definition to
31721 serve the default @file{/srv/git} over HTTPS might be:
31724 (service nginx-service-type
31725 (nginx-configuration
31728 (nginx-server-configuration
31729 (listen '("443 ssl"))
31730 (server-name "git.my-host.org")
31732 "/etc/letsencrypt/live/git.my-host.org/fullchain.pem")
31733 (ssl-certificate-key
31734 "/etc/letsencrypt/live/git.my-host.org/privkey.pem")
31737 (git-http-nginx-location-configuration
31738 (git-http-configuration (uri-path "/"))))))))))
31741 This example assumes that you are using Let's Encrypt to get your TLS
31742 certificate. @xref{Certificate Services}. The default @code{certbot}
31743 service will redirect all HTTP traffic on @code{git.my-host.org} to
31744 HTTPS@. You will also need to add an @code{fcgiwrap} proxy to your
31745 system services. @xref{Web Services}.
31748 @subsubheading Cgit Service
31750 @cindex Cgit service
31751 @cindex Git, web interface
31752 @uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
31753 repositories written in C.
31755 The following example will configure the service with default values.
31756 By default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
31759 (service cgit-service-type)
31762 The @code{file-object} type designates either a file-like object
31763 (@pxref{G-Expressions, file-like objects}) or a string.
31765 @c %start of fragment
31767 Available @code{cgit-configuration} fields are:
31769 @deftypevr {@code{cgit-configuration} parameter} package package
31774 @deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx
31775 NGINX configuration.
31779 @deftypevr {@code{cgit-configuration} parameter} file-object about-filter
31780 Specifies a command which will be invoked to format the content of about
31781 pages (both top-level and for each repository).
31783 Defaults to @samp{""}.
31787 @deftypevr {@code{cgit-configuration} parameter} string agefile
31788 Specifies a path, relative to each repository path, which can be used to
31789 specify the date and time of the youngest commit in the repository.
31791 Defaults to @samp{""}.
31795 @deftypevr {@code{cgit-configuration} parameter} file-object auth-filter
31796 Specifies a command that will be invoked for authenticating repository
31799 Defaults to @samp{""}.
31803 @deftypevr {@code{cgit-configuration} parameter} string branch-sort
31804 Flag which, when set to @samp{age}, enables date ordering in the branch
31805 ref list, and when set @samp{name} enables ordering by branch name.
31807 Defaults to @samp{"name"}.
31811 @deftypevr {@code{cgit-configuration} parameter} string cache-root
31812 Path used to store the cgit cache entries.
31814 Defaults to @samp{"/var/cache/cgit"}.
31818 @deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl
31819 Number which specifies the time-to-live, in minutes, for the cached
31820 version of repository pages accessed with a fixed SHA1.
31822 Defaults to @samp{-1}.
31826 @deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl
31827 Number which specifies the time-to-live, in minutes, for the cached
31828 version of repository pages accessed without a fixed SHA1.
31830 Defaults to @samp{5}.
31834 @deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl
31835 Number which specifies the time-to-live, in minutes, for the cached
31836 version of the repository summary page.
31838 Defaults to @samp{5}.
31842 @deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl
31843 Number which specifies the time-to-live, in minutes, for the cached
31844 version of the repository index page.
31846 Defaults to @samp{5}.
31850 @deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl
31851 Number which specifies the time-to-live, in minutes, for the result of
31852 scanning a path for Git repositories.
31854 Defaults to @samp{15}.
31858 @deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl
31859 Number which specifies the time-to-live, in minutes, for the cached
31860 version of the repository about page.
31862 Defaults to @samp{15}.
31866 @deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl
31867 Number which specifies the time-to-live, in minutes, for the cached
31868 version of snapshots.
31870 Defaults to @samp{5}.
31874 @deftypevr {@code{cgit-configuration} parameter} integer cache-size
31875 The maximum number of entries in the cgit cache. When set to @samp{0},
31876 caching is disabled.
31878 Defaults to @samp{0}.
31882 @deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort?
31883 Sort items in the repo list case sensitively.
31885 Defaults to @samp{#t}.
31889 @deftypevr {@code{cgit-configuration} parameter} list clone-prefix
31890 List of common prefixes which, when combined with a repository URL,
31891 generates valid clone URLs for the repository.
31893 Defaults to @samp{()}.
31897 @deftypevr {@code{cgit-configuration} parameter} list clone-url
31898 List of @code{clone-url} templates.
31900 Defaults to @samp{()}.
31904 @deftypevr {@code{cgit-configuration} parameter} file-object commit-filter
31905 Command which will be invoked to format commit messages.
31907 Defaults to @samp{""}.
31911 @deftypevr {@code{cgit-configuration} parameter} string commit-sort
31912 Flag which, when set to @samp{date}, enables strict date ordering in the
31913 commit log, and when set to @samp{topo} enables strict topological
31916 Defaults to @samp{"git log"}.
31920 @deftypevr {@code{cgit-configuration} parameter} file-object css
31921 URL which specifies the css document to include in all cgit pages.
31923 Defaults to @samp{"/share/cgit/cgit.css"}.
31927 @deftypevr {@code{cgit-configuration} parameter} file-object email-filter
31928 Specifies a command which will be invoked to format names and email
31929 address of committers, authors, and taggers, as represented in various
31930 places throughout the cgit interface.
31932 Defaults to @samp{""}.
31936 @deftypevr {@code{cgit-configuration} parameter} boolean embedded?
31937 Flag which, when set to @samp{#t}, will make cgit generate a HTML
31938 fragment suitable for embedding in other HTML pages.
31940 Defaults to @samp{#f}.
31944 @deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph?
31945 Flag which, when set to @samp{#t}, will make cgit print an ASCII-art
31946 commit history graph to the left of the commit messages in the
31947 repository log page.
31949 Defaults to @samp{#f}.
31953 @deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides?
31954 Flag which, when set to @samp{#t}, allows all filter settings to be
31955 overridden in repository-specific cgitrc files.
31957 Defaults to @samp{#f}.
31961 @deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links?
31962 Flag which, when set to @samp{#t}, allows users to follow a file in the
31965 Defaults to @samp{#f}.
31969 @deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone?
31970 If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git
31973 Defaults to @samp{#t}.
31977 @deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links?
31978 Flag which, when set to @samp{#t}, will make cgit generate extra links
31979 "summary", "commit", "tree" for each repo in the repository index.
31981 Defaults to @samp{#f}.
31985 @deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner?
31986 Flag which, when set to @samp{#t}, will make cgit display the owner of
31987 each repo in the repository index.
31989 Defaults to @samp{#t}.
31993 @deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount?
31994 Flag which, when set to @samp{#t}, will make cgit print the number of
31995 modified files for each commit on the repository log page.
31997 Defaults to @samp{#f}.
32001 @deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount?
32002 Flag which, when set to @samp{#t}, will make cgit print the number of
32003 added and removed lines for each commit on the repository log page.
32005 Defaults to @samp{#f}.
32009 @deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches?
32010 Flag which, when set to @code{#t}, will make cgit display remote
32011 branches in the summary and refs views.
32013 Defaults to @samp{#f}.
32017 @deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links?
32018 Flag which, when set to @code{1}, will make cgit use the subject of the
32019 parent commit as link text when generating links to parent commits in
32022 Defaults to @samp{#f}.
32026 @deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving?
32027 Flag which, when set to @samp{#t}, will make cgit use the subject of the
32028 parent commit as link text when generating links to parent commits in
32031 Defaults to @samp{#f}.
32035 @deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers?
32036 Flag which, when set to @samp{#t}, will make cgit generate linenumber
32037 links for plaintext blobs printed in the tree view.
32039 Defaults to @samp{#t}.
32043 @deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config?
32044 Flag which, when set to @samp{#f}, will allow cgit to use Git config to
32045 set any repo specific settings.
32047 Defaults to @samp{#f}.
32051 @deftypevr {@code{cgit-configuration} parameter} file-object favicon
32052 URL used as link to a shortcut icon for cgit.
32054 Defaults to @samp{"/favicon.ico"}.
32058 @deftypevr {@code{cgit-configuration} parameter} string footer
32059 The content of the file specified with this option will be included
32060 verbatim at the bottom of all pages (i.e.@: it replaces the standard
32061 "generated by..."@: message).
32063 Defaults to @samp{""}.
32067 @deftypevr {@code{cgit-configuration} parameter} string head-include
32068 The content of the file specified with this option will be included
32069 verbatim in the HTML HEAD section on all pages.
32071 Defaults to @samp{""}.
32075 @deftypevr {@code{cgit-configuration} parameter} string header
32076 The content of the file specified with this option will be included
32077 verbatim at the top of all pages.
32079 Defaults to @samp{""}.
32083 @deftypevr {@code{cgit-configuration} parameter} file-object include
32084 Name of a configfile to include before the rest of the current config-
32087 Defaults to @samp{""}.
32091 @deftypevr {@code{cgit-configuration} parameter} string index-header
32092 The content of the file specified with this option will be included
32093 verbatim above the repository index.
32095 Defaults to @samp{""}.
32099 @deftypevr {@code{cgit-configuration} parameter} string index-info
32100 The content of the file specified with this option will be included
32101 verbatim below the heading on the repository index page.
32103 Defaults to @samp{""}.
32107 @deftypevr {@code{cgit-configuration} parameter} boolean local-time?
32108 Flag which, if set to @samp{#t}, makes cgit print commit and tag times
32109 in the servers timezone.
32111 Defaults to @samp{#f}.
32115 @deftypevr {@code{cgit-configuration} parameter} file-object logo
32116 URL which specifies the source of an image which will be used as a logo
32119 Defaults to @samp{"/share/cgit/cgit.png"}.
32123 @deftypevr {@code{cgit-configuration} parameter} string logo-link
32124 URL loaded when clicking on the cgit logo image.
32126 Defaults to @samp{""}.
32130 @deftypevr {@code{cgit-configuration} parameter} file-object owner-filter
32131 Command which will be invoked to format the Owner column of the main
32134 Defaults to @samp{""}.
32138 @deftypevr {@code{cgit-configuration} parameter} integer max-atom-items
32139 Number of items to display in atom feeds view.
32141 Defaults to @samp{10}.
32145 @deftypevr {@code{cgit-configuration} parameter} integer max-commit-count
32146 Number of entries to list per page in "log" view.
32148 Defaults to @samp{50}.
32152 @deftypevr {@code{cgit-configuration} parameter} integer max-message-length
32153 Number of commit message characters to display in "log" view.
32155 Defaults to @samp{80}.
32159 @deftypevr {@code{cgit-configuration} parameter} integer max-repo-count
32160 Specifies the number of entries to list per page on the repository index
32163 Defaults to @samp{50}.
32167 @deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length
32168 Specifies the maximum number of repo description characters to display
32169 on the repository index page.
32171 Defaults to @samp{80}.
32175 @deftypevr {@code{cgit-configuration} parameter} integer max-blob-size
32176 Specifies the maximum size of a blob to display HTML for in KBytes.
32178 Defaults to @samp{0}.
32182 @deftypevr {@code{cgit-configuration} parameter} string max-stats
32183 Maximum statistics period. Valid values are @samp{week},@samp{month},
32184 @samp{quarter} and @samp{year}.
32186 Defaults to @samp{""}.
32190 @deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype
32191 Mimetype for the specified filename extension.
32193 Defaults to @samp{((gif "image/gif") (html "text/html") (jpg
32194 "image/jpeg") (jpeg "image/jpeg") (pdf "application/pdf") (png
32195 "image/png") (svg "image/svg+xml"))}.
32199 @deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file
32200 Specifies the file to use for automatic mimetype lookup.
32202 Defaults to @samp{""}.
32206 @deftypevr {@code{cgit-configuration} parameter} string module-link
32207 Text which will be used as the formatstring for a hyperlink when a
32208 submodule is printed in a directory listing.
32210 Defaults to @samp{""}.
32214 @deftypevr {@code{cgit-configuration} parameter} boolean nocache?
32215 If set to the value @samp{#t} caching will be disabled.
32217 Defaults to @samp{#f}.
32221 @deftypevr {@code{cgit-configuration} parameter} boolean noplainemail?
32222 If set to @samp{#t} showing full author email addresses will be
32225 Defaults to @samp{#f}.
32229 @deftypevr {@code{cgit-configuration} parameter} boolean noheader?
32230 Flag which, when set to @samp{#t}, will make cgit omit the standard
32231 header on all pages.
32233 Defaults to @samp{#f}.
32237 @deftypevr {@code{cgit-configuration} parameter} project-list project-list
32238 A list of subdirectories inside of @code{repository-directory}, relative
32239 to it, that should loaded as Git repositories. An empty list means that
32240 all subdirectories will be loaded.
32242 Defaults to @samp{()}.
32246 @deftypevr {@code{cgit-configuration} parameter} file-object readme
32247 Text which will be used as default value for @code{cgit-repo-readme}.
32249 Defaults to @samp{""}.
32253 @deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix?
32254 If set to @code{#t} and @code{repository-directory} is enabled, if any
32255 repositories are found with a suffix of @code{.git}, this suffix will be
32256 removed for the URL and name.
32258 Defaults to @samp{#f}.
32262 @deftypevr {@code{cgit-configuration} parameter} integer renamelimit
32263 Maximum number of files to consider when detecting renames.
32265 Defaults to @samp{-1}.
32269 @deftypevr {@code{cgit-configuration} parameter} string repository-sort
32270 The way in which repositories in each section are sorted.
32272 Defaults to @samp{""}.
32276 @deftypevr {@code{cgit-configuration} parameter} robots-list robots
32277 Text used as content for the @code{robots} meta-tag.
32279 Defaults to @samp{("noindex" "nofollow")}.
32283 @deftypevr {@code{cgit-configuration} parameter} string root-desc
32284 Text printed below the heading on the repository index page.
32286 Defaults to @samp{"a fast webinterface for the git dscm"}.
32290 @deftypevr {@code{cgit-configuration} parameter} string root-readme
32291 The content of the file specified with this option will be included
32292 verbatim below the ``about'' link on the repository index page.
32294 Defaults to @samp{""}.
32298 @deftypevr {@code{cgit-configuration} parameter} string root-title
32299 Text printed as heading on the repository index page.
32301 Defaults to @samp{""}.
32305 @deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path
32306 If set to @samp{#t} and repository-directory is enabled,
32307 repository-directory will recurse into directories whose name starts
32308 with a period. Otherwise, repository-directory will stay away from such
32309 directories, considered as ``hidden''. Note that this does not apply to
32310 the @file{.git} directory in non-bare repos.
32312 Defaults to @samp{#f}.
32316 @deftypevr {@code{cgit-configuration} parameter} list snapshots
32317 Text which specifies the default set of snapshot formats that cgit
32318 generates links for.
32320 Defaults to @samp{()}.
32324 @deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory
32325 Name of the directory to scan for repositories (represents
32328 Defaults to @samp{"/srv/git"}.
32332 @deftypevr {@code{cgit-configuration} parameter} string section
32333 The name of the current repository section - all repositories defined
32334 after this option will inherit the current section name.
32336 Defaults to @samp{""}.
32340 @deftypevr {@code{cgit-configuration} parameter} string section-sort
32341 Flag which, when set to @samp{1}, will sort the sections on the
32342 repository listing by name.
32344 Defaults to @samp{""}.
32348 @deftypevr {@code{cgit-configuration} parameter} integer section-from-path
32349 A number which, if defined prior to repository-directory, specifies how
32350 many path elements from each repo path to use as a default section name.
32352 Defaults to @samp{0}.
32356 @deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs?
32357 If set to @samp{#t} shows side-by-side diffs instead of unidiffs per
32360 Defaults to @samp{#f}.
32364 @deftypevr {@code{cgit-configuration} parameter} file-object source-filter
32365 Specifies a command which will be invoked to format plaintext blobs in
32368 Defaults to @samp{""}.
32372 @deftypevr {@code{cgit-configuration} parameter} integer summary-branches
32373 Specifies the number of branches to display in the repository ``summary''
32376 Defaults to @samp{10}.
32380 @deftypevr {@code{cgit-configuration} parameter} integer summary-log
32381 Specifies the number of log entries to display in the repository
32384 Defaults to @samp{10}.
32388 @deftypevr {@code{cgit-configuration} parameter} integer summary-tags
32389 Specifies the number of tags to display in the repository ``summary''
32392 Defaults to @samp{10}.
32396 @deftypevr {@code{cgit-configuration} parameter} string strict-export
32397 Filename which, if specified, needs to be present within the repository
32398 for cgit to allow access to that repository.
32400 Defaults to @samp{""}.
32404 @deftypevr {@code{cgit-configuration} parameter} string virtual-root
32405 URL which, if specified, will be used as root for all cgit links.
32407 Defaults to @samp{"/"}.
32411 @deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories
32412 A list of @dfn{cgit-repo} records to use with config.
32414 Defaults to @samp{()}.
32416 Available @code{repository-cgit-configuration} fields are:
32418 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots
32419 A mask of snapshot formats for this repo that cgit generates links for,
32420 restricted by the global @code{snapshots} setting.
32422 Defaults to @samp{()}.
32426 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter
32427 Override the default @code{source-filter}.
32429 Defaults to @samp{""}.
32433 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string url
32434 The relative URL used to access the repository.
32436 Defaults to @samp{""}.
32440 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter
32441 Override the default @code{about-filter}.
32443 Defaults to @samp{""}.
32447 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort
32448 Flag which, when set to @samp{age}, enables date ordering in the branch
32449 ref list, and when set to @samp{name} enables ordering by branch name.
32451 Defaults to @samp{""}.
32455 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url
32456 A list of URLs which can be used to clone repo.
32458 Defaults to @samp{()}.
32462 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter
32463 Override the default @code{commit-filter}.
32465 Defaults to @samp{""}.
32469 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort
32470 Flag which, when set to @samp{date}, enables strict date ordering in the
32471 commit log, and when set to @samp{topo} enables strict topological
32474 Defaults to @samp{""}.
32478 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch
32479 The name of the default branch for this repository. If no such branch
32480 exists in the repository, the first branch name (when sorted) is used as
32481 default instead. By default branch pointed to by HEAD, or ``master'' if
32482 there is no suitable HEAD.
32484 Defaults to @samp{""}.
32488 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc
32489 The value to show as repository description.
32491 Defaults to @samp{""}.
32495 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage
32496 The value to show as repository homepage.
32498 Defaults to @samp{""}.
32502 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter
32503 Override the default @code{email-filter}.
32505 Defaults to @samp{""}.
32509 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph?
32510 A flag which can be used to disable the global setting
32511 @code{enable-commit-graph?}.
32513 Defaults to @samp{disabled}.
32517 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount?
32518 A flag which can be used to disable the global setting
32519 @code{enable-log-filecount?}.
32521 Defaults to @samp{disabled}.
32525 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount?
32526 A flag which can be used to disable the global setting
32527 @code{enable-log-linecount?}.
32529 Defaults to @samp{disabled}.
32533 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches?
32534 Flag which, when set to @code{#t}, will make cgit display remote
32535 branches in the summary and refs views.
32537 Defaults to @samp{disabled}.
32541 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links?
32542 A flag which can be used to override the global setting
32543 @code{enable-subject-links?}.
32545 Defaults to @samp{disabled}.
32549 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving?
32550 A flag which can be used to override the global setting
32551 @code{enable-html-serving?}.
32553 Defaults to @samp{disabled}.
32557 @deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide?
32558 Flag which, when set to @code{#t}, hides the repository from the
32561 Defaults to @samp{#f}.
32565 @deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore?
32566 Flag which, when set to @samp{#t}, ignores the repository.
32568 Defaults to @samp{#f}.
32572 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo
32573 URL which specifies the source of an image which will be used as a logo
32574 on this repo’s pages.
32576 Defaults to @samp{""}.
32580 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link
32581 URL loaded when clicking on the cgit logo image.
32583 Defaults to @samp{""}.
32587 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter
32588 Override the default @code{owner-filter}.
32590 Defaults to @samp{""}.
32594 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link
32595 Text which will be used as the formatstring for a hyperlink when a
32596 submodule is printed in a directory listing. The arguments for the
32597 formatstring are the path and SHA1 of the submodule commit.
32599 Defaults to @samp{""}.
32603 @deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path
32604 Text which will be used as the formatstring for a hyperlink when a
32605 submodule with the specified subdirectory path is printed in a directory
32608 Defaults to @samp{()}.
32612 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats
32613 Override the default maximum statistics period.
32615 Defaults to @samp{""}.
32619 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string name
32620 The value to show as repository name.
32622 Defaults to @samp{""}.
32626 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner
32627 A value used to identify the owner of the repository.
32629 Defaults to @samp{""}.
32633 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string path
32634 An absolute path to the repository directory.
32636 Defaults to @samp{""}.
32640 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme
32641 A path (relative to repo) which specifies a file to include verbatim as
32642 the ``About'' page for this repo.
32644 Defaults to @samp{""}.
32648 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string section
32649 The name of the current repository section - all repositories defined
32650 after this option will inherit the current section name.
32652 Defaults to @samp{""}.
32656 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options
32657 Extra options will be appended to cgitrc file.
32659 Defaults to @samp{()}.
32665 @deftypevr {@code{cgit-configuration} parameter} list extra-options
32666 Extra options will be appended to cgitrc file.
32668 Defaults to @samp{()}.
32673 @c %end of fragment
32675 However, it could be that you just want to get a @code{cgitrc} up and
32676 running. In that case, you can pass an @code{opaque-cgit-configuration}
32677 as a record to @code{cgit-service-type}. As its name indicates, an
32678 opaque configuration does not have easy reflective capabilities.
32680 Available @code{opaque-cgit-configuration} fields are:
32682 @deftypevr {@code{opaque-cgit-configuration} parameter} package cgit
32686 @deftypevr {@code{opaque-cgit-configuration} parameter} string string
32687 The contents of the @code{cgitrc}, as a string.
32690 For example, if your @code{cgitrc} is just the empty string, you
32691 could instantiate a cgit service like this:
32694 (service cgit-service-type
32695 (opaque-cgit-configuration
32699 @subsubheading Gitolite Service
32701 @cindex Gitolite service
32702 @cindex Git, hosting
32703 @uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
32704 repositories on a central server.
32706 Gitolite can handle multiple repositories and users, and supports flexible
32707 configuration of the permissions for the users on the repositories.
32709 The following example will configure Gitolite using the default @code{git}
32710 user, and the provided SSH public key.
32713 (service gitolite-service-type
32714 (gitolite-configuration
32715 (admin-pubkey (plain-file
32717 "ssh-rsa AAAA... guix@@example.com"))))
32720 Gitolite is configured through a special admin repository which you can clone,
32721 for example, if you setup Gitolite on @code{example.com}, you would run the
32722 following command to clone the admin repository.
32725 git clone git@@example.com:gitolite-admin
32728 When the Gitolite service is activated, the provided @code{admin-pubkey} will
32729 be inserted in to the @file{keydir} directory in the gitolite-admin
32730 repository. If this results in a change in the repository, it will be
32731 committed using the message ``gitolite setup by GNU Guix''.
32733 @deftp {Data Type} gitolite-configuration
32734 Data type representing the configuration for @code{gitolite-service-type}.
32737 @item @code{package} (default: @var{gitolite})
32738 Gitolite package to use.
32740 @item @code{user} (default: @var{git})
32741 User to use for Gitolite. This will be user that you use when accessing
32744 @item @code{group} (default: @var{git})
32745 Group to use for Gitolite.
32747 @item @code{home-directory} (default: @var{"/var/lib/gitolite"})
32748 Directory in which to store the Gitolite configuration and repositories.
32750 @item @code{rc-file} (default: @var{(gitolite-rc-file)})
32751 A ``file-like'' object (@pxref{G-Expressions, file-like objects}),
32752 representing the configuration for Gitolite.
32754 @item @code{admin-pubkey} (default: @var{#f})
32755 A ``file-like'' object (@pxref{G-Expressions, file-like objects}) used to
32756 setup Gitolite. This will be inserted in to the @file{keydir} directory
32757 within the gitolite-admin repository.
32759 To specify the SSH key as a string, use the @code{plain-file} function.
32762 (plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com")
32768 @deftp {Data Type} gitolite-rc-file
32769 Data type representing the Gitolite RC file.
32772 @item @code{umask} (default: @code{#o0077})
32773 This controls the permissions Gitolite sets on the repositories and their
32776 A value like @code{#o0027} will give read access to the group used by Gitolite
32777 (by default: @code{git}). This is necessary when using Gitolite with software
32778 like cgit or gitweb.
32780 @item @code{unsafe-pattern} (default: @code{#f})
32781 An optional Perl regular expression for catching unsafe configurations in
32782 the configuration file. See
32783 @uref{https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt,
32784 Gitolite's documentation} for more information.
32786 When the value is not @code{#f}, it should be a string containing a Perl
32787 regular expression, such as @samp{"[`~#\$\&()|;<>]"}, which is the default
32788 value used by gitolite. It rejects any special character in configuration
32789 that might be interpreted by a shell, which is useful when sharing the
32790 administration burden with other people that do not otherwise have shell
32791 access on the server.
32793 @item @code{git-config-keys} (default: @code{""})
32794 Gitolite allows you to set git config values using the @samp{config}
32795 keyword. This setting allows control over the config keys to accept.
32797 @item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
32798 Set the role names allowed to be used by users running the perms command.
32800 @item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")})
32801 This setting controls the commands and features to enable within Gitolite.
32807 @subsubheading Gitile Service
32809 @cindex Gitile service
32811 @uref{https://git.lepiller.eu/gitile, Gitile} is a Git forge for viewing
32812 public git repository contents from a web browser.
32814 Gitile works best in collaboration with Gitolite, and will serve the public
32815 repositories from Gitolite by default. The service should listen only on
32816 a local port, and a webserver should be configured to serve static resources.
32817 The gitile service provides an easy way to extend the Nginx service for
32818 that purpose (@pxref{NGINX}).
32820 The following example will configure Gitile to serve repositories from a
32821 custom location, with some default messages for the home page and the
32825 (service gitile-service-type
32826 (gitile-configuration
32827 (repositories "/srv/git")
32828 (base-git-url "https://myweb.site/git")
32829 (index-title "My git repositories")
32830 (intro '((p "This is all my public work!")))
32831 (footer '((p "This is the end")))
32832 (nginx-server-block
32833 (nginx-server-configuration
32835 "/etc/letsencrypt/live/myweb.site/fullchain.pem")
32836 (ssl-certificate-key
32837 "/etc/letsencrypt/live/myweb.site/privkey.pem")
32838 (listen '("443 ssl http2" "[::]:443 ssl http2"))
32841 ;; Allow for https anonymous fetch on /git/ urls.
32842 (git-http-nginx-location-configuration
32843 (git-http-configuration
32845 (git-root "/var/lib/gitolite/repositories")))))))))
32848 In addition to the configuration record, you should configure your git
32849 repositories to contain some optional information. First, your public
32850 repositories need to contain the @file{git-daemon-export-ok} magic file
32851 that allows Git to export the repository. Gitile uses the presence of this
32852 file to detect public repositories it should make accessible. To do so with
32853 Gitolite for instance, modify your @file{conf/gitolite.conf} to include
32854 this in the repositories you want to make public:
32861 In addition, Gitile can read the repository configuration to display more
32862 information on the repository. Gitile uses the gitweb namespace for its
32863 configuration. As an example, you can use the following in your
32864 @file{conf/gitolite.conf}:
32869 desc = A long description, optionally with <i>HTML</i>, shown on the index page
32870 config gitweb.name = The Foo Project
32871 config gitweb.synopsis = A short description, shown on the main page of the project
32874 Do not forget to commit and push these changes once you are satisfied. You
32875 may need to change your gitolite configuration to allow the previous
32876 configuration options to be set. One way to do that is to add the
32877 following service definition:
32880 (service gitolite-service-type
32881 (gitolite-configuration
32882 (admin-pubkey (local-file "key.pub"))
32886 ;; Allow to set any configuration key
32887 (git-config-keys ".*")
32888 ;; Allow any text as a valid configuration value
32889 (unsafe-patt "^$")))))
32892 @deftp {Data Type} gitile-configuration
32893 Data type representing the configuration for @code{gitile-service-type}.
32896 @item @code{package} (default: @var{gitile})
32897 Gitile package to use.
32899 @item @code{host} (default: @code{"localhost"})
32900 The host on which gitile is listening.
32902 @item @code{port} (default: @code{8080})
32903 The port on which gitile is listening.
32905 @item @code{database} (default: @code{"/var/lib/gitile/gitile-db.sql"})
32906 The location of the database.
32908 @item @code{repositories} (default: @code{"/var/lib/gitolite/repositories"})
32909 The location of the repositories. Note that only public repositories will
32910 be shown by Gitile. To make a repository public, add an empty
32911 @file{git-daemon-export-ok} file at the root of that repository.
32913 @item @code{base-git-url}
32914 The base git url that will be used to show clone commands.
32916 @item @code{index-title} (default: @code{"Index"})
32917 The page title for the index page that lists all the available repositories.
32919 @item @code{intro} (default: @code{'()})
32920 The intro content, as a list of sxml expressions. This is shown above the list
32921 of repositories, on the index page.
32923 @item @code{footer} (default: @code{'()})
32924 The footer content, as a list of sxml expressions. This is shown on every
32925 page served by Gitile.
32927 @item @code{nginx-server-block}
32928 An nginx server block that will be extended and used as a reverse proxy by
32929 Gitile to serve its pages, and as a normal web server to serve its assets.
32931 You can use this block to add more custom URLs to your domain, such as a
32932 @code{/git/} URL for anonymous clones, or serving any other files you would
32938 @node Game Services
32939 @subsection Game Services
32941 @subsubheading The Battle for Wesnoth Service
32943 @uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn
32944 based tactical strategy game, with several single player campaigns, and
32945 multiplayer games (both networked and local).
32947 @defvar {Scheme Variable} wesnothd-service-type
32948 Service type for the wesnothd service. Its value must be a
32949 @code{wesnothd-configuration} object. To run wesnothd in the default
32950 configuration, instantiate it as:
32953 (service wesnothd-service-type)
32957 @deftp {Data Type} wesnothd-configuration
32958 Data type representing the configuration of @command{wesnothd}.
32961 @item @code{package} (default: @code{wesnoth-server})
32962 The wesnoth server package to use.
32964 @item @code{port} (default: @code{15000})
32965 The port to bind the server to.
32970 @node PAM Mount Service
32971 @subsection PAM Mount Service
32974 The @code{(gnu services pam-mount)} module provides a service allowing
32975 users to mount volumes when they log in. It should be able to mount any
32976 volume format supported by the system.
32978 @defvar {Scheme Variable} pam-mount-service-type
32979 Service type for PAM Mount support.
32982 @deftp {Data Type} pam-mount-configuration
32983 Data type representing the configuration of PAM Mount.
32985 It takes the following parameters:
32989 The configuration rules that will be used to generate
32990 @file{/etc/security/pam_mount.conf.xml}.
32992 The configuration rules are SXML elements (@pxref{SXML,,, guile, GNU
32993 Guile Reference Manual}), and the default ones don't mount anything for
32997 `((debug (@@ (enable "0")))
32998 (mntoptions (@@ (allow ,(string-join
32999 '("nosuid" "nodev" "loop"
33000 "encryption" "fsck" "nonempty"
33001 "allow_root" "allow_other")
33003 (mntoptions (@@ (require "nosuid,nodev")))
33004 (logout (@@ (wait "0")
33008 (mkmountpoint (@@ (enable "1")
33012 Some @code{volume} elements must be added to automatically mount volumes
33013 at login. Here's an example allowing the user @code{alice} to mount her
33014 encrypted @env{HOME} directory and allowing the user @code{bob} to mount
33015 the partition where he stores his data:
33018 (define pam-mount-rules
33019 `((debug (@@ (enable "0")))
33020 (volume (@@ (user "alice")
33023 (mountpoint "/home/alice")))
33024 (volume (@@ (user "bob")
33027 (mountpoint "/home/bob/data")
33028 (options "defaults,autodefrag,compress")))
33029 (mntoptions (@@ (allow ,(string-join
33030 '("nosuid" "nodev" "loop"
33031 "encryption" "fsck" "nonempty"
33032 "allow_root" "allow_other")
33034 (mntoptions (@@ (require "nosuid,nodev")))
33035 (logout (@@ (wait "0")
33039 (mkmountpoint (@@ (enable "1")
33040 (remove "true")))))
33042 (service pam-mount-service-type
33043 (pam-mount-configuration
33044 (rules pam-mount-rules)))
33047 The complete list of possible options can be found in the man page for
33048 @uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html, pam_mount.conf}.
33053 @node Guix Services
33054 @subsection Guix Services
33056 @subsubheading Guix Build Coordinator
33057 The @uref{https://git.cbaines.net/guix/build-coordinator/,Guix Build
33058 Coordinator} aids in distributing derivation builds among machines
33059 running an @dfn{agent}. The build daemon is still used to build the
33060 derivations, but the Guix Build Coordinator manages allocating builds
33061 and working with the results.
33063 The Guix Build Coordinator consists of one @dfn{coordinator}, and one or
33064 more connected @dfn{agent} processes. The coordinator process handles
33065 clients submitting builds, and allocating builds to agents. The agent
33066 processes talk to a build daemon to actually perform the builds, then
33067 send the results back to the coordinator.
33069 There is a script to run the coordinator component of the Guix Build
33070 Coordinator, but the Guix service uses a custom Guile script instead, to
33071 provide better integration with G-expressions used in the configuration.
33073 @defvar {Scheme Variable} guix-build-coordinator-service-type
33074 Service type for the Guix Build Coordinator. Its value must be a
33075 @code{guix-build-coordinator-configuration} object.
33078 @deftp {Data Type} guix-build-coordinator-configuration
33079 Data type representing the configuration of the Guix Build Coordinator.
33082 @item @code{package} (default: @code{guix-build-coordinator})
33083 The Guix Build Coordinator package to use.
33085 @item @code{user} (default: @code{"guix-build-coordinator"})
33086 The system user to run the service as.
33088 @item @code{group} (default: @code{"guix-build-coordinator"})
33089 The system group to run the service as.
33091 @item @code{database-uri-string} (default: @code{"sqlite:///var/lib/guix-build-coordinator/guix_build_coordinator.db"})
33092 The URI to use for the database.
33094 @item @code{agent-communication-uri} (default: @code{"http://0.0.0.0:8745"})
33095 The URI describing how to listen to requests from agent processes.
33097 @item @code{client-communication-uri} (default: @code{"http://127.0.0.1:8746"})
33098 The URI describing how to listen to requests from clients. The client
33099 API allows submitting builds and currently isn't authenticated, so take
33100 care when configuring this value.
33102 @item @code{allocation-strategy} (default: @code{#~basic-build-allocation-strategy})
33103 A G-expression for the allocation strategy to be used. This is a
33104 procedure that takes the datastore as an argument and populates the
33105 allocation plan in the database.
33107 @item @code{hooks} (default: @var{'()})
33108 An association list of hooks. These provide a way to execute arbitrary
33109 code upon certain events, like a build result being processed.
33111 @item @code{guile} (default: @code{guile-3.0-latest})
33112 The Guile package with which to run the Guix Build Coordinator.
33117 @defvar {Scheme Variable} guix-build-coordinator-agent-service-type
33118 Service type for a Guix Build Coordinator agent. Its value must be a
33119 @code{guix-build-coordinator-agent-configuration} object.
33122 @deftp {Data Type} guix-build-coordinator-agent-configuration
33123 Data type representing the configuration a Guix Build Coordinator agent.
33126 @item @code{package} (default: @code{guix-build-coordinator/agent-only})
33127 The Guix Build Coordinator package to use.
33129 @item @code{user} (default: @code{"guix-build-coordinator-agent"})
33130 The system user to run the service as.
33132 @item @code{coordinator} (default: @code{"http://localhost:8745"})
33133 The URI to use when connecting to the coordinator.
33135 @item @code{authentication}
33136 Record describing how this agent should authenticate with the
33137 coordinator. Possible record types are described below.
33139 @item @code{systems} (default: @code{#f})
33140 The systems for which this agent should fetch builds. The agent process
33141 will use the current system it's running on as the default.
33143 @item @code{max-parallel-builds} (default: @code{1})
33144 The number of builds to perform in parallel.
33146 @item @code{max-1min-load-average} (default: @code{#f})
33147 Load average value to look at when considering starting new builds, if
33148 the 1 minute load average exceeds this value, the agent will wait before
33149 starting new builds.
33151 This will be unspecified if the value is @code{#f}, and the agent will
33152 use the number of cores reported by the system as the max 1 minute load
33155 @item @code{derivation-substitute-urls} (default: @code{#f})
33156 URLs from which to attempt to fetch substitutes for derivations, if the
33157 derivations aren't already available.
33159 @item @code{non-derivation-substitute-urls} (default: @code{#f})
33160 URLs from which to attempt to fetch substitutes for build inputs, if the
33161 input store items aren't already available.
33166 @deftp {Data Type} guix-build-coordinator-agent-password-auth
33167 Data type representing an agent authenticating with a coordinator via a
33172 The UUID of the agent. This should be generated by the coordinator
33173 process, stored in the coordinator database, and used by the intended
33176 @item @code{password}
33177 The password to use when connecting to the coordinator.
33182 @deftp {Data Type} guix-build-coordinator-agent-password-file-auth
33183 Data type representing an agent authenticating with a coordinator via a
33184 UUID and password read from a file.
33188 The UUID of the agent. This should be generated by the coordinator
33189 process, stored in the coordinator database, and used by the intended
33192 @item @code{password-file}
33193 A file containing the password to use when connecting to the
33199 @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth
33200 Data type representing an agent authenticating with a coordinator via a
33201 dynamic auth token and agent name.
33204 @item @code{agent-name}
33205 Name of an agent, this is used to match up to an existing entry in the
33206 database if there is one. When no existing entry is found, a new entry
33207 is automatically added.
33210 Dynamic auth token, this is created and stored in the coordinator
33211 database, and is used by the agent to authenticate.
33216 @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth-with-file
33217 Data type representing an agent authenticating with a coordinator via a
33218 dynamic auth token read from a file and agent name.
33221 @item @code{agent-name}
33222 Name of an agent, this is used to match up to an existing entry in the
33223 database if there is one. When no existing entry is found, a new entry
33224 is automatically added.
33226 @item @code{token-file}
33227 File containing the dynamic auth token, this is created and stored in
33228 the coordinator database, and is used by the agent to authenticate.
33233 The Guix Build Coordinator package contains a script to query an
33234 instance of the Guix Data Service for derivations to build, and then
33235 submit builds for those derivations to the coordinator. The service
33236 type below assists in running this script. This is an additional tool
33237 that may be useful when building derivations contained within an
33238 instance of the Guix Data Service.
33240 @defvar {Scheme Variable} guix-build-coordinator-queue-builds-service-type
33241 Service type for the
33242 guix-build-coordinator-queue-builds-from-guix-data-service script. Its
33243 value must be a @code{guix-build-coordinator-queue-builds-configuration}
33247 @deftp {Data Type} guix-build-coordinator-queue-builds-configuration
33248 Data type representing the options to the queue builds from guix data
33252 @item @code{package} (default: @code{guix-build-coordinator})
33253 The Guix Build Coordinator package to use.
33255 @item @code{user} (default: @code{"guix-build-coordinator-queue-builds"})
33256 The system user to run the service as.
33258 @item @code{coordinator} (default: @code{"http://localhost:8746"})
33259 The URI to use when connecting to the coordinator.
33261 @item @code{systems} (default: @code{#f})
33262 The systems for which to fetch derivations to build.
33264 @item @code{systems-and-targets} (default: @code{#f})
33265 An association list of system and target pairs for which to fetch
33266 derivations to build.
33268 @item @code{guix-data-service} (default: @code{"https://data.guix.gnu.org"})
33269 The Guix Data Service instance from which to query to find out about
33270 derivations to build.
33272 @item @code{processed-commits-file} (default: @code{"/var/cache/guix-build-coordinator-queue-builds/processed-commits"})
33273 A file to record which commits have been processed, to avoid needlessly
33274 processing them again if the service is restarted.
33279 @subsubheading Guix Data Service
33280 The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores
33281 and provides data about GNU Guix. This includes information about
33282 packages, derivations and lint warnings.
33284 The data is stored in a PostgreSQL database, and available through a web
33287 @defvar {Scheme Variable} guix-data-service-type
33288 Service type for the Guix Data Service. Its value must be a
33289 @code{guix-data-service-configuration} object. The service optionally
33290 extends the getmail service, as the guix-commits mailing list is used to
33291 find out about changes in the Guix git repository.
33294 @deftp {Data Type} guix-data-service-configuration
33295 Data type representing the configuration of the Guix Data Service.
33298 @item @code{package} (default: @code{guix-data-service})
33299 The Guix Data Service package to use.
33301 @item @code{user} (default: @code{"guix-data-service"})
33302 The system user to run the service as.
33304 @item @code{group} (default: @code{"guix-data-service"})
33305 The system group to run the service as.
33307 @item @code{port} (default: @code{8765})
33308 The port to bind the web service to.
33310 @item @code{host} (default: @code{"127.0.0.1"})
33311 The host to bind the web service to.
33313 @item @code{getmail-idle-mailboxes} (default: @code{#f})
33314 If set, this is the list of mailboxes that the getmail service will be
33315 configured to listen to.
33317 @item @code{commits-getmail-retriever-configuration} (default: @code{#f})
33318 If set, this is the @code{getmail-retriever-configuration} object with
33319 which to configure getmail to fetch mail from the guix-commits mailing
33322 @item @code{extra-options} (default: @var{'()})
33323 Extra command line options for @code{guix-data-service}.
33325 @item @code{extra-process-jobs-options} (default: @var{'()})
33326 Extra command line options for @code{guix-data-service-process-jobs}.
33331 @node Linux Services
33332 @subsection Linux Services
33335 @cindex out of memory killer
33337 @cindex early out of memory daemon
33338 @subsubheading Early OOM Service
33340 @uref{https://github.com/rfjakob/earlyoom,Early OOM}, also known as
33341 Earlyoom, is a minimalist out of memory (OOM) daemon that runs in user
33342 space and provides a more responsive and configurable alternative to the
33343 in-kernel OOM killer. It is useful to prevent the system from becoming
33344 unresponsive when it runs out of memory.
33346 @deffn {Scheme Variable} earlyoom-service-type
33347 The service type for running @command{earlyoom}, the Early OOM daemon.
33348 Its value must be a @code{earlyoom-configuration} object, described
33349 below. The service can be instantiated in its default configuration
33353 (service earlyoom-service-type)
33357 @deftp {Data Type} earlyoom-configuration
33358 This is the configuration record for the @code{earlyoom-service-type}.
33361 @item @code{earlyoom} (default: @var{earlyoom})
33362 The Earlyoom package to use.
33364 @item @code{minimum-available-memory} (default: @code{10})
33365 The threshold for the minimum @emph{available} memory, in percentages.
33367 @item @code{minimum-free-swap} (default: @code{10})
33368 The threshold for the minimum free swap memory, in percentages.
33370 @item @code{prefer-regexp} (default: @code{#f})
33371 A regular expression (as a string) to match the names of the processes
33372 that should be preferably killed.
33374 @item @code{avoid-regexp} (default: @code{#f})
33375 A regular expression (as a string) to match the names of the processes
33376 that should @emph{not} be killed.
33378 @item @code{memory-report-interval} (default: @code{0})
33379 The interval in seconds at which a memory report is printed. It is
33380 disabled by default.
33382 @item @code{ignore-positive-oom-score-adj?} (default: @code{#f})
33383 A boolean indicating whether the positive adjustments set in
33384 @file{/proc/*/oom_score_adj} should be ignored.
33386 @item @code{show-debug-messages?} (default: @code{#f})
33387 A boolean indicating whether debug messages should be printed. The logs
33388 are saved at @file{/var/log/earlyoom.log}.
33390 @item @code{send-notification-command} (default: @code{#f})
33391 This can be used to provide a custom command used for sending
33397 @cindex kernel module loader
33398 @subsubheading Kernel Module Loader Service
33400 The kernel module loader service allows one to load loadable kernel
33401 modules at boot. This is especially useful for modules that don't
33402 autoload and need to be manually loaded, as is the case with
33405 @deffn {Scheme Variable} kernel-module-loader-service-type
33406 The service type for loading loadable kernel modules at boot with
33407 @command{modprobe}. Its value must be a list of strings representing
33408 module names. For example loading the drivers provided by
33409 @code{ddcci-driver-linux}, in debugging mode by passing some module
33410 parameters, can be done as follow:
33413 (use-modules (gnu) (gnu services))
33414 (use-package-modules linux)
33415 (use-service-modules linux)
33417 (define ddcci-config
33418 (plain-file "ddcci.conf"
33419 "options ddcci dyndbg delay=120"))
33423 (services (cons* (service kernel-module-loader-service-type
33424 '("ddcci" "ddcci_backlight"))
33425 (simple-service 'ddcci-config etc-service-type
33426 (list `("modprobe.d/ddcci.conf"
33429 (kernel-loadable-modules (list ddcci-driver-linux)))
33434 @cindex Platform Reliability, Availability and Serviceability daemon
33435 @subsubheading Rasdaemon Service
33437 The Rasdaemon service provides a daemon which monitors platform
33438 @acronym{RAS, Reliability@comma{} Availability@comma{} and Serviceability} reports from
33439 Linux kernel trace events, logging them to syslogd.
33441 Reliability, Availability and Serviceability is a concept used on servers meant
33442 to measure their robustness.
33444 @strong{Relability} is the probability that a system will produce correct
33448 @item Generally measured as Mean Time Between Failures (MTBF), and
33449 @item Enhanced by features that help to avoid, detect and repair hardware
33453 @strong{Availability} is the probability that a system is operational at a
33457 @item Generally measured as a percentage of downtime per a period of time, and
33458 @item Often uses mechanisms to detect and correct hardware faults in runtime.
33461 @strong{Serviceability} is the simplicity and speed with which a system can be
33462 repaired or maintained:
33465 @item Generally measured on Mean Time Between Repair (MTBR).
33469 Among the monitoring measures, the most usual ones include:
33472 @item CPU – detect errors at instruction execution and at L1/L2/L3 caches;
33473 @item Memory – add error correction logic (ECC) to detect and correct errors;
33474 @item I/O – add CRC checksums for transferred data;
33475 @item Storage – RAID, journal file systems, checksums, Self-Monitoring,
33476 Analysis and Reporting Technology (SMART).
33479 By monitoring the number of occurrences of error detections, it is possible to
33480 identify if the probability of hardware errors is increasing, and, on such
33481 case, do a preventive maintenance to replace a degraded component while those
33482 errors are correctable.
33484 For detailed information about the types of error events gathered and how to
33485 make sense of them, see the kernel administrator's guide at
33486 @url{https://www.kernel.org/doc/html/latest/admin-guide/ras.html}.
33488 @defvr {Scheme Variable} rasdaemon-service-type
33489 Service type for the @command{rasdaemon} service. It accepts a
33490 @code{rasdaemon-configuration} object. Instantiating like
33493 (service rasdaemon-service-type)
33496 will load with a default configuration, which monitors all events and logs to
33500 @deftp {Data Type} rasdaemon-configuration
33501 The data type representing the configuration of @command{rasdaemon}.
33504 @item @code{record?} (default: @code{#f})
33506 A boolean indicating whether to record the events in an SQLite database. This
33507 provides a more structured access to the information contained in the log file.
33508 The database location is hard-coded to @file{/var/lib/rasdaemon/ras-mc_event.db}.
33514 @cindex compressed swap
33515 @cindex Compressed RAM-based block devices
33516 @subsubheading Zram Device Service
33518 The Zram device service provides a compressed swap device in system
33519 memory. The Linux Kernel documentation has more information about
33520 @uref{https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html,zram}
33523 @deffn {Scheme Variable} zram-device-service-type
33524 This service creates the zram block device, formats it as swap and
33525 enables it as a swap device. The service's value is a
33526 @code{zram-device-configuration} record.
33528 @deftp {Data Type} zram-device-configuration
33529 This is the data type representing the configuration for the zram-device
33533 @item @code{size} (default @code{"1G"})
33534 This is the amount of space you wish to provide for the zram device. It
33535 accepts a string and can be a number of bytes or use a suffix, eg.:
33536 @code{"512M"} or @code{1024000}.
33537 @item @code{compression-algorithm} (default @code{'lzo})
33538 This is the compression algorithm you wish to use. It is difficult to
33539 list all the possible compression options, but common ones supported by
33540 Guix's Linux Libre Kernel include @code{'lzo}, @code{'lz4} and @code{'zstd}.
33541 @item @code{memory-limit} (default @code{0})
33542 This is the maximum amount of memory which the zram device can use.
33543 Setting it to '0' disables the limit. While it is generally expected
33544 that compression will be 2:1, it is possible that uncompressable data
33545 can be written to swap and this is a method to limit how much memory can
33546 be used. It accepts a string and can be a number of bytes or use a
33547 suffix, eg.: @code{"2G"}.
33548 @item @code{priority} (default @code{-1})
33549 This is the priority of the swap device created from the zram device.
33550 @code{swapon} accepts values between -1 and 32767, with higher values
33551 indicating higher priority. Higher priority swap will generally be used
33558 @node Hurd Services
33559 @subsection Hurd Services
33561 @defvr {Scheme Variable} hurd-console-service-type
33562 This service starts the fancy @code{VGA} console client on the Hurd.
33564 The service's value is a @code{hurd-console-configuration} record.
33567 @deftp {Data Type} hurd-console-configuration
33568 This is the data type representing the configuration for the
33569 hurd-console-service.
33572 @item @code{hurd} (default: @var{hurd})
33573 The Hurd package to use.
33577 @defvr {Scheme Variable} hurd-getty-service-type
33578 This service starts a tty using the Hurd @code{getty} program.
33580 The service's value is a @code{hurd-getty-configuration} record.
33583 @deftp {Data Type} hurd-getty-configuration
33584 This is the data type representing the configuration for the
33585 hurd-getty-service.
33588 @item @code{hurd} (default: @var{hurd})
33589 The Hurd package to use.
33592 The name of the console this Getty runs on---e.g., @code{"tty1"}.
33594 @item @code{baud-rate} (default: @code{38400})
33595 An integer specifying the baud rate of the tty.
33600 @node Miscellaneous Services
33601 @subsection Miscellaneous Services
33603 @cindex fingerprint
33604 @subsubheading Fingerprint Service
33606 The @code{(gnu services authentication)} module provides a DBus service to
33607 read and identify fingerprints via a fingerprint sensor.
33609 @defvr {Scheme Variable} fprintd-service-type
33610 The service type for @command{fprintd}, which provides the fingerprint
33611 reading capability.
33614 (service fprintd-service-type)
33619 @subsubheading System Control Service
33621 The @code{(gnu services sysctl)} provides a service to configure kernel
33622 parameters at boot.
33624 @defvr {Scheme Variable} sysctl-service-type
33625 The service type for @command{sysctl}, which modifies kernel parameters
33626 under @file{/proc/sys/}. To enable IPv4 forwarding, it can be
33630 (service sysctl-service-type
33631 (sysctl-configuration
33632 (settings '(("net.ipv4.ip_forward" . "1")))))
33635 Since @code{sysctl-service-type} is used in the default lists of
33636 services, @code{%base-services} and @code{%desktop-services}, you can
33637 use @code{modify-services} to change its configuration and add the
33638 kernel parameters that you want (@pxref{Service Reference,
33639 @code{modify-services}}).
33642 (modify-services %base-services
33643 (sysctl-service-type config =>
33644 (sysctl-configuration
33645 (settings (append '(("net.ipv4.ip_forward" . "1"))
33646 %default-sysctl-settings)))))
33651 @deftp {Data Type} sysctl-configuration
33652 The data type representing the configuration of @command{sysctl}.
33655 @item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
33656 The @command{sysctl} executable to use.
33658 @item @code{settings} (default: @code{%default-sysctl-settings})
33659 An association list specifies kernel parameters and their values.
33663 @defvr {Scheme Variable} %default-sysctl-settings
33664 An association list specifying the default @command{sysctl} parameters
33669 @subsubheading PC/SC Smart Card Daemon Service
33671 The @code{(gnu services security-token)} module provides the following service
33672 to run @command{pcscd}, the PC/SC Smart Card Daemon. @command{pcscd} is the
33673 daemon program for pcsc-lite and the MuscleCard framework. It is a resource
33674 manager that coordinates communications with smart card readers, smart cards
33675 and cryptographic tokens that are connected to the system.
33677 @defvr {Scheme Variable} pcscd-service-type
33678 Service type for the @command{pcscd} service. Its value must be a
33679 @code{pcscd-configuration} object. To run pcscd in the default
33680 configuration, instantiate it as:
33683 (service pcscd-service-type)
33687 @deftp {Data Type} pcscd-configuration
33688 The data type representing the configuration of @command{pcscd}.
33691 @item @code{pcsc-lite} (default: @code{pcsc-lite})
33692 The pcsc-lite package that provides pcscd.
33693 @item @code{usb-drivers} (default: @code{(list ccid)})
33694 List of packages that provide USB drivers to pcscd. Drivers are expected to be
33695 under @file{pcsc/drivers} in the store directory of the package.
33700 @subsubheading Lirc Service
33702 The @code{(gnu services lirc)} module provides the following service.
33704 @deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
33705 [#:device #f] [#:driver #f] [#:config-file #f] @
33706 [#:extra-options '()]
33707 Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
33708 decodes infrared signals from remote controls.
33710 Optionally, @var{device}, @var{driver} and @var{config-file}
33711 (configuration file name) may be specified. See @command{lircd} manual
33714 Finally, @var{extra-options} is a list of additional command-line options
33715 passed to @command{lircd}.
33719 @subsubheading Spice Service
33721 The @code{(gnu services spice)} module provides the following service.
33723 @deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
33724 Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon
33725 that enables sharing the clipboard with a vm and setting the guest display
33726 resolution when the graphical console window resizes.
33729 @cindex inputattach
33730 @subsubheading inputattach Service
33732 @cindex tablet input, for Xorg
33733 @cindex touchscreen input, for Xorg
33734 The @uref{https://linuxwacom.github.io/, inputattach} service allows you to
33735 use input devices such as Wacom tablets, touchscreens, or joysticks with the
33736 Xorg display server.
33738 @deffn {Scheme Variable} inputattach-service-type
33739 Type of a service that runs @command{inputattach} on a device and
33740 dispatches events from it.
33743 @deftp {Data Type} inputattach-configuration
33745 @item @code{device-type} (default: @code{"wacom"})
33746 The type of device to connect to. Run @command{inputattach --help}, from the
33747 @code{inputattach} package, to see the list of supported device types.
33749 @item @code{device} (default: @code{"/dev/ttyS0"})
33750 The device file to connect to the device.
33752 @item @code{baud-rate} (default: @code{#f})
33753 Baud rate to use for the serial connection.
33754 Should be a number or @code{#f}.
33756 @item @code{log-file} (default: @code{#f})
33757 If true, this must be the name of a file to log messages to.
33761 @subsubheading Dictionary Service
33763 The @code{(gnu services dict)} module provides the following service:
33765 @defvr {Scheme Variable} dicod-service-type
33766 This is the type of the service that runs the @command{dicod} daemon, an
33767 implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
33770 @deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
33771 Return a service that runs the @command{dicod} daemon, an implementation
33772 of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
33774 The optional @var{config} argument specifies the configuration for
33775 @command{dicod}, which should be a @code{<dicod-configuration>} object, by
33776 default it serves the GNU Collaborative International Dictionary of English.
33778 You can add @command{open localhost} to your @file{~/.dico} file to make
33779 @code{localhost} the default server for @command{dico} client
33780 (@pxref{Initialization File,,, dico, GNU Dico Manual}).
33783 @deftp {Data Type} dicod-configuration
33784 Data type representing the configuration of dicod.
33787 @item @code{dico} (default: @var{dico})
33788 Package object of the GNU Dico dictionary server.
33790 @item @code{interfaces} (default: @var{'("localhost")})
33791 This is the list of IP addresses and ports and possibly socket file
33792 names to listen to (@pxref{Server Settings, @code{listen} directive,,
33793 dico, GNU Dico Manual}).
33795 @item @code{handlers} (default: @var{'()})
33796 List of @code{<dicod-handler>} objects denoting handlers (module instances).
33798 @item @code{databases} (default: @var{(list %dicod-database:gcide)})
33799 List of @code{<dicod-database>} objects denoting dictionaries to be served.
33803 @deftp {Data Type} dicod-handler
33804 Data type representing a dictionary handler (module instance).
33808 Name of the handler (module instance).
33810 @item @code{module} (default: @var{#f})
33811 Name of the dicod module of the handler (instance). If it is @code{#f},
33812 the module has the same name as the handler.
33813 (@pxref{Modules,,, dico, GNU Dico Manual}).
33815 @item @code{options}
33816 List of strings or gexps representing the arguments for the module handler
33820 @deftp {Data Type} dicod-database
33821 Data type representing a dictionary database.
33825 Name of the database, will be used in DICT commands.
33827 @item @code{handler}
33828 Name of the dicod handler (module instance) used by this database
33829 (@pxref{Handlers,,, dico, GNU Dico Manual}).
33831 @item @code{complex?} (default: @var{#f})
33832 Whether the database configuration complex. The complex configuration
33833 will need a corresponding @code{<dicod-handler>} object, otherwise not.
33835 @item @code{options}
33836 List of strings or gexps representing the arguments for the database
33837 (@pxref{Databases,,, dico, GNU Dico Manual}).
33841 @defvr {Scheme Variable} %dicod-database:gcide
33842 A @code{<dicod-database>} object serving the GNU Collaborative International
33843 Dictionary of English using the @code{gcide} package.
33846 The following is an example @code{dicod-service} configuration.
33849 (dicod-service #:config
33850 (dicod-configuration
33851 (handlers (list (dicod-handler
33855 (list #~(string-append "dbdir=" #$wordnet))))))
33856 (databases (list (dicod-database
33859 (handler "wordnet")
33860 (options '("database=wn")))
33861 %dicod-database:gcide))))
33865 @subsubheading Docker Service
33867 The @code{(gnu services docker)} module provides the following services.
33869 @defvr {Scheme Variable} docker-service-type
33871 This is the type of the service that runs @url{https://www.docker.com,Docker},
33872 a daemon that can execute application bundles (sometimes referred to as
33873 ``containers'') in isolated environments.
33877 @deftp {Data Type} docker-configuration
33878 This is the data type representing the configuration of Docker and Containerd.
33882 @item @code{docker} (default: @code{docker})
33883 The Docker daemon package to use.
33885 @item @code{docker-cli} (default: @code{docker-cli})
33886 The Docker client package to use.
33888 @item @code{containerd} (default: @var{containerd})
33889 The Containerd package to use.
33891 @item @code{proxy} (default @var{docker-libnetwork-cmd-proxy})
33892 The Docker user-land networking proxy package to use.
33894 @item @code{enable-proxy?} (default @code{#t})
33895 Enable or disable the use of the Docker user-land networking proxy.
33897 @item @code{debug?} (default @code{#f})
33898 Enable or disable debug output.
33900 @item @code{enable-iptables?} (default @code{#t})
33901 Enable or disable the addition of iptables rules.
33903 @item @code{environment-variables} (default: @code{()})
33904 List of environment variables to set for @command{dockerd}.
33906 This must be a list of strings where each string has the form
33907 @samp{@var{key}=@var{value}} as in this example:
33910 (list "LANGUAGE=eo:ca:eu"
33911 "TMPDIR=/tmp/dockerd")
33917 @cindex Singularity, container service
33918 @defvr {Scheme Variable} singularity-service-type
33919 This is the type of the service that allows you to run
33920 @url{https://www.sylabs.io/singularity/, Singularity}, a Docker-style tool to
33921 create and run application bundles (aka. ``containers''). The value for this
33922 service is the Singularity package to use.
33924 The service does not install a daemon; instead, it installs helper programs as
33925 setuid-root (@pxref{Setuid Programs}) such that unprivileged users can invoke
33926 @command{singularity run} and similar commands.
33930 @subsubheading Auditd Service
33932 The @code{(gnu services auditd)} module provides the following service.
33934 @defvr {Scheme Variable} auditd-service-type
33936 This is the type of the service that runs
33937 @url{https://people.redhat.com/sgrubb/audit/,auditd},
33938 a daemon that tracks security-relevant information on your system.
33940 Examples of things that can be tracked:
33950 Failed login attempts
33957 @command{auditctl} from the @code{audit} package can be used in order
33958 to add or remove events to be tracked (until the next reboot).
33959 In order to permanently track events, put the command line arguments
33960 of auditctl into a file called @code{audit.rules} in the configuration
33961 directory (see below).
33962 @command{aureport} from the @code{audit} package can be used in order
33963 to view a report of all recorded events.
33964 The audit daemon by default logs into the file
33965 @file{/var/log/audit.log}.
33969 @deftp {Data Type} auditd-configuration
33970 This is the data type representing the configuration of auditd.
33974 @item @code{audit} (default: @code{audit})
33975 The audit package to use.
33977 @item @code{configuration-directory} (default: @code{%default-auditd-configuration-directory})
33978 The directory containing the configuration file for the audit package, which
33979 must be named @code{auditd.conf}, and optionally some audit rules to
33980 instantiate on startup.
33986 @subsubheading R-Shiny service
33988 The @code{(gnu services science)} module provides the following service.
33990 @defvr {Scheme Variable} rshiny-service-type
33992 This is a type of service which is used to run a webapp created with
33993 @code{r-shiny}. This service sets the @env{R_LIBS_USER} environment
33994 variable and runs the provided script to call @code{runApp}.
33996 @deftp {Data Type} rshiny-configuration
33997 This is the data type representing the configuration of rshiny.
34001 @item @code{package} (default: @code{r-shiny})
34002 The package to use.
34004 @item @code{binary} (defaunlt @code{"rshiny"})
34005 The name of the binary or shell script located at @code{package/bin/} to
34006 run when the service is run.
34008 The common way to create this file is as follows:
34012 (let* ((out (assoc-ref %outputs "out"))
34013 (targetdir (string-append out "/share/" ,name))
34014 (app (string-append out "/bin/" ,name))
34015 (Rbin (search-input-file %build-inputs "/bin/Rscript")))
34017 (mkdir-p (string-append out "/bin"))
34018 (call-with-output-file app
34024 runApp(launch.browser=0, port=4202)~%\n"
34033 @subsubheading Nix service
34035 The @code{(gnu services nix)} module provides the following service.
34037 @defvr {Scheme Variable} nix-service-type
34039 This is the type of the service that runs build daemon of the
34040 @url{https://nixos.org/nix/, Nix} package manager. Here is an example showing
34044 (use-modules (gnu))
34045 (use-service-modules nix)
34046 (use-package-modules package-management)
34050 (packages (append (list nix)
34053 (services (append (list (service nix-service-type))
34057 After @command{guix system reconfigure} configure Nix for your user:
34060 @item Add a Nix channel and update it. See
34061 @url{https://nixos.org/nix/manual/, Nix Package Manager Guide}.
34063 @item Create a symlink to your profile and activate Nix profile:
34067 $ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile
34068 $ source /run/current-system/profile/etc/profile.d/nix.sh
34073 @deftp {Data Type} nix-configuration
34074 This data type represents the configuration of the Nix daemon.
34077 @item @code{nix} (default: @code{nix})
34078 The Nix package to use.
34080 @item @code{sandbox} (default: @code{#t})
34081 Specifies whether builds are sandboxed by default.
34083 @item @code{build-sandbox-items} (default: @code{'()})
34084 This is a list of strings or objects appended to the
34085 @code{build-sandbox-items} field of the configuration file.
34087 @item @code{extra-config} (default: @code{'()})
34088 This is a list of strings or objects appended to the configuration file.
34089 It is used to pass extra text to be added verbatim to the configuration
34092 @item @code{extra-options} (default: @code{'()})
34093 Extra command line options for @code{nix-service-type}.
34097 @node Setuid Programs
34098 @section Setuid Programs
34100 @cindex setuid programs
34101 Some programs need to run with ``root'' privileges, even when they are
34102 launched by unprivileged users. A notorious example is the
34103 @command{passwd} program, which users can run to change their
34104 password, and which needs to access the @file{/etc/passwd} and
34105 @file{/etc/shadow} files---something normally restricted to root, for
34106 obvious security reasons. To address that, these executables are
34107 @dfn{setuid-root}, meaning that they always run with root privileges
34108 (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
34109 for more info about the setuid mechanism).
34111 The store itself @emph{cannot} contain setuid programs: that would be a
34112 security issue since any user on the system can write derivations that
34113 populate the store (@pxref{The Store}). Thus, a different mechanism is
34114 used: instead of changing the setuid bit directly on files that are in
34115 the store, we let the system administrator @emph{declare} which programs
34116 should be setuid root.
34118 The @code{setuid-programs} field of an @code{operating-system}
34119 declaration contains a list of @code{<setuid-program>} denoting the
34120 names of programs to have a setuid or setgid bit set (@pxref{Using the
34121 Configuration System}). For instance, the @command{mount.nfs} program,
34122 which is part of the nfs-utils package, with a setuid root can be
34123 designated like this:
34127 (program (file-append nfs-utils "/sbin/mount.nfs")))
34130 And then, to make @command{mount.nfs} setuid on your system, add the
34131 previous example to your operating system declaration by appending it to
34132 @code{%setuid-programs} like this:
34136 (append (list (setuid-program
34137 (program (file-append nfs-utils "/sbin/mount.nfs"))))
34141 @deftp {Data Type} setuid-program
34142 This data type represents a program with a setuid or setgid bit set.
34145 @item @code{program}
34146 A file-like object having its setuid and/or setgid bit set.
34148 @item @code{setuid?} (default: @code{#t})
34149 Whether to set user setuid bit.
34151 @item @code{setgid?} (default: @code{#f})
34152 Whether to set group setgid bit.
34154 @item @code{user} (default: @code{0})
34155 UID (integer) or user name (string) for the user owner of the program,
34158 @item @code{group} (default: @code{0})
34159 GID (integer) goup name (string) for the group owner of the program,
34165 A default set of setuid programs is defined by the
34166 @code{%setuid-programs} variable of the @code{(gnu system)} module.
34168 @defvr {Scheme Variable} %setuid-programs
34169 A list of @code{<setuid-program>} denoting common programs that are
34172 The list includes commands such as @command{passwd}, @command{ping},
34173 @command{su}, and @command{sudo}.
34176 Under the hood, the actual setuid programs are created in the
34177 @file{/run/setuid-programs} directory at system activation time. The
34178 files in this directory refer to the ``real'' binaries, which are in the
34181 @node X.509 Certificates
34182 @section X.509 Certificates
34184 @cindex HTTPS, certificates
34185 @cindex X.509 certificates
34187 Web servers available over HTTPS (that is, HTTP over the transport-layer
34188 security mechanism, TLS) send client programs an @dfn{X.509 certificate}
34189 that the client can then use to @emph{authenticate} the server. To do
34190 that, clients verify that the server's certificate is signed by a
34191 so-called @dfn{certificate authority} (CA). But to verify the CA's
34192 signature, clients must have first acquired the CA's certificate.
34194 Web browsers such as GNU@tie{}IceCat include their own set of CA
34195 certificates, such that they are able to verify CA signatures
34198 However, most other programs that can talk HTTPS---@command{wget},
34199 @command{git}, @command{w3m}, etc.---need to be told where CA
34200 certificates can be found.
34202 @cindex @code{nss-certs}
34203 In Guix, this is done by adding a package that provides certificates
34204 to the @code{packages} field of the @code{operating-system} declaration
34205 (@pxref{operating-system Reference}). Guix includes one such package,
34206 @code{nss-certs}, which is a set of CA certificates provided as part of
34207 Mozilla's Network Security Services.
34209 Note that it is @emph{not} part of @code{%base-packages}, so you need to
34210 explicitly add it. The @file{/etc/ssl/certs} directory, which is where
34211 most applications and libraries look for certificates by default, points
34212 to the certificates installed globally.
34214 Unprivileged users, including users of Guix on a foreign distro,
34215 can also install their own certificate package in
34216 their profile. A number of environment variables need to be defined so
34217 that applications and libraries know where to find them. Namely, the
34218 OpenSSL library honors the @env{SSL_CERT_DIR} and @env{SSL_CERT_FILE}
34219 variables. Some applications add their own environment variables; for
34220 instance, the Git version control system honors the certificate bundle
34221 pointed to by the @env{GIT_SSL_CAINFO} environment variable. Thus, you
34222 would typically run something like:
34225 guix install nss-certs
34226 export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
34227 export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
34228 export GIT_SSL_CAINFO="$SSL_CERT_FILE"
34231 As another example, R requires the @env{CURL_CA_BUNDLE} environment
34232 variable to point to a certificate bundle, so you would have to run
34233 something like this:
34236 guix install nss-certs
34237 export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
34240 For other applications you may want to look up the required environment
34241 variable in the relevant documentation.
34244 @node Name Service Switch
34245 @section Name Service Switch
34247 @cindex name service switch
34249 The @code{(gnu system nss)} module provides bindings to the
34250 configuration file of the libc @dfn{name service switch} or @dfn{NSS}
34251 (@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
34252 Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
34253 extended with new ``name'' lookup methods for system databases, which
34254 includes host names, service names, user accounts, and more (@pxref{Name
34255 Service Switch, System Databases and Name Service Switch,, libc, The GNU
34256 C Library Reference Manual}).
34258 The NSS configuration specifies, for each system database, which lookup
34259 method is to be used, and how the various methods are chained
34260 together---for instance, under which circumstances NSS should try the
34261 next method in the list. The NSS configuration is given in the
34262 @code{name-service-switch} field of @code{operating-system} declarations
34263 (@pxref{operating-system Reference, @code{name-service-switch}}).
34266 @cindex .local, host name lookup
34267 As an example, the declaration below configures the NSS to use the
34268 @uref{https://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
34269 back-end}, which supports host name lookups over multicast DNS (mDNS)
34270 for host names ending in @code{.local}:
34273 (name-service-switch
34274 (hosts (list %files ;first, check /etc/hosts
34276 ;; If the above did not succeed, try
34277 ;; with 'mdns_minimal'.
34279 (name "mdns_minimal")
34281 ;; 'mdns_minimal' is authoritative for
34282 ;; '.local'. When it returns "not found",
34283 ;; no need to try the next methods.
34284 (reaction (lookup-specification
34285 (not-found => return))))
34287 ;; Then fall back to DNS.
34291 ;; Finally, try with the "full" 'mdns'.
34296 Do not worry: the @code{%mdns-host-lookup-nss} variable (see below)
34297 contains this configuration, so you will not have to type it if all you
34298 want is to have @code{.local} host lookup working.
34300 Note that, in this case, in addition to setting the
34301 @code{name-service-switch} of the @code{operating-system} declaration,
34302 you also need to use @code{avahi-service-type} (@pxref{Networking Services,
34303 @code{avahi-service-type}}), or @code{%desktop-services}, which includes it
34304 (@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible
34305 to the name service cache daemon (@pxref{Base Services,
34306 @code{nscd-service}}).
34308 For convenience, the following variables provide typical NSS
34311 @defvr {Scheme Variable} %default-nss
34312 This is the default name service switch configuration, a
34313 @code{name-service-switch} object.
34316 @defvr {Scheme Variable} %mdns-host-lookup-nss
34317 This is the name service switch configuration with support for host name
34318 lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
34321 The reference for name service switch configuration is given below. It
34322 is a direct mapping of the configuration file format of the C library , so
34323 please refer to the C library manual for more information (@pxref{NSS
34324 Configuration File,,, libc, The GNU C Library Reference Manual}).
34325 Compared to the configuration file format of libc NSS, it has the advantage
34326 not only of adding this warm parenthetic feel that we like, but also
34327 static checks: you will know about syntax errors and typos as soon as you
34328 run @command{guix system}.
34330 @deftp {Data Type} name-service-switch
34332 This is the data type representation the configuration of libc's name
34333 service switch (NSS). Each field below represents one of the supported
34350 The system databases handled by the NSS@. Each of these fields must be a
34351 list of @code{<name-service>} objects (see below).
34355 @deftp {Data Type} name-service
34357 This is the data type representing an actual name service and the
34358 associated lookup action.
34362 A string denoting the name service (@pxref{Services in the NSS
34363 configuration,,, libc, The GNU C Library Reference Manual}).
34365 Note that name services listed here must be visible to nscd. This is
34366 achieved by passing the @code{#:name-services} argument to
34367 @code{nscd-service} the list of packages providing the needed name
34368 services (@pxref{Base Services, @code{nscd-service}}).
34371 An action specified using the @code{lookup-specification} macro
34372 (@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
34373 Reference Manual}). For example:
34376 (lookup-specification (unavailable => continue)
34377 (success => return))
34382 @node Initial RAM Disk
34383 @section Initial RAM Disk
34386 @cindex initial RAM disk
34387 For bootstrapping purposes, the Linux-Libre kernel is passed an
34388 @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
34389 root file system as well as an initialization script. The latter is
34390 responsible for mounting the real root file system, and for loading any
34391 kernel modules that may be needed to achieve that.
34393 The @code{initrd-modules} field of an @code{operating-system}
34394 declaration allows you to specify Linux-libre kernel modules that must
34395 be available in the initrd. In particular, this is where you would list
34396 modules needed to actually drive the hard disk where your root partition
34397 is---although the default value of @code{initrd-modules} should cover
34398 most use cases. For example, assuming you need the @code{megaraid_sas}
34399 module in addition to the default modules to be able to access your root
34400 file system, you would write:
34405 (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
34408 @defvr {Scheme Variable} %base-initrd-modules
34409 This is the list of kernel modules included in the initrd by default.
34412 Furthermore, if you need lower-level customization, the @code{initrd}
34413 field of an @code{operating-system} declaration allows
34414 you to specify which initrd you would like to use. The @code{(gnu
34415 system linux-initrd)} module provides three ways to build an initrd: the
34416 high-level @code{base-initrd} procedure and the low-level
34417 @code{raw-initrd} and @code{expression->initrd} procedures.
34419 The @code{base-initrd} procedure is intended to cover most common uses.
34420 For example, if you want to add a bunch of kernel modules to be loaded
34421 at boot time, you can define the @code{initrd} field of the operating
34422 system declaration like this:
34425 (initrd (lambda (file-systems . rest)
34426 ;; Create a standard initrd but set up networking
34427 ;; with the parameters QEMU expects by default.
34428 (apply base-initrd file-systems
34429 #:qemu-networking? #t
34433 The @code{base-initrd} procedure also handles common use cases that
34434 involves using the system as a QEMU guest, or as a ``live'' system with
34435 volatile root file system.
34437 The @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
34438 Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level,
34439 such as trying to guess which kernel modules and packages should be included
34440 to the initrd. An example use of @code{raw-initrd} is when a user has
34441 a custom Linux kernel configuration and default kernel modules included by
34442 @code{base-initrd} are not available.
34444 The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd}
34445 honors several options passed on the Linux kernel command line
34446 (that is, arguments passed @i{via} the @code{linux} command of GRUB, or the
34447 @code{-append} option of QEMU), notably:
34450 @item --load=@var{boot}
34451 Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
34452 program, once it has mounted the root file system.
34454 Guix uses this option to yield control to a boot program that runs the
34455 service activation programs and then spawns the GNU@tie{}Shepherd, the
34456 initialization system.
34458 @item --root=@var{root}
34459 Mount @var{root} as the root file system. @var{root} can be a device
34460 name like @code{/dev/sda1}, a file system label, or a file system UUID.
34461 When unspecified, the device name from the root file system of the
34462 operating system declaration is used.
34464 @item fsck.mode=@var{mode}
34465 Whether to check the @var{root} file system for errors before mounting
34466 it. @var{mode} is one of @code{skip} (never check), @code{force} (always
34467 check), or @code{auto} to respect the root file-system object's 'check?'
34468 setting (@pxref{File Systems}) and run a full scan only if the file system
34469 was not cleanly shut down.
34471 @code{auto} is the default if this option is not present or if @var{mode}
34472 is not one of the above.
34474 @item fsck.repair=@var{level}
34475 The level of repairs to perform automatically if errors are found in the
34476 @var{root} file system. @var{level} is one of @code{no} (do not write to
34477 @var{root} at all if possible), @code{yes} (repair as much as possible),
34478 or @code{preen} to repair problems considered safe to repair automatically.
34480 @code{preen} is the default if this option is not present or if @var{level}
34481 is not one of the above.
34483 @item --system=@var{system}
34484 Have @file{/run/booted-system} and @file{/run/current-system} point to
34487 @item modprobe.blacklist=@var{modules}@dots{}
34488 @cindex module, black-listing
34489 @cindex black list, of kernel modules
34490 Instruct the initial RAM disk as well as the @command{modprobe} command
34491 (from the kmod package) to refuse to load @var{modules}. @var{modules}
34492 must be a comma-separated list of module names---e.g.,
34493 @code{usbkbd,9pnet}.
34496 Start a read-eval-print loop (REPL) from the initial RAM disk before it
34497 tries to load kernel modules and to mount the root file system. Our
34498 marketing team calls it @dfn{boot-to-Guile}. The Schemer in you will
34499 love it. @xref{Using Guile Interactively,,, guile, GNU Guile Reference
34500 Manual}, for more information on Guile's REPL.
34504 Now that you know all the features that initial RAM disks produced by
34505 @code{base-initrd} and @code{raw-initrd} provide,
34506 here is how to use it and customize it further.
34509 @cindex initial RAM disk
34510 @deffn {Scheme Procedure} raw-initrd @var{file-systems} @
34511 [#:linux-modules '()] [#:mapped-devices '()] @
34512 [#:keyboard-layout #f] @
34513 [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]
34514 Return a derivation that builds a raw initrd. @var{file-systems} is
34515 a list of file systems to be mounted by the initrd, possibly in addition to
34516 the root file system specified on the kernel command line via @option{--root}.
34517 @var{linux-modules} is a list of kernel modules to be loaded at boot time.
34518 @var{mapped-devices} is a list of device mappings to realize before
34519 @var{file-systems} are mounted (@pxref{Mapped Devices}).
34520 @var{helper-packages} is a list of packages to be copied in the initrd.
34522 include @code{e2fsck/static} or other packages needed by the initrd to check
34523 the root file system.
34525 When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
34526 the desired console keyboard layout. This is done before @var{mapped-devices}
34527 are set up and before @var{file-systems} are mounted such that, should the
34528 user need to enter a passphrase or use the REPL, this happens using the
34529 intended keyboard layout.
34531 When @var{qemu-networking?} is true, set up networking with the standard QEMU
34532 parameters. When @var{virtio?} is true, load additional modules so that the
34533 initrd can be used as a QEMU guest with para-virtualized I/O drivers.
34535 When @var{volatile-root?} is true, the root file system is writable but any changes
34539 @deffn {Scheme Procedure} base-initrd @var{file-systems} @
34540 [#:mapped-devices '()] [#:keyboard-layout #f] @
34541 [#:qemu-networking? #f] [#:volatile-root? #f] @
34542 [#:linux-modules '()]
34543 Return as a file-like object a generic initrd, with kernel
34544 modules taken from @var{linux}. @var{file-systems} is a list of file-systems to be
34545 mounted by the initrd, possibly in addition to the root file system specified
34546 on the kernel command line via @option{--root}. @var{mapped-devices} is a list of device
34547 mappings to realize before @var{file-systems} are mounted.
34549 When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
34550 the desired console keyboard layout. This is done before @var{mapped-devices}
34551 are set up and before @var{file-systems} are mounted such that, should the
34552 user need to enter a passphrase or use the REPL, this happens using the
34553 intended keyboard layout.
34555 @var{qemu-networking?} and @var{volatile-root?} behaves as in @code{raw-initrd}.
34557 The initrd is automatically populated with all the kernel modules necessary
34558 for @var{file-systems} and for the given options. Additional kernel
34559 modules can be listed in @var{linux-modules}. They will be added to the initrd, and
34560 loaded at boot time in the order in which they appear.
34563 Needless to say, the initrds we produce and use embed a
34564 statically-linked Guile, and the initialization program is a Guile
34565 program. That gives a lot of flexibility. The
34566 @code{expression->initrd} procedure builds such an initrd, given the
34567 program to run in that initrd.
34569 @deffn {Scheme Procedure} expression->initrd @var{exp} @
34570 [#:guile %guile-static-stripped] [#:name "guile-initrd"]
34571 Return as a file-like object a Linux initrd (a gzipped cpio archive)
34572 containing @var{guile} and that evaluates @var{exp}, a G-expression,
34573 upon booting. All the derivations referenced by @var{exp} are
34574 automatically copied to the initrd.
34577 @node Bootloader Configuration
34578 @section Bootloader Configuration
34581 @cindex boot loader
34583 The operating system supports multiple bootloaders. The bootloader is
34584 configured using @code{bootloader-configuration} declaration. All the
34585 fields of this structure are bootloader agnostic except for one field,
34586 @code{bootloader} that indicates the bootloader to be configured and
34589 Some of the bootloaders do not honor every field of
34590 @code{bootloader-configuration}. For instance, the extlinux
34591 bootloader does not support themes and thus ignores the @code{theme}
34594 @deftp {Data Type} bootloader-configuration
34595 The type of a bootloader configuration declaration.
34599 @item @code{bootloader}
34600 @cindex EFI, bootloader
34601 @cindex UEFI, bootloader
34602 @cindex BIOS, bootloader
34603 The bootloader to use, as a @code{bootloader} object. For now
34604 @code{grub-bootloader}, @code{grub-efi-bootloader},
34605 @code{grub-efi-netboot-bootloader}, @code{extlinux-bootloader} and
34606 @code{u-boot-bootloader} are supported.
34608 @cindex ARM, bootloaders
34609 @cindex AArch64, bootloaders
34610 Available bootloaders are described in @code{(gnu bootloader @dots{})}
34611 modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
34612 of bootloaders for a wide range of ARM and AArch64 systems, using the
34613 @uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
34615 @vindex grub-efi-bootloader
34616 @code{grub-efi-bootloader} allows to boot on modern systems using the
34617 @dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should
34618 use if the installation image contains a @file{/sys/firmware/efi} directory
34619 when you boot it on your system.
34621 @vindex grub-bootloader
34622 @code{grub-bootloader} allows you to boot in particular Intel-based machines
34623 in ``legacy'' BIOS mode.
34625 @vindex grub-efi-netboot-bootloader
34626 @code{grub-efi-netboot-bootloader} allows you to boot your system over network
34627 through TFTP@. In combination with an NFS root file system this allows you to
34628 build a diskless Guix system.
34630 The installation of the @code{grub-efi-netboot-bootloader} generates the
34631 content of the TFTP root directory at @code{targets} (@pxref{Bootloader
34632 Configuration, @code{targets}}), to be served by a TFTP server. You may
34633 want to mount your TFTP server directories onto the @code{targets} to
34634 move the required files to the TFTP server automatically.
34636 If you plan to use an NFS root file system as well (actually if you mount the
34637 store from an NFS share), then the TFTP server needs to serve the file
34638 @file{/boot/grub/grub.cfg} and other files from the store (like GRUBs background
34639 image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and the
34640 initrd (@pxref{operating-system Reference, @code{initrd}})), too. All these
34641 files from the store will be accessed by GRUB through TFTP with their normal
34642 store path, for example as
34643 @file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.
34645 Two symlinks are created to make this possible. For each target in the
34646 @code{targets} field, the first symlink is
34647 @samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
34648 @file{../../../boot/grub/grub.cfg}, where @samp{target} may be
34649 @file{/boot}. In this case the link is not leaving the served TFTP root
34650 directory, but otherwise it does. The second link is
34651 @samp{target}@file{/gnu/store} and points to @file{../gnu/store}. This
34652 link is leaving the served TFTP root directory.
34654 The assumption behind all this is that you have an NFS server exporting
34655 the root file system for your Guix system, and additionally a TFTP
34656 server exporting your @code{targets} directories—usually a single
34657 @file{/boot}—from that same root file system for your Guix system. In
34658 this constellation the symlinks will work.
34660 For other constellations you will have to program your own bootloader
34661 installer, which then takes care to make necessary files from the store
34662 accessible through TFTP, for example by copying them into the TFTP root
34663 directory to your @code{targets}.
34665 It is important to note that symlinks pointing outside the TFTP root directory
34666 may need to be allowed in the configuration of your TFTP server. Further the
34667 store link exposes the whole store through TFTP@. Both points need to be
34668 considered carefully for security aspects.
34670 Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and
34671 NFS servers, you also need a properly configured DHCP server to make the booting
34672 over netboot possible. For all this we can currently only recommend you to look
34673 for instructions about @acronym{PXE, Preboot eXecution Environment}.
34675 @item @code{targets}
34676 This is a list of strings denoting the targets onto which to install the
34679 The interpretation of targets depends on the bootloader in question.
34680 For @code{grub-bootloader}, for example, they should be device names
34681 understood by the bootloader @command{installer} command, such as
34682 @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
34683 GNU GRUB Manual}). For @code{grub-efi-bootloader}, they should be mount
34684 points of the EFI file system, usually @file{/boot/efi}. For
34685 @code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
34686 points corresponding to TFTP root directories served by your TFTP
34689 @item @code{menu-entries} (default: @code{()})
34690 A possibly empty list of @code{menu-entry} objects (see below), denoting
34691 entries to appear in the bootloader menu, in addition to the current
34692 system entry and the entry pointing to previous system generations.
34694 @item @code{default-entry} (default: @code{0})
34695 The index of the default boot menu entry. Index 0 is for the entry of the
34698 @item @code{timeout} (default: @code{5})
34699 The number of seconds to wait for keyboard input before booting. Set to
34700 0 to boot immediately, and to -1 to wait indefinitely.
34702 @cindex keyboard layout, for the bootloader
34703 @item @code{keyboard-layout} (default: @code{#f})
34704 If this is @code{#f}, the bootloader's menu (if any) uses the default keyboard
34705 layout, usually US@tie{}English (``qwerty'').
34707 Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard
34711 This option is currently ignored by bootloaders other than @code{grub} and
34715 @item @code{theme} (default: @var{#f})
34716 The bootloader theme object describing the theme to use. If no theme
34717 is provided, some bootloaders might use a default theme, that's true
34720 @item @code{terminal-outputs} (default: @code{'(gfxterm)})
34721 The output terminals used for the bootloader boot menu, as a list of
34722 symbols. GRUB accepts the values: @code{console}, @code{serial},
34723 @code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
34724 @code{mda_text}, @code{morse}, and @code{pkmodem}. This field
34725 corresponds to the GRUB variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple
34726 configuration,,, grub,GNU GRUB manual}).
34728 @item @code{terminal-inputs} (default: @code{'()})
34729 The input terminals used for the bootloader boot menu, as a list of
34730 symbols. For GRUB, the default is the native platform terminal as
34731 determined at run-time. GRUB accepts the values: @code{console},
34732 @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
34733 @code{usb_keyboard}. This field corresponds to the GRUB variable
34734 @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB
34737 @item @code{serial-unit} (default: @code{#f})
34738 The serial unit used by the bootloader, as an integer from 0 to 3.
34739 For GRUB, it is chosen at run-time; currently GRUB chooses 0, which
34740 corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
34742 @item @code{serial-speed} (default: @code{#f})
34743 The speed of the serial interface, as an integer. For GRUB, the
34744 default value is chosen at run-time; currently GRUB chooses
34745 9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
34752 Should you want to list additional boot menu entries @i{via} the
34753 @code{menu-entries} field above, you will need to create them with the
34754 @code{menu-entry} form. For example, imagine you want to be able to
34755 boot another distro (hard to imagine!), you can define a menu entry
34760 (label "The Other Distro")
34761 (linux "/boot/old/vmlinux-2.6.32")
34762 (linux-arguments '("root=/dev/sda2"))
34763 (initrd "/boot/old/initrd"))
34768 @deftp {Data Type} menu-entry
34769 The type of an entry in the bootloader menu.
34774 The label to show in the menu---e.g., @code{"GNU"}.
34776 @item @code{linux} (default: @code{#f})
34777 The Linux kernel image to boot, for example:
34780 (file-append linux-libre "/bzImage")
34783 For GRUB, it is also possible to specify a device explicitly in the
34784 file path using GRUB's device naming convention (@pxref{Naming
34785 convention,,, grub, GNU GRUB manual}), for example:
34788 "(hd0,msdos1)/boot/vmlinuz"
34791 If the device is specified explicitly as above, then the @code{device}
34792 field is ignored entirely.
34794 @item @code{linux-arguments} (default: @code{()})
34795 The list of extra Linux kernel command-line arguments---e.g.,
34796 @code{("console=ttyS0")}.
34798 @item @code{initrd} (default: @code{#f})
34799 A G-Expression or string denoting the file name of the initial RAM disk
34800 to use (@pxref{G-Expressions}).
34802 @item @code{device} (default: @code{#f})
34803 The device where the kernel and initrd are to be found---i.e., for GRUB,
34804 @dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
34806 This may be a file system label (a string), a file system UUID (a
34807 bytevector, @pxref{File Systems}), or @code{#f}, in which case
34808 the bootloader will search the device containing the file specified by
34809 the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It
34810 must @emph{not} be an OS device name such as @file{/dev/sda1}.
34812 @item @code{multiboot-kernel} (default: @code{#f})
34813 The kernel to boot in Multiboot-mode (@pxref{multiboot,,, grub, GNU GRUB
34814 manual}). When this field is set, a Multiboot menu-entry is generated.
34818 (file-append mach "/boot/gnumach")
34821 @item @code{multiboot-arguments} (default: @code{()})
34822 The list of extra command-line arguments for the multiboot-kernel.
34824 @item @code{multiboot-modules} (default: @code{()})
34825 The list of commands for loading Multiboot modules. For example:
34828 (list (list (file-append hurd "/hurd/ext2fs.static") "ext2fs"
34830 (list (file-append libc "/lib/ld.so.1") "exec"
34840 @c FIXME: Write documentation once it's stable.
34841 For now only GRUB has theme support. GRUB themes are created using
34842 the @code{grub-theme} form, which is not fully documented yet.
34844 @deftp {Data Type} grub-theme
34845 Data type representing the configuration of the GRUB theme.
34848 @item @code{gfxmode} (default: @code{'("auto")})
34849 The GRUB @code{gfxmode} to set (a list of screen resolution strings,
34850 @pxref{gfxmode,,, grub, GNU GRUB manual}).
34854 @deffn {Scheme Procedure} grub-theme
34855 Return the default GRUB theme used by the operating system if no
34856 @code{theme} field is specified in @code{bootloader-configuration}
34859 It comes with a fancy background image displaying the GNU and Guix
34863 For example, to override the default resolution, you may use something
34868 (bootloader-configuration
34871 (inherit (grub-theme))
34872 (gfxmode '("1024x786x32" "auto"))))))
34875 @node Invoking guix system
34876 @section Invoking @code{guix system}
34878 Once you have written an operating system declaration as seen in the
34879 previous section, it can be @dfn{instantiated} using the @command{guix
34880 system} command. The synopsis is:
34883 guix system @var{options}@dots{} @var{action} @var{file}
34886 @var{file} must be the name of a file containing an
34887 @code{operating-system} declaration. @var{action} specifies how the
34888 operating system is instantiated. Currently the following values are
34893 Display available service type definitions that match the given regular
34894 expressions, sorted by relevance:
34900 $ guix system search console
34901 name: console-fonts
34902 location: gnu/services/base.scm:806:2
34903 extends: shepherd-root
34904 description: Install the given fonts on the specified ttys (fonts are per
34905 + virtual console on GNU/Linux). The value of this service is a list of
34906 + tty/font pairs. The font can be the name of a font provided by the `kbd'
34907 + package or any valid argument to `setfont', as in this example:
34909 + '(("tty1" . "LatGrkCyr-8x16")
34910 + ("tty2" . (file-append
34912 + "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
34913 + ("tty3" . (file-append
34915 + "/share/consolefonts/ter-132n"))) ; for HDPI
34919 location: gnu/services/base.scm:1190:2
34920 extends: shepherd-root
34921 description: Provide console login using the `mingetty' program.
34925 location: gnu/services/base.scm:860:2
34927 description: Provide a console log-in service as specified by its
34928 + configuration value, a `login-configuration' object.
34934 As for @command{guix package --search}, the result is written in
34935 @code{recutils} format, which makes it easy to filter the output
34936 (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
34939 Build the operating system described in @var{file}, activate it, and
34940 switch to it@footnote{This action (and the related actions
34941 @code{switch-generation} and @code{roll-back}) are usable only on
34942 systems already running Guix System.}.
34945 @c The paragraph below refers to the problem discussed at
34946 @c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
34947 It is highly recommended to run @command{guix pull} once before you run
34948 @command{guix system reconfigure} for the first time (@pxref{Invoking
34949 guix pull}). Failing to do that you would see an older version of Guix
34950 once @command{reconfigure} has completed.
34953 This effects all the configuration specified in @var{file}: user
34954 accounts, system services, global package list, setuid programs, etc.
34955 The command starts system services specified in @var{file} that are not
34956 currently running; if a service is currently running this command will
34957 arrange for it to be upgraded the next time it is stopped (e.g.@: by
34958 @code{herd stop X} or @code{herd restart X}).
34960 This command creates a new generation whose number is one greater than
34961 the current generation (as reported by @command{guix system
34962 list-generations}). If that generation already exists, it will be
34963 overwritten. This behavior mirrors that of @command{guix package}
34964 (@pxref{Invoking guix package}).
34966 It also adds a bootloader menu entry for the new OS configuration,
34967 ---unless @option{--no-bootloader} is passed. For GRUB, it moves
34968 entries for older configurations to a submenu, allowing you to choose
34969 an older system generation at boot time should you need it.
34971 @cindex provenance tracking, of the operating system
34972 Upon completion, the new system is deployed under
34973 @file{/run/current-system}. This directory contains @dfn{provenance
34974 meta-data}: the list of channels in use (@pxref{Channels}) and
34975 @var{file} itself, when available. You can view it by running:
34978 guix system describe
34981 This information is useful should you later want to inspect how this
34982 particular generation was built. In fact, assuming @var{file} is
34983 self-contained, you can later rebuild generation @var{n} of your
34984 operating system with:
34987 guix time-machine \
34988 -C /var/guix/profiles/system-@var{n}-link/channels.scm -- \
34989 system reconfigure \
34990 /var/guix/profiles/system-@var{n}-link/configuration.scm
34993 You can think of it as some sort of built-in version control! Your
34994 system is not just a binary artifact: @emph{it carries its own source}.
34995 @xref{Service Reference, @code{provenance-service-type}}, for more
34996 information on provenance tracking.
34998 By default, @command{reconfigure} @emph{prevents you from downgrading
34999 your system}, which could (re)introduce security vulnerabilities and
35000 also cause problems with ``stateful'' services such as database
35001 management systems. You can override that behavior by passing
35002 @option{--allow-downgrades}.
35004 @item switch-generation
35005 @cindex generations
35006 Switch to an existing system generation. This action atomically
35007 switches the system profile to the specified system generation. It
35008 also rearranges the system's existing bootloader menu entries. It
35009 makes the menu entry for the specified system generation the default,
35010 and it moves the entries for the other generations to a submenu, if
35011 supported by the bootloader being used. The next time the system
35012 boots, it will use the specified system generation.
35014 The bootloader itself is not being reinstalled when using this
35015 command. Thus, the installed bootloader is used with an updated
35016 configuration file.
35018 The target generation can be specified explicitly by its generation
35019 number. For example, the following invocation would switch to system
35023 guix system switch-generation 7
35026 The target generation can also be specified relative to the current
35027 generation with the form @code{+N} or @code{-N}, where @code{+3} means
35028 ``3 generations ahead of the current generation,'' and @code{-1} means
35029 ``1 generation prior to the current generation.'' When specifying a
35030 negative value such as @code{-1}, you must precede it with @code{--} to
35031 prevent it from being parsed as an option. For example:
35034 guix system switch-generation -- -1
35037 Currently, the effect of invoking this action is @emph{only} to switch
35038 the system profile to an existing generation and rearrange the
35039 bootloader menu entries. To actually start using the target system
35040 generation, you must reboot after running this action. In the future,
35041 it will be updated to do the same things as @command{reconfigure},
35042 like activating and deactivating services.
35044 This action will fail if the specified generation does not exist.
35047 @cindex rolling back
35048 Switch to the preceding system generation. The next time the system
35049 boots, it will use the preceding system generation. This is the inverse
35050 of @command{reconfigure}, and it is exactly the same as invoking
35051 @command{switch-generation} with an argument of @code{-1}.
35053 Currently, as with @command{switch-generation}, you must reboot after
35054 running this action to actually start using the preceding system
35057 @item delete-generations
35058 @cindex deleting system generations
35059 @cindex saving space
35060 Delete system generations, making them candidates for garbage collection
35061 (@pxref{Invoking guix gc}, for information on how to run the ``garbage
35064 This works in the same way as @samp{guix package --delete-generations}
35065 (@pxref{Invoking guix package, @option{--delete-generations}}). With no
35066 arguments, all system generations but the current one are deleted:
35069 guix system delete-generations
35072 You can also select the generations you want to delete. The example below
35073 deletes all the system generations that are more than two months old:
35076 guix system delete-generations 2m
35079 Running this command automatically reinstalls the bootloader with an updated
35080 list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no
35081 longer lists the generations that have been deleted.
35084 Build the derivation of the operating system, which includes all the
35085 configuration files and programs needed to boot and run the system.
35086 This action does not actually install anything.
35089 Populate the given directory with all the files necessary to run the
35090 operating system specified in @var{file}. This is useful for first-time
35091 installations of Guix System. For instance:
35094 guix system init my-os-config.scm /mnt
35097 copies to @file{/mnt} all the store items required by the configuration
35098 specified in @file{my-os-config.scm}. This includes configuration
35099 files, packages, and so on. It also creates other essential files
35100 needed for the system to operate correctly---e.g., the @file{/etc},
35101 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
35103 This command also installs bootloader on the targets specified in
35104 @file{my-os-config}, unless the @option{--no-bootloader} option was
35108 @cindex virtual machine
35110 @anchor{guix system vm}
35111 Build a virtual machine (VM) that contains the operating system declared
35112 in @var{file}, and return a script to run that VM.
35115 The @code{vm} action and others below
35116 can use KVM support in the Linux-libre kernel. Specifically, if the
35117 machine has hardware virtualization support, the corresponding
35118 KVM kernel module should be loaded, and the @file{/dev/kvm} device node
35119 must exist and be readable and writable by the user and by the
35120 build users of the daemon (@pxref{Build Environment Setup}).
35123 Arguments given to the script are passed to QEMU as in the example
35124 below, which enables networking and requests 1@tie{}GiB of RAM for the
35128 $ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
35131 It's possible to combine the two steps into one:
35134 $ $(guix system vm my-config.scm) -m 1024 -smp 2 -nic user,model=virtio-net-pci
35137 The VM shares its store with the host system.
35139 Additional file systems can be shared between the host and the VM using
35140 the @option{--share} and @option{--expose} command-line options: the former
35141 specifies a directory to be shared with write access, while the latter
35142 provides read-only access to the shared directory.
35144 The example below creates a VM in which the user's home directory is
35145 accessible read-only, and where the @file{/exchange} directory is a
35146 read-write mapping of @file{$HOME/tmp} on the host:
35149 guix system vm my-config.scm \
35150 --expose=$HOME --share=$HOME/tmp=/exchange
35153 On GNU/Linux, the default is to boot directly to the kernel; this has
35154 the advantage of requiring only a very tiny root disk image since the
35155 store of the host can then be mounted.
35157 The @option{--full-boot} option forces a complete boot sequence, starting
35158 with the bootloader. This requires more disk space since a root image
35159 containing at least the kernel, initrd, and bootloader data files must
35162 The @option{--image-size} option can be used to specify the size of the
35165 The @option{--no-graphic} option will instruct @command{guix system} to
35166 spawn a headless VM that will use the invoking tty for IO. Among other
35167 things, this enables copy-pasting, and scrollback. Use the @kbd{ctrl-a}
35168 prefix to issue QEMU commands; e.g. @kbd{ctrl-a h} prints a help,
35169 @kbd{ctrl-a x} quits the VM, and @kbd{ctrl-a c} switches between the
35170 QEMU monitor and the VM.
35172 @cindex System images, creation in various formats
35173 @cindex Creating system images in various formats
35175 @cindex image, creating disk images
35176 The @code{image} command can produce various image types. The
35177 image type can be selected using the @option{--image-type} option. It
35178 defaults to @code{efi-raw}. When its value is @code{iso9660}, the
35179 @option{--label} option can be used to specify a volume ID with
35180 @code{image}. By default, the root file system of a disk image is
35181 mounted non-volatile; the @option{--volatile} option can be provided to
35182 make it volatile instead. When using @code{image}, the bootloader
35183 installed on the generated image is taken from the provided
35184 @code{operating-system} definition. The following example demonstrates
35185 how to generate an image that uses the @code{grub-efi-bootloader}
35186 bootloader and boot it with QEMU:
35189 image=$(guix system image --image-type=qcow2 \
35190 gnu/system/examples/lightweight-desktop.tmpl)
35191 cp $image /tmp/my-image.qcow2
35192 chmod +w /tmp/my-image.qcow2
35193 qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \
35194 -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin
35197 When using the @code{efi-raw} image type, a raw disk image is produced;
35198 it can be copied as is to a USB stick, for instance. Assuming
35199 @code{/dev/sdc} is the device corresponding to a USB stick, one can copy
35200 the image to it using the following command:
35203 # dd if=$(guix system image my-os.scm) of=/dev/sdc status=progress
35206 The @code{--list-image-types} command lists all the available image
35209 @cindex creating virtual machine images
35210 When using the @code{qcow2} image type, the returned image is in qcow2
35211 format, which the QEMU emulator can efficiently use. @xref{Running Guix
35212 in a VM}, for more information on how to run the image in a virtual
35213 machine. The @code{grub-bootloader} bootloader is always used
35214 independently of what is declared in the @code{operating-system} file
35215 passed as argument. This is to make it easier to work with QEMU, which
35216 uses the SeaBIOS BIOS by default, expecting a bootloader to be installed
35217 in the Master Boot Record (MBR).
35219 @cindex docker-image, creating docker images
35220 When using the @code{docker} image type, a Docker image is produced.
35221 Guix builds the image from scratch, not from a pre-existing Docker base
35222 image. As a result, it contains @emph{exactly} what you define in the
35223 operating system configuration file. You can then load the image and
35224 launch a Docker container using commands like the following:
35227 image_id="$(docker load < guix-system-docker-image.tar.gz)"
35228 container_id="$(docker create $image_id)"
35229 docker start $container_id
35232 This command starts a new Docker container from the specified image. It
35233 will boot the Guix system in the usual manner, which means it will
35234 start any services you have defined in the operating system
35235 configuration. You can get an interactive shell running in the container
35236 using @command{docker exec}:
35239 docker exec -ti $container_id /run/current-system/profile/bin/bash --login
35242 Depending on what you run in the Docker container, it
35243 may be necessary to give the container additional permissions. For
35244 example, if you intend to build software using Guix inside of the Docker
35245 container, you may need to pass the @option{--privileged} option to
35246 @code{docker create}.
35248 Last, the @option{--network} option applies to @command{guix system
35249 docker-image}: it produces an image where network is supposedly shared
35250 with the host, and thus without services like nscd or NetworkManager.
35253 Return a script to run the operating system declared in @var{file}
35254 within a container. Containers are a set of lightweight isolation
35255 mechanisms provided by the kernel Linux-libre. Containers are
35256 substantially less resource-demanding than full virtual machines since
35257 the kernel, shared objects, and other resources can be shared with the
35258 host system; this also means they provide thinner isolation.
35260 Currently, the script must be run as root in order to support more than
35261 a single user and group. The container shares its store with the host
35264 As with the @code{vm} action (@pxref{guix system vm}), additional file
35265 systems to be shared between the host and container can be specified
35266 using the @option{--share} and @option{--expose} options:
35269 guix system container my-config.scm \
35270 --expose=$HOME --share=$HOME/tmp=/exchange
35274 This option requires Linux-libre 3.19 or newer.
35279 @var{options} can contain any of the common build options (@pxref{Common
35280 Build Options}). In addition, @var{options} can contain one of the
35284 @item --expression=@var{expr}
35285 @itemx -e @var{expr}
35286 Consider the operating-system @var{expr} evaluates to.
35287 This is an alternative to specifying a file which evaluates to an
35289 This is used to generate the Guix system installer @pxref{Building the
35290 Installation Image}).
35292 @item --system=@var{system}
35293 @itemx -s @var{system}
35294 Attempt to build for @var{system} instead of the host system type.
35295 This works as per @command{guix build} (@pxref{Invoking guix build}).
35299 Return the derivation file name of the given operating system without
35302 @cindex provenance tracking, of the operating system
35303 @item --save-provenance
35304 As discussed above, @command{guix system init} and @command{guix system
35305 reconfigure} always save provenance information @i{via} a dedicated
35306 service (@pxref{Service Reference, @code{provenance-service-type}}).
35307 However, other commands don't do that by default. If you wish to, say,
35308 create a virtual machine image that contains provenance information, you
35312 guix system image -t qcow2 --save-provenance config.scm
35315 That way, the resulting image will effectively ``embed its own source''
35316 in the form of meta-data in @file{/run/current-system}. With that
35317 information, one can rebuild the image to make sure it really contains
35318 what it pretends to contain; or they could use that to derive a variant
35321 @item --image-type=@var{type}
35322 @itemx -t @var{type}
35323 For the @code{image} action, create an image with given @var{type}.
35325 When this option is omitted, @command{guix system} uses the
35326 @code{efi-raw} image type.
35328 @cindex ISO-9660 format
35329 @cindex CD image format
35330 @cindex DVD image format
35331 @option{--image-type=iso9660} produces an ISO-9660 image, suitable
35332 for burning on CDs and DVDs.
35334 @item --image-size=@var{size}
35335 For the @code{image} action, create an image of the given @var{size}.
35336 @var{size} may be a number of bytes, or it may include a unit as a
35337 suffix (@pxref{Block size, size specifications,, coreutils, GNU
35340 When this option is omitted, @command{guix system} computes an estimate
35341 of the image size as a function of the size of the system declared in
35346 For the @code{container} action, allow containers to access the host network,
35347 that is, do not create a network namespace.
35349 @item --root=@var{file}
35350 @itemx -r @var{file}
35351 Make @var{file} a symlink to the result, and register it as a garbage
35354 @item --skip-checks
35355 Skip pre-installation safety checks.
35357 By default, @command{guix system init} and @command{guix system
35358 reconfigure} perform safety checks: they make sure the file systems that
35359 appear in the @code{operating-system} declaration actually exist
35360 (@pxref{File Systems}), and that any Linux kernel modules that may be
35361 needed at boot time are listed in @code{initrd-modules} (@pxref{Initial
35362 RAM Disk}). Passing this option skips these tests altogether.
35364 @item --allow-downgrades
35365 Instruct @command{guix system reconfigure} to allow system downgrades.
35367 By default, @command{reconfigure} prevents you from downgrading your
35368 system. It achieves that by comparing the provenance info of your
35369 system (shown by @command{guix system describe}) with that of your
35370 @command{guix} command (shown by @command{guix describe}). If the
35371 commits for @command{guix} are not descendants of those used for your
35372 system, @command{guix system reconfigure} errors out. Passing
35373 @option{--allow-downgrades} allows you to bypass these checks.
35376 Make sure you understand its security implications before using
35377 @option{--allow-downgrades}.
35381 @cindex on-error strategy
35382 @cindex error strategy
35383 @item --on-error=@var{strategy}
35384 Apply @var{strategy} when an error occurs when reading @var{file}.
35385 @var{strategy} may be one of the following:
35388 @item nothing-special
35389 Report the error concisely and exit. This is the default strategy.
35392 Likewise, but also display a backtrace.
35395 Report the error and enter Guile's debugger. From there, you can run
35396 commands such as @code{,bt} to get a backtrace, @code{,locals} to
35397 display local variable values, and more generally inspect the state of the
35398 program. @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
35399 a list of available debugging commands.
35403 Once you have built, configured, re-configured, and re-re-configured
35404 your Guix installation, you may find it useful to list the operating
35405 system generations available on disk---and that you can choose from the
35406 bootloader boot menu:
35411 Describe the current system generation: its file name, the kernel and
35412 bootloader used, etc., as well as provenance information when available.
35414 @item list-generations
35415 List a summary of each generation of the operating system available on
35416 disk, in a human-readable way. This is similar to the
35417 @option{--list-generations} option of @command{guix package}
35418 (@pxref{Invoking guix package}).
35420 Optionally, one can specify a pattern, with the same syntax that is used
35421 in @command{guix package --list-generations}, to restrict the list of
35422 generations displayed. For instance, the following command displays
35423 generations that are up to 10 days old:
35426 $ guix system list-generations 10d
35431 The @command{guix system} command has even more to offer! The following
35432 sub-commands allow you to visualize how your system services relate to
35435 @anchor{system-extension-graph}
35438 @item extension-graph
35439 Emit to standard output the @dfn{service
35440 extension graph} of the operating system defined in @var{file}
35441 (@pxref{Service Composition}, for more information on service
35442 extensions). By default the output is in Dot/Graphviz format, but you
35443 can choose a different format with @option{--graph-backend}, as with
35444 @command{guix graph} (@pxref{Invoking guix graph, @option{--backend}}):
35449 $ guix system extension-graph @var{file} | xdot -
35452 shows the extension relations among services.
35454 @anchor{system-shepherd-graph}
35455 @item shepherd-graph
35456 Emit to standard output the @dfn{dependency
35457 graph} of shepherd services of the operating system defined in
35458 @var{file}. @xref{Shepherd Services}, for more information and for an
35461 Again, the default output format is Dot/Graphviz, but you can pass
35462 @option{--graph-backend} to select a different one.
35466 @node Invoking guix deploy
35467 @section Invoking @code{guix deploy}
35469 We've already seen @code{operating-system} declarations used to manage a
35470 machine's configuration locally. Suppose you need to configure multiple
35471 machines, though---perhaps you're managing a service on the web that's
35472 comprised of several servers. @command{guix deploy} enables you to use those
35473 same @code{operating-system} declarations to manage multiple remote hosts at
35474 once as a logical ``deployment''.
35477 The functionality described in this section is still under development
35478 and is subject to change. Get in touch with us on
35479 @email{guix-devel@@gnu.org}!
35483 guix deploy @var{file}
35486 Such an invocation will deploy the machines that the code within @var{file}
35487 evaluates to. As an example, @var{file} might contain a definition like this:
35490 ;; This is a Guix deployment of a "bare bones" setup, with
35491 ;; no X11 display server, to a machine with an SSH daemon
35492 ;; listening on localhost:2222. A configuration such as this
35493 ;; may be appropriate for virtual machine with ports
35494 ;; forwarded to the host's loopback interface.
35496 (use-service-modules networking ssh)
35497 (use-package-modules bootloaders)
35501 (host-name "gnu-deployed")
35502 (timezone "Etc/UTC")
35503 (bootloader (bootloader-configuration
35504 (bootloader grub-bootloader)
35505 (targets '("/dev/vda"))
35506 (terminal-outputs '(console))))
35507 (file-systems (cons (file-system
35509 (device "/dev/vda1")
35511 %base-file-systems))
35513 (append (list (service dhcp-client-service-type)
35514 (service openssh-service-type
35515 (openssh-configuration
35516 (permit-root-login #t)
35517 (allow-empty-passwords? #t))))
35521 (operating-system %system)
35522 (environment managed-host-environment-type)
35523 (configuration (machine-ssh-configuration
35524 (host-name "localhost")
35525 (system "x86_64-linux")
35527 (identity "./id_rsa")
35531 The file should evaluate to a list of @var{machine} objects. This example,
35532 upon being deployed, will create a new generation on the remote system
35533 realizing the @code{operating-system} declaration @code{%system}.
35534 @code{environment} and @code{configuration} specify how the machine should be
35535 provisioned---that is, how the computing resources should be created and
35536 managed. The above example does not create any resources, as a
35537 @code{'managed-host} is a machine that is already running the Guix system and
35538 available over the network. This is a particularly simple case; a more
35539 complex deployment may involve, for example, starting virtual machines through
35540 a Virtual Private Server (VPS) provider. In such a case, a different
35541 @var{environment} type would be used.
35543 Do note that you first need to generate a key pair on the coordinator machine
35544 to allow the daemon to export signed archives of files from the store
35545 (@pxref{Invoking guix archive}), though this step is automatic on Guix
35549 # guix archive --generate-key
35553 Each target machine must authorize the key of the master machine so that it
35554 accepts store items it receives from the coordinator:
35557 # guix archive --authorize < coordinator-public-key.txt
35560 @code{user}, in this example, specifies the name of the user account to log in
35561 as to perform the deployment. Its default value is @code{root}, but root
35562 login over SSH may be forbidden in some cases. To work around this,
35563 @command{guix deploy} can log in as an unprivileged user and employ
35564 @code{sudo} to escalate privileges. This will only work if @code{sudo} is
35565 currently installed on the remote and can be invoked non-interactively as
35566 @code{user}. That is, the line in @code{sudoers} granting @code{user} the
35567 ability to use @code{sudo} must contain the @code{NOPASSWD} tag. This can
35568 be accomplished with the following operating system configuration snippet:
35572 (gnu system)) ;for %sudoers-specification
35574 (define %user "username")
35579 (plain-file "sudoers"
35580 (string-append (plain-file-content %sudoers-specification)
35581 (format #f "~a ALL = NOPASSWD: ALL~%"
35586 For more information regarding the format of the @file{sudoers} file,
35587 consult @command{man sudoers}.
35589 @deftp {Data Type} machine
35590 This is the data type representing a single machine in a heterogeneous Guix
35594 @item @code{operating-system}
35595 The object of the operating system configuration to deploy.
35597 @item @code{environment}
35598 An @code{environment-type} describing how the machine should be provisioned.
35600 @item @code{configuration} (default: @code{#f})
35601 An object describing the configuration for the machine's @code{environment}.
35602 If the @code{environment} has a default configuration, @code{#f} may be used.
35603 If @code{#f} is used for an environment with no default configuration,
35604 however, an error will be thrown.
35608 @deftp {Data Type} machine-ssh-configuration
35609 This is the data type representing the SSH client parameters for a machine
35610 with an @code{environment} of @code{managed-host-environment-type}.
35613 @item @code{host-name}
35614 @item @code{build-locally?} (default: @code{#t})
35615 If false, system derivations will be built on the machine being deployed to.
35616 @item @code{system}
35617 The system type describing the architecture of the machine being deployed
35618 to---e.g., @code{"x86_64-linux"}.
35619 @item @code{authorize?} (default: @code{#t})
35620 If true, the coordinator's signing key will be added to the remote's ACL
35622 @item @code{port} (default: @code{22})
35623 @item @code{user} (default: @code{"root"})
35624 @item @code{identity} (default: @code{#f})
35625 If specified, the path to the SSH private key to use to authenticate with the
35628 @item @code{host-key} (default: @code{#f})
35629 This should be the SSH host key of the machine, which looks like this:
35632 ssh-ed25519 AAAAC3Nz@dots{} root@@example.org
35635 When @code{host-key} is @code{#f}, the server is authenticated against
35636 the @file{~/.ssh/known_hosts} file, just like the OpenSSH @command{ssh}
35639 @item @code{allow-downgrades?} (default: @code{#f})
35640 Whether to allow potential downgrades.
35642 Like @command{guix system reconfigure}, @command{guix deploy} compares
35643 the channel commits currently deployed on the remote host (as returned
35644 by @command{guix system describe}) to those currently in use (as
35645 returned by @command{guix describe}) to determine whether commits
35646 currently in use are descendants of those deployed. When this is not
35647 the case and @code{allow-downgrades?} is false, it raises an error.
35648 This ensures you do not accidentally downgrade remote machines.
35652 @deftp {Data Type} digital-ocean-configuration
35653 This is the data type describing the Droplet that should be created for a
35654 machine with an @code{environment} of @code{digital-ocean-environment-type}.
35657 @item @code{ssh-key}
35658 The path to the SSH private key to use to authenticate with the remote
35659 host. In the future, this field may not exist.
35661 A list of string ``tags'' that uniquely identify the machine. Must be given
35662 such that no two machines in the deployment have the same set of tags.
35663 @item @code{region}
35664 A Digital Ocean region slug, such as @code{"nyc3"}.
35666 A Digital Ocean size slug, such as @code{"s-1vcpu-1gb"}
35667 @item @code{enable-ipv6?}
35668 Whether or not the droplet should be created with IPv6 networking.
35672 @node Running Guix in a VM
35673 @section Running Guix in a Virtual Machine
35675 @cindex virtual machine
35676 To run Guix in a virtual machine (VM), one can use the pre-built Guix VM
35677 image distributed at
35678 @url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}.
35679 This image is a compressed image in QCOW format. You can pass it to an
35680 emulator such as @uref{https://qemu.org/, QEMU} (see below for details).
35682 This image boots the Xfce graphical environment and it contains some
35683 commonly used tools. You can install more software in the image by running
35684 @command{guix package} in a terminal (@pxref{Invoking guix package}). You can
35685 also reconfigure the system based on its initial configuration file available
35686 as @file{/run/current-system/configuration.scm} (@pxref{Using the
35687 Configuration System}).
35689 Instead of using this pre-built image, one can also build their own
35690 image using @command{guix system image} (@pxref{Invoking guix system}).
35693 If you built your own image, you must copy it out of the store
35694 (@pxref{The Store}) and give yourself permission to write to the copy
35695 before you can use it. When invoking QEMU, you must choose a system
35696 emulator that is suitable for your hardware platform. Here is a minimal
35697 QEMU invocation that will boot the result of @command{guix system
35698 image -t qcow2} on x86_64 hardware:
35701 $ qemu-system-x86_64 \
35702 -nic user,model=virtio-net-pci \
35703 -enable-kvm -m 1024 \
35704 -device virtio-blk,drive=myhd \
35705 -drive if=none,file=/tmp/qemu-image,id=myhd
35708 Here is what each of these options means:
35711 @item qemu-system-x86_64
35712 This specifies the hardware platform to emulate. This should match the
35715 @item -nic user,model=virtio-net-pci
35716 Enable the unprivileged user-mode network stack. The guest OS can
35717 access the host but not vice versa. This is the simplest way to get the
35718 guest OS online. @code{model} specifies which network device to emulate:
35719 @code{virtio-net-pci} is a special device made for virtualized operating
35720 systems and recommended for most uses. Assuming your hardware platform is
35721 x86_64, you can get a list of available NIC models by running
35722 @command{qemu-system-x86_64 -nic model=help}.
35725 If your system has hardware virtualization extensions, enabling the
35726 virtual machine support (KVM) of the Linux kernel will make things run
35729 @c To run Xfce + 'guix pull', we need at least 1G of RAM.
35731 RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
35732 which may be insufficient for some operations.
35734 @item -device virtio-blk,drive=myhd
35735 Create a @code{virtio-blk} drive called ``myhd''. @code{virtio-blk} is a
35736 ``paravirtualization'' mechanism for block devices that allows QEMU to achieve
35737 better performance than if it were emulating a complete disk drive. See the
35738 QEMU and KVM documentation for more info.
35740 @item -drive if=none,file=/tmp/qemu-image,id=myhd
35741 Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing
35742 store of the ``myhd'' drive.
35745 The default @command{run-vm.sh} script that is returned by an invocation of
35746 @command{guix system vm} does not add a @command{-nic user} flag by default.
35747 To get network access from within the vm add the @code{(dhcp-client-service)}
35748 to your system definition and start the VM using
35749 @command{$(guix system vm config.scm) -nic user}. An important caveat of using
35750 @command{-nic user} for networking is that @command{ping} will not work, because
35751 it uses the ICMP protocol. You'll have to use a different command to check for
35752 network connectivity, for example @command{guix download}.
35754 @subsection Connecting Through SSH
35758 To enable SSH inside a VM you need to add an SSH server like
35759 @code{openssh-service-type} to your VM (@pxref{Networking Services,
35760 @code{openssh-service-type}}). In addition you need to forward the SSH port,
35761 22 by default, to the host. You can do this with
35764 $(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
35767 To connect to the VM you can run
35770 ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost
35773 The @command{-p} tells @command{ssh} the port you want to connect to.
35774 @command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from complaining
35775 every time you modify your @command{config.scm} file and the
35776 @command{-o StrictHostKeyChecking=no} prevents you from having to allow a
35777 connection to an unknown host every time you connect.
35780 If you find the above @samp{hostfwd} example not to be working (e.g.,
35781 your SSH client hangs attempting to connect to the mapped port of your
35782 VM), make sure that your Guix System VM has networking support, such as
35783 by using the @code{dhcp-client-service-type} service type.
35786 @subsection Using @command{virt-viewer} with Spice
35788 As an alternative to the default @command{qemu} graphical client you can
35789 use the @command{remote-viewer} from the @command{virt-viewer} package. To
35790 connect pass the @command{-spice port=5930,disable-ticketing} flag to
35791 @command{qemu}. See previous section for further information on how to do this.
35793 Spice also allows you to do some nice stuff like share your clipboard with your
35794 VM@. To enable that you'll also have to pass the following flags to @command{qemu}:
35797 -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
35798 -chardev spicevmc,name=vdagent,id=vdagent
35799 -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,\
35800 name=com.redhat.spice.0
35803 You'll also need to add the @code{(spice-vdagent-service)} to your
35804 system definition (@pxref{Miscellaneous Services, Spice service}).
35806 @node Defining Services
35807 @section Defining Services
35809 The previous sections show the available services and how one can combine
35810 them in an @code{operating-system} declaration. But how do we define
35811 them in the first place? And what is a service anyway?
35814 * Service Composition:: The model for composing services.
35815 * Service Types and Services:: Types and services.
35816 * Service Reference:: API reference.
35817 * Shepherd Services:: A particular type of service.
35818 * Complex Configurations:: Defining bindings for complex configurations.
35821 @node Service Composition
35822 @subsection Service Composition
35826 Here we define a @dfn{service} as, broadly, something that extends the
35827 functionality of the operating system. Often a service is a process---a
35828 @dfn{daemon}---started when the system boots: a secure shell server, a
35829 Web server, the Guix build daemon, etc. Sometimes a service is a daemon
35830 whose execution can be triggered by another daemon---e.g., an FTP server
35831 started by @command{inetd} or a D-Bus service activated by
35832 @command{dbus-daemon}. Occasionally, a service does not map to a
35833 daemon. For instance, the ``account'' service collects user accounts
35834 and makes sure they exist when the system runs; the ``udev'' service
35835 collects device management rules and makes them available to the eudev
35836 daemon; the @file{/etc} service populates the @file{/etc} directory
35839 @cindex service extensions
35840 Guix system services are connected by @dfn{extensions}. For instance, the
35841 secure shell service @emph{extends} the Shepherd---the
35842 initialization system, running as PID@tie{}1---by giving it the command
35843 lines to start and stop the secure shell daemon (@pxref{Networking
35844 Services, @code{openssh-service-type}}); the UPower service extends the D-Bus
35845 service by passing it its @file{.service} specification, and extends the
35846 udev service by passing it device management rules (@pxref{Desktop
35847 Services, @code{upower-service}}); the Guix daemon service extends the
35848 Shepherd by passing it the command lines to start and stop the daemon,
35849 and extends the account service by passing it a list of required build
35850 user accounts (@pxref{Base Services}).
35852 All in all, services and their ``extends'' relations form a directed
35853 acyclic graph (DAG). If we represent services as boxes and extensions
35854 as arrows, a typical system might provide something like this:
35856 @image{images/service-graph,,5in,Typical service extension graph.}
35858 @cindex system service
35859 At the bottom, we see the @dfn{system service}, which produces the
35860 directory containing everything to run and boot the system, as returned
35861 by the @command{guix system build} command. @xref{Service Reference},
35862 to learn about the other service types shown here.
35863 @xref{system-extension-graph, the @command{guix system extension-graph}
35864 command}, for information on how to generate this representation for a
35865 particular operating system definition.
35867 @cindex service types
35868 Technically, developers can define @dfn{service types} to express these
35869 relations. There can be any number of services of a given type on the
35870 system---for instance, a system running two instances of the GNU secure
35871 shell server (lsh) has two instances of @code{lsh-service-type}, with
35872 different parameters.
35874 The following section describes the programming interface for service
35875 types and services.
35877 @node Service Types and Services
35878 @subsection Service Types and Services
35880 A @dfn{service type} is a node in the DAG described above. Let us start
35881 with a simple example, the service type for the Guix build daemon
35882 (@pxref{Invoking guix-daemon}):
35885 (define guix-service-type
35889 (list (service-extension shepherd-root-service-type guix-shepherd-service)
35890 (service-extension account-service-type guix-accounts)
35891 (service-extension activation-service-type guix-activation)))
35892 (default-value (guix-configuration))))
35896 It defines three things:
35900 A name, whose sole purpose is to make inspection and debugging easier.
35903 A list of @dfn{service extensions}, where each extension designates the
35904 target service type and a procedure that, given the parameters of the
35905 service, returns a list of objects to extend the service of that type.
35907 Every service type has at least one service extension. The only
35908 exception is the @dfn{boot service type}, which is the ultimate service.
35911 Optionally, a default value for instances of this type.
35914 In this example, @code{guix-service-type} extends three services:
35917 @item shepherd-root-service-type
35918 The @code{guix-shepherd-service} procedure defines how the Shepherd
35919 service is extended. Namely, it returns a @code{<shepherd-service>}
35920 object that defines how @command{guix-daemon} is started and stopped
35921 (@pxref{Shepherd Services}).
35923 @item account-service-type
35924 This extension for this service is computed by @code{guix-accounts},
35925 which returns a list of @code{user-group} and @code{user-account}
35926 objects representing the build user accounts (@pxref{Invoking
35929 @item activation-service-type
35930 Here @code{guix-activation} is a procedure that returns a gexp, which is
35931 a code snippet to run at ``activation time''---e.g., when the service is
35935 A service of this type is instantiated like this:
35938 (service guix-service-type
35939 (guix-configuration
35941 (extra-options '("--gc-keep-derivations"))))
35944 The second argument to the @code{service} form is a value representing
35945 the parameters of this specific service instance.
35946 @xref{guix-configuration-type, @code{guix-configuration}}, for
35947 information about the @code{guix-configuration} data type. When the
35948 value is omitted, the default value specified by
35949 @code{guix-service-type} is used:
35952 (service guix-service-type)
35955 @code{guix-service-type} is quite simple because it extends other
35956 services but is not extensible itself.
35958 @c @subsubsubsection Extensible Service Types
35960 The service type for an @emph{extensible} service looks like this:
35963 (define udev-service-type
35964 (service-type (name 'udev)
35966 (list (service-extension shepherd-root-service-type
35967 udev-shepherd-service)))
35969 (compose concatenate) ;concatenate the list of rules
35970 (extend (lambda (config rules)
35972 (($ <udev-configuration> udev initial-rules)
35973 (udev-configuration
35974 (udev udev) ;the udev package to use
35975 (rules (append initial-rules rules)))))))))
35978 This is the service type for the
35979 @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
35980 management daemon}. Compared to the previous example, in addition to an
35981 extension of @code{shepherd-root-service-type}, we see two new fields:
35985 This is the procedure to @dfn{compose} the list of extensions to
35986 services of this type.
35988 Services can extend the udev service by passing it lists of rules; we
35989 compose those extensions simply by concatenating them.
35992 This procedure defines how the value of the service is @dfn{extended} with
35993 the composition of the extensions.
35995 Udev extensions are composed into a list of rules, but the udev service
35996 value is itself a @code{<udev-configuration>} record. So here, we
35997 extend that record by appending the list of rules it contains to the
35998 list of contributed rules.
36001 This is a string giving an overview of the service type. The string can
36002 contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}). The
36003 @command{guix system search} command searches these strings and displays
36004 them (@pxref{Invoking guix system}).
36007 There can be only one instance of an extensible service type such as
36008 @code{udev-service-type}. If there were more, the
36009 @code{service-extension} specifications would be ambiguous.
36011 Still here? The next section provides a reference of the programming
36012 interface for services.
36014 @node Service Reference
36015 @subsection Service Reference
36017 We have seen an overview of service types (@pxref{Service Types and
36018 Services}). This section provides a reference on how to manipulate
36019 services and service types. This interface is provided by the
36020 @code{(gnu services)} module.
36022 @deffn {Scheme Procedure} service @var{type} [@var{value}]
36023 Return a new service of @var{type}, a @code{<service-type>} object (see
36024 below). @var{value} can be any object; it represents the parameters of
36025 this particular service instance.
36027 When @var{value} is omitted, the default value specified by @var{type}
36028 is used; if @var{type} does not specify a default value, an error is
36031 For instance, this:
36034 (service openssh-service-type)
36038 is equivalent to this:
36041 (service openssh-service-type
36042 (openssh-configuration))
36045 In both cases the result is an instance of @code{openssh-service-type}
36046 with the default configuration.
36049 @deffn {Scheme Procedure} service? @var{obj}
36050 Return true if @var{obj} is a service.
36053 @deffn {Scheme Procedure} service-kind @var{service}
36054 Return the type of @var{service}---i.e., a @code{<service-type>} object.
36057 @deffn {Scheme Procedure} service-value @var{service}
36058 Return the value associated with @var{service}. It represents its
36062 Here is an example of how a service is created and manipulated:
36066 (service nginx-service-type
36067 (nginx-configuration
36069 (log-directory log-directory)
36070 (run-directory run-directory)
36071 (file config-file))))
36076 (eq? (service-kind s) nginx-service-type)
36080 The @code{modify-services} form provides a handy way to change the
36081 parameters of some of the services of a list such as
36082 @code{%base-services} (@pxref{Base Services, @code{%base-services}}). It
36083 evaluates to a list of services. Of course, you could always use
36084 standard list combinators such as @code{map} and @code{fold} to do that
36085 (@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
36086 @code{modify-services} simply provides a more concise form for this
36089 @deffn {Scheme Syntax} modify-services @var{services} @
36090 (@var{type} @var{variable} => @var{body}) @dots{}
36092 Modify the services listed in @var{services} according to the given
36093 clauses. Each clause has the form:
36096 (@var{type} @var{variable} => @var{body})
36099 where @var{type} is a service type---e.g.,
36100 @code{guix-service-type}---and @var{variable} is an identifier that is
36101 bound within the @var{body} to the service parameters---e.g., a
36102 @code{guix-configuration} instance---of the original service of that
36105 The @var{body} should evaluate to the new service parameters, which will
36106 be used to configure the new service. This new service will replace the
36107 original in the resulting list. Because a service's service parameters
36108 are created using @code{define-record-type*}, you can write a succinct
36109 @var{body} that evaluates to the new service parameters by using the
36110 @code{inherit} feature that @code{define-record-type*} provides.
36112 Clauses can also have the following form:
36115 (delete @var{type})
36118 Such a clause removes all services of the given @var{type} from
36121 @xref{Using the Configuration System}, for example usage.
36125 Next comes the programming interface for service types. This is
36126 something you want to know when writing new service definitions, but not
36127 necessarily when simply looking for ways to customize your
36128 @code{operating-system} declaration.
36130 @deftp {Data Type} service-type
36131 @cindex service type
36132 This is the representation of a @dfn{service type} (@pxref{Service Types
36137 This is a symbol, used only to simplify inspection and debugging.
36139 @item @code{extensions}
36140 A non-empty list of @code{<service-extension>} objects (see below).
36142 @item @code{compose} (default: @code{#f})
36143 If this is @code{#f}, then the service type denotes services that cannot
36144 be extended---i.e., services that do not receive ``values'' from other
36147 Otherwise, it must be a one-argument procedure. The procedure is called
36148 by @code{fold-services} and is passed a list of values collected from
36149 extensions. It may return any single value.
36151 @item @code{extend} (default: @code{#f})
36152 If this is @code{#f}, services of this type cannot be extended.
36154 Otherwise, it must be a two-argument procedure: @code{fold-services}
36155 calls it, passing it the initial value of the service as the first
36156 argument and the result of applying @code{compose} to the extension
36157 values as the second argument. It must return a value that is a valid
36158 parameter value for the service instance.
36160 @item @code{description}
36161 This is a string, possibly using Texinfo markup, describing in a couple
36162 of sentences what the service is about. This string allows users to
36163 find about the service through @command{guix system search}
36164 (@pxref{Invoking guix system}).
36166 @item @code{default-value} (default: @code{&no-default-value})
36167 The default value associated for instances of this service type. This
36168 allows users to use the @code{service} form without its second argument:
36171 (service @var{type})
36174 The returned service in this case has the default value specified by
36178 @xref{Service Types and Services}, for examples.
36181 @deffn {Scheme Procedure} service-extension @var{target-type} @
36183 Return a new extension for services of type @var{target-type}.
36184 @var{compute} must be a one-argument procedure: @code{fold-services}
36185 calls it, passing it the value associated with the service that provides
36186 the extension; it must return a valid value for the target service.
36189 @deffn {Scheme Procedure} service-extension? @var{obj}
36190 Return true if @var{obj} is a service extension.
36193 Occasionally, you might want to simply extend an existing service. This
36194 involves creating a new service type and specifying the extension of
36195 interest, which can be verbose; the @code{simple-service} procedure
36196 provides a shorthand for this.
36198 @deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
36199 Return a service that extends @var{target} with @var{value}. This works
36200 by creating a singleton service type @var{name}, of which the returned
36201 service is an instance.
36203 For example, this extends mcron (@pxref{Scheduled Job Execution}) with
36207 (simple-service 'my-mcron-job mcron-service-type
36208 #~(job '(next-hour (3)) "guix gc -F 2G"))
36212 At the core of the service abstraction lies the @code{fold-services}
36213 procedure, which is responsible for ``compiling'' a list of services
36214 down to a single directory that contains everything needed to boot and
36215 run the system---the directory shown by the @command{guix system build}
36216 command (@pxref{Invoking guix system}). In essence, it propagates
36217 service extensions down the service graph, updating each node parameters
36218 on the way, until it reaches the root node.
36220 @deffn {Scheme Procedure} fold-services @var{services} @
36221 [#:target-type @var{system-service-type}]
36222 Fold @var{services} by propagating their extensions down to the root of
36223 type @var{target-type}; return the root service adjusted accordingly.
36226 Lastly, the @code{(gnu services)} module also defines several essential
36227 service types, some of which are listed below.
36229 @defvr {Scheme Variable} system-service-type
36230 This is the root of the service graph. It produces the system directory
36231 as returned by the @command{guix system build} command.
36234 @defvr {Scheme Variable} boot-service-type
36235 The type of the ``boot service'', which produces the @dfn{boot script}.
36236 The boot script is what the initial RAM disk runs when booting.
36239 @defvr {Scheme Variable} etc-service-type
36240 The type of the @file{/etc} service. This service is used to create
36241 files under @file{/etc} and can be extended by
36242 passing it name/file tuples such as:
36245 (list `("issue" ,(plain-file "issue" "Welcome!\n")))
36248 In this example, the effect would be to add an @file{/etc/issue} file
36249 pointing to the given file.
36252 @defvr {Scheme Variable} setuid-program-service-type
36253 Type for the ``setuid-program service''. This service collects lists of
36254 executable file names, passed as gexps, and adds them to the set of
36255 setuid-root programs on the system (@pxref{Setuid Programs}).
36258 @defvr {Scheme Variable} profile-service-type
36259 Type of the service that populates the @dfn{system profile}---i.e., the
36260 programs under @file{/run/current-system/profile}. Other services can
36261 extend it by passing it lists of packages to add to the system profile.
36264 @cindex provenance tracking, of the operating system
36265 @anchor{provenance-service-type}
36266 @defvr {Scheme Variable} provenance-service-type
36267 This is the type of the service that records @dfn{provenance meta-data}
36268 in the system itself. It creates several files under
36269 @file{/run/current-system}:
36273 This is a ``channel file'' that can be passed to @command{guix pull -C}
36274 or @command{guix time-machine -C}, and which describes the channels used
36275 to build the system, if that information was available
36276 (@pxref{Channels}).
36278 @item configuration.scm
36279 This is the file that was passed as the value for this
36280 @code{provenance-service-type} service. By default, @command{guix
36281 system reconfigure} automatically passes the OS configuration file it
36282 received on the command line.
36285 This contains the same information as the two other files but in a
36286 format that is more readily processable.
36289 In general, these two pieces of information (channels and configuration
36290 file) are enough to reproduce the operating system ``from source''.
36293 This information is necessary to rebuild your operating system, but it
36294 is not always sufficient. In particular, @file{configuration.scm}
36295 itself is insufficient if it is not self-contained---if it refers to
36296 external Guile modules or to extra files. If you want
36297 @file{configuration.scm} to be self-contained, we recommend that modules
36298 or files it refers to be part of a channel.
36300 Besides, provenance meta-data is ``silent'' in the sense that it does
36301 not change the bits contained in your system, @emph{except for the
36302 meta-data bits themselves}. Two different OS configurations or sets of
36303 channels can lead to the same system, bit-for-bit; when
36304 @code{provenance-service-type} is used, these two systems will have
36305 different meta-data and thus different store file names, which makes
36306 comparison less trivial.
36309 This service is automatically added to your operating system
36310 configuration when you use @command{guix system reconfigure},
36311 @command{guix system init}, or @command{guix deploy}.
36314 @defvr {Scheme Variable} linux-loadable-module-service-type
36315 Type of the service that collects lists of packages containing
36316 kernel-loadable modules, and adds them to the set of kernel-loadable
36319 This service type is intended to be extended by other service types,
36323 (simple-service 'installing-module
36324 linux-loadable-module-service-type
36325 (list module-to-install-1
36326 module-to-install-2))
36329 This does not actually load modules at bootup, only adds it to the
36330 kernel profile so that it @emph{can} be loaded by other means.
36333 @node Shepherd Services
36334 @subsection Shepherd Services
36336 @cindex shepherd services
36338 @cindex init system
36339 The @code{(gnu services shepherd)} module provides a way to define
36340 services managed by the GNU@tie{}Shepherd, which is the
36341 initialization system---the first process that is started when the
36342 system boots, also known as PID@tie{}1
36343 (@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}).
36345 Services in the Shepherd can depend on each other. For instance, the
36346 SSH daemon may need to be started after the syslog daemon has been
36347 started, which in turn can only happen once all the file systems have
36348 been mounted. The simple operating system defined earlier (@pxref{Using
36349 the Configuration System}) results in a service graph like this:
36351 @image{images/shepherd-graph,,5in,Typical shepherd service graph.}
36353 You can actually generate such a graph for any operating system
36354 definition using the @command{guix system shepherd-graph} command
36355 (@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).
36357 The @code{%shepherd-root-service} is a service object representing
36358 PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended
36359 by passing it lists of @code{<shepherd-service>} objects.
36361 @deftp {Data Type} shepherd-service
36362 The data type representing a service managed by the Shepherd.
36365 @item @code{provision}
36366 This is a list of symbols denoting what the service provides.
36368 These are the names that may be passed to @command{herd start},
36369 @command{herd status}, and similar commands (@pxref{Invoking herd,,,
36370 shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the
36371 @code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.
36373 @item @code{requirement} (default: @code{'()})
36374 List of symbols denoting the Shepherd services this one depends on.
36376 @cindex one-shot services, for the Shepherd
36377 @item @code{one-shot?} (default: @code{#f})
36378 Whether this service is @dfn{one-shot}. One-shot services stop immediately
36379 after their @code{start} action has completed. @xref{Slots of services,,,
36380 shepherd, The GNU Shepherd Manual}, for more info.
36382 @item @code{respawn?} (default: @code{#t})
36383 Whether to restart the service when it stops, for instance when the
36384 underlying process dies.
36387 @itemx @code{stop} (default: @code{#~(const #f)})
36388 The @code{start} and @code{stop} fields refer to the Shepherd's
36389 facilities to start and stop processes (@pxref{Service De- and
36390 Constructors,,, shepherd, The GNU Shepherd Manual}). They are given as
36391 G-expressions that get expanded in the Shepherd configuration file
36392 (@pxref{G-Expressions}).
36394 @item @code{actions} (default: @code{'()})
36395 @cindex actions, of Shepherd services
36396 This is a list of @code{shepherd-action} objects (see below) defining
36397 @dfn{actions} supported by the service, in addition to the standard
36398 @code{start} and @code{stop} actions. Actions listed here become available as
36399 @command{herd} sub-commands:
36402 herd @var{action} @var{service} [@var{arguments}@dots{}]
36405 @item @code{auto-start?} (default: @code{#t})
36406 Whether this service should be started automatically by the Shepherd. If it
36407 is @code{#f} the service has to be started manually with @code{herd start}.
36409 @item @code{documentation}
36410 A documentation string, as shown when running:
36413 herd doc @var{service-name}
36416 where @var{service-name} is one of the symbols in @code{provision}
36417 (@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).
36419 @item @code{modules} (default: @code{%default-modules})
36420 This is the list of modules that must be in scope when @code{start} and
36421 @code{stop} are evaluated.
36426 The example below defines a Shepherd service that spawns
36427 @command{syslogd}, the system logger from the GNU Networking Utilities
36428 (@pxref{syslogd invocation, @command{syslogd},, inetutils, GNU
36432 (let ((config (plain-file "syslogd.conf" "@dots{}")))
36434 (documentation "Run the syslog daemon (syslogd).")
36435 (provision '(syslogd))
36436 (requirement '(user-processes))
36437 (start #~(make-forkexec-constructor
36438 (list #$(file-append inetutils "/libexec/syslogd")
36439 "--rcfile" #$config)
36440 #:pid-file "/var/run/syslog.pid"))
36441 (stop #~(make-kill-destructor))))
36444 Key elements in this example are the @code{start} and @code{stop}
36445 fields: they are @dfn{staged} code snippets that use the
36446 @code{make-forkexec-constructor} procedure provided by the Shepherd and
36447 its dual, @code{make-kill-destructor} (@pxref{Service De- and
36448 Constructors,,, shepherd, The GNU Shepherd Manual}). The @code{start}
36449 field will have @command{shepherd} spawn @command{syslogd} with the
36450 given option; note that we pass @code{config} after @option{--rcfile},
36451 which is a configuration file declared above (contents of this file are
36452 omitted). Likewise, the @code{stop} field tells how this service is to
36453 be stopped; in this case, it is stopped by making the @code{kill} system
36454 call on its PID@. Code staging is achieved using G-expressions:
36455 @code{#~} stages code, while @code{#$} ``escapes'' back to host code
36456 (@pxref{G-Expressions}).
36458 @deftp {Data Type} shepherd-action
36459 This is the data type that defines additional actions implemented by a
36460 Shepherd service (see above).
36464 Symbol naming the action.
36466 @item documentation
36467 This is a documentation string for the action. It can be viewed by running:
36470 herd doc @var{service} action @var{action}
36474 This should be a gexp that evaluates to a procedure of at least one argument,
36475 which is the ``running value'' of the service (@pxref{Slots of services,,,
36476 shepherd, The GNU Shepherd Manual}).
36479 The following example defines an action called @code{say-hello} that kindly
36485 (documentation "Say hi!")
36486 (procedure #~(lambda (running . args)
36487 (format #t "Hello, friend! arguments: ~s\n"
36492 Assuming this action is added to the @code{example} service, then you can do:
36495 # herd say-hello example
36496 Hello, friend! arguments: ()
36497 # herd say-hello example a b c
36498 Hello, friend! arguments: ("a" "b" "c")
36501 This, as you can see, is a fairly sophisticated way to say hello.
36502 @xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more
36506 @defvr {Scheme Variable} shepherd-root-service-type
36507 The service type for the Shepherd ``root service''---i.e., PID@tie{}1.
36509 This is the service type that extensions target when they want to create
36510 shepherd services (@pxref{Service Types and Services}, for an example).
36511 Each extension must pass a list of @code{<shepherd-service>}. Its
36512 value must be a @code{shepherd-configuration}, as described below.
36515 @deftp {Data Type} shepherd-configuration
36516 This data type represents the Shepherd's configuration.
36519 @item shepherd (default: @code{shepherd})
36520 The Shepherd package to use.
36522 @item services (default: @code{'()})
36523 A list of @code{<shepherd-service>} to start.
36524 You should probably use the service extension
36525 mechanism instead (@pxref{Shepherd Services}).
36529 The following example specifies the Shepherd package for the operating
36535 (services (append (list openssh-service-type))
36539 ;; Use own Shepherd package.
36540 (essential-services
36541 (modify-services (operating-system-default-essential-services
36542 this-operating-system)
36543 (shepherd-root-service-type config => (shepherd-configuration
36545 (shepherd my-shepherd))))))
36548 @defvr {Scheme Variable} %shepherd-root-service
36549 This service represents PID@tie{}1.
36552 @node Complex Configurations
36553 @subsection Complex Configurations
36554 @cindex complex configurations
36555 Some programs might have rather complex configuration files or formats,
36556 and to make it easier to create Scheme bindings for these configuration
36557 files, you can use the utilities defined in the @code{(gnu services
36558 configuration)} module.
36560 The main utility is the @code{define-configuration} macro, which you
36561 will use to define a Scheme record type (@pxref{Record Overview,,,
36562 guile, GNU Guile Reference Manual}). The Scheme record will be
36563 serialized to a configuration file by using @dfn{serializers}, which are
36564 procedures that take some kind of Scheme value and returns a
36565 G-expression (@pxref{G-Expressions}), which should, once serialized to
36566 the disk, return a string. More details are listed below.
36568 @deffn {Scheme Syntax} define-configuration @var{name} @var{clause1} @
36570 Create a record type named @code{@var{name}} that contains the
36571 fields found in the clauses.
36573 A clause can have one of the following forms:
36577 (@var{type} @var{default-value})
36578 @var{documentation})
36581 (@var{type} @var{default-value})
36582 @var{documentation}
36587 @var{documentation})
36591 @var{documentation}
36595 @var{field-name} is an identifier that denotes the name of the field in
36596 the generated record.
36598 @var{type} is the type of the value corresponding to @var{field-name};
36599 since Guile is untyped, a predicate
36600 procedure---@code{@var{type}?}---will be called on the value
36601 corresponding to the field to ensure that the value is of the correct
36602 type. This means that if say, @var{type} is @code{package}, then a
36603 procedure named @code{package?} will be applied on the value to make
36604 sure that it is indeed a @code{<package>} object.
36606 @var{default-value} is the default value corresponding to the field; if
36607 none is specified, the user is forced to provide a value when creating
36608 an object of the record type.
36610 @c XXX: Should these be full sentences or are they allow to be very
36611 @c short like package synopses?
36612 @var{documentation} is a string formatted with Texinfo syntax which
36613 should provide a description of what setting this field does.
36615 @var{serializer} is the name of a procedure which takes two arguments,
36616 the first is the name of the field, and the second is the value
36617 corresponding to the field. The procedure should return a string or
36618 G-expression (@pxref{G-Expressions}) that represents the content that
36619 will be serialized to the configuration file. If none is specified, a
36620 procedure of the name @code{serialize-@var{type}} will be used.
36622 A simple serializer procedure could look like this:
36625 (define (serialize-boolean field-name value)
36626 (let ((value (if value "true" "false")))
36627 #~(string-append #$field-name #$value)))
36630 In some cases multiple different configuration records might be defined
36631 in the same file, but their serializers for the same type might have to
36632 be different, because they have different configuration formats. For
36633 example, the @code{serialize-boolean} procedure for the Getmail service
36634 would have to be different for the one for the Transmission service. To
36635 make it easier to deal with this situation, one can specify a serializer
36636 prefix by using the @code{prefix} literal in the
36637 @code{define-configuration} form. This means that one doesn't have to
36638 manually specify a custom @var{serializer} for every field.
36641 (define (foo-serialize-string field-name value)
36644 (define (bar-serialize-string field-name value)
36647 (define-configuration foo-configuration
36650 "The name of label.")
36653 (define-configuration bar-configuration
36656 "The IPv4 address for this device.")
36660 However, in some cases you might not want to serialize any of the values
36661 of the record, to do this, you can use the @code{no-serialization}
36662 literal. There is also the @code{define-configuration/no-serialization}
36663 macro which is a shorthand of this.
36666 ;; Nothing will be serialized to disk.
36667 (define-configuration foo-configuration
36670 "Some documentation.")
36671 (no-serialization))
36673 ;; The same thing as above.
36674 (define-configuration/no-serialization bar-configuration
36677 "Some documentation."))
36681 @deffn {Scheme Syntax} define-maybe @var{type}
36682 Sometimes a field should not be serialized if the user doesn’t specify a
36683 value. To achieve this, you can use the @code{define-maybe} macro to
36684 define a ``maybe type''; if the value of a maybe type is set to the
36685 @code{disabled}, it will not be serialized.
36687 When defining a ``maybe type'', the corresponding serializer for the
36688 regular type will be used by default. For example, a field of type
36689 @code{maybe-string} will be serialized using the @code{serialize-string}
36690 procedure by default, you can of course change this by specifying a
36691 custom serializer procedure. Likewise, the type of the value would have
36692 to be a string, unless it is set to the @code{disabled} symbol.
36695 (define-maybe string)
36697 (define (serialize-string field-name value)
36700 (define-configuration baz-configuration
36702 ;; Nothing will be serialized by default. If set to a string, the
36703 ;; `serialize-string' procedure will be used to serialize the string.
36704 (maybe-string 'disabled)
36705 "The name of this module."))
36708 Like with @code{define-configuration}, one can set a prefix for the
36709 serializer name by using the @code{prefix} literal.
36712 (define-maybe integer
36715 (define (baz-serialize-interger field-name value)
36719 There is also the @code{no-serialization} literal, which when set means
36720 that no serializer will be defined for the ``maybe type'', regardless of
36721 its value is @code{disabled} or not.
36722 @code{define-maybe/no-serialization} is a shorthand for specifying the
36723 @code{no-serialization} literal.
36726 (define-maybe/no-serialization symbol)
36728 (define-configuration/no-serialization test-configuration
36730 (maybe-symbol 'disabled)
36735 @deffn {Scheme Procedure} serialize-configuration @var{configuration} @
36737 Return a G-expression that contains the values corresponding to the
36738 @var{fields} of @var{configuration}, a record that has been generated by
36739 @code{define-configuration}. The G-expression can then be serialized to
36740 disk by using something like @code{mixed-text-file}.
36743 @deffn {Scheme Procedure} validate-configuration @var{configuration}
36745 Type-check @var{fields}, a list of field names of @var{configuration}, a
36746 configuration record created by @code{define-configuration}.
36749 @deffn {Scheme Procedure} empty-serializer @var{field-name} @var{value}
36750 A serializer that just returns an empty string. The
36751 @code{serialize-package} procedure is an alias for this.
36754 Once you have defined a configuration record, you will most likely also
36755 want to document it so that other people know to use it. To help with
36756 that, there are two procedures, both of which are documented below.
36758 @deffn {Scheme Procedure} generate-documentation @var{documentation} @
36759 @var{documentation-name}
36760 Generate a Texinfo fragment from the docstrings in @var{documentation},
36761 a list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}.
36762 @var{label} should be a symbol and should be the name of the
36763 configuration record. @var{fields} should be a list of all the fields
36764 available for the configuration record.
36766 @var{sub-documentation} is a @code{(@var{field-name}
36767 @var{configuration-name})} tuple. @var{field-name} is the name of the
36768 field which takes another configuration record as its value, and
36769 @var{configuration-name} is the name of that configuration record.
36771 @var{sub-documentation} is only needed if there are nested configuration
36772 records. For example, the @code{getmail-configuration} record
36773 (@pxref{Mail Services}) accepts a @code{getmail-configuration-file}
36774 record in one of its @code{rcfile} field, therefore documentation for
36775 @code{getmail-configuration-file} is nested in
36776 @code{getmail-configuration}.
36779 (generate-documentation
36780 `((getmail-configuration ,getmail-configuration-fields
36781 (rcfile getmail-configuration-file))
36783 'getmail-configuration)
36786 @var{documentation-name} should be a symbol and should be the name of
36787 the configuration record.
36791 @deffn {Scheme Procedure} configuration->documentation
36792 @var{configuration-symbol}
36793 Take @var{configuration-symbol}, the symbol corresponding to the name
36794 used when defining a configuration record with
36795 @code{define-configuration}, and print the Texinfo documentation of its
36796 fields. This is useful if there aren’t any nested configuration records
36797 since it only prints the documentation for the top-level fields.
36800 As of right now, there is no automated way to generate documentation for
36801 configuration records and put them in the manual. Instead, every
36802 time you make a change to the docstrings of a configuration record, you
36803 have to manually call @code{generate-documentation} or
36804 @code{configuration->documentation}, and paste the output into the
36805 @file{doc/guix.texi} file.
36807 @c TODO: Actually test this
36808 Below is an example of a record type created using
36809 @code{define-configuration} and friends.
36812 (use-modules (gnu services)
36814 (gnu services configuration)
36818 ;; Turn field names, which are Scheme symbols into strings
36819 (define (uglify-field-name field-name)
36820 (let ((str (symbol->string field-name)))
36821 ;; field? -> is-field
36822 (if (string-suffix? "?" str)
36823 (string-append "is-" (string-drop-right str 1))
36826 (define (serialize-string field-name value)
36827 #~(string-append #$(uglify-field-name field-name) " = " #$value "\n"))
36829 (define (serialize-integer field-name value)
36830 (serialize-string field-name (number->string value)))
36832 (define (serialize-boolean field-name value)
36833 (serialize-string field-name (if value "true" "false")))
36835 (define (serialize-contact-name field-name value)
36836 #~(string-append "\n[" #$value "]\n"))
36838 (define (list-of-contact-configurations? lst)
36839 (every contact-configuration? lst))
36841 (define (serialize-list-of-contact-configurations field-name value)
36842 #~(string-append #$@@(map (cut serialize-configuration <>
36843 contact-configuration-fields)
36846 (define (serialize-contacts-list-configuration configuration)
36849 #~(string-append "[Owner]\n"
36850 #$(serialize-configuration
36851 configuration contacts-list-configuration-fields))))
36853 (define-maybe integer)
36854 (define-maybe string)
36856 (define-configuration contact-configuration
36859 "The name of the contact."
36860 serialize-contact-name)
36862 (maybe-integer 'disabled)
36863 "The person's phone number.")
36865 (maybe-string 'disabled)
36866 "The person's email address.")
36869 "Whether the person is married."))
36871 (define-configuration contacts-list-configuration
36874 "The name of the owner of this contact list.")
36877 "The owner's email address.")
36879 (list-of-contact-configurations '())
36880 "A list of @@code@{contact-configuation@} records which contain
36881 information about all your contacts."))
36884 A contacts list configuration could then be created like this:
36887 (define my-contacts
36888 (contacts-list-configuration
36890 (email "alice@@example.org")
36892 (list (contact-configuration
36894 (phone-number 1234)
36895 (email "bob@@gnu.org")
36897 (contact-configuration
36899 (phone-number 0000)
36903 After serializing the configuration to disk, the resulting file would
36909 email = alice@@example.org
36912 phone-number = 1234
36913 email = bob@@gnu.org
36922 @node Home Configuration
36923 @chapter Home Configuration
36924 @cindex home configuration
36925 Guix supports declarative configuration of @dfn{home environments} by
36926 utilizing the configuration mechanism described in the previous chapter
36927 (@pxref{Defining Services}), but for user's dotfiles and packages. It
36928 works both on Guix System and foreign distros and allows users to
36929 declare all the packages and services that should be installed and
36930 configured for the user. Once a user has written a file containing
36931 @code{home-environment} record, such a configuration can be
36932 @dfn{instantiated} by an unprivileged user with the @command{guix home}
36933 command (@pxref{Invoking guix home}).
36934 @c Maybe later, it will be possible to make home configuration a part of
36935 @c system configuration to make everything managed by guix system.
36938 The functionality described in this section is still under development
36939 and is subject to change. Get in touch with us on
36940 @email{guix-devel@@gnu.org}!
36943 The user's home environment usually consists of three basic parts:
36944 software, configuration, and state. Software in mainstream distros are
36945 usually installed system-wide, but with GNU Guix most software packages
36946 can be installed on a per-user basis without needing root privileges,
36947 and are thus considered part of the user’s @dfn{home environment}.
36948 Packages on their own not very useful in many cases, because often they
36949 require some additional configuration, usually config files that reside
36950 in @env{XDG_CONFIG_HOME} (@file{~/.config} by default) or other
36951 directories. Everything else can be considered state, like media files,
36952 application databases, and logs.
36954 Using Guix for managing home environments provides a number of
36959 @item All software can be configured in one language (Guile Scheme),
36960 this gives users the ability to share values between configurations of
36961 different programs.
36963 @item A well-defined home environment is self-contained and can be
36964 created in a declarative and reproducible way---there is no need to grab
36965 external binaries or manually edit some configuration file.
36967 @item After every @command{guix home reconfigure} invocation, a new home
36968 environment generation will be created. This means that users can
36969 rollback to a previous home environment generation so they don’t have to
36970 worry about breaking their configuration.
36972 @item It is possible to manage stateful data with Guix Home, this
36973 includes the ability to automatically clone Git repositories on the
36974 initial setup of the machine, and periodically running commands like
36975 @command{rsync} to sync data with another host. This functionality is
36976 still in an experimental stage, though.
36981 * Declaring the Home Environment:: Customizing your Home.
36982 * Configuring the Shell:: Enabling home environment.
36983 * Home Services:: Specifying home services.
36984 * Invoking guix home:: Instantiating a home configuration.
36987 @node Declaring the Home Environment
36988 @section Declaring the Home Environment
36989 The home environment is configured by providing a
36990 @code{home-environment} declaration in a file that can be passed to the
36991 @command{guix home} command (@pxref{Invoking guix home}). The easiest
36992 way to get started is by generating an initial configuration with
36993 @command{guix home import}:
36996 guix home import ~/src/guix-config
36999 The @command{guix home import} command reads some of the ``dot files''
37000 such as @file{~/.bashrc} found in your home directory and copies them to
37001 the given directory, @file{~/src/guix-config} in this case; it also
37002 reads the contents of your profile, @file{~/.guix-profile}, and, based
37003 on that, it populates @file{~/src/guix-config/home-configuration.scm}
37004 with a Home configuration that resembles your current configuration.
37006 A simple setup can include Bash and a custom text configuration, like in
37007 the example below. Don't be afraid to declare home environment parts,
37008 which overlaps with your current dot files: before installing any
37009 configuration files, Guix Home will back up existing config files to a
37010 separate place in the home directory.
37013 It is highly recommended that you manage your shell or shells with Guix
37014 Home, because it will make sure that all the necessary scripts are
37015 sourced by the shell configuration file. Otherwise you will need to do
37016 it manually. (@pxref{Configuring the Shell}).
37019 @findex home-environment
37021 @include he-config-bare-bones.scm
37024 The @code{packages} field should be self-explanatory, it will install
37025 the list of packages into the user's profile. The most important field
37026 is @code{services}, it contains a list of @dfn{home services}, which are
37027 the basic building blocks of a home environment.
37029 There is no daemon (at least not necessarily) related to a home service,
37030 a home service is just an element that is used to declare part of home
37031 environment and extend other parts of it. The extension mechanism
37032 discussed in the previous chapter (@pxref{Defining Services}) should not
37033 be confused with Shepherd services (@pxref{Shepherd Services}). Using this extension
37034 mechanism and some Scheme code that glues things together gives the user
37035 the freedom to declare their own, very custom, home environments.
37037 Once you have a configuration file that suits your needs, you can
37038 reconfigure your home by running:
37041 guix home reconfigure config.scm
37044 This ``builds'' your home environment and creates @file{~/.guix-home}
37045 pointing to it. Voilà!
37048 Make sure the operating system has elogind, systemd, or a similar
37049 mechanism to create the XDG run-time directory and has the
37050 @env{XDG_RUNTIME_DIR} variable set. Failing that, the
37051 @file{on-first-login} script will not execute anything, and processes
37052 like user Shepherd and its descendants will not start.
37055 @node Configuring the Shell
37056 @section Configuring the Shell
37057 This section is safe to skip if your shell or shells are managed by
37058 Guix Home. Otherwise, read it carefully.
37060 There are a few scripts that must be evaluated by a login shell to
37061 activate the home environment. The shell startup files only read by
37062 login shells often have @code{profile} suffix. For more information
37063 about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
37064 Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
37067 The first script that needs to be sourced is @file{setup-environment},
37068 which sets all the necessary environment variables (including variables
37069 declared by the user) and the second one is @file{on-first-login}, which
37070 starts Shepherd for the current user and performs actions declared by
37071 other home services that extends
37072 @code{home-run-on-first-login-service-type}.
37074 Guix Home will always create @file{~/.profile}, which contains the
37078 HOME_ENVIRONMENT=$HOME/.guix-home
37079 . $HOME_ENVIRONMENT/setup-environment
37080 $HOME_ENVIRONMENT/on-first-login
37083 This makes POSIX compliant login shells activate the home environment.
37084 However, in most cases this file won't be read by most modern shells,
37085 because they are run in non POSIX mode by default and have their own
37086 @file{*profile} startup files. For example Bash will prefer
37087 @file{~/.bash_profile} in case it exists and only if it doesn't will it
37088 fallback to @file{~/.profile}. Zsh (if no additional options are
37089 specified) will ignore @file{~/.profile}, even if @file{~/.zprofile}
37092 To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
37093 @code{source ~/profile} to the startup file for the login shell. In
37094 case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
37095 @file{~/.zprofile}.
37098 This step is only required if your shell is NOT managed by Guix Home.
37099 Otherwise, everything will be done automatically.
37102 @node Home Services
37103 @section Home Services
37104 @cindex home services
37106 A @dfn{home service} is not necessarily something that has a daemon and
37107 is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd
37108 Manual}), in most cases it doesn't. It's a simple building block of the
37109 home environment, often declaring a set of packages to be installed in
37110 the home environment profile, a set of config files to be symlinked into
37111 @env{XDG_CONFIG_HOME} (@file{~/.config} by default), and environment
37112 variables to be set by a login shell.
37114 There is a service extension mechanism (@pxref{Service Composition})
37115 which allows home services to extend other home services and utilize
37116 capabilities they provide; for example: declare mcron jobs
37117 (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home
37118 Service}; declare daemons by extending @ref{Shepherd Home Service}; add
37119 commands, which will be invoked on by the Bash by extending
37120 @ref{Shells Home Services, @code{home-bash-service-type}}.
37122 A good way to discover avaliable home services is using the
37123 @command{guix home search} command (@pxref{Invoking guix home}). After
37124 the required home services are found, include its module with the
37125 @code{use-modules} form (@pxref{use-modules,, Using Guile Modules,
37126 guile, The GNU Guile Reference Manual}), or the @code{#:use-modules}
37127 directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU
37128 Guile Reference Manual}) and declare a home service using the
37129 @code{service} function, or extend a service type by declaring a new
37130 service with the @code{simple-service} procedure from @code{(gnu
37134 * Essential Home Services:: Environment variables, packages, on-* scripts.
37135 * Shells: Shells Home Services. POSIX shells, Bash, Zsh.
37136 * Mcron: Mcron Home Service. Scheduled User's Job Execution.
37137 * Shepherd: Shepherd Home Service. Managing User's Daemons.
37139 @c In addition to that Home Services can provide
37141 @node Essential Home Services
37142 @subsection Essential Home Services
37143 There are a few essential home services defined in
37144 @code{(gnu services)}, they are mostly for internal use and are required
37145 to build a home environment, but some of them will be useful for the end
37148 @cindex environment variables
37150 @defvr {Scheme Variable} home-environment-variables-service-type
37151 The service of this type will be instantiated by every home environment
37152 automatically by default, there is no need to define it, but someone may
37153 want to extend it with a list of pairs to set some environment
37157 (list ("ENV_VAR1" . "value1")
37158 ("ENV_VAR2" . "value2"))
37161 The easiest way to extend a service type, without defining new service
37162 type is to use the @code{simple-service} helper from @code{(gnu
37166 (simple-service 'some-useful-env-vars-service
37167 home-environment-variables-service-type
37168 `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst")
37169 ("SHELL" . ,(file-append zsh "/bin/zsh"))
37170 ("USELESS_VAR" . #f)
37171 ("_JAVA_AWT_WM_NONREPARENTING" . #t)))
37174 If you include such a service in you home environment definition, it
37175 will add the following content to the @file{setup-environment} script
37176 (which is expected to be sourced by the login shell):
37179 export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst
37180 export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh
37181 export _JAVA_AWT_WM_NONREPARENTING
37185 Make sure that module @code{(gnu packages shells)} is imported with
37186 @code{use-modules} or any other way, this namespace contains the
37187 definition of the @code{zsh} packages, which is used in the example
37191 The association list (@pxref{Association Lists, alists, Association
37192 Lists, guile, The GNU Guile Reference manual}) is a data structure
37193 containing key-value pairs, for
37194 @code{home-environment-variables-service-type} the key is always a
37195 string, the value can be a string, string-valued gexp
37196 (@pxref{G-Expressions}), file-like object (@pxref{G-Expressions,
37197 file-like object}) or boolean. For gexps, the variable will be set to
37198 the value of the gexp; for file-like objects, it will be set to the path
37199 of the file in the store (@pxref{The Store}); for @code{#t}, it will
37200 export the variable without any value; and for @code{#f}, it will omit
37205 @defvr {Scheme Variable} home-profile-service-type
37206 The service of this type will be instantiated by every home environment
37207 automatically, there is no need to define it, but you may want to extend
37208 it with a list of packages if you want to install additional packages
37209 into your profile. Other services, which need to make some programs
37210 avaliable to the user will also extend this service type.
37212 The extension value is just a list of packages:
37215 (list htop vim emacs)
37218 The same approach as @code{simple-service} (@pxref{Service Reference,
37219 simple-service}) for @code{home-environment-variables-service-type} can
37220 be used here, too. Make sure that modules containing the specified
37221 packages are imported with @code{use-modules}. To find a package or
37222 information about its module use @command{guix search} (@pxref{Invoking
37223 guix package}). Alternatively, @code{specification->package} can be
37224 used to get the package record from string without importing related
37228 There are few more essential services, but users are not expected to
37231 @defvr {Scheme Variable} home-service-type
37232 The root of home services DAG, it generates a folder, which later will be
37233 symlinked to @file{~/.guix-home}, it contains configurations,
37234 profile with binaries and libraries, and some necessary scripts to glue
37238 @defvr {Scheme Variable} home-run-on-first-login-service-type
37239 The service of this type generates a Guile script, which is expected to
37240 be executed by the login shell. It is only executed if the special flag
37241 file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents
37242 redundant executions of the script if multiple login shells are spawned.
37244 It can be extended with a gexp. However, to autostart an application,
37245 users @emph{should not} use this service, in most cases it's better to extend
37246 @code{home-shepherd-service-type} with a Shepherd service
37247 (@pxref{Shepherd Services}), or extend the shell's startup file with
37248 the required command using the appropriate service type.
37251 @defvr {Scheme Variable} home-activation-service-type
37252 The service of this type generates a guile script, which runs on every
37253 @command{guix home reconfigure} invocation or any other action, which
37254 leads to the activation of the home environment.
37257 @node Shells Home Services
37261 @cindex login shell
37262 @cindex interactive shell
37266 Shells play a quite important role in the environment initialization
37267 process, you can configure them manually as described in section
37268 @ref{Configuring the Shell}, but the recommended way is to use home services
37269 listed below. It's both easier and more reliable.
37271 Each home environment instantiates
37272 @code{home-shell-profile-service-type}, which creates a
37273 @file{~/.profile} startup file for all POSIX-compatible shells. This
37274 file contains all the necessary steps to properly initialize the
37275 environment, but many modern shells like Bash or Zsh prefer their own
37276 startup files, that's why the respective home services
37277 (@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure
37278 that @file{~/.profile} is sourced by @file{~/.bash_profile} and
37279 @file{~/.zprofile}, respectively.
37281 @subsubheading Shell Profile Service
37283 @deftp {Data Type} home-shell-profile-configuration
37284 Available @code{home-shell-profile-configuration} fields are:
37287 @item @code{profile} (default: @code{()}) (type: text-config)
37288 @code{home-shell-profile} is instantiated automatically by
37289 @code{home-environment}, DO NOT create this service manually, it can
37290 only be extended. @code{profile} is a list of file-like objects, which
37291 will go to @file{~/.profile}. By default @file{~/.profile} contains the
37292 initialization code, which have to be evaluated by login shell to make
37293 home-environment's profile avaliable to the user, but other commands can
37294 be added to the file if it is really necessary. In most cases shell's
37295 configuration files are preferred places for user's customizations.
37296 Extend home-shell-profile service only if you really know what you do.
37302 @subsubheading Bash Home Service
37304 @anchor{home-bash-configuration}
37305 @deftp {Data Type} home-bash-configuration
37306 Available @code{home-bash-configuration} fields are:
37309 @item @code{package} (default: @code{bash}) (type: package)
37310 The Bash package to use.
37312 @item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
37313 Add sane defaults like reading @file{/etc/bashrc} and coloring the output of
37314 @command{ls} to the end of the @file{.bashrc} file.
37316 @item @code{environment-variables} (default: @code{()}) (type: alist)
37317 Association list of environment variables to set for the Bash session. The
37318 rules for the @code{home-environment-variables-service-type} apply
37319 here (@pxref{Essential Home Services}). The contents of this field will be
37320 added after the contents of the @code{bash-profile} field.
37322 @item @code{aliases} (default: @code{()}) (type: alist)
37323 Association list of aliases to set for the Bash session. The aliases
37324 will be defined after the contents of the @code{bashrc} field has been
37325 put in the @file{.bashrc} file. The alias will automatically be quoted,
37326 so something line this:
37329 '((\"ls\" . \"ls -alF\"))
37335 alias ls=\"ls -alF\"
37338 @item @code{bash-profile} (default: @code{()}) (type: text-config)
37339 List of file-like objects, which will be added to @file{.bash_profile}.
37340 Used for executing user's commands at start of login shell (In most
37341 cases the shell started on tty just after login). @file{.bash_login}
37342 won't be ever read, because @file{.bash_profile} always present.
37344 @item @code{bashrc} (default: @code{()}) (type: text-config)
37345 List of file-like objects, which will be added to @file{.bashrc}. Used
37346 for executing user's commands at start of interactive shell (The shell
37347 for interactive usage started by typing @code{bash} or by terminal app
37348 or any other program).
37350 @item @code{bash-logout} (default: @code{()}) (type: text-config)
37351 List of file-like objects, which will be added to @file{.bash_logout}.
37352 Used for executing user's commands at the exit of login shell. It won't
37353 be read in some cases (if the shell terminates by exec'ing another
37354 process for example).
37359 You can extend the Bash service by using the @code{home-bash-extension}
37360 configuration record, whose fields most mirror that of
37361 @code{home-bash-configuration} (@pxref{home-bash-configuration}). The
37362 contents of the extensions will be added to the end of the corresponding
37363 Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
37364 Bash Reference Manual}.
37366 @deftp {Data Type} home-bash-extension
37367 Available @code{home-bash-extension} fields are:
37370 @item @code{environment-variables} (default: @code{()}) (type: alist)
37371 Additional environment variables to set. These will be combined with the
37372 environment variables from other extensions and the base service to form one
37373 coherent block of environment variables.
37375 @item @code{aliases} (default: @code{()}) (type: alist)
37376 Additional aliases to set. These will be combined with the aliases from
37377 other extensions and the base service.
37379 @item @code{bash-profile} (default: @code{()}) (type: text-config)
37380 Additional text blocks to add to @file{.bash_profile}, which will be combined
37381 with text blocks from other extensions and the base service.
37383 @item @code{bashrc} (default: @code{()}) (type: text-config)
37384 Additional text blocks to add to @file{.bashrc}, which will be combined
37385 with text blocks from other extensions and the base service.
37387 @item @code{bash-logout} (default: @code{()}) (type: text-config)
37388 Additional text blocks to add to @file{.bash_logout}, which will be combined
37389 with text blocks from other extensions and the base service.
37394 @subsubheading Zsh Home Service
37396 @deftp {Data Type} home-zsh-configuration
37397 Available @code{home-zsh-configuration} fields are:
37400 @item @code{package} (default: @code{zsh}) (type: package)
37401 The Zsh package to use.
37403 @item @code{xdg-flavor?} (default: @code{#t}) (type: boolean)
37404 Place all the configs to @file{$XDG_CONFIG_HOME/zsh}. Makes
37405 @file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}.
37406 Shell startup process will continue with
37407 @file{$XDG_CONFIG_HOME/zsh/.zshenv}.
37409 @item @code{environment-variables} (default: @code{()}) (type: alist)
37410 Association list of environment variables to set for the Zsh session.
37412 @item @code{zshenv} (default: @code{()}) (type: text-config)
37413 List of file-like objects, which will be added to @file{.zshenv}. Used
37414 for setting user's shell environment variables. Must not contain
37415 commands assuming the presence of tty or producing output. Will be read
37416 always. Will be read before any other file in @env{ZDOTDIR}.
37418 @item @code{zprofile} (default: @code{()}) (type: text-config)
37419 List of file-like objects, which will be added to @file{.zprofile}. Used
37420 for executing user's commands at start of login shell (In most cases the
37421 shell started on tty just after login). Will be read before
37424 @item @code{zshrc} (default: @code{()}) (type: text-config)
37425 List of file-like objects, which will be added to @file{.zshrc}. Used
37426 for executing user's commands at start of interactive shell (The shell
37427 for interactive usage started by typing @code{zsh} or by terminal app or
37428 any other program).
37430 @item @code{zlogin} (default: @code{()}) (type: text-config)
37431 List of file-like objects, which will be added to @file{.zlogin}. Used
37432 for executing user's commands at the end of starting process of login
37435 @item @code{zlogout} (default: @code{()}) (type: text-config)
37436 List of file-like objects, which will be added to @file{.zlogout}. Used
37437 for executing user's commands at the exit of login shell. It won't be
37438 read in some cases (if the shell terminates by exec'ing another process
37445 @node Mcron Home Service
37446 @subsection Scheduled User's Job Execution
37450 @cindex scheduling jobs
37452 The @code{(gnu home services mcron)} module provides an interface to
37453 GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
37454 mcron, GNU@tie{}mcron}). The information about system's mcron is
37455 applicable here (@pxref{Scheduled Job Execution}), the only difference
37456 for home services is that they have to be declared in a
37457 @code{home-envirnoment} record instead of an @code{operating-system}
37460 @defvr {Scheme Variable} home-mcron-service-type
37461 This is the type of the @code{mcron} home service, whose value is an
37462 @code{home-mcron-configuration} object. It allows to manage scheduled
37465 This service type can be the target of a service extension that provides
37466 additional job specifications (@pxref{Service Composition}). In other
37467 words, it is possible to define services that provide additional mcron
37471 @deftp {Data Type} home-mcron-configuration
37472 Data type representing the configuration of mcron.
37475 @item @code{mcron} (default: @var{mcron})
37476 The mcron package to use.
37479 This is a list of gexps (@pxref{G-Expressions}), where each gexp
37480 corresponds to an mcron job specification (@pxref{Syntax, mcron job
37481 specifications,, mcron, GNU@tie{}mcron}).
37485 @node Shepherd Home Service
37486 @subsection Managing User's Daemons
37488 @cindex shepherd services
37490 @defvr {Scheme Variable} home-shepherd-service-type
37491 The service type for the userland Shepherd, which allows one to manage
37492 long-running processes or one-shot tasks. User's Shepherd is not an
37493 init process (PID 1), but almost all other information described in
37494 (@pxref{Shepherd Services}) is applicable here too.
37496 This is the service type that extensions target when they want to create
37497 shepherd services (@pxref{Service Types and Services}, for an example).
37498 Each extension must pass a list of @code{<shepherd-service>}. Its
37499 value must be a @code{home-shepherd-configuration}, as described below.
37502 @deftp {Data Type} home-shepherd-configuration
37503 This data type represents the Shepherd's configuration.
37506 @item shepherd (default: @code{shepherd})
37507 The Shepherd package to use.
37509 @item auto-start? (default: @code{#t})
37510 Whether or not to start Shepherd on first login.
37512 @item services (default: @code{'()})
37513 A list of @code{<shepherd-service>} to start.
37514 You should probably use the service extension
37515 mechanism instead (@pxref{Shepherd Services}).
37519 @node Invoking guix home
37520 @section Invoking @code{guix home}
37522 Once you have written a home environment declaration (@pxref{Declaring
37523 the Home Environment,,,,}, it can be @dfn{instantiated} using the
37524 @command{guix home} command. The synopsis is:
37527 guix home @var{options}@dots{} @var{action} @var{file}
37530 @var{file} must be the name of a file containing a
37531 @code{home-environment} declaration. @var{action} specifies how the
37532 home environment is instantiated, but there are few auxiliary actions
37533 which don't instantiate it. Currently the following values are
37538 Display available home service type definitions that match the given
37539 regular expressions, sorted by relevance:
37542 @cindex shell-profile
37546 $ guix home search shell
37547 name: home-shell-profile
37548 location: gnu/home/services/shells.scm:73:2
37549 extends: home-files
37550 description: Create `~/.profile', which is used for environment initialization
37551 + of POSIX compatible login shells. Can be extended with a list of strings or
37555 name: home-zsh-plugin-manager
37556 location: gnu/home/services/shellutils.scm:28:2
37557 extends: home-zsh home-profile
37558 description: Install plugins in profile and configure Zsh to load them.
37561 name: home-zsh-direnv
37562 location: gnu/home/services/shellutils.scm:69:2
37563 extends: home-profile home-zsh
37564 description: Enables `direnv' for `zsh'. Adds hook to `.zshrc' and installs a
37565 + package in the profile.
37568 name: home-zsh-autosuggestions
37569 location: gnu/home/services/shellutils.scm:43:2
37570 extends: home-zsh-plugin-manager home-zsh
37571 description: Enables Fish-like fast/unobtrusive autosuggestions for `zsh' and
37572 + sets reasonable default values for some plugin's variables to improve perfomance
37573 + and adjust behavior: `(history completion)' is set for strategy, manual rebind
37574 + and async are enabled.
37578 location: gnu/home/services/shells.scm:236:2
37579 extends: home-files home-profile
37580 description: Install and configure Zsh.
37584 location: gnu/home/services/shells.scm:388:2
37585 extends: home-files home-profile
37586 description: Install and configure Bash.
37592 As for @command{guix package --search}, the result is written in
37593 @code{recutils} format, which makes it easy to filter the output
37594 (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
37597 Build the home environment described in @var{file}, and switch to it.
37598 Switching means that the activation script will be evaluated and (in
37599 basic scenario) symlinks to configuration files generated from
37600 @code{home-environment} declaration will be created in @file{~}. If the
37601 file with the same path already exists in home folder it will be moved
37602 to @file{~/TIMESTAMP-guix-home-legacy-configs-backup}, where TIMESTAMP
37603 is a current UNIX epoch time.
37606 It is highly recommended to run @command{guix pull} once before you run
37607 @command{guix home reconfigure} for the first time (@pxref{Invoking guix
37611 This effects all the configuration specified in @var{file}. The command
37612 starts Shepherd services specified in @var{file} that are not currently
37613 running; if a service is currently running, this command will arrange
37614 for it to be upgraded the next time it is stopped (e.g.@: by @code{herd
37615 stop X} or @code{herd restart X}).
37617 This command creates a new generation whose number is one greater than
37618 the current generation (as reported by @command{guix home
37619 list-generations}). If that generation already exists, it will be
37620 overwritten. This behavior mirrors that of @command{guix package}
37621 (@pxref{Invoking guix package}).
37623 @cindex provenance tracking, of the home environment
37624 Upon completion, the new home is deployed under @file{~/.guix-home}.
37625 This directory contains @dfn{provenance meta-data}: the list of channels
37626 in use (@pxref{Channels}) and @var{file} itself, when available. You
37627 can view the provenance information by running:
37633 This information is useful should you later want to inspect how this
37634 particular generation was built. In fact, assuming @var{file} is
37635 self-contained, you can later rebuild generation @var{n} of your
37636 home environment with:
37639 guix time-machine \
37640 -C /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/channels.scm -- \
37642 /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configuration.scm
37646 You can think of it as some sort of built-in version control! Your
37647 home is not just a binary artifact: @emph{it carries its own source}.
37648 @c @xref{Service Reference, @code{provenance-service-type}}, for more
37649 @c information on provenance tracking.
37651 @c @footnote{This action (and the related actions
37652 @c @code{switch-generation} and @code{roll-back}) are usable after the
37653 @c home environment is initialized.}.
37655 @item switch-generation
37656 @cindex home generations
37657 Switch to an existing home generation. This action atomically switches
37658 the home profile to the specified home generation.
37660 The target generation can be specified explicitly by its generation
37661 number. For example, the following invocation would switch to home
37665 guix home switch-generation 7
37668 The target generation can also be specified relative to the current
37669 generation with the form @code{+N} or @code{-N}, where @code{+3} means
37670 ``3 generations ahead of the current generation,'' and @code{-1} means
37671 ``1 generation prior to the current generation.'' When specifying a
37672 negative value such as @code{-1}, you must precede it with @code{--} to
37673 prevent it from being parsed as an option. For example:
37676 guix home switch-generation -- -1
37679 This action will fail if the specified generation does not exist.
37682 @cindex rolling back
37683 Switch to the preceding home generation. This is the inverse
37684 of @command{reconfigure}, and it is exactly the same as invoking
37685 @command{switch-generation} with an argument of @code{-1}.
37687 @item delete-generations
37688 @cindex deleting home generations
37689 @cindex saving space
37690 Delete home generations, making them candidates for garbage collection
37691 (@pxref{Invoking guix gc}, for information on how to run the ``garbage
37694 This works in the same way as @samp{guix package --delete-generations}
37695 (@pxref{Invoking guix package, @option{--delete-generations}}). With no
37696 arguments, all home generations but the current one are deleted:
37699 guix home delete-generations
37702 You can also select the generations you want to delete. The example below
37703 deletes all the home generations that are more than two months old:
37706 guix home delete-generations 2m
37710 Build the derivation of the home environment, which includes all the
37711 configuration files and programs needed. This action does not actually
37715 Describe the current home generation: its file name, as well as
37716 provenance information when available.
37718 @item list-generations
37719 List a summary of each generation of the home environment available on
37720 disk, in a human-readable way. This is similar to the
37721 @option{--list-generations} option of @command{guix package}
37722 (@pxref{Invoking guix package}).
37724 Optionally, one can specify a pattern, with the same syntax that is used
37725 in @command{guix package --list-generations}, to restrict the list of
37726 generations displayed. For instance, the following command displays
37727 generations that are up to 10 days old:
37730 $ guix home list-generations 10d
37734 Generate a @dfn{home environment} from the packages in the default
37735 profile and configuration files found in the user's home directory. The
37736 configuration files will be copied to the specified directory, and a
37737 @file{home-configuration.scm} will be populated with the home
37738 environment. Note that not every home service that exists is supported
37739 (@pxref{Home Services}).
37742 $ guix home import ~/guix-config
37743 guix home: '/home/alice/guix-config' populated with all the Home configuration files
37748 @var{options} can contain any of the common build options (@pxref{Common
37749 Build Options}). In addition, @var{options} can contain one of the
37754 @item --expression=@var{expr}
37755 @itemx -e @var{expr}
37756 Consider the home-environment @var{expr} evaluates to.
37757 This is an alternative to specifying a file which evaluates to a home
37762 @node Documentation
37763 @chapter Documentation
37765 @cindex documentation, searching for
37766 @cindex searching for documentation
37767 @cindex Info, documentation format
37769 @cindex manual pages
37770 In most cases packages installed with Guix come with documentation.
37771 There are two main documentation formats: ``Info'', a browsable
37772 hypertext format used for GNU software, and ``manual pages'' (or ``man
37773 pages''), the linear documentation format traditionally found on Unix.
37774 Info manuals are accessed with the @command{info} command or with Emacs,
37775 and man pages are accessed using @command{man}.
37777 You can look for documentation of software installed on your system by
37778 keyword. For example, the following command searches for information
37779 about ``TLS'' in Info manuals:
37783 "(emacs)Network Security" -- STARTTLS
37784 "(emacs)Network Security" -- TLS
37785 "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
37786 "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
37791 The command below searches for the same keyword in man
37792 pages@footnote{The database searched by @command{man -k} is only created
37793 in profiles that contain the @code{man-db} package.}:
37797 SSL (7) - OpenSSL SSL/TLS library
37798 certtool (1) - GnuTLS certificate tool
37802 These searches are purely local to your computer so you have the
37803 guarantee that documentation you find corresponds to what you have
37804 actually installed, you can access it off-line, and your privacy is
37807 Once you have these results, you can view the relevant documentation by
37811 $ info "(gnutls)Core TLS API"
37821 Info manuals contain sections and indices as well as hyperlinks like
37822 those found in Web pages. The @command{info} reader (@pxref{Top, Info
37823 reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart
37824 (@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key
37825 bindings to navigate manuals. @xref{Getting Started,,, info, Info: An
37826 Introduction}, for an introduction to Info navigation.
37828 @node Installing Debugging Files
37829 @chapter Installing Debugging Files
37831 @cindex debugging files
37832 Program binaries, as produced by the GCC compilers for instance, are
37833 typically written in the ELF format, with a section containing
37834 @dfn{debugging information}. Debugging information is what allows the
37835 debugger, GDB, to map binary code to source code; it is required to
37836 debug a compiled program in good conditions.
37838 This chapter explains how to use separate debug info when packages
37839 provide it, and how to rebuild packages with debug info when it's
37843 * Separate Debug Info:: Installing 'debug' outputs.
37844 * Rebuilding Debug Info:: Building missing debug info.
37847 @node Separate Debug Info
37848 @section Separate Debug Info
37850 The problem with debugging information is that is takes up a fair amount
37851 of disk space. For example, debugging information for the GNU C Library
37852 weighs in at more than 60 MiB@. Thus, as a user, keeping all the
37853 debugging info of all the installed programs is usually not an option.
37854 Yet, space savings should not come at the cost of an impediment to
37855 debugging---especially in the GNU system, which should make it easier
37856 for users to exert their computing freedom (@pxref{GNU Distribution}).
37858 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
37859 mechanism that allows users to get the best of both worlds: debugging
37860 information can be stripped from the binaries and stored in separate
37861 files. GDB is then able to load debugging information from those files,
37862 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
37865 The GNU distribution takes advantage of this by storing debugging
37866 information in the @code{lib/debug} sub-directory of a separate package
37867 output unimaginatively called @code{debug} (@pxref{Packages with
37868 Multiple Outputs}). Users can choose to install the @code{debug} output
37869 of a package when they need it. For instance, the following command
37870 installs the debugging information for the GNU C Library and for GNU
37874 guix install glibc:debug guile:debug
37877 GDB must then be told to look for debug files in the user's profile, by
37878 setting the @code{debug-file-directory} variable (consider setting it
37879 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
37883 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
37886 From there on, GDB will pick up debugging information from the
37887 @file{.debug} files under @file{~/.guix-profile/lib/debug}.
37889 Below is an alternative GDB script which is useful when working with
37890 other profiles. It takes advantage of the optional Guile integration in
37891 GDB. This snippet is included by default on Guix System in the
37892 @file{~/.gdbinit} file.
37896 (use-modules (gdb))
37897 (execute (string-append "set debug-file-directory "
37898 (or (getenv "GDB_DEBUG_FILE_DIRECTORY")
37899 "~/.guix-profile/lib/debug")))
37903 In addition, you will most likely want GDB to be able to show the source
37904 code being debugged. To do that, you will have to unpack the source
37905 code of the package of interest (obtained with @code{guix build
37906 --source}, @pxref{Invoking guix build}), and to point GDB to that source
37907 directory using the @code{directory} command (@pxref{Source Path,
37908 @code{directory},, gdb, Debugging with GDB}).
37910 @c XXX: keep me up-to-date
37911 The @code{debug} output mechanism in Guix is implemented by the
37912 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
37913 opt-in---debugging information is available only for the packages with
37914 definitions explicitly declaring a @code{debug} output. To check
37915 whether a package has a @code{debug} output, use @command{guix package
37916 --list-available} (@pxref{Invoking guix package}).
37918 Read on for how to deal with packages lacking a @code{debug} output.
37920 @node Rebuilding Debug Info
37921 @section Rebuilding Debug Info
37923 @cindex debugging info, rebuilding
37924 As we saw above, some packages, but not all, provide debugging info in a
37925 @code{debug} output. What can you do when debugging info is missing?
37926 The @option{--with-debug-info} option provides a solution to that: it
37927 allows you to rebuild the package(s) for which debugging info is
37928 missing---and only those---and to graft those onto the application
37929 you're debugging. Thus, while it's not as fast as installing a
37930 @code{debug} output, it is relatively inexpensive.
37932 Let's illustrate that. Suppose you're experiencing a bug in Inkscape
37933 and would like to see what's going on in GLib, a library that's deep
37934 down in its dependency graph. As it turns out, GLib does not have a
37935 @code{debug} output and the backtrace GDB shows is all sadness:
37939 #0 0x00007ffff5f92190 in g_getenv ()
37940 from /gnu/store/@dots{}-glib-2.62.6/lib/libglib-2.0.so.0
37941 #1 0x00007ffff608a7d6 in gobject_init_ctor ()
37942 from /gnu/store/@dots{}-glib-2.62.6/lib/libgobject-2.0.so.0
37943 #2 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=1, argv=argv@@entry=0x7fffffffcfd8,
37944 env=env@@entry=0x7fffffffcfe8) at dl-init.c:72
37945 #3 0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=<optimized out>)
37949 To address that, you install Inkscape linked against a variant GLib that
37950 contains debug info:
37953 guix install inkscape --with-debug-info=glib
37956 This time, debugging will be a whole lot nicer:
37959 $ gdb --args sh -c 'exec inkscape'
37962 Function "g_getenv" not defined.
37963 Make breakpoint pending on future shared library load? (y or [n]) y
37964 Breakpoint 1 (g_getenv) pending.
37966 Starting program: /gnu/store/@dots{}-profile/bin/sh -c exec\ inkscape
37969 #0 g_getenv (variable=variable@@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252
37970 #1 0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380
37971 #2 gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493
37972 #3 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=3, argv=argv@@entry=0x7fffffffd088,
37973 env=env@@entry=0x7fffffffd0a8) at dl-init.c:72
37979 Note that there can be packages for which @option{--with-debug-info}
37980 will not have the desired effect. @xref{Package Transformation Options,
37981 @option{--with-debug-info}}, for more information.
37983 @node Security Updates
37984 @chapter Security Updates
37986 @cindex security updates
37987 @cindex security vulnerabilities
37988 Occasionally, important security vulnerabilities are discovered in software
37989 packages and must be patched. Guix developers try hard to keep track of
37990 known vulnerabilities and to apply fixes as soon as possible in the
37991 @code{master} branch of Guix (we do not yet provide a ``stable'' branch
37992 containing only security updates). The @command{guix lint} tool helps
37993 developers find out about vulnerable versions of software packages in the
37998 gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
37999 gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276
38000 gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
38004 @xref{Invoking guix lint}, for more information.
38006 Guix follows a functional
38007 package management discipline (@pxref{Introduction}), which implies
38008 that, when a package is changed, @emph{every package that depends on it}
38009 must be rebuilt. This can significantly slow down the deployment of
38010 fixes in core packages such as libc or Bash, since basically the whole
38011 distribution would need to be rebuilt. Using pre-built binaries helps
38012 (@pxref{Substitutes}), but deployment may still take more time than
38016 To address this, Guix implements @dfn{grafts}, a mechanism that allows
38017 for fast deployment of critical updates without the costs associated
38018 with a whole-distribution rebuild. The idea is to rebuild only the
38019 package that needs to be patched, and then to ``graft'' it onto packages
38020 explicitly installed by the user and that were previously referring to
38021 the original package. The cost of grafting is typically very low, and
38022 order of magnitudes lower than a full rebuild of the dependency chain.
38024 @cindex replacements of packages, for grafts
38025 For instance, suppose a security update needs to be applied to Bash.
38026 Guix developers will provide a package definition for the ``fixed''
38027 Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining
38028 Packages}). Then, the original package definition is augmented with a
38029 @code{replacement} field pointing to the package containing the bug fix:
38036 (replacement bash-fixed)))
38039 From there on, any package depending directly or indirectly on Bash---as
38040 reported by @command{guix gc --requisites} (@pxref{Invoking guix
38041 gc})---that is installed is automatically ``rewritten'' to refer to
38042 @code{bash-fixed} instead of @code{bash}. This grafting process takes
38043 time proportional to the size of the package, usually less than a
38044 minute for an ``average'' package on a recent machine. Grafting is
38045 recursive: when an indirect dependency requires grafting, then grafting
38046 ``propagates'' up to the package that the user is installing.
38048 Currently, the length of the name and version of the graft and that of
38049 the package it replaces (@code{bash-fixed} and @code{bash} in the example
38050 above) must be equal. This restriction mostly comes from the fact that
38051 grafting works by patching files, including binary files, directly.
38052 Other restrictions may apply: for instance, when adding a graft to a
38053 package providing a shared library, the original shared library and its
38054 replacement must have the same @code{SONAME} and be binary-compatible.
38056 The @option{--no-grafts} command-line option allows you to forcefully
38057 avoid grafting (@pxref{Common Build Options, @option{--no-grafts}}).
38061 guix build bash --no-grafts
38065 returns the store file name of the original Bash, whereas:
38072 returns the store file name of the ``fixed'', replacement Bash. This
38073 allows you to distinguish between the two variants of Bash.
38075 To verify which Bash your whole profile refers to, you can run
38076 (@pxref{Invoking guix gc}):
38079 guix gc -R $(readlink -f ~/.guix-profile) | grep bash
38083 @dots{} and compare the store file names that you get with those above.
38084 Likewise for a complete Guix system generation:
38087 guix gc -R $(guix system build my-config.scm) | grep bash
38090 Lastly, to check which Bash running processes are using, you can use the
38091 @command{lsof} command:
38094 lsof | grep /gnu/store/.*bash
38098 @node Bootstrapping
38099 @chapter Bootstrapping
38101 @c Adapted from the ELS 2013 paper.
38103 @cindex bootstrapping
38105 Bootstrapping in our context refers to how the distribution gets built
38106 ``from nothing''. Remember that the build environment of a derivation
38107 contains nothing but its declared inputs (@pxref{Introduction}). So
38108 there's an obvious chicken-and-egg problem: how does the first package
38109 get built? How does the first compiler get compiled?
38111 It is tempting to think of this question as one that only die-hard
38112 hackers may care about. However, while the answer to that question is
38113 technical in nature, its implications are wide-ranging. How the
38114 distribution is bootstrapped defines the extent to which we, as
38115 individuals and as a collective of users and hackers, can trust the
38116 software we run. It is a central concern from the standpoint of
38117 @emph{security} and from a @emph{user freedom} viewpoint.
38119 @cindex bootstrap binaries
38120 The GNU system is primarily made of C code, with libc at its core. The
38121 GNU build system itself assumes the availability of a Bourne shell and
38122 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
38123 `grep'. Furthermore, build programs---programs that run
38124 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
38125 (@pxref{Derivations}). Consequently, to be able to build anything at
38126 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
38127 Binutils, libc, and the other packages mentioned above---the
38128 @dfn{bootstrap binaries}.
38130 These bootstrap binaries are ``taken for granted'', though we can also
38131 re-create them if needed (@pxref{Preparing to Use the Bootstrap
38135 * Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
38136 * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
38139 @node Reduced Binary Seed Bootstrap
38140 @section The Reduced Binary Seed Bootstrap
38142 Guix---like other GNU/Linux distributions---is traditionally bootstrapped from
38143 a set of bootstrap binaries: Bourne shell, command-line tools provided by GNU
38144 Coreutils, Awk, Findutils, `sed', and `grep' and Guile, GCC, Binutils, and the
38145 GNU C Library (@pxref{Bootstrapping}). Usually, these bootstrap binaries are
38146 ``taken for granted.''
38148 Taking the bootstrap binaries for granted means that we consider them to
38149 be a correct and trustworthy ``seed'' for building the complete system.
38150 Therein lies a problem: the combined size of these bootstrap binaries is
38151 about 250MB (@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditing
38152 or even inspecting these is next to impossible.
38154 For @code{i686-linux} and @code{x86_64-linux}, Guix now features a
38155 ``Reduced Binary Seed'' bootstrap @footnote{We would like to say: ``Full
38156 Source Bootstrap'' and while we are working towards that goal it would
38157 be hyperbole to use that term for what we do now.}.
38159 The Reduced Binary Seed bootstrap removes the most critical tools---from a
38160 trust perspective---from the bootstrap binaries: GCC, Binutils and the GNU C
38161 Library are replaced by: @code{bootstrap-mescc-tools} (a tiny assembler and
38162 linker) and @code{bootstrap-mes} (a small Scheme Interpreter and a C compiler
38163 written in Scheme and the Mes C Library, built for TinyCC and for GCC).
38165 Using these new binary seeds the ``missing'' Binutils, GCC, and the GNU
38166 C Library are built from source. From here on the more traditional
38167 bootstrap process resumes. This approach has reduced the bootstrap
38168 binaries in size to about 145MB in Guix v1.1.
38170 The next step that Guix has taken is to replace the shell and all its
38171 utilities with implementations in Guile Scheme, the @emph{Scheme-only
38172 bootstrap}. Gash (@pxref{Gash,,, gash, The Gash manual}) is a
38173 POSIX-compatible shell that replaces Bash, and it comes with Gash Utils
38174 which has minimalist replacements for Awk, the GNU Core Utilities, Grep,
38175 Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were
38176 removed are now built from source.
38178 Building the GNU System from source is currently only possible by adding
38179 some historical GNU packages as intermediate steps@footnote{Packages
38180 such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5},
38181 @code{gzip-1.2.4}, @code{tar-1.22}, and some others. For details, see
38182 @file{gnu/packages/commencement.scm}.}. As Gash and Gash Utils mature,
38183 and GNU packages become more bootstrappable again (e.g., new releases of
38184 GNU Sed will also ship as gzipped tarballs again, as alternative to the
38185 hard to bootstrap @code{xz}-compression), this set of added packages can
38186 hopefully be reduced again.
38188 The graph below shows the resulting dependency graph for
38189 @code{gcc-core-mesboot0}, the bootstrap compiler used for the
38190 traditional bootstrap of the rest of the Guix System.
38192 @c ./pre-inst-env guix graph -e '(@@ (gnu packages commencement) gcc-core-mesboot0)' | sed -re 's,((bootstrap-mescc-tools|bootstrap-mes|guile-bootstrap).*shape =) box,\1 ellipse,' > doc/images/gcc-core-mesboot0-graph.dot
38193 @image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of gcc-core-mesboot0}
38195 The only significant binary bootstrap seeds that remain@footnote{
38196 Ignoring the 68KB @code{mescc-tools}; that will be removed later,
38197 together with @code{mes}.} are a Scheme interpreter and a Scheme
38198 compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the
38199 static binaries for @file{bash}, @code{tar}, and @code{xz} that are used
38200 to get Guile running.}.
38202 This further reduction has brought down the size of the binary seed to
38203 about 60MB for @code{i686-linux} and @code{x86_64-linux}.
38205 Work is ongoing to remove all binary blobs from our free software
38206 bootstrap stack, working towards a Full Source Bootstrap. Also ongoing
38207 is work to bring these bootstraps to the @code{arm-linux} and
38208 @code{aarch64-linux} architectures and to the Hurd.
38210 If you are interested, join us on @samp{#bootstrappable} on the Freenode
38211 IRC network or discuss on @email{bug-mes@@gnu.org} or
38212 @email{gash-devel@@nongnu.org}.
38214 @node Preparing to Use the Bootstrap Binaries
38215 @section Preparing to Use the Bootstrap Binaries
38217 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
38218 @c large image, it's hard to scroll. Oh well.
38219 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
38221 The figure above shows the very beginning of the dependency graph of the
38222 distribution, corresponding to the package definitions of the @code{(gnu
38223 packages bootstrap)} module. A similar figure can be generated with
38224 @command{guix graph} (@pxref{Invoking guix graph}), along the lines of:
38227 guix graph -t derivation \
38228 -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
38229 | dot -Tps > gcc.ps
38232 or, for the further Reduced Binary Seed bootstrap
38235 guix graph -t derivation \
38236 -e '(@@@@ (gnu packages bootstrap) %bootstrap-mes)' \
38237 | dot -Tps > mes.ps
38240 At this level of detail, things are
38241 slightly complex. First, Guile itself consists of an ELF executable,
38242 along with many source and compiled Scheme files that are dynamically
38243 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
38244 tarball shown in this graph. This tarball is part of Guix's ``source''
38245 distribution, and gets inserted into the store with @code{add-to-store}
38246 (@pxref{The Store}).
38248 But how do we write a derivation that unpacks this tarball and adds it
38249 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
38250 derivation---the first one that gets built---uses @code{bash} as its
38251 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
38252 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
38253 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
38254 the Guix source distribution, whose sole purpose is to allow the Guile
38255 tarball to be unpacked.
38257 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
38258 Guile that can be used to run subsequent build programs. Its first task
38259 is to download tarballs containing the other pre-built binaries---this
38260 is what the @file{.tar.xz.drv} derivations do. Guix modules such as
38261 @code{ftp-client.scm} are used for this purpose. The
38262 @code{module-import.drv} derivations import those modules in a directory
38263 in the store, using the original layout. The
38264 @code{module-import-compiled.drv} derivations compile those modules, and
38265 write them in an output directory with the right layout. This
38266 corresponds to the @code{#:modules} argument of
38267 @code{build-expression->derivation} (@pxref{Derivations}).
38269 Finally, the various tarballs are unpacked by the derivations
38270 @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, or
38271 @code{bootstrap-mes-0.drv} and @code{bootstrap-mescc-tools-0.drv}, at which
38272 point we have a working C tool chain.
38274 @unnumberedsec Building the Build Tools
38276 Bootstrapping is complete when we have a full tool chain that does not
38277 depend on the pre-built bootstrap tools discussed above. This
38278 no-dependency requirement is verified by checking whether the files of
38279 the final tool chain contain references to the @file{/gnu/store}
38280 directories of the bootstrap inputs. The process that leads to this
38281 ``final'' tool chain is described by the package definitions found in
38282 the @code{(gnu packages commencement)} module.
38284 The @command{guix graph} command allows us to ``zoom out'' compared to
38285 the graph above, by looking at the level of package objects instead of
38286 individual derivations---remember that a package may translate to
38287 several derivations, typically one derivation to download its source,
38288 one to build the Guile modules it needs, and one to actually build the
38289 package from source. The command:
38292 guix graph -t bag \
38293 -e '(@@@@ (gnu packages commencement)
38294 glibc-final-with-bootstrap-bash)' | xdot -
38298 displays the dependency graph leading to the ``final'' C
38299 library@footnote{You may notice the @code{glibc-intermediate} label,
38300 suggesting that it is not @emph{quite} final, but as a good
38301 approximation, we will consider it final.}, depicted below.
38303 @image{images/bootstrap-packages,6in,,Dependency graph of the early packages}
38305 @c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
38306 The first tool that gets built with the bootstrap binaries is
38307 GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite
38308 for all the following packages. From there Findutils and Diffutils get
38311 Then come the first-stage Binutils and GCC, built as pseudo cross
38312 tools---i.e., with @option{--target} equal to @option{--host}. They are
38313 used to build libc. Thanks to this cross-build trick, this libc is
38314 guaranteed not to hold any reference to the initial tool chain.
38316 From there the final Binutils and GCC (not shown above) are built. GCC
38317 uses @command{ld} from the final Binutils, and links programs against
38318 the just-built libc. This tool chain is used to build the other
38319 packages used by Guix and by the GNU Build System: Guile, Bash,
38322 And voilà! At this point we have the complete set of build tools that
38323 the GNU Build System expects. These are in the @code{%final-inputs}
38324 variable of the @code{(gnu packages commencement)} module, and are
38325 implicitly used by any package that uses @code{gnu-build-system}
38326 (@pxref{Build Systems, @code{gnu-build-system}}).
38329 @unnumberedsec Building the Bootstrap Binaries
38331 @cindex bootstrap binaries
38332 Because the final tool chain does not depend on the bootstrap binaries,
38333 those rarely need to be updated. Nevertheless, it is useful to have an
38334 automated way to produce them, should an update occur, and this is what
38335 the @code{(gnu packages make-bootstrap)} module provides.
38337 The following command builds the tarballs containing the bootstrap binaries
38338 (Binutils, GCC, glibc, for the traditional bootstrap and linux-libre-headers,
38339 bootstrap-mescc-tools, bootstrap-mes for the Reduced Binary Seed bootstrap,
38340 and Guile, and a tarball containing a mixture of Coreutils and other basic
38341 command-line tools):
38344 guix build bootstrap-tarballs
38347 The generated tarballs are those that should be referred to in the
38348 @code{(gnu packages bootstrap)} module mentioned at the beginning of
38351 Still here? Then perhaps by now you've started to wonder: when do we
38352 reach a fixed point? That is an interesting question! The answer is
38353 unknown, but if you would like to investigate further (and have
38354 significant computational and storage resources to do so), then let us
38357 @unnumberedsec Reducing the Set of Bootstrap Binaries
38359 Our traditional bootstrap includes GCC, GNU Libc, Guile, etc. That's a lot of
38360 binary code! Why is that a problem? It's a problem because these big chunks
38361 of binary code are practically non-auditable, which makes it hard to establish
38362 what source code produced them. Every unauditable binary also leaves us
38363 vulnerable to compiler backdoors as described by Ken Thompson in the 1984
38364 paper @emph{Reflections on Trusting Trust}.
38366 This is mitigated by the fact that our bootstrap binaries were generated
38367 from an earlier Guix revision. Nevertheless it lacks the level of
38368 transparency that we get in the rest of the package dependency graph,
38369 where Guix always gives us a source-to-binary mapping. Thus, our goal
38370 is to reduce the set of bootstrap binaries to the bare minimum.
38372 The @uref{https://bootstrappable.org, Bootstrappable.org web site} lists
38373 on-going projects to do that. One of these is about replacing the
38374 bootstrap GCC with a sequence of assemblers, interpreters, and compilers
38375 of increasing complexity, which could be built from source starting from
38376 a simple and auditable assembler.
38378 Our first major achievement is the replacement of of GCC, the GNU C Library
38379 and Binutils by MesCC-Tools (a simple hex linker and macro assembler) and Mes
38380 (@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, a Scheme interpreter
38381 and C compiler in Scheme). Neither MesCC-Tools nor Mes can be fully
38382 bootstrapped yet and thus we inject them as binary seeds. We call this the
38383 Reduced Binary Seed bootstrap, as it has halved the size of our bootstrap
38384 binaries! Also, it has eliminated the C compiler binary; i686-linux and
38385 x86_64-linux Guix packages are now bootstrapped without any binary C compiler.
38387 Work is ongoing to make MesCC-Tools and Mes fully bootstrappable and we are
38388 also looking at any other bootstrap binaries. Your help is welcome!
38391 @chapter Porting to a New Platform
38393 As discussed above, the GNU distribution is self-contained, and
38394 self-containment is achieved by relying on pre-built ``bootstrap
38395 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
38396 operating system kernel, CPU architecture, and application binary
38397 interface (ABI). Thus, to port the distribution to a platform that is
38398 not yet supported, one must build those bootstrap binaries, and update
38399 the @code{(gnu packages bootstrap)} module to use them on that platform.
38401 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
38402 When everything goes well, and assuming the GNU tool chain supports the
38403 target platform, this can be as simple as running a command like this
38407 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
38410 For this to work, the @code{glibc-dynamic-linker} procedure in
38411 @code{(gnu packages bootstrap)} must be augmented to return the right
38412 file name for libc's dynamic linker on that platform; likewise,
38413 @code{system->linux-architecture} in @code{(gnu packages linux)} must be
38414 taught about the new platform.
38416 Once these are built, the @code{(gnu packages bootstrap)} module needs
38417 to be updated to refer to these binaries on the target platform. That
38418 is, the hashes and URLs of the bootstrap tarballs for the new platform
38419 must be added alongside those of the currently supported platforms. The
38420 bootstrap Guile tarball is treated specially: it is expected to be
38421 available locally, and @file{gnu/local.mk} has rules to download it for
38422 the supported architectures; a rule for the new platform must be added
38425 In practice, there may be some complications. First, it may be that the
38426 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
38427 above) is not recognized by all the GNU tools. Typically, glibc
38428 recognizes some of these, whereas GCC uses an extra @option{--with-abi}
38429 configure flag (see @code{gcc.scm} for examples of how to handle this).
38430 Second, some of the required packages could fail to build for that
38431 platform. Lastly, the generated binaries could be broken for some
38434 @c *********************************************************************
38435 @include contributing.texi
38437 @c *********************************************************************
38438 @node Acknowledgments
38439 @chapter Acknowledgments
38441 Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
38442 which was designed and
38443 implemented by Eelco Dolstra, with contributions from other people (see
38444 the @file{nix/AUTHORS} file in Guix). Nix pioneered functional package
38445 management, and promoted unprecedented features, such as transactional
38446 package upgrades and rollbacks, per-user profiles, and referentially
38447 transparent build processes. Without this work, Guix would not exist.
38449 The Nix-based software distributions, Nixpkgs and NixOS, have also been
38450 an inspiration for Guix.
38452 GNU@tie{}Guix itself is a collective work with contributions from a
38453 number of people. See the @file{AUTHORS} file in Guix for more
38454 information on these fine people. The @file{THANKS} file lists people
38455 who have helped by reporting bugs, taking care of the infrastructure,
38456 providing artwork and themes, making suggestions, and more---thank you!
38459 @c *********************************************************************
38460 @node GNU Free Documentation License
38461 @appendix GNU Free Documentation License
38462 @cindex license, GNU Free Documentation License
38463 @include fdl-1.3.texi
38465 @c *********************************************************************
38466 @node Concept Index
38467 @unnumbered Concept Index
38470 @node Programming Index
38471 @unnumbered Programming Index
38472 @syncodeindex tp fn
38473 @syncodeindex vr fn
38478 @c Local Variables:
38479 @c ispell-local-dictionary: "american";