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-2022 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, 2022 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, 2022 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, 2022 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, 2022 Marius Bakke@*
51 Copyright @copyright{} 2017, 2019, 2020, 2022 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, 2022 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, 2022 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, 2022 Josselin Poiret@*
100 Copyright @copyright{} 2021 muradm@*
101 Copyright @copyright{} 2021, 2022 Andrew Tropin@*
102 Copyright @copyright{} 2021 Sarah Morgensen@*
103 Copyright @copyright{} 2022 Remco van 't Veer@*
104 Copyright @copyright{} 2022 Aleksandr Vityazev@*
105 Copyright @copyright{} 2022 Philip M@sup{c}Grath@*
106 Copyright @copyright{} 2022 Karl Hallsby@*
107 Copyright @copyright{} 2022 Justin Veilleux@*
108 Copyright @copyright{} 2022 Reily Siegel@*
109 Copyright @copyright{} 2022 Simon Streit@*
110 Copyright @copyright{} 2022 (@*
111 Copyright @copyright{} 2022 John Kehayias@*
113 Permission is granted to copy, distribute and/or modify this document
114 under the terms of the GNU Free Documentation License, Version 1.3 or
115 any later version published by the Free Software Foundation; with no
116 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
117 copy of the license is included in the section entitled ``GNU Free
118 Documentation License''.
121 @dircategory System administration
123 * Guix: (guix). Manage installed software and system configuration.
124 * guix package: (guix)Invoking guix package. Installing, removing, and upgrading packages.
125 * guix gc: (guix)Invoking guix gc. Reclaiming unused disk space.
126 * guix pull: (guix)Invoking guix pull. Update the list of available packages.
127 * guix system: (guix)Invoking guix system. Manage the operating system configuration.
128 * guix deploy: (guix)Invoking guix deploy. Manage operating system configurations for remote hosts.
131 @dircategory Software development
133 * guix shell: (guix)Invoking guix shell. Creating software environments.
134 * guix environment: (guix)Invoking guix environment. Building development environments with Guix.
135 * guix build: (guix)Invoking guix build. Building packages.
136 * guix pack: (guix)Invoking guix pack. Creating binary bundles.
140 @title GNU Guix Reference Manual
141 @subtitle Using the GNU Guix Functional Package Manager
142 @author The GNU Guix Developers
145 @vskip 0pt plus 1filll
146 Edition @value{EDITION} @*
154 @c *********************************************************************
158 This document describes GNU Guix version @value{VERSION}, a functional
159 package management tool written for the GNU system.
161 @c TRANSLATORS: You can replace the following paragraph with information on
162 @c how to join your own translation team and how to report issues with the
164 This manual is also available in Simplified Chinese (@pxref{Top,,, guix.zh_CN,
165 GNU Guix参考手册}), French (@pxref{Top,,, guix.fr, Manuel de référence de GNU
166 Guix}), German (@pxref{Top,,, guix.de, Referenzhandbuch zu GNU Guix}),
167 Spanish (@pxref{Top,,, guix.es, Manual de referencia de GNU Guix}), and
168 Russian (@pxref{Top,,, guix.ru, Руководство GNU Guix}). If you
169 would like to translate it in your native language, consider joining
170 @uref{https://translate.fedoraproject.org/projects/guix/documentation-manual,
171 Weblate} (@pxref{Translating Guix}).
174 * Introduction:: What is Guix about?
175 * Installation:: Installing Guix.
176 * System Installation:: Installing the whole operating system.
177 * System Troubleshooting Tips:: When things don't go as planned.
178 * Getting Started:: Your first steps.
179 * Package Management:: Package installation, upgrade, etc.
180 * Channels:: Customizing the package collection.
181 * Development:: Guix-aided software development.
182 * Programming Interface:: Using Guix in Scheme.
183 * Utilities:: Package management commands.
184 * Foreign Architectures:: Build for foreign architectures.
185 * System Configuration:: Configuring the operating system.
186 * Home Configuration:: Configuring the home environment.
187 * Documentation:: Browsing software user manuals.
188 * Platforms:: Defining platforms.
189 * System Images:: Creating system images.
190 * Installing Debugging Files:: Feeding the debugger.
191 * Using TeX and LaTeX:: Typesetting.
192 * Security Updates:: Deploying security fixes quickly.
193 * Bootstrapping:: GNU/Linux built from scratch.
194 * Porting:: Targeting another platform or kernel.
195 * Contributing:: Your help needed!
197 * Acknowledgments:: Thanks!
198 * GNU Free Documentation License:: The license of this manual.
199 * Concept Index:: Concepts.
200 * Programming Index:: Data types, functions, and variables.
203 --- The Detailed Node Listing ---
207 * Managing Software the Guix Way:: What's special.
208 * GNU Distribution:: The packages and tools.
212 * Binary Installation:: Getting Guix running in no time!
213 * Requirements:: Software needed to build and run Guix.
214 * Running the Test Suite:: Testing Guix.
215 * Setting Up the Daemon:: Preparing the build daemon's environment.
216 * Invoking guix-daemon:: Running the build daemon.
217 * Application Setup:: Application-specific setup.
218 * Upgrading Guix:: Upgrading Guix and its build daemon.
220 Setting Up the Daemon
222 * Build Environment Setup:: Preparing the isolated build environment.
223 * Daemon Offload Setup:: Offloading builds to remote machines.
224 * SELinux Support:: Using an SELinux policy for the daemon.
228 * Limitations:: What you can expect.
229 * Hardware Considerations:: Supported hardware.
230 * USB Stick and DVD Installation:: Preparing the installation medium.
231 * Preparing for Installation:: Networking, partitioning, etc.
232 * Guided Graphical Installation:: Easy graphical installation.
233 * Manual Installation:: Manual installation for wizards.
234 * After System Installation:: When installation succeeded.
235 * Installing Guix in a VM:: Guix System playground.
236 * Building the Installation Image:: How this comes to be.
238 System Troubleshooting Tips
240 * Chrooting into an existing system:: Fixing things from a chroot
244 * Keyboard Layout and Networking and Partitioning:: Initial setup.
245 * Proceeding with the Installation:: Installing.
249 * Features:: How Guix will make your life brighter.
250 * Invoking guix package:: Package installation, removal, etc.
251 * Substitutes:: Downloading pre-built binaries.
252 * Packages with Multiple Outputs:: Single source package, multiple outputs.
253 * Invoking guix gc:: Running the garbage collector.
254 * Invoking guix pull:: Fetching the latest Guix and distribution.
255 * Invoking guix time-machine:: Running an older revision of Guix.
256 * Inferiors:: Interacting with another revision of Guix.
257 * Invoking guix describe:: Display information about your Guix revision.
258 * Invoking guix archive:: Exporting and importing store files.
262 * Official Substitute Servers:: One particular source of substitutes.
263 * Substitute Server Authorization:: How to enable or disable substitutes.
264 * Getting Substitutes from Other Servers:: Substitute diversity.
265 * Substitute Authentication:: How Guix verifies substitutes.
266 * Proxy Settings:: How to get substitutes via proxy.
267 * Substitution Failure:: What happens when substitution fails.
268 * On Trusting Binaries:: How can you trust that binary blob?
272 * Specifying Additional Channels:: Extending the package collection.
273 * Using a Custom Guix Channel:: Using a customized Guix.
274 * Replicating Guix:: Running the @emph{exact same} Guix.
275 * Channel Authentication:: How Guix verifies what it fetches.
276 * Channels with Substitutes:: Using channels with available substitutes.
277 * Creating a Channel:: How to write your custom channel.
278 * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
279 * Declaring Channel Dependencies:: How to depend on other channels.
280 * Specifying Channel Authorizations:: Defining channel authors authorizations.
281 * Primary URL:: Distinguishing mirror to original.
282 * Writing Channel News:: Communicating information to channel's users.
286 * Invoking guix shell:: Spawning one-off software environments.
287 * Invoking guix environment:: Setting up development environments.
288 * Invoking guix pack:: Creating software bundles.
289 * The GCC toolchain:: Working with languages supported by GCC.
290 * Invoking guix git authenticate:: Authenticating Git repositories.
292 Programming Interface
294 * Package Modules:: Packages from the programmer's viewpoint.
295 * Defining Packages:: Defining new packages.
296 * Defining Package Variants:: Customizing packages.
297 * Writing Manifests:: The bill of materials of your environment.
298 * Build Systems:: Specifying how packages are built.
299 * Build Phases:: Phases of the build process of a package.
300 * Build Utilities:: Helpers for your package definitions and more.
301 * Search Paths:: Declaring search path environment variables.
302 * The Store:: Manipulating the package store.
303 * Derivations:: Low-level interface to package derivations.
304 * The Store Monad:: Purely functional interface to the store.
305 * G-Expressions:: Manipulating build expressions.
306 * Invoking guix repl:: Programming Guix in Guile.
307 * Using Guix Interactively:: Fine-grain interaction at the REPL.
311 * package Reference:: The package data type.
312 * origin Reference:: The origin data type.
316 * Invoking guix build:: Building packages from the command line.
317 * Invoking guix edit:: Editing package definitions.
318 * Invoking guix download:: Downloading a file and printing its hash.
319 * Invoking guix hash:: Computing the cryptographic hash of a file.
320 * Invoking guix import:: Importing package definitions.
321 * Invoking guix refresh:: Updating package definitions.
322 * Invoking guix style:: Styling package definitions.
323 * Invoking guix lint:: Finding errors in package definitions.
324 * Invoking guix size:: Profiling disk usage.
325 * Invoking guix graph:: Visualizing the graph of packages.
326 * Invoking guix publish:: Sharing substitutes.
327 * Invoking guix challenge:: Challenging substitute servers.
328 * Invoking guix copy:: Copying to and from a remote store.
329 * Invoking guix container:: Process isolation.
330 * Invoking guix weather:: Assessing substitute availability.
331 * Invoking guix processes:: Listing client processes.
333 Invoking @command{guix build}
335 * Common Build Options:: Build options for most commands.
336 * Package Transformation Options:: Creating variants of packages.
337 * Additional Build Options:: Options specific to 'guix build'.
338 * Debugging Build Failures:: Real life packaging experience.
340 Foreign Architectures
341 * Cross-Compilation:: Cross-compiling for another architecture.
342 * Native Builds:: Targeting another architecture through native builds.
346 * Using the Configuration System:: Customizing your GNU system.
347 * operating-system Reference:: Detail of operating-system declarations.
348 * File Systems:: Configuring file system mounts.
349 * Mapped Devices:: Block device extra processing.
350 * Swap Space:: Backing RAM with disk space.
351 * User Accounts:: Specifying user accounts.
352 * Keyboard Layout:: How the system interprets key strokes.
353 * Locales:: Language and cultural convention settings.
354 * Services:: Specifying system services.
355 * Setuid Programs:: Programs running with elevated privileges.
356 * X.509 Certificates:: Authenticating HTTPS servers.
357 * Name Service Switch:: Configuring libc's name service switch.
358 * Initial RAM Disk:: Linux-Libre bootstrapping.
359 * Bootloader Configuration:: Configuring the boot loader.
360 * Invoking guix system:: Instantiating a system configuration.
361 * Invoking guix deploy:: Deploying a system configuration to a remote host.
362 * Running Guix in a VM:: How to run Guix System in a virtual machine.
363 * Defining Services:: Adding new service definitions.
365 Home Environment Configuration
367 * Invoking guix home:: Instantiating a home environment configuration.
371 * Base Services:: Essential system services.
372 * Scheduled Job Execution:: The mcron service.
373 * Log Rotation:: The rottlog service.
374 * Networking Setup:: Setting up network interfaces.
375 * Networking Services:: Firewall, SSH daemon, etc.
376 * Unattended Upgrades:: Automated system upgrades.
377 * X Window:: Graphical display.
378 * Printing Services:: Local and remote printer support.
379 * Desktop Services:: D-Bus and desktop services.
380 * Sound Services:: ALSA and Pulseaudio services.
381 * Database Services:: SQL databases, key-value stores, etc.
382 * Mail Services:: IMAP, POP3, SMTP, and all that.
383 * Messaging Services:: Messaging services.
384 * Telephony Services:: Telephony services.
385 * Monitoring Services:: Monitoring services.
386 * Kerberos Services:: Kerberos services.
387 * LDAP Services:: LDAP services.
388 * Web Services:: Web servers.
389 * Certificate Services:: TLS certificates via Let's Encrypt.
390 * DNS Services:: DNS daemons.
391 * VPN Services:: VPN daemons.
392 * Network File System:: NFS related services.
393 * Samba Services:: Samba services.
394 * Continuous Integration:: Cuirass and Laminar services.
395 * Power Management Services:: Extending battery life.
396 * Audio Services:: The MPD.
397 * Virtualization Services:: Virtualization services.
398 * Version Control Services:: Providing remote access to Git repositories.
399 * Game Services:: Game servers.
400 * PAM Mount Service:: Service to mount volumes when logging in.
401 * Guix Services:: Services relating specifically to Guix.
402 * Linux Services:: Services tied to the Linux kernel.
403 * Hurd Services:: Services specific for a Hurd System.
404 * Miscellaneous Services:: Other services.
408 * Service Composition:: The model for composing services.
409 * Service Types and Services:: Types and services.
410 * Service Reference:: API reference.
411 * Shepherd Services:: A particular type of service.
412 * Complex Configurations:: Defining bindings for complex configurations.
416 * platform Reference:: Detail of platform declarations.
417 * Supported Platforms:: Description of the supported platforms.
421 * image Reference:: Detail of image declarations.
422 * Instantiate an Image:: How to instantiate an image record.
423 * image-type Reference:: Detail of image types declaration.
424 * Image Modules:: Definition of image modules.
426 Installing Debugging Files
428 * Separate Debug Info:: Installing 'debug' outputs.
429 * Rebuilding Debug Info:: Building missing debug info.
433 * Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
434 * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
439 @c *********************************************************************
441 @chapter Introduction
444 GNU Guix@footnote{``Guix'' is pronounced like ``geeks'', or ``ɡiːks''
445 using the international phonetic alphabet (IPA).} is a package
446 management tool for and distribution of the GNU system.
447 Guix makes it easy for unprivileged
448 users to install, upgrade, or remove software packages, to roll back to a
449 previous package set, to build packages from source, and generally
450 assists with the creation and maintenance of software environments.
453 @cindex GuixSD, now Guix System
454 @cindex Guix System Distribution, now Guix System
455 You can install GNU@tie{}Guix on top of an existing GNU/Linux system where it
456 complements the available tools without interference (@pxref{Installation}),
457 or you can use it as a standalone operating system distribution,
458 @dfn{Guix@tie{}System}@footnote{We used to refer to Guix System as ``Guix
459 System Distribution'' or ``GuixSD''. We now consider it makes more sense to
460 group everything under the ``Guix'' banner since, after all, Guix System is
461 readily available through the @command{guix system} command, even if you're
462 using a different distro underneath!}. @xref{GNU Distribution}.
465 * Managing Software the Guix Way:: What's special.
466 * GNU Distribution:: The packages and tools.
469 @node Managing Software the Guix Way
470 @section Managing Software the Guix Way
472 @cindex user interfaces
473 Guix provides a command-line package management interface
474 (@pxref{Package Management}), tools to help with software development
475 (@pxref{Development}), command-line utilities for more advanced usage
476 (@pxref{Utilities}), as well as Scheme programming interfaces
477 (@pxref{Programming Interface}).
479 Its @dfn{build daemon} is responsible for building packages on behalf of
480 users (@pxref{Setting Up the Daemon}) and for downloading pre-built
481 binaries from authorized sources (@pxref{Substitutes}).
483 @cindex extensibility of the distribution
484 @cindex customization, of packages
485 Guix includes package definitions for many GNU and non-GNU packages, all
486 of which @uref{https://www.gnu.org/philosophy/free-sw.html, respect the
487 user's computing freedom}. It is @emph{extensible}: users can write
488 their own package definitions (@pxref{Defining Packages}) and make them
489 available as independent package modules (@pxref{Package Modules}). It
490 is also @emph{customizable}: users can @emph{derive} specialized package
491 definitions from existing ones, including from the command line
492 (@pxref{Package Transformation Options}).
494 @cindex functional package management
496 Under the hood, Guix implements the @dfn{functional package management}
497 discipline pioneered by Nix (@pxref{Acknowledgments}).
498 In Guix, the package build and installation process is seen
499 as a @emph{function}, in the mathematical sense. That function takes inputs,
500 such as build scripts, a compiler, and libraries, and
501 returns an installed package. As a pure function, its result depends
502 solely on its inputs---for instance, it cannot refer to software or
503 scripts that were not explicitly passed as inputs. A build function
504 always produces the same result when passed a given set of inputs. It
505 cannot alter the environment of the running system in
506 any way; for instance, it cannot create, modify, or delete files outside
507 of its build and installation directories. This is achieved by running
508 build processes in isolated environments (or @dfn{containers}), where only their
509 explicit inputs are visible.
512 The result of package build functions is @dfn{cached} in the file
513 system, in a special directory called @dfn{the store} (@pxref{The
514 Store}). Each package is installed in a directory of its own in the
515 store---by default under @file{/gnu/store}. The directory name contains
516 a hash of all the inputs used to build that package; thus, changing an
517 input yields a different directory name.
519 This approach is the foundation for the salient features of Guix: support
520 for transactional package upgrade and rollback, per-user installation, and
521 garbage collection of packages (@pxref{Features}).
524 @node GNU Distribution
525 @section GNU Distribution
528 Guix comes with a distribution of the GNU system consisting entirely of
529 free software@footnote{The term ``free'' here refers to the
530 @url{https://www.gnu.org/philosophy/free-sw.html,freedom provided to
531 users of that software}.}. The
532 distribution can be installed on its own (@pxref{System Installation}),
533 but it is also possible to install Guix as a package manager on top of
534 an installed GNU/Linux system (@pxref{Installation}). When we need to
535 distinguish between the two, we refer to the standalone distribution as
538 The distribution provides core GNU packages such as GNU libc, GCC, and
539 Binutils, as well as many GNU and non-GNU applications. The complete
540 list of available packages can be browsed
541 @url{https://www.gnu.org/software/guix/packages,on-line} or by
542 running @command{guix package} (@pxref{Invoking guix package}):
545 guix package --list-available
548 Our goal is to provide a practical 100% free software distribution of
549 Linux-based and other variants of GNU, with a focus on the promotion and
550 tight integration of GNU components, and an emphasis on programs and
551 tools that help users exert that freedom.
553 Packages are currently available on the following platforms:
558 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel.
561 Intel 32-bit architecture (IA32), Linux-Libre kernel.
564 ARMv7-A architecture with hard float, Thumb-2 and NEON,
565 using the EABI hard-float application binary interface (ABI),
566 and Linux-Libre kernel.
569 little-endian 64-bit ARMv8-A processors, Linux-Libre kernel.
572 @uref{https://hurd.gnu.org, GNU/Hurd} on the Intel 32-bit architecture
575 This configuration is experimental and under development. The easiest
576 way for you to give it a try is by setting up an instance of
577 @code{hurd-vm-service-type} on your GNU/Linux machine
578 (@pxref{transparent-emulation-qemu, @code{hurd-vm-service-type}}).
579 @xref{Contributing}, on how to help!
581 @item mips64el-linux (unsupported)
582 little-endian 64-bit MIPS processors, specifically the Loongson series,
583 n32 ABI, and Linux-Libre kernel. This configuration is no longer fully
584 supported; in particular, there is no ongoing work to ensure that this
585 architecture still works. Should someone decide they wish to revive this
586 architecture then the code is still available.
588 @item powerpc-linux (unsupported)
589 big-endian 32-bit PowerPC processors, specifically the PowerPC G4 with
590 AltiVec support, and Linux-Libre kernel. This configuration is not
591 fully supported and there is no ongoing work to ensure this architecture
594 @item powerpc64le-linux
595 little-endian 64-bit Power ISA processors, Linux-Libre kernel. This
596 includes POWER9 systems such as the
597 @uref{https://www.fsf.org/news/talos-ii-mainboard-and-talos-ii-lite-mainboard-now-fsf-certified-to-respect-your-freedom,
598 RYF Talos II mainboard}. This platform is available as a "technology
599 preview": although it is supported, substitutes are not yet available
600 from the build farm (@pxref{Substitutes}), and some packages may fail to
601 build (@pxref{Tracking Bugs and Patches}). That said, the Guix
602 community is actively working on improving this support, and now is a
603 great time to try it and get involved!
606 little-endian 64-bit RISC-V processors, specifically RV64GC, and
607 Linux-Libre kernel. This platform is available as a "technology preview":
608 although it is supported, substitutes are not yet available from the
609 build farm (@pxref{Substitutes}), and some packages may fail to build
610 (@pxref{Tracking Bugs and Patches}). That said, the Guix community is
611 actively working on improving this support, and now is a great time to
612 try it and get involved!
616 With Guix@tie{}System, you @emph{declare} all aspects of the operating system
617 configuration and Guix takes care of instantiating the configuration in a
618 transactional, reproducible, and stateless fashion (@pxref{System
619 Configuration}). Guix System uses the Linux-libre kernel, the Shepherd
620 initialization system (@pxref{Introduction,,, shepherd, The GNU Shepherd
621 Manual}), the well-known GNU utilities and tool chain, as well as the
622 graphical environment or system services of your choice.
624 Guix System is available on all the above platforms except
625 @code{mips64el-linux}, @code{powerpc-linux}, @code{powerpc64le-linux} and
626 @code{riscv64-linux}.
629 For information on porting to other architectures or kernels,
632 Building this distribution is a cooperative effort, and you are invited
633 to join! @xref{Contributing}, for information about how you can help.
636 @c *********************************************************************
638 @chapter Installation
640 @cindex installing Guix
643 We recommend the use of this
644 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
645 shell installer script} to install Guix on top of a running GNU/Linux system,
646 thereafter called a @dfn{foreign distro}.@footnote{This section is concerned
647 with the installation of the package manager, which can be done on top of a
648 running GNU/Linux system. If, instead, you want to install the complete GNU
649 operating system, @pxref{System Installation}.} The script automates the
650 download, installation, and initial configuration of Guix. It should be run
654 @cindex foreign distro
655 @cindex directories related to foreign distro
656 When installed on a foreign distro, GNU@tie{}Guix complements the available
657 tools without interference. Its data lives exclusively in two directories,
658 usually @file{/gnu/store} and @file{/var/guix}; other files on your system,
659 such as @file{/etc}, are left untouched.
661 Once installed, Guix can be updated by running @command{guix pull}
662 (@pxref{Invoking guix pull}).
664 If you prefer to perform the installation steps manually or want to tweak
665 them, you may find the following subsections useful. They describe the
666 software requirements of Guix, as well as how to install it manually and get
670 * Binary Installation:: Getting Guix running in no time!
671 * Requirements:: Software needed to build and run Guix.
672 * Running the Test Suite:: Testing Guix.
673 * Setting Up the Daemon:: Preparing the build daemon's environment.
674 * Invoking guix-daemon:: Running the build daemon.
675 * Application Setup:: Application-specific setup.
676 * Upgrading Guix:: Upgrading Guix and its build daemon.
679 @node Binary Installation
680 @section Binary Installation
682 @cindex installing Guix from binaries
683 @cindex installer script
684 This section describes how to install Guix on an arbitrary system from a
685 self-contained tarball providing binaries for Guix and for all its
686 dependencies. This is often quicker than installing from source, which
687 is described in the next sections. The only requirement is to have
690 @c Note duplicated from the ``Installation'' node.
692 We recommend the use of this
693 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
694 shell installer script}. The script automates the download, installation, and
695 initial configuration steps described below. It should be run as the root
696 user. As root, you can thus run this:
700 wget https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh
701 chmod +x guix-install.sh
705 If you're running Debian or a derivative such as Ubuntu, you can instead
706 install the package (it might be a version older than @value{VERSION}
707 but you can update it afterwards by running @samp{guix pull}):
710 sudo apt install guix
713 Likewise on openSUSE:
716 sudo zypper install guix
719 When you're done, @pxref{Application Setup} for extra configuration you
720 might need, and @ref{Getting Started} for your first steps!
723 Installing goes along these lines:
727 @cindex downloading Guix binary
728 Download the binary tarball from
729 @indicateurl{@value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz},
730 where @code{x86_64-linux} can be replaced with @code{i686-linux} for an
731 @code{i686} (32-bits) machine already running the kernel Linux, and so on
732 (@pxref{GNU Distribution}).
734 @c The following is somewhat duplicated in ``System Installation''.
735 Make sure to download the associated @file{.sig} file and to verify the
736 authenticity of the tarball against it, along these lines:
739 $ wget @value{BASE-URL}/guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
740 $ gpg --verify guix-binary-@value{VERSION}.x86_64-linux.tar.xz.sig
743 If that command fails because you do not have the required public key,
744 then run this command to import it:
747 $ wget '@value{OPENPGP-SIGNING-KEY-URL}' \
748 -qO - | gpg --import -
752 and rerun the @code{gpg --verify} command.
754 Take note that a warning like ``This key is not certified with a trusted
755 signature!'' is normal.
757 @c end authentication part
760 Now, you need to become the @code{root} user. Depending on your distribution,
761 you may have to run @code{su -} or @code{sudo -i}. As @code{root}, run:
765 # tar --warning=no-timestamp -xf \
766 /path/to/guix-binary-@value{VERSION}.x86_64-linux.tar.xz
767 # mv var/guix /var/ && mv gnu /
770 This creates @file{/gnu/store} (@pxref{The Store}) and @file{/var/guix}.
771 The latter contains a ready-to-use profile for @code{root} (see next
774 Do @emph{not} unpack the tarball on a working Guix system since that
775 would overwrite its own essential files.
777 The @option{--warning=no-timestamp} option makes sure GNU@tie{}tar does
778 not emit warnings about ``implausibly old time stamps'' (such
779 warnings were triggered by GNU@tie{}tar 1.26 and older; recent
781 They stem from the fact that all the
782 files in the archive have their modification time set to 1 (which
783 means January 1st, 1970). This is done on purpose to make sure the
784 archive content is independent of its creation time, thus making it
788 Make the profile available under @file{~root/.config/guix/current}, which is
789 where @command{guix pull} will install updates (@pxref{Invoking guix pull}):
792 # mkdir -p ~root/.config/guix
793 # ln -sf /var/guix/profiles/per-user/root/current-guix \
794 ~root/.config/guix/current
797 Source @file{etc/profile} to augment @env{PATH} and other relevant
798 environment variables:
801 # GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
802 source $GUIX_PROFILE/etc/profile
806 Create the group and user accounts for build users as explained below
807 (@pxref{Build Environment Setup}).
810 Run the daemon, and set it to automatically start on boot.
812 If your host distro uses the systemd init system, this can be achieved
815 @c Versions of systemd that supported symlinked service files are not
816 @c yet widely deployed, so we should suggest that users copy the service
819 @c See this thread for more information:
820 @c https://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
823 # cp ~root/.config/guix/current/lib/systemd/system/gnu-store.mount \
824 ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
826 # systemctl enable --now gnu-store.mount guix-daemon
829 You may also want to arrange for @command{guix gc} to run periodically:
832 # cp ~root/.config/guix/current/lib/systemd/system/guix-gc.service \
833 ~root/.config/guix/current/lib/systemd/system/guix-gc.timer \
835 # systemctl enable --now guix-gc.timer
838 You may want to edit @file{guix-gc.service} to adjust the command line
839 options to fit your needs (@pxref{Invoking guix gc}).
841 If your host distro uses the Upstart init system:
844 # initctl reload-configuration
845 # cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
850 Otherwise, you can still start the daemon manually with:
853 # ~root/.config/guix/current/bin/guix-daemon \
854 --build-users-group=guixbuild
858 Make the @command{guix} command available to other users on the machine,
862 # mkdir -p /usr/local/bin
864 # ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
867 It is also a good idea to make the Info version of this manual available
871 # mkdir -p /usr/local/share/info
872 # cd /usr/local/share/info
873 # for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
877 That way, assuming @file{/usr/local/share/info} is in the search path,
878 running @command{info guix} will open this manual (@pxref{Other Info
879 Directories,,, texinfo, GNU Texinfo}, for more details on changing the
883 @cindex substitutes, authorization thereof
884 To use substitutes from @code{@value{SUBSTITUTE-SERVER-1}},
885 @code{@value{SUBSTITUTE-SERVER-2}} or a mirror (@pxref{Substitutes}),
889 # guix archive --authorize < \
890 ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
891 # guix archive --authorize < \
892 ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
896 If you do not enable substitutes, Guix will end up building
897 @emph{everything} from source on your machine, making each installation
898 and upgrade very expensive. @xref{On Trusting Binaries}, for a
899 discussion of reasons why one might want do disable substitutes.
903 Each user may need to perform a few additional steps to make their Guix
904 environment ready for use, @pxref{Application Setup}.
907 Voilà, the installation is complete!
909 You can confirm that Guix is working by installing a sample package into
916 The binary installation tarball can be (re)produced and verified simply
917 by running the following command in the Guix source tree:
920 make guix-binary.@var{system}.tar.xz
924 ...@: which, in turn, runs:
927 guix pack -s @var{system} --localstatedir \
928 --profile-name=current-guix guix
931 @xref{Invoking guix pack}, for more info on this handy tool.
934 @section Requirements
936 This section lists requirements when building Guix from source. The
937 build procedure for Guix is the same as for other GNU software, and is
938 not covered here. Please see the files @file{README} and @file{INSTALL}
939 in the Guix source tree for additional details.
941 @cindex official website
942 GNU Guix is available for download from its website at
943 @url{https://www.gnu.org/software/guix/}.
945 GNU Guix depends on the following packages:
948 @item @url{https://gnu.org/software/guile/, GNU Guile}, version 3.0.x,
949 version 3.0.3 or later;
950 @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
953 @uref{https://gitlab.com/gnutls/guile/, Guile-GnuTLS} (@pxref{Guile
954 Preparations, how to install the GnuTLS bindings for Guile,,
955 gnutls-guile, GnuTLS-Guile})@footnote{The Guile bindings to
956 @uref{https://gnutls.org/, GnuTLS} were distributed as part of GnuTLS
957 until version 3.7.8 included.};
959 @uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, version 0.1.0
961 @item @uref{https://notabug.org/guile-zlib/guile-zlib, Guile-zlib},
962 version 0.1.0 or later;
963 @item @uref{https://notabug.org/guile-lzlib/guile-lzlib, Guile-lzlib};
964 @item @uref{https://www.nongnu.org/guile-avahi/, Guile-Avahi};
966 @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, version 0.5.0
968 @item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
970 @item @url{https://www.gnu.org/software/make/, GNU Make}.
973 The following dependencies are optional:
977 @c Note: We need at least 0.13.0 for #:nodelay.
978 Support for build offloading (@pxref{Daemon Offload Setup}) and
979 @command{guix copy} (@pxref{Invoking guix copy}) depends on
980 @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH},
981 version 0.13.0 or later.
984 @uref{https://notabug.org/guile-zstd/guile-zstd, Guile-zstd}, for zstd
985 compression and decompression in @command{guix publish} and for
986 substitutes (@pxref{Invoking guix publish}).
989 @uref{https://ngyro.com/software/guile-semver.html, Guile-Semver} for
990 the @code{crate} importer (@pxref{Invoking guix import}).
993 @uref{https://www.nongnu.org/guile-lib/doc/ref/htmlprag/, Guile-Lib} for
994 the @code{go} importer (@pxref{Invoking guix import}) and for some of
995 the ``updaters'' (@pxref{Invoking guix refresh}).
998 When @url{http://www.bzip.org, libbz2} is available,
999 @command{guix-daemon} can use it to compress build logs.
1002 Unless @option{--disable-daemon} was passed to @command{configure}, the
1003 following packages are also needed:
1006 @item @url{https://gnupg.org/, GNU libgcrypt};
1007 @item @url{https://sqlite.org, SQLite 3};
1008 @item @url{https://gcc.gnu.org, GCC's g++}, with support for the
1012 @cindex state directory
1013 When configuring Guix on a system that already has a Guix installation,
1014 be sure to specify the same state directory as the existing installation
1015 using the @option{--localstatedir} option of the @command{configure}
1016 script (@pxref{Directory Variables, @code{localstatedir},, standards,
1017 GNU Coding Standards}). Usually, this @var{localstatedir} option is
1018 set to the value @file{/var}. The @command{configure} script protects
1019 against unintended misconfiguration of @var{localstatedir} so you do not
1020 inadvertently corrupt your store (@pxref{The Store}).
1022 @node Running the Test Suite
1023 @section Running the Test Suite
1026 After a successful @command{configure} and @code{make} run, it is a good
1027 idea to run the test suite. It can help catch issues with the setup or
1028 environment, or bugs in Guix itself---and really, reporting test
1029 failures is a good way to help improve the software. To run the test
1036 Test cases can run in parallel: you can use the @code{-j} option of
1037 GNU@tie{}make to speed things up. The first run may take a few minutes
1038 on a recent machine; subsequent runs will be faster because the store
1039 that is created for test purposes will already have various things in
1042 It is also possible to run a subset of the tests by defining the
1043 @code{TESTS} makefile variable as in this example:
1046 make check TESTS="tests/store.scm tests/cpio.scm"
1049 By default, tests results are displayed at a file level. In order to
1050 see the details of every individual test cases, it is possible to define
1051 the @code{SCM_LOG_DRIVER_FLAGS} makefile variable as in this example:
1054 make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
1057 The underlying SRFI 64 custom Automake test driver used for the 'check'
1058 test suite (located at @file{build-aux/test-driver.scm}) also allows
1059 selecting which test cases to run at a finer level, via its
1060 @option{--select} and @option{--exclude} options. Here's an example, to
1061 run all the test cases from the @file{tests/packages.scm} test file
1062 whose names start with ``transaction-upgrade-entry'':
1065 export SCM_LOG_DRIVER_FLAGS="--select=^transaction-upgrade-entry"
1066 make check TESTS="tests/packages.scm"
1069 Those wishing to inspect the results of failed tests directly from the
1070 command line can add the @option{--errors-only=yes} option to the
1071 @code{SCM_LOG_DRIVER_FLAGS} makefile variable and set the @code{VERBOSE}
1072 Automake makefile variable, as in:
1075 make check SCM_LOG_DRIVER_FLAGS="--brief=no --errors-only=yes" VERBOSE=1
1078 The @option{--show-duration=yes} option can be used to print the
1079 duration of the individual test cases, when used in combination with
1080 @option{--brief=no}:
1083 make check SCM_LOG_DRIVER_FLAGS="--brief=no --show-duration=yes"
1086 @xref{Parallel Test Harness,,,automake,GNU Automake} for more
1087 information about the Automake Parallel Test Harness.
1089 Upon failure, please email @email{bug-guix@@gnu.org} and attach the
1090 @file{test-suite.log} file. Please specify the Guix version being used
1091 as well as version numbers of the dependencies (@pxref{Requirements}) in
1094 Guix also comes with a whole-system test suite that tests complete
1095 Guix System instances. It can only run on systems where
1096 Guix is already installed, using:
1103 or, again, by defining @code{TESTS} to select a subset of tests to run:
1106 make check-system TESTS="basic mcron"
1109 These system tests are defined in the @code{(gnu tests @dots{})}
1110 modules. They work by running the operating systems under test with
1111 lightweight instrumentation in a virtual machine (VM). They can be
1112 computationally intensive or rather cheap, depending on whether
1113 substitutes are available for their dependencies (@pxref{Substitutes}).
1114 Some of them require a lot of storage space to hold VM images.
1116 Again in case of test failures, please send @email{bug-guix@@gnu.org}
1119 @node Setting Up the Daemon
1120 @section Setting Up the Daemon
1123 Operations such as building a package or running the garbage collector
1124 are all performed by a specialized process, the @dfn{build daemon}, on
1125 behalf of clients. Only the daemon may access the store and its
1126 associated database. Thus, any operation that manipulates the store
1127 goes through the daemon. For instance, command-line tools such as
1128 @command{guix package} and @command{guix build} communicate with the
1129 daemon (@i{via} remote procedure calls) to instruct it what to do.
1131 The following sections explain how to prepare the build daemon's
1132 environment. See also @ref{Substitutes}, for information on how to allow
1133 the daemon to download pre-built binaries.
1136 * Build Environment Setup:: Preparing the isolated build environment.
1137 * Daemon Offload Setup:: Offloading builds to remote machines.
1138 * SELinux Support:: Using an SELinux policy for the daemon.
1141 @node Build Environment Setup
1142 @subsection Build Environment Setup
1144 @cindex build environment
1145 In a standard multi-user setup, Guix and its daemon---the
1146 @command{guix-daemon} program---are installed by the system
1147 administrator; @file{/gnu/store} is owned by @code{root} and
1148 @command{guix-daemon} runs as @code{root}. Unprivileged users may use
1149 Guix tools to build packages or otherwise access the store, and the
1150 daemon will do it on their behalf, ensuring that the store is kept in a
1151 consistent state, and allowing built packages to be shared among users.
1154 When @command{guix-daemon} runs as @code{root}, you may not want package
1155 build processes themselves to run as @code{root} too, for obvious
1156 security reasons. To avoid that, a special pool of @dfn{build users}
1157 should be created for use by build processes started by the daemon.
1158 These build users need not have a shell and a home directory: they will
1159 just be used when the daemon drops @code{root} privileges in build
1160 processes. Having several such users allows the daemon to launch
1161 distinct build processes under separate UIDs, which guarantees that they
1162 do not interfere with each other---an essential feature since builds are
1163 regarded as pure functions (@pxref{Introduction}).
1165 On a GNU/Linux system, a build user pool may be created like this (using
1166 Bash syntax and the @code{shadow} commands):
1168 @c See https://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
1169 @c for why `-G' is needed.
1171 # groupadd --system guixbuild
1172 # for i in $(seq -w 1 10);
1174 useradd -g guixbuild -G guixbuild \
1175 -d /var/empty -s $(which nologin) \
1176 -c "Guix build user $i" --system \
1182 The number of build users determines how many build jobs may run in
1183 parallel, as specified by the @option{--max-jobs} option
1184 (@pxref{Invoking guix-daemon, @option{--max-jobs}}). To use
1185 @command{guix system vm} and related commands, you may need to add the
1186 build users to the @code{kvm} group so they can access @file{/dev/kvm},
1187 using @code{-G guixbuild,kvm} instead of @code{-G guixbuild}
1188 (@pxref{Invoking guix system}).
1190 The @code{guix-daemon} program may then be run as @code{root} with the
1191 following command@footnote{If your machine uses the systemd init system,
1192 copying the @file{@var{prefix}/lib/systemd/system/guix-daemon.service}
1193 file to @file{/etc/systemd/system} will ensure that
1194 @command{guix-daemon} is automatically started. Similarly, if your
1195 machine uses the Upstart init system, copy the
1196 @file{@var{prefix}/lib/upstart/system/guix-daemon.conf}
1197 file to @file{/etc/init}.}:
1200 # guix-daemon --build-users-group=guixbuild
1205 This way, the daemon starts build processes in a chroot, under one of
1206 the @code{guixbuilder} users. On GNU/Linux, by default, the chroot
1207 environment contains nothing but:
1209 @c Keep this list in sync with libstore/build.cc! -----------------------
1212 a minimal @code{/dev} directory, created mostly independently from the
1213 host @code{/dev}@footnote{``Mostly'', because while the set of files
1214 that appear in the chroot's @code{/dev} is fixed, most of these files
1215 can only be created if the host has them.};
1218 the @code{/proc} directory; it only shows the processes of the container
1219 since a separate PID name space is used;
1222 @file{/etc/passwd} with an entry for the current user and an entry for
1226 @file{/etc/group} with an entry for the user's group;
1229 @file{/etc/hosts} with an entry that maps @code{localhost} to
1233 a writable @file{/tmp} directory.
1236 The chroot does not contain a @file{/home} directory, and the @env{HOME}
1237 environment variable is set to the non-existent
1238 @file{/homeless-shelter}. This helps to highlight inappropriate uses of
1239 @env{HOME} in the build scripts of packages.
1241 You can influence the directory where the daemon stores build trees
1242 @i{via} the @env{TMPDIR} environment variable. However, the build tree
1243 within the chroot is always called @file{/tmp/guix-build-@var{name}.drv-0},
1244 where @var{name} is the derivation name---e.g., @code{coreutils-8.24}.
1245 This way, the value of @env{TMPDIR} does not leak inside build
1246 environments, which avoids discrepancies in cases where build processes
1247 capture the name of their build tree.
1251 The daemon also honors the @env{http_proxy} and @env{https_proxy}
1252 environment variables for HTTP and HTTPS downloads it performs, be it
1253 for fixed-output derivations (@pxref{Derivations}) or for substitutes
1254 (@pxref{Substitutes}).
1256 If you are installing Guix as an unprivileged user, it is still possible
1257 to run @command{guix-daemon} provided you pass @option{--disable-chroot}.
1258 However, build processes will not be isolated from one another, and not
1259 from the rest of the system. Thus, build processes may interfere with
1260 each other, and may access programs, libraries, and other files
1261 available on the system---making it much harder to view them as
1262 @emph{pure} functions.
1265 @node Daemon Offload Setup
1266 @subsection Using the Offload Facility
1270 When desired, the build daemon can @dfn{offload} derivation builds to
1271 other machines running Guix, using the @code{offload} @dfn{build
1272 hook}@footnote{This feature is available only when
1273 @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH} is
1274 present.}. When that feature is enabled, a list of user-specified build
1275 machines is read from @file{/etc/guix/machines.scm}; every time a build
1276 is requested, for instance via @code{guix build}, the daemon attempts to
1277 offload it to one of the machines that satisfy the constraints of the
1278 derivation, in particular its system types---e.g., @code{x86_64-linux}.
1279 A single machine can have multiple system types, either because its
1280 architecture natively supports it, via emulation
1281 (@pxref{transparent-emulation-qemu, Transparent Emulation with QEMU}),
1282 or both. Missing prerequisites for the build are
1283 copied over SSH to the target machine, which then proceeds with the
1284 build; upon success the output(s) of the build are copied back to the
1285 initial machine. The offload facility comes with a basic scheduler that
1286 attempts to select the best machine. The best machine is chosen among
1287 the available machines based on criteria such as:
1291 The availability of a build slot. A build machine can have as many
1292 build slots (connections) as the value of the @code{parallel-builds}
1293 field of its @code{build-machine} object.
1296 Its relative speed, as defined via the @code{speed} field of its
1297 @code{build-machine} object.
1300 Its load. The normalized machine load must be lower than a threshold
1301 value, configurable via the @code{overload-threshold} field of its
1302 @code{build-machine} object.
1305 Disk space availability. More than a 100 MiB must be available.
1308 The @file{/etc/guix/machines.scm} file typically looks like this:
1311 (list (build-machine
1312 (name "eightysix.example.org")
1313 (systems (list "x86_64-linux" "i686-linux"))
1314 (host-key "ssh-ed25519 AAAAC3Nza@dots{}")
1316 (speed 2.)) ;incredibly fast!
1319 (name "armeight.example.org")
1320 (systems (list "aarch64-linux"))
1321 (host-key "ssh-rsa AAAAB3Nza@dots{}")
1324 ;; Remember 'guix offload' is spawned by
1325 ;; 'guix-daemon' as root.
1326 (private-key "/root/.ssh/identity-for-guix")))
1330 In the example above we specify a list of two build machines, one for
1331 the @code{x86_64} and @code{i686} architectures and one for the
1332 @code{aarch64} architecture.
1334 In fact, this file is---not surprisingly!---a Scheme file that is
1335 evaluated when the @code{offload} hook is started. Its return value
1336 must be a list of @code{build-machine} objects. While this example
1337 shows a fixed list of build machines, one could imagine, say, using
1338 DNS-SD to return a list of potential build machines discovered in the
1339 local network (@pxref{Introduction, Guile-Avahi,, guile-avahi, Using
1340 Avahi in Guile Scheme Programs}). The @code{build-machine} data type is
1343 @deftp {Data Type} build-machine
1344 This data type represents build machines to which the daemon may offload
1345 builds. The important fields are:
1350 The host name of the remote machine.
1353 The system types the remote machine supports---e.g., @code{(list
1354 "x86_64-linux" "i686-linux")}.
1357 The user account to use when connecting to the remote machine over SSH.
1358 Note that the SSH key pair must @emph{not} be passphrase-protected, to
1359 allow non-interactive logins.
1362 This must be the machine's SSH @dfn{public host key} in OpenSSH format.
1363 This is used to authenticate the machine when we connect to it. It is a
1364 long string that looks like this:
1367 ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
1370 If the machine is running the OpenSSH daemon, @command{sshd}, the host
1371 key can be found in a file such as
1372 @file{/etc/ssh/ssh_host_ed25519_key.pub}.
1374 If the machine is running the SSH daemon of GNU@tie{}lsh,
1375 @command{lshd}, the host key is in @file{/etc/lsh/host-key.pub} or a
1376 similar file. It can be converted to the OpenSSH format using
1377 @command{lsh-export-key} (@pxref{Converting keys,,, lsh, LSH Manual}):
1380 $ lsh-export-key --openssh < /etc/lsh/host-key.pub
1381 ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
1386 A number of optional fields may be specified:
1390 @item @code{port} (default: @code{22})
1391 Port number of SSH server on the machine.
1393 @item @code{private-key} (default: @file{~root/.ssh/id_rsa})
1394 The SSH private key file to use when connecting to the machine, in
1395 OpenSSH format. This key must not be protected with a passphrase.
1397 Note that the default value is the private key @emph{of the root
1398 account}. Make sure it exists if you use the default.
1400 @item @code{compression} (default: @code{"zlib@@openssh.com,zlib"})
1401 @itemx @code{compression-level} (default: @code{3})
1402 The SSH-level compression methods and compression level requested.
1404 Note that offloading relies on SSH compression to reduce bandwidth usage
1405 when transferring files to and from build machines.
1407 @item @code{daemon-socket} (default: @code{"/var/guix/daemon-socket/socket"})
1408 File name of the Unix-domain socket @command{guix-daemon} is listening
1411 @item @code{overload-threshold} (default: @code{0.6})
1412 The load threshold above which a potential offload machine is
1413 disregarded by the offload scheduler. The value roughly translates to
1414 the total processor usage of the build machine, ranging from 0.0 (0%) to
1415 1.0 (100%). It can also be disabled by setting
1416 @code{overload-threshold} to @code{#f}.
1418 @item @code{parallel-builds} (default: @code{1})
1419 The number of builds that may run in parallel on the machine.
1421 @item @code{speed} (default: @code{1.0})
1422 A ``relative speed factor''. The offload scheduler will tend to prefer
1423 machines with a higher speed factor.
1425 @item @code{features} (default: @code{'()})
1426 A list of strings denoting specific features supported by the machine.
1427 An example is @code{"kvm"} for machines that have the KVM Linux modules
1428 and corresponding hardware support. Derivations can request features by
1429 name, and they will be scheduled on matching build machines.
1434 The @command{guix} command must be in the search path on the build
1435 machines. You can check whether this is the case by running:
1438 ssh build-machine guix repl --version
1441 There is one last thing to do once @file{machines.scm} is in place. As
1442 explained above, when offloading, files are transferred back and forth
1443 between the machine stores. For this to work, you first need to
1444 generate a key pair on each machine to allow the daemon to export signed
1445 archives of files from the store (@pxref{Invoking guix archive}):
1448 # guix archive --generate-key
1452 Each build machine must authorize the key of the master machine so that
1453 it accepts store items it receives from the master:
1456 # guix archive --authorize < master-public-key.txt
1460 Likewise, the master machine must authorize the key of each build machine.
1462 All the fuss with keys is here to express pairwise mutual trust
1463 relations between the master and the build machines. Concretely, when
1464 the master receives files from a build machine (and @i{vice versa}), its
1465 build daemon can make sure they are genuine, have not been tampered
1466 with, and that they are signed by an authorized key.
1468 @cindex offload test
1469 To test whether your setup is operational, run this command on the
1476 This will attempt to connect to each of the build machines specified in
1477 @file{/etc/guix/machines.scm}, make sure Guix is
1478 available on each machine, attempt to export to the machine and import
1479 from it, and report any error in the process.
1481 If you want to test a different machine file, just specify it on the
1485 # guix offload test machines-qualif.scm
1488 Last, you can test the subset of the machines whose name matches a
1489 regular expression like this:
1492 # guix offload test machines.scm '\.gnu\.org$'
1495 @cindex offload status
1496 To display the current load of all build hosts, run this command on the
1500 # guix offload status
1504 @node SELinux Support
1505 @subsection SELinux Support
1507 @cindex SELinux, daemon policy
1508 @cindex mandatory access control, SELinux
1509 @cindex security, guix-daemon
1510 Guix includes an SELinux policy file at @file{etc/guix-daemon.cil} that
1511 can be installed on a system where SELinux is enabled, in order to label
1512 Guix files and to specify the expected behavior of the daemon. Since
1513 Guix System does not provide an SELinux base policy, the daemon policy cannot
1514 be used on Guix System.
1516 @subsubsection Installing the SELinux policy
1517 @cindex SELinux, policy installation
1518 To install the policy run this command as root:
1521 semodule -i etc/guix-daemon.cil
1524 Then relabel the file system with @code{restorecon} or by a different
1525 mechanism provided by your system.
1527 Once the policy is installed, the file system has been relabeled, and
1528 the daemon has been restarted, it should be running in the
1529 @code{guix_daemon_t} context. You can confirm this with the following
1533 ps -Zax | grep guix-daemon
1536 Monitor the SELinux log files as you run a command like @code{guix build
1537 hello} to convince yourself that SELinux permits all necessary
1540 @subsubsection Limitations
1541 @cindex SELinux, limitations
1543 This policy is not perfect. Here is a list of limitations or quirks
1544 that should be considered when deploying the provided SELinux policy for
1549 @code{guix_daemon_socket_t} isn’t actually used. None of the socket
1550 operations involve contexts that have anything to do with
1551 @code{guix_daemon_socket_t}. It doesn’t hurt to have this unused label,
1552 but it would be preferable to define socket rules for only this label.
1555 @code{guix gc} cannot access arbitrary links to profiles. By design,
1556 the file label of the destination of a symlink is independent of the
1557 file label of the link itself. Although all profiles under
1558 $localstatedir are labelled, the links to these profiles inherit the
1559 label of the directory they are in. For links in the user’s home
1560 directory this will be @code{user_home_t}. But for links from the root
1561 user’s home directory, or @file{/tmp}, or the HTTP server’s working
1562 directory, etc, this won’t work. @code{guix gc} would be prevented from
1563 reading and following these links.
1566 The daemon’s feature to listen for TCP connections might no longer work.
1567 This might require extra rules, because SELinux treats network sockets
1568 differently from files.
1571 Currently all files with a name matching the regular expression
1572 @code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} are assigned the
1573 label @code{guix_daemon_exec_t}; this means that @emph{any} file with
1574 that name in any profile would be permitted to run in the
1575 @code{guix_daemon_t} domain. This is not ideal. An attacker could
1576 build a package that provides this executable and convince a user to
1577 install and run it, which lifts it into the @code{guix_daemon_t} domain.
1578 At that point SELinux could not prevent it from accessing files that are
1579 allowed for processes in that domain.
1581 You will need to relabel the store directory after all upgrades to
1582 @file{guix-daemon}, such as after running @code{guix pull}. Assuming the
1583 store is in @file{/gnu}, you can do this with @code{restorecon -vR /gnu},
1584 or by other means provided by your operating system.
1586 We could generate a much more restrictive policy at installation time,
1587 so that only the @emph{exact} file name of the currently installed
1588 @code{guix-daemon} executable would be labelled with
1589 @code{guix_daemon_exec_t}, instead of using a broad regular expression.
1590 The downside is that root would have to install or upgrade the policy at
1591 installation time whenever the Guix package that provides the
1592 effectively running @code{guix-daemon} executable is upgraded.
1595 @node Invoking guix-daemon
1596 @section Invoking @command{guix-daemon}
1597 @cindex @command{guix-daemon}
1598 The @command{guix-daemon} program implements all the functionality to
1599 access the store. This includes launching build processes, running the
1600 garbage collector, querying the availability of a build result, etc. It
1601 is normally run as @code{root} like this:
1604 # guix-daemon --build-users-group=guixbuild
1607 @cindex socket activation, for @command{guix-daemon}
1608 This daemon can also be started following the systemd ``socket
1609 activation'' protocol (@pxref{Service De- and Constructors,
1610 @code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}).
1612 For details on how to set it up, @pxref{Setting Up the Daemon}.
1615 @cindex container, build environment
1616 @cindex build environment
1617 @cindex reproducible builds
1618 By default, @command{guix-daemon} launches build processes under
1619 different UIDs, taken from the build group specified with
1620 @option{--build-users-group}. In addition, each build process is run in a
1621 chroot environment that only contains the subset of the store that the
1622 build process depends on, as specified by its derivation
1623 (@pxref{Programming Interface, derivation}), plus a set of specific
1624 system directories. By default, the latter contains @file{/dev} and
1625 @file{/dev/pts}. Furthermore, on GNU/Linux, the build environment is a
1626 @dfn{container}: in addition to having its own file system tree, it has
1627 a separate mount name space, its own PID name space, network name space,
1628 etc. This helps achieve reproducible builds (@pxref{Features}).
1630 When the daemon performs a build on behalf of the user, it creates a
1631 build directory under @file{/tmp} or under the directory specified by
1632 its @env{TMPDIR} environment variable. This directory is shared with
1633 the container for the duration of the build, though within the container,
1634 the build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
1636 The build directory is automatically deleted upon completion, unless the
1637 build failed and the client specified @option{--keep-failed}
1638 (@pxref{Common Build Options, @option{--keep-failed}}).
1640 The daemon listens for connections and spawns one sub-process for each session
1641 started by a client (one of the @command{guix} sub-commands). The
1642 @command{guix processes} command allows you to get an overview of the activity
1643 on your system by viewing each of the active sessions and clients.
1644 @xref{Invoking guix processes}, for more information.
1646 The following command-line options are supported:
1649 @item --build-users-group=@var{group}
1650 Take users from @var{group} to run build processes (@pxref{Setting Up
1651 the Daemon, build users}).
1653 @item --no-substitutes
1655 Do not use substitutes for build products. That is, always build things
1656 locally instead of allowing downloads of pre-built binaries
1657 (@pxref{Substitutes}).
1659 When the daemon runs with @option{--no-substitutes}, clients can still
1660 explicitly enable substitution @i{via} the @code{set-build-options}
1661 remote procedure call (@pxref{The Store}).
1663 @anchor{daemon-substitute-urls}
1664 @item --substitute-urls=@var{urls}
1665 Consider @var{urls} the default whitespace-separated list of substitute
1666 source URLs. When this option is omitted,
1667 @indicateurl{@value{SUBSTITUTE-URLS}} is used.
1669 This means that substitutes may be downloaded from @var{urls}, as long
1670 as they are signed by a trusted signature (@pxref{Substitutes}).
1672 @xref{Getting Substitutes from Other Servers}, for more information on
1673 how to configure the daemon to get substitutes from other servers.
1677 Do not use offload builds to other machines (@pxref{Daemon Offload
1678 Setup}). That is, always build things locally instead of offloading
1679 builds to remote machines.
1681 @item --cache-failures
1682 Cache build failures. By default, only successful builds are cached.
1684 When this option is used, @command{guix gc --list-failures} can be used
1685 to query the set of store items marked as failed; @command{guix gc
1686 --clear-failures} removes store items from the set of cached failures.
1687 @xref{Invoking guix gc}.
1689 @item --cores=@var{n}
1691 Use @var{n} CPU cores to build each derivation; @code{0} means as many
1694 The default value is @code{0}, but it may be overridden by clients, such
1695 as the @option{--cores} option of @command{guix build} (@pxref{Invoking
1698 The effect is to define the @env{NIX_BUILD_CORES} environment variable
1699 in the build process, which can then use it to exploit internal
1700 parallelism---for instance, by running @code{make -j$NIX_BUILD_CORES}.
1702 @item --max-jobs=@var{n}
1704 Allow at most @var{n} build jobs in parallel. The default value is
1705 @code{1}. Setting it to @code{0} means that no builds will be performed
1706 locally; instead, the daemon will offload builds (@pxref{Daemon Offload
1707 Setup}), or simply fail.
1709 @item --max-silent-time=@var{seconds}
1710 When the build or substitution process remains silent for more than
1711 @var{seconds}, terminate it and report a build failure.
1713 The default value is @code{0}, which disables the timeout.
1715 The value specified here can be overridden by clients (@pxref{Common
1716 Build Options, @option{--max-silent-time}}).
1718 @item --timeout=@var{seconds}
1719 Likewise, when the build or substitution process lasts for more than
1720 @var{seconds}, terminate it and report a build failure.
1722 The default value is @code{0}, which disables the timeout.
1724 The value specified here can be overridden by clients (@pxref{Common
1725 Build Options, @option{--timeout}}).
1727 @item --rounds=@var{N}
1728 Build each derivation @var{n} times in a row, and raise an error if
1729 consecutive build results are not bit-for-bit identical. Note that this
1730 setting can be overridden by clients such as @command{guix build}
1731 (@pxref{Invoking guix build}).
1733 When used in conjunction with @option{--keep-failed}, the differing
1734 output is kept in the store, under @file{/gnu/store/@dots{}-check}.
1735 This makes it easy to look for differences between the two results.
1738 Produce debugging output.
1740 This is useful to debug daemon start-up issues, but then it may be
1741 overridden by clients, for example the @option{--verbosity} option of
1742 @command{guix build} (@pxref{Invoking guix build}).
1744 @item --chroot-directory=@var{dir}
1745 Add @var{dir} to the build chroot.
1747 Doing this may change the result of build processes---for instance if
1748 they use optional dependencies found in @var{dir} when it is available,
1749 and not otherwise. For that reason, it is not recommended to do so.
1750 Instead, make sure that each derivation declares all the inputs that it
1753 @item --disable-chroot
1754 Disable chroot builds.
1756 Using this option is not recommended since, again, it would allow build
1757 processes to gain access to undeclared dependencies. It is necessary,
1758 though, when @command{guix-daemon} is running under an unprivileged user
1761 @item --log-compression=@var{type}
1762 Compress build logs according to @var{type}, one of @code{gzip},
1763 @code{bzip2}, or @code{none}.
1765 Unless @option{--lose-logs} is used, all the build logs are kept in the
1766 @var{localstatedir}. To save space, the daemon automatically compresses
1767 them with gzip by default.
1769 @item --discover[=yes|no]
1770 Whether to discover substitute servers on the local network using mDNS
1773 This feature is still experimental. However, here are a few
1778 It might be faster/less expensive than fetching from remote servers;
1780 There are no security risks, only genuine substitutes will be used
1781 (@pxref{Substitute Authentication});
1783 An attacker advertising @command{guix publish} on your LAN cannot serve
1784 you malicious binaries, but they can learn what software you’re
1787 Servers may serve substitute over HTTP, unencrypted, so anyone on the
1788 LAN can see what software you’re installing.
1791 It is also possible to enable or disable substitute server discovery at
1792 run-time by running:
1795 herd discover guix-daemon on
1796 herd discover guix-daemon off
1799 @item --disable-deduplication
1800 @cindex deduplication
1801 Disable automatic file ``deduplication'' in the store.
1803 By default, files added to the store are automatically ``deduplicated'':
1804 if a newly added file is identical to another one found in the store,
1805 the daemon makes the new file a hard link to the other file. This can
1806 noticeably reduce disk usage, at the expense of slightly increased
1807 input/output load at the end of a build process. This option disables
1810 @item --gc-keep-outputs[=yes|no]
1811 Tell whether the garbage collector (GC) must keep outputs of live
1815 @cindex garbage collector roots
1816 When set to @code{yes}, the GC will keep the outputs of any live
1817 derivation available in the store---the @file{.drv} files. The default
1818 is @code{no}, meaning that derivation outputs are kept only if they are
1819 reachable from a GC root. @xref{Invoking guix gc}, for more on GC
1822 @item --gc-keep-derivations[=yes|no]
1823 Tell whether the garbage collector (GC) must keep derivations
1824 corresponding to live outputs.
1826 When set to @code{yes}, as is the case by default, the GC keeps
1827 derivations---i.e., @file{.drv} files---as long as at least one of their
1828 outputs is live. This allows users to keep track of the origins of
1829 items in their store. Setting it to @code{no} saves a bit of disk
1832 In this way, setting @option{--gc-keep-derivations} to @code{yes} causes
1833 liveness to flow from outputs to derivations, and setting
1834 @option{--gc-keep-outputs} to @code{yes} causes liveness to flow from
1835 derivations to outputs. When both are set to @code{yes}, the effect is
1836 to keep all the build prerequisites (the sources, compiler, libraries,
1837 and other build-time tools) of live objects in the store, regardless of
1838 whether these prerequisites are reachable from a GC root. This is
1839 convenient for developers since it saves rebuilds or downloads.
1841 @item --impersonate-linux-2.6
1842 On Linux-based systems, impersonate Linux 2.6. This means that the
1843 kernel's @command{uname} system call will report 2.6 as the release number.
1845 This might be helpful to build programs that (usually wrongfully) depend
1846 on the kernel version number.
1849 Do not keep build logs. By default they are kept under
1850 @file{@var{localstatedir}/guix/log}.
1852 @item --system=@var{system}
1853 Assume @var{system} as the current system type. By default it is the
1854 architecture/kernel pair found at configure time, such as
1855 @code{x86_64-linux}.
1857 @item --listen=@var{endpoint}
1858 Listen for connections on @var{endpoint}. @var{endpoint} is interpreted
1859 as the file name of a Unix-domain socket if it starts with
1860 @code{/} (slash sign). Otherwise, @var{endpoint} is interpreted as a
1861 host name or host name and port to listen to. Here are a few examples:
1864 @item --listen=/gnu/var/daemon
1865 Listen for connections on the @file{/gnu/var/daemon} Unix-domain socket,
1866 creating it if needed.
1868 @item --listen=localhost
1869 @cindex daemon, remote access
1870 @cindex remote access to the daemon
1871 @cindex daemon, cluster setup
1872 @cindex clusters, daemon setup
1873 Listen for TCP connections on the network interface corresponding to
1874 @code{localhost}, on port 44146.
1876 @item --listen=128.0.0.42:1234
1877 Listen for TCP connections on the network interface corresponding to
1878 @code{128.0.0.42}, on port 1234.
1881 This option can be repeated multiple times, in which case
1882 @command{guix-daemon} accepts connections on all the specified
1883 endpoints. Users can tell client commands what endpoint to connect to
1884 by setting the @env{GUIX_DAEMON_SOCKET} environment variable
1885 (@pxref{The Store, @env{GUIX_DAEMON_SOCKET}}).
1888 The daemon protocol is @emph{unauthenticated and unencrypted}. Using
1889 @option{--listen=@var{host}} is suitable on local networks, such as
1890 clusters, where only trusted nodes may connect to the build daemon. In
1891 other cases where remote access to the daemon is needed, we recommend
1892 using Unix-domain sockets along with SSH.
1895 When @option{--listen} is omitted, @command{guix-daemon} listens for
1896 connections on the Unix-domain socket located at
1897 @file{@var{localstatedir}/guix/daemon-socket/socket}.
1901 @node Application Setup
1902 @section Application Setup
1904 @cindex foreign distro
1905 When using Guix on top of GNU/Linux distribution other than Guix System---a
1906 so-called @dfn{foreign distro}---a few additional steps are needed to
1907 get everything in place. Here are some of them.
1911 @anchor{locales-and-locpath}
1912 @cindex locales, when not on Guix System
1914 @vindex GUIX_LOCPATH
1915 Packages installed @i{via} Guix will not use the locale data of the
1916 host system. Instead, you must first install one of the locale packages
1917 available with Guix and then define the @env{GUIX_LOCPATH} environment
1921 $ guix install glibc-locales
1922 $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
1925 Note that the @code{glibc-locales} package contains data for all the
1926 locales supported by the GNU@tie{}libc and weighs in at around
1927 930@tie{}MiB@footnote{The size of the @code{glibc-locales} package is
1928 reduced down to about 213@tie{}MiB with store deduplication and further
1929 down to about 67@tie{}MiB when using a zstd-compressed Btrfs file
1930 system.}. If you only need a few locales, you can define your custom
1931 locales package via the @code{make-glibc-utf8-locales} procedure from
1932 the @code{(gnu packages base)} module. The following example defines a
1933 package containing the various Canadian UTF-8 locales known to the
1934 GNU@tie{}libc, that weighs around 14@tie{}MiB:
1937 (use-modules (gnu packages base))
1939 (define my-glibc-locales
1940 (make-glibc-utf8-locales
1942 #:locales (list "en_CA" "fr_CA" "ik_CA" "iu_CA" "shs_CA")
1943 #:name "glibc-canadian-utf8-locales"))
1946 The @env{GUIX_LOCPATH} variable plays a role similar to @env{LOCPATH}
1947 (@pxref{Locale Names, @env{LOCPATH},, libc, The GNU C Library Reference
1948 Manual}). There are two important differences though:
1952 @env{GUIX_LOCPATH} is honored only by the libc in Guix, and not by the libc
1953 provided by foreign distros. Thus, using @env{GUIX_LOCPATH} allows you
1954 to make sure the programs of the foreign distro will not end up loading
1955 incompatible locale data.
1958 libc suffixes each entry of @env{GUIX_LOCPATH} with @code{/X.Y}, where
1959 @code{X.Y} is the libc version---e.g., @code{2.22}. This means that,
1960 should your Guix profile contain a mixture of programs linked against
1961 different libc version, each libc version will only try to load locale
1962 data in the right format.
1965 This is important because the locale data format used by different libc
1966 versions may be incompatible.
1968 @subsection Name Service Switch
1970 @cindex name service switch, glibc
1971 @cindex NSS (name service switch), glibc
1972 @cindex nscd (name service caching daemon)
1973 @cindex name service caching daemon (nscd)
1974 When using Guix on a foreign distro, we @emph{strongly recommend} that
1975 the system run the GNU C library's @dfn{name service cache daemon},
1976 @command{nscd}, which should be listening on the
1977 @file{/var/run/nscd/socket} socket. Failing to do that, applications
1978 installed with Guix may fail to look up host names or user accounts, or
1979 may even crash. The next paragraphs explain why.
1981 @cindex @file{nsswitch.conf}
1982 The GNU C library implements a @dfn{name service switch} (NSS), which is
1983 an extensible mechanism for ``name lookups'' in general: host name
1984 resolution, user accounts, and more (@pxref{Name Service Switch,,, libc,
1985 The GNU C Library Reference Manual}).
1987 @cindex Network information service (NIS)
1988 @cindex NIS (Network information service)
1989 Being extensible, the NSS supports @dfn{plugins}, which provide new name
1990 lookup implementations: for example, the @code{nss-mdns} plugin allow
1991 resolution of @code{.local} host names, the @code{nis} plugin allows
1992 user account lookup using the Network information service (NIS), and so
1993 on. These extra ``lookup services'' are configured system-wide in
1994 @file{/etc/nsswitch.conf}, and all the programs running on the system
1995 honor those settings (@pxref{NSS Configuration File,,, libc, The GNU C
1998 When they perform a name lookup---for instance by calling the
1999 @code{getaddrinfo} function in C---applications first try to connect to
2000 the nscd; on success, nscd performs name lookups on their behalf. If
2001 the nscd is not running, then they perform the name lookup by
2002 themselves, by loading the name lookup services into their own address
2003 space and running it. These name lookup services---the
2004 @file{libnss_*.so} files---are @code{dlopen}'d, but they may come from
2005 the host system's C library, rather than from the C library the
2006 application is linked against (the C library coming from Guix).
2008 And this is where the problem is: if your application is linked against
2009 Guix's C library (say, glibc 2.24) and tries to load NSS plugins from
2010 another C library (say, @code{libnss_mdns.so} for glibc 2.22), it will
2011 likely crash or have its name lookups fail unexpectedly.
2013 Running @command{nscd} on the system, among other advantages, eliminates
2014 this binary incompatibility problem because those @code{libnss_*.so}
2015 files are loaded in the @command{nscd} process, not in applications
2018 @subsection X11 Fonts
2021 The majority of graphical applications use Fontconfig to locate and load
2022 fonts and perform X11-client-side rendering. The @code{fontconfig}
2023 package in Guix looks for fonts in @file{$HOME/.guix-profile} by
2024 default. Thus, to allow graphical applications installed with Guix to
2025 display fonts, you have to install fonts with Guix as well. Essential
2026 font packages include @code{font-ghostscript}, @code{font-dejavu}, and
2027 @code{font-gnu-freefont}.
2029 @cindex @code{fc-cache}
2031 Once you have installed or removed fonts, or when you notice an
2032 application that does not find fonts, you may need to install Fontconfig
2033 and to force an update of its font cache by running:
2036 guix install fontconfig
2040 To display text written in Chinese languages, Japanese, or Korean in
2041 graphical applications, consider installing
2042 @code{font-adobe-source-han-sans} or @code{font-wqy-zenhei}. The former
2043 has multiple outputs, one per language family (@pxref{Packages with
2044 Multiple Outputs}). For instance, the following command installs fonts
2045 for Chinese languages:
2048 guix install font-adobe-source-han-sans:cn
2051 @cindex @code{xterm}
2052 Older programs such as @command{xterm} do not use Fontconfig and instead
2053 rely on server-side font rendering. Such programs require to specify a
2054 full name of a font using XLFD (X Logical Font Description), like this:
2057 -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
2060 To be able to use such full names for the TrueType fonts installed in
2061 your Guix profile, you need to extend the font path of the X server:
2063 @c Note: 'xset' does not accept symlinks so the trick below arranges to
2064 @c get at the real directory. See <https://bugs.gnu.org/30655>.
2066 xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))
2069 @cindex @code{xlsfonts}
2070 After that, you can run @code{xlsfonts} (from @code{xlsfonts} package)
2071 to make sure your TrueType fonts are listed there.
2074 @subsection X.509 Certificates
2076 @cindex @code{nss-certs}
2077 The @code{nss-certs} package provides X.509 certificates, which allow
2078 programs to authenticate Web servers accessed over HTTPS.
2080 When using Guix on a foreign distro, you can install this package and
2081 define the relevant environment variables so that packages know where to
2082 look for certificates. @xref{X.509 Certificates}, for detailed
2085 @subsection Emacs Packages
2087 @cindex @code{emacs}
2088 When you install Emacs packages with Guix, the Elisp files are placed
2089 under the @file{share/emacs/site-lisp/} directory of the profile in
2090 which they are installed. The Elisp libraries are made available to
2091 Emacs through the @env{EMACSLOADPATH} environment variable, which is
2092 set when installing Emacs itself.
2094 Additionally, autoload definitions are automatically evaluated at the
2095 initialization of Emacs, by the Guix-specific
2096 @code{guix-emacs-autoload-packages} procedure. If, for some reason, you
2097 want to avoid auto-loading the Emacs packages installed with Guix, you
2098 can do so by running Emacs with the @option{--no-site-file} option
2099 (@pxref{Init File,,, emacs, The GNU Emacs Manual}).
2102 Emacs can now compile packages natively. Under the default
2103 configuration, this means that Emacs packages will now be
2104 just-in-time (JIT) compiled as you use them, and the results
2105 stored in a subdirectory of your @code{user-emacs-directory}.
2107 Furthermore, the build system for Emacs packages transparently
2108 supports native compilation, but note, that
2109 @code{emacs-minimal}---the default Emacs for building
2110 packages---has been configured without native compilation.
2111 To natively compile your emacs packages ahead of time, use a
2112 transformation like @option{--with-input=emacs-minimal=emacs}.
2115 @node Upgrading Guix
2116 @section Upgrading Guix
2118 @cindex Upgrading Guix, on a foreign distro
2120 To upgrade Guix, run:
2126 @xref{Invoking guix pull}, for more information.
2128 @cindex upgrading Guix for the root user, on a foreign distro
2129 @cindex upgrading the Guix daemon, on a foreign distro
2130 @cindex @command{guix pull} for the root user, on a foreign distro
2132 On a foreign distro, you can upgrade the build daemon by running:
2139 followed by (assuming your distro uses the systemd service management
2143 systemctl restart guix-daemon.service
2146 On Guix System, upgrading the daemon is achieved by reconfiguring the
2147 system (@pxref{Invoking guix system, @code{guix system reconfigure}}).
2151 @c *********************************************************************
2152 @node System Installation
2153 @chapter System Installation
2155 @cindex installing Guix System
2156 @cindex Guix System, installation
2157 This section explains how to install Guix System
2158 on a machine. Guix, as a package manager, can
2159 also be installed on top of a running GNU/Linux system,
2160 @pxref{Installation}.
2164 @c This paragraph is for people reading this from tty2 of the
2165 @c installation image.
2166 You are reading this documentation with an Info reader. For details on
2167 how to use it, hit the @key{RET} key (``return'' or ``enter'') on the
2168 link that follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU
2169 Info}. Hit @kbd{l} afterwards to come back here.
2171 Alternatively, run @command{info info} in another tty to keep the manual
2177 * Limitations:: What you can expect.
2178 * Hardware Considerations:: Supported hardware.
2179 * USB Stick and DVD Installation:: Preparing the installation medium.
2180 * Preparing for Installation:: Networking, partitioning, etc.
2181 * Guided Graphical Installation:: Easy graphical installation.
2182 * Manual Installation:: Manual installation for wizards.
2183 * After System Installation:: When installation succeeded.
2184 * Installing Guix in a VM:: Guix System playground.
2185 * Building the Installation Image:: How this comes to be.
2189 @section Limitations
2191 We consider Guix System to be ready for a wide range of ``desktop'' and server
2192 use cases. The reliability guarantees it provides---transactional upgrades
2193 and rollbacks, reproducibility---make it a solid foundation.
2195 Nevertheless, before you proceed with the installation, be aware of the
2196 following noteworthy limitations applicable to version @value{VERSION}:
2200 More and more system services are provided (@pxref{Services}), but some
2204 GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop Services}),
2205 as well as a number of X11 window managers. However, KDE is currently
2209 More than a disclaimer, this is an invitation to report issues (and success
2210 stories!), and to join us in improving it. @xref{Contributing}, for more
2214 @node Hardware Considerations
2215 @section Hardware Considerations
2217 @cindex hardware support on Guix System
2218 GNU@tie{}Guix focuses on respecting the user's computing freedom. It
2219 builds around the kernel Linux-libre, which means that only hardware for
2220 which free software drivers and firmware exist is supported. Nowadays,
2221 a wide range of off-the-shelf hardware is supported on
2222 GNU/Linux-libre---from keyboards to graphics cards to scanners and
2223 Ethernet controllers. Unfortunately, there are still areas where
2224 hardware vendors deny users control over their own computing, and such
2225 hardware is not supported on Guix System.
2227 @cindex WiFi, hardware support
2228 One of the main areas where free drivers or firmware are lacking is WiFi
2229 devices. WiFi devices known to work include those using Atheros chips
2230 (AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
2231 driver, and those using Broadcom/AirForce chips (BCM43xx with
2232 Wireless-Core Revision 5), which corresponds to the @code{b43-open}
2233 Linux-libre driver. Free firmware exists for both and is available
2234 out-of-the-box on Guix System, as part of @code{%base-firmware}
2235 (@pxref{operating-system Reference, @code{firmware}}).
2237 @cindex RYF, Respects Your Freedom
2238 The @uref{https://www.fsf.org/, Free Software Foundation} runs
2239 @uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
2240 certification program for hardware products that respect your freedom
2241 and your privacy and ensure that you have control over your device. We
2242 encourage you to check the list of RYF-certified devices.
2244 Another useful resource is the @uref{https://www.h-node.org/, H-Node}
2245 web site. It contains a catalog of hardware devices with information
2246 about their support in GNU/Linux.
2249 @node USB Stick and DVD Installation
2250 @section USB Stick and DVD Installation
2252 An ISO-9660 installation image that can be written to a USB stick or
2253 burnt to a DVD can be downloaded from
2254 @indicateurl{@value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso},
2255 where you can replace @code{x86_64-linux} with one of:
2259 for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
2262 for a 32-bit GNU/Linux system on Intel-compatible CPUs.
2265 @c start duplication of authentication part from ``Binary Installation''
2266 Make sure to download the associated @file{.sig} file and to verify the
2267 authenticity of the image against it, along these lines:
2270 $ wget @value{BASE-URL}/guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
2271 $ gpg --verify guix-system-install-@value{VERSION}.x86_64-linux.iso.sig
2274 If that command fails because you do not have the required public key,
2275 then run this command to import it:
2278 $ wget @value{OPENPGP-SIGNING-KEY-URL} \
2279 -qO - | gpg --import -
2283 and rerun the @code{gpg --verify} command.
2285 Take note that a warning like ``This key is not certified with a trusted
2286 signature!'' is normal.
2290 This image contains the tools necessary for an installation.
2291 It is meant to be copied @emph{as is} to a large-enough USB stick or DVD.
2293 @unnumberedsubsec Copying to a USB Stick
2295 Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
2296 its device name. Assuming that the USB stick is known as @file{/dev/sdX},
2297 copy the image with:
2300 dd if=guix-system-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX status=progress
2304 Access to @file{/dev/sdX} usually requires root privileges.
2306 @unnumberedsubsec Burning on a DVD
2308 Insert a blank DVD into your machine, and determine
2309 its device name. Assuming that the DVD drive is known as @file{/dev/srX},
2310 copy the image with:
2313 growisofs -dvd-compat -Z /dev/srX=guix-system-install-@value{VERSION}.x86_64-linux.iso
2316 Access to @file{/dev/srX} usually requires root privileges.
2318 @unnumberedsubsec Booting
2320 Once this is done, you should be able to reboot the system and boot from
2321 the USB stick or DVD@. The latter usually requires you to get in the
2322 BIOS or UEFI boot menu, where you can choose to boot from the USB stick.
2323 In order to boot from Libreboot, switch to the command mode by pressing
2324 the @kbd{c} key and type @command{search_grub usb}.
2326 @xref{Installing Guix in a VM}, if, instead, you would like to install
2327 Guix System in a virtual machine (VM).
2330 @node Preparing for Installation
2331 @section Preparing for Installation
2333 Once you have booted, you can use the guided graphical installer, which makes
2334 it easy to get started (@pxref{Guided Graphical Installation}). Alternatively,
2335 if you are already familiar with GNU/Linux and if you want more control than
2336 what the graphical installer provides, you can choose the ``manual''
2337 installation process (@pxref{Manual Installation}).
2339 The graphical installer is available on TTY1. You can obtain root shells on
2340 TTYs 3 to 6 by hitting @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, etc. TTY2 shows
2341 this documentation and you can reach it with @kbd{ctrl-alt-f2}. Documentation
2342 is browsable using the Info reader commands (@pxref{Top,,, info-stnd,
2343 Stand-alone GNU Info}). The installation system runs the GPM mouse daemon,
2344 which allows you to select text with the left mouse button and to paste it
2345 with the middle button.
2348 Installation requires access to the Internet so that any missing
2349 dependencies of your system configuration can be downloaded. See the
2350 ``Networking'' section below.
2353 @node Guided Graphical Installation
2354 @section Guided Graphical Installation
2356 The graphical installer is a text-based user interface. It will guide you,
2357 with dialog boxes, through the steps needed to install GNU@tie{}Guix System.
2359 The first dialog boxes allow you to set up the system as you use it during the
2360 installation: you can choose the language, keyboard layout, and set up
2361 networking, which will be used during the installation. The image below shows
2362 the networking dialog.
2364 @image{images/installer-network,5in,, networking setup with the graphical installer}
2366 Later steps allow you to partition your hard disk, as shown in the image
2367 below, to choose whether or not to use encrypted file systems, to enter the
2368 host name and root password, and to create an additional account, among other
2371 @image{images/installer-partitions,5in,, partitioning with the graphical installer}
2373 Note that, at any time, the installer allows you to exit the current
2374 installation step and resume at a previous step, as show in the image below.
2376 @image{images/installer-resume,5in,, resuming the installation process}
2378 Once you're done, the installer produces an operating system configuration and
2379 displays it (@pxref{Using the Configuration System}). At that point you can
2380 hit ``OK'' and installation will proceed. On success, you can reboot into the
2381 new system and enjoy. @xref{After System Installation}, for what's next!
2384 @node Manual Installation
2385 @section Manual Installation
2387 This section describes how you would ``manually'' install GNU@tie{}Guix System
2388 on your machine. This option requires familiarity with GNU/Linux, with the
2389 shell, and with common administration tools. If you think this is not for
2390 you, consider using the guided graphical installer (@pxref{Guided Graphical
2393 The installation system provides root shells on TTYs 3 to 6; press
2394 @kbd{ctrl-alt-f3}, @kbd{ctrl-alt-f4}, and so on to reach them. It includes
2395 many common tools needed to install the system, but is also a full-blown
2396 Guix System. This means that you can install additional packages, should you
2397 need it, using @command{guix package} (@pxref{Invoking guix package}).
2400 * Keyboard Layout and Networking and Partitioning:: Initial setup.
2401 * Proceeding with the Installation:: Installing.
2404 @node Keyboard Layout and Networking and Partitioning
2405 @subsection Keyboard Layout, Networking, and Partitioning
2407 Before you can install the system, you may want to adjust the keyboard layout,
2408 set up networking, and partition your target hard disk. This section will
2409 guide you through this.
2411 @subsubsection Keyboard Layout
2413 @cindex keyboard layout
2414 The installation image uses the US qwerty keyboard layout. If you want
2415 to change it, you can use the @command{loadkeys} command. For example,
2416 the following command selects the Dvorak keyboard layout:
2422 See the files under @file{/run/current-system/profile/share/keymaps} for
2423 a list of available keyboard layouts. Run @command{man loadkeys} for
2426 @anchor{manual-installation-networking}
2427 @subsubsection Networking
2429 Run the following command to see what your network interfaces are called:
2436 @dots{} or, using the GNU/Linux-specific @command{ip} command:
2442 @c https://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
2443 Wired interfaces have a name starting with @samp{e}; for example, the
2444 interface corresponding to the first on-board Ethernet controller is
2445 called @samp{eno1}. Wireless interfaces have a name starting with
2446 @samp{w}, like @samp{w1p2s0}.
2449 @item Wired connection
2450 To configure a wired network run the following command, substituting
2451 @var{interface} with the name of the wired interface you want to use.
2454 ifconfig @var{interface} up
2458 @dots{} or, using the GNU/Linux-specific @command{ip} command:
2461 ip link set @var{interface} up
2464 @item Wireless connection
2467 To configure wireless networking, you can create a configuration file
2468 for the @command{wpa_supplicant} configuration tool (its location is not
2469 important) using one of the available text editors such as
2473 nano wpa_supplicant.conf
2476 As an example, the following stanza can go to this file and will work
2477 for many wireless networks, provided you give the actual SSID and
2478 passphrase for the network you are connecting to:
2482 ssid="@var{my-ssid}"
2484 psk="the network's secret passphrase"
2488 Start the wireless service and run it in the background with the
2489 following command (substitute @var{interface} with the name of the
2490 network interface you want to use):
2493 wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
2496 Run @command{man wpa_supplicant} for more information.
2500 At this point, you need to acquire an IP address. On a network where IP
2501 addresses are automatically assigned @i{via} DHCP, you can run:
2504 dhclient -v @var{interface}
2507 Try to ping a server to see if networking is up and running:
2513 Setting up network access is almost always a requirement because the
2514 image does not contain all the software and tools that may be needed.
2516 @cindex proxy, during system installation
2517 If you need HTTP and HTTPS access to go through a proxy, run the
2521 herd set-http-proxy guix-daemon @var{URL}
2525 where @var{URL} is the proxy URL, for example
2526 @code{http://example.org:8118}.
2528 @cindex installing over SSH
2529 If you want to, you can continue the installation remotely by starting
2533 herd start ssh-daemon
2536 Make sure to either set a password with @command{passwd}, or configure
2537 OpenSSH public key authentication before logging in.
2539 @subsubsection Disk Partitioning
2541 Unless this has already been done, the next step is to partition, and
2542 then format the target partition(s).
2544 The installation image includes several partitioning tools, including
2545 Parted (@pxref{Overview,,, parted, GNU Parted User Manual}),
2546 @command{fdisk}, and @command{cfdisk}. Run it and set up your disk with
2547 the partition layout you want:
2553 If your disk uses the GUID Partition Table (GPT) format and you plan to
2554 install BIOS-based GRUB (which is the default), make sure a BIOS Boot
2555 Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB
2558 @cindex EFI, installation
2559 @cindex UEFI, installation
2560 @cindex ESP, EFI system partition
2561 If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System Partition}
2562 (ESP) is required. This partition can be mounted at @file{/boot/efi} for
2563 instance and must have the @code{esp} flag set. E.g., for @command{parted}:
2566 parted /dev/sda set 1 esp on
2570 @vindex grub-bootloader
2571 @vindex grub-efi-bootloader
2572 Unsure whether to use EFI- or BIOS-based GRUB? If the directory
2573 @file{/sys/firmware/efi} exists in the installation image, then you should
2574 probably perform an EFI installation, using @code{grub-efi-bootloader}.
2575 Otherwise you should use the BIOS-based GRUB, known as
2576 @code{grub-bootloader}. @xref{Bootloader Configuration}, for more info on
2580 Once you are done partitioning the target hard disk drive, you have to
2581 create a file system on the relevant partition(s)@footnote{Currently
2582 Guix System only supports ext4, btrfs, JFS, F2FS, and XFS file systems. In
2583 particular, code that reads file system UUIDs and labels only works for these
2584 file system types.}. For the ESP, if you have one and assuming it is
2585 @file{/dev/sda1}, run:
2588 mkfs.fat -F32 /dev/sda1
2591 For the root file system, ext4 is the most widely used format. Other
2592 file systems, such as Btrfs, support compression, which is reported to
2593 nicely complement file deduplication that the daemon performs
2594 independently of the file system (@pxref{Invoking guix-daemon,
2597 Preferably, assign file systems a label so that you can easily and
2598 reliably refer to them in @code{file-system} declarations (@pxref{File
2599 Systems}). This is typically done using the @code{-L} option of
2600 @command{mkfs.ext4} and related commands. So, assuming the target root
2601 partition lives at @file{/dev/sda2}, a file system with the label
2602 @code{my-root} can be created with:
2605 mkfs.ext4 -L my-root /dev/sda2
2608 @cindex encrypted disk
2609 If you are instead planning to encrypt the root partition, you can use
2610 the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
2611 @uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
2612 @code{man cryptsetup}} for more information).
2615 Note that GRUB can unlock LUKS2 devices since version 2.06, but only
2616 supports the PBKDF2 key derivation function, which is not the default
2617 for @command{cryptsetup luksFormat}. You can check which key derivation
2618 function is being used by a device by running @command{cryptsetup
2619 luksDump @var{device}}, and looking for the PBKDF field of your
2623 Assuming you want to store the root partition on @file{/dev/sda2}, the
2624 command sequence to format it as a LUKS2 partition would be along these
2628 cryptsetup luksFormat --type luks2 --pbkdf pbkdf2 /dev/sda2
2629 cryptsetup open /dev/sda2 my-partition
2630 mkfs.ext4 -L my-root /dev/mapper/my-partition
2633 Once that is done, mount the target file system under @file{/mnt}
2634 with a command like (again, assuming @code{my-root} is the label of the
2638 mount LABEL=my-root /mnt
2641 Also mount any other file systems you would like to use on the target
2642 system relative to this path. If you have opted for @file{/boot/efi} as an
2643 EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is
2644 found by @code{guix system init} afterwards.
2646 Finally, if you plan to use one or more swap partitions (@pxref{Swap
2647 Space}), make sure to initialize them with @command{mkswap}. Assuming
2648 you have one swap partition on @file{/dev/sda3}, you would run:
2655 Alternatively, you may use a swap file. For example, assuming that in
2656 the new system you want to use the file @file{/swapfile} as a swap file,
2657 you would run@footnote{This example will work for many types of file
2658 systems (e.g., ext4). However, for copy-on-write file systems (e.g.,
2659 btrfs), the required steps may be different. For details, see the
2660 manual pages for @command{mkswap} and @command{swapon}.}:
2663 # This is 10 GiB of swap space. Adjust "count" to change the size.
2664 dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
2665 # For security, make the file readable and writable only by root.
2666 chmod 600 /mnt/swapfile
2667 mkswap /mnt/swapfile
2668 swapon /mnt/swapfile
2671 Note that if you have encrypted the root partition and created a swap
2672 file in its file system as described above, then the encryption also
2673 protects the swap file, just like any other file in that file system.
2675 @node Proceeding with the Installation
2676 @subsection Proceeding with the Installation
2678 With the target partitions ready and the target root mounted on
2679 @file{/mnt}, we're ready to go. First, run:
2682 herd start cow-store /mnt
2685 This makes @file{/gnu/store} copy-on-write, such that packages added to it
2686 during the installation phase are written to the target disk on @file{/mnt}
2687 rather than kept in memory. This is necessary because the first phase of
2688 the @command{guix system init} command (see below) entails downloads or
2689 builds to @file{/gnu/store} which, initially, is an in-memory file system.
2691 Next, you have to edit a file and
2692 provide the declaration of the operating system to be installed. To
2693 that end, the installation system comes with three text editors. We
2694 recommend GNU nano (@pxref{Top,,, nano, GNU nano Manual}), which
2695 supports syntax highlighting and parentheses matching; other editors
2696 include mg (an Emacs clone), and
2697 nvi (a clone of the original BSD @command{vi} editor).
2698 We strongly recommend storing that file on the target root file system, say,
2699 as @file{/mnt/etc/config.scm}. Failing to do that, you will have lost your
2700 configuration file once you have rebooted into the newly-installed system.
2702 @xref{Using the Configuration System}, for an overview of the
2703 configuration file. The example configurations discussed in that
2704 section are available under @file{/etc/configuration} in the
2705 installation image. Thus, to get started with a system configuration
2706 providing a graphical display server (a ``desktop'' system), you can run
2707 something along these lines:
2711 # cp /etc/configuration/desktop.scm /mnt/etc/config.scm
2712 # nano /mnt/etc/config.scm
2715 You should pay attention to what your configuration file contains, and
2720 Make sure the @code{bootloader-configuration} form refers to the targets
2721 you want to install GRUB on. It should mention @code{grub-bootloader}
2722 if you are installing GRUB in the legacy way, or
2723 @code{grub-efi-bootloader} for newer UEFI systems. For legacy systems,
2724 the @code{targets} field contain the names of the devices, like
2725 @code{(list "/dev/sda")}; for UEFI systems it names the paths to mounted
2726 EFI partitions, like @code{(list "/boot/efi")}; do make sure the paths
2727 are currently mounted and a @code{file-system} entry is specified in
2731 Be sure that your file system labels match the value of their respective
2732 @code{device} fields in your @code{file-system} configuration, assuming
2733 your @code{file-system} configuration uses the @code{file-system-label}
2734 procedure in its @code{device} field.
2737 If there are encrypted or RAID partitions, make sure to add a
2738 @code{mapped-devices} field to describe them (@pxref{Mapped Devices}).
2741 Once you are done preparing the configuration file, the new system must
2742 be initialized (remember that the target root file system is mounted
2746 guix system init /mnt/etc/config.scm /mnt
2750 This copies all the necessary files and installs GRUB on
2751 @file{/dev/sdX}, unless you pass the @option{--no-bootloader} option. For
2752 more information, @pxref{Invoking guix system}. This command may trigger
2753 downloads or builds of missing packages, which can take some time.
2755 Once that command has completed---and hopefully succeeded!---you can run
2756 @command{reboot} and boot into the new system. The @code{root} password
2757 in the new system is initially empty; other users' passwords need to be
2758 initialized by running the @command{passwd} command as @code{root},
2759 unless your configuration specifies otherwise
2760 (@pxref{user-account-password, user account passwords}).
2761 @xref{After System Installation}, for what's next!
2764 @node After System Installation
2765 @section After System Installation
2767 Success, you've now booted into Guix System! From then on, you can update the
2768 system whenever you want by running, say:
2772 sudo guix system reconfigure /etc/config.scm
2776 This builds a new system generation with the latest packages and services
2777 (@pxref{Invoking guix system}). We recommend doing that regularly so that
2778 your system includes the latest security updates (@pxref{Security Updates}).
2780 @c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>.
2782 @cindex sudo vs. @command{guix pull}
2783 Note that @command{sudo guix} runs your user's @command{guix} command and
2784 @emph{not} root's, because @command{sudo} leaves @env{PATH} unchanged. To
2785 explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}.
2787 The difference matters here, because @command{guix pull} updates
2788 the @command{guix} command and package definitions only for the user it is run
2789 as. This means that if you choose to use @command{guix system reconfigure} in
2790 root's login shell, you'll need to @command{guix pull} separately.
2793 Now, @pxref{Getting Started}, and
2794 join us on @code{#guix} on the Libera Chat IRC network or on
2795 @email{guix-devel@@gnu.org} to share your experience!
2798 @node Installing Guix in a VM
2799 @section Installing Guix in a Virtual Machine
2801 @cindex virtual machine, Guix System installation
2802 @cindex virtual private server (VPS)
2803 @cindex VPS (virtual private server)
2804 If you'd like to install Guix System in a virtual machine (VM) or on a
2805 virtual private server (VPS) rather than on your beloved machine, this
2808 To boot a @uref{https://qemu.org/,QEMU} VM for installing Guix System in a
2809 disk image, follow these steps:
2813 First, retrieve and decompress the Guix system installation image as
2814 described previously (@pxref{USB Stick and DVD Installation}).
2817 Create a disk image that will hold the installed system. To make a
2818 qcow2-formatted disk image, use the @command{qemu-img} command:
2821 qemu-img create -f qcow2 guix-system.img 50G
2824 The resulting file will be much smaller than 50 GB (typically less than
2825 1 MB), but it will grow as the virtualized storage device is filled up.
2828 Boot the USB installation image in an VM:
2831 qemu-system-x86_64 -m 1024 -smp 1 -enable-kvm \
2832 -nic user,model=virtio-net-pci -boot menu=on,order=d \
2833 -drive file=guix-system.img \
2834 -drive media=cdrom,file=guix-system-install-@value{VERSION}.@var{system}.iso
2837 @code{-enable-kvm} is optional, but significantly improves performance,
2838 @pxref{Running Guix in a VM}.
2841 You're now root in the VM, proceed with the installation process.
2842 @xref{Preparing for Installation}, and follow the instructions.
2845 Once installation is complete, you can boot the system that's on your
2846 @file{guix-system.img} image. @xref{Running Guix in a VM}, for how to do
2849 @node Building the Installation Image
2850 @section Building the Installation Image
2852 @cindex installation image
2853 The installation image described above was built using the @command{guix
2854 system} command, specifically:
2857 guix system image -t iso9660 gnu/system/install.scm
2860 Have a look at @file{gnu/system/install.scm} in the source tree,
2861 and see also @ref{Invoking guix system} for more information
2862 about the installation image.
2864 @section Building the Installation Image for ARM Boards
2866 Many ARM boards require a specific variant of the
2867 @uref{https://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
2869 If you build a disk image and the bootloader is not available otherwise
2870 (on another boot drive etc), it's advisable to build an image that
2871 includes the bootloader, specifically:
2874 guix system image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
2877 @code{A20-OLinuXino-Lime2} is the name of the board. If you specify an invalid
2878 board, a list of possible boards will be printed.
2880 @c *********************************************************************
2881 @cindex troubleshooting, guix system
2882 @cindex guix system troubleshooting
2883 @node System Troubleshooting Tips
2884 @chapter System Troubleshooting Tips
2886 Guix System allows rebooting into a previous generation should the last
2887 one be malfunctioning, which makes it quite robust against being broken
2888 irreversibly. This feature depends on GRUB being correctly functioning
2889 though, which means that if for whatever reasons your GRUB installation
2890 becomes corrupted during a system reconfiguration, you may not be able
2891 to easily boot into a previous generation. A technique that can be used
2892 in this case is to @i{chroot} into your broken system and reconfigure it
2893 from there. Such technique is explained below.
2895 @cindex chroot, guix system
2896 @cindex chrooting, guix system
2897 @cindex repairing GRUB, via chroot
2898 @node Chrooting into an existing system
2899 @section Chrooting into an existing system
2901 This section details how to @i{chroot} to an already installed Guix
2902 System with the aim of reconfiguring it, for example to fix a broken
2903 GRUB installation. The process is similar to how it would be done on
2904 other GNU/Linux systems, but there are some Guix System particularities
2905 such as the daemon and profiles that make it worthy of explaining here.
2909 Obtain a bootable image of Guix System. It is recommended the latest
2910 development snapshot so the kernel and the tools used are at least as as
2911 new as those of your installed system; it can be retrieved from the
2912 @url{https://ci.guix.gnu.org/search/latest/ISO-9660?query=spec:images+status:success+system:x86_64-linux+image.iso,
2913 https://ci.guix.gnu.org} URL. Follow the @pxref{USB Stick and DVD
2914 Installation} section for copying it to a bootable media.
2917 Boot the image, and proceed with the graphical text-based installer
2918 until your network is configured. Alternatively, you could configure
2919 the network manually by following the
2920 @ref{manual-installation-networking} section. If you get the error
2921 @samp{RTNETLINK answers: Operation not possible due to RF-kill}, try
2922 @samp{rfkill list} followed by @samp{rfkill unblock 0}, where @samp{0}
2923 is your device identifier (ID).
2926 Switch to a virtual console (tty) if you haven't already by pressing
2927 simultaneously the @kbd{Control + Alt + F4} keys. Mount your file
2928 system at @file{/mnt}. Assuming your root partition is
2929 @file{/dev/sda2}, you would do:
2932 mount /dev/sda2 /mnt
2936 Mount special block devices and Linux-specific directories:
2939 mount --bind /proc /mnt/proc
2940 mount --bind /sys /mnt/sys
2941 mount --bind /dev /mnt/dev
2944 If your system is EFI-based, you must also mount the ESP partition.
2945 Assuming it is @file{/dev/sda1}, you can do so with:
2948 mount /dev/sda1 /mnt/boot/efi
2952 Enter your system via chroot:
2959 Source the system profile as well as your @var{user} profile to setup
2960 the environment, where @var{user} is the user name used for the Guix
2961 System you are attempting to repair:
2964 source /var/guix/profiles/system/profile/etc/profile
2965 source /home/@var{user}/.guix-profile/etc/profile
2968 To ensure you are working with the Guix revision you normally would as
2969 your normal user, also source your current Guix profile:
2972 source /home/@var{user}/.config/guix/current/etc/profile
2976 Start a minimal @command{guix-daemon} in the background:
2979 guix-daemon --build-users-group=guixbuild --disable-chroot &
2983 Edit your Guix System configuration if needed, then reconfigure with:
2986 guix system reconfigure your-config.scm
2990 Finally, you should be good to reboot the system to test your fix.
2994 @c *********************************************************************
2995 @node Getting Started
2996 @chapter Getting Started
2998 Presumably, you've reached this section because either you have
2999 installed Guix on top of another distribution (@pxref{Installation}), or
3000 you've installed the standalone Guix System (@pxref{System
3001 Installation}). It's time for you to get started using Guix and this
3002 section aims to help you do that and give you a feel of what it's like.
3004 Guix is about installing software, so probably the first thing you'll
3005 want to do is to actually look for software. Let's say you're looking
3006 for a text editor, you can run:
3009 guix search text editor
3012 This command shows you a number of matching @dfn{packages}, each time
3013 showing the package's name, version, a description, and additional info.
3014 Once you've found out the one you want to use, let's say Emacs (ah ha!),
3015 you can go ahead and install it (run this command as a regular user,
3016 @emph{no need for root privileges}!):
3023 You've installed your first package, congrats! The package is now
3024 visible in your default @dfn{profile}, @file{$HOME/.guix-profile}---a
3025 profile is a directory containing installed packages.
3026 In the process, you've
3027 probably noticed that Guix downloaded pre-built binaries; or, if you
3028 explicitly chose to @emph{not} use pre-built binaries, then probably
3029 Guix is still building software (@pxref{Substitutes}, for more info).
3031 Unless you're using Guix System, the @command{guix install} command must
3032 have printed this hint:
3035 hint: Consider setting the necessary environment variables by running:
3037 GUIX_PROFILE="$HOME/.guix-profile"
3038 . "$GUIX_PROFILE/etc/profile"
3040 Alternately, see `guix package --search-paths -p "$HOME/.guix-profile"'.
3043 Indeed, you must now tell your shell where @command{emacs} and other
3044 programs installed with Guix are to be found. Pasting the two lines
3045 above will do just that: it will add
3046 @code{$HOME/.guix-profile/bin}---which is where the installed package
3047 is---to the @code{PATH} environment variable. You can paste these two
3048 lines in your shell so they take effect right away, but more importantly
3049 you should add them to @file{~/.bash_profile} (or equivalent file if you
3050 do not use Bash) so that environment variables are set next time you
3051 spawn a shell. You only need to do this once and other search paths
3052 environment variables will be taken care of similarly---e.g., if you
3053 eventually install @code{python} and Python libraries,
3054 @env{GUIX_PYTHONPATH} will be defined.
3056 You can go on installing packages at your will. To list installed
3060 guix package --list-installed
3063 To remove a package, you would unsurprisingly run @command{guix remove}.
3064 A distinguishing feature is the ability to @dfn{roll back} any operation
3065 you made---installation, removal, upgrade---by simply typing:
3068 guix package --roll-back
3071 This is because each operation is in fact a @dfn{transaction} that
3072 creates a new @dfn{generation}. These generations and the difference
3073 between them can be displayed by running:
3076 guix package --list-generations
3079 Now you know the basics of package management!
3081 @quotation Going further
3082 @xref{Package Management}, for more about package management. You may
3083 like @dfn{declarative} package management with @command{guix package
3084 --manifest}, managing separate @dfn{profiles} with @option{--profile},
3085 deleting old generations, collecting garbage, and other nifty features
3086 that will come in handy as you become more familiar with Guix. If you
3087 are a developer, @pxref{Development} for additional tools. And if
3088 you're curious, @pxref{Features}, to peek under the hood.
3091 Once you've installed a set of packages, you will want to periodically
3092 @emph{upgrade} them to the latest and greatest version. To do that, you
3093 will first pull the latest revision of Guix and its package collection:
3099 The end result is a new @command{guix} command, under
3100 @file{~/.config/guix/current/bin}. Unless you're on Guix System, the
3101 first time you run @command{guix pull}, be sure to follow the hint that
3102 the command prints and, similar to what we saw above, paste these two
3103 lines in your terminal and @file{.bash_profile}:
3106 GUIX_PROFILE="$HOME/.config/guix/current"
3107 . "$GUIX_PROFILE/etc/profile"
3111 You must also instruct your shell to point to this new @command{guix}:
3117 At this point, you're running a brand new Guix. You can thus go ahead
3118 and actually upgrade all the packages you previously installed:
3124 As you run this command, you will see that binaries are downloaded (or
3125 perhaps some packages are built), and eventually you end up with the
3126 upgraded packages. Should one of these upgraded packages not be to your
3127 liking, remember you can always roll back!
3129 You can display the exact revision of Guix you're currently using by
3136 The information it displays is @emph{all it takes to reproduce the exact
3137 same Guix}, be it at a different point in time or on a different
3140 @quotation Going further
3141 @xref{Invoking guix pull}, for more information. @xref{Channels}, on
3142 how to specify additional @dfn{channels} to pull packages from, how to
3143 replicate Guix, and more. You may also find @command{time-machine}
3144 handy (@pxref{Invoking guix time-machine}).
3147 If you installed Guix System, one of the first things you'll want to do
3148 is to upgrade your system. Once you've run @command{guix pull} to get
3149 the latest Guix, you can upgrade the system like this:
3152 sudo guix system reconfigure /etc/config.scm
3155 Upon completion, the system runs the latest versions of its software
3156 packages. When you eventually reboot, you'll notice a sub-menu in the
3157 bootloader that reads ``Old system generations'': it's what allows you
3158 to boot @emph{an older generation of your system}, should the latest
3159 generation be ``broken'' or otherwise unsatisfying. Just like for
3160 packages, you can always @emph{roll back} to a previous generation
3161 @emph{of the whole system}:
3164 sudo guix system roll-back
3167 There are many things you'll probably want to tweak on your system:
3168 adding new user accounts, adding new system services, fiddling with the
3169 configuration of those services, etc. The system configuration is
3170 @emph{entirely} described in the @file{/etc/config.scm} file.
3171 @xref{Using the Configuration System}, to learn how to change it.
3173 Now you know enough to get started!
3175 @quotation Resources
3176 The rest of this manual provides a reference for all things Guix. Here
3177 are some additional resources you may find useful:
3181 @xref{Top,,, guix-cookbook, The GNU Guix Cookbook}, for a list of
3182 ``how-to'' style of recipes for a variety of applications.
3185 The @uref{https://guix.gnu.org/guix-refcard.pdf, GNU Guix Reference
3186 Card} lists in two pages most of the commands and options you'll ever
3190 The web site contains @uref{https://guix.gnu.org/en/videos/,
3191 instructional videos} covering topics such as everyday use of Guix, how
3192 to get help, and how to become a contributor.
3195 @xref{Documentation}, to learn how to access documentation on your
3199 We hope you will enjoy Guix as much as the community enjoys building it!
3202 @c *********************************************************************
3203 @node Package Management
3204 @chapter Package Management
3207 The purpose of GNU Guix is to allow users to easily install, upgrade, and
3208 remove software packages, without having to know about their build
3209 procedures or dependencies. Guix also goes beyond this obvious set of
3212 This chapter describes the main features of Guix, as well as the
3213 package management tools it provides. Along with the command-line
3214 interface described below (@pxref{Invoking guix package, @code{guix
3215 package}}), you may also use the Emacs-Guix interface (@pxref{Top,,,
3216 emacs-guix, The Emacs-Guix Reference Manual}), after installing
3217 @code{emacs-guix} package (run @kbd{M-x guix-help} command to start
3221 guix install emacs-guix
3225 * Features:: How Guix will make your life brighter.
3226 * Invoking guix package:: Package installation, removal, etc.
3227 * Substitutes:: Downloading pre-built binaries.
3228 * Packages with Multiple Outputs:: Single source package, multiple outputs.
3229 * Invoking guix gc:: Running the garbage collector.
3230 * Invoking guix pull:: Fetching the latest Guix and distribution.
3231 * Invoking guix time-machine:: Running an older revision of Guix.
3232 * Inferiors:: Interacting with another revision of Guix.
3233 * Invoking guix describe:: Display information about your Guix revision.
3234 * Invoking guix archive:: Exporting and importing store files.
3240 Here we assume you've already made your first steps with Guix
3241 (@pxref{Getting Started}) and would like to get an overview about what's
3242 going on under the hood.
3244 When using Guix, each package ends up in the @dfn{package store}, in its
3245 own directory---something that resembles
3246 @file{/gnu/store/xxx-package-1.2}, where @code{xxx} is a base32 string.
3248 Instead of referring to these directories, users have their own
3249 @dfn{profile}, which points to the packages that they actually want to
3250 use. These profiles are stored within each user's home directory, at
3251 @code{$HOME/.guix-profile}.
3253 For example, @code{alice} installs GCC 4.7.2. As a result,
3254 @file{/home/alice/.guix-profile/bin/gcc} points to
3255 @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Now, on the same machine,
3256 @code{bob} had already installed GCC 4.8.0. The profile of @code{bob}
3257 simply continues to point to
3258 @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc}---i.e., both versions of GCC
3259 coexist on the same system without any interference.
3261 The @command{guix package} command is the central tool to manage
3262 packages (@pxref{Invoking guix package}). It operates on the per-user
3263 profiles, and can be used @emph{with normal user privileges}.
3265 @cindex transactions
3266 The command provides the obvious install, remove, and upgrade
3267 operations. Each invocation is actually a @emph{transaction}: either
3268 the specified operation succeeds, or nothing happens. Thus, if the
3269 @command{guix package} process is terminated during the transaction,
3270 or if a power outage occurs during the transaction, then the user's
3271 profile remains in its previous state, and remains usable.
3273 In addition, any package transaction may be @emph{rolled back}. So, if,
3274 for example, an upgrade installs a new version of a package that turns
3275 out to have a serious bug, users may roll back to the previous instance
3276 of their profile, which was known to work well. Similarly, the global
3277 system configuration on Guix is subject to
3278 transactional upgrades and roll-back
3279 (@pxref{Using the Configuration System}).
3281 All packages in the package store may be @emph{garbage-collected}.
3282 Guix can determine which packages are still referenced by user
3283 profiles, and remove those that are provably no longer referenced
3284 (@pxref{Invoking guix gc}). Users may also explicitly remove old
3285 generations of their profile so that the packages they refer to can be
3288 @cindex reproducibility
3289 @cindex reproducible builds
3290 Guix takes a @dfn{purely functional} approach to package
3291 management, as described in the introduction (@pxref{Introduction}).
3292 Each @file{/gnu/store} package directory name contains a hash of all the
3293 inputs that were used to build that package---compiler, libraries, build
3294 scripts, etc. This direct correspondence allows users to make sure a
3295 given package installation matches the current state of their
3296 distribution. It also helps maximize @dfn{build reproducibility}:
3297 thanks to the isolated build environments that are used, a given build
3298 is likely to yield bit-identical files when performed on different
3299 machines (@pxref{Invoking guix-daemon, container}).
3302 This foundation allows Guix to support @dfn{transparent binary/source
3303 deployment}. When a pre-built binary for a @file{/gnu/store} item is
3304 available from an external source---a @dfn{substitute}, Guix just
3305 downloads it and unpacks it;
3306 otherwise, it builds the package from source, locally
3307 (@pxref{Substitutes}). Because build results are usually bit-for-bit
3308 reproducible, users do not have to trust servers that provide
3309 substitutes: they can force a local build and @emph{challenge} providers
3310 (@pxref{Invoking guix challenge}).
3312 Control over the build environment is a feature that is also useful for
3313 developers. The @command{guix shell} command allows developers of
3314 a package to quickly set up the right development environment for their
3315 package, without having to manually install the dependencies of the
3316 package into their profile (@pxref{Invoking guix shell}).
3318 @cindex replication, of software environments
3319 @cindex provenance tracking, of software artifacts
3320 All of Guix and its package definitions is version-controlled, and
3321 @command{guix pull} allows you to ``travel in time'' on the history of Guix
3322 itself (@pxref{Invoking guix pull}). This makes it possible to replicate a
3323 Guix instance on a different machine or at a later point in time, which in
3324 turn allows you to @emph{replicate complete software environments}, while
3325 retaining precise @dfn{provenance tracking} of the software.
3327 @node Invoking guix package
3328 @section Invoking @command{guix package}
3330 @cindex installing packages
3331 @cindex removing packages
3332 @cindex package installation
3333 @cindex package removal
3335 @cindex @command{guix package}
3336 The @command{guix package} command is the tool that allows users to
3337 install, upgrade, and remove packages, as well as rolling back to
3338 previous configurations. These operations work on a user
3339 @dfn{profile}---a directory of installed packages. Each user has a
3340 default profile in @file{$HOME/.guix-profile}.
3341 The command operates only on the user's own profile,
3342 and works with normal user privileges (@pxref{Features}). Its syntax
3346 guix package @var{options}
3349 @cindex transactions
3350 Primarily, @var{options} specifies the operations to be performed during
3351 the transaction. Upon completion, a new profile is created, but
3352 previous @dfn{generations} of the profile remain available, should the user
3355 For example, to remove @code{lua} and install @code{guile} and
3356 @code{guile-cairo} in a single transaction:
3359 guix package -r lua -i guile guile-cairo
3362 @cindex aliases, for @command{guix package}
3363 For your convenience, we also provide the following aliases:
3367 @command{guix search} is an alias for @command{guix package -s},
3369 @command{guix install} is an alias for @command{guix package -i},
3371 @command{guix remove} is an alias for @command{guix package -r},
3373 @command{guix upgrade} is an alias for @command{guix package -u},
3375 and @command{guix show} is an alias for @command{guix package --show=}.
3378 These aliases are less expressive than @command{guix package} and provide
3379 fewer options, so in some cases you'll probably want to use @command{guix
3382 @command{guix package} also supports a @dfn{declarative approach}
3383 whereby the user specifies the exact set of packages to be available and
3384 passes it @i{via} the @option{--manifest} option
3385 (@pxref{profile-manifest, @option{--manifest}}).
3388 For each user, a symlink to the user's default profile is automatically
3389 created in @file{$HOME/.guix-profile}. This symlink always points to the
3390 current generation of the user's default profile. Thus, users can add
3391 @file{$HOME/.guix-profile/bin} to their @env{PATH} environment
3392 variable, and so on.
3393 @cindex search paths
3394 If you are not using Guix System, consider adding the
3395 following lines to your @file{~/.bash_profile} (@pxref{Bash Startup
3396 Files,,, bash, The GNU Bash Reference Manual}) so that newly-spawned
3397 shells get all the right environment variable definitions:
3400 GUIX_PROFILE="$HOME/.guix-profile" ; \
3401 source "$GUIX_PROFILE/etc/profile"
3404 In a multi-user setup, user profiles are stored in a place registered as
3405 a @dfn{garbage-collector root}, which @file{$HOME/.guix-profile} points
3406 to (@pxref{Invoking guix gc}). That directory is normally
3407 @code{@var{localstatedir}/guix/profiles/per-user/@var{user}}, where
3408 @var{localstatedir} is the value passed to @code{configure} as
3409 @option{--localstatedir}, and @var{user} is the user name. The
3410 @file{per-user} directory is created when @command{guix-daemon} is
3411 started, and the @var{user} sub-directory is created by @command{guix
3414 The @var{options} can be among the following:
3418 @item --install=@var{package} @dots{}
3419 @itemx -i @var{package} @dots{}
3420 Install the specified @var{package}s.
3422 Each @var{package} may specify either a simple package name, such as
3423 @code{guile}, or a package name followed by an at-sign and version number,
3424 such as @code{guile@@1.8.8} or simply @code{guile@@1.8} (in the latter
3425 case, the newest version prefixed by @code{1.8} is selected).
3427 If no version number is specified, the
3428 newest available version will be selected. In addition, @var{package}
3429 may contain a colon, followed by the name of one of the outputs of the
3430 package, as in @code{gcc:doc} or @code{binutils@@2.22:lib}
3431 (@pxref{Packages with Multiple Outputs}). Packages with a corresponding
3432 name (and optionally version) are searched for among the GNU
3433 distribution modules (@pxref{Package Modules}).
3435 @cindex propagated inputs
3436 Sometimes packages have @dfn{propagated inputs}: these are dependencies
3437 that automatically get installed along with the required package
3438 (@pxref{package-propagated-inputs, @code{propagated-inputs} in
3439 @code{package} objects}, for information about propagated inputs in
3440 package definitions).
3442 @anchor{package-cmd-propagated-inputs}
3443 An example is the GNU MPC library: its C header files refer to those of
3444 the GNU MPFR library, which in turn refer to those of the GMP library.
3445 Thus, when installing MPC, the MPFR and GMP libraries also get installed
3446 in the profile; removing MPC also removes MPFR and GMP---unless they had
3447 also been explicitly installed by the user.
3449 Besides, packages sometimes rely on the definition of environment
3450 variables for their search paths (see explanation of
3451 @option{--search-paths} below). Any missing or possibly incorrect
3452 environment variable definitions are reported here.
3454 @item --install-from-expression=@var{exp}
3456 Install the package @var{exp} evaluates to.
3458 @var{exp} must be a Scheme expression that evaluates to a
3459 @code{<package>} object. This option is notably useful to disambiguate
3460 between same-named variants of a package, with expressions such as
3461 @code{(@@ (gnu packages base) guile-final)}.
3463 Note that this option installs the first output of the specified
3464 package, which may be insufficient when needing a specific output of a
3465 multiple-output package.
3467 @item --install-from-file=@var{file}
3468 @itemx -f @var{file}
3469 Install the package that the code within @var{file} evaluates to.
3471 As an example, @var{file} might contain a definition like this
3472 (@pxref{Defining Packages}):
3475 @include package-hello.scm
3478 Developers may find it useful to include such a @file{guix.scm} file
3479 in the root of their project source tree that can be used to test
3480 development snapshots and create reproducible development environments
3481 (@pxref{Invoking guix shell}).
3483 The @var{file} may also contain a JSON representation of one or more
3484 package definitions. Running @code{guix package -f} on
3485 @file{hello.json} with the following contents would result in installing
3486 the package @code{greeter} after building @code{myhello}:
3489 @verbatiminclude package-hello.json
3492 @item --remove=@var{package} @dots{}
3493 @itemx -r @var{package} @dots{}
3494 Remove the specified @var{package}s.
3496 As for @option{--install}, each @var{package} may specify a version number
3497 and/or output name in addition to the package name. For instance,
3498 @samp{-r glibc:debug} would remove the @code{debug} output of
3501 @item --upgrade[=@var{regexp} @dots{}]
3502 @itemx -u [@var{regexp} @dots{}]
3503 @cindex upgrading packages
3504 Upgrade all the installed packages. If one or more @var{regexp}s are
3505 specified, upgrade only installed packages whose name matches a
3506 @var{regexp}. Also see the @option{--do-not-upgrade} option below.
3508 Note that this upgrades package to the latest version of packages found
3509 in the distribution currently installed. To update your distribution,
3510 you should regularly run @command{guix pull} (@pxref{Invoking guix
3513 @cindex package transformations, upgrades
3514 When upgrading, package transformations that were originally applied
3515 when creating the profile are automatically re-applied (@pxref{Package
3516 Transformation Options}). For example, assume you first installed Emacs
3517 from the tip of its development branch with:
3520 guix install emacs-next --with-branch=emacs-next=master
3523 Next time you run @command{guix upgrade}, Guix will again pull the tip
3524 of the Emacs development branch and build @code{emacs-next} from that
3527 Note that transformation options such as @option{--with-branch} and
3528 @option{--with-source} depend on external state; it is up to you to
3529 ensure that they work as expected. You can also discard a
3530 transformations that apply to a package by running:
3533 guix install @var{package}
3536 @item --do-not-upgrade[=@var{regexp} @dots{}]
3537 When used together with the @option{--upgrade} option, do @emph{not}
3538 upgrade any packages whose name matches a @var{regexp}. For example, to
3539 upgrade all packages in the current profile except those containing the
3540 substring ``emacs'':
3543 $ guix package --upgrade . --do-not-upgrade emacs
3546 @item @anchor{profile-manifest}--manifest=@var{file}
3547 @itemx -m @var{file}
3548 @cindex profile declaration
3549 @cindex profile manifest
3550 Create a new generation of the profile from the manifest object
3551 returned by the Scheme code in @var{file}. This option can be repeated
3552 several times, in which case the manifests are concatenated.
3554 This allows you to @emph{declare} the profile's contents rather than
3555 constructing it through a sequence of @option{--install} and similar
3556 commands. The advantage is that @var{file} can be put under version
3557 control, copied to different machines to reproduce the same profile, and
3560 @var{file} must return a @dfn{manifest} object, which is roughly a list
3563 @findex packages->manifest
3565 (use-package-modules guile emacs)
3570 ;; Use a specific package output.
3571 (list guile-2.0 "debug")))
3574 @xref{Writing Manifests}, for information on how to write a manifest.
3575 @xref{export-manifest, @option{--export-manifest}}, to learn how to
3576 obtain a manifest file from an existing profile.
3579 @cindex rolling back
3580 @cindex undoing transactions
3581 @cindex transactions, undoing
3582 Roll back to the previous @dfn{generation} of the profile---i.e., undo
3583 the last transaction.
3585 When combined with options such as @option{--install}, roll back occurs
3586 before any other actions.
3588 When rolling back from the first generation that actually contains
3589 installed packages, the profile is made to point to the @dfn{zeroth
3590 generation}, which contains no files apart from its own metadata.
3592 After having rolled back, installing, removing, or upgrading packages
3593 overwrites previous future generations. Thus, the history of the
3594 generations in a profile is always linear.
3596 @item --switch-generation=@var{pattern}
3597 @itemx -S @var{pattern}
3599 Switch to a particular generation defined by @var{pattern}.
3601 @var{pattern} may be either a generation number or a number prefixed
3602 with ``+'' or ``-''. The latter means: move forward/backward by a
3603 specified number of generations. For example, if you want to return to
3604 the latest generation after @option{--roll-back}, use
3605 @option{--switch-generation=+1}.
3607 The difference between @option{--roll-back} and
3608 @option{--switch-generation=-1} is that @option{--switch-generation} will
3609 not make a zeroth generation, so if a specified generation does not
3610 exist, the current generation will not be changed.
3612 @item --search-paths[=@var{kind}]
3613 @cindex search paths
3614 Report environment variable definitions, in Bash syntax, that may be
3615 needed in order to use the set of installed packages. These environment
3616 variables are used to specify @dfn{search paths} for files used by some
3617 of the installed packages.
3619 For example, GCC needs the @env{CPATH} and @env{LIBRARY_PATH}
3620 environment variables to be defined so it can look for headers and
3621 libraries in the user's profile (@pxref{Environment Variables,,, gcc,
3622 Using the GNU Compiler Collection (GCC)}). If GCC and, say, the C
3623 library are installed in the profile, then @option{--search-paths} will
3624 suggest setting these variables to @file{@var{profile}/include} and
3625 @file{@var{profile}/lib}, respectively (@pxref{Search Paths}, for info
3626 on search path specifications associated with packages.)
3628 The typical use case is to define these environment variables in the
3632 $ eval $(guix package --search-paths)
3635 @var{kind} may be one of @code{exact}, @code{prefix}, or @code{suffix},
3636 meaning that the returned environment variable definitions will either
3637 be exact settings, or prefixes or suffixes of the current value of these
3638 variables. When omitted, @var{kind} defaults to @code{exact}.
3640 This option can also be used to compute the @emph{combined} search paths
3641 of several profiles. Consider this example:
3644 $ guix package -p foo -i guile
3645 $ guix package -p bar -i guile-json
3646 $ guix package -p foo -p bar --search-paths
3649 The last command above reports about the @env{GUILE_LOAD_PATH}
3650 variable, even though, taken individually, neither @file{foo} nor
3651 @file{bar} would lead to that recommendation.
3654 @cindex profile, choosing
3655 @item --profile=@var{profile}
3656 @itemx -p @var{profile}
3657 Use @var{profile} instead of the user's default profile.
3659 @var{profile} must be the name of a file that will be created upon
3660 completion. Concretely, @var{profile} will be a mere symbolic link
3661 (``symlink'') pointing to the actual profile where packages are
3665 $ guix install hello -p ~/code/my-profile
3667 $ ~/code/my-profile/bin/hello
3671 All it takes to get rid of the profile is to remove this symlink and its
3672 siblings that point to specific generations:
3675 $ rm ~/code/my-profile ~/code/my-profile-*-link
3678 @item --list-profiles
3679 List all the user's profiles:
3682 $ guix package --list-profiles
3683 /home/charlie/.guix-profile
3684 /home/charlie/code/my-profile
3685 /home/charlie/code/devel-profile
3686 /home/charlie/tmp/test
3689 When running as root, list all the profiles of all the users.
3691 @cindex collisions, in a profile
3692 @cindex colliding packages in profiles
3693 @cindex profile collisions
3694 @item --allow-collisions
3695 Allow colliding packages in the new profile. Use at your own risk!
3697 By default, @command{guix package} reports as an error @dfn{collisions}
3698 in the profile. Collisions happen when two or more different versions
3699 or variants of a given package end up in the profile.
3702 Use the bootstrap Guile to build the profile. This option is only
3703 useful to distribution developers.
3707 In addition to these actions, @command{guix package} supports the
3708 following options to query the current state of a profile, or the
3709 availability of packages:
3713 @item --search=@var{regexp}
3714 @itemx -s @var{regexp}
3715 @anchor{guix-search}
3716 @cindex searching for packages
3717 List the available packages whose name, synopsis, or description matches
3718 @var{regexp} (in a case-insensitive fashion), sorted by relevance.
3719 Print all the metadata of matching packages in
3720 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils,
3721 GNU recutils manual}).
3723 This allows specific fields to be extracted using the @command{recsel}
3724 command, for instance:
3727 $ guix package -s malloc | recsel -p name,version,relevance
3741 Similarly, to show the name of all the packages available under the
3742 terms of the GNU@tie{}LGPL version 3:
3745 $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
3752 It is also possible to refine search results using several @code{-s} flags to
3753 @command{guix package}, or several arguments to @command{guix search}. For
3754 example, the following command returns a list of board games (this time using
3755 the @command{guix search} alias):
3758 $ guix search '\<board\>' game | recsel -p name
3763 If we were to omit @code{-s game}, we would also get software packages
3764 that deal with printed circuit boards; removing the angle brackets
3765 around @code{board} would further add packages that have to do with
3768 And now for a more elaborate example. The following command searches
3769 for cryptographic libraries, filters out Haskell, Perl, Python, and Ruby
3770 libraries, and prints the name and synopsis of the matching packages:
3773 $ guix search crypto library | \
3774 recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
3778 @xref{Selection Expressions,,, recutils, GNU recutils manual}, for more
3779 information on @dfn{selection expressions} for @code{recsel -e}.
3781 @item --show=@var{package}
3782 Show details about @var{package}, taken from the list of available packages, in
3783 @code{recutils} format (@pxref{Top, GNU recutils databases,, recutils, GNU
3787 $ guix package --show=guile | recsel -p name,version
3799 You may also specify the full name of a package to only get details about a
3800 specific version of it (this time using the @command{guix show} alias):
3802 $ guix show guile@@3.0.5 | recsel -p name,version
3807 @item --list-installed[=@var{regexp}]
3808 @itemx -I [@var{regexp}]
3809 List the currently installed packages in the specified profile, with the
3810 most recently installed packages shown last. When @var{regexp} is
3811 specified, list only installed packages whose name matches @var{regexp}.
3813 For each installed package, print the following items, separated by
3814 tabs: the package name, its version string, the part of the package that
3815 is installed (for instance, @code{out} for the default output,
3816 @code{include} for its headers, etc.), and the path of this package in
3819 @item --list-available[=@var{regexp}]
3820 @itemx -A [@var{regexp}]
3821 List packages currently available in the distribution for this system
3822 (@pxref{GNU Distribution}). When @var{regexp} is specified, list only
3823 available packages whose name matches @var{regexp}.
3825 For each package, print the following items separated by tabs: its name,
3826 its version string, the parts of the package (@pxref{Packages with
3827 Multiple Outputs}), and the source location of its definition.
3829 @item --list-generations[=@var{pattern}]
3830 @itemx -l [@var{pattern}]
3832 Return a list of generations along with their creation dates; for each
3833 generation, show the installed packages, with the most recently
3834 installed packages shown last. Note that the zeroth generation is never
3837 For each installed package, print the following items, separated by
3838 tabs: the name of a package, its version string, the part of the package
3839 that is installed (@pxref{Packages with Multiple Outputs}), and the
3840 location of this package in the store.
3842 When @var{pattern} is used, the command returns only matching
3843 generations. Valid patterns include:
3846 @item @emph{Integers and comma-separated integers}. Both patterns denote
3847 generation numbers. For instance, @option{--list-generations=1} returns
3850 And @option{--list-generations=1,8,2} outputs three generations in the
3851 specified order. Neither spaces nor trailing commas are allowed.
3853 @item @emph{Ranges}. @option{--list-generations=2..9} prints the
3854 specified generations and everything in between. Note that the start of
3855 a range must be smaller than its end.
3857 It is also possible to omit the endpoint. For example,
3858 @option{--list-generations=2..}, returns all generations starting from the
3861 @item @emph{Durations}. You can also get the last @emph{N}@tie{}days, weeks,
3862 or months by passing an integer along with the first letter of the
3863 duration. For example, @option{--list-generations=20d} lists generations
3864 that are up to 20 days old.
3867 @item --delete-generations[=@var{pattern}]
3868 @itemx -d [@var{pattern}]
3869 When @var{pattern} is omitted, delete all generations except the current
3872 This command accepts the same patterns as @option{--list-generations}.
3873 When @var{pattern} is specified, delete the matching generations. When
3874 @var{pattern} specifies a duration, generations @emph{older} than the
3875 specified duration match. For instance, @option{--delete-generations=1m}
3876 deletes generations that are more than one month old.
3878 If the current generation matches, it is @emph{not} deleted. Also, the
3879 zeroth generation is never deleted.
3881 Note that deleting generations prevents rolling back to them.
3882 Consequently, this command must be used with care.
3884 @cindex manifest, exporting
3885 @anchor{export-manifest}
3886 @item --export-manifest
3887 Write to standard output a manifest suitable for @option{--manifest}
3888 corresponding to the chosen profile(s).
3890 This option is meant to help you migrate from the ``imperative''
3891 operating mode---running @command{guix install}, @command{guix upgrade},
3892 etc.---to the declarative mode that @option{--manifest} offers.
3894 Be aware that the resulting manifest @emph{approximates} what your
3895 profile actually contains; for instance, depending on how your profile
3896 was created, it can refer to packages or package versions that are not
3897 exactly what you specified.
3899 Keep in mind that a manifest is purely symbolic: it only contains
3900 package names and possibly versions, and their meaning varies over time.
3901 If you wish to ``pin'' channels to the revisions that were used to build
3902 the profile(s), see @option{--export-channels} below.
3904 @cindex pinning, channel revisions of a profile
3905 @item --export-channels
3906 Write to standard output the list of channels used by the chosen
3907 profile(s), in a format suitable for @command{guix pull --channels} or
3908 @command{guix time-machine --channels} (@pxref{Channels}).
3910 Together with @option{--export-manifest}, this option provides
3911 information allowing you to replicate the current profile
3912 (@pxref{Replicating Guix}).
3914 However, note that the output of this command @emph{approximates} what
3915 was actually used to build this profile. In particular, a single
3916 profile might have been built from several different revisions of the
3917 same channel. In that case, @option{--export-manifest} chooses the last
3918 one and writes the list of other revisions in a comment. If you really
3919 need to pick packages from different channel revisions, you can use
3920 inferiors in your manifest to do so (@pxref{Inferiors}).
3922 Together with @option{--export-manifest}, this is a good starting point
3923 if you are willing to migrate from the ``imperative'' model to the fully
3924 declarative model consisting of a manifest file along with a channels
3925 file pinning the exact channel revision(s) you want.
3928 Finally, since @command{guix package} may actually start build
3929 processes, it supports all the common build options (@pxref{Common Build
3930 Options}). It also supports package transformation options, such as
3931 @option{--with-source}, and preserves them across upgrades
3932 (@pxref{Package Transformation Options}).
3935 @section Substitutes
3938 @cindex pre-built binaries
3939 Guix supports transparent source/binary deployment, which means that it
3940 can either build things locally, or download pre-built items from a
3941 server, or both. We call these pre-built items @dfn{substitutes}---they
3942 are substitutes for local build results. In many cases, downloading a
3943 substitute is much faster than building things locally.
3945 Substitutes can be anything resulting from a derivation build
3946 (@pxref{Derivations}). Of course, in the common case, they are
3947 pre-built package binaries, but source tarballs, for instance, which
3948 also result from derivation builds, can be available as substitutes.
3951 * Official Substitute Servers:: One particular source of substitutes.
3952 * Substitute Server Authorization:: How to enable or disable substitutes.
3953 * Getting Substitutes from Other Servers:: Substitute diversity.
3954 * Substitute Authentication:: How Guix verifies substitutes.
3955 * Proxy Settings:: How to get substitutes via proxy.
3956 * Substitution Failure:: What happens when substitution fails.
3957 * On Trusting Binaries:: How can you trust that binary blob?
3960 @node Official Substitute Servers
3961 @subsection Official Substitute Servers
3964 @code{@value{SUBSTITUTE-SERVER-1}} and
3965 @code{@value{SUBSTITUTE-SERVER-2}} are both front-ends to official build
3966 farms that build packages from Guix continuously for some architectures,
3967 and make them available as substitutes. These are the default source of
3968 substitutes; which can be overridden by passing the
3969 @option{--substitute-urls} option either to @command{guix-daemon}
3970 (@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}})
3971 or to client tools such as @command{guix package}
3972 (@pxref{client-substitute-urls,, client @option{--substitute-urls}
3975 Substitute URLs can be either HTTP or HTTPS.
3976 HTTPS is recommended because communications are encrypted; conversely,
3977 using HTTP makes all communications visible to an eavesdropper, who
3978 could use the information gathered to determine, for instance, whether
3979 your system has unpatched security vulnerabilities.
3981 Substitutes from the official build farms are enabled by default when
3982 using Guix System (@pxref{GNU Distribution}). However,
3983 they are disabled by default when using Guix on a foreign distribution,
3984 unless you have explicitly enabled them via one of the recommended
3985 installation steps (@pxref{Installation}). The following paragraphs
3986 describe how to enable or disable substitutes for the official build
3987 farm; the same procedure can also be used to enable substitutes for any
3988 other substitute server.
3990 @node Substitute Server Authorization
3991 @subsection Substitute Server Authorization
3994 @cindex substitutes, authorization thereof
3995 @cindex access control list (ACL), for substitutes
3996 @cindex ACL (access control list), for substitutes
3997 To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER-1}}, @code{@value{SUBSTITUTE-SERVER-2}} or a mirror, you
3998 must add the relevant public key to the access control list (ACL) of archive
3999 imports, using the @command{guix archive} command (@pxref{Invoking guix
4000 archive}). Doing so implies that you trust the substitute server to not
4001 be compromised and to serve genuine substitutes.
4004 If you are using Guix System, you can skip this section: Guix System
4005 authorizes substitutes from @code{@value{SUBSTITUTE-SERVER-1}} and
4006 @code{@value{SUBSTITUTE-SERVER-2}} by default.
4009 The public keys for each of the project maintained substitute servers
4010 are installed along with Guix, in @code{@var{prefix}/share/guix/}, where
4011 @var{prefix} is the installation prefix of Guix. If you installed Guix
4012 from source, make sure you checked the GPG signature of
4013 @file{guix-@value{VERSION}.tar.gz}, which contains this public key file.
4014 Then, you can run something like this:
4017 # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-1}.pub
4018 # guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER-2}.pub
4021 Once this is in place, the output of a command like @code{guix build}
4022 should change from something like:
4025 $ guix build emacs --dry-run
4026 The following derivations would be built:
4027 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
4028 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
4029 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
4030 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
4038 $ guix build emacs --dry-run
4039 112.3 MB would be downloaded:
4040 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
4041 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
4042 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
4043 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
4048 The text changed from ``The following derivations would be built'' to
4049 ``112.3 MB would be downloaded''. This indicates that substitutes from
4050 the configured substitute servers are usable and will be downloaded,
4051 when possible, for future builds.
4053 @cindex substitutes, how to disable
4054 The substitute mechanism can be disabled globally by running
4055 @code{guix-daemon} with @option{--no-substitutes} (@pxref{Invoking
4056 guix-daemon}). It can also be disabled temporarily by passing the
4057 @option{--no-substitutes} option to @command{guix package},
4058 @command{guix build}, and other command-line tools.
4060 @node Getting Substitutes from Other Servers
4061 @subsection Getting Substitutes from Other Servers
4063 @cindex substitute servers, adding more
4064 Guix can look up and fetch substitutes from several servers. This is
4065 useful when you are using packages from additional channels for which
4066 the official server does not have substitutes but another server
4067 provides them. Another situation where this is useful is when you would
4068 prefer to download from your organization's substitute server, resorting
4069 to the official server only as a fallback or dismissing it altogether.
4071 You can give Guix a list of substitute server URLs and it will check
4072 them in the specified order. You also need to explicitly authorize the
4073 public keys of substitute servers to instruct Guix to accept the
4074 substitutes they sign.
4076 On Guix System, this is achieved by modifying the configuration of the
4077 @code{guix} service. Since the @code{guix} service is part of the
4078 default lists of services, @code{%base-services} and
4079 @code{%desktop-services}, you can use @code{modify-services} to change
4080 its configuration and add the URLs and substitute keys that you want
4081 (@pxref{Service Reference, @code{modify-services}}).
4083 As an example, suppose you want to fetch substitutes from
4084 @code{guix.example.org} and to authorize the signing key of that server,
4085 in addition to the default @code{@value{SUBSTITUTE-SERVER-1}} and
4086 @code{@value{SUBSTITUTE-SERVER-2}}. The resulting operating system
4087 configuration will look something like:
4093 ;; Assume we're starting from '%desktop-services'. Replace it
4094 ;; with the list of services you're actually using.
4095 (modify-services %desktop-services
4096 (guix-service-type config =>
4100 (append (list "https://guix.example.org")
4101 %default-substitute-urls))
4103 (append (list (local-file "./key.pub"))
4104 %default-authorized-guix-keys)))))))
4107 This assumes that the file @file{key.pub} contains the signing key of
4108 @code{guix.example.org}. With this change in place in your operating
4109 system configuration file (say @file{/etc/config.scm}), you can
4110 reconfigure and restart the @code{guix-daemon} service or reboot so the
4111 changes take effect:
4114 $ sudo guix system reconfigure /etc/config.scm
4115 $ sudo herd restart guix-daemon
4118 If you're running Guix on a ``foreign distro'', you would instead take
4119 the following steps to get substitutes from additional servers:
4123 Edit the service configuration file for @code{guix-daemon}; when using
4124 systemd, this is normally
4125 @file{/etc/systemd/system/guix-daemon.service}. Add the
4126 @option{--substitute-urls} option on the @command{guix-daemon} command
4127 line and list the URLs of interest (@pxref{daemon-substitute-urls,
4128 @code{guix-daemon --substitute-urls}}):
4131 @dots{} --substitute-urls='https://guix.example.org @value{SUBSTITUTE-URLS}'
4135 Restart the daemon. For systemd, it goes like this:
4138 systemctl daemon-reload
4139 systemctl restart guix-daemon.service
4143 Authorize the key of the new server (@pxref{Invoking guix archive}):
4146 guix archive --authorize < key.pub
4149 Again this assumes @file{key.pub} contains the public key that
4150 @code{guix.example.org} uses to sign substitutes.
4153 Now you're all set! Substitutes will be preferably taken from
4154 @code{https://guix.example.org}, using
4155 @code{@value{SUBSTITUTE-SERVER-1}} then
4156 @code{@value{SUBSTITUTE-SERVER-2}} as fallback options. Of course you
4157 can list as many substitute servers as you like, with the caveat that
4158 substitute lookup can be slowed down if too many servers need to be
4161 Note that there are also situations where one may want to add the URL of
4162 a substitute server @emph{without} authorizing its key.
4163 @xref{Substitute Authentication}, to understand this fine point.
4165 @node Substitute Authentication
4166 @subsection Substitute Authentication
4168 @cindex digital signatures
4169 Guix detects and raises an error when attempting to use a substitute
4170 that has been tampered with. Likewise, it ignores substitutes that are
4171 not signed, or that are not signed by one of the keys listed in the ACL.
4173 There is one exception though: if an unauthorized server provides
4174 substitutes that are @emph{bit-for-bit identical} to those provided by
4175 an authorized server, then the unauthorized server becomes eligible for
4176 downloads. For example, assume we have chosen two substitute servers
4180 --substitute-urls="https://a.example.org https://b.example.org"
4184 @cindex reproducible builds
4185 If the ACL contains only the key for @samp{b.example.org}, and if
4186 @samp{a.example.org} happens to serve the @emph{exact same} substitutes,
4187 then Guix will download substitutes from @samp{a.example.org} because it
4188 comes first in the list and can be considered a mirror of
4189 @samp{b.example.org}. In practice, independent build machines usually
4190 produce the same binaries, thanks to bit-reproducible builds (see
4193 When using HTTPS, the server's X.509 certificate is @emph{not} validated
4194 (in other words, the server is not authenticated), contrary to what
4195 HTTPS clients such as Web browsers usually do. This is because Guix
4196 authenticates substitute information itself, as explained above, which
4197 is what we care about (whereas X.509 certificates are about
4198 authenticating bindings between domain names and public keys).
4200 @node Proxy Settings
4201 @subsection Proxy Settings
4205 Substitutes are downloaded over HTTP or HTTPS@. The @env{http_proxy} and
4206 @env{https_proxy} environment variables can be set in the environment of
4207 @command{guix-daemon} and are honored for downloads of substitutes.
4208 Note that the value of those environment variables in the environment
4209 where @command{guix build}, @command{guix package}, and other client
4210 commands are run has @emph{absolutely no effect}.
4212 @node Substitution Failure
4213 @subsection Substitution Failure
4215 Even when a substitute for a derivation is available, sometimes the
4216 substitution attempt will fail. This can happen for a variety of
4217 reasons: the substitute server might be offline, the substitute may
4218 recently have been deleted, the connection might have been interrupted,
4221 When substitutes are enabled and a substitute for a derivation is
4222 available, but the substitution attempt fails, Guix will attempt to
4223 build the derivation locally depending on whether or not
4224 @option{--fallback} was given (@pxref{fallback-option,, common build
4225 option @option{--fallback}}). Specifically, if @option{--fallback} was
4226 omitted, then no local build will be performed, and the derivation is
4227 considered to have failed. However, if @option{--fallback} was given,
4228 then Guix will attempt to build the derivation locally, and the success
4229 or failure of the derivation depends on the success or failure of the
4230 local build. Note that when substitutes are disabled or no substitute
4231 is available for the derivation in question, a local build will
4232 @emph{always} be performed, regardless of whether or not
4233 @option{--fallback} was given.
4235 To get an idea of how many substitutes are available right now, you can
4236 try running the @command{guix weather} command (@pxref{Invoking guix
4237 weather}). This command provides statistics on the substitutes provided
4240 @node On Trusting Binaries
4241 @subsection On Trusting Binaries
4243 @cindex trust, of pre-built binaries
4244 Today, each individual's control over their own computing is at the
4245 mercy of institutions, corporations, and groups with enough power and
4246 determination to subvert the computing infrastructure and exploit its
4247 weaknesses. While using substitutes can be convenient, we encourage
4248 users to also build on their own, or even run their own build farm, such
4249 that the project run substitute servers are less of an interesting
4250 target. One way to help is by publishing the software you build using
4251 @command{guix publish} so that others have one more choice of server to
4252 download substitutes from (@pxref{Invoking guix publish}).
4254 Guix has the foundations to maximize build reproducibility
4255 (@pxref{Features}). In most cases, independent builds of a given
4256 package or derivation should yield bit-identical results. Thus, through
4257 a diverse set of independent package builds, we can strengthen the
4258 integrity of our systems. The @command{guix challenge} command aims to
4259 help users assess substitute servers, and to assist developers in
4260 finding out about non-deterministic package builds (@pxref{Invoking guix
4261 challenge}). Similarly, the @option{--check} option of @command{guix
4262 build} allows users to check whether previously-installed substitutes
4263 are genuine by rebuilding them locally (@pxref{build-check,
4264 @command{guix build --check}}).
4266 In the future, we want Guix to have support to publish and retrieve
4267 binaries to/from other users, in a peer-to-peer fashion. If you would
4268 like to discuss this project, join us on @email{guix-devel@@gnu.org}.
4270 @node Packages with Multiple Outputs
4271 @section Packages with Multiple Outputs
4273 @cindex multiple-output packages
4274 @cindex package outputs
4277 Often, packages defined in Guix have a single @dfn{output}---i.e., the
4278 source package leads to exactly one directory in the store. When running
4279 @command{guix install glibc}, one installs the default output of the
4280 GNU libc package; the default output is called @code{out}, but its name
4281 can be omitted as shown in this command. In this particular case, the
4282 default output of @code{glibc} contains all the C header files, shared
4283 libraries, static libraries, Info documentation, and other supporting
4286 Sometimes it is more appropriate to separate the various types of files
4287 produced from a single source package into separate outputs. For
4288 instance, the GLib C library (used by GTK+ and related packages)
4289 installs more than 20 MiB of reference documentation as HTML pages.
4290 To save space for users who do not need it, the documentation goes to a
4291 separate output, called @code{doc}. To install the main GLib output,
4292 which contains everything but the documentation, one would run:
4298 @cindex documentation
4299 The command to install its documentation is:
4302 guix install glib:doc
4305 Some packages install programs with different ``dependency footprints''.
4306 For instance, the WordNet package installs both command-line tools and
4307 graphical user interfaces (GUIs). The former depend solely on the C
4308 library, whereas the latter depend on Tcl/Tk and the underlying X
4309 libraries. In this case, we leave the command-line tools in the default
4310 output, whereas the GUIs are in a separate output. This allows users
4311 who do not need the GUIs to save space. The @command{guix size} command
4312 can help find out about such situations (@pxref{Invoking guix size}).
4313 @command{guix graph} can also be helpful (@pxref{Invoking guix graph}).
4315 There are several such multiple-output packages in the GNU distribution.
4316 Other conventional output names include @code{lib} for libraries and
4317 possibly header files, @code{bin} for stand-alone programs, and
4318 @code{debug} for debugging information (@pxref{Installing Debugging
4319 Files}). The outputs of a packages are listed in the third column of
4320 the output of @command{guix package --list-available} (@pxref{Invoking
4324 @node Invoking guix gc
4325 @section Invoking @command{guix gc}
4327 @cindex garbage collector
4329 @cindex @command{guix gc}
4330 Packages that are installed, but not used, may be @dfn{garbage-collected}.
4331 The @command{guix gc} command allows users to explicitly run the garbage
4332 collector to reclaim space from the @file{/gnu/store} directory. It is
4333 the @emph{only} way to remove files from @file{/gnu/store}---removing
4334 files or directories manually may break it beyond repair!
4337 @cindex garbage collector roots
4338 The garbage collector has a set of known @dfn{roots}: any file under
4339 @file{/gnu/store} reachable from a root is considered @dfn{live} and
4340 cannot be deleted; any other file is considered @dfn{dead} and may be
4341 deleted. The set of garbage collector roots (``GC roots'' for short)
4342 includes default user profiles; by default, the symlinks under
4343 @file{/var/guix/gcroots} represent these GC roots. New GC roots can be
4344 added with @command{guix build --root}, for example (@pxref{Invoking
4345 guix build}). The @command{guix gc --list-roots} command lists them.
4347 Prior to running @code{guix gc --collect-garbage} to make space, it is
4348 often useful to remove old generations from user profiles; that way, old
4349 package builds referenced by those generations can be reclaimed. This
4350 is achieved by running @code{guix package --delete-generations}
4351 (@pxref{Invoking guix package}).
4353 Our recommendation is to run a garbage collection periodically, or when
4354 you are short on disk space. For instance, to guarantee that at least
4355 5@tie{}GB are available on your disk, simply run:
4361 It is perfectly safe to run as a non-interactive periodic job
4362 (@pxref{Scheduled Job Execution}, for how to set up such a job).
4363 Running @command{guix gc} with no arguments will collect as
4364 much garbage as it can, but that is often inconvenient: you may find
4365 yourself having to rebuild or re-download software that is ``dead'' from
4366 the GC viewpoint but that is necessary to build other pieces of
4367 software---e.g., the compiler tool chain.
4369 The @command{guix gc} command has three modes of operation: it can be
4370 used to garbage-collect any dead files (the default), to delete specific
4371 files (the @option{--delete} option), to print garbage-collector
4372 information, or for more advanced queries. The garbage collection
4373 options are as follows:
4376 @item --collect-garbage[=@var{min}]
4377 @itemx -C [@var{min}]
4378 Collect garbage---i.e., unreachable @file{/gnu/store} files and
4379 sub-directories. This is the default operation when no option is
4382 When @var{min} is given, stop once @var{min} bytes have been collected.
4383 @var{min} may be a number of bytes, or it may include a unit as a
4384 suffix, such as @code{MiB} for mebibytes and @code{GB} for gigabytes
4385 (@pxref{Block size, size specifications,, coreutils, GNU Coreutils}).
4387 When @var{min} is omitted, collect all the garbage.
4389 @item --free-space=@var{free}
4390 @itemx -F @var{free}
4391 Collect garbage until @var{free} space is available under
4392 @file{/gnu/store}, if possible; @var{free} denotes storage space, such
4393 as @code{500MiB}, as described above.
4395 When @var{free} or more is already available in @file{/gnu/store}, do
4396 nothing and exit immediately.
4398 @item --delete-generations[=@var{duration}]
4399 @itemx -d [@var{duration}]
4400 Before starting the garbage collection process, delete all the generations
4401 older than @var{duration}, for all the user profiles and home environment
4402 generations; when run as root, this
4403 applies to all the profiles @emph{of all the users}.
4405 For example, this command deletes all the generations of all your profiles
4406 that are older than 2 months (except generations that are current), and then
4407 proceeds to free space until at least 10 GiB are available:
4410 guix gc -d 2m -F 10G
4415 Attempt to delete all the store files and directories specified as
4416 arguments. This fails if some of the files are not in the store, or if
4417 they are still live.
4419 @item --list-failures
4420 List store items corresponding to cached build failures.
4422 This prints nothing unless the daemon was started with
4423 @option{--cache-failures} (@pxref{Invoking guix-daemon,
4424 @option{--cache-failures}}).
4427 List the GC roots owned by the user; when run as root, list @emph{all} the GC
4431 List store items in use by currently running processes. These store
4432 items are effectively considered GC roots: they cannot be deleted.
4434 @item --clear-failures
4435 Remove the specified store items from the failed-build cache.
4437 Again, this option only makes sense when the daemon is started with
4438 @option{--cache-failures}. Otherwise, it does nothing.
4441 Show the list of dead files and directories still present in the
4442 store---i.e., files and directories no longer reachable from any root.
4445 Show the list of live store files and directories.
4449 In addition, the references among existing store files can be queried:
4455 @cindex package dependencies
4456 List the references (respectively, the referrers) of store files given
4462 List the requisites of the store files passed as arguments. Requisites
4463 include the store files themselves, their references, and the references
4464 of these, recursively. In other words, the returned list is the
4465 @dfn{transitive closure} of the store files.
4467 @xref{Invoking guix size}, for a tool to profile the size of the closure
4468 of an element. @xref{Invoking guix graph}, for a tool to visualize
4469 the graph of references.
4473 Return the derivation(s) leading to the given store items
4474 (@pxref{Derivations}).
4476 For example, this command:
4479 guix gc --derivers $(guix package -I ^emacs$ | cut -f4)
4483 returns the @file{.drv} file(s) leading to the @code{emacs} package
4484 installed in your profile.
4486 Note that there may be zero matching @file{.drv} files, for instance
4487 because these files have been garbage-collected. There can also be more
4488 than one matching @file{.drv} due to fixed-output derivations.
4491 Lastly, the following options allow you to check the integrity of the
4492 store and to control disk usage.
4496 @item --verify[=@var{options}]
4497 @cindex integrity, of the store
4498 @cindex integrity checking
4499 Verify the integrity of the store.
4501 By default, make sure that all the store items marked as valid in the
4502 database of the daemon actually exist in @file{/gnu/store}.
4504 When provided, @var{options} must be a comma-separated list containing one
4505 or more of @code{contents} and @code{repair}.
4507 When passing @option{--verify=contents}, the daemon computes the
4508 content hash of each store item and compares it against its hash in the
4509 database. Hash mismatches are reported as data corruptions. Because it
4510 traverses @emph{all the files in the store}, this command can take a
4511 long time, especially on systems with a slow disk drive.
4513 @cindex repairing the store
4514 @cindex corruption, recovering from
4515 Using @option{--verify=repair} or @option{--verify=contents,repair}
4516 causes the daemon to try to repair corrupt store items by fetching
4517 substitutes for them (@pxref{Substitutes}). Because repairing is not
4518 atomic, and thus potentially dangerous, it is available only to the
4519 system administrator. A lightweight alternative, when you know exactly
4520 which items in the store are corrupt, is @command{guix build --repair}
4521 (@pxref{Invoking guix build}).
4524 @cindex deduplication
4525 Optimize the store by hard-linking identical files---this is
4526 @dfn{deduplication}.
4528 The daemon performs deduplication after each successful build or archive
4529 import, unless it was started with @option{--disable-deduplication}
4530 (@pxref{Invoking guix-daemon, @option{--disable-deduplication}}). Thus,
4531 this option is primarily useful when the daemon was running with
4532 @option{--disable-deduplication}.
4536 @node Invoking guix pull
4537 @section Invoking @command{guix pull}
4539 @cindex upgrading Guix
4540 @cindex updating Guix
4541 @cindex @command{guix pull}
4543 @cindex security, @command{guix pull}
4544 @cindex authenticity, of code obtained with @command{guix pull}
4545 Packages are installed or upgraded to the latest version available in
4546 the distribution currently available on your local machine. To update
4547 that distribution, along with the Guix tools, you must run @command{guix
4548 pull}: the command downloads the latest Guix source code and package
4549 descriptions, and deploys it. Source code is downloaded from a
4550 @uref{https://git-scm.com, Git} repository, by default the official
4551 GNU@tie{}Guix repository, though this can be customized. @command{guix
4552 pull} ensures that the code it downloads is @emph{authentic} by
4553 verifying that commits are signed by Guix developers.
4555 Specifically, @command{guix pull} downloads code from the @dfn{channels}
4556 (@pxref{Channels}) specified by one of the followings, in this order:
4560 the @option{--channels} option;
4562 the user's @file{~/.config/guix/channels.scm} file;
4564 the system-wide @file{/etc/guix/channels.scm} file;
4566 the built-in default channels specified in the @code{%default-channels}
4570 On completion, @command{guix package} will use packages and package
4571 versions from this just-retrieved copy of Guix. Not only that, but all
4572 the Guix commands and Scheme modules will also be taken from that latest
4573 version. New @command{guix} sub-commands added by the update also
4576 Any user can update their Guix copy using @command{guix pull}, and the
4577 effect is limited to the user who ran @command{guix pull}. For
4578 instance, when user @code{root} runs @command{guix pull}, this has no
4579 effect on the version of Guix that user @code{alice} sees, and vice
4582 The result of running @command{guix pull} is a @dfn{profile} available
4583 under @file{~/.config/guix/current} containing the latest Guix. Thus,
4584 make sure to add it to the beginning of your search path so that you use
4585 the latest version, and similarly for the Info manual
4586 (@pxref{Documentation}):
4589 export PATH="$HOME/.config/guix/current/bin:$PATH"
4590 export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
4593 The @option{--list-generations} or @option{-l} option lists past generations
4594 produced by @command{guix pull}, along with details about their provenance:
4598 Generation 1 Jun 10 2018 00:18:18
4600 repository URL: https://git.savannah.gnu.org/git/guix.git
4601 branch: origin/master
4602 commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
4604 Generation 2 Jun 11 2018 11:02:49
4606 repository URL: https://git.savannah.gnu.org/git/guix.git
4607 branch: origin/master
4608 commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
4610 Generation 3 Jun 13 2018 23:31:07 (current)
4612 repository URL: https://git.savannah.gnu.org/git/guix.git
4613 branch: origin/master
4614 commit: 844cc1c8f394f03b404c5bb3aee086922373490c
4617 @xref{Invoking guix describe, @command{guix describe}}, for other ways to
4618 describe the current status of Guix.
4620 This @code{~/.config/guix/current} profile works exactly like the profiles
4621 created by @command{guix package} (@pxref{Invoking guix package}). That
4622 is, you can list generations, roll back to the previous
4623 generation---i.e., the previous Guix---and so on:
4626 $ guix pull --roll-back
4627 switched from generation 3 to 2
4628 $ guix pull --delete-generations=1
4629 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
4632 You can also use @command{guix package} (@pxref{Invoking guix package})
4633 to manage the profile by naming it explicitly:
4635 $ guix package -p ~/.config/guix/current --roll-back
4636 switched from generation 3 to 2
4637 $ guix package -p ~/.config/guix/current --delete-generations=1
4638 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
4641 The @command{guix pull} command is usually invoked with no arguments,
4642 but it supports the following options:
4645 @item --url=@var{url}
4646 @itemx --commit=@var{commit}
4647 @itemx --branch=@var{branch}
4648 Download code for the @code{guix} channel from the specified @var{url}, at the
4649 given @var{commit} (a valid Git commit ID represented as a hexadecimal
4650 string or the name of a tag), or @var{branch}.
4652 @cindex @file{channels.scm}, configuration file
4653 @cindex configuration file for channels
4654 These options are provided for convenience, but you can also specify your
4655 configuration in the @file{~/.config/guix/channels.scm} file or using the
4656 @option{--channels} option (see below).
4658 @item --channels=@var{file}
4659 @itemx -C @var{file}
4660 Read the list of channels from @var{file} instead of
4661 @file{~/.config/guix/channels.scm} or @file{/etc/guix/channels.scm}.
4662 @var{file} must contain Scheme code that
4663 evaluates to a list of channel objects. @xref{Channels}, for more
4666 @cindex channel news
4669 Display news written by channel authors for their users for changes made
4670 since the previous generation (@pxref{Channels, Writing Channel News}).
4671 When @option{--details} is passed, additionally display new and upgraded
4674 You can view that information for previous generations with
4675 @command{guix pull -l}.
4677 @item --list-generations[=@var{pattern}]
4678 @itemx -l [@var{pattern}]
4679 List all the generations of @file{~/.config/guix/current} or, if @var{pattern}
4680 is provided, the subset of generations that match @var{pattern}.
4681 The syntax of @var{pattern} is the same as with @code{guix package
4682 --list-generations} (@pxref{Invoking guix package}).
4684 By default, this prints information about the channels used in each
4685 revision as well as the corresponding news entries. If you pass
4686 @option{--details}, it will also print the list of packages added and
4687 upgraded in each generation compared to the previous one.
4690 Instruct @option{--list-generations} or @option{--news} to display more
4691 information about the differences between subsequent generations---see
4695 @cindex rolling back
4696 @cindex undoing transactions
4697 @cindex transactions, undoing
4698 Roll back to the previous @dfn{generation} of @file{~/.config/guix/current}---i.e.,
4699 undo the last transaction.
4701 @item --switch-generation=@var{pattern}
4702 @itemx -S @var{pattern}
4704 Switch to a particular generation defined by @var{pattern}.
4706 @var{pattern} may be either a generation number or a number prefixed
4707 with ``+'' or ``-''. The latter means: move forward/backward by a
4708 specified number of generations. For example, if you want to return to
4709 the latest generation after @option{--roll-back}, use
4710 @option{--switch-generation=+1}.
4712 @item --delete-generations[=@var{pattern}]
4713 @itemx -d [@var{pattern}]
4714 When @var{pattern} is omitted, delete all generations except the current
4717 This command accepts the same patterns as @option{--list-generations}.
4718 When @var{pattern} is specified, delete the matching generations. When
4719 @var{pattern} specifies a duration, generations @emph{older} than the
4720 specified duration match. For instance, @option{--delete-generations=1m}
4721 deletes generations that are more than one month old.
4723 If the current generation matches, it is @emph{not} deleted.
4725 Note that deleting generations prevents rolling back to them.
4726 Consequently, this command must be used with care.
4728 @xref{Invoking guix describe}, for a way to display information about the
4729 current generation only.
4731 @item --profile=@var{profile}
4732 @itemx -p @var{profile}
4733 Use @var{profile} instead of @file{~/.config/guix/current}.
4737 Show which channel commit(s) would be used and what would be built or
4738 substituted but do not actually do it.
4740 @item --allow-downgrades
4741 Allow pulling older or unrelated revisions of channels than those
4744 @cindex downgrade attacks, protection against
4745 By default, @command{guix pull} protects against so-called ``downgrade
4746 attacks'' whereby the Git repository of a channel would be reset to an
4747 earlier or unrelated revision of itself, potentially leading you to
4748 install older, known-vulnerable versions of software packages.
4751 Make sure you understand its security implications before using
4752 @option{--allow-downgrades}.
4755 @item --disable-authentication
4756 Allow pulling channel code without authenticating it.
4758 @cindex authentication, of channel code
4759 By default, @command{guix pull} authenticates code downloaded from
4760 channels by verifying that its commits are signed by authorized
4761 developers, and raises an error if this is not the case. This option
4762 instructs it to not perform any such verification.
4765 Make sure you understand its security implications before using
4766 @option{--disable-authentication}.
4769 @item --system=@var{system}
4770 @itemx -s @var{system}
4771 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
4772 the system type of the build host.
4775 Use the bootstrap Guile to build the latest Guix. This option is only
4776 useful to Guix developers.
4779 The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
4780 repository and branch to pull from, as well as @emph{additional} repositories
4781 containing package modules that should be deployed. @xref{Channels}, for more
4784 In addition, @command{guix pull} supports all the common build options
4785 (@pxref{Common Build Options}).
4787 @node Invoking guix time-machine
4788 @section Invoking @command{guix time-machine}
4790 @cindex @command{guix time-machine}
4791 @cindex pinning, channels
4792 @cindex replicating Guix
4793 @cindex reproducibility, of Guix
4795 The @command{guix time-machine} command provides access to other
4796 revisions of Guix, for example to install older versions of packages,
4797 or to reproduce a computation in an identical environment. The revision
4798 of Guix to be used is defined by a commit or by a channel
4799 description file created by @command{guix describe}
4800 (@pxref{Invoking guix describe}).
4802 Let's assume that you want to travel to those days of November 2020 when
4803 version 1.2.0 of Guix was released and, once you're there, run the
4804 @command{guile} of that time:
4807 guix time-machine --commit=v1.2.0 -- \
4808 environment -C --ad-hoc guile -- guile
4811 The command above fetches Guix@tie{}1.2.0 and runs its @command{guix
4812 environment} command to spawn an environment in a container running
4813 @command{guile} (@command{guix environment} has since been subsumed by
4814 @command{guix shell}; @pxref{Invoking guix shell}). It's like driving a
4815 DeLorean@footnote{If you don't know what a DeLorean is, consider
4816 traveling back to the 1980's.}! The first @command{guix time-machine}
4817 invocation can be expensive: it may have to download or even build a
4818 large number of packages; the result is cached though and subsequent
4819 commands targeting the same commit are almost instantaneous.
4821 The general syntax is:
4824 guix time-machine @var{options}@dots{} -- @var{command} @var {arg}@dots{}
4827 where @var{command} and @var{arg}@dots{} are passed unmodified to the
4828 @command{guix} command of the specified revision. The @var{options} that define
4829 this revision are the same as for @command{guix pull} (@pxref{Invoking guix pull}):
4832 @item --url=@var{url}
4833 @itemx --commit=@var{commit}
4834 @itemx --branch=@var{branch}
4835 Use the @code{guix} channel from the specified @var{url}, at the
4836 given @var{commit} (a valid Git commit ID represented as a hexadecimal
4837 string or the name of a tag), or @var{branch}.
4839 @item --channels=@var{file}
4840 @itemx -C @var{file}
4841 Read the list of channels from @var{file}. @var{file} must contain
4842 Scheme code that evaluates to a list of channel objects.
4843 @xref{Channels} for more information.
4846 As for @command{guix pull}, the absence of any options means that the
4847 latest commit on the master branch will be used. The command
4850 guix time-machine -- build hello
4853 will thus build the package @code{hello} as defined in the master branch,
4854 which is in general a newer revision of Guix than you have installed.
4855 Time travel works in both directions!
4857 Note that @command{guix time-machine} can trigger builds of channels and
4858 their dependencies, and these are controlled by the standard build
4859 options (@pxref{Common Build Options}).
4864 @c TODO: Remove this once we're more confident about API stability.
4866 The functionality described here is a ``technology preview'' as of version
4867 @value{VERSION}. As such, the interface is subject to change.
4871 @cindex composition of Guix revisions
4872 Sometimes you might need to mix packages from the revision of Guix you're
4873 currently running with packages available in a different revision of Guix.
4874 Guix @dfn{inferiors} allow you to achieve that by composing different Guix
4875 revisions in arbitrary ways.
4877 @cindex inferior packages
4878 Technically, an ``inferior'' is essentially a separate Guix process connected
4879 to your main Guix process through a REPL (@pxref{Invoking guix repl}). The
4880 @code{(guix inferior)} module allows you to create inferiors and to
4881 communicate with them. It also provides a high-level interface to browse and
4882 manipulate the packages that an inferior provides---@dfn{inferior packages}.
4884 When combined with channels (@pxref{Channels}), inferiors provide a simple way
4885 to interact with a separate revision of Guix. For example, let's assume you
4886 want to install in your profile the current @code{guile} package, along with
4887 the @code{guile-json} as it existed in an older revision of Guix---perhaps
4888 because the newer @code{guile-json} has an incompatible API and you want to
4889 run your code against the old API@. To do that, you could write a manifest for
4890 use by @code{guix package --manifest} (@pxref{Writing Manifests}); in that
4891 manifest, you would create an inferior for that old Guix revision you care
4892 about, and you would look up the @code{guile-json} package in the inferior:
4895 (use-modules (guix inferior) (guix channels)
4896 (srfi srfi-1)) ;for 'first'
4899 ;; This is the old revision from which we want to
4900 ;; extract guile-json.
4903 (url "https://git.savannah.gnu.org/git/guix.git")
4905 "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
4908 ;; An inferior representing the above revision.
4909 (inferior-for-channels channels))
4911 ;; Now create a manifest with the current "guile" package
4912 ;; and the old "guile-json" package.
4914 (list (first (lookup-inferior-packages inferior "guile-json"))
4915 (specification->package "guile")))
4918 On its first run, @command{guix package --manifest} might have to build the
4919 channel you specified before it can create the inferior; subsequent runs will
4920 be much faster because the Guix revision will be cached.
4922 The @code{(guix inferior)} module provides the following procedures to open an
4925 @deffn {Scheme Procedure} inferior-for-channels @var{channels} @
4926 [#:cache-directory] [#:ttl]
4927 Return an inferior for @var{channels}, a list of channels. Use the cache at
4928 @var{cache-directory}, where entries can be reclaimed after @var{ttl} seconds.
4929 This procedure opens a new connection to the build daemon.
4931 As a side effect, this procedure may build or substitute binaries for
4932 @var{channels}, which can take time.
4935 @deffn {Scheme Procedure} open-inferior @var{directory} @
4936 [#:command "bin/guix"]
4937 Open the inferior Guix in @var{directory}, running
4938 @code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f} if
4939 the inferior could not be launched.
4942 @cindex inferior packages
4943 The procedures listed below allow you to obtain and manipulate inferior
4946 @deffn {Scheme Procedure} inferior-packages @var{inferior}
4947 Return the list of packages known to @var{inferior}.
4950 @deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
4952 Return the sorted list of inferior packages matching @var{name} in
4953 @var{inferior}, with highest version numbers first. If @var{version} is true,
4954 return only packages with a version number prefixed by @var{version}.
4957 @deffn {Scheme Procedure} inferior-package? @var{obj}
4958 Return true if @var{obj} is an inferior package.
4961 @deffn {Scheme Procedure} inferior-package-name @var{package}
4962 @deffnx {Scheme Procedure} inferior-package-version @var{package}
4963 @deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
4964 @deffnx {Scheme Procedure} inferior-package-description @var{package}
4965 @deffnx {Scheme Procedure} inferior-package-home-page @var{package}
4966 @deffnx {Scheme Procedure} inferior-package-location @var{package}
4967 @deffnx {Scheme Procedure} inferior-package-inputs @var{package}
4968 @deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
4969 @deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
4970 @deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
4971 @deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
4972 @deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
4973 @deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
4974 These procedures are the counterpart of package record accessors
4975 (@pxref{package Reference}). Most of them work by querying the inferior
4976 @var{package} comes from, so the inferior must still be live when you call
4980 Inferior packages can be used transparently like any other package or
4981 file-like object in G-expressions (@pxref{G-Expressions}). They are also
4982 transparently handled by the @code{packages->manifest} procedure, which is
4983 commonly used in manifests (@pxref{Invoking guix package, the
4984 @option{--manifest} option of @command{guix package}}). Thus you can insert
4985 an inferior package pretty much anywhere you would insert a regular package:
4986 in manifests, in the @code{packages} field of your @code{operating-system}
4987 declaration, and so on.
4989 @node Invoking guix describe
4990 @section Invoking @command{guix describe}
4992 @cindex reproducibility
4993 @cindex replicating Guix
4994 @cindex @command{guix describe}
4995 Often you may want to answer questions like: ``Which revision of Guix am I
4996 using?'' or ``Which channels am I using?'' This is useful information in many
4997 situations: if you want to @emph{replicate} an environment on a different
4998 machine or user account, if you want to report a bug or to determine what
4999 change in the channels you are using caused it, or if you want to record your
5000 system state for reproducibility purposes. The @command{guix describe}
5001 command answers these questions.
5003 When run from a @command{guix pull}ed @command{guix}, @command{guix describe}
5004 displays the channel(s) that it was built from, including their repository URL
5005 and commit IDs (@pxref{Channels}):
5009 Generation 10 Sep 03 2018 17:32:44 (current)
5011 repository URL: https://git.savannah.gnu.org/git/guix.git
5013 commit: e0fa68c7718fffd33d81af415279d6ddb518f727
5016 If you're familiar with the Git version control system, this is similar in
5017 spirit to @command{git describe}; the output is also similar to that of
5018 @command{guix pull --list-generations}, but limited to the current generation
5019 (@pxref{Invoking guix pull, the @option{--list-generations} option}). Because
5020 the Git commit ID shown above unambiguously refers to a snapshot of Guix, this
5021 information is all it takes to describe the revision of Guix you're using, and
5022 also to replicate it.
5024 To make it easier to replicate Guix, @command{guix describe} can also be asked
5025 to return a list of channels instead of the human-readable description above:
5028 $ guix describe -f channels
5031 (url "https://git.savannah.gnu.org/git/guix.git")
5033 "e0fa68c7718fffd33d81af415279d6ddb518f727")
5035 (make-channel-introduction
5036 "9edb3f66fd807b096b48283debdcddccfea34bad"
5037 (openpgp-fingerprint
5038 "BBB0 2DDF 2CEA F6A8 0D1D E643 A2A0 6DF2 A33A 54FA")))))
5042 You can save this to a file and feed it to @command{guix pull -C} on some
5043 other machine or at a later point in time, which will instantiate @emph{this
5044 exact Guix revision} (@pxref{Invoking guix pull, the @option{-C} option}).
5045 From there on, since you're able to deploy the same revision of Guix, you can
5046 just as well @emph{replicate a complete software environment}. We humbly
5047 think that this is @emph{awesome}, and we hope you'll like it too!
5049 The details of the options supported by @command{guix describe} are as
5053 @item --format=@var{format}
5054 @itemx -f @var{format}
5055 Produce output in the specified @var{format}, one of:
5059 produce human-readable output;
5061 produce a list of channel specifications that can be passed to @command{guix
5062 pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Invoking
5064 @item channels-sans-intro
5065 like @code{channels}, but omit the @code{introduction} field; use it to
5066 produce a channel specification suitable for Guix version 1.1.0 or
5067 earlier---the @code{introduction} field has to do with channel
5068 authentication (@pxref{Channels, Channel Authentication}) and is not
5069 supported by these older versions;
5072 produce a list of channel specifications in JSON format;
5074 produce a list of channel specifications in Recutils format.
5077 @item --list-formats
5078 Display available formats for @option{--format} option.
5080 @item --profile=@var{profile}
5081 @itemx -p @var{profile}
5082 Display information about @var{profile}.
5085 @node Invoking guix archive
5086 @section Invoking @command{guix archive}
5088 @cindex @command{guix archive}
5090 @cindex exporting files from the store
5091 @cindex importing files to the store
5092 The @command{guix archive} command allows users to @dfn{export} files
5093 from the store into a single archive, and to later @dfn{import} them on
5094 a machine that runs Guix.
5095 In particular, it allows store files to be transferred from one machine
5096 to the store on another machine.
5099 If you're looking for a way to produce archives in a format suitable for
5100 tools other than Guix, @pxref{Invoking guix pack}.
5103 @cindex exporting store items
5104 To export store files as an archive to standard output, run:
5107 guix archive --export @var{options} @var{specifications}...
5110 @var{specifications} may be either store file names or package
5111 specifications, as for @command{guix package} (@pxref{Invoking guix
5112 package}). For instance, the following command creates an archive
5113 containing the @code{gui} output of the @code{git} package and the main
5114 output of @code{emacs}:
5117 guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
5120 If the specified packages are not built yet, @command{guix archive}
5121 automatically builds them. The build process may be controlled with the
5122 common build options (@pxref{Common Build Options}).
5124 To transfer the @code{emacs} package to a machine connected over SSH,
5128 guix archive --export -r emacs | ssh the-machine guix archive --import
5132 Similarly, a complete user profile may be transferred from one machine
5133 to another like this:
5136 guix archive --export -r $(readlink -f ~/.guix-profile) | \
5137 ssh the-machine guix archive --import
5141 However, note that, in both examples, all of @code{emacs} and the
5142 profile as well as all of their dependencies are transferred (due to
5143 @option{-r}), regardless of what is already available in the store on
5144 the target machine. The @option{--missing} option can help figure out
5145 which items are missing from the target store. The @command{guix copy}
5146 command simplifies and optimizes this whole process, so this is probably
5147 what you should use in this case (@pxref{Invoking guix copy}).
5149 @cindex nar, archive format
5150 @cindex normalized archive (nar)
5151 @cindex nar bundle, archive format
5152 Each store item is written in the @dfn{normalized archive} or @dfn{nar}
5153 format (described below), and the output of @command{guix archive
5154 --export} (and input of @command{guix archive --import}) is a @dfn{nar
5158 comparable in spirit to `tar', but with differences
5159 that make it more appropriate for our purposes. First, rather than
5160 recording all Unix metadata for each file, the nar format only mentions
5161 the file type (regular, directory, or symbolic link); Unix permissions
5162 and owner/group are dismissed. Second, the order in which directory
5163 entries are stored always follows the order of file names according to
5164 the C locale collation order. This makes archive production fully
5167 That nar bundle format is essentially the concatenation of zero or more
5168 nars along with metadata for each store item it contains: its file name,
5169 references, corresponding derivation, and a digital signature.
5171 When exporting, the daemon digitally signs the contents of the archive,
5172 and that digital signature is appended. When importing, the daemon
5173 verifies the signature and rejects the import in case of an invalid
5174 signature or if the signing key is not authorized.
5175 @c FIXME: Add xref to daemon doc about signatures.
5177 The main options are:
5181 Export the specified store files or packages (see below). Write the
5182 resulting archive to the standard output.
5184 Dependencies are @emph{not} included in the output, unless
5185 @option{--recursive} is passed.
5189 When combined with @option{--export}, this instructs @command{guix archive}
5190 to include dependencies of the given items in the archive. Thus, the
5191 resulting archive is self-contained: it contains the closure of the
5192 exported store items.
5195 Read an archive from the standard input, and import the files listed
5196 therein into the store. Abort if the archive has an invalid digital
5197 signature, or if it is signed by a public key not among the authorized
5198 keys (see @option{--authorize} below).
5201 Read a list of store file names from the standard input, one per line,
5202 and write on the standard output the subset of these files missing from
5205 @item --generate-key[=@var{parameters}]
5206 @cindex signing, archives
5207 Generate a new key pair for the daemon. This is a prerequisite before
5208 archives can be exported with @option{--export}. This
5209 operation is usually instantaneous but it can take time if the system's
5210 entropy pool needs to be refilled. On Guix System,
5211 @code{guix-service-type} takes care of generating this key pair the
5214 The generated key pair is typically stored under @file{/etc/guix}, in
5215 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private
5216 key, which must be kept secret). When @var{parameters} is omitted,
5217 an ECDSA key using the Ed25519 curve is generated, or, for Libgcrypt
5218 versions before 1.6.0, it is a 4096-bit RSA key.
5219 Alternatively, @var{parameters} can specify
5220 @code{genkey} parameters suitable for Libgcrypt (@pxref{General
5221 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The
5222 Libgcrypt Reference Manual}).
5225 @cindex authorizing, archives
5226 Authorize imports signed by the public key passed on standard input.
5227 The public key must be in ``s-expression advanced format''---i.e., the
5228 same format as the @file{signing-key.pub} file.
5230 The list of authorized keys is kept in the human-editable file
5231 @file{/etc/guix/acl}. The file contains
5232 @url{https://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
5233 s-expressions''} and is structured as an access-control list in the
5234 @url{https://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
5237 @item --extract=@var{directory}
5238 @itemx -x @var{directory}
5239 Read a single-item archive as served by substitute servers
5240 (@pxref{Substitutes}) and extract it to @var{directory}. This is a
5241 low-level operation needed in only very narrow use cases; see below.
5243 For example, the following command extracts the substitute for Emacs
5244 served by @code{@value{SUBSTITUTE-SERVER-1}} to @file{/tmp/emacs}:
5248 https://@value{SUBSTITUTE-SERVER-1}/nar/gzip/@dots{}-emacs-24.5 \
5249 | gunzip | guix archive -x /tmp/emacs
5252 Single-item archives are different from multiple-item archives produced
5253 by @command{guix archive --export}; they contain a single store item,
5254 and they do @emph{not} embed a signature. Thus this operation does
5255 @emph{no} signature verification and its output should be considered
5258 The primary purpose of this operation is to facilitate inspection of
5259 archive contents coming from possibly untrusted substitute servers
5260 (@pxref{Invoking guix challenge}).
5264 Read a single-item archive as served by substitute servers
5265 (@pxref{Substitutes}) and print the list of files it contains, as in
5270 https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-emacs-26.3 \
5271 | lzip -d | guix archive -t
5276 @c *********************************************************************
5281 @cindex @file{channels.scm}, configuration file
5282 @cindex configuration file for channels
5283 @cindex @command{guix pull}, configuration file
5284 @cindex configuration of @command{guix pull}
5285 Guix and its package collection are updated by running @command{guix pull}
5286 (@pxref{Invoking guix pull}). By default @command{guix pull} downloads and
5287 deploys Guix itself from the official GNU@tie{}Guix repository. This can be
5288 customized by defining @dfn{channels} in the
5289 @file{~/.config/guix/channels.scm} file. A channel specifies a URL and branch
5290 of a Git repository to be deployed, and @command{guix pull} can be instructed
5291 to pull from one or more channels. In other words, channels can be used
5292 to @emph{customize} and to @emph{extend} Guix, as we will see below.
5293 Guix is able to take into account security concerns and deal with authenticated
5297 * Specifying Additional Channels:: Extending the package collection.
5298 * Using a Custom Guix Channel:: Using a customized Guix.
5299 * Replicating Guix:: Running the @emph{exact same} Guix.
5300 * Channel Authentication:: How Guix verifies what it fetches.
5301 * Channels with Substitutes:: Using channels with available substitutes.
5302 * Creating a Channel:: How to write your custom channel.
5303 * Package Modules in a Sub-directory:: Specifying the channel's package modules location.
5304 * Declaring Channel Dependencies:: How to depend on other channels.
5305 * Specifying Channel Authorizations:: Defining channel authors authorizations.
5306 * Primary URL:: Distinguishing mirror to original.
5307 * Writing Channel News:: Communicating information to channel's users.
5310 @node Specifying Additional Channels
5311 @section Specifying Additional Channels
5313 @cindex extending the package collection (channels)
5314 @cindex variant packages (channels)
5315 You can specify @emph{additional channels} to pull from. To use a channel, write
5316 @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to pull from it
5317 @emph{in addition} to the default Guix channel(s):
5319 @vindex %default-channels
5321 ;; Add variant packages to those Guix provides.
5323 (name 'variant-packages)
5324 (url "https://example.org/variant-packages.git"))
5329 Note that the snippet above is (as always!)@: Scheme code; we use @code{cons} to
5330 add a channel the list of channels that the variable @code{%default-channels}
5331 is bound to (@pxref{Pairs, @code{cons} and lists,, guile, GNU Guile Reference
5332 Manual}). With this file in place, @command{guix pull} builds not only Guix
5333 but also the package modules from your own repository. The result in
5334 @file{~/.config/guix/current} is the union of Guix with your own package
5339 Generation 19 Aug 27 2018 16:20:48
5341 repository URL: https://git.savannah.gnu.org/git/guix.git
5343 commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
5344 variant-packages dd3df5e
5345 repository URL: https://example.org/variant-packages.git
5347 commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
5351 The output of @command{guix describe} above shows that we're now running
5352 Generation@tie{}19 and that it includes
5353 both Guix and packages from the @code{variant-personal-packages} channel
5354 (@pxref{Invoking guix describe}).
5356 @node Using a Custom Guix Channel
5357 @section Using a Custom Guix Channel
5359 The channel called @code{guix} specifies where Guix itself---its command-line
5360 tools as well as its package collection---should be downloaded. For instance,
5361 suppose you want to update from another copy of the Guix repository at
5362 @code{example.org}, and specifically the @code{super-hacks} branch, you can
5363 write in @code{~/.config/guix/channels.scm} this specification:
5366 ;; Tell 'guix pull' to use another repo.
5369 (url "https://example.org/another-guix.git")
5370 (branch "super-hacks")))
5374 From there on, @command{guix pull} will fetch code from the @code{super-hacks}
5375 branch of the repository at @code{example.org}. The authentication concern is
5376 addressed below (@pxref{Channel Authentication}).
5378 @node Replicating Guix
5379 @section Replicating Guix
5381 @cindex pinning, channels
5382 @cindex replicating Guix
5383 @cindex reproducibility, of Guix
5384 The @command{guix describe} command shows precisely which commits were
5385 used to build the instance of Guix we're using (@pxref{Invoking guix
5386 describe}). We can replicate this instance on another machine or at a
5387 different point in time by providing a channel specification ``pinned''
5388 to these commits that looks like this:
5391 ;; Deploy specific commits of my channels of interest.
5394 (url "https://git.savannah.gnu.org/git/guix.git")
5395 (commit "6298c3ffd9654d3231a6f25390b056483e8f407c"))
5397 (name 'variant-packages)
5398 (url "https://example.org/variant-packages.git")
5399 (commit "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
5402 To obtain this pinned channel specification, the easiest way is to run
5403 @command{guix describe} and to save its output in the @code{channels}
5404 format in a file, like so:
5407 guix describe -f channels > channels.scm
5410 The resulting @file{channels.scm} file can be passed to the @option{-C}
5411 option of @command{guix pull} (@pxref{Invoking guix pull}) or
5412 @command{guix time-machine} (@pxref{Invoking guix time-machine}), as in
5416 guix time-machine -C channels.scm -- shell python -- python3
5419 Given the @file{channels.scm} file, the command above will always fetch
5420 the @emph{exact same Guix instance}, then use that instance to run the
5421 exact same Python (@pxref{Invoking guix shell}). On any machine, at any
5422 time, it ends up running the exact same binaries, bit for bit.
5425 Pinned channels address a problem similar to ``lock files'' as
5426 implemented by some deployment tools---they let you pin and reproduce a
5427 set of packages. In the case of Guix though, you are effectively
5428 pinning the entire package set as defined at the given channel commits;
5429 in fact, you are pinning all of Guix, including its core modules and
5430 command-line tools. You're also getting strong guarantees that you are,
5431 indeed, obtaining the exact same software.
5433 This gives you super powers, allowing you to track the provenance of binary
5434 artifacts with very fine grain, and to reproduce software environments at
5435 will---some sort of ``meta reproducibility'' capabilities, if you will.
5436 @xref{Inferiors}, for another way to take advantage of these super powers.
5438 @node Channel Authentication
5439 @section Channel Authentication
5441 @anchor{channel-authentication}
5442 @cindex authentication, of channel code
5443 The @command{guix pull} and @command{guix time-machine} commands
5444 @dfn{authenticate} the code retrieved from channels: they make sure each
5445 commit that is fetched is signed by an authorized developer. The goal
5446 is to protect from unauthorized modifications to the channel that would
5447 lead users to run malicious code.
5449 As a user, you must provide a @dfn{channel introduction} in your
5450 channels file so that Guix knows how to authenticate its first commit.
5451 A channel specification, including its introduction, looks something
5456 (name 'some-channel)
5457 (url "https://example.org/some-channel.git")
5459 (make-channel-introduction
5460 "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
5461 (openpgp-fingerprint
5462 "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
5465 The specification above shows the name and URL of the channel. The call
5466 to @code{make-channel-introduction} above specifies that authentication
5467 of this channel starts at commit @code{6f0d8cc@dots{}}, which is signed
5468 by the OpenPGP key with fingerprint @code{CABB A931@dots{}}.
5470 For the main channel, called @code{guix}, you automatically get that
5471 information from your Guix installation. For other channels, include
5472 the channel introduction provided by the channel authors in your
5473 @file{channels.scm} file. Make sure you retrieve the channel
5474 introduction from a trusted source since that is the root of your trust.
5476 If you're curious about the authentication mechanics, read on!
5478 @node Channels with Substitutes
5479 @section Channels with Substitutes
5481 When running @command{guix pull}, Guix will first compile the
5482 definitions of every available package. This is an expensive operation
5483 for which substitutes (@pxref{Substitutes}) may be available. The
5484 following snippet in @file{channels.scm} will ensure that @command{guix
5485 pull} uses the latest commit with available substitutes for the package
5486 definitions: this is done by querying the continuous integration
5487 server at @url{https://ci.guix.gnu.org}.
5490 (use-modules (guix ci))
5492 (list (channel-with-substitutes-available
5493 %default-guix-channel
5494 "https://ci.guix.gnu.org"))
5497 Note that this does not mean that all the packages that you will
5498 install after running @command{guix pull} will have available
5499 substitutes. It only ensures that @command{guix pull} will not try to
5500 compile package definitions. This is particularly useful when using
5501 machines with limited resources.
5503 @node Creating a Channel
5504 @section Creating a Channel
5506 @cindex personal packages (channels)
5507 @cindex channels, for personal packages
5508 Let's say you have a bunch of custom package variants or personal packages
5509 that you think would make little sense to contribute to the Guix project, but
5510 would like to have these packages transparently available to you at the
5511 command line. You would first write modules containing those package
5512 definitions (@pxref{Package Modules}), maintain them in a Git repository, and
5513 then you and anyone else can use it as an additional channel to get packages
5516 @c What follows stems from discussions at
5517 @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
5518 @c earlier discussions on guix-devel@gnu.org.
5520 Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
5521 publish your personal channel to the world, we would like to share a few words
5526 Before publishing a channel, please consider contributing your package
5527 definitions to Guix proper (@pxref{Contributing}). Guix as a project is open
5528 to free software of all sorts, and packages in Guix proper are readily
5529 available to all Guix users and benefit from the project's quality assurance
5533 When you maintain package definitions outside Guix, we, Guix developers,
5534 consider that @emph{the compatibility burden is on you}. Remember that
5535 package modules and package definitions are just Scheme code that uses various
5536 programming interfaces (APIs). We want to remain free to change these APIs to
5537 keep improving Guix, possibly in ways that break your channel. We never
5538 change APIs gratuitously, but we will @emph{not} commit to freezing APIs
5542 Corollary: if you're using an external channel and that channel breaks, please
5543 @emph{report the issue to the channel authors}, not to the Guix project.
5546 You've been warned! Having said this, we believe external channels are a
5547 practical way to exert your freedom to augment Guix' package collection and to
5548 share your improvements, which are basic tenets of
5549 @uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
5550 email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
5553 To create a channel, create a Git repository containing your own package
5554 modules and make it available. The repository can contain anything, but a
5555 useful channel will contain Guile modules that export packages. Once you
5556 start using a channel, Guix will behave as if the root directory of that
5557 channel's Git repository has been added to the Guile load path (@pxref{Load
5558 Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel
5559 contains a file at @file{my-packages/my-tools.scm} that defines a Guile
5560 module, then the module will be available under the name @code{(my-packages
5561 my-tools)}, and you will be able to use it like any other module
5562 (@pxref{Modules,,, guile, GNU Guile Reference Manual}).
5564 As a channel author, consider bundling authentication material with your
5565 channel so that users can authenticate it. @xref{Channel
5566 Authentication}, and @ref{Specifying Channel Authorizations}, for info
5570 @node Package Modules in a Sub-directory
5571 @section Package Modules in a Sub-directory
5573 @cindex subdirectory, channels
5574 As a channel author, you may want to keep your channel modules in a
5575 sub-directory. If your modules are in the sub-directory @file{guix}, you must
5576 add a meta-data file @file{.guix-channel} that contains:
5584 @node Declaring Channel Dependencies
5585 @section Declaring Channel Dependencies
5587 @cindex dependencies, channels
5588 @cindex meta-data, channels
5589 Channel authors may decide to augment a package collection provided by other
5590 channels. They can declare their channel to be dependent on other channels in
5591 a meta-data file @file{.guix-channel}, which is to be placed in the root of
5592 the channel repository.
5594 The meta-data file should contain a simple S-expression like this:
5601 (name some-collection)
5602 (url "https://example.org/first-collection.git")
5604 ;; The 'introduction' bit below is optional: you would
5605 ;; provide it for dependencies that can be authenticated.
5607 (channel-introduction
5609 (commit "a8883b58dc82e167c96506cf05095f37c2c2c6cd")
5610 (signer "CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"))))
5612 (name some-other-collection)
5613 (url "https://example.org/second-collection.git")
5614 (branch "testing"))))
5617 In the above example this channel is declared to depend on two other channels,
5618 which will both be fetched automatically. The modules provided by the channel
5619 will be compiled in an environment where the modules of all these declared
5620 channels are available.
5622 For the sake of reliability and maintainability, you should avoid dependencies
5623 on channels that you don't control, and you should aim to keep the number of
5624 dependencies to a minimum.
5626 @node Specifying Channel Authorizations
5627 @section Specifying Channel Authorizations
5629 @cindex channel authorizations
5630 @anchor{channel-authorizations}
5631 As we saw above, Guix ensures the source code it pulls from channels
5632 comes from authorized developers. As a channel author, you need to
5633 specify the list of authorized developers in the
5634 @file{.guix-authorizations} file in the channel's Git repository. The
5635 authentication rule is simple: each commit must be signed by a key
5636 listed in the @file{.guix-authorizations} file of its parent
5637 commit(s)@footnote{Git commits form a @dfn{directed acyclic graph}
5638 (DAG). Each commit can have zero or more parents; ``regular'' commits
5639 have one parent and merge commits have two parent commits. Read
5640 @uref{https://eagain.net/articles/git-for-computer-scientists/, @i{Git
5641 for Computer Scientists}} for a great overview.} The
5642 @file{.guix-authorizations} file looks like this:
5645 ;; Example '.guix-authorizations' file.
5648 (version 0) ;current file format version
5650 (("AD17 A21E F8AE D8F1 CC02 DBD9 F8AE D8F1 765C 61E3"
5652 ("2A39 3FFF 68F4 EF7A 3D29 12AF 68F4 EF7A 22FB B2D5"
5654 ("CABB A931 C0FF EEC6 900D 0CFB 090B 1199 3D9A EBB5"
5658 Each fingerprint is followed by optional key/value pairs, as in the
5659 example above. Currently these key/value pairs are ignored.
5661 This authentication rule creates a chicken-and-egg issue: how do we
5662 authenticate the first commit? Related to that: how do we deal with
5663 channels whose repository history contains unsigned commits and lack
5664 @file{.guix-authorizations}? And how do we fork existing channels?
5666 @cindex channel introduction
5667 Channel introductions answer these questions by describing the first
5668 commit of a channel that should be authenticated. The first time a
5669 channel is fetched with @command{guix pull} or @command{guix
5670 time-machine}, the command looks up the introductory commit and verifies
5671 that it is signed by the specified OpenPGP key. From then on, it
5672 authenticates commits according to the rule above. Authentication fails
5673 if the target commit is neither a descendant nor an ancestor of the
5674 introductory commit.
5676 Additionally, your channel must provide all the OpenPGP keys that were
5677 ever mentioned in @file{.guix-authorizations}, stored as @file{.key}
5678 files, which can be either binary or ``ASCII-armored''. By default,
5679 those @file{.key} files are searched for in the branch named
5680 @code{keyring} but you can specify a different branch name in
5681 @code{.guix-channel} like so:
5686 (keyring-reference "my-keyring-branch"))
5689 To summarize, as the author of a channel, there are three things you have
5690 to do to allow users to authenticate your code:
5694 Export the OpenPGP keys of past and present committers with @command{gpg
5695 --export} and store them in @file{.key} files, by default in a branch
5696 named @code{keyring} (we recommend making it an @dfn{orphan branch}).
5699 Introduce an initial @file{.guix-authorizations} in the channel's
5700 repository. Do that in a signed commit (@pxref{Commit Access}, for
5701 information on how to sign Git commits.)
5704 Advertise the channel introduction, for instance on your channel's web
5705 page. The channel introduction, as we saw above, is the commit/key
5706 pair---i.e., the commit that introduced @file{.guix-authorizations}, and
5707 the fingerprint of the OpenPGP used to sign it.
5710 Before pushing to your public Git repository, you can run @command{guix
5711 git-authenticate} to verify that you did sign all the commits you are
5712 about to push with an authorized key:
5715 guix git authenticate @var{commit} @var{signer}
5719 where @var{commit} and @var{signer} are your channel introduction.
5720 @xref{Invoking guix git authenticate}, for details.
5722 Publishing a signed channel requires discipline: any mistake, such as an
5723 unsigned commit or a commit signed by an unauthorized key, will prevent
5724 users from pulling from your channel---well, that's the whole point of
5725 authentication! Pay attention to merges in particular: merge commits
5726 are considered authentic if and only if they are signed by a key present
5727 in the @file{.guix-authorizations} file of @emph{both} branches.
5730 @section Primary URL
5732 @cindex primary URL, channels
5733 Channel authors can indicate the primary URL of their channel's Git
5734 repository in the @file{.guix-channel} file, like so:
5739 (url "https://example.org/guix.git"))
5742 This allows @command{guix pull} to determine whether it is pulling code
5743 from a mirror of the channel; when that is the case, it warns the user
5744 that the mirror might be stale and displays the primary URL@. That way,
5745 users cannot be tricked into fetching code from a stale mirror that does
5746 not receive security updates.
5748 This feature only makes sense for authenticated repositories, such as
5749 the official @code{guix} channel, for which @command{guix pull} ensures
5750 the code it fetches is authentic.
5752 @node Writing Channel News
5753 @section Writing Channel News
5755 @cindex news, for channels
5756 Channel authors may occasionally want to communicate to their users
5757 information about important changes in the channel. You'd send them all
5758 an email, but that's not convenient.
5760 Instead, channels can provide a @dfn{news file}; when the channel users
5761 run @command{guix pull}, that news file is automatically read and
5762 @command{guix pull --news} can display the announcements that correspond
5763 to the new commits that have been pulled, if any.
5765 To do that, channel authors must first declare the name of the news file
5766 in their @file{.guix-channel} file:
5771 (news-file "etc/news.txt"))
5774 The news file itself, @file{etc/news.txt} in this example, must look
5775 something like this:
5780 (entry (tag "the-bug-fix")
5781 (title (en "Fixed terrible bug")
5783 (body (en "@@emph@{Good news@}! It's fixed!")
5784 (eo "Certe ĝi pli bone funkcias nun!")))
5785 (entry (commit "bdcabe815cd28144a2d2b4bc3c5057b051fa9906")
5786 (title (en "Added a great package")
5787 (ca "Què vol dir guix?"))
5788 (body (en "Don't miss the @@code@{hello@} package!"))))
5791 While the news file is using the Scheme syntax, avoid naming it with a
5792 @file{.scm} extension or else it will get picked up when building the
5793 channel and yield an error since it is not a valid module.
5794 Alternatively, you can move the channel module to a subdirectory and
5795 store the news file in another directory.
5797 The file consists of a list of @dfn{news entries}. Each entry is
5798 associated with a commit or tag: it describes changes made in this
5799 commit, possibly in preceding commits as well. Users see entries only
5800 the first time they obtain the commit the entry refers to.
5802 The @code{title} field should be a one-line summary while @code{body}
5803 can be arbitrarily long, and both can contain Texinfo markup
5804 (@pxref{Overview,,, texinfo, GNU Texinfo}). Both the title and body are
5805 a list of language tag/message tuples, which allows @command{guix pull}
5806 to display news in the language that corresponds to the user's locale.
5808 If you want to translate news using a gettext-based workflow, you can
5809 extract translatable strings with @command{xgettext} (@pxref{xgettext
5810 Invocation,,, gettext, GNU Gettext Utilities}). For example, assuming
5811 you write news entries in English first, the command below creates a PO
5812 file containing the strings to translate:
5815 xgettext -o news.po -l scheme -ken etc/news.txt
5818 To sum up, yes, you could use your channel as a blog. But beware, this
5819 is @emph{not quite} what your users might expect.
5821 @c *********************************************************************
5823 @chapter Development
5825 @cindex software development
5826 If you are a software developer, Guix provides tools that you should find
5827 helpful---independently of the language you're developing in. This is what
5828 this chapter is about.
5830 The @command{guix shell} command provides a convenient way to set up
5831 one-off software environments, be it for development purposes or to run
5832 a command without installing it in your profile. The @command{guix
5833 pack} command allows you to create @dfn{application bundles} that can be
5834 easily distributed to users who do not run Guix.
5837 * Invoking guix shell:: Spawning one-off software environments.
5838 * Invoking guix environment:: Setting up development environments.
5839 * Invoking guix pack:: Creating software bundles.
5840 * The GCC toolchain:: Working with languages supported by GCC.
5841 * Invoking guix git authenticate:: Authenticating Git repositories.
5844 @node Invoking guix shell
5845 @section Invoking @command{guix shell}
5847 @cindex reproducible build environments
5848 @cindex development environments
5849 @cindex @command{guix environment}
5850 @cindex @command{guix shell}
5851 @cindex environment, package build environment
5852 The purpose of @command{guix shell} is to make it easy to create one-off
5853 software environments, without changing one's profile. It is typically
5854 used to create development environments; it is also a convenient way to
5855 run applications without ``polluting'' your profile.
5858 The @command{guix shell} command was recently introduced to supersede
5859 @command{guix environment} (@pxref{Invoking guix environment}). If you
5860 are familiar with @command{guix environment}, you will notice that it is
5861 similar but also---we hope!---more convenient.
5864 The general syntax is:
5867 guix shell [@var{options}] [@var{package}@dots{}]
5870 The following example creates an environment containing Python and NumPy,
5871 building or downloading any missing package, and runs the
5872 @command{python3} command in that environment:
5875 guix shell python python-numpy -- python3
5878 Development environments can be created as in the example below, which
5879 spawns an interactive shell containing all the dependencies and
5880 environment variables needed to work on Inkscape:
5883 guix shell --development inkscape
5886 Exiting the shell places the user back in the original environment
5887 before @command{guix shell} was invoked. The next garbage collection
5888 (@pxref{Invoking guix gc}) may clean up packages that were installed in
5889 the environment and that are no longer used outside of it.
5891 As an added convenience, @command{guix shell} will try to do what you
5892 mean when it is invoked interactively without any other arguments
5899 If it finds a @file{manifest.scm} in the current working directory or
5900 any of its parents, it uses this manifest as though it was given via @code{--manifest}.
5901 Likewise, if it finds a @file{guix.scm} in the same directories, it uses
5902 it to build a development profile as though both @code{--development}
5903 and @code{--file} were present.
5904 In either case, the file will only be loaded if the directory it
5905 resides in is listed in
5906 @file{~/.config/guix/shell-authorized-directories}.
5907 This provides an easy way to define, share, and enter development
5910 By default, the shell session or command runs in an @emph{augmented}
5911 environment, where the new packages are added to search path environment
5912 variables such as @code{PATH}. You can, instead, choose to create an
5913 @emph{isolated} environment containing nothing but the packages you
5914 asked for. Passing the @option{--pure} option clears environment
5915 variable definitions found in the parent environment@footnote{Be sure to
5916 use the @option{--check} option the first time you use @command{guix
5917 shell} interactively to make sure the shell does not undo the effect of
5918 @option{--pure}.}; passing @option{--container} goes one step further by
5919 spawning a @dfn{container} isolated from the rest of the system:
5922 guix shell --container emacs gcc-toolchain
5925 The command above spawns an interactive shell in a container where
5926 nothing but @code{emacs}, @code{gcc-toolchain}, and their dependencies
5927 is available. The container lacks network access and shares no files
5928 other than the current working directory with the surrounding
5929 environment. This is useful to prevent access to system-wide resources
5930 such as @file{/usr/bin} on foreign distros.
5932 This @option{--container} option can also prove useful if you wish to
5933 run a security-sensitive application, such as a web browser, in an
5934 isolated environment. For example, the command below launches
5935 Ungoogled-Chromium in an isolated environment, this time sharing network
5936 access with the host and preserving its @code{DISPLAY} environment
5937 variable, but without even sharing the current directory:
5940 guix shell --container --network --no-cwd ungoogled-chromium \
5941 --preserve='^DISPLAY$' -- chromium
5944 @vindex GUIX_ENVIRONMENT
5945 @command{guix shell} defines the @env{GUIX_ENVIRONMENT}
5946 variable in the shell it spawns; its value is the file name of the
5947 profile of this environment. This allows users to, say, define a
5948 specific prompt for development environments in their @file{.bashrc}
5949 (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
5952 if [ -n "$GUIX_ENVIRONMENT" ]
5954 export PS1="\u@@\h \w [dev]\$ "
5959 ...@: or to browse the profile:
5962 $ ls "$GUIX_ENVIRONMENT/bin"
5965 The available options are summarized below.
5969 Set up the environment and check whether the shell would clobber
5970 environment variables. It's a good idea to use this option the first
5971 time you run @command{guix shell} for an interactive session to make
5972 sure your setup is correct.
5974 For example, if the shell modifies the @env{PATH} environment variable,
5975 report it since you would get a different environment than what you
5978 Such problems usually indicate that the shell startup files are
5979 unexpectedly modifying those environment variables. For example, if you
5980 are using Bash, make sure that environment variables are set or modified
5981 in @file{~/.bash_profile} and @emph{not} in @file{~/.bashrc}---the
5982 former is sourced only by log-in shells. @xref{Bash Startup Files,,,
5983 bash, The GNU Bash Reference Manual}, for details on Bash start-up
5986 @anchor{shell-development-option}
5989 Cause @command{guix shell} to include in the environment the
5990 dependencies of the following package rather than the package itself.
5991 This can be combined with other packages. For instance, the command
5992 below starts an interactive shell containing the build-time dependencies
5993 of GNU@tie{}Guile, plus Autoconf, Automake, and Libtool:
5996 guix shell -D guile autoconf automake libtool
5999 @item --expression=@var{expr}
6000 @itemx -e @var{expr}
6001 Create an environment for the package or list of packages that
6002 @var{expr} evaluates to.
6004 For example, running:
6007 guix shell -D -e '(@@ (gnu packages maths) petsc-openmpi)'
6010 starts a shell with the environment for this specific variant of the
6016 guix shell -e '(@@ (gnu) %base-packages)'
6019 starts a shell with all the base system packages available.
6021 The above commands only use the default output of the given packages.
6022 To select other outputs, two element tuples can be specified:
6025 guix shell -e '(list (@@ (gnu packages bash) bash) "include")'
6028 @xref{package-development-manifest,
6029 @code{package->development-manifest}}, for information on how to write a
6030 manifest for the development environment of a package.
6032 @item --file=@var{file}
6033 @itemx -f @var{file}
6034 Create an environment containing the package or list of packages that
6035 the code within @var{file} evaluates to.
6037 As an example, @var{file} might contain a definition like this
6038 (@pxref{Defining Packages}):
6041 @verbatiminclude environment-gdb.scm
6044 With the file above, you can enter a development environment for GDB by
6048 guix shell -D -f gdb-devel.scm
6051 @anchor{shell-manifest}
6052 @item --manifest=@var{file}
6053 @itemx -m @var{file}
6054 Create an environment for the packages contained in the manifest object
6055 returned by the Scheme code in @var{file}. This option can be repeated
6056 several times, in which case the manifests are concatenated.
6058 This is similar to the same-named option in @command{guix package}
6059 (@pxref{profile-manifest, @option{--manifest}}) and uses the same
6062 @xref{Writing Manifests}, for information on how to write a manifest.
6063 See @option{--export-manifest} below on how to obtain a first manifest.
6065 @cindex manifest, exporting
6066 @anchor{shell-export-manifest}
6067 @item --export-manifest
6068 Write to standard output a manifest suitable for @option{--manifest}
6069 corresponding to given command-line options.
6071 This is a way to ``convert'' command-line arguments into a manifest.
6072 For example, imagine you are tired of typing long lines and would like
6073 to get a manifest equivalent to this command line:
6076 guix shell -D guile git emacs emacs-geiser emacs-geiser-guile
6079 Just add @option{--export-manifest} to the command line above:
6082 guix shell --export-manifest \
6083 -D guile git emacs emacs-geiser emacs-geiser-guile
6087 ... and you get a manifest along these lines:
6090 (concatenate-manifests
6091 (list (specifications->manifest
6095 "emacs-geiser-guile"))
6096 (package->development-manifest
6097 (specification->package "guile"))))
6100 You can store it into a file, say @file{manifest.scm}, and from there
6101 pass it to @command{guix shell} or indeed pretty much any @command{guix}
6105 guix shell -m manifest.scm
6108 Voilà, you've converted a long command line into a manifest! That
6109 conversion process honors package transformation options (@pxref{Package
6110 Transformation Options}) so it should be lossless.
6112 @item --profile=@var{profile}
6113 @itemx -p @var{profile}
6114 Create an environment containing the packages installed in @var{profile}.
6115 Use @command{guix package} (@pxref{Invoking guix package}) to create
6116 and manage profiles.
6119 Unset existing environment variables when building the new environment, except
6120 those specified with @option{--preserve} (see below). This has the effect of
6121 creating an environment in which search paths only contain package inputs.
6123 @item --preserve=@var{regexp}
6124 @itemx -E @var{regexp}
6125 When used alongside @option{--pure}, preserve the environment variables
6126 matching @var{regexp}---in other words, put them on a ``white list'' of
6127 environment variables that must be preserved. This option can be repeated
6131 guix shell --pure --preserve=^SLURM openmpi @dots{} \
6135 This example runs @command{mpirun} in a context where the only environment
6136 variables defined are @env{PATH}, environment variables whose name starts
6137 with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
6140 @item --search-paths
6141 Display the environment variable definitions that make up the
6144 @item --system=@var{system}
6145 @itemx -s @var{system}
6146 Attempt to build for @var{system}---e.g., @code{i686-linux}.
6151 Run @var{command} within an isolated container. The current working
6152 directory outside the container is mapped inside the container.
6153 Additionally, unless overridden with @option{--user}, a dummy home
6154 directory is created that matches the current user's home directory, and
6155 @file{/etc/passwd} is configured accordingly.
6157 The spawned process runs as the current user outside the container. Inside
6158 the container, it has the same UID and GID as the current user, unless
6159 @option{--user} is passed (see below).
6163 For containers, share the network namespace with the host system.
6164 Containers created without this flag only have access to the loopback
6167 @item --link-profile
6169 For containers, link the environment profile to @file{~/.guix-profile}
6170 within the container and set @code{GUIX_ENVIRONMENT} to that.
6171 This is equivalent to making @file{~/.guix-profile} a symlink to the
6172 actual profile within the container.
6173 Linking will fail and abort the environment if the directory already
6174 exists, which will certainly be the case if @command{guix shell}
6175 was invoked in the user's home directory.
6177 Certain packages are configured to look in @file{~/.guix-profile} for
6178 configuration files and data;@footnote{For example, the
6179 @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
6180 for additional fonts.} @option{--link-profile} allows these programs to
6181 behave as expected within the environment.
6183 @item --user=@var{user}
6184 @itemx -u @var{user}
6185 For containers, use the username @var{user} in place of the current
6186 user. The generated @file{/etc/passwd} entry within the container will
6187 contain the name @var{user}, the home directory will be
6188 @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
6189 the UID and GID inside the container are 1000. @var{user}
6190 need not exist on the system.
6192 Additionally, any shared or exposed path (see @option{--share} and
6193 @option{--expose} respectively) whose target is within the current user's
6194 home directory will be remapped relative to @file{/home/USER}; this
6195 includes the automatic mapping of the current working directory.
6198 # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
6200 guix shell --container --user=foo \
6201 --expose=$HOME/test \
6202 --expose=/tmp/target=$HOME/target
6205 While this will limit the leaking of user identity through home paths
6206 and each of the user fields, this is only one useful component of a
6207 broader privacy/anonymity solution---not one in and of itself.
6210 For containers, the default behavior is to share the current working
6211 directory with the isolated container and immediately change to that
6212 directory within the container. If this is undesirable,
6213 @option{--no-cwd} will cause the current working directory to @emph{not}
6214 be automatically shared and will change to the user's home directory
6215 within the container instead. See also @option{--user}.
6217 @item --expose=@var{source}[=@var{target}]
6218 @itemx --share=@var{source}[=@var{target}]
6219 For containers, @option{--expose} (resp. @option{--share}) exposes the
6220 file system @var{source} from the host system as the read-only
6221 (resp. writable) file system @var{target} within the container. If
6222 @var{target} is not specified, @var{source} is used as the target mount
6223 point in the container.
6225 The example below spawns a Guile REPL in a container in which the user's
6226 home directory is accessible read-only via the @file{/exchange}
6230 guix shell --container --expose=$HOME=/exchange guile -- guile
6233 @cindex file system hierarchy standard (FHS)
6234 @cindex FHS (file system hierarchy standard)
6237 When used with @option{--container}, emulate a
6238 @uref{https://refspecs.linuxfoundation.org/fhs.shtml, Filesystem
6239 Hierarchy Standard (FHS)} configuration within the container, providing
6240 @file{/bin}, @file{/lib}, and other directories and files specified by
6243 As Guix deviates from the FHS specification, this
6244 option sets up the container to more closely mimic that of other
6245 GNU/Linux distributions. This is useful for reproducing other
6246 development environments, testing, and using programs which expect the
6247 FHS specification to be followed. With this option, the container will
6248 include a version of glibc that will read
6249 @file{/etc/ld.so.cache} within the container for the shared library
6250 cache (contrary to glibc in regular Guix usage) and set up the
6251 expected FHS directories: @file{/bin}, @file{/etc}, @file{/lib}, and
6252 @file{/usr} from the container's profile.
6254 @item --rebuild-cache
6255 @cindex caching, of profiles
6256 @cindex caching, in @command{guix shell}
6257 In most cases, @command{guix shell} caches the environment so that
6258 subsequent uses are instantaneous. Least-recently used cache entries
6259 are periodically removed. The cache is also invalidated, when using
6260 @option{--file} or @option{--manifest}, anytime the corresponding file
6263 The @option{--rebuild-cache} forces the cached environment to be
6264 refreshed. This is useful when using @option{--file} or
6265 @option{--manifest} and the @command{guix.scm} or @command{manifest.scm}
6266 file has external dependencies, or if its behavior depends, say, on
6267 environment variables.
6269 @item --root=@var{file}
6270 @itemx -r @var{file}
6271 @cindex persistent environment
6272 @cindex garbage collector root, for environments
6273 Make @var{file} a symlink to the profile for this environment, and
6274 register it as a garbage collector root.
6276 This is useful if you want to protect your environment from garbage
6277 collection, to make it ``persistent''.
6279 When this option is omitted, @command{guix shell} caches profiles so
6280 that subsequent uses of the same environment are instantaneous---this is
6281 comparable to using @option{--root} except that @command{guix shell}
6282 takes care of periodically removing the least-recently used garbage
6285 In some cases, @command{guix shell} does not cache profiles---e.g., if
6286 transformation options such as @option{--with-latest} are used. In
6287 those cases, the environment is protected from garbage collection only
6288 for the duration of the @command{guix shell} session. This means that
6289 next time you recreate the same environment, you could have to rebuild
6290 or re-download packages.
6292 @xref{Invoking guix gc}, for more on GC roots.
6295 @command{guix shell} also supports all of the common build options that
6296 @command{guix build} supports (@pxref{Common Build Options}) as well as
6297 package transformation options (@pxref{Package Transformation Options}).
6299 @node Invoking guix environment
6300 @section Invoking @command{guix environment}
6302 @cindex @command{guix environment}
6304 The purpose of @command{guix environment} is to assist in creating
6305 development environments.
6307 @quotation Deprecation warning
6308 The @command{guix environment} command is deprecated in favor of
6309 @command{guix shell}, which performs similar functions but is more
6310 convenient to use. @xref{Invoking guix shell}.
6312 Being deprecated, @command{guix environment} is slated for eventual
6313 removal, but the Guix project is committed to keeping it until May 1st,
6314 2023. Please get in touch with us at @email{guix-devel@@gnu.org} if you
6315 would like to discuss it.
6318 The general syntax is:
6321 guix environment @var{options} @var{package}@dots{}
6324 The following example spawns a new shell set up for the development of
6328 guix environment guile
6331 If the needed dependencies are not built yet, @command{guix environment}
6332 automatically builds them. The environment of the new shell is an
6333 augmented version of the environment that @command{guix environment} was
6334 run in. It contains the necessary search paths for building the given
6335 package added to the existing environment variables. To create
6336 a ``pure'' environment, in which the original environment variables have
6337 been unset, use the @option{--pure} option@footnote{Users sometimes
6338 wrongfully augment environment variables such as @env{PATH} in their
6339 @file{~/.bashrc} file. As a consequence, when @command{guix
6340 environment} launches it, Bash may read @file{~/.bashrc}, thereby
6341 introducing ``impurities'' in these environment variables. It is an
6342 error to define such environment variables in @file{.bashrc}; instead,
6343 they should be defined in @file{.bash_profile}, which is sourced only by
6344 log-in shells. @xref{Bash Startup Files,,, bash, The GNU Bash Reference
6345 Manual}, for details on Bash start-up files.}.
6347 Exiting from a Guix environment is the same as exiting from the shell,
6348 and will place the user back in the old environment before @command{guix
6349 environment} was invoked. The next garbage collection (@pxref{Invoking
6350 guix gc}) will clean up packages that were installed from within the
6351 environment and are no longer used outside of it.
6353 @vindex GUIX_ENVIRONMENT
6354 @command{guix environment} defines the @env{GUIX_ENVIRONMENT}
6355 variable in the shell it spawns; its value is the file name of the
6356 profile of this environment. This allows users to, say, define a
6357 specific prompt for development environments in their @file{.bashrc}
6358 (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference Manual}):
6361 if [ -n "$GUIX_ENVIRONMENT" ]
6363 export PS1="\u@@\h \w [dev]\$ "
6368 ...@: or to browse the profile:
6371 $ ls "$GUIX_ENVIRONMENT/bin"
6374 Additionally, more than one package may be specified, in which case the
6375 union of the inputs for the given packages are used. For example, the
6376 command below spawns a shell where all of the dependencies of both Guile
6377 and Emacs are available:
6380 guix environment guile emacs
6383 Sometimes an interactive shell session is not desired. An arbitrary
6384 command may be invoked by placing the @code{--} token to separate the
6385 command from the rest of the arguments:
6388 guix environment guile -- make -j4
6391 In other situations, it is more convenient to specify the list of
6392 packages needed in the environment. For example, the following command
6393 runs @command{python} from an environment containing Python@tie{}3 and
6397 guix environment --ad-hoc python-numpy python -- python3
6400 Furthermore, one might want the dependencies of a package and also some
6401 additional packages that are not build-time or runtime dependencies, but
6402 are useful when developing nonetheless. Because of this, the
6403 @option{--ad-hoc} flag is positional. Packages appearing before
6404 @option{--ad-hoc} are interpreted as packages whose dependencies will be
6405 added to the environment. Packages appearing after are interpreted as
6406 packages that will be added to the environment directly. For example,
6407 the following command creates a Guix development environment that
6408 additionally includes Git and strace:
6411 guix environment --pure guix --ad-hoc git strace
6415 Sometimes it is desirable to isolate the environment as much as
6416 possible, for maximal purity and reproducibility. In particular, when
6417 using Guix on a host distro that is not Guix System, it is desirable to
6418 prevent access to @file{/usr/bin} and other system-wide resources from
6419 the development environment. For example, the following command spawns
6420 a Guile REPL in a ``container'' where only the store and the current
6421 working directory are mounted:
6424 guix environment --ad-hoc --container guile -- guile
6428 The @option{--container} option requires Linux-libre 3.19 or newer.
6431 @cindex certificates
6432 Another typical use case for containers is to run security-sensitive
6433 applications such as a web browser. To run Eolie, we must expose and
6434 share some files and directories; we include @code{nss-certs} and expose
6435 @file{/etc/ssl/certs/} for HTTPS authentication; finally we preserve the
6436 @env{DISPLAY} environment variable since containerized graphical
6437 applications won't display without it.
6440 guix environment --preserve='^DISPLAY$' --container --network \
6441 --expose=/etc/machine-id \
6442 --expose=/etc/ssl/certs/ \
6443 --share=$HOME/.local/share/eolie/=$HOME/.local/share/eolie/ \
6444 --ad-hoc eolie nss-certs dbus -- eolie
6447 The available options are summarized below.
6451 Set up the environment and check whether the shell would clobber
6452 environment variables. @xref{Invoking guix shell, @option{--check}},
6455 @item --root=@var{file}
6456 @itemx -r @var{file}
6457 @cindex persistent environment
6458 @cindex garbage collector root, for environments
6459 Make @var{file} a symlink to the profile for this environment, and
6460 register it as a garbage collector root.
6462 This is useful if you want to protect your environment from garbage
6463 collection, to make it ``persistent''.
6465 When this option is omitted, the environment is protected from garbage
6466 collection only for the duration of the @command{guix environment}
6467 session. This means that next time you recreate the same environment,
6468 you could have to rebuild or re-download packages. @xref{Invoking guix
6469 gc}, for more on GC roots.
6471 @item --expression=@var{expr}
6472 @itemx -e @var{expr}
6473 Create an environment for the package or list of packages that
6474 @var{expr} evaluates to.
6476 For example, running:
6479 guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
6482 starts a shell with the environment for this specific variant of the
6488 guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
6491 starts a shell with all the base system packages available.
6493 The above commands only use the default output of the given packages.
6494 To select other outputs, two element tuples can be specified:
6497 guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
6500 @item --load=@var{file}
6501 @itemx -l @var{file}
6502 Create an environment for the package or list of packages that the code
6503 within @var{file} evaluates to.
6505 As an example, @var{file} might contain a definition like this
6506 (@pxref{Defining Packages}):
6509 @verbatiminclude environment-gdb.scm
6512 @item --manifest=@var{file}
6513 @itemx -m @var{file}
6514 Create an environment for the packages contained in the manifest object
6515 returned by the Scheme code in @var{file}. This option can be repeated
6516 several times, in which case the manifests are concatenated.
6518 This is similar to the same-named option in @command{guix package}
6519 (@pxref{profile-manifest, @option{--manifest}}) and uses the same
6522 @xref{shell-export-manifest, @command{guix shell --export-manifest}},
6523 for information on how to ``convert'' command-line options into a
6527 Include all specified packages in the resulting environment, as if an
6528 @i{ad hoc} package were defined with them as inputs. This option is
6529 useful for quickly creating an environment without having to write a
6530 package expression to contain the desired inputs.
6532 For instance, the command:
6535 guix environment --ad-hoc guile guile-sdl -- guile
6538 runs @command{guile} in an environment where Guile and Guile-SDL are
6541 Note that this example implicitly asks for the default output of
6542 @code{guile} and @code{guile-sdl}, but it is possible to ask for a
6543 specific output---e.g., @code{glib:bin} asks for the @code{bin} output
6544 of @code{glib} (@pxref{Packages with Multiple Outputs}).
6546 This option may be composed with the default behavior of @command{guix
6547 environment}. Packages appearing before @option{--ad-hoc} are
6548 interpreted as packages whose dependencies will be added to the
6549 environment, the default behavior. Packages appearing after are
6550 interpreted as packages that will be added to the environment directly.
6552 @item --profile=@var{profile}
6553 @itemx -p @var{profile}
6554 Create an environment containing the packages installed in @var{profile}.
6555 Use @command{guix package} (@pxref{Invoking guix package}) to create
6556 and manage profiles.
6559 Unset existing environment variables when building the new environment, except
6560 those specified with @option{--preserve} (see below). This has the effect of
6561 creating an environment in which search paths only contain package inputs.
6563 @item --preserve=@var{regexp}
6564 @itemx -E @var{regexp}
6565 When used alongside @option{--pure}, preserve the environment variables
6566 matching @var{regexp}---in other words, put them on a ``white list'' of
6567 environment variables that must be preserved. This option can be repeated
6571 guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \
6575 This example runs @command{mpirun} in a context where the only environment
6576 variables defined are @env{PATH}, environment variables whose name starts
6577 with @samp{SLURM}, as well as the usual ``precious'' variables (@env{HOME},
6580 @item --search-paths
6581 Display the environment variable definitions that make up the
6584 @item --system=@var{system}
6585 @itemx -s @var{system}
6586 Attempt to build for @var{system}---e.g., @code{i686-linux}.
6591 Run @var{command} within an isolated container. The current working
6592 directory outside the container is mapped inside the container.
6593 Additionally, unless overridden with @option{--user}, a dummy home
6594 directory is created that matches the current user's home directory, and
6595 @file{/etc/passwd} is configured accordingly.
6597 The spawned process runs as the current user outside the container. Inside
6598 the container, it has the same UID and GID as the current user, unless
6599 @option{--user} is passed (see below).
6603 For containers, share the network namespace with the host system.
6604 Containers created without this flag only have access to the loopback
6607 @item --link-profile
6609 For containers, link the environment profile to @file{~/.guix-profile}
6610 within the container and set @code{GUIX_ENVIRONMENT} to that.
6611 This is equivalent to making @file{~/.guix-profile} a symlink to the
6612 actual profile within the container.
6613 Linking will fail and abort the environment if the directory already
6614 exists, which will certainly be the case if @command{guix environment}
6615 was invoked in the user's home directory.
6617 Certain packages are configured to look in @file{~/.guix-profile} for
6618 configuration files and data;@footnote{For example, the
6619 @code{fontconfig} package inspects @file{~/.guix-profile/share/fonts}
6620 for additional fonts.} @option{--link-profile} allows these programs to
6621 behave as expected within the environment.
6623 @item --user=@var{user}
6624 @itemx -u @var{user}
6625 For containers, use the username @var{user} in place of the current
6626 user. The generated @file{/etc/passwd} entry within the container will
6627 contain the name @var{user}, the home directory will be
6628 @file{/home/@var{user}}, and no user GECOS data will be copied. Furthermore,
6629 the UID and GID inside the container are 1000. @var{user}
6630 need not exist on the system.
6632 Additionally, any shared or exposed path (see @option{--share} and
6633 @option{--expose} respectively) whose target is within the current user's
6634 home directory will be remapped relative to @file{/home/USER}; this
6635 includes the automatic mapping of the current working directory.
6638 # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
6640 guix environment --container --user=foo \
6641 --expose=$HOME/test \
6642 --expose=/tmp/target=$HOME/target
6645 While this will limit the leaking of user identity through home paths
6646 and each of the user fields, this is only one useful component of a
6647 broader privacy/anonymity solution---not one in and of itself.
6650 For containers, the default behavior is to share the current working
6651 directory with the isolated container and immediately change to that
6652 directory within the container. If this is undesirable,
6653 @option{--no-cwd} will cause the current working directory to @emph{not}
6654 be automatically shared and will change to the user's home directory
6655 within the container instead. See also @option{--user}.
6657 @item --expose=@var{source}[=@var{target}]
6658 @itemx --share=@var{source}[=@var{target}]
6659 For containers, @option{--expose} (resp. @option{--share}) exposes the
6660 file system @var{source} from the host system as the read-only
6661 (resp. writable) file system @var{target} within the container. If
6662 @var{target} is not specified, @var{source} is used as the target mount
6663 point in the container.
6665 The example below spawns a Guile REPL in a container in which the user's
6666 home directory is accessible read-only via the @file{/exchange}
6670 guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
6675 For containers, emulate a Filesystem Hierarchy Standard (FHS)
6676 configuration within the container, see
6677 @uref{https://refspecs.linuxfoundation.org/fhs.shtml, the official
6678 specification}. As Guix deviates from the FHS specification, this
6679 option sets up the container to more closely mimic that of other
6680 GNU/Linux distributions. This is useful for reproducing other
6681 development environments, testing, and using programs which expect the
6682 FHS specification to be followed. With this option, the container will
6683 include a version of @code{glibc} which will read
6684 @code{/etc/ld.so.cache} within the container for the shared library
6685 cache (contrary to @code{glibc} in regular Guix usage) and set up the
6686 expected FHS directories: @code{/bin}, @code{/etc}, @code{/lib}, and
6687 @code{/usr} from the container's profile.
6691 @command{guix environment}
6692 also supports all of the common build options that @command{guix
6693 build} supports (@pxref{Common Build Options}) as well as package
6694 transformation options (@pxref{Package Transformation Options}).
6696 @node Invoking guix pack
6697 @section Invoking @command{guix pack}
6699 @cindex @command{guix pack}
6701 Occasionally you want to pass software to people who are not (yet!)
6702 lucky enough to be using Guix. You'd tell them to run @command{guix
6703 package -i @var{something}}, but that's not possible in this case. This
6704 is where @command{guix pack} comes in.
6707 If you are looking for ways to exchange binaries among machines that
6708 already run Guix, @pxref{Invoking guix copy}, @ref{Invoking guix
6709 publish}, and @ref{Invoking guix archive}.
6714 @cindex application bundle
6715 @cindex software bundle
6716 The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
6717 @dfn{software bundle}: it creates a tarball or some other archive
6718 containing the binaries of the software you're interested in, and all
6719 its dependencies. The resulting archive can be used on any machine that
6720 does not have Guix, and people can run the exact same binaries as those
6721 you have with Guix. The pack itself is created in a bit-reproducible
6722 fashion, so anyone can verify that it really contains the build results
6723 that you pretend to be shipping.
6725 For example, to create a bundle containing Guile, Emacs, Geiser, and all
6726 their dependencies, you can run:
6729 $ guix pack guile emacs emacs-geiser
6731 /gnu/store/@dots{}-pack.tar.gz
6734 The result here is a tarball containing a @file{/gnu/store} directory
6735 with all the relevant packages. The resulting tarball contains a
6736 @dfn{profile} with the three packages of interest; the profile is the
6737 same as would be created by @command{guix package -i}. It is this
6738 mechanism that is used to create Guix's own standalone binary tarball
6739 (@pxref{Binary Installation}).
6741 Users of this pack would have to run
6742 @file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may
6743 find inconvenient. To work around it, you can create, say, a
6744 @file{/opt/gnu/bin} symlink to the profile:
6747 guix pack -S /opt/gnu/bin=bin guile emacs emacs-geiser
6751 That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
6753 @cindex relocatable binaries, with @command{guix pack}
6754 What if the recipient of your pack does not have root privileges on
6755 their machine, and thus cannot unpack it in the root file system? In
6756 that case, you will want to use the @option{--relocatable} option (see
6757 below). This option produces @dfn{relocatable binaries}, meaning they
6758 they can be placed anywhere in the file system hierarchy: in the example
6759 above, users can unpack your tarball in their home directory and
6760 directly run @file{./opt/gnu/bin/guile}.
6762 @cindex Docker, build an image with guix pack
6763 Alternatively, you can produce a pack in the Docker image format using
6764 the following command:
6767 guix pack -f docker -S /bin=bin guile guile-readline
6771 The result is a tarball that can be passed to the @command{docker load}
6772 command, followed by @code{docker run}:
6775 docker load < @var{file}
6776 docker run -ti guile-guile-readline /bin/guile
6780 where @var{file} is the image returned by @var{guix pack}, and
6781 @code{guile-guile-readline} is its ``image tag''. See the
6782 @uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
6783 documentation} for more information.
6785 @cindex Singularity, build an image with guix pack
6786 @cindex SquashFS, build an image with guix pack
6787 Yet another option is to produce a SquashFS image with the following
6791 guix pack -f squashfs bash guile emacs emacs-geiser
6795 The result is a SquashFS file system image that can either be mounted or
6796 directly be used as a file system container image with the
6797 @uref{https://www.sylabs.io/docs/, Singularity container execution
6798 environment}, using commands like @command{singularity shell} or
6799 @command{singularity exec}.
6801 Several command-line options allow you to customize your pack:
6804 @item --format=@var{format}
6805 @itemx -f @var{format}
6806 Produce a pack in the given @var{format}.
6808 The available formats are:
6812 This is the default format. It produces a tarball containing all the
6813 specified binaries and symlinks.
6816 This produces a tarball that follows the
6817 @uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
6818 Docker Image Specification}. The ``repository name'' as it appears in
6819 the output of the @command{docker images} command is computed from
6820 package names passed on the command line or in the manifest file.
6823 This produces a SquashFS image containing all the specified binaries and
6824 symlinks, as well as empty mount points for virtual file systems like
6828 Singularity @emph{requires} you to provide @file{/bin/sh} in the image.
6829 For that reason, @command{guix pack -f squashfs} always implies @code{-S
6830 /bin=bin}. Thus, your @command{guix pack} invocation must always start
6831 with something like:
6834 guix pack -f squashfs bash @dots{}
6837 If you forget the @code{bash} (or similar) package, @command{singularity
6838 run} and @command{singularity exec} will fail with an unhelpful ``no
6839 such file or directory'' message.
6843 This produces a Debian archive (a package with the @samp{.deb} file
6844 extension) containing all the specified binaries and symbolic links,
6845 that can be installed on top of any dpkg-based GNU(/Linux) distribution.
6846 Advanced options can be revealed via the @option{--help-deb-format}
6847 option. They allow embedding control files for more fine-grained
6848 control, such as activating specific triggers or providing a maintainer
6849 configure script to run arbitrary setup code upon installation.
6852 guix pack -f deb -C xz -S /usr/bin/hello=bin/hello hello
6856 Because archives produced with @command{guix pack} contain a collection
6857 of store items and because each @command{dpkg} package must not have
6858 conflicting files, in practice that means you likely won't be able to
6859 install more than one such archive on a given system.
6863 @command{dpkg} will assume ownership of any files contained in the pack
6864 that it does @emph{not} know about. It is unwise to install
6865 Guix-produced @samp{.deb} files on a system where @file{/gnu/store} is
6866 shared by other software, such as a Guix installation or other, non-deb
6872 @cindex relocatable binaries
6875 Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
6876 anywhere in the file system hierarchy and run from there.
6878 When this option is passed once, the resulting binaries require support for
6879 @dfn{user namespaces} in the kernel Linux; when passed
6880 @emph{twice}@footnote{Here's a trick to memorize it: @code{-RR}, which adds
6881 PRoot support, can be thought of as the abbreviation of ``Really
6882 Relocatable''. Neat, isn't it?}, relocatable binaries fall to back to
6883 other techniques if user namespaces are unavailable, and essentially
6884 work anywhere---see below for the implications.
6886 For example, if you create a pack containing Bash with:
6889 guix pack -RR -S /mybin=bin bash
6893 ...@: you can copy that pack to a machine that lacks Guix, and from your
6894 home directory as a normal user, run:
6902 In that shell, if you type @code{ls /gnu/store}, you'll notice that
6903 @file{/gnu/store} shows up and contains all the dependencies of
6904 @code{bash}, even though the machine actually lacks @file{/gnu/store}
6905 altogether! That is probably the simplest way to deploy Guix-built
6906 software on a non-Guix machine.
6909 By default, relocatable binaries rely on the @dfn{user namespace} feature of
6910 the kernel Linux, which allows unprivileged users to mount or change root.
6911 Old versions of Linux did not support it, and some GNU/Linux distributions
6914 To produce relocatable binaries that work even in the absence of user
6915 namespaces, pass @option{--relocatable} or @option{-R} @emph{twice}. In that
6916 case, binaries will try user namespace support and fall back to another
6917 @dfn{execution engine} if user namespaces are not supported. The
6918 following execution engines are supported:
6922 Try user namespaces and fall back to PRoot if user namespaces are not
6923 supported (see below).
6926 Try user namespaces and fall back to Fakechroot if user namespaces are
6927 not supported (see below).
6930 Run the program through user namespaces and abort if they are not
6934 Run through PRoot. The @uref{https://proot-me.github.io/, PRoot} program
6935 provides the necessary
6936 support for file system virtualization. It achieves that by using the
6937 @code{ptrace} system call on the running program. This approach has the
6938 advantage to work without requiring special kernel support, but it incurs
6939 run-time overhead every time a system call is made.
6942 Run through Fakechroot. @uref{https://github.com/dex4er/fakechroot/,
6943 Fakechroot} virtualizes file system accesses by intercepting calls to C
6944 library functions such as @code{open}, @code{stat}, @code{exec}, and so
6945 on. Unlike PRoot, it incurs very little overhead. However, it does not
6946 always work: for example, some file system accesses made from within the
6947 C library are not intercepted, and file system accesses made @i{via}
6948 direct syscalls are not intercepted either, leading to erratic behavior.
6951 @vindex GUIX_EXECUTION_ENGINE
6952 When running a wrapped program, you can explicitly request one of the
6953 execution engines listed above by setting the
6954 @env{GUIX_EXECUTION_ENGINE} environment variable accordingly.
6957 @cindex entry point, for Docker images
6958 @item --entry-point=@var{command}
6959 Use @var{command} as the @dfn{entry point} of the resulting pack, if the pack
6960 format supports it---currently @code{docker} and @code{squashfs} (Singularity)
6961 support it. @var{command} must be relative to the profile contained in the
6964 The entry point specifies the command that tools like @code{docker run} or
6965 @code{singularity run} automatically start by default. For example, you can
6969 guix pack -f docker --entry-point=bin/guile guile
6972 The resulting pack can easily be loaded and @code{docker run} with no extra
6973 arguments will spawn @code{bin/guile}:
6976 docker load -i pack.tar.gz
6977 docker run @var{image-id}
6980 @item --expression=@var{expr}
6981 @itemx -e @var{expr}
6982 Consider the package @var{expr} evaluates to.
6984 This has the same purpose as the same-named option in @command{guix
6985 build} (@pxref{Additional Build Options, @option{--expression} in
6986 @command{guix build}}).
6988 @anchor{pack-manifest}
6989 @item --manifest=@var{file}
6990 @itemx -m @var{file}
6991 Use the packages contained in the manifest object returned by the Scheme
6992 code in @var{file}. This option can be repeated several times, in which
6993 case the manifests are concatenated.
6995 This has a similar purpose as the same-named option in @command{guix
6996 package} (@pxref{profile-manifest, @option{--manifest}}) and uses the
6997 same manifest files. It allows you to define a collection of packages
6998 once and use it both for creating profiles and for creating archives
6999 for use on machines that do not have Guix installed. Note that you can
7000 specify @emph{either} a manifest file @emph{or} a list of packages,
7003 @xref{Writing Manifests}, for information on how to write a manifest.
7004 @xref{shell-export-manifest, @command{guix shell --export-manifest}},
7005 for information on how to ``convert'' command-line options into a
7008 @item --system=@var{system}
7009 @itemx -s @var{system}
7010 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
7011 the system type of the build host.
7013 @item --target=@var{triplet}
7014 @cindex cross-compilation
7015 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
7016 as @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets, GNU
7017 configuration triplets,, autoconf, Autoconf}).
7019 @item --compression=@var{tool}
7020 @itemx -C @var{tool}
7021 Compress the resulting tarball using @var{tool}---one of @code{gzip},
7022 @code{zstd}, @code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no
7025 @item --symlink=@var{spec}
7026 @itemx -S @var{spec}
7027 Add the symlinks specified by @var{spec} to the pack. This option can
7028 appear several times.
7030 @var{spec} has the form @code{@var{source}=@var{target}}, where
7031 @var{source} is the symlink that will be created and @var{target} is the
7034 For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
7035 symlink pointing to the @file{bin} sub-directory of the profile.
7037 @item --save-provenance
7038 Save provenance information for the packages passed on the command line.
7039 Provenance information includes the URL and commit of the channels in use
7042 Provenance information is saved in the
7043 @file{/gnu/store/@dots{}-profile/manifest} file in the pack, along with the
7044 usual package metadata---the name and version of each package, their
7045 propagated inputs, and so on. It is useful information to the recipient of
7046 the pack, who then knows how the pack was (supposedly) obtained.
7048 This option is not enabled by default because, like timestamps, provenance
7049 information contributes nothing to the build process. In other words, there
7050 is an infinity of channel URLs and commit IDs that can lead to the same pack.
7051 Recording such ``silent'' metadata in the output thus potentially breaks the
7052 source-to-binary bitwise reproducibility property.
7054 @item --root=@var{file}
7055 @itemx -r @var{file}
7056 @cindex garbage collector root, for packs
7057 Make @var{file} a symlink to the resulting pack, and register it as a garbage
7060 @item --localstatedir
7061 @itemx --profile-name=@var{name}
7062 Include the ``local state directory'', @file{/var/guix}, in the resulting
7063 pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
7064 profile---by default @var{name} is @code{guix-profile}, which corresponds to
7065 @file{~root/.guix-profile}.
7067 @file{/var/guix} contains the store database (@pxref{The Store}) as well
7068 as garbage-collector roots (@pxref{Invoking guix gc}). Providing it in
7069 the pack means that the store is ``complete'' and manageable by Guix;
7070 not providing it pack means that the store is ``dead'': items cannot be
7071 added to it or removed from it after extraction of the pack.
7073 One use case for this is the Guix self-contained binary tarball
7074 (@pxref{Binary Installation}).
7078 Print the name of the derivation that builds the pack.
7081 Use the bootstrap binaries to build the pack. This option is only
7082 useful to Guix developers.
7085 In addition, @command{guix pack} supports all the common build options
7086 (@pxref{Common Build Options}) and all the package transformation
7087 options (@pxref{Package Transformation Options}).
7090 @node The GCC toolchain
7091 @section The GCC toolchain
7095 @cindex linker wrapper
7096 @cindex toolchain, for C development
7097 @cindex toolchain, for Fortran development
7099 If you need a complete toolchain for compiling and linking C or C++
7100 source code, use the @code{gcc-toolchain} package. This package
7101 provides a complete GCC toolchain for C/C++ development, including GCC
7102 itself, the GNU C Library (headers and binaries, plus debugging symbols
7103 in the @code{debug} output), Binutils, and a linker wrapper.
7105 The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches
7106 passed to the linker, add corresponding @code{-rpath} arguments, and
7107 invoke the actual linker with this new set of arguments. You can instruct the
7108 wrapper to refuse to link against libraries not in the store by setting the
7109 @env{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}.
7111 The package @code{gfortran-toolchain} provides a complete GCC toolchain
7112 for Fortran development. For other languages, please use
7113 @samp{guix search gcc toolchain} (@pxref{guix-search,, Invoking guix package}).
7116 @node Invoking guix git authenticate
7117 @section Invoking @command{guix git authenticate}
7119 @cindex @command{guix git authenticate}
7121 The @command{guix git authenticate} command authenticates a Git checkout
7122 following the same rule as for channels (@pxref{channel-authentication,
7123 channel authentication}). That is, starting from a given commit, it
7124 ensures that all subsequent commits are signed by an OpenPGP key whose
7125 fingerprint appears in the @file{.guix-authorizations} file of its
7128 You will find this command useful if you maintain a channel. But in
7129 fact, this authentication mechanism is useful in a broader context, so
7130 you might want to use it for Git repositories that have nothing to do
7133 The general syntax is:
7136 guix git authenticate @var{commit} @var{signer} [@var{options}@dots{}]
7139 By default, this command authenticates the Git checkout in the current
7140 directory; it outputs nothing and exits with exit code zero on success
7141 and non-zero on failure. @var{commit} above denotes the first commit
7142 where authentication takes place, and @var{signer} is the OpenPGP
7143 fingerprint of public key used to sign @var{commit}. Together, they
7144 form a ``channel introduction'' (@pxref{channel-authentication, channel
7145 introduction}). The options below allow you to fine-tune the process.
7148 @item --repository=@var{directory}
7149 @itemx -r @var{directory}
7150 Open the Git repository in @var{directory} instead of the current
7153 @item --keyring=@var{reference}
7154 @itemx -k @var{reference}
7155 Load OpenPGP keyring from @var{reference}, the reference of a branch
7156 such as @code{origin/keyring} or @code{my-keyring}. The branch must
7157 contain OpenPGP public keys in @file{.key} files, either in binary form
7158 or ``ASCII-armored''. By default the keyring is loaded from the branch
7159 named @code{keyring}.
7162 Display commit signing statistics upon completion.
7164 @item --cache-key=@var{key}
7165 Previously-authenticated commits are cached in a file under
7166 @file{~/.cache/guix/authentication}. This option forces the cache to be
7167 stored in file @var{key} in that directory.
7169 @item --historical-authorizations=@var{file}
7170 By default, any commit whose parent commit(s) lack the
7171 @file{.guix-authorizations} file is considered inauthentic. In
7172 contrast, this option considers the authorizations in @var{file} for any
7173 commit that lacks @file{.guix-authorizations}. The format of @var{file}
7174 is the same as that of @file{.guix-authorizations}
7175 (@pxref{channel-authorizations, @file{.guix-authorizations} format}).
7179 @c *********************************************************************
7180 @node Programming Interface
7181 @chapter Programming Interface
7183 GNU Guix provides several Scheme programming interfaces (APIs) to
7184 define, build, and query packages. The first interface allows users to
7185 write high-level package definitions. These definitions refer to
7186 familiar packaging concepts, such as the name and version of a package,
7187 its build system, and its dependencies. These definitions can then be
7188 turned into concrete build actions.
7190 Build actions are performed by the Guix daemon, on behalf of users. In a
7191 standard setup, the daemon has write access to the store---the
7192 @file{/gnu/store} directory---whereas users do not. The recommended
7193 setup also has the daemon perform builds in chroots, under specific
7194 build users, to minimize interference with the rest of the system.
7197 Lower-level APIs are available to interact with the daemon and the
7198 store. To instruct the daemon to perform a build action, users actually
7199 provide it with a @dfn{derivation}. A derivation is a low-level
7200 representation of the build actions to be taken, and the environment in
7201 which they should occur---derivations are to package definitions what
7202 assembly is to C programs. The term ``derivation'' comes from the fact
7203 that build results @emph{derive} from them.
7205 This chapter describes all these APIs in turn, starting from high-level
7206 package definitions.
7209 * Package Modules:: Packages from the programmer's viewpoint.
7210 * Defining Packages:: Defining new packages.
7211 * Defining Package Variants:: Customizing packages.
7212 * Writing Manifests:: The bill of materials of your environment.
7213 * Build Systems:: Specifying how packages are built.
7214 * Build Phases:: Phases of the build process of a package.
7215 * Build Utilities:: Helpers for your package definitions and more.
7216 * Search Paths:: Declaring search path environment variables.
7217 * The Store:: Manipulating the package store.
7218 * Derivations:: Low-level interface to package derivations.
7219 * The Store Monad:: Purely functional interface to the store.
7220 * G-Expressions:: Manipulating build expressions.
7221 * Invoking guix repl:: Programming Guix in Guile
7222 * Using Guix Interactively:: Fine-grain interaction at the REPL.
7225 @node Package Modules
7226 @section Package Modules
7228 From a programming viewpoint, the package definitions of the
7229 GNU distribution are provided by Guile modules in the @code{(gnu packages
7230 @dots{})} name space@footnote{Note that packages under the @code{(gnu
7231 packages @dots{})} module name space are not necessarily ``GNU
7232 packages''. This module naming scheme follows the usual Guile module
7233 naming convention: @code{gnu} means that these modules are distributed
7234 as part of the GNU system, and @code{packages} identifies modules that
7235 define packages.} (@pxref{Modules, Guile modules,, guile, GNU Guile
7236 Reference Manual}). For instance, the @code{(gnu packages emacs)}
7237 module exports a variable named @code{emacs}, which is bound to a
7238 @code{<package>} object (@pxref{Defining Packages}).
7240 The @code{(gnu packages @dots{})} module name space is
7241 automatically scanned for packages by the command-line tools. For
7242 instance, when running @code{guix install emacs}, all the @code{(gnu
7243 packages @dots{})} modules are scanned until one that exports a package
7244 object whose name is @code{emacs} is found. This package search
7245 facility is implemented in the @code{(gnu packages)} module.
7247 @cindex customization, of packages
7248 @cindex package module search path
7249 Users can store package definitions in modules with different
7250 names---e.g., @code{(my-packages emacs)}@footnote{Note that the file
7251 name and module name must match. For instance, the @code{(my-packages
7252 emacs)} module must be stored in a @file{my-packages/emacs.scm} file
7253 relative to the load path specified with @option{--load-path} or
7254 @env{GUIX_PACKAGE_PATH}. @xref{Modules and the File System,,,
7255 guile, GNU Guile Reference Manual}, for details.}. There are two ways to make
7256 these package definitions visible to the user interfaces:
7260 By adding the directory containing your package modules to the search path
7261 with the @code{-L} flag of @command{guix package} and other commands
7262 (@pxref{Common Build Options}), or by setting the @env{GUIX_PACKAGE_PATH}
7263 environment variable described below.
7266 By defining a @dfn{channel} and configuring @command{guix pull} so that it
7267 pulls from it. A channel is essentially a Git repository containing package
7268 modules. @xref{Channels}, for more information on how to define and use
7272 @env{GUIX_PACKAGE_PATH} works similarly to other search path variables:
7274 @defvr {Environment Variable} GUIX_PACKAGE_PATH
7275 This is a colon-separated list of directories to search for additional
7276 package modules. Directories listed in this variable take precedence
7277 over the own modules of the distribution.
7280 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}:
7281 each package is built based solely on other packages in the
7282 distribution. The root of this dependency graph is a small set of
7283 @dfn{bootstrap binaries}, provided by the @code{(gnu packages
7284 bootstrap)} module. For more information on bootstrapping,
7285 @pxref{Bootstrapping}.
7287 @node Defining Packages
7288 @section Defining Packages
7290 The high-level interface to package definitions is implemented in the
7291 @code{(guix packages)} and @code{(guix build-system)} modules. As an
7292 example, the package definition, or @dfn{recipe}, for the GNU Hello
7293 package looks like this:
7296 (define-module (gnu packages hello)
7297 #:use-module (guix packages)
7298 #:use-module (guix download)
7299 #:use-module (guix build-system gnu)
7300 #:use-module (guix licenses)
7301 #:use-module (gnu packages gawk))
7303 (define-public hello
7309 (uri (string-append "mirror://gnu/hello/hello-" version
7313 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
7314 (build-system gnu-build-system)
7315 (arguments '(#:configure-flags '("--enable-silent-rules")))
7316 (inputs (list gawk))
7317 (synopsis "Hello, GNU world: An example GNU package")
7318 (description "Guess what GNU Hello prints!")
7319 (home-page "https://www.gnu.org/software/hello/")
7324 Without being a Scheme expert, the reader may have guessed the meaning
7325 of the various fields here. This expression binds the variable
7326 @code{hello} to a @code{<package>} object, which is essentially a record
7327 (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference Manual}).
7328 This package object can be inspected using procedures found in the
7329 @code{(guix packages)} module; for instance, @code{(package-name hello)}
7330 returns---surprise!---@code{"hello"}.
7332 With luck, you may be able to import part or all of the definition of
7333 the package you are interested in from another repository, using the
7334 @code{guix import} command (@pxref{Invoking guix import}).
7336 In the example above, @code{hello} is defined in a module of its own,
7337 @code{(gnu packages hello)}. Technically, this is not strictly
7338 necessary, but it is convenient to do so: all the packages defined in
7339 modules under @code{(gnu packages @dots{})} are automatically known to
7340 the command-line tools (@pxref{Package Modules}).
7342 There are a few points worth noting in the above package definition:
7346 The @code{source} field of the package is an @code{<origin>} object
7347 (@pxref{origin Reference}, for the complete reference).
7348 Here, the @code{url-fetch} method from @code{(guix download)} is used,
7349 meaning that the source is a file to be downloaded over FTP or HTTP.
7351 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of
7352 the GNU mirrors defined in @code{(guix download)}.
7354 The @code{sha256} field specifies the expected SHA256 hash of the file
7355 being downloaded. It is mandatory, and allows Guix to check the
7356 integrity of the file. The @code{(base32 @dots{})} form introduces the
7357 base32 representation of the hash. You can obtain this information with
7358 @code{guix download} (@pxref{Invoking guix download}) and @code{guix
7359 hash} (@pxref{Invoking guix hash}).
7362 When needed, the @code{origin} form can also have a @code{patches} field
7363 listing patches to be applied, and a @code{snippet} field giving a
7364 Scheme expression to modify the source code.
7367 @cindex GNU Build System
7368 The @code{build-system} field specifies the procedure to build the
7369 package (@pxref{Build Systems}). Here, @code{gnu-build-system}
7370 represents the familiar GNU Build System, where packages may be
7371 configured, built, and installed with the usual @code{./configure &&
7372 make && make check && make install} command sequence.
7374 When you start packaging non-trivial software, you may need tools to
7375 manipulate those build phases, manipulate files, and so on. @xref{Build
7376 Utilities}, for more on this.
7379 The @code{arguments} field specifies options for the build system
7380 (@pxref{Build Systems}). Here it is interpreted by
7381 @code{gnu-build-system} as a request run @file{configure} with the
7382 @option{--enable-silent-rules} flag.
7388 @cindex backquote (quasiquote)
7391 @cindex comma (unquote)
7394 What about these quote (@code{'}) characters? They are Scheme syntax to
7395 introduce a literal list; @code{'} is synonymous with @code{quote}.
7396 Sometimes you'll also see @code{`} (a backquote, synonymous with
7397 @code{quasiquote}) and @code{,} (a comma, synonymous with @code{unquote}).
7398 @xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual},
7399 for details. Here the value of the @code{arguments} field is a list of
7400 arguments passed to the build system down the road, as with @code{apply}
7401 (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference
7404 The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
7405 (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
7406 @code{#:configure-flags} is a keyword used to pass a keyword argument
7407 to the build system (@pxref{Coding With Keywords,,, guile, GNU Guile
7411 The @code{inputs} field specifies inputs to the build process---i.e.,
7412 build-time or run-time dependencies of the package. Here, we add
7413 an input, a reference to the @code{gawk}
7414 variable; @code{gawk} is itself bound to a @code{<package>} object.
7416 Note that GCC, Coreutils, Bash, and other essential tools do not need to
7417 be specified as inputs here. Instead, @code{gnu-build-system} takes care
7418 of ensuring that they are present (@pxref{Build Systems}).
7420 However, any other dependencies need to be specified in the
7421 @code{inputs} field. Any dependency not specified here will simply be
7422 unavailable to the build process, possibly leading to a build failure.
7425 @xref{package Reference}, for a full description of possible fields.
7427 @quotation Going further
7428 @cindex Scheme programming language, getting started
7429 Intimidated by the Scheme language or curious about it? The Cookbook
7430 has a short section to get started that recaps some of the things shown
7431 above and explains the fundamentals. @xref{A Scheme Crash Course,,,
7432 guix-cookbook, GNU Guix Cookbook}, for more information.
7435 Once a package definition is in place, the
7436 package may actually be built using the @code{guix build} command-line
7437 tool (@pxref{Invoking guix build}), troubleshooting any build failures
7438 you encounter (@pxref{Debugging Build Failures}). You can easily jump back to the
7439 package definition using the @command{guix edit} command
7440 (@pxref{Invoking guix edit}).
7441 @xref{Packaging Guidelines}, for
7442 more information on how to test package definitions, and
7443 @ref{Invoking guix lint}, for information on how to check a definition
7444 for style conformance.
7445 @vindex GUIX_PACKAGE_PATH
7446 Lastly, @pxref{Channels}, for information
7447 on how to extend the distribution by adding your own package definitions
7450 Finally, updating the package definition to a new upstream version
7451 can be partly automated by the @command{guix refresh} command
7452 (@pxref{Invoking guix refresh}).
7454 Behind the scenes, a derivation corresponding to the @code{<package>}
7455 object is first computed by the @code{package-derivation} procedure.
7456 That derivation is stored in a @file{.drv} file under @file{/gnu/store}.
7457 The build actions it prescribes may then be realized by using the
7458 @code{build-derivations} procedure (@pxref{The Store}).
7460 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
7461 Return the @code{<derivation>} object of @var{package} for @var{system}
7462 (@pxref{Derivations}).
7464 @var{package} must be a valid @code{<package>} object, and @var{system}
7465 must be a string denoting the target system type---e.g.,
7466 @code{"x86_64-linux"} for an x86_64 Linux-based GNU system. @var{store}
7467 must be a connection to the daemon, which operates on the store
7468 (@pxref{The Store}).
7472 @cindex cross-compilation
7473 Similarly, it is possible to compute a derivation that cross-builds a
7474 package for some other system:
7476 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
7477 @var{package} @var{target} [@var{system}]
7478 Return the @code{<derivation>} object of @var{package} cross-built from
7479 @var{system} to @var{target}.
7481 @var{target} must be a valid GNU triplet denoting the target hardware
7482 and operating system, such as @code{"aarch64-linux-gnu"}
7483 (@pxref{Specifying Target Triplets,,, autoconf, Autoconf}).
7486 Once you have package definitions, you can easily define @emph{variants}
7487 of those packages. @xref{Defining Package Variants}, for more on that.
7490 * package Reference:: The package data type.
7491 * origin Reference:: The origin data type.
7495 @node package Reference
7496 @subsection @code{package} Reference
7498 This section summarizes all the options available in @code{package}
7499 declarations (@pxref{Defining Packages}).
7501 @deftp {Data Type} package
7502 This is the data type representing a package recipe.
7506 The name of the package, as a string.
7508 @item @code{version}
7509 The version of the package, as a string. @xref{Version Numbers}, for
7513 An object telling how the source code for the package should be
7514 acquired. Most of the time, this is an @code{origin} object, which
7515 denotes a file fetched from the Internet (@pxref{origin Reference}). It
7516 can also be any other ``file-like'' object such as a @code{local-file},
7517 which denotes a file from the local file system (@pxref{G-Expressions,
7518 @code{local-file}}).
7520 @item @code{build-system}
7521 The build system that should be used to build the package (@pxref{Build
7524 @item @code{arguments} (default: @code{'()})
7525 The arguments that should be passed to the build system (@pxref{Build
7526 Systems}). This is a list, typically containing sequential
7527 keyword-value pairs, as in this example:
7532 ;; several fields omitted
7534 (list #:tests? #f ;skip tests
7535 #:make-flags #~'("VERBOSE=1") ;pass flags to 'make'
7536 #:configure-flags #~'("--enable-frobbing"))))
7539 The exact set of supported keywords depends on the build system
7540 (@pxref{Build Systems}), but you will find that almost all of them honor
7541 @code{#:configure-flags}, @code{#:make-flags}, @code{#:tests?}, and
7542 @code{#:phases}. The @code{#:phases} keyword in particular lets you
7543 modify the set of build phases for your package (@pxref{Build Phases}).
7545 @item @code{inputs} (default: @code{'()})
7546 @itemx @code{native-inputs} (default: @code{'()})
7547 @itemx @code{propagated-inputs} (default: @code{'()})
7548 @cindex inputs, of packages
7549 These fields list dependencies of the package. Each element of these
7550 lists is either a package, origin, or other ``file-like object''
7551 (@pxref{G-Expressions}); to specify the output of that file-like object
7552 that should be used, pass a two-element list where the second element is
7553 the output (@pxref{Packages with Multiple Outputs}, for more on package
7554 outputs). For example, the list below specifies three inputs:
7557 (list libffi libunistring
7558 `(,glib "bin")) ;the "bin" output of GLib
7561 In the example above, the @code{"out"} output of @code{libffi} and
7562 @code{libunistring} is used.
7564 @quotation Compatibility Note
7565 Until version 1.3.0, input lists were a list of tuples,
7566 where each tuple has a label for the input (a string) as its
7567 first element, a package, origin, or derivation as its second element,
7568 and optionally the name of the output thereof that should be used, which
7569 defaults to @code{"out"}. For example, the list below is equivalent to
7570 the one above, but using the @dfn{old input style}:
7573 ;; Old input style (deprecated).
7574 `(("libffi" ,libffi)
7575 ("libunistring" ,libunistring)
7576 ("glib:bin" ,glib "bin")) ;the "bin" output of GLib
7579 This style is now deprecated; it is still supported but support will be
7580 removed in a future version. It should not be used for new package
7581 definitions. @xref{Invoking guix style}, on how to migrate to the new
7585 @cindex cross compilation, package dependencies
7586 The distinction between @code{native-inputs} and @code{inputs} is
7587 necessary when considering cross-compilation. When cross-compiling,
7588 dependencies listed in @code{inputs} are built for the @emph{target}
7589 architecture; conversely, dependencies listed in @code{native-inputs}
7590 are built for the architecture of the @emph{build} machine.
7592 @code{native-inputs} is typically used to list tools needed at
7593 build time, but not at run time, such as Autoconf, Automake, pkg-config,
7594 Gettext, or Bison. @command{guix lint} can report likely mistakes in
7595 this area (@pxref{Invoking guix lint}).
7597 @anchor{package-propagated-inputs}
7598 Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
7599 specified packages will be automatically installed to profiles
7600 (@pxref{Features, the role of profiles in Guix}) alongside the package
7601 they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
7602 package}}, for information on how @command{guix package} deals with
7605 For example this is necessary when packaging a C/C++ library that needs
7606 headers of another library to compile, or when a pkg-config file refers
7607 to another one @i{via} its @code{Requires} field.
7609 Another example where @code{propagated-inputs} is useful is for languages
7610 that lack a facility to record the run-time search path akin to the
7611 @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and
7612 more. When packaging libraries written in those languages, ensure they
7613 can find library code they depend on at run time by listing run-time
7614 dependencies in @code{propagated-inputs} rather than @code{inputs}.
7616 @item @code{outputs} (default: @code{'("out")})
7617 The list of output names of the package. @xref{Packages with Multiple
7618 Outputs}, for typical uses of additional outputs.
7620 @item @code{native-search-paths} (default: @code{'()})
7621 @itemx @code{search-paths} (default: @code{'()})
7622 A list of @code{search-path-specification} objects describing
7623 search-path environment variables honored by the package. @xref{Search
7624 Paths}, for more on search path specifications.
7626 As for inputs, the distinction between @code{native-search-paths} and
7627 @code{search-paths} only matters when cross-compiling. In a
7628 cross-compilation context, @code{native-search-paths} applies
7629 exclusively to native inputs whereas @code{search-paths} applies only to
7632 Packages such as cross-compilers care about target inputs---for
7633 instance, our (modified) GCC cross-compiler has
7634 @env{CROSS_C_INCLUDE_PATH} in @code{search-paths}, which allows it to
7635 pick @file{.h} files for the target system and @emph{not} those of
7636 native inputs. For the majority of packages though, only
7637 @code{native-search-paths} makes sense.
7639 @item @code{replacement} (default: @code{#f})
7640 This must be either @code{#f} or a package object that will be used as a
7641 @dfn{replacement} for this package. @xref{Security Updates, grafts},
7644 @item @code{synopsis}
7645 A one-line description of the package.
7647 @item @code{description}
7648 A more elaborate description of the package, as a string in Texinfo
7651 @item @code{license}
7652 @cindex license, of packages
7653 The license of the package; a value from @code{(guix licenses)},
7654 or a list of such values.
7656 @item @code{home-page}
7657 The URL to the home-page of the package, as a string.
7659 @item @code{supported-systems} (default: @code{%supported-systems})
7660 The list of systems supported by the package, as strings of the form
7661 @code{architecture-kernel}, for example @code{"x86_64-linux"}.
7663 @item @code{location} (default: source location of the @code{package} form)
7664 The source location of the package. It is useful to override this when
7665 inheriting from another package, in which case this field is not
7666 automatically corrected.
7670 @deffn {Scheme Syntax} this-package
7671 When used in the @emph{lexical scope} of a package field definition, this
7672 identifier resolves to the package being defined.
7674 The example below shows how to add a package as a native input of itself when
7682 ;; When cross-compiled, Guile, for example, depends on
7683 ;; a native version of itself. Add it here.
7684 (native-inputs (if (%current-target-system)
7689 It is an error to refer to @code{this-package} outside a package definition.
7692 The following helper procedures are provided to help deal with package
7695 @deffn {Scheme Procedure} lookup-package-input @var{package} @var{name}
7696 @deffnx {Scheme Procedure} lookup-package-native-input @var{package} @var{name}
7697 @deffnx {Scheme Procedure} lookup-package-propagated-input @var{package} @var{name}
7698 @deffnx {Scheme Procedure} lookup-package-direct-input @var{package} @var{name}
7699 Look up @var{name} among @var{package}'s inputs (or native, propagated,
7700 or direct inputs). Return it if found, @code{#f} otherwise.
7702 @var{name} is the name of a package depended on. Here's how you might
7706 (use-modules (guix packages) (gnu packages base))
7708 (lookup-package-direct-input coreutils "gmp")
7709 @result{} #<package gmp@@6.2.1 @dots{}>
7712 In this example we obtain the @code{gmp} package that is among the
7713 direct inputs of @code{coreutils}.
7716 @cindex development inputs, of a package
7717 @cindex implicit inputs, of a package
7718 Sometimes you will want to obtain the list of inputs needed to
7719 @emph{develop} a package---all the inputs that are visible when the
7720 package is compiled. This is what the @code{package-development-inputs}
7723 @deffn {Scheme Procedure} package-development-inputs @var{package} @
7724 [@var{system}] [#:target #f]
7725 Return the list of inputs required by @var{package} for development
7726 purposes on @var{system}. When @var{target} is true, return the inputs
7727 needed to cross-compile @var{package} from @var{system} to
7728 @var{target}, where @var{target} is a triplet such as
7729 @code{"aarch64-linux-gnu"}.
7731 Note that the result includes both explicit inputs and implicit
7732 inputs---inputs automatically added by the build system (@pxref{Build
7733 Systems}). Let us take the @code{hello} package to illustrate that:
7736 (use-modules (gnu packages base) (guix packages))
7739 @result{} #<package hello@@2.10 gnu/packages/base.scm:79 7f585d4f6790>
7741 (package-direct-inputs hello)
7744 (package-development-inputs hello)
7745 @result{} (("source" @dots{}) ("tar" #<package tar@@1.32 @dots{}>) @dots{})
7748 In this example, @code{package-direct-inputs} returns the empty list,
7749 because @code{hello} has zero explicit dependencies. Conversely,
7750 @code{package-development-inputs} includes inputs implicitly added by
7751 @code{gnu-build-system} that are required to build @code{hello}: tar,
7752 gzip, GCC, libc, Bash, and more. To visualize it, @command{guix graph
7753 hello} would show you explicit inputs, whereas @command{guix graph -t
7754 bag hello} would include implicit inputs (@pxref{Invoking guix graph}).
7757 Because packages are regular Scheme objects that capture a complete
7758 dependency graph and associated build procedures, it is often useful to
7759 write procedures that take a package and return a modified version
7760 thereof according to some parameters. Below are a few examples.
7762 @cindex tool chain, choosing a package's tool chain
7763 @deffn {Scheme Procedure} package-with-c-toolchain @var{package} @var{toolchain}
7764 Return a variant of @var{package} that uses @var{toolchain} instead of
7765 the default GNU C/C++ toolchain. @var{toolchain} must be a list of
7766 inputs (label/package tuples) providing equivalent functionality, such
7767 as the @code{gcc-toolchain} package.
7769 The example below returns a variant of the @code{hello} package built
7770 with GCC@tie{}10.x and the rest of the GNU tool chain (Binutils and the
7771 GNU C Library) instead of the default tool chain:
7774 (let ((toolchain (specification->package "gcc-toolchain@@10")))
7775 (package-with-c-toolchain hello `(("toolchain" ,toolchain))))
7778 The build tool chain is part of the @dfn{implicit inputs} of
7779 packages---it's usually not listed as part of the various ``inputs''
7780 fields and is instead pulled in by the build system. Consequently, this
7781 procedure works by changing the build system of @var{package} so that it
7782 pulls in @var{toolchain} instead of the defaults. @ref{Build Systems},
7783 for more on build systems.
7786 @node origin Reference
7787 @subsection @code{origin} Reference
7789 This section documents @dfn{origins}. An @code{origin} declaration
7790 specifies data that must be ``produced''---downloaded, usually---and
7791 whose content hash is known in advance. Origins are primarily used to
7792 represent the source code of packages (@pxref{Defining Packages}). For
7793 that reason, the @code{origin} form allows you to declare patches to
7794 apply to the original source code as well as code snippets to modify it.
7796 @deftp {Data Type} origin
7797 This is the data type representing a source code origin.
7801 An object containing the URI of the source. The object type depends on
7802 the @code{method} (see below). For example, when using the
7803 @var{url-fetch} method of @code{(guix download)}, the valid @code{uri}
7804 values are: a URL represented as a string, or a list thereof.
7806 @cindex fixed-output derivations, for download
7808 A monadic procedure that handles the given URI@. The procedure must
7809 accept at least three arguments: the value of the @code{uri} field and
7810 the hash algorithm and hash value specified by the @code{hash} field.
7811 It must return a store item or a derivation in the store monad
7812 (@pxref{The Store Monad}); most methods return a fixed-output derivation
7813 (@pxref{Derivations}).
7815 Commonly used methods include @code{url-fetch}, which fetches data from
7816 a URL, and @code{git-fetch}, which fetches data from a Git repository
7820 A bytevector containing the SHA-256 hash of the source. This is
7821 equivalent to providing a @code{content-hash} SHA256 object in the
7822 @code{hash} field described below.
7825 The @code{content-hash} object of the source---see below for how to use
7826 @code{content-hash}.
7828 You can obtain this information using @code{guix download}
7829 (@pxref{Invoking guix download}) or @code{guix hash} (@pxref{Invoking
7832 @item @code{file-name} (default: @code{#f})
7833 The file name under which the source code should be saved. When this is
7834 @code{#f}, a sensible default value will be used in most cases. In case
7835 the source is fetched from a URL, the file name from the URL will be
7836 used. For version control checkouts, it is recommended to provide the
7837 file name explicitly because the default is not very descriptive.
7839 @item @code{patches} (default: @code{'()})
7840 A list of file names, origins, or file-like objects (@pxref{G-Expressions,
7841 file-like objects}) pointing to patches to be applied to the source.
7843 This list of patches must be unconditional. In particular, it cannot
7844 depend on the value of @code{%current-system} or
7845 @code{%current-target-system}.
7847 @item @code{snippet} (default: @code{#f})
7848 A G-expression (@pxref{G-Expressions}) or S-expression that will be run
7849 in the source directory. This is a convenient way to modify the source,
7850 sometimes more convenient than a patch.
7852 @item @code{patch-flags} (default: @code{'("-p1")})
7853 A list of command-line flags that should be passed to the @code{patch}
7856 @item @code{patch-inputs} (default: @code{#f})
7857 Input packages or derivations to the patching process. When this is
7858 @code{#f}, the usual set of inputs necessary for patching are provided,
7859 such as GNU@tie{}Patch.
7861 @item @code{modules} (default: @code{'()})
7862 A list of Guile modules that should be loaded during the patching
7863 process and while running the code in the @code{snippet} field.
7865 @item @code{patch-guile} (default: @code{#f})
7866 The Guile package that should be used in the patching process. When
7867 this is @code{#f}, a sensible default is used.
7871 @deftp {Data Type} content-hash @var{value} [@var{algorithm}]
7872 Construct a content hash object for the given @var{algorithm}, and with
7873 @var{value} as its hash value. When @var{algorithm} is omitted, assume
7874 it is @code{sha256}.
7876 @var{value} can be a literal string, in which case it is base32-decoded,
7877 or it can be a bytevector.
7879 The following forms are all equivalent:
7882 (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj")
7883 (content-hash "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"
7885 (content-hash (base32
7886 "05zxkyz9bv3j9h0xyid1rhvh3klhsmrpkf3bcs6frvlgyr2gwilj"))
7887 (content-hash (base64 "kkb+RPaP7uyMZmu4eXPVkM4BN8yhRd8BTHLslb6f/Rc=")
7891 Technically, @code{content-hash} is currently implemented as a macro.
7892 It performs sanity checks at macro-expansion time, when possible, such
7893 as ensuring that @var{value} has the right size for @var{algorithm}.
7896 As we have seen above, how exactly the data an origin refers to is
7897 retrieved is determined by its @code{method} field. The @code{(guix
7898 download)} module provides the most common method, @code{url-fetch},
7901 @deffn {Scheme Procedure} url-fetch @var{url} @var{hash-algo} @var{hash} @
7902 [name] [#:executable? #f]
7903 Return a fixed-output derivation that fetches data from @var{url} (a
7904 string, or a list of strings denoting alternate URLs), which is expected
7905 to have hash @var{hash} of type @var{hash-algo} (a symbol). By default,
7906 the file name is the base name of URL; optionally, @var{name} can
7907 specify a different file name. When @var{executable?} is true, make the
7908 downloaded file executable.
7910 When one of the URL starts with @code{mirror://}, then its host part is
7911 interpreted as the name of a mirror scheme, taken from @file{%mirror-file}.
7913 Alternatively, when URL starts with @code{file://}, return the
7914 corresponding file name in the store.
7917 Likewise, the @code{(guix git-download)} module defines the
7918 @code{git-fetch} origin method, which fetches data from a Git version
7919 control repository, and the @code{git-reference} data type to describe
7920 the repository and revision to fetch.
7922 @deffn {Scheme Procedure} git-fetch @var{ref} @var{hash-algo} @var{hash}
7923 Return a fixed-output derivation that fetches @var{ref}, a
7924 @code{<git-reference>} object. The output is expected to have recursive
7925 hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
7926 the file name, or a generic name if @code{#f}.
7929 @deftp {Data Type} git-reference
7930 This data type represents a Git reference for @code{git-fetch} to
7935 The URL of the Git repository to clone.
7938 This string denotes either the commit to fetch (a hexadecimal string),
7939 or the tag to fetch. You can also use a ``short'' commit ID or a
7940 @command{git describe} style identifier such as
7941 @code{v1.0.1-10-g58d7909c97}.
7943 @item @code{recursive?} (default: @code{#f})
7944 This Boolean indicates whether to recursively fetch Git sub-modules.
7947 The example below denotes the @code{v2.10} tag of the GNU@tie{}Hello
7952 (url "https://git.savannah.gnu.org/git/hello.git")
7956 This is equivalent to the reference below, which explicitly names the
7961 (url "https://git.savannah.gnu.org/git/hello.git")
7962 (commit "dc7dc56a00e48fe6f231a58f6537139fe2908fb9"))
7966 For Mercurial repositories, the module @code{(guix hg-download)} defines
7967 the @code{hg-fetch} origin method and @code{hg-reference} data type for
7968 support of the Mercurial version control system.
7970 @deffn {Scheme Procedure} hg-fetch @var{ref} @var{hash-algo} @var{hash} @
7972 Return a fixed-output derivation that fetches @var{ref}, a
7973 @code{<hg-reference>} object. The output is expected to have recursive
7974 hash @var{hash} of type @var{hash-algo} (a symbol). Use @var{name} as
7975 the file name, or a generic name if @code{#false}.
7978 @node Defining Package Variants
7979 @section Defining Package Variants
7981 @cindex customizing packages
7982 @cindex variants, of packages
7983 One of the nice things with Guix is that, given a package definition,
7984 you can easily @emph{derive} variants of that package---for a different
7985 upstream version, with different dependencies, different compilation
7986 options, and so on. Some of these custom packages can be defined
7987 straight from the command line (@pxref{Package Transformation Options}).
7988 This section describes how to define package variants in code. This can
7989 be useful in ``manifests'' (@pxref{Writing Manifests})
7990 and in your own package collection
7991 (@pxref{Creating a Channel}), among others!
7993 @cindex inherit, for package definitions
7994 As discussed earlier, packages are first-class objects in the Scheme
7995 language. The @code{(guix packages)} module provides the @code{package}
7996 construct to define new package objects (@pxref{package Reference}).
7997 The easiest way to define a package variant is using the @code{inherit}
7998 keyword together with @code{package}. This allows you to inherit from a
7999 package definition while overriding the fields you want.
8001 For example, given the @code{hello} variable, which contains a
8002 definition for the current version of GNU@tie{}Hello, here's how you
8003 would define a variant for version 2.2 (released in 2006, it's
8007 (use-modules (gnu packages base)) ;for 'hello'
8015 (uri (string-append "mirror://gnu/hello/hello-" version
8019 "0lappv4slgb5spyqbh6yl5r013zv72yqg2pcl30mginf3wdqd8k9"))))))
8022 The example above corresponds to what the @option{--with-source} package
8023 transformation option does. Essentially @code{hello-2.2} preserves all
8024 the fields of @code{hello}, except @code{version} and @code{source},
8025 which it overrides. Note that the original @code{hello} variable is
8026 still there, in the @code{(gnu packages base)} module, unchanged. When
8027 you define a custom package like this, you are really @emph{adding} a
8028 new package definition; the original one remains available.
8030 You can just as well define variants with a different set of
8031 dependencies than the original package. For example, the default
8032 @code{gdb} package depends on @code{guile}, but since that is an
8033 optional dependency, you can define a variant that removes that
8037 (use-modules (gnu packages gdb)) ;for 'gdb'
8039 (define gdb-sans-guile
8042 (inputs (modify-inputs (package-inputs gdb)
8043 (delete "guile")))))
8046 The @code{modify-inputs} form above removes the @code{"guile"} package
8047 from the @code{inputs} field of @code{gdb}. The @code{modify-inputs}
8048 macro is a helper that can prove useful anytime you want to remove, add,
8049 or replace package inputs.
8051 @deffn {Scheme Syntax} modify-inputs @var{inputs} @var{clauses}
8052 Modify the given package inputs, as returned by @code{package-inputs} & co.,
8053 according to the given clauses. Each clause must have one of the
8057 @item (delete @var{name}@dots{})
8058 Delete from the inputs packages with the given @var{name}s (strings).
8060 @item (append @var{package}@dots{})
8061 Add @var{package}s to the end of the input list.
8063 @item (prepend @var{package}@dots{})
8064 Add @var{package}s to the front of the input list.
8067 The example below removes the GMP and ACL inputs of Coreutils and adds
8068 libcap to the back of the input list:
8071 (modify-inputs (package-inputs coreutils)
8072 (delete "gmp" "acl")
8076 The example below replaces the @code{guile} package from the inputs of
8077 @code{guile-redis} with @code{guile-2.2}:
8080 (modify-inputs (package-inputs guile-redis)
8081 (replace "guile" guile-2.2))
8084 The last type of clause is @code{prepend}, to add inputs to the front of
8088 In some cases, you may find it useful to write functions
8089 (``procedures'', in Scheme parlance) that return a package based on some
8090 parameters. For example, consider the @code{luasocket} library for the
8091 Lua programming language. We want to create @code{luasocket} packages
8092 for major versions of Lua. One way to do that is to define a procedure
8093 that takes a Lua package and returns a @code{luasocket} package that
8097 (define (make-lua-socket name lua)
8098 ;; Return a luasocket package built with LUA.
8102 ;; several fields omitted
8104 (synopsis "Socket library for Lua")))
8106 (define-public lua5.1-socket
8107 (make-lua-socket "lua5.1-socket" lua-5.1))
8109 (define-public lua5.2-socket
8110 (make-lua-socket "lua5.2-socket" lua-5.2))
8113 Here we have defined packages @code{lua5.1-socket} and
8114 @code{lua5.2-socket} by calling @code{make-lua-socket} with different
8115 arguments. @xref{Procedures,,, guile, GNU Guile Reference Manual}, for
8116 more info on procedures. Having top-level public definitions for these
8117 two packages means that they can be referred to from the command line
8118 (@pxref{Package Modules}).
8120 @cindex package transformations
8121 These are pretty simple package variants. As a convenience, the
8122 @code{(guix transformations)} module provides a high-level interface
8123 that directly maps to the more sophisticated package transformation
8124 options (@pxref{Package Transformation Options}):
8126 @deffn {Scheme Procedure} options->transformation @var{opts}
8127 Return a procedure that, when passed an object to build (package,
8128 derivation, etc.), applies the transformations specified by @var{opts} and returns
8129 the resulting objects. @var{opts} must be a list of symbol/string pairs such as:
8132 ((with-branch . "guile-gcrypt=master")
8133 (without-tests . "libgcrypt"))
8136 Each symbol names a transformation and the corresponding string is an argument
8137 to that transformation.
8140 For instance, a manifest equivalent to this command:
8144 --with-branch=guile-gcrypt=master \
8145 --with-debug-info=zlib
8149 ... would look like this:
8152 (use-modules (guix transformations))
8155 ;; The package transformation procedure.
8156 (options->transformation
8157 '((with-branch . "guile-gcrypt=master")
8158 (with-debug-info . "zlib"))))
8161 (list (transform (specification->package "guix"))))
8164 @cindex input rewriting
8165 @cindex dependency graph rewriting
8166 The @code{options->transformation} procedure is convenient, but it's
8167 perhaps also not as flexible as you may like. How is it implemented?
8168 The astute reader probably noticed that most package transformation
8169 options go beyond the superficial changes shown in the first examples of
8170 this section: they involve @dfn{input rewriting}, whereby the dependency
8171 graph of a package is rewritten by replacing specific inputs by others.
8173 Dependency graph rewriting, for the purposes of swapping packages in the
8174 graph, is what the @code{package-input-rewriting} procedure in
8175 @code{(guix packages)} implements.
8177 @deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
8178 [@var{rewrite-name}] [#:deep? #t]
8179 Return a procedure that, when passed a package, replaces its direct and
8180 indirect dependencies, including implicit inputs when @var{deep?} is
8181 true, according to @var{replacements}. @var{replacements} is a list of
8182 package pairs; the first element of each pair is the package to replace,
8183 and the second one is the replacement.
8185 Optionally, @var{rewrite-name} is a one-argument procedure that takes
8186 the name of a package and returns its new name after rewrite.
8190 Consider this example:
8193 (define libressl-instead-of-openssl
8194 ;; This is a procedure to replace OPENSSL by LIBRESSL,
8196 (package-input-rewriting `((,openssl . ,libressl))))
8198 (define git-with-libressl
8199 (libressl-instead-of-openssl git))
8203 Here we first define a rewriting procedure that replaces @var{openssl}
8204 with @var{libressl}. Then we use it to define a @dfn{variant} of the
8205 @var{git} package that uses @var{libressl} instead of @var{openssl}.
8206 This is exactly what the @option{--with-input} command-line option does
8207 (@pxref{Package Transformation Options, @option{--with-input}}).
8209 The following variant of @code{package-input-rewriting} can match packages to
8210 be replaced by name rather than by identity.
8212 @deffn {Scheme Procedure} package-input-rewriting/spec @var{replacements} [#:deep? #t]
8213 Return a procedure that, given a package, applies the given
8214 @var{replacements} to all the package graph, including implicit inputs
8215 unless @var{deep?} is false. @var{replacements} is a list of
8216 spec/procedures pair; each spec is a package specification such as
8217 @code{"gcc"} or @code{"guile@@2"}, and each procedure takes a matching
8218 package and returns a replacement for that package.
8221 The example above could be rewritten this way:
8224 (define libressl-instead-of-openssl
8225 ;; Replace all the packages called "openssl" with LibreSSL.
8226 (package-input-rewriting/spec `(("openssl" . ,(const libressl)))))
8229 The key difference here is that, this time, packages are matched by spec and
8230 not by identity. In other words, any package in the graph that is called
8231 @code{openssl} will be replaced.
8233 A more generic procedure to rewrite a package dependency graph is
8234 @code{package-mapping}: it supports arbitrary changes to nodes in the
8237 @deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}] [#:deep? #f]
8238 Return a procedure that, given a package, applies @var{proc} to all the packages
8239 depended on and returns the resulting package. The procedure stops recursion
8240 when @var{cut?} returns true for a given package. When @var{deep?} is true, @var{proc} is
8241 applied to implicit inputs as well.
8244 @node Writing Manifests
8245 @section Writing Manifests
8248 @cindex bill of materials (manifests)
8249 @command{guix} commands let you specify package lists on the command
8250 line. This is convenient, but as the command line becomes longer and
8251 less trivial, it quickly becomes more convenient to have that package
8252 list in what we call a @dfn{manifest}. A manifest is some sort of a
8253 ``bill of materials'' that defines a package set. You would typically
8254 come up with a code snippet that builds the manifest, store it in a
8255 file, say @file{manifest.scm}, and then pass that file to the
8256 @option{-m} (or @option{--manifest}) option that many @command{guix}
8257 commands support. For example, here's what a manifest for a simple
8258 package set might look like:
8261 ;; Manifest for three packages.
8262 (specifications->manifest '("gcc-toolchain" "make" "git"))
8265 Once you have that manifest, you can pass it, for example, to
8266 @command{guix package} to install just those three packages to your
8267 profile (@pxref{profile-manifest, @option{-m} option of @command{guix
8271 guix package -m manifest.scm
8275 ... or you can pass it to @command{guix shell} (@pxref{shell-manifest,
8276 @command{-m} option of @command{guix shell}}) to spawn an ephemeral
8280 guix shell -m manifest.scm
8284 ... or you can pass it to @command{guix pack} in pretty much the same
8285 way (@pxref{pack-manifest, @option{-m} option of @command{guix pack}}).
8286 You can store the manifest under version control, share it with others
8287 so they can easily get set up, etc.
8289 But how do you write your first manifest? To get started, maybe you'll
8290 want to write a manifest that mirrors what you already have in a
8291 profile. Rather than start from a blank page, @command{guix package}
8292 can generate a manifest for you (@pxref{export-manifest, @command{guix
8293 package --export-manifest}}):
8296 # Write to 'manifest.scm' a manifest corresponding to the
8297 # default profile, ~/.guix-profile.
8298 guix package --export-manifest > manifest.scm
8301 Or maybe you'll want to ``translate'' command-line arguments into a
8302 manifest. In that case, @command{guix shell} can help
8303 (@pxref{shell-export-manifest, @command{guix shell --export-manifest}}):
8306 # Write a manifest for the packages specified on the command line.
8307 guix shell --export-manifest gcc-toolchain make git > manifest.scm
8310 In both cases, the @option{--export-manifest} option tries hard to
8311 generate a faithful manifest; in particular, it takes package
8312 transformation options into account (@pxref{Package Transformation
8316 Manifests are @emph{symbolic}: they refer to packages of the channels
8317 @emph{currently in use} (@pxref{Channels}). In the example above,
8318 @code{gcc-toolchain} might refer to version 11 today, but it might refer
8319 to version 13 two years from now.
8321 If you want to ``pin'' your software environment to specific package
8322 versions and variants, you need an additional piece of information: the
8323 list of channel revisions in use, as returned by @command{guix
8324 describe}. @xref{Replicating Guix}, for more information.
8327 Once you've obtained your first manifest, perhaps you'll want to
8328 customize it. Since your manifest is code, you now have access to all
8329 the Guix programming interfaces!
8331 Let's assume you want a manifest to deploy a custom variant of GDB, the
8332 GNU Debugger, that does not depend on Guile, together with another
8333 package. Building on the example seen in the previous section
8334 (@pxref{Defining Package Variants}), you can write a manifest along
8338 (use-modules (guix packages)
8339 (gnu packages gdb) ;for 'gdb'
8340 (gnu packages version-control)) ;for 'git'
8342 ;; Define a variant of GDB without a dependency on Guile.
8343 (define gdb-sans-guile
8346 (inputs (modify-inputs (package-inputs gdb)
8347 (delete "guile")))))
8349 ;; Return a manifest containing that one package plus Git.
8350 (packages->manifest (list gdb-sans-guile git))
8353 Note that in this example, the manifest directly refers to the
8354 @code{gdb} and @code{git} variables, which are bound to a @code{package}
8355 object (@pxref{package Reference}), instead of calling
8356 @code{specifications->manifest} to look up packages by name as we did
8357 before. The @code{use-modules} form at the top lets us access the core
8358 package interface (@pxref{Defining Packages}) and the modules that
8359 define @code{gdb} and @code{git} (@pxref{Package Modules}). Seamlessly,
8360 we're weaving all this together---the possibilities are endless, unleash
8363 The data type for manifests as well as supporting procedures are defined
8364 in the @code{(guix profiles)} module, which is automatically available
8365 to code passed to @option{-m}. The reference follows.
8367 @deftp {Data Type} manifest
8368 Data type representing a manifest.
8370 It currently has one field:
8374 This must be a list of @code{manifest-entry} records---see below.
8378 @deftp {Data Type} manifest-entry
8379 Data type representing a manifest entry. A manifest entry contains
8380 essential metadata: a name and version string, the object (usually a
8381 package) for that entry, the desired output (@pxref{Packages with
8382 Multiple Outputs}), and a number of optional pieces of information
8385 Most of the time, you won't build a manifest entry directly; instead,
8386 you will pass a package to @code{package->manifest-entry}, described
8387 below. In some unusual cases though, you might want to create manifest
8388 entries for things that are @emph{not} packages, as in this example:
8391 ;; Manually build a single manifest entry for a non-package object.
8392 (let ((hello (program-file "hello" #~(display "Hi!"))))
8397 (computed-file "hello-directory"
8398 #~(let ((bin (string-append #$output "/bin")))
8399 (mkdir #$output) (mkdir bin)
8401 (string-append bin "/hello")))))))
8404 The available fields are the following:
8408 @itemx @code{version}
8409 Name and version string for this entry.
8412 A package or other file-like object (@pxref{G-Expressions, file-like
8415 @item @code{output} (default: @code{"out"})
8416 Output of @code{item} to use, in case @code{item} has multiple outputs
8417 (@pxref{Packages with Multiple Outputs}).
8419 @item @code{dependencies} (default: @code{'()})
8420 List of manifest entries this entry depends on. When building a
8421 profile, dependencies are added to the profile.
8423 Typically, the propagated inputs of a package (@pxref{package Reference,
8424 @code{propagated-inputs}}) end up having a corresponding manifest entry
8425 in among the dependencies of the package's own manifest entry.
8427 @item @code{search-paths} (default: @code{'()})
8428 The list of search path specifications honored by this entry
8429 (@pxref{Search Paths}).
8431 @item @code{properties} (default: @code{'()})
8432 List of symbol/value pairs. When building a profile, those properties
8435 This can be used to piggyback additional metadata---e.g., the
8436 transformations applied to a package (@pxref{Package Transformation
8439 @item @code{parent} (default: @code{(delay #f)})
8440 A promise pointing to the ``parent'' manifest entry.
8442 This is used as a hint to provide context when reporting an error
8443 related to a manifest entry coming from a @code{dependencies} field.
8447 @deffn {Scheme Procedure} concatenate-manifests @var{lst}
8448 Concatenate the manifests listed in @var{lst} and return the resulting
8452 @c TODO: <manifest-pattern>, manifest-lookup, manifest-remove, etc.
8454 @deffn {Scheme Procedure} package->manifest-entry @var{package} @
8455 [@var{output}] [#:properties]
8456 Return a manifest entry for the @var{output} of package @var{package},
8457 where @var{output} defaults to @code{"out"}, and with the given
8458 @var{properties}. By default @var{properties} is the empty list or, if
8459 one or more package transformations were applied to @var{package}, it is
8460 an association list representing those transformations, suitable as an
8461 argument to @code{options->transformation} (@pxref{Defining Package
8462 Variants, @code{options->transformation}}).
8464 The code snippet below builds a manifest with an entry for the default
8465 output and the @code{send-email} output of the @code{git} package:
8468 (use-modules (gnu packages version-control))
8470 (manifest (list (package->manifest-entry git)
8471 (package->manifest-entry git "send-email")))
8475 @deffn {Scheme Procedure} packages->manifest @var{packages}
8476 Return a list of manifest entries, one for each item listed in
8477 @var{packages}. Elements of @var{packages} can be either package
8478 objects or package/string tuples denoting a specific output of a
8481 Using this procedure, the manifest above may be rewritten more
8485 (use-modules (gnu packages version-control))
8487 (packages->manifest (list git `(,git "send-email")))
8491 @anchor{package-development-manifest}
8492 @deffn {Scheme Procedure} package->development-manifest @var{package} @
8493 [@var{system}] [#:target]
8494 Return a manifest for the @dfn{development inputs} of @var{package} for
8495 @var{system}, optionally when cross-compiling to @var{target}.
8496 Development inputs include both explicit and implicit inputs of
8499 Like the @option{-D} option of @command{guix shell}
8500 (@pxref{shell-development-option, @command{guix shell -D}}), the
8501 resulting manifest describes the environment in which one can develop
8502 @var{package}. For example, suppose you're willing to set up a
8503 development environment for Inkscape, with the addition of Git for
8504 version control; you can describe that ``bill of materials'' with the
8508 (use-modules (gnu packages inkscape) ;for 'inkscape'
8509 (gnu packages version-control)) ;for 'git'
8511 (concatenate-manifests
8512 (list (package->development-manifest inkscape)
8513 (packages->manifest (list git))))
8516 In this example, the development manifest that
8517 @code{package->development-manifest} returns includes the compiler
8518 (GCC), the many supporting libraries (Boost, GLib, GTK, etc.), and a
8519 couple of additional development tools---these are the dependencies
8520 @command{guix show inkscape} lists.
8523 @c TODO: Move (gnu packages) interface to a section of its own.
8525 Last, the @code{(gnu packages)} module provides higher-level facilities
8526 to build manifests. In particular, it lets you look up packages by
8529 @deffn {Scheme Procedure} specifications->manifest @var{specs}
8530 Given @var{specs}, a list of specifications such as @code{"emacs@@25.2"}
8531 or @code{"guile:debug"}, return a manifest. Specs have the format that
8532 command-line tools such as @command{guix install} and @command{guix
8533 package} understand (@pxref{Invoking guix package}).
8535 As an example, it lets you rewrite the Git manifest that we saw earlier
8539 (specifications->manifest '("git" "git:send-email"))
8542 Notice that we do not need to worry about @code{use-modules}, importing
8543 the right set of modules, and referring to the right variables.
8544 Instead, we directly refer to packages in the same way as on the command
8545 line, which can often be more convenient.
8548 @c TODO: specifications->package, etc.
8552 @section Build Systems
8554 @cindex build system
8555 Each package definition specifies a @dfn{build system} and arguments for
8556 that build system (@pxref{Defining Packages}). This @code{build-system}
8557 field represents the build procedure of the package, as well as implicit
8558 dependencies of that build procedure.
8560 Build systems are @code{<build-system>} objects. The interface to
8561 create and manipulate them is provided by the @code{(guix build-system)}
8562 module, and actual build systems are exported by specific modules.
8564 @cindex bag (low-level package representation)
8565 Under the hood, build systems first compile package objects to
8566 @dfn{bags}. A @dfn{bag} is like a package, but with less
8567 ornamentation---in other words, a bag is a lower-level representation of
8568 a package, which includes all the inputs of that package, including some
8569 that were implicitly added by the build system. This intermediate
8570 representation is then compiled to a derivation (@pxref{Derivations}).
8571 The @code{package-with-c-toolchain} is an example of a way to change the
8572 implicit inputs that a package's build system pulls in (@pxref{package
8573 Reference, @code{package-with-c-toolchain}}).
8575 Build systems accept an optional list of @dfn{arguments}. In package
8576 definitions, these are passed @i{via} the @code{arguments} field
8577 (@pxref{Defining Packages}). They are typically keyword arguments
8578 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU
8579 Guile Reference Manual}). The value of these arguments is usually
8580 evaluated in the @dfn{build stratum}---i.e., by a Guile process launched
8581 by the daemon (@pxref{Derivations}).
8583 The main build system is @code{gnu-build-system}, which implements the
8584 standard build procedure for GNU and many other packages. It
8585 is provided by the @code{(guix build-system gnu)} module.
8587 @defvr {Scheme Variable} gnu-build-system
8588 @code{gnu-build-system} represents the GNU Build System, and variants
8589 thereof (@pxref{Configuration, configuration and makefile conventions,,
8590 standards, GNU Coding Standards}).
8592 @cindex build phases
8593 In a nutshell, packages using it are configured, built, and installed with
8594 the usual @code{./configure && make && make check && make install}
8595 command sequence. In practice, a few additional steps are often needed.
8596 All these steps are split up in separate @dfn{phases}.
8597 @xref{Build Phases}, for more info on build phases and ways to customize
8600 In addition, this build system ensures that the ``standard'' environment
8601 for GNU packages is available. This includes tools such as GCC, libc,
8602 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
8603 build-system gnu)} module for a complete list). We call these the
8604 @dfn{implicit inputs} of a package, because package definitions do not
8605 have to mention them.
8607 This build system supports a number of keyword arguments, which can be
8608 passed @i{via} the @code{arguments} field of a package. Here are some
8609 of the main parameters:
8613 This argument specifies build-side code that evaluates to an alist of
8614 build phases. @xref{Build Phases}, for more information.
8616 @item #:configure-flags
8617 This is a list of flags (strings) passed to the @command{configure}
8618 script. @xref{Defining Packages}, for an example.
8621 This list of strings contains flags passed as arguments to
8622 @command{make} invocations in the @code{build}, @code{check}, and
8623 @code{install} phases.
8625 @item #:out-of-source?
8626 This Boolean, @code{#f} by default, indicates whether to run builds in a
8627 build directory separate from the source tree.
8629 When it is true, the @code{configure} phase creates a separate build
8630 directory, changes to that directory, and runs the @code{configure}
8631 script from there. This is useful for packages that require it, such as
8635 This Boolean, @code{#t} by default, indicates whether the @code{check}
8636 phase should run the package's test suite.
8639 This string, @code{"check"} by default, gives the name of the makefile
8640 target used by the @code{check} phase.
8642 @item #:parallel-build?
8643 @itemx #:parallel-tests?
8644 These Boolean values specify whether to build, respectively run the test
8645 suite, in parallel, with the @code{-j} flag of @command{make}. When
8646 they are true, @code{make} is passed @code{-j@var{n}}, where @var{n} is
8647 the number specified as the @option{--cores} option of
8648 @command{guix-daemon} or that of the @command{guix} client command
8649 (@pxref{Common Build Options, @option{--cores}}).
8651 @cindex RUNPATH, validation
8652 @item #:validate-runpath?
8653 This Boolean, @code{#t} by default, determines whether to ``validate''
8654 the @code{RUNPATH} of ELF binaries (@code{.so} shared libraries as well
8655 as executables) previously installed by the @code{install} phase.
8656 @xref{phase-validate-runpath, the @code{validate-runpath} phase}, for
8659 @item #:substitutable?
8660 This Boolean, @code{#t} by default, tells whether the package outputs
8661 should be substitutable---i.e., whether users should be able to obtain
8662 substitutes for them instead of building locally (@pxref{Substitutes}).
8664 @item #:allowed-references
8665 @itemx #:disallowed-references
8666 When true, these arguments must be a list of dependencies that must not
8667 appear among the references of the build results. If, upon build
8668 completion, some of these references are retained, the build process
8671 This is useful to ensure that a package does not erroneously keep a
8672 reference to some of it build-time inputs, in cases where doing so
8673 would, for example, unnecessarily increase its size (@pxref{Invoking
8677 Most other build systems support these keyword arguments.
8680 Other @code{<build-system>} objects are defined to support other
8681 conventions and tools used by free software packages. They inherit most
8682 of @code{gnu-build-system}, and differ mainly in the set of inputs
8683 implicitly added to the build process, and in the list of phases
8684 executed. Some of these build systems are listed below.
8686 @defvr {Scheme Variable} ant-build-system
8687 This variable is exported by @code{(guix build-system ant)}. It
8688 implements the build procedure for Java packages that can be built with
8689 @url{https://ant.apache.org/, Ant build tool}.
8691 It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as
8692 provided by the @code{icedtea} package to the set of inputs. Different
8693 packages can be specified with the @code{#:ant} and @code{#:jdk}
8694 parameters, respectively.
8696 When the original package does not provide a suitable Ant build file,
8697 the parameter @code{#:jar-name} can be used to generate a minimal Ant
8698 build file @file{build.xml} with tasks to build the specified jar
8699 archive. In this case the parameter @code{#:source-dir} can be used to
8700 specify the source sub-directory, defaulting to ``src''.
8702 The @code{#:main-class} parameter can be used with the minimal ant
8703 buildfile to specify the main class of the resulting jar. This makes the
8704 jar file executable. The @code{#:test-include} parameter can be used to
8705 specify the list of junit tests to run. It defaults to
8706 @code{(list "**/*Test.java")}. The @code{#:test-exclude} can be used to
8707 disable some tests. It defaults to @code{(list "**/Abstract*.java")},
8708 because abstract classes cannot be run as tests.
8710 The parameter @code{#:build-target} can be used to specify the Ant task
8711 that should be run during the @code{build} phase. By default the
8712 ``jar'' task will be run.
8716 @defvr {Scheme Variable} android-ndk-build-system
8717 @cindex Android distribution
8718 @cindex Android NDK build system
8719 This variable is exported by @code{(guix build-system android-ndk)}. It
8720 implements a build procedure for Android NDK (native development kit)
8721 packages using a Guix-specific build process.
8723 The build system assumes that packages install their public interface
8724 (header) files to the subdirectory @file{include} of the @code{out} output and
8725 their libraries to the subdirectory @file{lib} the @code{out} output.
8727 It's also assumed that the union of all the dependencies of a package
8728 has no conflicting files.
8730 For the time being, cross-compilation is not supported - so right now
8731 the libraries and header files are assumed to be host tools.
8735 @defvr {Scheme Variable} asdf-build-system/source
8736 @defvrx {Scheme Variable} asdf-build-system/sbcl
8737 @defvrx {Scheme Variable} asdf-build-system/ecl
8739 These variables, exported by @code{(guix build-system asdf)}, implement
8740 build procedures for Common Lisp packages using
8741 @url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
8742 definition facility for Common Lisp programs and libraries.
8744 The @code{asdf-build-system/source} system installs the packages in
8745 source form, and can be loaded using any common lisp implementation, via
8746 ASDF@. The others, such as @code{asdf-build-system/sbcl}, install binary
8747 systems in the format which a particular implementation understands.
8748 These build systems can also be used to produce executable programs, or
8749 lisp images which contain a set of packages pre-loaded.
8751 The build system uses naming conventions. For binary packages, the
8752 package name should be prefixed with the lisp implementation, such as
8753 @code{sbcl-} for @code{asdf-build-system/sbcl}.
8755 Additionally, the corresponding source package should be labeled using
8756 the same convention as python packages (see @ref{Python Modules}), using
8757 the @code{cl-} prefix.
8759 In order to create executable programs and images, the build-side
8760 procedures @code{build-program} and @code{build-image} can be used.
8761 They should be called in a build phase after the
8762 @code{create-asdf-configuration} phase, so that the system which was
8763 just built can be used within the resulting image. @code{build-program}
8764 requires a list of Common Lisp expressions to be passed as the
8765 @code{#:entry-program} argument.
8767 By default, all the @file{.asd} files present in the sources are read to
8768 find system definitions. The @code{#:asd-files} parameter can be used
8769 to specify the list of @file{.asd} files to read. Furthermore, if the
8770 package defines a system for its tests in a separate file, it will be
8771 loaded before the tests are run if it is specified by the
8772 @code{#:test-asd-file} parameter. If it is not set, the files
8773 @code{<system>-tests.asd}, @code{<system>-test.asd}, @code{tests.asd},
8774 and @code{test.asd} will be tried if they exist.
8776 If for some reason the package must be named in a different way than the
8777 naming conventions suggest, or if several systems must be compiled, the
8778 @code{#:asd-systems} parameter can be used to specify the list of system
8783 @defvr {Scheme Variable} cargo-build-system
8784 @cindex Rust programming language
8785 @cindex Cargo (Rust build system)
8786 This variable is exported by @code{(guix build-system cargo)}. It
8787 supports builds of packages using Cargo, the build tool of the
8788 @uref{https://www.rust-lang.org, Rust programming language}.
8790 It adds @code{rustc} and @code{cargo} to the set of inputs.
8791 A different Rust package can be specified with the @code{#:rust} parameter.
8793 Regular cargo dependencies should be added to the package definition similarly
8794 to other packages; those needed only at build time to native-inputs, others to
8795 inputs. If you need to add source-only crates then you should add them to via
8796 the @code{#:cargo-inputs} parameter as a list of name and spec pairs, where the
8797 spec can be a package or a source definition. Note that the spec must
8798 evaluate to a path to a gzipped tarball which includes a @code{Cargo.toml}
8799 file at its root, or it will be ignored. Similarly, cargo dev-dependencies
8800 should be added to the package definition via the
8801 @code{#:cargo-development-inputs} parameter.
8803 In its @code{configure} phase, this build system will make any source inputs
8804 specified in the @code{#:cargo-inputs} and @code{#:cargo-development-inputs}
8805 parameters available to cargo. It will also remove an included
8806 @code{Cargo.lock} file to be recreated by @code{cargo} during the
8807 @code{build} phase. The @code{package} phase will run @code{cargo package}
8808 to create a source crate for future use. The @code{install} phase installs
8809 the binaries defined by the crate. Unless @code{install-source? #f} is
8810 defined it will also install a source crate repository of itself and unpacked
8811 sources, to ease in future hacking on rust packages.
8814 @defvr {Scheme Variable} chicken-build-system
8815 This variable is exported by @code{(guix build-system chicken)}. It
8816 builds @uref{https://call-cc.org/, CHICKEN Scheme} modules, also called
8817 ``eggs'' or ``extensions''. CHICKEN generates C source code, which then
8818 gets compiled by a C compiler, in this case GCC.
8820 This build system adds @code{chicken} to the package inputs, as well as
8821 the packages of @code{gnu-build-system}.
8823 The build system can't (yet) deduce the egg's name automatically, so just like
8824 with @code{go-build-system} and its @code{#:import-path}, you should define
8825 @code{#:egg-name} in the package's @code{arguments} field.
8827 For example, if you are packaging the @code{srfi-1} egg:
8830 (arguments '(#:egg-name "srfi-1"))
8833 Egg dependencies must be defined in @code{propagated-inputs}, not @code{inputs}
8834 because CHICKEN doesn't embed absolute references in compiled eggs.
8835 Test dependencies should go to @code{native-inputs}, as usual.
8838 @defvr {Scheme Variable} copy-build-system
8839 This variable is exported by @code{(guix build-system copy)}. It
8840 supports builds of simple packages that don't require much compiling,
8841 mostly just moving files around.
8843 It adds much of the @code{gnu-build-system} packages to the set of
8844 inputs. Because of this, the @code{copy-build-system} does not require
8845 all the boilerplate code often needed for the
8846 @code{trivial-build-system}.
8848 To further simplify the file installation process, an
8849 @code{#:install-plan} argument is exposed to let the packager specify
8850 which files go where. The install plan is a list of @code{(@var{source}
8851 @var{target} [@var{filters}])}. @var{filters} are optional.
8854 @item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
8856 @item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
8857 @item Otherwise install @var{source} as @var{target}.
8860 @item When @var{source} is a directory with a trailing slash, or when @var{filters} are used,
8861 the trailing slash of @var{target} is implied with the same meaning
8864 @item Without @var{filters}, install the full @var{source} @emph{content} to @var{target}.
8865 @item With @var{filters} among @code{#:include}, @code{#:include-regexp}, @code{#:exclude},
8866 @code{#:exclude-regexp}, only select files are installed depending on
8867 the filters. Each filters is specified by a list of strings.
8869 @item With @code{#:include}, install all the files which the path suffix matches
8870 at least one of the elements in the given list.
8871 @item With @code{#:include-regexp}, install all the files which the
8872 subpaths match at least one of the regular expressions in the given
8874 @item The @code{#:exclude} and @code{#:exclude-regexp} filters
8875 are the complement of their inclusion counterpart. Without @code{#:include} flags,
8876 install all files but those matching the exclusion filters.
8877 If both inclusions and exclusions are specified, the exclusions are done
8878 on top of the inclusions.
8881 In all cases, the paths relative to @var{source} are preserved within
8888 @item @code{("foo/bar" "share/my-app/")}: Install @file{bar} to @file{share/my-app/bar}.
8889 @item @code{("foo/bar" "share/my-app/baz")}: Install @file{bar} to @file{share/my-app/baz}.
8890 @item @code{("foo/" "share/my-app")}: Install the content of @file{foo} inside @file{share/my-app},
8891 e.g., install @file{foo/sub/file} to @file{share/my-app/sub/file}.
8892 @item @code{("foo/" "share/my-app" #:include ("sub/file"))}: Install only @file{foo/sub/file} to
8893 @file{share/my-app/sub/file}.
8894 @item @code{("foo/sub" "share/my-app" #:include ("file"))}: Install @file{foo/sub/file} to
8895 @file{share/my-app/file}.
8900 @cindex Clojure (programming language)
8901 @cindex simple Clojure build system
8902 @defvr {Scheme Variable} clojure-build-system
8903 This variable is exported by @code{(guix build-system clojure)}. It implements
8904 a simple build procedure for @uref{https://clojure.org/, Clojure} packages
8905 using plain old @code{compile} in Clojure. Cross-compilation is not supported
8908 It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
8909 Different packages can be specified with the @code{#:clojure}, @code{#:jdk} and
8910 @code{#:zip} parameters, respectively.
8912 A list of source directories, test directories and jar names can be specified
8913 with the @code{#:source-dirs}, @code{#:test-dirs} and @code{#:jar-names}
8914 parameters, respectively. Compile directory and main class can be specified
8915 with the @code{#:compile-dir} and @code{#:main-class} parameters, respectively.
8916 Other parameters are documented below.
8918 This build system is an extension of @code{ant-build-system}, but with the
8919 following phases changed:
8924 This phase calls @code{compile} in Clojure to compile source files and runs
8925 @command{jar} to create jars from both source files and compiled files
8926 according to the include list and exclude list specified in
8927 @code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude list
8928 has priority over the include list. These lists consist of symbols
8929 representing Clojure libraries or the special keyword @code{#:all} representing
8930 all Clojure libraries found under the source directories. The parameter
8931 @code{#:omit-source?} decides if source should be included into the jars.
8934 This phase runs tests according to the include list and exclude list specified
8935 in @code{#:test-include} and @code{#:test-exclude}, respectively. Their
8936 meanings are analogous to that of @code{#:aot-include} and
8937 @code{#:aot-exclude}, except that the special keyword @code{#:all} now
8938 stands for all Clojure libraries found under the test directories. The
8939 parameter @code{#:tests?} decides if tests should be run.
8942 This phase installs all jars built previously.
8945 Apart from the above, this build system also contains an additional phase:
8950 This phase installs all top-level files with base name matching
8951 @code{%doc-regex}. A different regex can be specified with the
8952 @code{#:doc-regex} parameter. All files (recursively) inside the documentation
8953 directories specified in @code{#:doc-dirs} are installed as well.
8957 @defvr {Scheme Variable} cmake-build-system
8958 This variable is exported by @code{(guix build-system cmake)}. It
8959 implements the build procedure for packages using the
8960 @url{https://www.cmake.org, CMake build tool}.
8962 It automatically adds the @code{cmake} package to the set of inputs.
8963 Which package is used can be specified with the @code{#:cmake}
8966 The @code{#:configure-flags} parameter is taken as a list of flags
8967 passed to the @command{cmake} command. The @code{#:build-type}
8968 parameter specifies in abstract terms the flags passed to the compiler;
8969 it defaults to @code{"RelWithDebInfo"} (short for ``release mode with
8970 debugging information''), which roughly means that code is compiled with
8971 @code{-O2 -g}, as is the case for Autoconf-based packages by default.
8974 @defvr {Scheme Variable} dune-build-system
8975 This variable is exported by @code{(guix build-system dune)}. It
8976 supports builds of packages using @uref{https://dune.build/, Dune}, a build
8977 tool for the OCaml programming language. It is implemented as an extension
8978 of the @code{ocaml-build-system} which is described below. As such, the
8979 @code{#:ocaml} and @code{#:findlib} parameters can be passed to this build
8982 It automatically adds the @code{dune} package to the set of inputs.
8983 Which package is used can be specified with the @code{#:dune}
8986 There is no @code{configure} phase because dune packages typically don't
8987 need to be configured. The @code{#:build-flags} parameter is taken as a
8988 list of flags passed to the @code{dune} command during the build.
8990 The @code{#:jbuild?} parameter can be passed to use the @code{jbuild}
8991 command instead of the more recent @code{dune} command while building
8992 a package. Its default value is @code{#f}.
8994 The @code{#:package} parameter can be passed to specify a package name, which
8995 is useful when a package contains multiple packages and you want to build
8996 only one of them. This is equivalent to passing the @code{-p} argument to
9001 @defvr {Scheme variable} elm-build-system
9002 This variable is exported by @code{(guix build-system elm)}. It implements a
9003 build procedure for @url{https://elm-lang.org, Elm} packages similar to
9006 The build system adds an Elm compiler package to the set of inputs. The
9007 default compiler package (currently @code{elm-sans-reactor}) can be overridden
9008 using the @code{#:elm} argument. Additionally, Elm packages needed by the
9009 build system itself are added as implicit inputs if they are not already
9010 present: to suppress this behavior, use the
9011 @code{#:implicit-elm-package-inputs?} argument, which is primarily useful for
9014 The @code{"dependencies"} and @code{"test-dependencies"} in an Elm package's
9015 @file{elm.json} file correspond to @code{propagated-inputs} and @code{inputs},
9018 Elm requires a particular structure for package names: @pxref{Elm Packages}
9019 for more details, including utilities provided by @code{(guix build-system
9022 There are currently a few noteworthy limitations to @code{elm-build-system}:
9026 The build system is focused on @dfn{packages} in the Elm sense of the word:
9027 Elm @dfn{projects} which declare @code{@{ "type": "package" @}} in their
9028 @file{elm.json} files. Using @code{elm-build-system} to build Elm
9029 @dfn{applications} (which declare @code{@{ "type": "application" @}}) is
9030 possible, but requires ad-hoc modifications to the build phases. For
9031 examples, see the definitions of the @code{elm-todomvc} example application and
9032 the @code{elm} package itself (because the front-end for the
9033 @samp{elm reactor} command is an Elm application).
9036 Elm supports multiple versions of a package coexisting simultaneously under
9037 @env{ELM_HOME}, but this does not yet work well with @code{elm-build-system}.
9038 This limitation primarily affects Elm applications, because they specify
9039 exact versions for their dependencies, whereas Elm packages specify supported
9040 version ranges. As a workaround, the example applications mentioned above use
9041 the @code{patch-application-dependencies} procedure provided by
9042 @code{(guix build elm-build-system)} to rewrite their @file{elm.json} files to
9043 refer to the package versions actually present in the build environment.
9044 Alternatively, Guix package transformations (@pxref{Defining Package
9045 Variants}) could be used to rewrite an application's entire dependency graph.
9048 We are not yet able to run tests for Elm projects because neither
9049 @url{https://github.com/mpizenberg/elm-test-rs, @command{elm-test-rs}} nor the
9050 Node.js-based @url{https://github.com/rtfeldman/node-test-runner,
9051 @command{elm-test}} runner has been packaged for Guix yet.
9055 @defvr {Scheme Variable} go-build-system
9056 This variable is exported by @code{(guix build-system go)}. It
9057 implements a build procedure for Go packages using the standard
9058 @url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies,
9059 Go build mechanisms}.
9061 The user is expected to provide a value for the key @code{#:import-path}
9062 and, in some cases, @code{#:unpack-path}. The
9063 @url{https://golang.org/doc/code.html#ImportPaths, import path}
9064 corresponds to the file system path expected by the package's build
9065 scripts and any referring packages, and provides a unique way to
9066 refer to a Go package. It is typically based on a combination of the
9067 package source code's remote URI and file system hierarchy structure. In
9068 some cases, you will need to unpack the package's source code to a
9069 different directory structure than the one indicated by the import path,
9070 and @code{#:unpack-path} should be used in such cases.
9072 Packages that provide Go libraries should install their source code into
9073 the built output. The key @code{#:install-source?}, which defaults to
9074 @code{#t}, controls whether or not the source code is installed. It can
9075 be set to @code{#f} for packages that only provide executable files.
9077 Packages can be cross-built, and if a specific architecture or operating
9078 system is desired then the keywords @code{#:goarch} and @code{#:goos}
9079 can be used to force the package to be built for that architecture and
9080 operating system. The combinations known to Go can be found
9081 @url{"https://golang.org/doc/install/source#environment", in their
9085 @defvr {Scheme Variable} glib-or-gtk-build-system
9086 This variable is exported by @code{(guix build-system glib-or-gtk)}. It
9087 is intended for use with packages making use of GLib or GTK+.
9089 This build system adds the following two phases to the ones defined by
9090 @code{gnu-build-system}:
9093 @item glib-or-gtk-wrap
9094 The phase @code{glib-or-gtk-wrap} ensures that programs in
9095 @file{bin/} are able to find GLib ``schemas'' and
9096 @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
9097 modules}. This is achieved by wrapping the programs in launch scripts
9098 that appropriately set the @env{XDG_DATA_DIRS} and @env{GTK_PATH}
9099 environment variables.
9101 It is possible to exclude specific package outputs from that wrapping
9102 process by listing their names in the
9103 @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful
9104 when an output is known not to contain any GLib or GTK+ binaries, and
9105 where wrapping would gratuitously add a dependency of that output on
9108 @item glib-or-gtk-compile-schemas
9109 The phase @code{glib-or-gtk-compile-schemas} makes sure that all
9110 @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
9111 GSettings schemas} of GLib are compiled. Compilation is performed by the
9112 @command{glib-compile-schemas} program. It is provided by the package
9113 @code{glib:bin} which is automatically imported by the build system.
9114 The @code{glib} package providing @command{glib-compile-schemas} can be
9115 specified with the @code{#:glib} parameter.
9118 Both phases are executed after the @code{install} phase.
9121 @defvr {Scheme Variable} guile-build-system
9122 This build system is for Guile packages that consist exclusively of Scheme
9123 code and that are so lean that they don't even have a makefile, let alone a
9124 @file{configure} script. It compiles Scheme code using @command{guild
9125 compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
9126 installs the @file{.scm} and @file{.go} files in the right place. It also
9127 installs documentation.
9129 This build system supports cross-compilation by using the
9130 @option{--target} option of @samp{guild compile}.
9132 Packages built with @code{guile-build-system} must provide a Guile package in
9133 their @code{native-inputs} field.
9136 @defvr {Scheme Variable} julia-build-system
9137 This variable is exported by @code{(guix build-system julia)}. It
9138 implements the build procedure used by @uref{https://julialang.org/,
9139 julia} packages, which essentially is similar to running @samp{julia -e
9140 'using Pkg; Pkg.add(package)'} in an environment where
9141 @env{JULIA_LOAD_PATH} contains the paths to all Julia package inputs.
9142 Tests are run by calling @code{/test/runtests.jl}.
9144 The Julia package name and uuid is read from the file
9145 @file{Project.toml}. These values can be overridden by passing the
9146 argument @code{#:julia-package-name} (which must be correctly
9147 capitalized) or @code{#:julia-package-uuid}.
9149 Julia packages usually manage their binary dependencies via
9150 @code{JLLWrappers.jl}, a Julia package that creates a module (named
9151 after the wrapped library followed by @code{_jll.jl}.
9153 To add the binary path @code{_jll.jl} packages, you need to patch the
9154 files under @file{src/wrappers/}, replacing the call to the macro
9155 @code{JLLWrappers.@@generate_wrapper_header}, adding as a second
9156 argument containing the store path the binary.
9158 As an example, in the MbedTLS Julia package, we add a build phase
9159 (@pxref{Build Phases}) to insert the absolute file name of the wrapped
9163 (add-after 'unpack 'override-binary-path
9164 (lambda* (#:key inputs #:allow-other-keys)
9165 (for-each (lambda (wrapper)
9166 (substitute* wrapper
9167 (("generate_wrapper_header.*")
9169 "generate_wrapper_header(\"MbedTLS\", \""
9170 (assoc-ref inputs "mbedtls-apache") "\")\n"))))
9171 ;; There's a Julia file for each platform, override them all.
9172 (find-files "src/wrappers/" "\\.jl$"))))
9175 Some older packages that aren't using @file{Project.toml} yet, will
9176 require this file to be created, too. It is internally done if the
9177 arguments @code{#:julia-package-name} and @code{#:julia-package-uuid}
9181 @defvr {Scheme Variable} maven-build-system
9182 This variable is exported by @code{(guix build-system maven)}. It implements
9183 a build procedure for @uref{https://maven.apache.org, Maven} packages. Maven
9184 is a dependency and lifecycle management tool for Java. A user of Maven
9185 specifies dependencies and plugins in a @file{pom.xml} file that Maven reads.
9186 When Maven does not have one of the dependencies or plugins in its repository,
9187 it will download them and use them to build the package.
9189 The maven build system ensures that maven will not try to download any
9190 dependency by running in offline mode. Maven will fail if a dependency is
9191 missing. Before running Maven, the @file{pom.xml} (and subprojects) are
9192 modified to specify the version of dependencies and plugins that match the
9193 versions available in the guix build environment. Dependencies and plugins
9194 must be installed in the fake maven repository at @file{lib/m2}, and are
9195 symlinked into a proper repository before maven is run. Maven is instructed
9196 to use that repository for the build and installs built artifacts there.
9197 Changed files are copied to the @file{lib/m2} directory of the package output.
9199 You can specify a @file{pom.xml} file with the @code{#:pom-file} argument,
9200 or let the build system use the default @file{pom.xml} file in the sources.
9202 In case you need to specify a dependency's version manually, you can use the
9203 @code{#:local-packages} argument. It takes an association list where the key
9204 is the groupId of the package and its value is an association list where the
9205 key is the artifactId of the package and its value is the version you want to
9206 override in the @file{pom.xml}.
9208 Some packages use dependencies or plugins that are not useful at runtime nor
9209 at build time in Guix. You can alter the @file{pom.xml} file to remove them
9210 using the @code{#:exclude} argument. Its value is an association list where
9211 the key is the groupId of the plugin or dependency you want to remove, and
9212 the value is a list of artifactId you want to remove.
9214 You can override the default @code{jdk} and @code{maven} packages with the
9215 corresponding argument, @code{#:jdk} and @code{#:maven}.
9217 The @code{#:maven-plugins} argument is a list of maven plugins used during
9218 the build, with the same format as the @code{inputs} fields of the package
9219 declaration. Its default value is @code{(default-maven-plugins)} which is
9223 @defvr {Scheme Variable} minetest-mod-build-system
9224 This variable is exported by @code{(guix build-system minetest)}. It
9225 implements a build procedure for @uref{https://www.minetest.net, Minetest}
9226 mods, which consists of copying Lua code, images and other resources to
9227 the location Minetest searches for mods. The build system also minimises
9228 PNG images and verifies that Minetest can load the mod without errors.
9231 @defvr {Scheme Variable} minify-build-system
9232 This variable is exported by @code{(guix build-system minify)}. It
9233 implements a minification procedure for simple JavaScript packages.
9235 It adds @code{uglify-js} to the set of inputs and uses it to compress
9236 all JavaScript files in the @file{src} directory. A different minifier
9237 package can be specified with the @code{#:uglify-js} parameter, but it
9238 is expected that the package writes the minified code to the standard
9241 When the input JavaScript files are not all located in the @file{src}
9242 directory, the parameter @code{#:javascript-files} can be used to
9243 specify a list of file names to feed to the minifier.
9246 @defvr {Scheme Variable} ocaml-build-system
9247 This variable is exported by @code{(guix build-system ocaml)}. It implements
9248 a build procedure for @uref{https://ocaml.org, OCaml} packages, which consists
9249 of choosing the correct set of commands to run for each package. OCaml
9250 packages can expect many different commands to be run. This build system will
9253 When the package has a @file{setup.ml} file present at the top-level, it will
9254 run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
9255 @code{ocaml setup.ml -install}. The build system will assume that this file
9256 was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will take
9257 care of setting the prefix and enabling tests if they are not disabled. You
9258 can pass configure and build flags with the @code{#:configure-flags} and
9259 @code{#:build-flags}. The @code{#:test-flags} key can be passed to change the
9260 set of flags used to enable tests. The @code{#:use-make?} key can be used to
9261 bypass this system in the build and install phases.
9263 When the package has a @file{configure} file, it is assumed that it is a
9264 hand-made configure script that requires a different argument format than
9265 in the @code{gnu-build-system}. You can add more flags with the
9266 @code{#:configure-flags} key.
9268 When the package has a @file{Makefile} file (or @code{#:use-make?} is
9269 @code{#t}), it will be used and more flags can be passed to the build and
9270 install phases with the @code{#:make-flags} key.
9272 Finally, some packages do not have these files and use a somewhat standard
9273 location for its build system. In that case, the build system will run
9274 @code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
9275 providing the path to the required findlib module. Additional flags can
9276 be passed via the @code{#:build-flags} key. Install is taken care of by
9277 @command{opam-installer}. In this case, the @code{opam} package must
9278 be added to the @code{native-inputs} field of the package definition.
9280 Note that most OCaml packages assume they will be installed in the same
9281 directory as OCaml, which is not what we want in guix. In particular, they
9282 will install @file{.so} files in their module's directory, which is usually
9283 fine because it is in the OCaml compiler directory. In guix though, these
9284 libraries cannot be found and we use @env{CAML_LD_LIBRARY_PATH}. This
9285 variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
9286 @file{.so} libraries should be installed.
9289 @defvr {Scheme Variable} python-build-system
9290 This variable is exported by @code{(guix build-system python)}. It
9291 implements the more or less standard build procedure used by Python
9292 packages, which consists in running @code{python setup.py build} and
9293 then @code{python setup.py install --prefix=/gnu/store/@dots{}}.
9295 For packages that install stand-alone Python programs under @code{bin/},
9296 it takes care of wrapping these programs so that their
9297 @env{GUIX_PYTHONPATH} environment variable points to all the Python
9298 libraries they depend on.
9300 Which Python package is used to perform the build can be specified with
9301 the @code{#:python} parameter. This is a useful way to force a package
9302 to be built for a specific version of the Python interpreter, which
9303 might be necessary if the package is only compatible with a single
9304 interpreter version.
9306 By default guix calls @code{setup.py} under control of
9307 @code{setuptools}, much like @command{pip} does. Some packages are not
9308 compatible with setuptools (and pip), thus you can disable this by
9309 setting the @code{#:use-setuptools?} parameter to @code{#f}.
9311 If a @code{"python"} output is available, the package is installed into it
9312 instead of the default @code{"out"} output. This is useful for packages that
9313 include a Python package as only a part of the software, and thus want to
9314 combine the phases of @code{python-build-system} with another build system.
9315 Python bindings are a common usecase.
9319 @defvr {Scheme Variable} perl-build-system
9320 This variable is exported by @code{(guix build-system perl)}. It
9321 implements the standard build procedure for Perl packages, which either
9322 consists in running @code{perl Build.PL --prefix=/gnu/store/@dots{}},
9323 followed by @code{Build} and @code{Build install}; or in running
9324 @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}}, followed by
9325 @code{make} and @code{make install}, depending on which of
9326 @code{Build.PL} or @code{Makefile.PL} is present in the package
9327 distribution. Preference is given to the former if both @code{Build.PL}
9328 and @code{Makefile.PL} exist in the package distribution. This
9329 preference can be reversed by specifying @code{#t} for the
9330 @code{#:make-maker?} parameter.
9332 The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
9333 passes flags specified by the @code{#:make-maker-flags} or
9334 @code{#:module-build-flags} parameter, respectively.
9336 Which Perl package is used can be specified with @code{#:perl}.
9339 @defvr {Scheme Variable} renpy-build-system
9340 This variable is exported by @code{(guix build-system renpy)}. It implements
9341 the more or less standard build procedure used by Ren'py games, which consists
9342 of loading @code{#:game} once, thereby creating bytecode for it.
9344 It further creates a wrapper script in @code{bin/} and a desktop entry in
9345 @code{share/applications}, both of which can be used to launch the game.
9347 Which Ren'py package is used can be specified with @code{#:renpy}.
9348 Games can also be installed in outputs other than ``out'' by using
9352 @defvr {Scheme Variable} qt-build-system
9353 This variable is exported by @code{(guix build-system qt)}. It
9354 is intended for use with applications using Qt or KDE.
9356 This build system adds the following two phases to the ones defined by
9357 @code{cmake-build-system}:
9361 The phase @code{check-setup} prepares the environment for running
9362 the checks as commonly used by Qt test programs.
9363 For now this only sets some environment variables:
9364 @code{QT_QPA_PLATFORM=offscreen},
9365 @code{DBUS_FATAL_WARNINGS=0} and
9366 @code{CTEST_OUTPUT_ON_FAILURE=1}.
9368 This phase is added before the @code{check} phase.
9369 It's a separate phase to ease adjusting if necessary.
9372 The phase @code{qt-wrap}
9373 searches for Qt5 plugin paths, QML paths and some XDG in the inputs
9374 and output. In case some path is found, all programs in the output's
9375 @file{bin/}, @file{sbin/}, @file{libexec/} and @file{lib/libexec/} directories
9376 are wrapped in scripts defining the necessary environment variables.
9378 It is possible to exclude specific package outputs from that wrapping process
9379 by listing their names in the @code{#:qt-wrap-excluded-outputs} parameter.
9380 This is useful when an output is known not to contain any Qt binaries, and
9381 where wrapping would gratuitously add a dependency of that output on Qt, KDE,
9384 This phase is added after the @code{install} phase.
9388 @defvr {Scheme Variable} r-build-system
9389 This variable is exported by @code{(guix build-system r)}. It
9390 implements the build procedure used by @uref{https://r-project.org, R}
9391 packages, which essentially is little more than running @samp{R CMD
9392 INSTALL --library=/gnu/store/@dots{}} in an environment where
9393 @env{R_LIBS_SITE} contains the paths to all R package inputs. Tests are
9394 run after installation using the R function
9395 @code{tools::testInstalledPackage}.
9398 @defvr {Scheme Variable} rakudo-build-system
9399 This variable is exported by @code{(guix build-system rakudo)}. It
9400 implements the build procedure used by @uref{https://rakudo.org/,
9401 Rakudo} for @uref{https://perl6.org/, Perl6} packages. It installs the
9402 package to @code{/gnu/store/@dots{}/NAME-VERSION/share/perl6} and
9403 installs the binaries, library files and the resources, as well as wrap
9404 the files under the @code{bin/} directory. Tests can be skipped by
9405 passing @code{#f} to the @code{tests?} parameter.
9407 Which rakudo package is used can be specified with @code{rakudo}.
9408 Which perl6-tap-harness package used for the tests can be specified with
9409 @code{#:prove6} or removed by passing @code{#f} to the
9410 @code{with-prove6?} parameter.
9411 Which perl6-zef package used for tests and installing can be specified
9412 with @code{#:zef} or removed by passing @code{#f} to the
9413 @code{with-zef?} parameter.
9416 @defvr {Scheme Variable} rebar-build-system
9417 This variable is exported by @code{(guix build-system rebar)}. It
9418 implements a build procedure around @uref{https://rebar3.org,rebar3},
9419 a build system for programs written in the Erlang language.
9421 It adds both @code{rebar3} and the @code{erlang} to the set of inputs.
9422 Different packages can be specified with the @code{#:rebar} and
9423 @code{#:erlang} parameters, respectively.
9425 This build system is based on @code{gnu-build-system}, but with the
9426 following phases changed:
9431 This phase, after unpacking the source like the @code{gnu-build-system}
9432 does, checks for a file @code{contents.tar.gz} at the top-level of the
9433 source. If this file exists, it will be unpacked, too. This eases
9434 handling of package hosted at @uref{https://hex.pm/},
9435 the Erlang and Elixir package repository.
9439 There are no @code{bootstrap} and @code{configure} phase because erlang
9440 packages typically don’t need to be configured.
9443 This phase runs @code{rebar3 compile}
9444 with the flags listed in @code{#:rebar-flags}.
9447 Unless @code{#:tests? #f} is passed,
9448 this phase runs @code{rebar3 eunit},
9449 or some other target specified with @code{#:test-target},
9450 with the flags listed in @code{#:rebar-flags},
9453 This installs the files created in the @i{default} profile, or some
9454 other profile specified with @code{#:install-profile}.
9459 @defvr {Scheme Variable} texlive-build-system
9460 This variable is exported by @code{(guix build-system texlive)}. It is
9461 used to build TeX packages in batch mode with a specified engine. The
9462 build system sets the @env{TEXINPUTS} variable to find all TeX source
9463 files in the inputs.
9465 By default it runs @code{luatex} on all files ending on @code{ins}. A
9466 different engine and format can be specified with the
9467 @code{#:tex-format} argument. Different build targets can be specified
9468 with the @code{#:build-targets} argument, which expects a list of file
9469 names. The build system adds only @code{texlive-bin} and
9470 @code{texlive-latex-base} (both from @code{(gnu packages tex}) to the
9471 inputs. Both can be overridden with the arguments @code{#:texlive-bin}
9472 and @code{#:texlive-latex-base}, respectively.
9474 The @code{#:tex-directory} parameter tells the build system where to
9475 install the built files under the texmf tree.
9478 @defvr {Scheme Variable} ruby-build-system
9479 This variable is exported by @code{(guix build-system ruby)}. It
9480 implements the RubyGems build procedure used by Ruby packages, which
9481 involves running @code{gem build} followed by @code{gem install}.
9483 The @code{source} field of a package that uses this build system
9484 typically references a gem archive, since this is the format that Ruby
9485 developers use when releasing their software. The build system unpacks
9486 the gem archive, potentially patches the source, runs the test suite,
9487 repackages the gem, and installs it. Additionally, directories and
9488 tarballs may be referenced to allow building unreleased gems from Git or
9489 a traditional source release tarball.
9491 Which Ruby package is used can be specified with the @code{#:ruby}
9492 parameter. A list of additional flags to be passed to the @command{gem}
9493 command can be specified with the @code{#:gem-flags} parameter.
9496 @defvr {Scheme Variable} waf-build-system
9497 This variable is exported by @code{(guix build-system waf)}. It
9498 implements a build procedure around the @code{waf} script. The common
9499 phases---@code{configure}, @code{build}, and @code{install}---are
9500 implemented by passing their names as arguments to the @code{waf}
9503 The @code{waf} script is executed by the Python interpreter. Which
9504 Python package is used to run the script can be specified with the
9505 @code{#:python} parameter.
9508 @defvr {Scheme Variable} scons-build-system
9509 This variable is exported by @code{(guix build-system scons)}. It
9510 implements the build procedure used by the SCons software construction
9511 tool. This build system runs @code{scons} to build the package,
9512 @code{scons test} to run tests, and then @code{scons install} to install
9515 Additional flags to be passed to @code{scons} can be specified with the
9516 @code{#:scons-flags} parameter. The default build and install targets
9517 can be overridden with @code{#:build-targets} and
9518 @code{#:install-targets} respectively. The version of Python used to
9519 run SCons can be specified by selecting the appropriate SCons package
9520 with the @code{#:scons} parameter.
9523 @defvr {Scheme Variable} haskell-build-system
9524 This variable is exported by @code{(guix build-system haskell)}. It
9525 implements the Cabal build procedure used by Haskell packages, which
9526 involves running @code{runhaskell Setup.hs configure
9527 --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}.
9528 Instead of installing the package by running @code{runhaskell Setup.hs
9529 install}, to avoid trying to register libraries in the read-only
9530 compiler store directory, the build system uses @code{runhaskell
9531 Setup.hs copy}, followed by @code{runhaskell Setup.hs register}. In
9532 addition, the build system generates the package documentation by
9533 running @code{runhaskell Setup.hs haddock}, unless @code{#:haddock? #f}
9534 is passed. Optional Haddock parameters can be passed with the help of
9535 the @code{#:haddock-flags} parameter. If the file @code{Setup.hs} is
9536 not found, the build system looks for @code{Setup.lhs} instead.
9538 Which Haskell compiler is used can be specified with the @code{#:haskell}
9539 parameter which defaults to @code{ghc}.
9542 @defvr {Scheme Variable} dub-build-system
9543 This variable is exported by @code{(guix build-system dub)}. It
9544 implements the Dub build procedure used by D packages, which
9545 involves running @code{dub build} and @code{dub run}.
9546 Installation is done by copying the files manually.
9548 Which D compiler is used can be specified with the @code{#:ldc}
9549 parameter which defaults to @code{ldc}.
9552 @anchor{emacs-build-system}
9553 @defvr {Scheme Variable} emacs-build-system
9554 This variable is exported by @code{(guix build-system emacs)}. It
9555 implements an installation procedure similar to the packaging system
9556 of Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
9558 It first creates the @code{@code{package}-autoloads.el} file, then it
9559 byte compiles all Emacs Lisp files. Differently from the Emacs
9560 packaging system, the Info documentation files are moved to the standard
9561 documentation directory and the @file{dir} file is deleted. The Elisp
9562 package files are installed directly under @file{share/emacs/site-lisp}.
9565 @defvr {Scheme Variable} font-build-system
9566 This variable is exported by @code{(guix build-system font)}. It
9567 implements an installation procedure for font packages where upstream
9568 provides pre-compiled TrueType, OpenType, etc.@: font files that merely
9569 need to be copied into place. It copies font files to standard
9570 locations in the output directory.
9573 @defvr {Scheme Variable} meson-build-system
9574 This variable is exported by @code{(guix build-system meson)}. It
9575 implements the build procedure for packages that use
9576 @url{https://mesonbuild.com, Meson} as their build system.
9578 It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set
9579 of inputs, and they can be changed with the parameters @code{#:meson}
9580 and @code{#:ninja} if needed.
9582 This build system is an extension of @code{gnu-build-system}, but with the
9583 following phases changed to some specific for Meson:
9588 The phase runs @code{meson} with the flags specified in
9589 @code{#:configure-flags}. The flag @option{--buildtype} is always set to
9590 @code{debugoptimized} unless something else is specified in
9591 @code{#:build-type}.
9594 The phase runs @code{ninja} to build the package in parallel by default, but
9595 this can be changed with @code{#:parallel-build?}.
9598 The phase runs @samp{meson test} with a base set of options that cannot
9599 be overridden. This base set of options can be extended via the
9600 @code{#:test-options} argument, for example to select or skip a specific
9604 The phase runs @code{ninja install} and can not be changed.
9607 Apart from that, the build system also adds the following phases:
9612 This phase ensures that all binaries can find the libraries they need.
9613 It searches for required libraries in subdirectories of the package
9614 being built, and adds those to @code{RUNPATH} where needed. It also
9615 removes references to libraries left over from the build phase by
9616 @code{meson}, such as test dependencies, that aren't actually required
9617 for the program to run.
9619 @item glib-or-gtk-wrap
9620 This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
9621 is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
9623 @item glib-or-gtk-compile-schemas
9624 This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
9625 is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
9629 @defvr {Scheme Variable} linux-module-build-system
9630 @code{linux-module-build-system} allows building Linux kernel modules.
9632 @cindex build phases
9633 This build system is an extension of @code{gnu-build-system}, but with the
9634 following phases changed:
9639 This phase configures the environment so that the Linux kernel's Makefile
9640 can be used to build the external kernel module.
9643 This phase uses the Linux kernel's Makefile in order to build the external
9647 This phase uses the Linux kernel's Makefile in order to install the external
9651 It is possible and useful to specify the Linux kernel to use for building
9652 the module (in the @code{arguments} form of a package using the
9653 @code{linux-module-build-system}, use the key @code{#:linux} to specify it).
9656 @defvr {Scheme Variable} node-build-system
9657 This variable is exported by @code{(guix build-system node)}. It
9658 implements the build procedure used by @uref{https://nodejs.org,
9659 Node.js}, which implements an approximation of the @code{npm install}
9660 command, followed by an @code{npm test} command.
9662 Which Node.js package is used to interpret the @code{npm} commands can
9663 be specified with the @code{#:node} parameter which defaults to
9667 Lastly, for packages that do not need anything as sophisticated, a
9668 ``trivial'' build system is provided. It is trivial in the sense that
9669 it provides basically no support: it does not pull any implicit inputs,
9670 and does not have a notion of build phases.
9672 @defvr {Scheme Variable} trivial-build-system
9673 This variable is exported by @code{(guix build-system trivial)}.
9675 This build system requires a @code{#:builder} argument. This argument
9676 must be a Scheme expression that builds the package output(s)---as
9677 with @code{build-expression->derivation} (@pxref{Derivations,
9678 @code{build-expression->derivation}}).
9681 @defvr {Scheme Variable} channel-build-system
9682 This variable is exported by @code{(guix build-system channel)}.
9684 This build system is meant primarily for internal use. A package using
9685 this build system must have a channel specification as its @code{source}
9686 field (@pxref{Channels}); alternatively, its source can be a directory
9687 name, in which case an additional @code{#:commit} argument must be
9688 supplied to specify the commit being built (a hexadecimal string).
9690 The resulting package is a Guix instance of the given channel, similar
9691 to how @command{guix time-machine} would build it.
9695 @section Build Phases
9697 @cindex build phases, for packages
9698 Almost all package build systems implement a notion @dfn{build phases}:
9699 a sequence of actions that the build system executes, when you build the
9700 package, leading to the installed byproducts in the store. A notable
9701 exception is the ``bare-bones'' @code{trivial-build-system}
9702 (@pxref{Build Systems}).
9704 As discussed in the previous section, those build systems provide a
9705 standard list of phases. For @code{gnu-build-system}, the main build
9706 phases are the following:
9710 Define search path environment variables for all the input packages,
9711 including @env{PATH} (@pxref{Search Paths}).
9714 Unpack the source tarball, and change the current directory to the
9715 extracted source tree. If the source is actually a directory, copy it
9716 to the build tree, and enter that directory.
9718 @item patch-source-shebangs
9719 Patch shebangs encountered in source files so they refer to the right
9720 store file names. For instance, this changes @code{#!/bin/sh} to
9721 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
9724 Run the @file{configure} script with a number of default options, such
9725 as @option{--prefix=/gnu/store/@dots{}}, as well as the options specified
9726 by the @code{#:configure-flags} argument.
9729 Run @code{make} with the list of flags specified with
9730 @code{#:make-flags}. If the @code{#:parallel-build?} argument is true
9731 (the default), build with @code{make -j}.
9734 Run @code{make check}, or some other target specified with
9735 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
9736 @code{#:parallel-tests?} argument is true (the default), run @code{make
9740 Run @code{make install} with the flags listed in @code{#:make-flags}.
9742 @item patch-shebangs
9743 Patch shebangs on the installed executable files.
9746 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?}
9747 is false), copying them to the @code{debug} output when available
9748 (@pxref{Installing Debugging Files}).
9750 @cindex RUNPATH, validation
9751 @anchor{phase-validate-runpath}
9752 @item validate-runpath
9753 Validate the @code{RUNPATH} of ELF binaries, unless
9754 @code{#:validate-runpath?} is false (@pxref{Build Systems}).
9756 This validation step consists in making sure that all the shared
9757 libraries needed by an ELF binary, which are listed as @code{DT_NEEDED}
9758 entries in its @code{PT_DYNAMIC} segment, appear in the
9759 @code{DT_RUNPATH} entry of that binary. In other words, it ensures that
9760 running or using those binaries will not result in a ``file not found''
9761 error at run time. @xref{Options, @option{-rpath},, ld, The GNU
9762 Linker}, for more information on @code{RUNPATH}.
9766 Other build systems have similar phases, with some variations. For
9767 example, @code{cmake-build-system} has same-named phases but its
9768 @code{configure} phases runs @code{cmake} instead of @code{./configure}.
9769 Others, such as @code{python-build-system}, have a wholly different list
9770 of standard phases. All this code runs on the @dfn{build side}: it is
9771 evaluated when you actually build the package, in a dedicated build
9772 process spawned by the build daemon (@pxref{Invoking guix-daemon}).
9774 Build phases are represented as association lists or ``alists''
9775 (@pxref{Association Lists,,, guile, GNU Guile Reference Manual}) where
9776 each key is a symbol for the name of the phase and the associated value
9777 is a procedure that accepts an arbitrary number of arguments. By
9778 convention, those procedures receive information about the build in the
9779 form of @dfn{keyword parameters}, which they can use or ignore.
9781 @vindex %standard-phases
9782 For example, here is how @code{(guix build gnu-build-system)} defines
9783 @code{%standard-phases}, the variable holding its alist of build
9784 phases@footnote{We present a simplified view of those build phases, but
9785 do take a look at @code{(guix build gnu-build-system)} to see all the
9789 ;; The build phases of 'gnu-build-system'.
9791 (define* (unpack #:key source #:allow-other-keys)
9792 ;; Extract the source tarball.
9793 (invoke "tar" "xvf" source))
9795 (define* (configure #:key outputs #:allow-other-keys)
9796 ;; Run the 'configure' script. Install to output "out".
9797 (let ((out (assoc-ref outputs "out")))
9798 (invoke "./configure"
9799 (string-append "--prefix=" out))))
9801 (define* (build #:allow-other-keys)
9805 (define* (check #:key (test-target "check") (tests? #true)
9807 ;; Run the test suite.
9809 (invoke "make" test-target)
9810 (display "test suite not run\n")))
9812 (define* (install #:allow-other-keys)
9813 ;; Install files to the prefix 'configure' specified.
9814 (invoke "make" "install"))
9816 (define %standard-phases
9817 ;; The list of standard phases (quite a few are omitted
9818 ;; for brevity). Each element is a symbol/procedure pair.
9819 (list (cons 'unpack unpack)
9820 (cons 'configure configure)
9823 (cons 'install install)))
9826 This shows how @code{%standard-phases} is defined as a list of
9827 symbol/procedure pairs (@pxref{Pairs,,, guile, GNU Guile Reference
9828 Manual}). The first pair associates the @code{unpack} procedure with
9829 the @code{unpack} symbol---a name; the second pair defines the
9830 @code{configure} phase similarly, and so on. When building a package
9831 that uses @code{gnu-build-system} with its default list of phases, those
9832 phases are executed sequentially. You can see the name of each phase
9833 started and completed in the build log of packages that you build.
9835 Let's now look at the procedures themselves. Each one is defined with
9836 @code{define*}: @code{#:key} lists keyword parameters the procedure
9837 accepts, possibly with a default value, and @code{#:allow-other-keys}
9838 specifies that other keyword parameters are ignored (@pxref{Optional
9839 Arguments,,, guile, GNU Guile Reference Manual}).
9841 The @code{unpack} procedure honors the @code{source} parameter, which
9842 the build system uses to pass the file name of the source tarball (or
9843 version control checkout), and it ignores other parameters. The
9844 @code{configure} phase only cares about the @code{outputs} parameter, an
9845 alist mapping package output names to their store file name
9846 (@pxref{Packages with Multiple Outputs}). It extracts the file name of
9847 for @code{out}, the default output, and passes it to
9848 @command{./configure} as the installation prefix, meaning that
9849 @command{make install} will eventually copy all the files in that
9850 directory (@pxref{Configuration, configuration and makefile
9851 conventions,, standards, GNU Coding Standards}). @code{build} and
9852 @code{install} ignore all their arguments. @code{check} honors the
9853 @code{test-target} argument, which specifies the name of the Makefile
9854 target to run tests; it prints a message and skips tests when
9855 @code{tests?} is false.
9857 @cindex build phases, customizing
9858 The list of phases used for a particular package can be changed with the
9859 @code{#:phases} parameter of the build system. Changing the set of
9860 build phases boils down to building a new alist of phases based on the
9861 @code{%standard-phases} alist described above. This can be done with
9862 standard alist procedures such as @code{alist-delete} (@pxref{SRFI-1
9863 Association Lists,,, guile, GNU Guile Reference Manual}); however, it is
9864 more convenient to do so with @code{modify-phases} (@pxref{Build
9865 Utilities, @code{modify-phases}}).
9867 Here is an example of a package definition that removes the
9868 @code{configure} phase of @code{%standard-phases} and inserts a new
9869 phase before the @code{build} phase, called
9870 @code{set-prefix-in-makefile}:
9873 (define-public example
9876 ;; other fields omitted
9877 (build-system gnu-build-system)
9879 '(#:phases (modify-phases %standard-phases
9881 (add-before 'build 'set-prefix-in-makefile
9882 (lambda* (#:key outputs #:allow-other-keys)
9883 ;; Modify the makefile so that its
9884 ;; 'PREFIX' variable points to "out".
9885 (let ((out (assoc-ref outputs "out")))
9886 (substitute* "Makefile"
9888 (string-append "PREFIX = "
9892 The new phase that is inserted is written as an anonymous procedure,
9893 introduced with @code{lambda*}; it honors the @code{outputs} parameter
9894 we have seen before. @xref{Build Utilities}, for more about the helpers
9895 used by this phase, and for more examples of @code{modify-phases}.
9897 @cindex code staging
9898 @cindex staging, of code
9899 Keep in mind that build phases are code evaluated at the time the
9900 package is actually built. This explains why the whole
9901 @code{modify-phases} expression above is quoted (it comes after the
9902 @code{'} or apostrophe): it is @dfn{staged} for later execution.
9903 @xref{G-Expressions}, for an explanation of code staging and the
9904 @dfn{code strata} involved.
9906 @node Build Utilities
9907 @section Build Utilities
9909 As soon as you start writing non-trivial package definitions
9910 (@pxref{Defining Packages}) or other build actions
9911 (@pxref{G-Expressions}), you will likely start looking for helpers for
9912 ``shell-like'' actions---creating directories, copying and deleting
9913 files recursively, manipulating build phases, and so on. The
9914 @code{(guix build utils)} module provides such utility procedures.
9916 Most build systems load @code{(guix build utils)} (@pxref{Build
9917 Systems}). Thus, when writing custom build phases for your package
9918 definitions, you can usually assume those procedures are in scope.
9920 When writing G-expressions, you can import @code{(guix build utils)} on
9921 the ``build side'' using @code{with-imported-modules} and then put it in
9922 scope with the @code{use-modules} form (@pxref{Using Guile Modules,,,
9923 guile, GNU Guile Reference Manual}):
9926 (with-imported-modules '((guix build utils)) ;import it
9927 (computed-file "empty-tree"
9930 (use-modules (guix build utils))
9932 ;; Happily use its 'mkdir-p' procedure.
9933 (mkdir-p (string-append #$output "/a/b/c")))))
9936 The remainder of this section is the reference for most of the utility
9937 procedures provided by @code{(guix build utils)}.
9939 @c TODO Document what's missing.
9941 @subsection Dealing with Store File Names
9943 This section documents procedures that deal with store file names.
9945 @deffn {Scheme Procedure} %store-directory
9946 Return the directory name of the store.
9949 @deffn {Scheme Procedure} store-file-name? @var{file}
9950 Return true if @var{file} is in the store.
9953 @deffn {Scheme Procedure} strip-store-file-name @var{file}
9954 Strip the @file{/gnu/store} and hash from @var{file}, a store file name.
9955 The result is typically a @code{"@var{package}-@var{version}"} string.
9958 @deffn {Scheme Procedure} package-name->name+version @var{name}
9959 Given @var{name}, a package name like @code{"foo-0.9.1b"}, return two
9960 values: @code{"foo"} and @code{"0.9.1b"}. When the version part is
9961 unavailable, @var{name} and @code{#f} are returned. The first hyphen
9962 followed by a digit is considered to introduce the version part.
9965 @subsection File Types
9967 The procedures below deal with files and file types.
9969 @deffn {Scheme Procedure} directory-exists? @var{dir}
9970 Return @code{#t} if @var{dir} exists and is a directory.
9973 @deffn {Scheme Procedure} executable-file? @var{file}
9974 Return @code{#t} if @var{file} exists and is executable.
9977 @deffn {Scheme Procedure} symbolic-link? @var{file}
9978 Return @code{#t} if @var{file} is a symbolic link (aka. a ``symlink'').
9981 @deffn {Scheme Procedure} elf-file? @var{file}
9982 @deffnx {Scheme Procedure} ar-file? @var{file}
9983 @deffnx {Scheme Procedure} gzip-file? @var{file}
9984 Return @code{#t} if @var{file} is, respectively, an ELF file, an
9985 @code{ar} archive (such as a @file{.a} static library), or a gzip file.
9988 @deffn {Scheme Procedure} reset-gzip-timestamp @var{file} [#:keep-mtime? #t]
9989 If @var{file} is a gzip file, reset its embedded timestamp (as with
9990 @command{gzip --no-name}) and return true. Otherwise return @code{#f}.
9991 When @var{keep-mtime?} is true, preserve @var{file}'s modification time.
9994 @subsection File Manipulation
9996 The following procedures and macros help create, modify, and delete
9997 files. They provide functionality comparable to common shell utilities
9998 such as @command{mkdir -p}, @command{cp -r}, @command{rm -r}, and
9999 @command{sed}. They complement Guile's extensive, but low-level, file
10000 system interface (@pxref{POSIX,,, guile, GNU Guile Reference Manual}).
10002 @deffn {Scheme Syntax} with-directory-excursion @var{directory} @var{body}@dots{}
10003 Run @var{body} with @var{directory} as the process's current directory.
10005 Essentially, this macro changes the current directory to @var{directory}
10006 before evaluating @var{body}, using @code{chdir} (@pxref{Processes,,,
10007 guile, GNU Guile Reference Manual}). It changes back to the initial
10008 directory when the dynamic extent of @var{body} is left, be it @i{via}
10009 normal procedure return or @i{via} a non-local exit such as an
10013 @deffn {Scheme Procedure} mkdir-p @var{dir}
10014 Create directory @var{dir} and all its ancestors.
10017 @deffn {Scheme Procedure} install-file @var{file} @var{directory}
10018 Create @var{directory} if it does not exist and copy @var{file} in there
10019 under the same name.
10022 @deffn {Scheme Procedure} make-file-writable @var{file}
10023 Make @var{file} writable for its owner.
10026 @deffn {Scheme Procedure} copy-recursively @var{source} @var{destination} @
10027 [#:log (current-output-port)] [#:follow-symlinks? #f] @
10028 [#:copy-file copy-file] [#:keep-mtime? #f] [#:keep-permissions? #t]
10029 Copy @var{source} directory to @var{destination}. Follow symlinks if
10030 @var{follow-symlinks?} is true; otherwise, just preserve them. Call
10031 @var{copy-file} to copy regular files. When @var{keep-mtime?} is true,
10032 keep the modification time of the files in @var{source} on those of
10033 @var{destination}. When @var{keep-permissions?} is true, preserve file
10034 permissions. Write verbose output to the @var{log} port.
10037 @deffn {Scheme Procedure} delete-file-recursively @var{dir} @
10038 [#:follow-mounts? #f]
10039 Delete @var{dir} recursively, like @command{rm -rf}, without following
10040 symlinks. Don't follow mount points either, unless @var{follow-mounts?}
10041 is true. Report but ignore errors.
10044 @deffn {Scheme Syntax} substitute* @var{file} @
10045 ((@var{regexp} @var{match-var}@dots{}) @var{body}@dots{}) @dots{}
10046 Substitute @var{regexp} in @var{file} by the string returned by
10047 @var{body}. @var{body} is evaluated with each @var{match-var} bound to
10048 the corresponding positional regexp sub-expression. For example:
10054 (("foo([a-z]+)bar(.*)$" all letters end)
10055 (string-append "baz" letters end)))
10058 Here, anytime a line of @var{file} contains @code{hello}, it is replaced
10059 by @code{good morning}. Anytime a line of @var{file} matches the second
10060 regexp, @code{all} is bound to the complete match, @code{letters} is bound
10061 to the first sub-expression, and @code{end} is bound to the last one.
10063 When one of the @var{match-var} is @code{_}, no variable is bound to the
10064 corresponding match substring.
10066 Alternatively, @var{file} may be a list of file names, in which case
10067 they are all subject to the substitutions.
10069 Be careful about using @code{$} to match the end of a line; by itself it
10070 won't match the terminating newline of a line.
10073 @subsection File Search
10075 @cindex file, searching
10076 This section documents procedures to search and filter files.
10078 @deffn {Scheme Procedure} file-name-predicate @var{regexp}
10079 Return a predicate that returns true when passed a file name whose base
10080 name matches @var{regexp}.
10083 @deffn {Scheme Procedure} find-files @var{dir} [@var{pred}] @
10084 [#:stat lstat] [#:directories? #f] [#:fail-on-error? #f]
10085 Return the lexicographically sorted list of files under @var{dir} for
10086 which @var{pred} returns true. @var{pred} is passed two arguments: the
10087 absolute file name, and its stat buffer; the default predicate always
10088 returns true. @var{pred} can also be a regular expression, in which
10089 case it is equivalent to @code{(file-name-predicate @var{pred})}.
10090 @var{stat} is used to obtain file information; using @code{lstat} means
10091 that symlinks are not followed. If @var{directories?} is true, then
10092 directories will also be included. If @var{fail-on-error?} is true,
10093 raise an exception upon error.
10096 Here are a few examples where we assume that the current directory is
10097 the root of the Guix source tree:
10100 ;; List all the regular files in the current directory.
10102 @result{} ("./.dir-locals.el" "./.gitignore" @dots{})
10104 ;; List all the .scm files under gnu/services.
10105 (find-files "gnu/services" "\\.scm$")
10106 @result{} ("gnu/services/admin.scm" "gnu/services/audio.scm" @dots{})
10108 ;; List ar files in the current directory.
10109 (find-files "." (lambda (file stat) (ar-file? file)))
10110 @result{} ("./libformat.a" "./libstore.a" @dots{})
10113 @deffn {Scheme Procedure} which @var{program}
10114 Return the complete file name for @var{program} as found in
10115 @code{$PATH}, or @code{#f} if @var{program} could not be found.
10118 @deffn {Scheme Procedure} search-input-file @var{inputs} @var{name}
10119 @deffnx {Scheme Procedure} search-input-directory @var{inputs} @var{name}
10120 Return the complete file name for @var{name} as found in @var{inputs};
10121 @code{search-input-file} searches for a regular file and
10122 @code{search-input-directory} searches for a directory. If @var{name}
10123 could not be found, an exception is raised.
10125 Here, @var{inputs} must be an association list like @code{inputs} and
10126 @code{native-inputs} as available to build phases (@pxref{Build
10130 Here is a (simplified) example of how @code{search-input-file} is used
10131 in a build phase of the @code{wireguard-tools} package:
10134 (add-after 'install 'wrap-wg-quick
10135 (lambda* (#:key inputs outputs #:allow-other-keys)
10136 (let ((coreutils (string-append (assoc-ref inputs "coreutils")
10138 (wrap-program (search-input-file outputs "bin/wg-quick")
10139 #:sh (search-input-file inputs "bin/bash")
10140 `("PATH" ":" prefix ,(list coreutils))))))
10143 @subsection Program Invocation
10145 @cindex program invocation, from Scheme
10146 @cindex invoking programs, from Scheme
10147 You'll find handy procedures to spawn processes in this module,
10148 essentially convenient wrappers around Guile's @code{system*}
10149 (@pxref{Processes, @code{system*},, guile, GNU Guile Reference Manual}).
10151 @deffn {Scheme Procedure} invoke @var{program} @var{args}@dots{}
10152 Invoke @var{program} with the given @var{args}. Raise an
10153 @code{&invoke-error} exception if the exit code is non-zero; otherwise
10156 The advantage compared to @code{system*} is that you do not need to
10157 check the return value. This reduces boilerplate in shell-script-like
10158 snippets for instance in package build phases.
10161 @deffn {Scheme Procedure} invoke-error? @var{c}
10162 Return true if @var{c} is an @code{&invoke-error} condition.
10165 @deffn {Scheme Procedure} invoke-error-program @var{c}
10166 @deffnx {Scheme Procedure} invoke-error-arguments @var{c}
10167 @deffnx {Scheme Procedure} invoke-error-exit-status @var{c}
10168 @deffnx {Scheme Procedure} invoke-error-term-signal @var{c}
10169 @deffnx {Scheme Procedure} invoke-error-stop-signal @var{c}
10170 Access specific fields of @var{c}, an @code{&invoke-error} condition.
10173 @deffn {Scheme Procedure} report-invoke-error @var{c} [@var{port}]
10174 Report to @var{port} (by default the current error port) about @var{c},
10175 an @code{&invoke-error} condition, in a human-friendly way.
10177 Typical usage would look like this:
10180 (use-modules (srfi srfi-34) ;for 'guard'
10181 (guix build utils))
10183 (guard (c ((invoke-error? c)
10184 (report-invoke-error c)))
10185 (invoke "date" "--imaginary-option"))
10187 @print{} command "date" "--imaginary-option" failed with status 1
10191 @deffn {Scheme Procedure} invoke/quiet @var{program} @var{args}@dots{}
10192 Invoke @var{program} with @var{args} and capture @var{program}'s
10193 standard output and standard error. If @var{program} succeeds, print
10194 nothing and return the unspecified value; otherwise, raise a
10195 @code{&message} error condition that includes the status code and the
10196 output of @var{program}.
10201 (use-modules (srfi srfi-34) ;for 'guard'
10202 (srfi srfi-35) ;for 'message-condition?'
10203 (guix build utils))
10205 (guard (c ((message-condition? c)
10206 (display (condition-message c))))
10207 (invoke/quiet "date") ;all is fine
10208 (invoke/quiet "date" "--imaginary-option"))
10210 @print{} 'date --imaginary-option' exited with status 1; output follows:
10212 date: unrecognized option '--imaginary-option'
10213 Try 'date --help' for more information.
10217 @subsection Build Phases
10219 @cindex build phases
10220 The @code{(guix build utils)} also contains tools to manipulate build
10221 phases as used by build systems (@pxref{Build Systems}). Build phases
10222 are represented as association lists or ``alists'' (@pxref{Association
10223 Lists,,, guile, GNU Guile Reference Manual}) where each key is a symbol
10224 naming the phase and the associated value is a procedure (@pxref{Build
10227 Guile core and the @code{(srfi srfi-1)} module both provide tools to
10228 manipulate alists. The @code{(guix build utils)} module complements
10229 those with tools written with build phases in mind.
10231 @cindex build phases, modifying
10232 @deffn {Scheme Syntax} modify-phases @var{phases} @var{clause}@dots{}
10233 Modify @var{phases} sequentially as per each @var{clause}, which may
10234 have one of the following forms:
10237 (delete @var{old-phase-name})
10238 (replace @var{old-phase-name} @var{new-phase})
10239 (add-before @var{old-phase-name} @var{new-phase-name} @var{new-phase})
10240 (add-after @var{old-phase-name} @var{new-phase-name} @var{new-phase})
10243 Where every @var{phase-name} above is an expression evaluating to a
10244 symbol, and @var{new-phase} an expression evaluating to a procedure.
10247 The example below is taken from the definition of the @code{grep}
10248 package. It adds a phase to run after the @code{install} phase, called
10249 @code{fix-egrep-and-fgrep}. That phase is a procedure (@code{lambda*}
10250 is for anonymous procedures) that takes a @code{#:outputs} keyword
10251 argument and ignores extra keyword arguments (@pxref{Optional
10252 Arguments,,, guile, GNU Guile Reference Manual}, for more on
10253 @code{lambda*} and optional and keyword arguments.) The phase uses
10254 @code{substitute*} to modify the installed @file{egrep} and @file{fgrep}
10255 scripts so that they refer to @code{grep} by its absolute file name:
10258 (modify-phases %standard-phases
10259 (add-after 'install 'fix-egrep-and-fgrep
10260 ;; Patch 'egrep' and 'fgrep' to execute 'grep' via its
10261 ;; absolute file name instead of searching for it in $PATH.
10262 (lambda* (#:key outputs #:allow-other-keys)
10263 (let* ((out (assoc-ref outputs "out"))
10264 (bin (string-append out "/bin")))
10265 (substitute* (list (string-append bin "/egrep")
10266 (string-append bin "/fgrep"))
10268 (string-append "exec " bin "/grep")))))))
10271 In the example below, phases are modified in two ways: the standard
10272 @code{configure} phase is deleted, presumably because the package does
10273 not have a @file{configure} script or anything similar, and the default
10274 @code{install} phase is replaced by one that manually copies the
10275 executable files to be installed:
10278 (modify-phases %standard-phases
10279 (delete 'configure) ;no 'configure' script
10281 (lambda* (#:key outputs #:allow-other-keys)
10282 ;; The package's Makefile doesn't provide an "install"
10283 ;; rule so do it by ourselves.
10284 (let ((bin (string-append (assoc-ref outputs "out")
10286 (install-file "footswitch" bin)
10287 (install-file "scythe" bin)))))
10290 @c TODO: Add more examples.
10292 @subsection Wrappers
10294 @cindex program wrappers
10295 @cindex wrapping programs
10296 It is not unusual for a command to require certain environment variables
10297 to be set for proper functioning, typically search paths (@pxref{Search
10298 Paths}). Failing to do that, the command might fail to find files or
10299 other commands it relies on, or it might pick the ``wrong''
10300 ones---depending on the environment in which it runs. Examples include:
10304 a shell script that assumes all the commands it uses are in @env{PATH};
10307 a Guile program that assumes all its modules are in @env{GUILE_LOAD_PATH}
10308 and @env{GUILE_LOAD_COMPILED_PATH};
10311 a Qt application that expects to find certain plugins in
10312 @env{QT_PLUGIN_PATH}.
10315 For a package writer, the goal is to make sure commands always work the
10316 same rather than depend on some external settings. One way to achieve
10317 that is to @dfn{wrap} commands in a thin script that sets those
10318 environment variables, thereby ensuring that those run-time dependencies
10319 are always found. The wrapper would be used to set @env{PATH},
10320 @env{GUILE_LOAD_PATH}, or @env{QT_PLUGIN_PATH} in the examples above.
10322 To ease that task, the @code{(guix build utils)} module provides a
10323 couple of helpers to wrap commands.
10325 @deffn {Scheme Procedure} wrap-program @var{program} @
10326 [#:sh @var{sh}] [#:rest @var{variables}]
10327 Make a wrapper for @var{program}. @var{variables} should look like this:
10330 '(@var{variable} @var{delimiter} @var{position} @var{list-of-directories})
10333 where @var{delimiter} is optional. @code{:} will be used if
10334 @var{delimiter} is not given.
10336 For example, this call:
10339 (wrap-program "foo"
10340 '("PATH" ":" = ("/gnu/.../bar/bin"))
10341 '("CERT_PATH" suffix ("/gnu/.../baz/certs"
10345 will copy @file{foo} to @file{.foo-real} and create the file @file{foo}
10346 with the following contents:
10349 #!location/of/bin/bash
10350 export PATH="/gnu/.../bar/bin"
10351 export CERT_PATH="$CERT_PATH$@{CERT_PATH:+:@}/gnu/.../baz/certs:/qux/certs"
10352 exec -a $0 location/of/.foo-real "$@@"
10355 If @var{program} has previously been wrapped by @code{wrap-program}, the
10356 wrapper is extended with definitions for @var{variables}. If it is not,
10357 @var{sh} will be used as the interpreter.
10360 @deffn {Scheme Procedure} wrap-script @var{program} @
10361 [#:guile @var{guile}] [#:rest @var{variables}]
10362 Wrap the script @var{program} such that @var{variables} are set first.
10363 The format of @var{variables} is the same as in the @code{wrap-program}
10364 procedure. This procedure differs from @code{wrap-program} in that it
10365 does not create a separate shell script. Instead, @var{program} is
10366 modified directly by prepending a Guile script, which is interpreted as
10367 a comment in the script's language.
10369 Special encoding comments as supported by Python are recreated on the
10372 Note that this procedure can only be used once per file as Guile scripts are
10377 @section Search Paths
10379 @cindex search path
10380 Many programs and libraries look for input data in a @dfn{search path},
10381 a list of directories: shells like Bash look for executables in the
10382 command search path, a C compiler looks for @file{.h} files in its
10383 header search path, the Python interpreter looks for @file{.py}
10384 files in its search path, the spell checker has a search path for
10385 dictionaries, and so on.
10387 Search paths can usually be defined or overridden @i{via} environment
10388 variables (@pxref{Environment Variables,,, libc, The GNU C Library
10389 Reference Manual}). For example, the search paths mentioned above can
10390 be changed by defining the @env{PATH}, @env{C_INCLUDE_PATH},
10391 @env{PYTHONPATH} (or @env{GUIX_PYTHONPATH}), and @env{DICPATH}
10392 environment variables---you know, all these something-PATH variables
10393 that you need to get right or things ``won't be found''.
10395 You may have noticed from the command line that Guix ``knows'' which
10396 search path environment variables should be defined, and how. When you
10397 install packages in your default profile, the file
10398 @file{~/.guix-profile/etc/profile} is created, which you can ``source''
10399 from the shell to set those variables. Likewise, if you ask
10400 @command{guix shell} to create an environment containing Python and
10401 NumPy, a Python library, and if you pass it the @option{--search-paths}
10402 option, it will tell you about @env{PATH} and @env{GUIX_PYTHONPATH}
10403 (@pxref{Invoking guix shell}):
10406 $ guix shell python python-numpy --pure --search-paths
10407 export PATH="/gnu/store/@dots{}-profile/bin"
10408 export GUIX_PYTHONPATH="/gnu/store/@dots{}-profile/lib/python3.9/site-packages"
10411 When you omit @option{--search-paths}, it defines these environment
10412 variables right away, such that Python can readily find NumPy:
10415 $ guix shell python python-numpy -- python3
10416 Python 3.9.6 (default, Jan 1 1970, 00:00:01)
10417 [GCC 10.3.0] on linux
10418 Type "help", "copyright", "credits" or "license" for more information.
10420 >>> numpy.version.version
10424 For this to work, the definition of the @code{python} package
10425 @emph{declares} the search path it cares about and its associated
10426 environment variable, @env{GUIX_PYTHONPATH}. It looks like this:
10432 ;; some fields omitted...
10433 (native-search-paths
10434 (list (search-path-specification
10435 (variable "GUIX_PYTHONPATH")
10436 (files (list "lib/python/3.9/site-packages"))))))
10439 What this @code{native-search-paths} field says is that, when the
10440 @code{python} package is used, the @env{GUIX_PYTHONPATH} environment
10441 variable must be defined to include all the
10442 @file{lib/python/3.9/site-packages} sub-directories encountered in its
10443 environment. (The @code{native-} bit means that, if we are in a
10444 cross-compilation environment, only native inputs may be added to the
10445 search path; @pxref{package Reference, @code{search-paths}}.)
10446 In the NumPy example above, the profile where
10447 @code{python} appears contains exactly one such sub-directory, and
10448 @env{GUIX_PYTHONPATH} is set to that. When there are several
10449 @file{lib/python/3.9/site-packages}---this is the case in package build
10450 environments---they are all added to @env{GUIX_PYTHONPATH}, separated by
10454 Notice that @env{GUIX_PYTHONPATH} is specified as part of the definition
10455 of the @code{python} package, and @emph{not} as part of that of
10456 @code{python-numpy}. This is because this environment variable
10457 ``belongs'' to Python, not NumPy: Python actually reads the value of
10458 that variable and honors it.
10460 Corollary: if you create a profile that does not contain @code{python},
10461 @code{GUIX_PYTHONPATH} will @emph{not} be defined, even if it contains
10462 packages that provide @file{.py} files:
10465 $ guix shell python-numpy --search-paths --pure
10466 export PATH="/gnu/store/@dots{}-profile/bin"
10469 This makes a lot of sense if we look at this profile in isolation: no
10470 software in this profile would read @env{GUIX_PYTHONPATH}.
10473 Of course, there are many variations on that theme: some packages honor
10474 more than one search path, some use separators other than colon, some
10475 accumulate several directories in their search path, and so on. A more
10476 complex example is the search path of libxml2: the value of the
10477 @env{XML_CATALOG_FILES} environment variable is space-separated, it must
10478 contain a list of @file{catalog.xml} files (not directories), which are
10479 to be found in @file{xml} sub-directories---nothing less. The search
10480 path specification looks like this:
10485 ;; some fields omitted
10486 (native-search-paths
10487 (list (search-path-specification
10488 (variable "XML_CATALOG_FILES")
10491 (file-pattern "^catalog\\.xml$")
10492 (file-type 'regular)))))
10495 Worry not, search path specifications are usually not this tricky.
10497 The @code{(guix search-paths)} module defines the data type of search
10498 path specifications and a number of helper procedures. Below is the
10499 reference of search path specifications.
10501 @deftp {Data Type} search-path-specification
10502 The data type for search path specifications.
10505 @item @code{variable}
10506 The name of the environment variable for this search path (a string).
10509 The list of sub-directories (strings) that should be added to the search
10512 @item @code{separator} (default: @code{":"})
10513 The string used to separate search path components.
10515 As a special case, a @code{separator} value of @code{#f} specifies a
10516 ``single-component search path''---in other words, a search path that
10517 cannot contain more than one element. This is useful in some cases,
10518 such as the @code{SSL_CERT_DIR} variable (honored by OpenSSL, cURL, and
10519 a few other packages) or the @code{ASPELL_DICT_DIR} variable (honored by
10520 the GNU Aspell spell checker), both of which must point to a single
10523 @item @code{file-type} (default: @code{'directory})
10524 The type of file being matched---@code{'directory} or @code{'regular},
10525 though it can be any symbol returned by @code{stat:type} (@pxref{File
10526 System, @code{stat},, guile, GNU Guile Reference Manual}).
10528 In the libxml2 example above, we would match regular files; in the
10529 Python example, we would match directories.
10531 @item @code{file-pattern} (default: @code{#f})
10532 This must be either @code{#f} or a regular expression specifying
10533 files to be matched @emph{within} the sub-directories specified by the
10534 @code{files} field.
10536 Again, the libxml2 example shows a situation where this is needed.
10540 Some search paths are not tied by a single package but to many packages.
10541 To reduce duplications, some of them are pre-defined in @code{(guix
10544 @defvr {Scheme Variable} $SSL_CERT_DIR
10545 @defvrx {Scheme Variable} $SSL_CERT_FILE
10546 These two search paths indicate where X.509 certificates can be found
10547 (@pxref{X.509 Certificates}).
10550 These pre-defined search paths can be used as in the following example:
10555 ;; some fields omitted ...
10556 (native-search-paths (list $SSL_CERT_DIR $SSL_CERT_FILE)))
10559 How do you turn search path specifications on one hand and a bunch of
10560 directories on the other hand in a set of environment variable
10561 definitions? That's the job of @code{evaluate-search-paths}.
10563 @deffn {Scheme Procedure} evaluate-search-paths @var{search-paths} @
10564 @var{directories} [@var{getenv}]
10565 Evaluate @var{search-paths}, a list of search-path specifications, for
10566 @var{directories}, a list of directory names, and return a list of
10567 specification/value pairs. Use @var{getenv} to determine the current
10568 settings and report only settings not already effective.
10571 The @code{(guix profiles)} provides a higher-level helper procedure,
10572 @code{load-profile}, that sets the environment variables of a profile.
10578 @cindex store items
10579 @cindex store paths
10581 Conceptually, the @dfn{store} is the place where derivations that have
10582 been built successfully are stored---by default, @file{/gnu/store}.
10583 Sub-directories in the store are referred to as @dfn{store items} or
10584 sometimes @dfn{store paths}. The store has an associated database that
10585 contains information such as the store paths referred to by each store
10586 path, and the list of @emph{valid} store items---results of successful
10587 builds. This database resides in @file{@var{localstatedir}/guix/db},
10588 where @var{localstatedir} is the state directory specified @i{via}
10589 @option{--localstatedir} at configure time, usually @file{/var}.
10591 The store is @emph{always} accessed by the daemon on behalf of its clients
10592 (@pxref{Invoking guix-daemon}). To manipulate the store, clients
10593 connect to the daemon over a Unix-domain socket, send requests to it,
10594 and read the result---these are remote procedure calls, or RPCs.
10597 Users must @emph{never} modify files under @file{/gnu/store} directly.
10598 This would lead to inconsistencies and break the immutability
10599 assumptions of Guix's functional model (@pxref{Introduction}).
10601 @xref{Invoking guix gc, @command{guix gc --verify}}, for information on
10602 how to check the integrity of the store and attempt recovery from
10603 accidental modifications.
10606 The @code{(guix store)} module provides procedures to connect to the
10607 daemon, and to perform RPCs. These are described below. By default,
10608 @code{open-connection}, and thus all the @command{guix} commands,
10609 connect to the local daemon or to the URI specified by the
10610 @env{GUIX_DAEMON_SOCKET} environment variable.
10612 @defvr {Environment Variable} GUIX_DAEMON_SOCKET
10613 When set, the value of this variable should be a file name or a URI
10614 designating the daemon endpoint. When it is a file name, it denotes a
10615 Unix-domain socket to connect to. In addition to file names, the
10616 supported URI schemes are:
10621 These are for Unix-domain sockets.
10622 @code{file:///var/guix/daemon-socket/socket} is equivalent to
10623 @file{/var/guix/daemon-socket/socket}.
10626 @cindex daemon, remote access
10627 @cindex remote access to the daemon
10628 @cindex daemon, cluster setup
10629 @cindex clusters, daemon setup
10630 These URIs denote connections over TCP/IP, without encryption nor
10631 authentication of the remote host. The URI must specify the host name
10632 and optionally a port number (by default port 44146 is used):
10635 guix://master.guix.example.org:1234
10638 This setup is suitable on local networks, such as clusters, where only
10639 trusted nodes may connect to the build daemon at
10640 @code{master.guix.example.org}.
10642 The @option{--listen} option of @command{guix-daemon} can be used to
10643 instruct it to listen for TCP connections (@pxref{Invoking guix-daemon,
10644 @option{--listen}}).
10647 @cindex SSH access to build daemons
10648 These URIs allow you to connect to a remote daemon over SSH@. This
10649 feature requires Guile-SSH (@pxref{Requirements}) and a working
10650 @command{guile} binary in @env{PATH} on the destination machine. It
10651 supports public key and GSSAPI authentication. A typical URL might look
10655 ssh://charlie@@guix.example.org:22
10658 As for @command{guix copy}, the usual OpenSSH client configuration files
10659 are honored (@pxref{Invoking guix copy}).
10662 Additional URI schemes may be supported in the future.
10664 @c XXX: Remove this note when the protocol incurs fewer round trips
10665 @c and when (guix derivations) no longer relies on file system access.
10667 The ability to connect to remote build daemons is considered
10668 experimental as of @value{VERSION}. Please get in touch with us to
10669 share any problems or suggestions you may have (@pxref{Contributing}).
10673 @deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
10674 Connect to the daemon over the Unix-domain socket at @var{uri} (a string). When
10675 @var{reserve-space?} is true, instruct it to reserve a little bit of
10676 extra space on the file system so that the garbage collector can still
10677 operate should the disk become full. Return a server object.
10679 @var{file} defaults to @code{%default-socket-path}, which is the normal
10680 location given the options that were passed to @command{configure}.
10683 @deffn {Scheme Procedure} close-connection @var{server}
10684 Close the connection to @var{server}.
10687 @defvr {Scheme Variable} current-build-output-port
10688 This variable is bound to a SRFI-39 parameter, which refers to the port
10689 where build and error logs sent by the daemon should be written.
10692 Procedures that make RPCs all take a server object as their first
10695 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
10696 @cindex invalid store items
10697 Return @code{#t} when @var{path} designates a valid store item and
10698 @code{#f} otherwise (an invalid item may exist on disk but still be
10699 invalid, for instance because it is the result of an aborted or failed
10702 A @code{&store-protocol-error} condition is raised if @var{path} is not
10703 prefixed by the store directory (@file{/gnu/store}).
10706 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
10707 Add @var{text} under file @var{name} in the store, and return its store
10708 path. @var{references} is the list of store paths referred to by the
10709 resulting store path.
10712 @deffn {Scheme Procedure} build-derivations @var{store} @var{derivations} @
10714 Build @var{derivations}, a list of @code{<derivation>} objects, @file{.drv}
10715 file names, or derivation/output pairs, using the specified
10716 @var{mode}---@code{(build-mode normal)} by default.
10719 Note that the @code{(guix monads)} module provides a monad as well as
10720 monadic versions of the above procedures, with the goal of making it
10721 more convenient to work with code that accesses the store (@pxref{The
10725 @i{This section is currently incomplete.}
10728 @section Derivations
10730 @cindex derivations
10731 Low-level build actions and the environment in which they are performed
10732 are represented by @dfn{derivations}. A derivation contains the
10733 following pieces of information:
10737 The outputs of the derivation---derivations produce at least one file or
10738 directory in the store, but may produce more.
10741 @cindex build-time dependencies
10742 @cindex dependencies, build-time
10743 The inputs of the derivations---i.e., its build-time dependencies---which may
10744 be other derivations or plain files in the store (patches, build scripts,
10748 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
10751 The file name of a build script in the store, along with the arguments
10755 A list of environment variables to be defined.
10759 @cindex derivation path
10760 Derivations allow clients of the daemon to communicate build actions to
10761 the store. They exist in two forms: as an in-memory representation,
10762 both on the client- and daemon-side, and as files in the store whose
10763 name end in @file{.drv}---these files are referred to as @dfn{derivation
10764 paths}. Derivations paths can be passed to the @code{build-derivations}
10765 procedure to perform the build actions they prescribe (@pxref{The
10768 @cindex fixed-output derivations
10769 Operations such as file downloads and version-control checkouts for
10770 which the expected content hash is known in advance are modeled as
10771 @dfn{fixed-output derivations}. Unlike regular derivations, the outputs
10772 of a fixed-output derivation are independent of its inputs---e.g., a
10773 source code download produces the same result regardless of the download
10774 method and tools being used.
10777 @cindex run-time dependencies
10778 @cindex dependencies, run-time
10779 The outputs of derivations---i.e., the build results---have a set of
10780 @dfn{references}, as reported by the @code{references} RPC or the
10781 @command{guix gc --references} command (@pxref{Invoking guix gc}). References
10782 are the set of run-time dependencies of the build results. References are a
10783 subset of the inputs of the derivation; this subset is automatically computed
10784 by the build daemon by scanning all the files in the outputs.
10786 The @code{(guix derivations)} module provides a representation of
10787 derivations as Scheme objects, along with procedures to create and
10788 otherwise manipulate derivations. The lowest-level primitive to create
10789 a derivation is the @code{derivation} procedure:
10791 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
10792 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
10793 [#:recursive? #f] [#:inputs '()] [#:env-vars '()] @
10794 [#:system (%current-system)] [#:references-graphs #f] @
10795 [#:allowed-references #f] [#:disallowed-references #f] @
10796 [#:leaked-env-vars #f] [#:local-build? #f] @
10797 [#:substitutable? #t] [#:properties '()]
10798 Build a derivation with the given arguments, and return the resulting
10799 @code{<derivation>} object.
10801 When @var{hash} and @var{hash-algo} are given, a
10802 @dfn{fixed-output derivation} is created---i.e., one whose result is
10803 known in advance, such as a file download. If, in addition,
10804 @var{recursive?} is true, then that fixed output may be an executable
10805 file or a directory and @var{hash} must be the hash of an archive
10806 containing this output.
10808 When @var{references-graphs} is true, it must be a list of file
10809 name/store path pairs. In that case, the reference graph of each store
10810 path is exported in the build environment in the corresponding file, in
10811 a simple text format.
10813 When @var{allowed-references} is true, it must be a list of store items
10814 or outputs that the derivation's output may refer to. Likewise,
10815 @var{disallowed-references}, if true, must be a list of things the
10816 outputs may @emph{not} refer to.
10818 When @var{leaked-env-vars} is true, it must be a list of strings
10819 denoting environment variables that are allowed to ``leak'' from the
10820 daemon's environment to the build environment. This is only applicable
10821 to fixed-output derivations---i.e., when @var{hash} is true. The main
10822 use is to allow variables such as @code{http_proxy} to be passed to
10823 derivations that download files.
10825 When @var{local-build?} is true, declare that the derivation is not a
10826 good candidate for offloading and should rather be built locally
10827 (@pxref{Daemon Offload Setup}). This is the case for small derivations
10828 where the costs of data transfers would outweigh the benefits.
10830 When @var{substitutable?} is false, declare that substitutes of the
10831 derivation's output should not be used (@pxref{Substitutes}). This is
10832 useful, for instance, when building packages that capture details of the
10833 host CPU instruction set.
10835 @var{properties} must be an association list describing ``properties'' of the
10836 derivation. It is kept as-is, uninterpreted, in the derivation.
10840 Here's an example with a shell script as its builder, assuming
10841 @var{store} is an open connection to the daemon, and @var{bash} points
10842 to a Bash executable in the store:
10845 (use-modules (guix utils)
10847 (guix derivations))
10849 (let ((builder ; add the Bash script to the store
10850 (add-text-to-store store "my-builder.sh"
10851 "echo hello world > $out\n" '())))
10852 (derivation store "foo"
10853 bash `("-e" ,builder)
10854 #:inputs `((,bash) (,builder))
10855 #:env-vars '(("HOME" . "/homeless"))))
10856 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
10859 As can be guessed, this primitive is cumbersome to use directly. A
10860 better approach is to write build scripts in Scheme, of course! The
10861 best course of action for that is to write the build code as a
10862 ``G-expression'', and to pass it to @code{gexp->derivation}. For more
10863 information, @pxref{G-Expressions}.
10865 Once upon a time, @code{gexp->derivation} did not exist and constructing
10866 derivations with build code written in Scheme was achieved with
10867 @code{build-expression->derivation}, documented below. This procedure
10868 is now deprecated in favor of the much nicer @code{gexp->derivation}.
10870 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
10871 @var{name} @var{exp} @
10872 [#:system (%current-system)] [#:inputs '()] @
10873 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @
10874 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
10875 [#:references-graphs #f] [#:allowed-references #f] @
10876 [#:disallowed-references #f] @
10877 [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f]
10878 Return a derivation that executes Scheme expression @var{exp} as a
10879 builder for derivation @var{name}. @var{inputs} must be a list of
10880 @code{(name drv-path sub-drv)} tuples; when @var{sub-drv} is omitted,
10881 @code{"out"} is assumed. @var{modules} is a list of names of Guile
10882 modules from the current search path to be copied in the store,
10883 compiled, and made available in the load path during the execution of
10884 @var{exp}---e.g., @code{((guix build utils) (guix build
10885 gnu-build-system))}.
10887 @var{exp} is evaluated in an environment where @code{%outputs} is bound
10888 to a list of output/path pairs, and where @code{%build-inputs} is bound
10889 to a list of string/output-path pairs made from @var{inputs}.
10890 Optionally, @var{env-vars} is a list of string pairs specifying the name
10891 and value of environment variables visible to the builder. The builder
10892 terminates by passing the result of @var{exp} to @code{exit}; thus, when
10893 @var{exp} returns @code{#f}, the build is considered to have failed.
10895 @var{exp} is built using @var{guile-for-build} (a derivation). When
10896 @var{guile-for-build} is omitted or is @code{#f}, the value of the
10897 @code{%guile-for-build} fluid is used instead.
10899 See the @code{derivation} procedure for the meaning of
10900 @var{references-graphs}, @var{allowed-references},
10901 @var{disallowed-references}, @var{local-build?}, and
10902 @var{substitutable?}.
10906 Here's an example of a single-output derivation that creates a directory
10907 containing one file:
10910 (let ((builder '(let ((out (assoc-ref %outputs "out")))
10911 (mkdir out) ; create /gnu/store/@dots{}-goo
10912 (call-with-output-file (string-append out "/test")
10914 (display '(hello guix) p))))))
10915 (build-expression->derivation store "goo" builder))
10917 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
10921 @node The Store Monad
10922 @section The Store Monad
10926 The procedures that operate on the store described in the previous
10927 sections all take an open connection to the build daemon as their first
10928 argument. Although the underlying model is functional, they either have
10929 side effects or depend on the current state of the store.
10931 The former is inconvenient: the connection to the build daemon has to be
10932 carried around in all those functions, making it impossible to compose
10933 functions that do not take that parameter with functions that do. The
10934 latter can be problematic: since store operations have side effects
10935 and/or depend on external state, they have to be properly sequenced.
10937 @cindex monadic values
10938 @cindex monadic functions
10939 This is where the @code{(guix monads)} module comes in. This module
10940 provides a framework for working with @dfn{monads}, and a particularly
10941 useful monad for our uses, the @dfn{store monad}. Monads are a
10942 construct that allows two things: associating ``context'' with values
10943 (in our case, the context is the store), and building sequences of
10944 computations (here computations include accesses to the store). Values
10945 in a monad---values that carry this additional context---are called
10946 @dfn{monadic values}; procedures that return such values are called
10947 @dfn{monadic procedures}.
10949 Consider this ``normal'' procedure:
10952 (define (sh-symlink store)
10953 ;; Return a derivation that symlinks the 'bash' executable.
10954 (let* ((drv (package-derivation store bash))
10955 (out (derivation->output-path drv))
10956 (sh (string-append out "/bin/bash")))
10957 (build-expression->derivation store "sh"
10958 `(symlink ,sh %output))))
10961 Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten
10962 as a monadic function:
10965 (define (sh-symlink)
10966 ;; Same, but return a monadic value.
10967 (mlet %store-monad ((drv (package->derivation bash)))
10968 (gexp->derivation "sh"
10969 #~(symlink (string-append #$drv "/bin/bash")
10973 There are several things to note in the second version: the @code{store}
10974 parameter is now implicit and is ``threaded'' in the calls to the
10975 @code{package->derivation} and @code{gexp->derivation} monadic
10976 procedures, and the monadic value returned by @code{package->derivation}
10977 is @dfn{bound} using @code{mlet} instead of plain @code{let}.
10979 As it turns out, the call to @code{package->derivation} can even be
10980 omitted since it will take place implicitly, as we will see later
10981 (@pxref{G-Expressions}):
10984 (define (sh-symlink)
10985 (gexp->derivation "sh"
10986 #~(symlink (string-append #$bash "/bin/bash")
10991 @c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
10992 @c for the funny quote.
10993 Calling the monadic @code{sh-symlink} has no effect. As someone once
10994 said, ``you exit a monad like you exit a building on fire: by running''.
10995 So, to exit the monad and get the desired effect, one must use
10996 @code{run-with-store}:
10999 (run-with-store (open-connection) (sh-symlink))
11000 @result{} /gnu/store/...-sh-symlink
11003 Note that the @code{(guix monad-repl)} module extends the Guile REPL with
11004 new ``commands'' to make it easier to deal with monadic procedures:
11005 @code{run-in-store}, and @code{enter-store-monad} (@pxref{Using Guix
11006 Interactively}). The former is used
11007 to ``run'' a single monadic value through the store:
11010 scheme@@(guile-user)> ,run-in-store (package->derivation hello)
11011 $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
11014 The latter enters a recursive REPL, where all the return values are
11015 automatically run through the store:
11018 scheme@@(guile-user)> ,enter-store-monad
11019 store-monad@@(guile-user) [1]> (package->derivation hello)
11020 $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
11021 store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
11022 $3 = "/gnu/store/@dots{}-foo"
11023 store-monad@@(guile-user) [1]> ,q
11024 scheme@@(guile-user)>
11028 Note that non-monadic values cannot be returned in the
11029 @code{store-monad} REPL.
11031 Other meta-commands are available at the REPL, such as @code{,build} to
11032 build a file-like object (@pxref{Using Guix Interactively}).
11034 The main syntactic forms to deal with monads in general are provided by
11035 the @code{(guix monads)} module and are described below.
11037 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
11038 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being
11042 @deffn {Scheme Syntax} return @var{val}
11043 Return a monadic value that encapsulates @var{val}.
11046 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
11047 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
11048 procedures @var{mproc}@dots{}@footnote{This operation is commonly
11049 referred to as ``bind'', but that name denotes an unrelated procedure in
11050 Guile. Thus we use this somewhat cryptic symbol inherited from the
11051 Haskell language.}. There can be one @var{mproc} or several of them, as
11056 (with-monad %state-monad
11058 (lambda (x) (return (+ 1 x)))
11059 (lambda (x) (return (* 2 x)))))
11063 @result{} some-state
11067 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
11069 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
11071 Bind the variables @var{var} to the monadic values @var{mval} in
11072 @var{body}, which is a sequence of expressions. As with the bind
11073 operator, this can be thought of as ``unpacking'' the raw, non-monadic
11074 value ``contained'' in @var{mval} and making @var{var} refer to that
11075 raw, non-monadic value within the scope of the @var{body}. The form
11076 (@var{var} -> @var{val}) binds @var{var} to the ``normal'' value
11077 @var{val}, as per @code{let}. The binding operations occur in sequence
11078 from left to right. The last expression of @var{body} must be a monadic
11079 expression, and its result will become the result of the @code{mlet} or
11080 @code{mlet*} when run in the @var{monad}.
11082 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
11083 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
11086 @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
11087 Bind @var{mexp} and the following monadic expressions in sequence,
11088 returning the result of the last expression. Every expression in the
11089 sequence must be a monadic expression.
11091 This is akin to @code{mlet}, except that the return values of the
11092 monadic expressions are ignored. In that sense, it is analogous to
11093 @code{begin}, but applied to monadic expressions.
11096 @deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
11097 When @var{condition} is true, evaluate the sequence of monadic
11098 expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
11099 @var{condition} is false, return @code{*unspecified*} in the current
11100 monad. Every expression in the sequence must be a monadic expression.
11103 @deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ...
11104 When @var{condition} is false, evaluate the sequence of monadic
11105 expressions @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When
11106 @var{condition} is true, return @code{*unspecified*} in the current
11107 monad. Every expression in the sequence must be a monadic expression.
11110 @cindex state monad
11111 The @code{(guix monads)} module provides the @dfn{state monad}, which
11112 allows an additional value---the state---to be @emph{threaded} through
11113 monadic procedure calls.
11115 @defvr {Scheme Variable} %state-monad
11116 The state monad. Procedures in the state monad can access and change
11117 the state that is threaded.
11119 Consider the example below. The @code{square} procedure returns a value
11120 in the state monad. It returns the square of its argument, but also
11121 increments the current state value:
11125 (mlet %state-monad ((count (current-state)))
11126 (mbegin %state-monad
11127 (set-current-state (+ 1 count))
11128 (return (* x x)))))
11130 (run-with-state (sequence %state-monad (map square (iota 3))) 0)
11135 When ``run'' through @code{%state-monad}, we obtain that additional state
11136 value, which is the number of @code{square} calls.
11139 @deffn {Monadic Procedure} current-state
11140 Return the current state as a monadic value.
11143 @deffn {Monadic Procedure} set-current-state @var{value}
11144 Set the current state to @var{value} and return the previous state as a
11148 @deffn {Monadic Procedure} state-push @var{value}
11149 Push @var{value} to the current state, which is assumed to be a list,
11150 and return the previous state as a monadic value.
11153 @deffn {Monadic Procedure} state-pop
11154 Pop a value from the current state and return it as a monadic value.
11155 The state is assumed to be a list.
11158 @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
11159 Run monadic value @var{mval} starting with @var{state} as the initial
11160 state. Return two values: the resulting value, and the resulting state.
11163 The main interface to the store monad, provided by the @code{(guix
11164 store)} module, is as follows.
11166 @defvr {Scheme Variable} %store-monad
11167 The store monad---an alias for @code{%state-monad}.
11169 Values in the store monad encapsulate accesses to the store. When its
11170 effect is needed, a value of the store monad must be ``evaluated'' by
11171 passing it to the @code{run-with-store} procedure (see below).
11174 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
11175 Run @var{mval}, a monadic value in the store monad, in @var{store}, an
11176 open store connection.
11179 @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
11180 Return as a monadic value the absolute file name in the store of the file
11181 containing @var{text}, a string. @var{references} is a list of store items that the
11182 resulting text file refers to; it defaults to the empty list.
11185 @deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}]
11186 Return as a monadic value the absolute file name in the store of the file
11187 containing @var{data}, a bytevector. @var{references} is a list of store
11188 items that the resulting binary file refers to; it defaults to the empty list.
11191 @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
11192 [#:recursive? #t] [#:select? (const #t)]
11193 Return the name of @var{file} once interned in the store. Use
11194 @var{name} as its store name, or the basename of @var{file} if
11195 @var{name} is omitted.
11197 When @var{recursive?} is true, the contents of @var{file} are added
11198 recursively; if @var{file} designates a flat file and @var{recursive?}
11199 is true, its contents are added, and its permission bits are kept.
11201 When @var{recursive?} is true, call @code{(@var{select?} @var{file}
11202 @var{stat})} for each directory entry, where @var{file} is the entry's
11203 absolute file name and @var{stat} is the result of @code{lstat}; exclude
11204 entries for which @var{select?} does not return true.
11206 The example below adds a file to the store, under two different names:
11209 (run-with-store (open-connection)
11210 (mlet %store-monad ((a (interned-file "README"))
11211 (b (interned-file "README" "LEGU-MIN")))
11212 (return (list a b))))
11214 @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
11219 The @code{(guix packages)} module exports the following package-related
11220 monadic procedures:
11222 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
11223 [#:system (%current-system)] [#:target #f] @
11225 Return as a monadic
11226 value in the absolute file name of @var{file} within the @var{output}
11227 directory of @var{package}. When @var{file} is omitted, return the name
11228 of the @var{output} directory of @var{package}. When @var{target} is
11229 true, use it as a cross-compilation target triplet.
11231 Note that this procedure does @emph{not} build @var{package}. Thus, the
11232 result might or might not designate an existing file. We recommend not
11233 using this procedure unless you know what you are doing.
11236 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
11237 @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
11238 @var{target} [@var{system}]
11239 Monadic version of @code{package-derivation} and
11240 @code{package-cross-derivation} (@pxref{Defining Packages}).
11244 @node G-Expressions
11245 @section G-Expressions
11247 @cindex G-expression
11248 @cindex build code quoting
11249 So we have ``derivations'', which represent a sequence of build actions
11250 to be performed to produce an item in the store (@pxref{Derivations}).
11251 These build actions are performed when asking the daemon to actually
11252 build the derivations; they are run by the daemon in a container
11253 (@pxref{Invoking guix-daemon}).
11255 @cindex code staging
11256 @cindex staging, of code
11257 @cindex strata of code
11258 It should come as no surprise that we like to write these build actions
11259 in Scheme. When we do that, we end up with two @dfn{strata} of Scheme
11260 code@footnote{The term @dfn{stratum} in this context was coined by
11261 Manuel Serrano et al.@: in the context of their work on Hop. Oleg
11262 Kiselyov, who has written insightful
11263 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code
11264 on this topic}, refers to this kind of code generation as
11265 @dfn{staging}.}: the ``host code''---code that defines packages, talks
11266 to the daemon, etc.---and the ``build code''---code that actually
11267 performs build actions, such as making directories, invoking
11268 @command{make}, and so on (@pxref{Build Phases}).
11270 To describe a derivation and its build actions, one typically needs to
11271 embed build code inside host code. It boils down to manipulating build
11272 code as data, and the homoiconicity of Scheme---code has a direct
11273 representation as data---comes in handy for that. But we need more than
11274 the normal @code{quasiquote} mechanism in Scheme to construct build
11277 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
11278 S-expressions adapted to build expressions. G-expressions, or
11279 @dfn{gexps}, consist essentially of three syntactic forms: @code{gexp},
11280 @code{ungexp}, and @code{ungexp-splicing} (or simply: @code{#~},
11281 @code{#$}, and @code{#$@@}), which are comparable to
11282 @code{quasiquote}, @code{unquote}, and @code{unquote-splicing},
11283 respectively (@pxref{Expression Syntax, @code{quasiquote},, guile,
11284 GNU Guile Reference Manual}). However, there are major differences:
11288 Gexps are meant to be written to a file and run or manipulated by other
11292 When a high-level object such as a package or derivation is unquoted
11293 inside a gexp, the result is as if its output file name had been
11297 Gexps carry information about the packages or derivations they refer to,
11298 and these dependencies are automatically added as inputs to the build
11299 processes that use them.
11302 @cindex lowering, of high-level objects in gexps
11303 This mechanism is not limited to package and derivation
11304 objects: @dfn{compilers} able to ``lower'' other high-level objects to
11305 derivations or files in the store can be defined,
11306 such that these objects can also be inserted
11307 into gexps. For example, a useful type of high-level objects that can be
11308 inserted in a gexp is ``file-like objects'', which make it easy to
11309 add files to the store and to refer to them in
11310 derivations and such (see @code{local-file} and @code{plain-file}
11313 To illustrate the idea, here is an example of a gexp:
11320 (symlink (string-append #$coreutils "/bin/ls")
11324 This gexp can be passed to @code{gexp->derivation}; we obtain a
11325 derivation that builds a directory containing exactly one symlink to
11326 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
11329 (gexp->derivation "the-thing" build-exp)
11332 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string is
11333 substituted to the reference to the @var{coreutils} package in the
11334 actual build code, and @var{coreutils} is automatically made an input to
11335 the derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
11336 output)}) is replaced by a string containing the directory name of the
11337 output of the derivation.
11339 @cindex cross compilation
11340 In a cross-compilation context, it is useful to distinguish between
11341 references to the @emph{native} build of a package---that can run on the
11342 host---versus references to cross builds of a package. To that end, the
11343 @code{#+} plays the same role as @code{#$}, but is a reference to a
11344 native package build:
11347 (gexp->derivation "vi"
11350 (mkdir (string-append #$output "/bin"))
11351 (system* (string-append #+coreutils "/bin/ln")
11353 (string-append #$emacs "/bin/emacs")
11354 (string-append #$output "/bin/vi")))
11355 #:target "aarch64-linux-gnu")
11359 In the example above, the native build of @var{coreutils} is used, so
11360 that @command{ln} can actually run on the host; but then the
11361 cross-compiled build of @var{emacs} is referenced.
11363 @cindex imported modules, for gexps
11364 @findex with-imported-modules
11365 Another gexp feature is @dfn{imported modules}: sometimes you want to be
11366 able to use certain Guile modules from the ``host environment'' in the
11367 gexp, so those modules should be imported in the ``build environment''.
11368 The @code{with-imported-modules} form allows you to express that:
11371 (let ((build (with-imported-modules '((guix build utils))
11373 (use-modules (guix build utils))
11374 (mkdir-p (string-append #$output "/bin"))))))
11375 (gexp->derivation "empty-dir"
11378 (display "success!\n")
11383 In this example, the @code{(guix build utils)} module is automatically
11384 pulled into the isolated build environment of our gexp, such that
11385 @code{(use-modules (guix build utils))} works as expected.
11387 @cindex module closure
11388 @findex source-module-closure
11389 Usually you want the @emph{closure} of the module to be imported---i.e.,
11390 the module itself and all the modules it depends on---rather than just
11391 the module; failing to do that, attempts to use the module will fail
11392 because of missing dependent modules. The @code{source-module-closure}
11393 procedure computes the closure of a module by looking at its source file
11394 headers, which comes in handy in this case:
11397 (use-modules (guix modules)) ;for 'source-module-closure'
11399 (with-imported-modules (source-module-closure
11400 '((guix build utils)
11401 (gnu build image)))
11402 (gexp->derivation "something-with-vms"
11404 (use-modules (guix build utils)
11409 @cindex extensions, for gexps
11410 @findex with-extensions
11411 In the same vein, sometimes you want to import not just pure-Scheme
11412 modules, but also ``extensions'' such as Guile bindings to C libraries
11413 or other ``full-blown'' packages. Say you need the @code{guile-json}
11414 package available on the build side, here's how you would do it:
11417 (use-modules (gnu packages guile)) ;for 'guile-json'
11419 (with-extensions (list guile-json)
11420 (gexp->derivation "something-with-json"
11422 (use-modules (json))
11426 The syntactic form to construct gexps is summarized below.
11428 @deffn {Scheme Syntax} #~@var{exp}
11429 @deffnx {Scheme Syntax} (gexp @var{exp})
11430 Return a G-expression containing @var{exp}. @var{exp} may contain one
11431 or more of the following forms:
11435 @itemx (ungexp @var{obj})
11436 Introduce a reference to @var{obj}. @var{obj} may have one of the
11437 supported types, for example a package or a
11438 derivation, in which case the @code{ungexp} form is replaced by its
11439 output file name---e.g., @code{"/gnu/store/@dots{}-coreutils-8.22}.
11441 If @var{obj} is a list, it is traversed and references to supported
11442 objects are substituted similarly.
11444 If @var{obj} is another gexp, its contents are inserted and its
11445 dependencies are added to those of the containing gexp.
11447 If @var{obj} is another kind of object, it is inserted as is.
11449 @item #$@var{obj}:@var{output}
11450 @itemx (ungexp @var{obj} @var{output})
11451 This is like the form above, but referring explicitly to the
11452 @var{output} of @var{obj}---this is useful when @var{obj} produces
11453 multiple outputs (@pxref{Packages with Multiple Outputs}).
11456 @itemx #+@var{obj}:output
11457 @itemx (ungexp-native @var{obj})
11458 @itemx (ungexp-native @var{obj} @var{output})
11459 Same as @code{ungexp}, but produces a reference to the @emph{native}
11460 build of @var{obj} when used in a cross compilation context.
11462 @item #$output[:@var{output}]
11463 @itemx (ungexp output [@var{output}])
11464 Insert a reference to derivation output @var{output}, or to the main
11465 output when @var{output} is omitted.
11467 This only makes sense for gexps passed to @code{gexp->derivation}.
11469 @item #$@@@var{lst}
11470 @itemx (ungexp-splicing @var{lst})
11471 Like the above, but splices the contents of @var{lst} inside the
11474 @item #+@@@var{lst}
11475 @itemx (ungexp-native-splicing @var{lst})
11476 Like the above, but refers to native builds of the objects listed in
11481 G-expressions created by @code{gexp} or @code{#~} are run-time objects
11482 of the @code{gexp?} type (see below).
11485 @deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{}
11486 Mark the gexps defined in @var{body}@dots{} as requiring @var{modules}
11487 in their execution environment.
11489 Each item in @var{modules} can be the name of a module, such as
11490 @code{(guix build utils)}, or it can be a module name, followed by an
11491 arrow, followed by a file-like object:
11494 `((guix build utils)
11496 ((guix config) => ,(scheme-file "config.scm"
11497 #~(define-module @dots{}))))
11501 In the example above, the first two modules are taken from the search
11502 path, and the last one is created from the given file-like object.
11504 This form has @emph{lexical} scope: it has an effect on the gexps
11505 directly defined in @var{body}@dots{}, but not on those defined, say, in
11506 procedures called from @var{body}@dots{}.
11509 @deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
11510 Mark the gexps defined in @var{body}@dots{} as requiring
11511 @var{extensions} in their build and execution environment.
11512 @var{extensions} is typically a list of package objects such as those
11513 defined in the @code{(gnu packages guile)} module.
11515 Concretely, the packages listed in @var{extensions} are added to the
11516 load path while compiling imported modules in @var{body}@dots{}; they
11517 are also added to the load path of the gexp returned by
11521 @deffn {Scheme Procedure} gexp? @var{obj}
11522 Return @code{#t} if @var{obj} is a G-expression.
11525 G-expressions are meant to be written to disk, either as code building
11526 some derivation, or as plain files in the store. The monadic procedures
11527 below allow you to do that (@pxref{The Store Monad}, for more
11528 information about monads).
11530 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
11531 [#:system (%current-system)] [#:target #f] [#:graft? #t] @
11532 [#:hash #f] [#:hash-algo #f] @
11533 [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
11534 [#:module-path @code{%load-path}] @
11535 [#:effective-version "2.2"] @
11536 [#:references-graphs #f] [#:allowed-references #f] @
11537 [#:disallowed-references #f] @
11538 [#:leaked-env-vars #f] @
11539 [#:script-name (string-append @var{name} "-builder")] @
11540 [#:deprecation-warnings #f] @
11541 [#:local-build? #f] [#:substitutable? #t] @
11542 [#:properties '()] [#:guile-for-build #f]
11543 Return a derivation @var{name} that runs @var{exp} (a gexp) with
11544 @var{guile-for-build} (a derivation) on @var{system}; @var{exp} is
11545 stored in a file called @var{script-name}. When @var{target} is true,
11546 it is used as the cross-compilation target triplet for packages referred
11549 @var{modules} is deprecated in favor of @code{with-imported-modules}.
11551 make @var{modules} available in the evaluation context of @var{exp};
11552 @var{modules} is a list of names of Guile modules searched in
11553 @var{module-path} to be copied in the store, compiled, and made available in
11554 the load path during the execution of @var{exp}---e.g., @code{((guix
11555 build utils) (guix build gnu-build-system))}.
11557 @var{effective-version} determines the string to use when adding extensions of
11558 @var{exp} (see @code{with-extensions}) to the search path---e.g., @code{"2.2"}.
11560 @var{graft?} determines whether packages referred to by @var{exp} should be grafted when
11563 When @var{references-graphs} is true, it must be a list of tuples of one of the
11567 (@var{file-name} @var{package})
11568 (@var{file-name} @var{package} @var{output})
11569 (@var{file-name} @var{derivation})
11570 (@var{file-name} @var{derivation} @var{output})
11571 (@var{file-name} @var{store-item})
11574 The right-hand-side of each element of @var{references-graphs} is automatically made
11575 an input of the build process of @var{exp}. In the build environment, each
11576 @var{file-name} contains the reference graph of the corresponding item, in a simple
11579 @var{allowed-references} must be either @code{#f} or a list of output names and packages.
11580 In the latter case, the list denotes store items that the result is allowed to
11581 refer to. Any reference to another store item will lead to a build error.
11582 Similarly for @var{disallowed-references}, which can list items that must not be
11583 referenced by the outputs.
11585 @var{deprecation-warnings} determines whether to show deprecation warnings while
11586 compiling modules. It can be @code{#f}, @code{#t}, or @code{'detailed}.
11588 The other arguments are as for @code{derivation} (@pxref{Derivations}).
11591 @cindex file-like objects
11592 The @code{local-file}, @code{plain-file}, @code{computed-file},
11593 @code{program-file}, and @code{scheme-file} procedures below return
11594 @dfn{file-like objects}. That is, when unquoted in a G-expression,
11595 these objects lead to a file in the store. Consider this G-expression:
11598 #~(system* #$(file-append glibc "/sbin/nscd") "-f"
11599 #$(local-file "/tmp/my-nscd.conf"))
11602 The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it
11603 to the store. Once expanded, for instance @i{via}
11604 @code{gexp->derivation}, the G-expression refers to that copy under
11605 @file{/gnu/store}; thus, modifying or removing the file in @file{/tmp}
11606 does not have any effect on what the G-expression does.
11607 @code{plain-file} can be used similarly; it differs in that the file
11608 content is directly passed as a string.
11610 @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
11611 [#:recursive? #f] [#:select? (const #t)]
11612 Return an object representing local file @var{file} to add to the store;
11613 this object can be used in a gexp. If @var{file} is a literal string
11614 denoting a relative file name, it is looked up relative to the source
11615 file where it appears; if @var{file} is not a literal string, it is
11616 looked up relative to the current working directory at run time.
11617 @var{file} will be added to the store under @var{name}--by default the
11618 base name of @var{file}.
11620 When @var{recursive?} is true, the contents of @var{file} are added recursively; if @var{file}
11621 designates a flat file and @var{recursive?} is true, its contents are added, and its
11622 permission bits are kept.
11624 When @var{recursive?} is true, call @code{(@var{select?} @var{file}
11625 @var{stat})} for each directory entry, where @var{file} is the entry's
11626 absolute file name and @var{stat} is the result of @code{lstat}; exclude
11627 entries for which @var{select?} does not return true.
11629 This is the declarative counterpart of the @code{interned-file} monadic
11630 procedure (@pxref{The Store Monad, @code{interned-file}}).
11633 @deffn {Scheme Procedure} plain-file @var{name} @var{content}
11634 Return an object representing a text file called @var{name} with the given
11635 @var{content} (a string or a bytevector) to be added to the store.
11637 This is the declarative counterpart of @code{text-file}.
11640 @deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
11641 [#:local-build? #t]
11643 Return an object representing the store item @var{name}, a file or
11644 directory computed by @var{gexp}. When @var{local-build?} is true (the
11645 default), the derivation is built locally. @var{options} is a list of
11646 additional arguments to pass to @code{gexp->derivation}.
11648 This is the declarative counterpart of @code{gexp->derivation}.
11651 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
11652 [#:guile (default-guile)] [#:module-path %load-path] @
11653 [#:system (%current-system)] [#:target #f]
11654 Return an executable script @var{name} that runs @var{exp} using
11655 @var{guile}, with @var{exp}'s imported modules in its search path.
11656 Look up @var{exp}'s modules in @var{module-path}.
11658 The example below builds a script that simply invokes the @command{ls}
11662 (use-modules (guix gexp) (gnu packages base))
11664 (gexp->script "list-files"
11665 #~(execl #$(file-append coreutils "/bin/ls")
11669 When ``running'' it through the store (@pxref{The Store Monad,
11670 @code{run-with-store}}), we obtain a derivation that produces an
11671 executable file @file{/gnu/store/@dots{}-list-files} along these lines:
11674 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
11676 (execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
11680 @deffn {Scheme Procedure} program-file @var{name} @var{exp} @
11681 [#:guile #f] [#:module-path %load-path]
11682 Return an object representing the executable store item @var{name} that
11683 runs @var{gexp}. @var{guile} is the Guile package used to execute that
11684 script. Imported modules of @var{gexp} are looked up in @var{module-path}.
11686 This is the declarative counterpart of @code{gexp->script}.
11689 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
11690 [#:set-load-path? #t] [#:module-path %load-path] @
11692 [#:guile (default-guile)]
11693 Return a derivation that builds a file @var{name} containing @var{exp}.
11694 When @var{splice?} is true, @var{exp} is considered to be a list of
11695 expressions that will be spliced in the resulting file.
11697 When @var{set-load-path?} is true, emit code in the resulting file to
11698 set @code{%load-path} and @code{%load-compiled-path} to honor
11699 @var{exp}'s imported modules. Look up @var{exp}'s modules in
11702 The resulting file holds references to all the dependencies of @var{exp}
11703 or a subset thereof.
11706 @deffn {Scheme Procedure} scheme-file @var{name} @var{exp} @
11707 [#:splice? #f] [#:set-load-path? #t]
11708 Return an object representing the Scheme file @var{name} that contains
11711 This is the declarative counterpart of @code{gexp->file}.
11714 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
11715 Return as a monadic value a derivation that builds a text file
11716 containing all of @var{text}. @var{text} may list, in addition to
11717 strings, objects of any type that can be used in a gexp: packages,
11718 derivations, local file objects, etc. The resulting store file holds
11719 references to all these.
11721 This variant should be preferred over @code{text-file} anytime the file
11722 to create will reference items from the store. This is typically the
11723 case when building a configuration file that embeds store file names,
11727 (define (profile.sh)
11728 ;; Return the name of a shell script in the store that
11729 ;; initializes the 'PATH' environment variable.
11730 (text-file* "profile.sh"
11731 "export PATH=" coreutils "/bin:"
11732 grep "/bin:" sed "/bin\n"))
11735 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
11736 will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
11737 preventing them from being garbage-collected during its lifetime.
11740 @deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
11741 Return an object representing store file @var{name} containing
11742 @var{text}. @var{text} is a sequence of strings and file-like objects,
11746 (mixed-text-file "profile"
11747 "export PATH=" coreutils "/bin:" grep "/bin")
11750 This is the declarative counterpart of @code{text-file*}.
11753 @deffn {Scheme Procedure} file-union @var{name} @var{files}
11754 Return a @code{<computed-file>} that builds a directory containing all of @var{files}.
11755 Each item in @var{files} must be a two-element list where the first element is the
11756 file name to use in the new directory, and the second element is a gexp
11757 denoting the target file. Here's an example:
11761 `(("hosts" ,(plain-file "hosts"
11762 "127.0.0.1 localhost"))
11763 ("bashrc" ,(plain-file "bashrc"
11764 "alias ls='ls --color=auto'"))))
11767 This yields an @code{etc} directory containing these two files.
11770 @deffn {Scheme Procedure} directory-union @var{name} @var{things}
11771 Return a directory that is the union of @var{things}, where @var{things} is a list of
11772 file-like objects denoting directories. For example:
11775 (directory-union "guile+emacs" (list guile emacs))
11778 yields a directory that is the union of the @code{guile} and @code{emacs} packages.
11781 @deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
11782 Return a file-like object that expands to the concatenation of @var{obj}
11783 and @var{suffix}, where @var{obj} is a lowerable object and each
11784 @var{suffix} is a string.
11786 As an example, consider this gexp:
11789 (gexp->script "run-uname"
11790 #~(system* #$(file-append coreutils
11794 The same effect could be achieved with:
11797 (gexp->script "run-uname"
11798 #~(system* (string-append #$coreutils
11802 There is one difference though: in the @code{file-append} case, the
11803 resulting script contains the absolute file name as a string, whereas in
11804 the second case, the resulting script contains a @code{(string-append
11805 @dots{})} expression to construct the file name @emph{at run time}.
11808 @deffn {Scheme Syntax} let-system @var{system} @var{body}@dots{}
11809 @deffnx {Scheme Syntax} let-system (@var{system} @var{target}) @var{body}@dots{}
11810 Bind @var{system} to the currently targeted system---e.g.,
11811 @code{"x86_64-linux"}---within @var{body}.
11813 In the second case, additionally bind @var{target} to the current
11814 cross-compilation target---a GNU triplet such as
11815 @code{"arm-linux-gnueabihf"}---or @code{#f} if we are not
11818 @code{let-system} is useful in the occasional case where the object
11819 spliced into the gexp depends on the target system, as in this example:
11823 #+(let-system system
11824 (cond ((string-prefix? "armhf-" system)
11825 (file-append qemu "/bin/qemu-system-arm"))
11826 ((string-prefix? "x86_64-" system)
11827 (file-append qemu "/bin/qemu-system-x86_64"))
11829 (error "dunno!"))))
11830 "-net" "user" #$image)
11834 @deffn {Scheme Syntax} with-parameters ((@var{parameter} @var{value}) @dots{}) @var{exp}
11835 This macro is similar to the @code{parameterize} form for
11836 dynamically-bound @dfn{parameters} (@pxref{Parameters,,, guile, GNU
11837 Guile Reference Manual}). The key difference is that it takes effect
11838 when the file-like object returned by @var{exp} is lowered to a
11839 derivation or store item.
11841 A typical use of @code{with-parameters} is to force the system in effect
11842 for a given object:
11845 (with-parameters ((%current-system "i686-linux"))
11849 The example above returns an object that corresponds to the i686 build
11850 of Coreutils, regardless of the current value of @code{%current-system}.
11854 Of course, in addition to gexps embedded in ``host'' code, there are
11855 also modules containing build tools. To make it clear that they are
11856 meant to be used in the build stratum, these modules are kept in the
11857 @code{(guix build @dots{})} name space.
11859 @cindex lowering, of high-level objects in gexps
11860 Internally, high-level objects are @dfn{lowered}, using their compiler,
11861 to either derivations or store items. For instance, lowering a package
11862 yields a derivation, and lowering a @code{plain-file} yields a store
11863 item. This is achieved using the @code{lower-object} monadic procedure.
11865 @deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
11867 Return as a value in @code{%store-monad} the derivation or store item
11868 corresponding to @var{obj} for @var{system}, cross-compiling for
11869 @var{target} if @var{target} is true. @var{obj} must be an object that
11870 has an associated gexp compiler, such as a @code{<package>}.
11873 @deffn {Procedure} gexp->approximate-sexp @var{gexp}
11874 Sometimes, it may be useful to convert a G-exp into a S-exp. For
11875 example, some linters (@pxref{Invoking guix lint}) peek into the build
11876 phases of a package to detect potential problems. This conversion can
11877 be achieved with this procedure. However, some information can be lost
11878 in the process. More specifically, lowerable objects will be silently
11879 replaced with some arbitrary object -- currently the list
11880 @code{(*approximate*)}, but this may change.
11883 @node Invoking guix repl
11884 @section Invoking @command{guix repl}
11886 @cindex @command{guix repl}
11887 @cindex REPL, read-eval-print loop, script
11888 The @command{guix repl} command makes it easier to program Guix in Guile
11889 by launching a Guile @dfn{read-eval-print loop} (REPL) for interactive
11890 programming (@pxref{Using Guile Interactively,,, guile,
11891 GNU Guile Reference Manual}), or by running Guile scripts
11892 (@pxref{Running Guile Scripts,,, guile,
11893 GNU Guile Reference Manual}).
11894 Compared to just launching the @command{guile}
11895 command, @command{guix repl} guarantees that all the Guix modules and all its
11896 dependencies are available in the search path.
11898 The general syntax is:
11901 guix repl @var{options} [@var{file} @var{args}]
11904 When a @var{file} argument is provided, @var{file} is
11905 executed as a Guile scripts:
11908 guix repl my-script.scm
11911 To pass arguments to the script, use @code{--} to prevent them from
11912 being interpreted as arguments to @command{guix repl} itself:
11915 guix repl -- my-script.scm --input=foo.txt
11918 To make a script executable directly from the shell, using the guix
11919 executable that is on the user's search path, add the following two
11920 lines at the top of the script:
11923 @code{#!/usr/bin/env -S guix repl --}
11927 Without a file name argument, a Guile REPL is started, allowing for
11928 interactive use (@pxref{Using Guix Interactively}):
11932 scheme@@(guile-user)> ,use (gnu packages base)
11933 scheme@@(guile-user)> coreutils
11934 $1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
11938 In addition, @command{guix repl} implements a simple machine-readable REPL
11939 protocol for use by @code{(guix inferior)}, a facility to interact with
11940 @dfn{inferiors}, separate processes running a potentially different revision
11943 The available options are as follows:
11946 @item --type=@var{type}
11947 @itemx -t @var{type}
11948 Start a REPL of the given @var{TYPE}, which can be one of the following:
11952 This is default, and it spawns a standard full-featured Guile REPL.
11954 Spawn a REPL that uses the machine-readable protocol. This is the protocol
11955 that the @code{(guix inferior)} module speaks.
11958 @item --listen=@var{endpoint}
11959 By default, @command{guix repl} reads from standard input and writes to
11960 standard output. When this option is passed, it will instead listen for
11961 connections on @var{endpoint}. Here are examples of valid options:
11964 @item --listen=tcp:37146
11965 Accept connections on localhost on port 37146.
11967 @item --listen=unix:/tmp/socket
11968 Accept connections on the Unix-domain socket @file{/tmp/socket}.
11971 @item --load-path=@var{directory}
11972 @itemx -L @var{directory}
11973 Add @var{directory} to the front of the package module search path
11974 (@pxref{Package Modules}).
11976 This allows users to define their own packages and make them visible to
11977 the script or REPL.
11980 Inhibit loading of the @file{~/.guile} file. By default, that
11981 configuration file is loaded when spawning a @code{guile} REPL.
11984 @node Using Guix Interactively
11985 @section Using Guix Interactively
11987 @cindex interactive use
11988 @cindex REPL, read-eval-print loop
11989 The @command{guix repl} command gives you access to a warm and friendly
11990 @dfn{read-eval-print loop} (REPL) (@pxref{Invoking guix repl}). If
11991 you're getting into Guix programming---defining your own packages,
11992 writing manifests, defining services for Guix System or Guix Home,
11993 etc.---you will surely find it convenient to toy with ideas at the REPL.
11995 If you use Emacs, the most convenient way to do that is with Geiser
11996 (@pxref{The Perfect Setup}), but you do not have to use Emacs to enjoy
11997 the REPL@. When using @command{guix repl} or @command{guile} in the
11998 terminal, we recommend using Readline for completion and Colorized to
11999 get colorful output. To do that, you can run:
12002 guix install guile guile-readline guile-colorized
12006 ... and then create a @file{.guile} file in your home directory containing
12010 (use-modules (ice-9 readline) (ice-9 colorized))
12012 (activate-readline)
12013 (activate-colorized)
12016 The REPL lets you evaluate Scheme code; you type a Scheme expression at
12017 the prompt, and the REPL prints what it evaluates to:
12021 scheme@@(guix-user)> (+ 2 3)
12023 scheme@@(guix-user)> (string-append "a" "b")
12027 It becomes interesting when you start fiddling with Guix at the REPL.
12028 The first thing you'll want to do is to ``import'' the @code{(guix)}
12029 module, which gives access to the main part of the programming
12030 interface, and perhaps a bunch of useful Guix modules. You could type
12031 @code{(use-modules (guix))}, which is valid Scheme code to import a
12032 module (@pxref{Using Guile Modules,,, guile, GNU Guile Reference
12033 Manual}), but the REPL provides the @code{use} @dfn{command} as a
12034 shorthand notation (@pxref{REPL Commands,,, guile, GNU Guile Reference
12038 scheme@@(guix-user)> ,use (guix)
12039 scheme@@(guix-user)> ,use (gnu packages base)
12042 Notice that REPL commands are introduced by a leading comma. A REPL
12043 command like @code{use} is not valid Scheme code; it's interpreted
12044 specially by the REPL.
12046 Guix extends the Guile REPL with additional commands for convenience.
12047 Among those, the @code{build} command comes in handy: it ensures that
12048 the given file-like object is built, building it if needed, and returns
12049 its output file name(s). In the example below, we build the
12050 @code{coreutils} and @code{grep} packages, as well as a ``computed
12051 file'' (@pxref{G-Expressions, @code{computed-file}}), and we use the
12052 @code{scandir} procedure to list the files in Grep's @code{/bin}
12056 scheme@@(guix-user)> ,build coreutils
12057 $1 = "/gnu/store/@dots{}-coreutils-8.32-debug"
12058 $2 = "/gnu/store/@dots{}-coreutils-8.32"
12059 scheme@@(guix-user)> ,build grep
12060 $3 = "/gnu/store/@dots{}-grep-3.6"
12061 scheme@@(guix-user)> ,build (computed-file "x" #~(mkdir #$output))
12062 building /gnu/store/@dots{}-x.drv...
12063 $4 = "/gnu/store/@dots{}-x"
12064 scheme@@(guix-user)> ,use(ice-9 ftw)
12065 scheme@@(guix-user)> (scandir (string-append $3 "/bin"))
12066 $5 = ("." ".." "egrep" "fgrep" "grep")
12069 At a lower-level, a useful command is @code{lower}: it takes a file-like
12070 object and ``lowers'' it into a derivation (@pxref{Derivations}) or a
12074 scheme@@(guix-user)> ,lower grep
12075 $6 = #<derivation /gnu/store/@dots{}-grep-3.6.drv => /gnu/store/@dots{}-grep-3.6 7f0e639115f0>
12076 scheme@@(guix-user)> ,lower (plain-file "x" "Hello!")
12077 $7 = "/gnu/store/@dots{}-x"
12080 The full list of REPL commands can be seen by typing @code{,help guix}
12081 and is given below for reference.
12083 @deffn {REPL command} build @var{object}
12084 Lower @var{object} and build it if it's not already built, returning its
12085 output file name(s).
12088 @deffn {REPL command} lower @var{object}
12089 Lower @var{object} into a derivation or store file name and return it.
12092 @deffn {REPL command} verbosity @var{level}
12093 Change build verbosity to @var{level}.
12095 This is similar to the @option{--verbosity} command-line option
12096 (@pxref{Common Build Options}): level 0 means total silence, level 1
12097 shows build events only, and higher levels print build logs.
12100 @deffn {REPL command} run-in-store @var{exp}
12101 Run @var{exp}, a monadic expresssion, through the store monad.
12102 @xref{The Store Monad}, for more information.
12105 @deffn {REPL command} enter-store-monad
12106 Enter a new REPL to evaluate monadic expressions (@pxref{The Store
12107 Monad}). You can quit this ``inner'' REPL by typing @code{,q}.
12110 @c *********************************************************************
12114 This section describes Guix command-line utilities. Some of them are
12115 primarily targeted at developers and users who write new package
12116 definitions, while others are more generally useful. They complement
12117 the Scheme programming interface of Guix in a convenient way.
12120 * Invoking guix build:: Building packages from the command line.
12121 * Invoking guix edit:: Editing package definitions.
12122 * Invoking guix download:: Downloading a file and printing its hash.
12123 * Invoking guix hash:: Computing the cryptographic hash of a file.
12124 * Invoking guix import:: Importing package definitions.
12125 * Invoking guix refresh:: Updating package definitions.
12126 * Invoking guix style:: Styling package definitions.
12127 * Invoking guix lint:: Finding errors in package definitions.
12128 * Invoking guix size:: Profiling disk usage.
12129 * Invoking guix graph:: Visualizing the graph of packages.
12130 * Invoking guix publish:: Sharing substitutes.
12131 * Invoking guix challenge:: Challenging substitute servers.
12132 * Invoking guix copy:: Copying to and from a remote store.
12133 * Invoking guix container:: Process isolation.
12134 * Invoking guix weather:: Assessing substitute availability.
12135 * Invoking guix processes:: Listing client processes.
12138 @node Invoking guix build
12139 @section Invoking @command{guix build}
12141 @cindex package building
12142 @cindex @command{guix build}
12143 The @command{guix build} command builds packages or derivations and
12144 their dependencies, and prints the resulting store paths. Note that it
12145 does not modify the user's profile---this is the job of the
12146 @command{guix package} command (@pxref{Invoking guix package}). Thus,
12147 it is mainly useful for distribution developers.
12149 The general syntax is:
12152 guix build @var{options} @var{package-or-derivation}@dots{}
12155 As an example, the following command builds the latest versions of Emacs
12156 and of Guile, displays their build logs, and finally displays the
12157 resulting directories:
12160 guix build emacs guile
12163 Similarly, the following command builds all the available packages:
12166 guix build --quiet --keep-going \
12167 $(guix package -A | awk '@{ print $1 "@@" $2 @}')
12170 @var{package-or-derivation} may be either the name of a package found in
12171 the software distribution such as @code{coreutils} or
12172 @code{coreutils@@8.20}, or a derivation such as
12173 @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the former case, a
12174 package with the corresponding name (and optionally version) is searched
12175 for among the GNU distribution modules (@pxref{Package Modules}).
12177 Alternatively, the @option{--expression} option may be used to specify a
12178 Scheme expression that evaluates to a package; this is useful when
12179 disambiguating among several same-named packages or package variants is
12182 There may be zero or more @var{options}. The available options are
12183 described in the subsections below.
12186 * Common Build Options:: Build options for most commands.
12187 * Package Transformation Options:: Creating variants of packages.
12188 * Additional Build Options:: Options specific to 'guix build'.
12189 * Debugging Build Failures:: Real life packaging experience.
12192 @node Common Build Options
12193 @subsection Common Build Options
12195 A number of options that control the build process are common to
12196 @command{guix build} and other commands that can spawn builds, such as
12197 @command{guix package} or @command{guix archive}. These are the
12202 @item --load-path=@var{directory}
12203 @itemx -L @var{directory}
12204 Add @var{directory} to the front of the package module search path
12205 (@pxref{Package Modules}).
12207 This allows users to define their own packages and make them visible to
12208 the command-line tools.
12210 @item --keep-failed
12212 Keep the build tree of failed builds. Thus, if a build fails, its build
12213 tree is kept under @file{/tmp}, in a directory whose name is shown at
12214 the end of the build log. This is useful when debugging build issues.
12215 @xref{Debugging Build Failures}, for tips and tricks on how to debug
12218 This option implies @option{--no-offload}, and it has no effect when
12219 connecting to a remote daemon with a @code{guix://} URI (@pxref{The
12220 Store, the @env{GUIX_DAEMON_SOCKET} variable}).
12224 Keep going when some of the derivations fail to build; return only once
12225 all the builds have either completed or failed.
12227 The default behavior is to stop as soon as one of the specified
12228 derivations has failed.
12232 Do not build the derivations.
12234 @anchor{fallback-option}
12236 When substituting a pre-built binary fails, fall back to building
12237 packages locally (@pxref{Substitution Failure}).
12239 @item --substitute-urls=@var{urls}
12240 @anchor{client-substitute-urls}
12241 Consider @var{urls} the whitespace-separated list of substitute source
12242 URLs, overriding the default list of URLs of @command{guix-daemon}
12243 (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
12245 This means that substitutes may be downloaded from @var{urls}, provided
12246 they are signed by a key authorized by the system administrator
12247 (@pxref{Substitutes}).
12249 When @var{urls} is the empty string, substitutes are effectively
12252 @item --no-substitutes
12253 Do not use substitutes for build products. That is, always build things
12254 locally instead of allowing downloads of pre-built binaries
12255 (@pxref{Substitutes}).
12258 Do not ``graft'' packages. In practice, this means that package updates
12259 available as grafts are not applied. @xref{Security Updates}, for more
12260 information on grafts.
12262 @item --rounds=@var{n}
12263 Build each derivation @var{n} times in a row, and raise an error if
12264 consecutive build results are not bit-for-bit identical.
12266 This is a useful way to detect non-deterministic builds processes.
12267 Non-deterministic build processes are a problem because they make it
12268 practically impossible for users to @emph{verify} whether third-party
12269 binaries are genuine. @xref{Invoking guix challenge}, for more.
12271 When used in conjunction with @option{--keep-failed}, the differing
12272 output is kept in the store, under @file{/gnu/store/@dots{}-check}.
12273 This makes it easy to look for differences between the two results.
12276 Do not use offload builds to other machines (@pxref{Daemon Offload
12277 Setup}). That is, always build things locally instead of offloading
12278 builds to remote machines.
12280 @item --max-silent-time=@var{seconds}
12281 When the build or substitution process remains silent for more than
12282 @var{seconds}, terminate it and report a build failure.
12284 By default, the daemon's setting is honored (@pxref{Invoking
12285 guix-daemon, @option{--max-silent-time}}).
12287 @item --timeout=@var{seconds}
12288 Likewise, when the build or substitution process lasts for more than
12289 @var{seconds}, terminate it and report a build failure.
12291 By default, the daemon's setting is honored (@pxref{Invoking
12292 guix-daemon, @option{--timeout}}).
12294 @c Note: This option is actually not part of %standard-build-options but
12295 @c most programs honor it.
12296 @cindex verbosity, of the command-line tools
12297 @cindex build logs, verbosity
12298 @item -v @var{level}
12299 @itemx --verbosity=@var{level}
12300 Use the given verbosity @var{level}, an integer. Choosing 0 means that
12301 no output is produced, 1 is for quiet output; 2 is similar to 1 but it
12302 additionally displays download URLs; 3 shows all the build log output on
12305 @item --cores=@var{n}
12307 Allow the use of up to @var{n} CPU cores for the build. The special
12308 value @code{0} means to use as many CPU cores as available.
12310 @item --max-jobs=@var{n}
12312 Allow at most @var{n} build jobs in parallel. @xref{Invoking
12313 guix-daemon, @option{--max-jobs}}, for details about this option and the
12314 equivalent @command{guix-daemon} option.
12316 @item --debug=@var{level}
12317 Produce debugging output coming from the build daemon. @var{level} must be an
12318 integer between 0 and 5; higher means more verbose output. Setting a level of
12319 4 or more may be helpful when debugging setup issues with the build daemon.
12323 Behind the scenes, @command{guix build} is essentially an interface to
12324 the @code{package-derivation} procedure of the @code{(guix packages)}
12325 module, and to the @code{build-derivations} procedure of the @code{(guix
12326 derivations)} module.
12328 In addition to options explicitly passed on the command line,
12329 @command{guix build} and other @command{guix} commands that support
12330 building honor the @env{GUIX_BUILD_OPTIONS} environment variable.
12332 @defvr {Environment Variable} GUIX_BUILD_OPTIONS
12333 Users can define this variable to a list of command line options that
12334 will automatically be used by @command{guix build} and other
12335 @command{guix} commands that can perform builds, as in the example
12339 $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
12342 These options are parsed independently, and the result is appended to
12343 the parsed command-line options.
12347 @node Package Transformation Options
12348 @subsection Package Transformation Options
12350 @cindex package variants
12351 Another set of command-line options supported by @command{guix build}
12352 and also @command{guix package} are @dfn{package transformation
12353 options}. These are options that make it possible to define @dfn{package
12354 variants}---for instance, packages built from different source code.
12355 This is a convenient way to create customized packages on the fly
12356 without having to type in the definitions of package variants
12357 (@pxref{Defining Packages}).
12359 Package transformation options are preserved across upgrades:
12360 @command{guix upgrade} attempts to apply transformation options
12361 initially used when creating the profile to the upgraded packages.
12363 The available options are listed below. Most commands support them and
12364 also support a @option{--help-transform} option that lists all the
12365 available options and a synopsis (these options are not shown in the
12366 @option{--help} output for brevity).
12370 @cindex performance, tuning code
12371 @cindex optimization, of package code
12372 @cindex tuning, of package code
12373 @cindex SIMD support
12374 @cindex tunable packages
12375 @cindex package multi-versioning
12376 @item --tune[=@var{cpu}]
12377 Use versions of the packages marked as ``tunable'' optimized for
12378 @var{cpu}. When @var{cpu} is @code{native}, or when it is omitted, tune
12379 for the CPU on which the @command{guix} command is running.
12381 Valid @var{cpu} names are those recognized by the underlying compiler,
12382 by default the GNU Compiler Collection. On x86_64 processors, this
12383 includes CPU names such as @code{nehalem}, @code{haswell}, and
12384 @code{skylake} (@pxref{x86 Options, @code{-march},, gcc, Using the GNU
12385 Compiler Collection (GCC)}).
12387 As new generations of CPUs come out, they augment the standard
12388 instruction set architecture (ISA) with additional instructions, in
12389 particular instructions for single-instruction/multiple-data (SIMD)
12390 parallel processing. For example, while Core2 and Skylake CPUs both
12391 implement the x86_64 ISA, only the latter supports AVX2 SIMD
12394 The primary gain one can expect from @option{--tune} is for programs
12395 that can make use of those SIMD capabilities @emph{and} that do not
12396 already have a mechanism to select the right optimized code at run time.
12397 Packages that have the @code{tunable?} property set are considered
12398 @dfn{tunable packages} by the @option{--tune} option; a package
12399 definition with the property set looks like this:
12403 (name "hello-simd")
12406 ;; This package may benefit from SIMD extensions so
12407 ;; mark it as "tunable".
12408 (properties '((tunable? . #t))))
12411 Other packages are not considered tunable. This allows Guix to use
12412 generic binaries in the cases where tuning for a specific CPU is
12413 unlikely to provide any gain.
12415 Tuned packages are built with @code{-march=@var{CPU}}; under the hood,
12416 the @option{-march} option is passed to the actual wrapper by a compiler
12417 wrapper. Since the build machine may not be able to run code for the
12418 target CPU micro-architecture, the test suite is not run when building a
12421 To reduce rebuilds to the minimum, tuned packages are @emph{grafted}
12422 onto packages that depend on them (@pxref{Security Updates, grafts}).
12423 Thus, using @option{--no-grafts} cancels the effect of @option{--tune}.
12425 We call this technique @dfn{package multi-versioning}: several variants
12426 of tunable packages may be built, one for each CPU variant. It is the
12427 coarse-grain counterpart of @dfn{function multi-versioning} as
12428 implemented by the GNU tool chain (@pxref{Function Multiversioning,,,
12429 gcc, Using the GNU Compiler Collection (GCC)}).
12431 @item --with-source=@var{source}
12432 @itemx --with-source=@var{package}=@var{source}
12433 @itemx --with-source=@var{package}@@@var{version}=@var{source}
12434 Use @var{source} as the source of @var{package}, and @var{version} as
12435 its version number.
12436 @var{source} must be a file name or a URL, as for @command{guix
12437 download} (@pxref{Invoking guix download}).
12439 When @var{package} is omitted,
12440 it is taken to be the package name specified on the
12441 command line that matches the base of @var{source}---e.g.,
12442 if @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding
12443 package is @code{guile}.
12445 Likewise, when @var{version} is omitted, the version string is inferred from
12446 @var{source}; in the previous example, it is @code{2.0.10}.
12448 This option allows users to try out versions of packages other than the
12449 one provided by the distribution. The example below downloads
12450 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for
12451 the @code{ed} package:
12454 guix build ed --with-source=mirror://gnu/ed/ed-1.4.tar.gz
12457 As a developer, @option{--with-source} makes it easy to test release
12458 candidates, and even to test their impact on packages that depend on
12462 guix build elogind --with-source=@dots{}/shepherd-0.9.0rc1.tar.gz
12465 @dots{} or to build from a checkout in a pristine environment:
12468 $ git clone git://git.sv.gnu.org/guix.git
12469 $ guix build guix --with-source=guix@@1.0=./guix
12472 @item --with-input=@var{package}=@var{replacement}
12473 Replace dependency on @var{package} by a dependency on
12474 @var{replacement}. @var{package} must be a package name, and
12475 @var{replacement} must be a package specification such as @code{guile}
12476 or @code{guile@@1.8}.
12478 For instance, the following command builds Guix, but replaces its
12479 dependency on the current stable version of Guile with a dependency on
12480 the legacy version of Guile, @code{guile@@2.0}:
12483 guix build --with-input=guile=guile@@2.0 guix
12486 This is a recursive, deep replacement. So in this example, both
12487 @code{guix} and its dependency @code{guile-json} (which also depends on
12488 @code{guile}) get rebuilt against @code{guile@@2.0}.
12490 This is implemented using the @code{package-input-rewriting} Scheme
12491 procedure (@pxref{Defining Packages, @code{package-input-rewriting}}).
12493 @item --with-graft=@var{package}=@var{replacement}
12494 This is similar to @option{--with-input} but with an important difference:
12495 instead of rebuilding the whole dependency chain, @var{replacement} is
12496 built and then @dfn{grafted} onto the binaries that were initially
12497 referring to @var{package}. @xref{Security Updates}, for more
12498 information on grafts.
12500 For example, the command below grafts version 3.5.4 of GnuTLS onto Wget
12501 and all its dependencies, replacing references to the version of GnuTLS
12502 they currently refer to:
12505 guix build --with-graft=gnutls=gnutls@@3.5.4 wget
12508 This has the advantage of being much faster than rebuilding everything.
12509 But there is a caveat: it works if and only if @var{package} and
12510 @var{replacement} are strictly compatible---for example, if they provide
12511 a library, the application binary interface (ABI) of those libraries
12512 must be compatible. If @var{replacement} is somehow incompatible with
12513 @var{package}, then the resulting package may be unusable. Use with
12516 @cindex debugging info, rebuilding
12517 @item --with-debug-info=@var{package}
12518 Build @var{package} in a way that preserves its debugging info and graft
12519 it onto packages that depend on it. This is useful if @var{package}
12520 does not already provide debugging info as a @code{debug} output
12521 (@pxref{Installing Debugging Files}).
12523 For example, suppose you're experiencing a crash in Inkscape and would
12524 like to see what's up in GLib, a library deep down in Inkscape's
12525 dependency graph. GLib lacks a @code{debug} output, so debugging is
12526 tough. Fortunately, you rebuild GLib with debugging info and tack it on
12530 guix install inkscape --with-debug-info=glib
12533 Only GLib needs to be recompiled so this takes a reasonable amount of
12534 time. @xref{Installing Debugging Files}, for more info.
12537 Under the hood, this option works by passing the @samp{#:strip-binaries?
12538 #f} to the build system of the package of interest (@pxref{Build
12539 Systems}). Most build systems support that option but some do not. In
12540 that case, an error is raised.
12542 Likewise, if a C/C++ package is built without @code{-g} (which is rarely
12543 the case), debugging info will remain unavailable even when
12544 @code{#:strip-binaries?} is false.
12547 @cindex tool chain, changing the build tool chain of a package
12548 @item --with-c-toolchain=@var{package}=@var{toolchain}
12549 This option changes the compilation of @var{package} and everything that
12550 depends on it so that they get built with @var{toolchain} instead of the
12551 default GNU tool chain for C/C++.
12553 Consider this example:
12556 guix build octave-cli \
12557 --with-c-toolchain=fftw=gcc-toolchain@@10 \
12558 --with-c-toolchain=fftwf=gcc-toolchain@@10
12561 The command above builds a variant of the @code{fftw} and @code{fftwf}
12562 packages using version 10 of @code{gcc-toolchain} instead of the default
12563 tool chain, and then builds a variant of the GNU@tie{}Octave
12564 command-line interface using them. GNU@tie{}Octave itself is also built
12565 with @code{gcc-toolchain@@10}.
12567 This other example builds the Hardware Locality (@code{hwloc}) library
12568 and its dependents up to @code{intel-mpi-benchmarks} with the Clang C
12572 guix build --with-c-toolchain=hwloc=clang-toolchain \
12573 intel-mpi-benchmarks
12577 There can be application binary interface (ABI) incompatibilities among
12578 tool chains. This is particularly true of the C++ standard library and
12579 run-time support libraries such as that of OpenMP@. By rebuilding all
12580 dependents with the same tool chain, @option{--with-c-toolchain} minimizes
12581 the risks of incompatibility but cannot entirely eliminate them. Choose
12582 @var{package} wisely.
12585 @item --with-git-url=@var{package}=@var{url}
12586 @cindex Git, using the latest commit
12587 @cindex latest commit, building
12588 Build @var{package} from the latest commit of the @code{master} branch of the
12589 Git repository at @var{url}. Git sub-modules of the repository are fetched,
12592 For example, the following command builds the NumPy Python library against the
12593 latest commit of the master branch of Python itself:
12596 guix build python-numpy \
12597 --with-git-url=python=https://github.com/python/cpython
12600 This option can also be combined with @option{--with-branch} or
12601 @option{--with-commit} (see below).
12603 @cindex continuous integration
12604 Obviously, since it uses the latest commit of the given branch, the result of
12605 such a command varies over time. Nevertheless it is a convenient way to
12606 rebuild entire software stacks against the latest commit of one or more
12607 packages. This is particularly useful in the context of continuous
12610 Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed up
12611 consecutive accesses to the same repository. You may want to clean it up once
12612 in a while to save disk space.
12614 @item --with-branch=@var{package}=@var{branch}
12615 Build @var{package} from the latest commit of @var{branch}. If the
12616 @code{source} field of @var{package} is an origin with the @code{git-fetch}
12617 method (@pxref{origin Reference}) or a @code{git-checkout} object, the
12618 repository URL is taken from that @code{source}. Otherwise you have to use
12619 @option{--with-git-url} to specify the URL of the Git repository.
12621 For instance, the following command builds @code{guile-sqlite3} from the
12622 latest commit of its @code{master} branch, and then builds @code{guix} (which
12623 depends on it) and @code{cuirass} (which depends on @code{guix}) against this
12624 specific @code{guile-sqlite3} build:
12627 guix build --with-branch=guile-sqlite3=master cuirass
12630 @item --with-commit=@var{package}=@var{commit}
12631 This is similar to @option{--with-branch}, except that it builds from
12632 @var{commit} rather than the tip of a branch. @var{commit} must be a valid
12633 Git commit SHA1 identifier, a tag, or a @command{git describe} style
12634 identifier such as @code{1.0-3-gabc123}.
12636 @item --with-patch=@var{package}=@var{file}
12637 Add @var{file} to the list of patches applied to @var{package}, where
12638 @var{package} is a spec such as @code{python@@3.8} or @code{glibc}.
12639 @var{file} must contain a patch; it is applied with the flags specified
12640 in the @code{origin} of @var{package} (@pxref{origin Reference}), which
12641 by default includes @code{-p1} (@pxref{patch Directories,,, diffutils,
12642 Comparing and Merging Files}).
12644 As an example, the command below rebuilds Coreutils with the GNU C
12645 Library (glibc) patched with the given patch:
12648 guix build coreutils --with-patch=glibc=./glibc-frob.patch
12651 In this example, glibc itself as well as everything that leads to
12652 Coreutils in the dependency graph is rebuilt.
12654 @cindex upstream, latest version
12655 @item --with-latest=@var{package}
12656 So you like living on the bleeding edge? This option is for you! It
12657 replaces occurrences of @var{package} in the dependency graph with its
12658 latest upstream version, as reported by @command{guix refresh}
12659 (@pxref{Invoking guix refresh}).
12661 It does so by determining the latest upstream release of @var{package}
12662 (if possible), downloading it, and authenticating it @emph{if} it comes
12663 with an OpenPGP signature.
12665 As an example, the command below builds Guix against the latest version
12669 guix build guix --with-latest=guile-json
12672 There are limitations. First, in cases where the tool cannot or does
12673 not know how to authenticate source code, you are at risk of running
12674 malicious code; a warning is emitted in this case. Second, this option
12675 simply changes the source used in the existing package definitions,
12676 which is not always sufficient: there might be additional dependencies
12677 that need to be added, patches to apply, and more generally the quality
12678 assurance work that Guix developers normally do will be missing.
12680 You've been warned! In all the other cases, it's a snappy way to stay
12681 on top. We encourage you to submit patches updating the actual package
12682 definitions once you have successfully tested an upgrade
12683 (@pxref{Contributing}).
12685 @cindex test suite, skipping
12686 @item --without-tests=@var{package}
12687 Build @var{package} without running its tests. This can be useful in
12688 situations where you want to skip the lengthy test suite of a
12689 intermediate package, or if a package's test suite fails in a
12690 non-deterministic fashion. It should be used with care because running
12691 the test suite is a good way to ensure a package is working as intended.
12693 Turning off tests leads to a different store item. Consequently, when
12694 using this option, anything that depends on @var{package} must be
12695 rebuilt, as in this example:
12698 guix install --without-tests=python python-notebook
12701 The command above installs @code{python-notebook} on top of
12702 @code{python} built without running its test suite. To do so, it also
12703 rebuilds everything that depends on @code{python}, including
12704 @code{python-notebook} itself.
12706 Internally, @option{--without-tests} relies on changing the
12707 @code{#:tests?} option of a package's @code{check} phase (@pxref{Build
12708 Systems}). Note that some packages use a customized @code{check} phase
12709 that does not respect a @code{#:tests? #f} setting. Therefore,
12710 @option{--without-tests} has no effect on these packages.
12714 Wondering how to achieve the same effect using Scheme code, for example
12715 in your manifest, or how to write your own package transformation?
12716 @xref{Defining Package Variants}, for an overview of the programming
12717 interfaces available.
12719 @node Additional Build Options
12720 @subsection Additional Build Options
12722 The command-line options presented below are specific to @command{guix
12729 Build quietly, without displaying the build log; this is equivalent to
12730 @option{--verbosity=0}. Upon completion, the build log is kept in @file{/var}
12731 (or similar) and can always be retrieved using the @option{--log-file} option.
12733 @item --file=@var{file}
12734 @itemx -f @var{file}
12735 Build the package, derivation, or other file-like object that the code within
12736 @var{file} evaluates to (@pxref{G-Expressions, file-like objects}).
12738 As an example, @var{file} might contain a package definition like this
12739 (@pxref{Defining Packages}):
12742 @include package-hello.scm
12745 The @var{file} may also contain a JSON representation of one or more
12746 package definitions. Running @code{guix build -f} on @file{hello.json}
12747 with the following contents would result in building the packages
12748 @code{myhello} and @code{greeter}:
12751 @verbatiminclude package-hello.json
12754 @item --manifest=@var{manifest}
12755 @itemx -m @var{manifest}
12756 Build all packages listed in the given @var{manifest}
12757 (@pxref{profile-manifest, @option{--manifest}}).
12759 @item --expression=@var{expr}
12760 @itemx -e @var{expr}
12761 Build the package or derivation @var{expr} evaluates to.
12763 For example, @var{expr} may be @code{(@@ (gnu packages guile)
12764 guile-1.8)}, which unambiguously designates this specific variant of
12765 version 1.8 of Guile.
12767 Alternatively, @var{expr} may be a G-expression, in which case it is used
12768 as a build program passed to @code{gexp->derivation}
12769 (@pxref{G-Expressions}).
12771 Lastly, @var{expr} may refer to a zero-argument monadic procedure
12772 (@pxref{The Store Monad}). The procedure must return a derivation as a
12773 monadic value, which is then passed through @code{run-with-store}.
12777 Build the source derivations of the packages, rather than the packages
12780 For instance, @code{guix build -S gcc} returns something like
12781 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC
12784 The returned source tarball is the result of applying any patches and
12785 code snippets specified in the package @code{origin} (@pxref{Defining
12788 @cindex source, verification
12789 As with other derivations, the result of building a source derivation
12790 can be verified using the @option{--check} option (@pxref{build-check}).
12791 This is useful to validate that a (potentially already built or
12792 substituted, thus cached) package source matches against its declared
12795 Note that @command{guix build -S} compiles the sources only of the
12796 specified packages. They do not include the sources of statically
12797 linked dependencies and by themselves are insufficient for reproducing
12801 Fetch and return the source of @var{package-or-derivation} and all their
12802 dependencies, recursively. This is a handy way to obtain a local copy
12803 of all the source code needed to build @var{packages}, allowing you to
12804 eventually build them even without network access. It is an extension
12805 of the @option{--source} option and can accept one of the following
12806 optional argument values:
12810 This value causes the @option{--sources} option to behave in the same way
12811 as the @option{--source} option.
12814 Build the source derivations of all packages, including any source that
12815 might be listed as @code{inputs}. This is the default value.
12818 $ guix build --sources tzdata
12819 The following derivations will be built:
12820 /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
12821 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
12825 Build the source derivations of all packages, as well of all transitive
12826 inputs to the packages. This can be used e.g.@: to
12827 prefetch package source for later offline building.
12830 $ guix build --sources=transitive tzdata
12831 The following derivations will be built:
12832 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
12833 /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
12834 /gnu/store/@dots{}-grep-2.21.tar.xz.drv
12835 /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
12836 /gnu/store/@dots{}-make-4.1.tar.xz.drv
12837 /gnu/store/@dots{}-bash-4.3.tar.xz.drv
12843 @item --system=@var{system}
12844 @itemx -s @var{system}
12845 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of
12846 the system type of the build host. The @command{guix build} command allows
12847 you to repeat this option several times, in which case it builds for all the
12848 specified systems; other commands ignore extraneous @option{-s} options.
12851 The @option{--system} flag is for @emph{native} compilation and must not
12852 be confused with cross-compilation. See @option{--target} below for
12853 information on cross-compilation.
12856 An example use of this is on Linux-based systems, which can emulate
12857 different personalities. For instance, passing
12858 @option{--system=i686-linux} on an @code{x86_64-linux} system or
12859 @option{--system=armhf-linux} on an @code{aarch64-linux} system allows
12860 you to build packages in a complete 32-bit environment.
12863 Building for an @code{armhf-linux} system is unconditionally enabled on
12864 @code{aarch64-linux} machines, although certain aarch64 chipsets do not
12865 allow for this functionality, notably the ThunderX.
12868 Similarly, when transparent emulation with QEMU and @code{binfmt_misc}
12869 is enabled (@pxref{Virtualization Services,
12870 @code{qemu-binfmt-service-type}}), you can build for any system for
12871 which a QEMU @code{binfmt_misc} handler is installed.
12873 Builds for a system other than that of the machine you are using can
12874 also be offloaded to a remote machine of the right architecture.
12875 @xref{Daemon Offload Setup}, for more information on offloading.
12877 @item --target=@var{triplet}
12878 @cindex cross-compilation
12879 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
12880 as @code{"aarch64-linux-gnu"} (@pxref{Specifying Target Triplets, GNU
12881 configuration triplets,, autoconf, Autoconf}).
12883 @item --list-systems
12884 List all the supported systems, that can be passed as an argument to
12887 @item --list-targets
12888 List all the supported targets, that can be passed as an argument to
12891 @anchor{build-check}
12893 @cindex determinism, checking
12894 @cindex reproducibility, checking
12895 Rebuild @var{package-or-derivation}, which are already available in the
12896 store, and raise an error if the build results are not bit-for-bit
12899 This mechanism allows you to check whether previously installed
12900 substitutes are genuine (@pxref{Substitutes}), or whether the build result
12901 of a package is deterministic. @xref{Invoking guix challenge}, for more
12902 background information and tools.
12904 When used in conjunction with @option{--keep-failed}, the differing
12905 output is kept in the store, under @file{/gnu/store/@dots{}-check}.
12906 This makes it easy to look for differences between the two results.
12909 @cindex repairing store items
12910 @cindex corruption, recovering from
12911 Attempt to repair the specified store items, if they are corrupt, by
12912 re-downloading or rebuilding them.
12914 This operation is not atomic and thus restricted to @code{root}.
12916 @item --derivations
12918 Return the derivation paths, not the output paths, of the given
12921 @item --root=@var{file}
12922 @itemx -r @var{file}
12923 @cindex GC roots, adding
12924 @cindex garbage collector roots, adding
12925 Make @var{file} a symlink to the result, and register it as a garbage
12928 Consequently, the results of this @command{guix build} invocation are
12929 protected from garbage collection until @var{file} is removed. When
12930 that option is omitted, build results are eligible for garbage
12931 collection as soon as the build completes. @xref{Invoking guix gc}, for
12935 @cindex build logs, access
12936 Return the build log file names or URLs for the given
12937 @var{package-or-derivation}, or raise an error if build logs are
12940 This works regardless of how packages or derivations are specified. For
12941 instance, the following invocations are equivalent:
12944 guix build --log-file $(guix build -d guile)
12945 guix build --log-file $(guix build guile)
12946 guix build --log-file guile
12947 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
12950 If a log is unavailable locally, and unless @option{--no-substitutes} is
12951 passed, the command looks for a corresponding log on one of the
12952 substitute servers (as specified with @option{--substitute-urls}).
12954 So for instance, imagine you want to see the build log of GDB on
12955 @code{aarch64}, but you are actually on an @code{x86_64} machine:
12958 $ guix build --log-file gdb -s aarch64-linux
12959 https://@value{SUBSTITUTE-SERVER-1}/log/@dots{}-gdb-7.10
12962 You can freely access a huge library of build logs!
12965 @node Debugging Build Failures
12966 @subsection Debugging Build Failures
12968 @cindex build failures, debugging
12969 When defining a new package (@pxref{Defining Packages}), you will
12970 probably find yourself spending some time debugging and tweaking the
12971 build until it succeeds. To do that, you need to operate the build
12972 commands yourself in an environment as close as possible to the one the
12975 To that end, the first thing to do is to use the @option{--keep-failed}
12976 or @option{-K} option of @command{guix build}, which will keep the
12977 failed build tree in @file{/tmp} or whatever directory you specified as
12978 @env{TMPDIR} (@pxref{Common Build Options, @option{--keep-failed}}).
12980 From there on, you can @command{cd} to the failed build tree and source
12981 the @file{environment-variables} file, which contains all the
12982 environment variable definitions that were in place when the build
12983 failed. So let's say you're debugging a build failure in package
12984 @code{foo}; a typical session would look like this:
12987 $ guix build foo -K
12988 @dots{} @i{build fails}
12989 $ cd /tmp/guix-build-foo.drv-0
12990 $ source ./environment-variables
12994 Now, you can invoke commands as if you were the daemon (almost) and
12995 troubleshoot your build process.
12997 Sometimes it happens that, for example, a package's tests pass when you
12998 run them manually but they fail when the daemon runs them. This can
12999 happen because the daemon runs builds in containers where, unlike in our
13000 environment above, network access is missing, @file{/bin/sh} does not
13001 exist, etc. (@pxref{Build Environment Setup}).
13003 In such cases, you may need to run inspect the build process from within
13004 a container similar to the one the build daemon creates:
13007 $ guix build -K foo
13009 $ cd /tmp/guix-build-foo.drv-0
13010 $ guix shell --no-grafts -C -D foo strace gdb
13011 [env]# source ./environment-variables
13015 Here, @command{guix shell -C} creates a container and spawns a new
13016 shell in it (@pxref{Invoking guix shell}). The @command{strace gdb}
13017 part adds the @command{strace} and @command{gdb} commands to
13018 the container, which you may find handy while debugging. The
13019 @option{--no-grafts} option makes sure we get the exact same
13020 environment, with ungrafted packages (@pxref{Security Updates}, for more
13023 To get closer to a container like that used by the build daemon, we can
13024 remove @file{/bin/sh}:
13030 (Don't worry, this is harmless: this is all happening in the throw-away
13031 container created by @command{guix shell}.)
13033 The @command{strace} command is probably not in the search path, but we
13037 [env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
13040 In this way, not only you will have reproduced the environment variables
13041 the daemon uses, you will also be running the build process in a container
13042 similar to the one the daemon uses.
13045 @node Invoking guix edit
13046 @section Invoking @command{guix edit}
13048 @cindex @command{guix edit}
13049 @cindex package definition, editing
13050 So many packages, so many source files! The @command{guix edit} command
13051 facilitates the life of users and packagers by pointing their editor at
13052 the source file containing the definition of the specified packages.
13056 guix edit gcc@@4.9 vim
13060 launches the program specified in the @env{VISUAL} or in the
13061 @env{EDITOR} environment variable to view the recipe of GCC@tie{}4.9.3
13064 If you are using a Guix Git checkout (@pxref{Building from Git}), or
13065 have created your own packages on @env{GUIX_PACKAGE_PATH}
13066 (@pxref{Package Modules}), you will be able to edit the package
13067 recipes. In other cases, you will be able to examine the read-only recipes
13068 for packages currently in the store.
13070 Instead of @env{GUIX_PACKAGE_PATH}, the command-line option
13071 @option{--load-path=@var{directory}} (or in short @option{-L
13072 @var{directory}}) allows you to add @var{directory} to the front of the
13073 package module search path and so make your own packages visible.
13075 @node Invoking guix download
13076 @section Invoking @command{guix download}
13078 @cindex @command{guix download}
13079 @cindex downloading package sources
13080 When writing a package definition, developers typically need to download
13081 a source tarball, compute its SHA256 hash, and write that
13082 hash in the package definition (@pxref{Defining Packages}). The
13083 @command{guix download} tool helps with this task: it downloads a file
13084 from the given URI, adds it to the store, and prints both its file name
13085 in the store and its SHA256 hash.
13087 The fact that the downloaded file is added to the store saves bandwidth:
13088 when the developer eventually tries to build the newly defined package
13089 with @command{guix build}, the source tarball will not have to be
13090 downloaded again because it is already in the store. It is also a
13091 convenient way to temporarily stash files, which may be deleted
13092 eventually (@pxref{Invoking guix gc}).
13094 The @command{guix download} command supports the same URIs as used in
13095 package definitions. In particular, it supports @code{mirror://} URIs.
13096 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the
13097 Guile bindings for GnuTLS are available in the user's environment; when
13098 they are not available, an error is raised. @xref{Guile Preparations,
13099 how to install the GnuTLS bindings for Guile,, gnutls-guile,
13100 GnuTLS-Guile}, for more information.
13102 @command{guix download} verifies HTTPS server certificates by loading
13103 the certificates of X.509 authorities from the directory pointed to by
13104 the @env{SSL_CERT_DIR} environment variable (@pxref{X.509
13105 Certificates}), unless @option{--no-check-certificate} is used.
13107 The following options are available:
13110 @item --hash=@var{algorithm}
13111 @itemx -H @var{algorithm}
13112 Compute a hash using the specified @var{algorithm}. @xref{Invoking guix
13113 hash}, for more information.
13115 @item --format=@var{fmt}
13116 @itemx -f @var{fmt}
13117 Write the hash in the format specified by @var{fmt}. For more
13118 information on the valid values for @var{fmt}, @pxref{Invoking guix hash}.
13120 @item --no-check-certificate
13121 Do not validate the X.509 certificates of HTTPS servers.
13123 When using this option, you have @emph{absolutely no guarantee} that you
13124 are communicating with the authentic server responsible for the given
13125 URL, which makes you vulnerable to ``man-in-the-middle'' attacks.
13127 @item --output=@var{file}
13128 @itemx -o @var{file}
13129 Save the downloaded file to @var{file} instead of adding it to the
13133 @node Invoking guix hash
13134 @section Invoking @command{guix hash}
13136 @cindex @command{guix hash}
13137 The @command{guix hash} command computes the hash of a file.
13138 It is primarily a convenience tool for anyone contributing to the
13139 distribution: it computes the cryptographic hash of one or more files, which can be
13140 used in the definition of a package (@pxref{Defining Packages}).
13142 The general syntax is:
13145 guix hash @var{option} @var{file} ...
13148 When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
13149 hash of data read from standard input. @command{guix hash} has the
13154 @item --hash=@var{algorithm}
13155 @itemx -H @var{algorithm}
13156 Compute a hash using the specified @var{algorithm}, @code{sha256} by
13159 @var{algorithm} must be the name of a cryptographic hash algorithm
13160 supported by Libgcrypt @i{via} Guile-Gcrypt---e.g., @code{sha512} or
13161 @code{sha3-256} (@pxref{Hash Functions,,, guile-gcrypt, Guile-Gcrypt
13162 Reference Manual}).
13164 @item --format=@var{fmt}
13165 @itemx -f @var{fmt}
13166 Write the hash in the format specified by @var{fmt}.
13168 Supported formats: @code{base64}, @code{nix-base32}, @code{base32}, @code{base16}
13169 (@code{hex} and @code{hexadecimal} can be used as well).
13171 If the @option{--format} option is not specified, @command{guix hash}
13172 will output the hash in @code{nix-base32}. This representation is used
13173 in the definitions of packages.
13177 The @option{--recursive} option is deprecated in favor of
13178 @option{--serializer=nar} (see below); @option{-r} remains accepted as a
13179 convenient shorthand.
13181 @item --serializer=@var{type}
13182 @itemx -S @var{type}
13183 Compute the hash on @var{file} using @var{type} serialization.
13185 @var{type} may be one of the following:
13189 This is the default: it computes the hash of a file's contents.
13192 Compute the hash of a ``normalized archive'' (or ``nar'') containing
13193 @var{file}, including its children if it is a directory. Some of the
13194 metadata of @var{file} is part of the archive; for instance, when
13195 @var{file} is a regular file, the hash is different depending on whether
13196 @var{file} is executable or not. Metadata such as time stamps have no
13197 impact on the hash (@pxref{Invoking guix archive}, for more info on the
13199 @c FIXME: Replace xref above with xref to an ``Archive'' section when
13203 Compute the hash of the file or directory as a Git ``tree'', following
13204 the same method as the Git version control system.
13207 @item --exclude-vcs
13209 When combined with @option{--recursive}, exclude version control system
13210 directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.).
13213 As an example, here is how you would compute the hash of a Git checkout,
13214 which is useful when using the @code{git-fetch} method (@pxref{origin
13218 $ git clone http://example.org/foo.git
13220 $ guix hash -x --serializer=nar .
13224 @node Invoking guix import
13225 @section Invoking @command{guix import}
13227 @cindex importing packages
13228 @cindex package import
13229 @cindex package conversion
13230 @cindex Invoking @command{guix import}
13231 The @command{guix import} command is useful for people who would like to
13232 add a package to the distribution with as little work as
13233 possible---a legitimate demand. The command knows of a few
13234 repositories from which it can ``import'' package metadata. The result
13235 is a package definition, or a template thereof, in the format we know
13236 (@pxref{Defining Packages}).
13238 The general syntax is:
13241 guix import @var{importer} @var{options}@dots{}
13244 @var{importer} specifies the source from which to import package
13245 metadata, and @var{options} specifies a package identifier and other
13246 options specific to @var{importer}.
13248 Some of the importers rely on the ability to run the @command{gpgv} command.
13249 For these, GnuPG must be installed and in @code{$PATH}; run @code{guix install
13252 Currently, the available ``importers'' are:
13256 Import metadata for the given GNU package. This provides a template
13257 for the latest version of that GNU package, including the hash of its
13258 source tarball, and its canonical synopsis and description.
13260 Additional information such as the package dependencies and its
13261 license needs to be figured out manually.
13263 For example, the following command returns a package definition for
13267 guix import gnu hello
13270 Specific command-line options are:
13273 @item --key-download=@var{policy}
13274 As for @command{guix refresh}, specify the policy to handle missing
13275 OpenPGP keys when verifying the package signature. @xref{Invoking guix
13276 refresh, @option{--key-download}}.
13281 Import metadata from the @uref{https://pypi.python.org/, Python Package
13282 Index}. Information is taken from the JSON-formatted description
13283 available at @code{pypi.python.org} and usually includes all the relevant
13284 information, including package dependencies. For maximum efficiency, it
13285 is recommended to install the @command{unzip} utility, so that the
13286 importer can unzip Python wheels and gather data from them.
13288 The command below imports metadata for the latest version of the
13289 @code{itsdangerous} Python package:
13292 guix import pypi itsdangerous
13295 You can also ask for a specific version:
13298 guix import pypi itsdangerous@@1.1.0
13304 Traverse the dependency graph of the given upstream package recursively
13305 and generate package expressions for all those packages that are not yet
13311 Import metadata from @uref{https://rubygems.org/, RubyGems}. Information
13312 is taken from the JSON-formatted description available at
13313 @code{rubygems.org} and includes most relevant information, including
13314 runtime dependencies. There are some caveats, however. The metadata
13315 doesn't distinguish between synopses and descriptions, so the same string
13316 is used for both fields. Additionally, the details of non-Ruby
13317 dependencies required to build native extensions is unavailable and left
13318 as an exercise to the packager.
13320 The command below imports metadata for the @code{rails} Ruby package:
13323 guix import gem rails
13326 You can also ask for a specific version:
13329 guix import gem rails@@7.0.4
13335 Traverse the dependency graph of the given upstream package recursively
13336 and generate package expressions for all those packages that are not yet
13343 Import metadata from @uref{https://content.minetest.net, ContentDB}.
13344 Information is taken from the JSON-formatted metadata provided through
13345 @uref{https://content.minetest.net/help/api/, ContentDB's API} and
13346 includes most relevant information, including dependencies. There are
13347 some caveats, however. The license information is often incomplete.
13348 The commit hash is sometimes missing. The descriptions are in the
13349 Markdown format, but Guix uses Texinfo instead. Texture packs and
13350 subgames are unsupported.
13352 The command below imports metadata for the Mesecons mod by Jeija:
13355 guix import minetest Jeija/mesecons
13358 The author name can also be left out:
13361 guix import minetest mesecons
13367 Traverse the dependency graph of the given upstream package recursively
13368 and generate package expressions for all those packages that are not yet
13374 Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}.
13375 Information is taken from the JSON-formatted metadata provided through
13376 @uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most
13377 relevant information, such as module dependencies. License information
13378 should be checked closely. If Perl is available in the store, then the
13379 @code{corelist} utility will be used to filter core modules out of the
13380 list of dependencies.
13382 The command command below imports metadata for the Acme::Boolean Perl
13386 guix import cpan Acme::Boolean
13391 @cindex Bioconductor
13392 Import metadata from @uref{https://cran.r-project.org/, CRAN}, the
13393 central repository for the @uref{https://r-project.org, GNU@tie{}R
13394 statistical and graphical environment}.
13396 Information is extracted from the @file{DESCRIPTION} file of the package.
13398 The command command below imports metadata for the Cairo R package:
13401 guix import cran Cairo
13404 You can also ask for a specific version:
13407 guix import cran rasterVis@@0.50.3
13410 When @option{--recursive} is added, the importer will traverse the
13411 dependency graph of the given upstream package recursively and generate
13412 package expressions for all those packages that are not yet in Guix.
13414 When @option{--style=specification} is added, the importer will generate
13415 package definitions whose inputs are package specifications instead of
13416 references to package variables. This is useful when generated package
13417 definitions are to be appended to existing user modules, as the list of
13418 used package modules need not be changed. The default is
13419 @option{--style=variable}.
13421 When @option{--archive=bioconductor} is added, metadata is imported from
13422 @uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
13423 packages for the analysis and comprehension of high-throughput
13424 genomic data in bioinformatics.
13426 Information is extracted from the @file{DESCRIPTION} file contained in the
13429 The command below imports metadata for the GenomicRanges R package:
13432 guix import cran --archive=bioconductor GenomicRanges
13435 Finally, you can also import R packages that have not yet been published on
13436 CRAN or Bioconductor as long as they are in a git repository. Use
13437 @option{--archive=git} followed by the URL of the git repository:
13440 guix import cran --archive=git https://github.com/immunogenomics/harmony
13446 Import TeX package information from the TeX Live package database for
13447 TeX packages that are part of the @uref{https://www.tug.org/texlive/,
13448 TeX Live distribution}.
13450 Information about the package is obtained from the TeX Live package
13451 database, a plain text file that is included in the @code{texlive-bin}
13452 package. The source code is downloaded from possibly multiple locations
13453 in the SVN repository of the Tex Live project.
13455 The command command below imports metadata for the @code{fontspec}
13459 guix import texlive fontspec
13463 @cindex JSON, import
13464 Import package metadata from a local JSON file. Consider the following
13465 example package definition in JSON format:
13471 "source": "mirror://gnu/hello/hello-2.10.tar.gz",
13472 "build-system": "gnu",
13473 "home-page": "https://www.gnu.org/software/hello/",
13474 "synopsis": "Hello, GNU world: An example GNU package",
13475 "description": "GNU Hello prints a greeting.",
13476 "license": "GPL-3.0+",
13477 "native-inputs": ["gettext"]
13481 The field names are the same as for the @code{<package>} record
13482 (@xref{Defining Packages}). References to other packages are provided
13483 as JSON lists of quoted package specification strings such as
13484 @code{guile} or @code{guile@@2.0}.
13486 The importer also supports a more explicit source definition using the
13487 common fields for @code{<origin>} records:
13493 "method": "url-fetch",
13494 "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
13496 "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
13503 The command below reads metadata from the JSON file @code{hello.json}
13504 and outputs a package expression:
13507 guix import json hello.json
13512 Import metadata from the Haskell community's central package archive
13513 @uref{https://hackage.haskell.org/, Hackage}. Information is taken from
13514 Cabal files and includes all the relevant information, including package
13517 Specific command-line options are:
13522 Read a Cabal file from standard input.
13523 @item --no-test-dependencies
13525 Do not include dependencies required only by the test suites.
13526 @item --cabal-environment=@var{alist}
13527 @itemx -e @var{alist}
13528 @var{alist} is a Scheme alist defining the environment in which the
13529 Cabal conditionals are evaluated. The accepted keys are: @code{os},
13530 @code{arch}, @code{impl} and a string representing the name of a flag.
13531 The value associated with a flag has to be either the symbol
13532 @code{true} or @code{false}. The value associated with other keys
13533 has to conform to the Cabal file format definition. The default value
13534 associated with the keys @code{os}, @code{arch} and @code{impl} is
13535 @samp{linux}, @samp{x86_64} and @samp{ghc}, respectively.
13538 Traverse the dependency graph of the given upstream package recursively
13539 and generate package expressions for all those packages that are not yet
13543 The command below imports metadata for the latest version of the
13544 HTTP Haskell package without including test dependencies and
13545 specifying the value of the flag @samp{network-uri} as @code{false}:
13548 guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
13551 A specific package version may optionally be specified by following the
13552 package name by an at-sign and a version number as in the following example:
13555 guix import hackage mtl@@2.1.3.1
13560 The @code{stackage} importer is a wrapper around the @code{hackage} one.
13561 It takes a package name, looks up the package version included in a
13562 long-term support (LTS) @uref{https://www.stackage.org, Stackage}
13563 release and uses the @code{hackage} importer to retrieve its metadata.
13564 Note that it is up to you to select an LTS release compatible with the
13565 GHC compiler used by Guix.
13567 Specific command-line options are:
13570 @item --no-test-dependencies
13572 Do not include dependencies required only by the test suites.
13573 @item --lts-version=@var{version}
13574 @itemx -l @var{version}
13575 @var{version} is the desired LTS release version. If omitted the latest
13579 Traverse the dependency graph of the given upstream package recursively
13580 and generate package expressions for all those packages that are not yet
13584 The command below imports metadata for the HTTP Haskell package
13585 included in the LTS Stackage release version 7.18:
13588 guix import stackage --lts-version=7.18 HTTP
13593 Import metadata from an Emacs Lisp Package Archive (ELPA) package
13594 repository (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
13596 Specific command-line options are:
13599 @item --archive=@var{repo}
13600 @itemx -a @var{repo}
13601 @var{repo} identifies the archive repository from which to retrieve the
13602 information. Currently the supported repositories and their identifiers
13606 @uref{https://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
13607 identifier. This is the default.
13609 Packages from @code{elpa.gnu.org} are signed with one of the keys
13610 contained in the GnuPG keyring at
13611 @file{share/emacs/25.1/etc/package-keyring.gpg} (or similar) in the
13612 @code{emacs} package (@pxref{Package Installation, ELPA package
13613 signatures,, emacs, The GNU Emacs Manual}).
13616 @uref{https://elpa.nongnu.org/nongnu/, NonGNU}, selected by the
13617 @code{nongnu} identifier.
13620 @uref{https://stable.melpa.org/packages, MELPA-Stable}, selected by the
13621 @code{melpa-stable} identifier.
13624 @uref{https://melpa.org/packages, MELPA}, selected by the @code{melpa}
13630 Traverse the dependency graph of the given upstream package recursively
13631 and generate package expressions for all those packages that are not yet
13637 Import metadata from the crates.io Rust package repository
13638 @uref{https://crates.io, crates.io}, as in this example:
13641 guix import crate blake2-rfc
13644 The crate importer also allows you to specify a version string:
13647 guix import crate constant-time-eq@@0.1.0
13650 Additional options include:
13655 Traverse the dependency graph of the given upstream package recursively
13656 and generate package expressions for all those packages that are not yet
13662 Import metadata from the Elm package repository
13663 @uref{https://package.elm-lang.org, package.elm-lang.org}, as in this example:
13666 guix import elm elm-explorations/webgl
13669 The Elm importer also allows you to specify a version string:
13672 guix import elm elm-explorations/webgl@@1.1.3
13675 Additional options include:
13680 Traverse the dependency graph of the given upstream package recursively
13681 and generate package expressions for all those packages that are not yet
13688 Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
13689 repository used by the OCaml community.
13691 Additional options include:
13696 Traverse the dependency graph of the given upstream package recursively
13697 and generate package expressions for all those packages that are not yet
13700 By default, packages are searched in the official OPAM repository. This
13701 option, which can be used more than once, lets you add other repositories
13702 which will be searched for packages. It accepts as valid arguments:
13705 @item the name of a known repository - can be one of @code{opam},
13706 @code{coq} (equivalent to @code{coq-released}),
13707 @code{coq-core-dev}, @code{coq-extra-dev} or @code{grew}.
13708 @item the URL of a repository as expected by the
13709 @code{opam repository add} command (for instance, the URL equivalent
13710 of the above @code{opam} name would be
13711 @uref{https://opam.ocaml.org}).
13712 @item the path to a local copy of a repository (a directory containing a
13713 @file{packages/} sub-directory).
13716 Repositories are assumed to be passed to this option by order of
13717 preference. The additional repositories will not replace the default
13718 @code{opam} repository, which is always kept as a fallback.
13720 Also, please note that versions are not compared across repositories.
13721 The first repository (from left to right) that has at least one version
13722 of a given package will prevail over any others, and the version
13723 imported will be the latest one found @emph{in this repository only}.
13729 Import metadata for a Go module using
13730 @uref{https://proxy.golang.org, proxy.golang.org}.
13733 guix import go gopkg.in/yaml.v2
13736 It is possible to use a package specification with a @code{@@VERSION}
13737 suffix to import a specific version.
13739 Additional options include:
13744 Traverse the dependency graph of the given upstream package recursively
13745 and generate package expressions for all those packages that are not yet
13747 @item --pin-versions
13748 When using this option, the importer preserves the exact versions of the
13749 Go modules dependencies instead of using their latest available
13750 versions. This can be useful when attempting to import packages that
13751 recursively depend on former versions of themselves to build. When
13752 using this mode, the symbol of the package is made by appending the
13753 version to its name, so that multiple versions of the same package can
13759 Import metadata for @uref{https://wiki.call-cc.org/eggs, CHICKEN eggs}.
13760 The information is taken from @file{PACKAGE.egg} files found in the
13761 @uref{git://code.call-cc.org/eggs-5-all, eggs-5-all} Git
13762 repository. However, it does not provide all the information that we
13763 need, there is no ``description'' field, and the licenses used are not
13764 always precise (BSD is often used instead of BSD-N).
13767 guix import egg sourcehut
13770 You can also ask for a specific version:
13773 guix import egg arrays@@1.0
13776 Additional options include:
13780 Traverse the dependency graph of the given upstream package recursively
13781 and generate package expressions for all those packages that are not yet
13787 Import metadata from the hex.pm Erlang and Elixir package repository
13788 @uref{https://hex.pm, hex.pm}, as in this example:
13791 guix import hexpm stun
13794 The importer tries to determine the build system used by the package.
13796 The hexpm importer also allows you to specify a version string:
13799 guix import hexpm cf@@0.3.0
13802 Additional options include:
13807 Traverse the dependency graph of the given upstream package recursively
13808 and generate package expressions for all those packages that are not yet
13813 The structure of the @command{guix import} code is modular. It would be
13814 useful to have more importers for other package formats, and your help
13815 is welcome here (@pxref{Contributing}).
13817 @node Invoking guix refresh
13818 @section Invoking @command{guix refresh}
13820 @cindex @command {guix refresh}
13821 The primary audience of the @command{guix refresh} command is packagers.
13822 As a user, you may be interested in the @option{--with-latest} option,
13823 which can bring you package update superpowers built upon @command{guix
13824 refresh} (@pxref{Package Transformation Options,
13825 @option{--with-latest}}). By default, @command{guix refresh} reports
13826 any packages provided by the distribution that are outdated compared to
13827 the latest upstream version, like this:
13831 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
13832 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
13835 Alternatively, one can specify packages to consider, in which case a
13836 warning is emitted for packages that lack an updater:
13839 $ guix refresh coreutils guile guile-ssh
13840 gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
13841 gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
13844 @command{guix refresh} browses the upstream repository of each package and determines
13845 the highest version number of the releases therein. The command
13846 knows how to update specific types of packages: GNU packages, ELPA
13847 packages, etc.---see the documentation for @option{--type} below. There
13848 are many packages, though, for which it lacks a method to determine
13849 whether a new upstream release is available. However, the mechanism is
13850 extensible, so feel free to get in touch with us to add a new method!
13855 Consider the packages specified, and all the packages upon which they depend.
13858 $ guix refresh --recursive coreutils
13859 gnu/packages/acl.scm:40:13: acl would be upgraded from 2.2.53 to 2.3.1
13860 gnu/packages/m4.scm:30:12: 1.4.18 is already the latest version of m4
13861 gnu/packages/xml.scm:68:2: warning: no updater for expat
13862 gnu/packages/multiprecision.scm:40:12: 6.1.2 is already the latest version of gmp
13868 Sometimes the upstream name differs from the package name used in Guix,
13869 and @command{guix refresh} needs a little help. Most updaters honor the
13870 @code{upstream-name} property in package definitions, which can be used
13874 (define-public network-manager
13876 (name "network-manager")
13878 (properties '((upstream-name . "NetworkManager")))))
13881 When passed @option{--update}, it modifies distribution source files to
13882 update the version numbers and source tarball hashes of those package
13883 recipes (@pxref{Defining Packages}). This is achieved by downloading
13884 each package's latest source tarball and its associated OpenPGP
13885 signature, authenticating the downloaded tarball against its signature
13886 using @command{gpgv}, and finally computing its hash---note that GnuPG must be
13887 installed and in @code{$PATH}; run @code{guix install gnupg} if needed.
13890 key used to sign the tarball is missing from the user's keyring, an
13891 attempt is made to automatically retrieve it from a public key server;
13892 when this is successful, the key is added to the user's keyring; otherwise,
13893 @command{guix refresh} reports an error.
13895 The following options are supported:
13899 @item --expression=@var{expr}
13900 @itemx -e @var{expr}
13901 Consider the package @var{expr} evaluates to.
13903 This is useful to precisely refer to a package, as in this example:
13906 guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
13909 This command lists the dependents of the ``final'' libc (essentially all
13914 Update distribution source files (package recipes) in place. This is
13915 usually run from a checkout of the Guix source tree (@pxref{Running
13916 Guix Before It Is Installed}):
13919 $ ./pre-inst-env guix refresh -s non-core -u
13922 @xref{Defining Packages}, for more information on package definitions.
13924 @item --select=[@var{subset}]
13925 @itemx -s @var{subset}
13926 Select all the packages in @var{subset}, one of @code{core} or
13929 The @code{core} subset refers to all the packages at the core of the
13930 distribution---i.e., packages that are used to build ``everything
13931 else''. This includes GCC, libc, Binutils, Bash, etc. Usually,
13932 changing one of these packages in the distribution entails a rebuild of
13933 all the others. Thus, such updates are an inconvenience to users in
13934 terms of build time or bandwidth used to achieve the upgrade.
13936 The @code{non-core} subset refers to the remaining packages. It is
13937 typically useful in cases where an update of the core packages would be
13940 @item --manifest=@var{file}
13941 @itemx -m @var{file}
13942 Select all the packages from the manifest in @var{file}. This is useful to
13943 check if any packages of the user manifest can be updated.
13945 @item --type=@var{updater}
13946 @itemx -t @var{updater}
13947 Select only packages handled by @var{updater} (may be a comma-separated
13948 list of updaters). Currently, @var{updater} may be one of:
13952 the updater for GNU packages;
13954 the updater for packages hosted at @uref{https://savannah.gnu.org, Savannah};
13956 the updater for packages hosted at @uref{https://sourceforge.net, SourceForge};
13958 the updater for GNOME packages;
13960 the updater for KDE packages;
13962 the updater for X.org packages;
13964 the updater for packages hosted on kernel.org;
13966 the updater for @uref{https://wiki.call-cc.org/eggs/, Egg} packages;
13968 the updater for @uref{https://elpa.gnu.org/, ELPA} packages;
13970 the updater for @uref{https://cran.r-project.org/, CRAN} packages;
13972 the updater for @uref{https://www.bioconductor.org/, Bioconductor} R packages;
13974 the updater for @uref{https://www.cpan.org/, CPAN} packages;
13976 the updater for @uref{https://pypi.python.org, PyPI} packages.
13978 the updater for @uref{https://rubygems.org, RubyGems} packages.
13980 the updater for @uref{https://github.com, GitHub} packages.
13982 the updater for @uref{https://hackage.haskell.org, Hackage} packages.
13984 the updater for @uref{https://www.stackage.org, Stackage} packages.
13986 the updater for @uref{https://crates.io, Crates} packages.
13988 the updater for @uref{https://launchpad.net, Launchpad} packages.
13990 a generic updater that crawls the HTML page where the source tarball of
13991 the package is hosted, when applicable.
13994 a generic updater for packages hosted on Git repositories. It tries to
13995 be smart about parsing Git tag names, but if it is not able to parse the
13996 tag name and compare tags correctly, users can define the following
13997 properties for a package.
14000 @item @code{release-tag-prefix}: a regular expression for matching a prefix of
14003 @item @code{release-tag-suffix}: a regular expression for matching a suffix of
14006 @item @code{release-tag-version-delimiter}: a string used as the delimiter in
14007 the tag name for separating the numbers of the version.
14009 @item @code{accept-pre-releases}: by default, the updater will ignore
14010 pre-releases; to make it also look for pre-releases, set the this
14011 property to @code{#t}.
14020 '((release-tag-prefix . "^release0-")
14021 (release-tag-suffix . "[a-z]?$")
14022 (release-tag-version-delimiter . ":"))))
14028 For instance, the following command only checks for updates of Emacs
14029 packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
14032 $ guix refresh --type=elpa,cran
14033 gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
14034 gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
14037 @item --list-updaters
14038 List available updaters and exit (see @option{--type} above).
14040 For each updater, display the fraction of packages it covers; at the
14041 end, display the fraction of packages covered by all these updaters.
14044 In addition, @command{guix refresh} can be passed one or more package
14045 names, as in this example:
14048 $ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
14052 The command above specifically updates the @code{emacs} and
14053 @code{idutils} packages. The @option{--select} option would have no
14054 effect in this case. You might also want to update definitions that
14055 correspond to the packages installed in your profile:
14058 $ ./pre-inst-env guix refresh -u \
14059 $(guix package --list-installed | cut -f1)
14062 When considering whether to upgrade a package, it is sometimes
14063 convenient to know which packages would be affected by the upgrade and
14064 should be checked for compatibility. For this the following option may
14065 be used when passing @command{guix refresh} one or more package names:
14069 @item --list-dependent
14071 List top-level dependent packages that would need to be rebuilt as a
14072 result of upgrading one or more packages.
14074 @xref{Invoking guix graph, the @code{reverse-package} type of
14075 @command{guix graph}}, for information on how to visualize the list of
14076 dependents of a package.
14080 Be aware that the @option{--list-dependent} option only
14081 @emph{approximates} the rebuilds that would be required as a result of
14082 an upgrade. More rebuilds might be required under some circumstances.
14085 $ guix refresh --list-dependent flex
14086 Building the following 120 packages would ensure 213 dependent packages are rebuilt:
14087 hop@@2.4.0 emacs-geiser@@0.13 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
14090 The command above lists a set of packages that could be built to check
14091 for compatibility with an upgraded @code{flex} package.
14095 @item --list-transitive
14096 List all the packages which one or more packages depend upon.
14099 $ guix refresh --list-transitive flex
14100 flex@@2.6.4 depends on the following 25 packages: perl@@5.28.0 help2man@@1.47.6
14101 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{}
14106 The command above lists a set of packages which, when changed, would cause
14107 @code{flex} to be rebuilt.
14109 The following options can be used to customize GnuPG operation:
14113 @item --gpg=@var{command}
14114 Use @var{command} as the GnuPG 2.x command. @var{command} is searched
14115 for in @code{$PATH}.
14117 @item --keyring=@var{file}
14118 Use @var{file} as the keyring for upstream keys. @var{file} must be in the
14119 @dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx}
14120 and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
14121 (@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, for
14122 information on a tool to manipulate keybox files).
14124 When this option is omitted, @command{guix refresh} uses
14125 @file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
14126 signing keys. OpenPGP signatures are checked against keys from this keyring;
14127 missing keys are downloaded to this keyring as well (see
14128 @option{--key-download} below).
14130 You can export keys from your default GPG keyring into a keybox file using
14131 commands like this one:
14134 gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
14137 Likewise, you can fetch keys to a specific keybox file like this:
14140 gpg --no-default-keyring --keyring mykeyring.kbx \
14141 --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
14144 @xref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
14145 Privacy Guard}, for more information on GPG's @option{--keyring} option.
14147 @item --key-download=@var{policy}
14148 Handle missing OpenPGP keys according to @var{policy}, which may be one
14153 Always download missing OpenPGP keys from the key server, and add them
14154 to the user's GnuPG keyring.
14157 Never try to download missing OpenPGP keys. Instead just bail out.
14160 When a package signed with an unknown OpenPGP key is encountered, ask
14161 the user whether to download it or not. This is the default behavior.
14164 @item --key-server=@var{host}
14165 Use @var{host} as the OpenPGP key server when importing a public key.
14167 @item --load-path=@var{directory}
14168 @itemx -L @var{directory}
14169 Add @var{directory} to the front of the package module search path
14170 (@pxref{Package Modules}).
14172 This allows users to define their own packages and make them visible to
14173 the command-line tools.
14177 The @code{github} updater uses the
14178 @uref{https://developer.github.com/v3/, GitHub API} to query for new
14179 releases. When used repeatedly e.g.@: when refreshing all packages,
14180 GitHub will eventually refuse to answer any further API requests. By
14181 default 60 API requests per hour are allowed, and a full refresh on all
14182 GitHub packages in Guix requires more than this. Authentication with
14183 GitHub through the use of an API token alleviates these limits. To use
14184 an API token, set the environment variable @env{GUIX_GITHUB_TOKEN} to a
14185 token procured from @uref{https://github.com/settings/tokens} or
14189 @node Invoking guix style
14190 @section Invoking @command{guix style}
14192 @cindex @command{guix style}
14193 @cindex styling rules
14194 @cindex lint, code style
14195 @cindex format, code style
14196 @cindex format conventions
14197 The @command{guix style} command helps users and packagers alike style
14198 their package definitions and configuration files according to the
14199 latest fashionable trends. It can either reformat whole files, with the
14200 @option{--whole-file} option, or apply specific @dfn{styling rules} to
14201 individual package definitions. The command currently provides the
14202 following styling rules:
14206 formatting package definitions according to the project's conventions
14207 (@pxref{Formatting Code});
14210 rewriting package inputs to the ``new style'', as explained below.
14213 The way package inputs are written is going through a transition
14214 (@pxref{package Reference}, for more on package inputs). Until version
14215 1.3.0, package inputs were written using the ``old style'', where each
14216 input was given an explicit label, most of the time the package name:
14221 ;; The "old style" (deprecated).
14222 (inputs `(("libunistring" ,libunistring)
14223 ("libffi" ,libffi))))
14226 Today, the old style is deprecated and the preferred style looks like
14232 ;; The "new style".
14233 (inputs (list libunistring libffi)))
14236 Likewise, uses of @code{alist-delete} and friends to manipulate inputs
14237 is now deprecated in favor of @code{modify-inputs} (@pxref{Defining
14238 Package Variants}, for more info on @code{modify-inputs}).
14240 In the vast majority of cases, this is a purely mechanical change on the
14241 surface syntax that does not even incur a package rebuild. Running
14242 @command{guix style -S inputs} can do that for you, whether you're working on
14243 packages in Guix proper or in an external channel.
14245 The general syntax is:
14248 guix style [@var{options}] @var{package}@dots{}
14251 This causes @command{guix style} to analyze and rewrite the definition
14252 of @var{package}@dots{} or, when @var{package} is omitted, of @emph{all}
14253 the packages. The @option{--styling} or @option{-S} option allows you
14254 to select the style rule, the default rule being @code{format}---see
14257 To reformat entire source files, the syntax is:
14260 guix style --whole-file @var{file}@dots{}
14263 The available options are listed below.
14268 Show source file locations that would be edited but do not modify them.
14272 Reformat the given files in their entirety. In that case, subsequent
14273 arguments are interpreted as file names (rather than package names), and
14274 the @option{--styling} option has no effect.
14276 As an example, here is how you might reformat your operating system
14277 configuration (you need write permissions for the file):
14280 guix style -f /etc/config.scm
14283 @item --styling=@var{rule}
14284 @itemx -S @var{rule}
14285 Apply @var{rule}, one of the following styling rules:
14289 Format the given package definition(s)---this is the default styling
14290 rule. For example, a packager running Guix on a checkout
14291 (@pxref{Running Guix Before It Is Installed}) might want to reformat the
14292 definition of the Coreutils package like so:
14295 ./pre-inst-env guix style coreutils
14299 Rewrite package inputs to the ``new style'', as described above. This
14300 is how you would rewrite inputs of package @code{whatnot} in your own
14304 guix style -L ~/my/channel -S inputs whatnot
14307 Rewriting is done in a conservative way: preserving comments and bailing
14308 out if it cannot make sense of the code that appears in an inputs field.
14309 The @option{--input-simplification} option described below provides
14310 fine-grain control over when inputs should be simplified.
14313 @item --list-stylings
14315 List and describe the available styling rules and exit.
14317 @item --load-path=@var{directory}
14318 @itemx -L @var{directory}
14319 Add @var{directory} to the front of the package module search path
14320 (@pxref{Package Modules}).
14322 @item --expression=@var{expr}
14323 @itemx -e @var{expr}
14324 Style the package @var{expr} evaluates to.
14326 For example, running:
14329 guix style -e '(@@ (gnu packages gcc) gcc-5)'
14332 styles the @code{gcc-5} package definition.
14334 @item --input-simplification=@var{policy}
14335 When using the @code{inputs} styling rule, with @samp{-S inputs}, this
14336 option specifies the package input simplification policy for cases where
14337 an input label does not match the corresponding package name.
14338 @var{policy} may be one of the following:
14342 Simplify inputs only when the change is ``silent'', meaning that the
14343 package does not need to be rebuilt (its derivation is unchanged).
14346 Simplify inputs only when that is ``safe'' to do: the package might need
14347 to be rebuilt, but the change is known to have no observable effect.
14350 Simplify inputs even when input labels do not match package names, and
14351 even if that might have an observable effect.
14354 The default is @code{silent}, meaning that input simplifications do not
14355 trigger any package rebuild.
14358 @node Invoking guix lint
14359 @section Invoking @command{guix lint}
14361 @cindex @command{guix lint}
14362 @cindex package, checking for errors
14363 The @command{guix lint} command is meant to help package developers avoid
14364 common errors and use a consistent style. It runs a number of checks on
14365 a given set of packages in order to find common mistakes in their
14366 definitions. Available @dfn{checkers} include (see
14367 @option{--list-checkers} for a complete list):
14372 Validate certain typographical and stylistic rules about package
14373 descriptions and synopses.
14375 @item inputs-should-be-native
14376 Identify inputs that should most likely be native inputs.
14382 @itemx source-file-name
14383 Probe @code{home-page} and @code{source} URLs and report those that are
14384 invalid. Suggest a @code{mirror://} URL when applicable. If the
14385 @code{source} URL redirects to a GitHub URL, recommend usage of the GitHub
14386 URL@. Check that the source file name is meaningful, e.g.@: is not just a
14387 version number or ``git-checkout'', without a declared @code{file-name}
14388 (@pxref{origin Reference}).
14390 @item source-unstable-tarball
14391 Parse the @code{source} URL to determine if a tarball from GitHub is
14392 autogenerated or if it is a release tarball. Unfortunately GitHub's
14393 autogenerated tarballs are sometimes regenerated.
14396 Check that the derivation of the given packages can be successfully
14397 computed for all the supported systems (@pxref{Derivations}).
14399 @item profile-collisions
14400 Check whether installing the given packages in a profile would lead to
14401 collisions. Collisions occur when several packages with the same name
14402 but a different version or a different store file name are propagated.
14403 @xref{package Reference, @code{propagated-inputs}}, for more information
14404 on propagated inputs.
14407 @cindex Software Heritage, source code archive
14408 @cindex archival of source code, Software Heritage
14409 Checks whether the package's source code is archived at
14410 @uref{https://www.softwareheritage.org, Software Heritage}.
14412 When the source code that is not archived comes from a version-control system
14413 (VCS)---e.g., it's obtained with @code{git-fetch}, send Software Heritage a
14414 ``save'' request so that it eventually archives it. This ensures that the
14415 source will remain available in the long term, and that Guix can fall back to
14416 Software Heritage should the source code disappear from its original host.
14417 The status of recent ``save'' requests can be
14418 @uref{https://archive.softwareheritage.org/save/#requests, viewed on-line}.
14420 When source code is a tarball obtained with @code{url-fetch}, simply print a
14421 message when it is not archived. As of this writing, Software Heritage does
14422 not allow requests to save arbitrary tarballs; we are working on ways to
14423 ensure that non-VCS source code is also archived.
14426 @uref{https://archive.softwareheritage.org/api/#rate-limiting, limits the
14427 request rate per IP address}. When the limit is reached, @command{guix lint}
14428 prints a message and the @code{archival} checker stops doing anything until
14429 that limit has been reset.
14432 @cindex security vulnerabilities
14433 @cindex CVE, Common Vulnerabilities and Exposures
14434 Report known vulnerabilities found in the Common Vulnerabilities and
14435 Exposures (CVE) databases of the current and past year
14436 @uref{https://nvd.nist.gov/vuln/data-feeds, published by the US
14439 To view information about a particular vulnerability, visit pages such as:
14443 @indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
14445 @indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
14449 where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
14450 @code{CVE-2015-7554}.
14452 Package developers can specify in package recipes the
14453 @uref{https://nvd.nist.gov/products/cpe,Common Platform Enumeration (CPE)}
14454 name and version of the package when they differ from the name or version
14455 that Guix uses, as in this example:
14461 ;; CPE calls this package "grub2".
14462 (properties '((cpe-name . "grub2")
14463 (cpe-version . "2.3"))))
14466 @c See <https://www.openwall.com/lists/oss-security/2017/03/15/3>.
14467 Some entries in the CVE database do not specify which version of a
14468 package they apply to, and would thus ``stick around'' forever. Package
14469 developers who found CVE alerts and verified they can be ignored can
14470 declare them as in this example:
14476 ;; These CVEs no longer apply and can be safely ignored.
14477 (properties `((lint-hidden-cve . ("CVE-2011-0433"
14480 "CVE-2011-5244")))))
14484 Warn about obvious source code formatting issues: trailing white space,
14485 use of tabulations, etc.
14488 Report old-style input labels that do not match the name of the
14489 corresponding package. This aims to help migrate from the ``old input
14490 style''. @xref{package Reference}, for more information on package
14491 inputs and input styles. @xref{Invoking guix style}, on how to migrate
14495 The general syntax is:
14498 guix lint @var{options} @var{package}@dots{}
14501 If no package is given on the command line, then all packages are checked.
14502 The @var{options} may be zero or more of the following:
14505 @item --list-checkers
14507 List and describe all the available checkers that will be run on packages
14512 Only enable the checkers specified in a comma-separated list using the
14513 names returned by @option{--list-checkers}.
14517 Only disable the checkers specified in a comma-separated list using the
14518 names returned by @option{--list-checkers}.
14520 @item --expression=@var{expr}
14521 @itemx -e @var{expr}
14522 Consider the package @var{expr} evaluates to.
14524 This is useful to unambiguously designate packages, as in this example:
14527 guix lint -c archival -e '(@@ (gnu packages guile) guile-3.0)'
14532 Only enable the checkers that do not depend on Internet access.
14534 @item --load-path=@var{directory}
14535 @itemx -L @var{directory}
14536 Add @var{directory} to the front of the package module search path
14537 (@pxref{Package Modules}).
14539 This allows users to define their own packages and make them visible to
14540 the command-line tools.
14544 @node Invoking guix size
14545 @section Invoking @command{guix size}
14548 @cindex package size
14550 @cindex @command{guix size}
14551 The @command{guix size} command helps package developers profile the
14552 disk usage of packages. It is easy to overlook the impact of an
14553 additional dependency added to a package, or the impact of using a
14554 single output for a package that could easily be split (@pxref{Packages
14555 with Multiple Outputs}). Such are the typical issues that
14556 @command{guix size} can highlight.
14558 The command can be passed one or more package specifications
14559 such as @code{gcc@@4.8}
14560 or @code{guile:debug}, or a file name in the store. Consider this
14564 $ guix size coreutils
14565 store item total self
14566 /gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
14567 /gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
14568 /gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
14569 /gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
14570 /gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
14571 /gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
14572 /gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
14573 /gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
14578 The store items listed here constitute the @dfn{transitive closure} of
14579 Coreutils---i.e., Coreutils and all its dependencies, recursively---as
14580 would be returned by:
14583 $ guix gc -R /gnu/store/@dots{}-coreutils-8.23
14586 Here the output shows three columns next to store items. The first column,
14587 labeled ``total'', shows the size in mebibytes (MiB) of the closure of
14588 the store item---that is, its own size plus the size of all its
14589 dependencies. The next column, labeled ``self'', shows the size of the
14590 item itself. The last column shows the ratio of the size of the item
14591 itself to the space occupied by all the items listed here.
14593 In this example, we see that the closure of Coreutils weighs in at
14594 79@tie{}MiB, most of which is taken by libc and GCC's run-time support
14595 libraries. (That libc and GCC's libraries represent a large fraction of
14596 the closure is not a problem @i{per se} because they are always available
14597 on the system anyway.)
14599 Since the command also accepts store file names, assessing the size of
14600 a build result is straightforward:
14603 guix size $(guix system build config.scm)
14606 When the package(s) passed to @command{guix size} are available in the
14607 store@footnote{More precisely, @command{guix size} looks for the
14608 @emph{ungrafted} variant of the given package(s), as returned by
14609 @code{guix build @var{package} --no-grafts}. @xref{Security Updates},
14610 for information on grafts.}, @command{guix size} queries the daemon to determine its
14611 dependencies, and measures its size in the store, similar to @command{du
14612 -ms --apparent-size} (@pxref{du invocation,,, coreutils, GNU
14615 When the given packages are @emph{not} in the store, @command{guix size}
14616 reports information based on the available substitutes
14617 (@pxref{Substitutes}). This makes it possible it to profile disk usage of
14618 store items that are not even on disk, only available remotely.
14620 You can also specify several package names:
14623 $ guix size coreutils grep sed bash
14624 store item total self
14625 /gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
14626 /gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
14627 /gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
14628 /gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
14634 In this example we see that the combination of the four packages takes
14635 102.3@tie{}MiB in total, which is much less than the sum of each closure
14636 since they have a lot of dependencies in common.
14638 When looking at the profile returned by @command{guix size}, you may
14639 find yourself wondering why a given package shows up in the profile at
14640 all. To understand it, you can use @command{guix graph --path -t
14641 references} to display the shortest path between the two packages
14642 (@pxref{Invoking guix graph}).
14644 The available options are:
14648 @item --substitute-urls=@var{urls}
14649 Use substitute information from @var{urls}.
14650 @xref{client-substitute-urls, the same option for @code{guix build}}.
14652 @item --sort=@var{key}
14653 Sort lines according to @var{key}, one of the following options:
14657 the size of each item (the default);
14659 the total size of the item's closure.
14662 @item --map-file=@var{file}
14663 Write a graphical map of disk usage in PNG format to @var{file}.
14665 For the example above, the map looks like this:
14667 @image{images/coreutils-size-map,5in,, map of Coreutils disk usage
14668 produced by @command{guix size}}
14670 This option requires that
14671 @uref{https://wingolog.org/software/guile-charting/, Guile-Charting} be
14672 installed and visible in Guile's module search path. When that is not
14673 the case, @command{guix size} fails as it tries to load it.
14675 @item --system=@var{system}
14676 @itemx -s @var{system}
14677 Consider packages for @var{system}---e.g., @code{x86_64-linux}.
14679 @item --load-path=@var{directory}
14680 @itemx -L @var{directory}
14681 Add @var{directory} to the front of the package module search path
14682 (@pxref{Package Modules}).
14684 This allows users to define their own packages and make them visible to
14685 the command-line tools.
14688 @node Invoking guix graph
14689 @section Invoking @command{guix graph}
14692 @cindex @command{guix graph}
14693 @cindex package dependencies
14694 Packages and their dependencies form a @dfn{graph}, specifically a
14695 directed acyclic graph (DAG). It can quickly become difficult to have a
14696 mental model of the package DAG, so the @command{guix graph} command
14697 provides a visual representation of the DAG@. By default,
14698 @command{guix graph} emits a DAG representation in the input format of
14699 @uref{https://www.graphviz.org/, Graphviz}, so its output can be passed
14700 directly to the @command{dot} command of Graphviz. It can also emit an
14701 HTML page with embedded JavaScript code to display a ``chord diagram''
14702 in a Web browser, using the @uref{https://d3js.org/, d3.js} library, or
14703 emit Cypher queries to construct a graph in a graph database supporting
14704 the @uref{https://www.opencypher.org/, openCypher} query language. With
14705 @option{--path}, it simply displays the shortest path between two
14706 packages. The general syntax is:
14709 guix graph @var{options} @var{package}@dots{}
14712 For example, the following command generates a PDF file representing the
14713 package DAG for the GNU@tie{}Core Utilities, showing its build-time
14717 guix graph coreutils | dot -Tpdf > dag.pdf
14720 The output looks like this:
14722 @image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
14724 Nice little graph, no?
14726 You may find it more pleasant to navigate the graph interactively with
14727 @command{xdot} (from the @code{xdot} package):
14730 guix graph coreutils | xdot -
14733 But there is more than one graph! The one above is concise: it is the
14734 graph of package objects, omitting implicit inputs such as GCC, libc,
14735 grep, etc. It is often useful to have such a concise graph, but
14736 sometimes one may want to see more details. @command{guix graph} supports
14737 several types of graphs, allowing you to choose the level of detail:
14741 This is the default type used in the example above. It shows the DAG of
14742 package objects, excluding implicit dependencies. It is concise, but
14743 filters out many details.
14745 @item reverse-package
14746 This shows the @emph{reverse} DAG of packages. For example:
14749 guix graph --type=reverse-package ocaml
14752 ...@: yields the graph of packages that @emph{explicitly} depend on OCaml (if
14753 you are also interested in cases where OCaml is an implicit dependency, see
14754 @code{reverse-bag} below).
14756 Note that for core packages this can yield huge graphs. If all you want
14757 is to know the number of packages that depend on a given package, use
14758 @command{guix refresh --list-dependent} (@pxref{Invoking guix refresh,
14759 @option{--list-dependent}}).
14762 This is the package DAG, @emph{including} implicit inputs.
14764 For instance, the following command:
14767 guix graph --type=bag-emerged coreutils
14770 ...@: yields this bigger graph:
14772 @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU Coreutils}
14774 At the bottom of the graph, we see all the implicit inputs of
14775 @var{gnu-build-system} (@pxref{Build Systems, @code{gnu-build-system}}).
14777 Now, note that the dependencies of these implicit inputs---that is, the
14778 @dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown
14779 here, for conciseness.
14782 Similar to @code{bag-emerged}, but this time including all the bootstrap
14785 @item bag-with-origins
14786 Similar to @code{bag}, but also showing origins and their dependencies.
14789 This shows the @emph{reverse} DAG of packages. Unlike @code{reverse-package},
14790 it also takes implicit dependencies into account. For example:
14793 guix graph -t reverse-bag dune
14797 ...@: yields the graph of all packages that depend on Dune, directly or
14798 indirectly. Since Dune is an @emph{implicit} dependency of many packages
14799 @i{via} @code{dune-build-system}, this shows a large number of packages,
14800 whereas @code{reverse-package} would show very few if any.
14803 This is the most detailed representation: It shows the DAG of
14804 derivations (@pxref{Derivations}) and plain store items. Compared to
14805 the above representation, many additional nodes are visible, including
14806 build scripts, patches, Guile modules, etc.
14808 For this type of graph, it is also possible to pass a @file{.drv} file
14809 name instead of a package name, as in:
14812 guix graph -t derivation $(guix system build -d my-config.scm)
14816 This is the graph of @dfn{package modules} (@pxref{Package Modules}).
14817 For example, the following command shows the graph for the package
14818 module that defines the @code{guile} package:
14821 guix graph -t module guile | xdot -
14825 All the types above correspond to @emph{build-time dependencies}. The
14826 following graph type represents the @emph{run-time dependencies}:
14830 This is the graph of @dfn{references} of a package output, as returned
14831 by @command{guix gc --references} (@pxref{Invoking guix gc}).
14833 If the given package output is not available in the store, @command{guix
14834 graph} attempts to obtain dependency information from substitutes.
14836 Here you can also pass a store file name instead of a package name. For
14837 example, the command below produces the reference graph of your profile
14838 (which can be big!):
14841 guix graph -t references $(readlink -f ~/.guix-profile)
14845 This is the graph of the @dfn{referrers} of a store item, as returned by
14846 @command{guix gc --referrers} (@pxref{Invoking guix gc}).
14848 This relies exclusively on local information from your store. For
14849 instance, let us suppose that the current Inkscape is available in 10
14850 profiles on your machine; @command{guix graph -t referrers inkscape}
14851 will show a graph rooted at Inkscape and with those 10 profiles linked
14854 It can help determine what is preventing a store item from being garbage
14859 @cindex shortest path, between packages
14860 Often, the graph of the package you are interested in does not fit on
14861 your screen, and anyway all you want to know is @emph{why} that package
14862 actually depends on some seemingly unrelated package. The
14863 @option{--path} option instructs @command{guix graph} to display the
14864 shortest path between two packages (or derivations, or store items,
14868 $ guix graph --path emacs libunistring
14871 libunistring@@0.9.10
14872 $ guix graph --path -t derivation emacs libunistring
14873 /gnu/store/@dots{}-emacs-26.3.drv
14874 /gnu/store/@dots{}-mailutils-3.9.drv
14875 /gnu/store/@dots{}-libunistring-0.9.10.drv
14876 $ guix graph --path -t references emacs libunistring
14877 /gnu/store/@dots{}-emacs-26.3
14878 /gnu/store/@dots{}-libidn2-2.2.0
14879 /gnu/store/@dots{}-libunistring-0.9.10
14882 Sometimes you still want to visualize the graph but would like to trim
14883 it so it can actually be displayed. One way to do it is via the
14884 @option{--max-depth} (or @option{-M}) option, which lets you specify the
14885 maximum depth of the graph. In the example below, we visualize only
14886 @code{libreoffice} and the nodes whose distance to @code{libreoffice} is
14890 guix graph -M 2 libreoffice | xdot -f fdp -
14893 Mind you, that's still a big ball of spaghetti, but at least
14894 @command{dot} can render it quickly and it can be browsed somewhat.
14896 The available options are the following:
14899 @item --type=@var{type}
14900 @itemx -t @var{type}
14901 Produce a graph output of @var{type}, where @var{type} must be one of
14902 the values listed above.
14905 List the supported graph types.
14907 @item --backend=@var{backend}
14908 @itemx -b @var{backend}
14909 Produce a graph using the selected @var{backend}.
14911 @item --list-backends
14912 List the supported graph backends.
14914 Currently, the available backends are Graphviz and d3.js.
14917 Display the shortest path between two nodes of the type specified by
14918 @option{--type}. The example below shows the shortest path between
14919 @code{libreoffice} and @code{llvm} according to the references of
14920 @code{libreoffice}:
14923 $ guix graph --path -t references libreoffice llvm
14924 /gnu/store/@dots{}-libreoffice-6.4.2.2
14925 /gnu/store/@dots{}-libepoxy-1.5.4
14926 /gnu/store/@dots{}-mesa-19.3.4
14927 /gnu/store/@dots{}-llvm-9.0.1
14930 @item --expression=@var{expr}
14931 @itemx -e @var{expr}
14932 Consider the package @var{expr} evaluates to.
14934 This is useful to precisely refer to a package, as in this example:
14937 guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
14940 @item --system=@var{system}
14941 @itemx -s @var{system}
14942 Display the graph for @var{system}---e.g., @code{i686-linux}.
14944 The package dependency graph is largely architecture-independent, but there
14945 are some architecture-dependent bits that this option allows you to visualize.
14947 @item --load-path=@var{directory}
14948 @itemx -L @var{directory}
14949 Add @var{directory} to the front of the package module search path
14950 (@pxref{Package Modules}).
14952 This allows users to define their own packages and make them visible to
14953 the command-line tools.
14956 On top of that, @command{guix graph} supports all the usual package
14957 transformation options (@pxref{Package Transformation Options}). This
14958 makes it easy to view the effect of a graph-rewriting transformation
14959 such as @option{--with-input}. For example, the command below outputs
14960 the graph of @code{git} once @code{openssl} has been replaced by
14961 @code{libressl} everywhere in the graph:
14964 guix graph git --with-input=openssl=libressl
14967 So many possibilities, so much fun!
14969 @node Invoking guix publish
14970 @section Invoking @command{guix publish}
14972 @cindex @command{guix publish}
14973 The purpose of @command{guix publish} is to enable users to easily share
14974 their store with others, who can then use it as a substitute server
14975 (@pxref{Substitutes}).
14977 When @command{guix publish} runs, it spawns an HTTP server which allows
14978 anyone with network access to obtain substitutes from it. This means
14979 that any machine running Guix can also act as if it were a build farm,
14980 since the HTTP interface is compatible with Cuirass, the software behind
14981 the @code{@value{SUBSTITUTE-SERVER-1}} build farm.
14983 For security, each substitute is signed, allowing recipients to check
14984 their authenticity and integrity (@pxref{Substitutes}). Because
14985 @command{guix publish} uses the signing key of the system, which is only
14986 readable by the system administrator, it must be started as root; the
14987 @option{--user} option makes it drop root privileges early on.
14989 The signing key pair must be generated before @command{guix publish} is
14990 launched, using @command{guix archive --generate-key} (@pxref{Invoking
14993 When the @option{--advertise} option is passed, the server advertises
14994 its availability on the local network using multicast DNS (mDNS) and DNS
14995 service discovery (DNS-SD), currently @i{via} Guile-Avahi (@pxref{Top,,,
14996 guile-avahi, Using Avahi in Guile Scheme Programs}).
14998 The general syntax is:
15001 guix publish @var{options}@dots{}
15004 Running @command{guix publish} without any additional arguments will
15005 spawn an HTTP server on port 8080:
15011 @cindex socket activation, for @command{guix publish}
15012 @command{guix publish} can also be started following the systemd
15013 ``socket activation'' protocol (@pxref{Service De- and Constructors,
15014 @code{make-systemd-constructor},, shepherd, The GNU Shepherd Manual}).
15016 Once a publishing server has been authorized, the daemon may download
15017 substitutes from it. @xref{Getting Substitutes from Other Servers}.
15019 By default, @command{guix publish} compresses archives on the fly as it
15020 serves them. This ``on-the-fly'' mode is convenient in that it requires
15021 no setup and is immediately available. However, when serving lots of
15022 clients, we recommend using the @option{--cache} option, which enables
15023 caching of the archives before they are sent to clients---see below for
15024 details. The @command{guix weather} command provides a handy way to
15025 check what a server provides (@pxref{Invoking guix weather}).
15027 As a bonus, @command{guix publish} also serves as a content-addressed
15028 mirror for source files referenced in @code{origin} records
15029 (@pxref{origin Reference}). For instance, assuming @command{guix
15030 publish} is running on @code{example.org}, the following URL returns the
15031 raw @file{hello-2.10.tar.gz} file with the given SHA256 hash
15032 (represented in @code{nix-base32} format, @pxref{Invoking guix hash}):
15035 http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
15038 Obviously, these URLs only work for files that are in the store; in
15039 other cases, they return 404 (``Not Found'').
15041 @cindex build logs, publication
15042 Build logs are available from @code{/log} URLs like:
15045 http://example.org/log/gwspk@dots{}-guile-2.2.3
15049 When @command{guix-daemon} is configured to save compressed build logs,
15050 as is the case by default (@pxref{Invoking guix-daemon}), @code{/log}
15051 URLs return the compressed log as-is, with an appropriate
15052 @code{Content-Type} and/or @code{Content-Encoding} header. We recommend
15053 running @command{guix-daemon} with @option{--log-compression=gzip} since
15054 Web browsers can automatically decompress it, which is not the case with
15057 The following options are available:
15060 @item --port=@var{port}
15061 @itemx -p @var{port}
15062 Listen for HTTP requests on @var{port}.
15064 @item --listen=@var{host}
15065 Listen on the network interface for @var{host}. The default is to
15066 accept connections from any interface.
15068 @item --user=@var{user}
15069 @itemx -u @var{user}
15070 Change privileges to @var{user} as soon as possible---i.e., once the
15071 server socket is open and the signing key has been read.
15073 @item --compression[=@var{method}[:@var{level}]]
15074 @itemx -C [@var{method}[:@var{level}]]
15075 Compress data using the given @var{method} and @var{level}. @var{method} is
15076 one of @code{lzip}, @code{zstd}, and @code{gzip}; when @var{method} is
15077 omitted, @code{gzip} is used.
15079 When @var{level} is zero, disable compression. The range 1 to 9 corresponds
15080 to different compression levels: 1 is the fastest, and 9 is the best
15081 (CPU-intensive). The default is 3.
15083 Usually, @code{lzip} compresses noticeably better than @code{gzip} for a
15084 small increase in CPU usage; see
15085 @uref{https://nongnu.org/lzip/lzip_benchmark.html,benchmarks on the lzip
15086 Web page}. However, @code{lzip} achieves low decompression throughput
15087 (on the order of 50@tie{}MiB/s on modern hardware), which can be a
15088 bottleneck for someone who downloads over a fast network connection.
15090 The compression ratio of @code{zstd} is between that of @code{lzip} and
15091 that of @code{gzip}; its main advantage is a
15092 @uref{https://facebook.github.io/zstd/,high decompression speed}.
15094 Unless @option{--cache} is used, compression occurs on the fly and
15095 the compressed streams are not
15096 cached. Thus, to reduce load on the machine that runs @command{guix
15097 publish}, it may be a good idea to choose a low compression level, to
15098 run @command{guix publish} behind a caching proxy, or to use
15099 @option{--cache}. Using @option{--cache} has the advantage that it
15100 allows @command{guix publish} to add @code{Content-Length} HTTP header
15103 This option can be repeated, in which case every substitute gets compressed
15104 using all the selected methods, and all of them are advertised. This is
15105 useful when users may not support all the compression methods: they can select
15106 the one they support.
15108 @item --cache=@var{directory}
15109 @itemx -c @var{directory}
15110 Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory}
15111 and only serve archives that are in cache.
15113 When this option is omitted, archives and meta-data are created
15114 on-the-fly. This can reduce the available bandwidth, especially when
15115 compression is enabled, since this may become CPU-bound. Another
15116 drawback of the default mode is that the length of archives is not known
15117 in advance, so @command{guix publish} does not add a
15118 @code{Content-Length} HTTP header to its responses, which in turn
15119 prevents clients from knowing the amount of data being downloaded.
15121 Conversely, when @option{--cache} is used, the first request for a store
15122 item (@i{via} a @code{.narinfo} URL) triggers a
15123 background process to @dfn{bake} the archive---computing its
15124 @code{.narinfo} and compressing the archive, if needed. Once the
15125 archive is cached in @var{directory}, subsequent requests succeed and
15126 are served directly from the cache, which guarantees that clients get
15127 the best possible bandwidth.
15129 That first @code{.narinfo} request nonetheless returns 200, provided the
15130 requested store item is ``small enough'', below the cache bypass
15131 threshold---see @option{--cache-bypass-threshold} below. That way,
15132 clients do not have to wait until the archive is baked. For larger
15133 store items, the first @code{.narinfo} request returns 404, meaning that
15134 clients have to wait until the archive is baked.
15136 The ``baking'' process is performed by worker threads. By default, one
15137 thread per CPU core is created, but this can be customized. See
15138 @option{--workers} below.
15140 When @option{--ttl} is used, cached entries are automatically deleted
15141 when they have expired.
15143 @item --workers=@var{N}
15144 When @option{--cache} is used, request the allocation of @var{N} worker
15145 threads to ``bake'' archives.
15147 @item --ttl=@var{ttl}
15148 Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
15149 (TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
15150 days, @code{1m} means 1 month, and so on.
15152 This allows the user's Guix to keep substitute information in cache for
15153 @var{ttl}. However, note that @code{guix publish} does not itself
15154 guarantee that the store items it provides will indeed remain available
15155 for as long as @var{ttl}.
15157 Additionally, when @option{--cache} is used, cached entries that have
15158 not been accessed for @var{ttl} and that no longer have a corresponding
15159 item in the store, may be deleted.
15161 @item --negative-ttl=@var{ttl}
15162 Similarly produce @code{Cache-Control} HTTP headers to advertise the
15163 time-to-live (TTL) of @emph{negative} lookups---missing store items, for
15164 which the HTTP 404 code is returned. By default, no negative TTL is
15167 This parameter can help adjust server load and substitute latency by
15168 instructing cooperating clients to be more or less patient when a store
15171 @item --cache-bypass-threshold=@var{size}
15172 When used in conjunction with @option{--cache}, store items smaller than
15173 @var{size} are immediately available, even when they are not yet in
15174 cache. @var{size} is a size in bytes, or it can be suffixed by @code{M}
15175 for megabytes and so on. The default is @code{10M}.
15177 ``Cache bypass'' allows you to reduce the publication delay for clients
15178 at the expense of possibly additional I/O and CPU use on the server
15179 side: depending on the client access patterns, those store items can end
15180 up being baked several times until a copy is available in cache.
15182 Increasing the threshold may be useful for sites that have few users, or
15183 to guarantee that users get substitutes even for store items that are
15186 @item --nar-path=@var{path}
15187 Use @var{path} as the prefix for the URLs of ``nar'' files
15188 (@pxref{Invoking guix archive, normalized archives}).
15190 By default, nars are served at a URL such as
15191 @code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to
15192 change the @code{/nar} part to @var{path}.
15194 @item --public-key=@var{file}
15195 @itemx --private-key=@var{file}
15196 Use the specific @var{file}s as the public/private key pair used to sign
15197 the store items being published.
15199 The files must correspond to the same key pair (the private key is used
15200 for signing and the public key is merely advertised in the signature
15201 metadata). They must contain keys in the canonical s-expression format
15202 as produced by @command{guix archive --generate-key} (@pxref{Invoking
15203 guix archive}). By default, @file{/etc/guix/signing-key.pub} and
15204 @file{/etc/guix/signing-key.sec} are used.
15206 @item --repl[=@var{port}]
15207 @itemx -r [@var{port}]
15208 Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile
15209 Reference Manual}) on @var{port} (37146 by default). This is used
15210 primarily for debugging a running @command{guix publish} server.
15213 Enabling @command{guix publish} on Guix System is a one-liner: just
15214 instantiate a @code{guix-publish-service-type} service in the @code{services} field
15215 of the @code{operating-system} declaration (@pxref{guix-publish-service-type,
15216 @code{guix-publish-service-type}}).
15218 If you are instead running Guix on a ``foreign distro'', follow these
15223 If your host distro uses the systemd init system:
15226 # ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
15227 /etc/systemd/system/
15228 # systemctl start guix-publish && systemctl enable guix-publish
15232 If your host distro uses the Upstart init system:
15235 # ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
15236 # start guix-publish
15240 Otherwise, proceed similarly with your distro's init system.
15243 @node Invoking guix challenge
15244 @section Invoking @command{guix challenge}
15246 @cindex reproducible builds
15247 @cindex verifiable builds
15248 @cindex @command{guix challenge}
15250 Do the binaries provided by this server really correspond to the source
15251 code it claims to build? Is a package build process deterministic?
15252 These are the questions the @command{guix challenge} command attempts to
15255 The former is obviously an important question: Before using a substitute
15256 server (@pxref{Substitutes}), one had better @emph{verify} that it
15257 provides the right binaries, and thus @emph{challenge} it. The latter
15258 is what enables the former: If package builds are deterministic, then
15259 independent builds of the package should yield the exact same result,
15260 bit for bit; if a server provides a binary different from the one
15261 obtained locally, it may be either corrupt or malicious.
15263 We know that the hash that shows up in @file{/gnu/store} file names is
15264 the hash of all the inputs of the process that built the file or
15265 directory---compilers, libraries, build scripts,
15266 etc. (@pxref{Introduction}). Assuming deterministic build processes,
15267 one store file name should map to exactly one build output.
15268 @command{guix challenge} checks whether there is, indeed, a single
15269 mapping by comparing the build outputs of several independent builds of
15270 any given store item.
15272 The command output looks like this:
15276 --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org" \
15277 openssl git pius coreutils grep
15278 updating substitutes from 'https://@value{SUBSTITUTE-SERVER-1}'... 100.0%
15279 updating substitutes from 'https://guix.example.org'... 100.0%
15280 /gnu/store/@dots{}-openssl-1.0.2d contents differ:
15281 local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
15282 https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
15283 https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
15285 /lib/libcrypto.so.1.1
15288 /gnu/store/@dots{}-git-2.5.0 contents differ:
15289 local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
15290 https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
15291 https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
15293 /libexec/git-core/git-fsck
15295 /gnu/store/@dots{}-pius-2.1.1 contents differ:
15296 local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
15297 https://@value{SUBSTITUTE-SERVER-1}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
15298 https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
15300 /share/man/man1/pius.1.gz
15304 5 store items were analyzed:
15305 - 2 (40.0%) were identical
15306 - 3 (60.0%) differed
15307 - 0 (0.0%) were inconclusive
15311 In this example, @command{guix challenge} queries all the substitute
15312 servers for each of the fives packages specified on the command line.
15313 It then reports those store items for which the servers obtained a
15314 result different from the local build (if it exists) and/or different
15315 from one another; here, the @samp{local hash} lines indicate that a
15316 local build result was available for each of these packages and shows
15319 @cindex non-determinism, in package builds
15320 As an example, @code{guix.example.org} always gets a different answer.
15321 Conversely, @code{@value{SUBSTITUTE-SERVER-1}} agrees with local builds, except in the
15322 case of Git. This might indicate that the build process of Git is
15323 non-deterministic, meaning that its output varies as a function of
15324 various things that Guix does not fully control, in spite of building
15325 packages in isolated environments (@pxref{Features}). Most common
15326 sources of non-determinism include the addition of timestamps in build
15327 results, the inclusion of random numbers, and directory listings sorted
15328 by inode number. See @uref{https://reproducible-builds.org/docs/}, for
15331 To find out what is wrong with this Git binary, the easiest approach is
15335 guix challenge git \
15336 --diff=diffoscope \
15337 --substitute-urls="https://@value{SUBSTITUTE-SERVER-1} https://guix.example.org"
15340 This automatically invokes @command{diffoscope}, which displays detailed
15341 information about files that differ.
15343 Alternatively, we can do something along these lines (@pxref{Invoking guix
15347 $ wget -q -O - https://@value{SUBSTITUTE-SERVER-1}/nar/lzip/@dots{}-git-2.5.0 \
15348 | lzip -d | guix archive -x /tmp/git
15349 $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
15352 This command shows the difference between the files resulting from the
15353 local build, and the files resulting from the build on
15354 @code{@value{SUBSTITUTE-SERVER-1}} (@pxref{Overview, Comparing and Merging Files,,
15355 diffutils, Comparing and Merging Files}). The @command{diff} command
15356 works great for text files. When binary files differ, a better option
15357 is @uref{https://diffoscope.org/, Diffoscope}, a tool that helps
15358 visualize differences for all kinds of files.
15360 Once you have done that work, you can tell whether the differences are due
15361 to a non-deterministic build process or to a malicious server. We try
15362 hard to remove sources of non-determinism in packages to make it easier
15363 to verify substitutes, but of course, this is a process that
15364 involves not just Guix, but a large part of the free software community.
15365 In the meantime, @command{guix challenge} is one tool to help address
15368 If you are writing packages for Guix, you are encouraged to check
15369 whether @code{@value{SUBSTITUTE-SERVER-1}} and other substitute servers obtain the
15370 same build result as you did with:
15373 guix challenge @var{package}
15376 The general syntax is:
15379 guix challenge @var{options} @var{argument}@dots{}
15383 where @var{argument} is a package specification such as
15384 @code{guile@@2.0} or @code{glibc:debug} or, alternatively, a store file
15385 name as returned, for example, by @command{guix build} or @command{guix
15388 When a difference is found between the hash of a locally-built item and
15389 that of a server-provided substitute, or among substitutes provided by
15390 different servers, the command displays it as in the example above and
15391 its exit code is 2 (other non-zero exit codes denote other kinds of
15394 The one option that matters is:
15398 @item --substitute-urls=@var{urls}
15399 Consider @var{urls} the whitespace-separated list of substitute source
15400 URLs to compare to.
15402 @item --diff=@var{mode}
15403 Upon mismatches, show differences according to @var{mode}, one of:
15406 @item @code{simple} (the default)
15407 Show the list of files that differ.
15409 @item @code{diffoscope}
15410 @itemx @var{command}
15411 Invoke @uref{https://diffoscope.org/, Diffoscope}, passing it
15412 two directories whose contents do not match.
15414 When @var{command} is an absolute file name, run @var{command} instead
15418 Do not show further details about the differences.
15421 Thus, unless @option{--diff=none} is passed, @command{guix challenge}
15422 downloads the store items from the given substitute servers so that it
15427 Show details about matches (identical contents) in addition to
15428 information about mismatches.
15432 @node Invoking guix copy
15433 @section Invoking @command{guix copy}
15435 @cindex @command{guix copy}
15436 @cindex copy, of store items, over SSH
15437 @cindex SSH, copy of store items
15438 @cindex sharing store items across machines
15439 @cindex transferring store items across machines
15440 The @command{guix copy} command copies items from the store of one
15441 machine to that of another machine over a secure shell (SSH)
15442 connection@footnote{This command is available only when Guile-SSH was
15443 found. @xref{Requirements}, for details.}. For example, the following
15444 command copies the @code{coreutils} package, the user's profile, and all
15445 their dependencies over to @var{host}, logged in as @var{user}:
15448 guix copy --to=@var{user}@@@var{host} \
15449 coreutils $(readlink -f ~/.guix-profile)
15452 If some of the items to be copied are already present on @var{host},
15453 they are not actually sent.
15455 The command below retrieves @code{libreoffice} and @code{gimp} from
15456 @var{host}, assuming they are available there:
15459 guix copy --from=@var{host} libreoffice gimp
15462 The SSH connection is established using the Guile-SSH client, which is
15463 compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
15464 @file{~/.ssh/config}, and uses the SSH agent for authentication.
15466 The key used to sign items that are sent must be accepted by the remote
15467 machine. Likewise, the key used by the remote machine to sign items you
15468 are retrieving must be in @file{/etc/guix/acl} so it is accepted by your
15469 own daemon. @xref{Invoking guix archive}, for more information about
15470 store item authentication.
15472 The general syntax is:
15475 guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
15478 You must always specify one of the following options:
15481 @item --to=@var{spec}
15482 @itemx --from=@var{spec}
15483 Specify the host to send to or receive from. @var{spec} must be an SSH
15484 spec such as @code{example.org}, @code{charlie@@example.org}, or
15485 @code{charlie@@example.org:2222}.
15488 The @var{items} can be either package names, such as @code{gimp}, or
15489 store items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
15491 When specifying the name of a package to send, it is first built if
15492 needed, unless @option{--dry-run} was specified. Common build options
15493 are supported (@pxref{Common Build Options}).
15496 @node Invoking guix container
15497 @section Invoking @command{guix container}
15499 @cindex @command{guix container}
15501 As of version @value{VERSION}, this tool is experimental. The interface
15502 is subject to radical change in the future.
15505 The purpose of @command{guix container} is to manipulate processes
15506 running within an isolated environment, commonly known as a
15507 ``container'', typically created by the @command{guix shell}
15508 (@pxref{Invoking guix shell}) and @command{guix system container}
15509 (@pxref{Invoking guix system}) commands.
15511 The general syntax is:
15514 guix container @var{action} @var{options}@dots{}
15517 @var{action} specifies the operation to perform with a container, and
15518 @var{options} specifies the context-specific arguments for the action.
15520 The following actions are available:
15524 Execute a command within the context of a running container.
15529 guix container exec @var{pid} @var{program} @var{arguments}@dots{}
15532 @var{pid} specifies the process ID of the running container.
15533 @var{program} specifies an executable file name within the root file
15534 system of the container. @var{arguments} are the additional options that
15535 will be passed to @var{program}.
15537 The following command launches an interactive login shell inside a
15538 Guix system container, started by @command{guix system container}, and whose
15539 process ID is 9001:
15542 guix container exec 9001 /run/current-system/profile/bin/bash --login
15545 Note that the @var{pid} cannot be the parent process of a container. It
15546 must be PID 1 of the container or one of its child processes.
15550 @node Invoking guix weather
15551 @section Invoking @command{guix weather}
15553 @cindex @command{guix weather}
15554 Occasionally you're grumpy because substitutes are lacking and you end
15555 up building packages by yourself (@pxref{Substitutes}). The
15556 @command{guix weather} command reports on substitute availability on the
15557 specified servers so you can have an idea of whether you'll be grumpy
15558 today. It can sometimes be useful info as a user, but it is primarily
15559 useful to people running @command{guix publish} (@pxref{Invoking guix
15562 @cindex statistics, for substitutes
15563 @cindex availability of substitutes
15564 @cindex substitute availability
15565 @cindex weather, substitute availability
15566 Here's a sample run:
15569 $ guix weather --substitute-urls=https://guix.example.org
15570 computing 5,872 package derivations for x86_64-linux...
15571 looking for 6,128 store items on https://guix.example.org..
15572 updating substitutes from 'https://guix.example.org'... 100.0%
15573 https://guix.example.org
15574 43.4% substitutes available (2,658 out of 6,128)
15575 7,032.5 MiB of nars (compressed)
15576 19,824.2 MiB on disk (uncompressed)
15577 0.030 seconds per request (182.9 seconds in total)
15578 33.5 requests per second
15580 9.8% (342 out of 3,470) of the missing items are queued
15582 x86_64-linux: 518 (59.7%)
15583 i686-linux: 221 (25.5%)
15584 aarch64-linux: 128 (14.8%)
15585 build rate: 23.41 builds per hour
15586 x86_64-linux: 11.16 builds per hour
15587 i686-linux: 6.03 builds per hour
15588 aarch64-linux: 6.41 builds per hour
15591 @cindex continuous integration, statistics
15592 As you can see, it reports the fraction of all the packages for which
15593 substitutes are available on the server---regardless of whether
15594 substitutes are enabled, and regardless of whether this server's signing
15595 key is authorized. It also reports the size of the compressed archives
15596 (``nars'') provided by the server, the size the corresponding store
15597 items occupy in the store (assuming deduplication is turned off), and
15598 the server's throughput. The second part gives continuous integration
15599 (CI) statistics, if the server supports it. In addition, using the
15600 @option{--coverage} option, @command{guix weather} can list ``important''
15601 package substitutes missing on the server (see below).
15603 To achieve that, @command{guix weather} queries over HTTP(S) meta-data
15604 (@dfn{narinfos}) for all the relevant store items. Like @command{guix
15605 challenge}, it ignores signatures on those substitutes, which is
15606 innocuous since the command only gathers statistics and cannot install
15609 The general syntax is:
15612 guix weather @var{options}@dots{} [@var{packages}@dots{}]
15615 When @var{packages} is omitted, @command{guix weather} checks the availability
15616 of substitutes for @emph{all} the packages, or for those specified with
15617 @option{--manifest}; otherwise it only considers the specified packages. It
15618 is also possible to query specific system types with @option{--system}.
15619 @command{guix weather} exits with a non-zero code when the fraction of
15620 available substitutes is below 100%.
15622 The available options are listed below.
15625 @item --substitute-urls=@var{urls}
15626 @var{urls} is the space-separated list of substitute server URLs to
15627 query. When this option is omitted, the default set of substitute
15628 servers is queried.
15630 @item --system=@var{system}
15631 @itemx -s @var{system}
15632 Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
15633 option can be repeated, in which case @command{guix weather} will query
15634 substitutes for several system types.
15636 @item --manifest=@var{file}
15637 Instead of querying substitutes for all the packages, only ask for those
15638 specified in @var{file}. @var{file} must contain a @dfn{manifest}, as
15639 with the @code{-m} option of @command{guix package} (@pxref{Invoking
15642 This option can be repeated several times, in which case the manifests
15645 @item --coverage[=@var{count}]
15646 @itemx -c [@var{count}]
15647 Report on substitute coverage for packages: list packages with at least
15648 @var{count} dependents (zero by default) for which substitutes are
15649 unavailable. Dependent packages themselves are not listed: if @var{b} depends
15650 on @var{a} and @var{a} has no substitutes, only @var{a} is listed, even though
15651 @var{b} usually lacks substitutes as well. The result looks like this:
15654 $ guix weather --substitute-urls=@value{SUBSTITUTE-URLS} -c 10
15655 computing 8,983 package derivations for x86_64-linux...
15656 looking for 9,343 store items on @value{SUBSTITUTE-URLS}...
15657 updating substitutes from '@value{SUBSTITUTE-URLS}'... 100.0%
15658 @value{SUBSTITUTE-URLS}
15659 64.7% substitutes available (6,047 out of 9,343)
15661 2502 packages are missing from '@value{SUBSTITUTE-URLS}' for 'x86_64-linux', among which:
15662 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0
15663 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1
15664 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008
15668 What this example shows is that @code{kcoreaddons} and presumably the 58
15669 packages that depend on it have no substitutes at
15670 @code{@value{SUBSTITUTE-SERVER-1}}; likewise for @code{qgpgme} and the 46
15671 packages that depend on it.
15673 If you are a Guix developer, or if you are taking care of this build farm,
15674 you'll probably want to have a closer look at these packages: they may simply
15677 @item --display-missing
15678 Display the list of store items for which substitutes are missing.
15681 @node Invoking guix processes
15682 @section Invoking @command{guix processes}
15684 @cindex @command{guix processes}
15685 The @command{guix processes} command can be useful to developers and system
15686 administrators, especially on multi-user machines and on build farms: it lists
15687 the current sessions (connections to the daemon), as well as information about
15688 the processes involved@footnote{Remote sessions, when @command{guix-daemon} is
15689 started with @option{--listen} specifying a TCP endpoint, are @emph{not}
15690 listed.}. Here's an example of the information it returns:
15693 $ sudo guix processes
15696 ClientCommand: guix shell python
15700 ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
15704 ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
15705 LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
15706 LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
15707 LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
15709 ChildCommand: guix offload x86_64-linux 7200 1 28800
15711 ChildCommand: guix offload x86_64-linux 7200 1 28800
15713 ChildCommand: guix offload x86_64-linux 7200 1 28800
15716 In this example we see that @command{guix-daemon} has three clients:
15717 @command{guix environment}, @command{guix publish}, and the Cuirass continuous
15718 integration tool; their process identifier (PID) is given by the
15719 @code{ClientPID} field. The @code{SessionPID} field gives the PID of the
15720 @command{guix-daemon} sub-process of this particular session.
15722 The @code{LockHeld} fields show which store items are currently locked
15723 by this session, which corresponds to store items being built or
15724 substituted (the @code{LockHeld} field is not displayed when
15725 @command{guix processes} is not running as root). Last, by looking at
15726 the @code{ChildPID} and @code{ChildCommand} fields, we understand that
15727 these three builds are being offloaded (@pxref{Daemon Offload Setup}).
15729 The output is in Recutils format so we can use the handy @command{recsel}
15730 command to select sessions of interest (@pxref{Selection Expressions,,,
15731 recutils, GNU recutils manual}). As an example, the command shows the command
15732 line and PID of the client that triggered the build of a Perl package:
15735 $ sudo guix processes | \
15736 recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
15738 ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
15741 Additional options are listed below.
15744 @item --format=@var{format}
15745 @itemx -f @var{format}
15746 Produce output in the specified @var{format}, one of:
15750 The default option. It outputs a set of Session recutils records
15751 that include each @code{ChildProcess} as a field.
15754 Normalize the output records into record sets (@pxref{Record Sets,,,
15755 recutils, GNU recutils manual}). Normalizing into record sets allows
15756 joins across record types. The example below lists the PID of each
15757 @code{ChildProcess} and the associated PID for @code{Session} that
15758 spawned the @code{ChildProcess} where the @code{Session} was started
15759 using @command{guix build}.
15762 $ guix processes --format=normalized | \
15766 -p Session.PID,PID \
15767 -e 'Session.ClientCommand ~ "guix build"'
15780 @node Foreign Architectures
15781 @chapter Foreign Architectures
15783 You can target computers of different CPU architectures when producing
15784 packages (@pxref{Invoking guix package}), packs (@pxref{Invoking guix
15785 pack}) or full systems (@pxref{Invoking guix system}).
15787 GNU Guix supports two distinct mechanisms to target foreign
15793 @uref{https://en.wikipedia.org/wiki/Cross_compiler,cross-compilation}
15796 The native building mechanism which consists in building using the CPU
15797 instruction set of the foreign system you are targeting. It often
15798 requires emulation, using the QEMU program for instance.
15802 * Cross-Compilation:: Cross-compiling for another architecture.
15803 * Native Builds:: Targeting another architecture through native builds.
15806 @node Cross-Compilation
15807 @section Cross-Compilation
15809 @cindex foreign architectures
15810 The commands supporting cross-compilation are proposing the
15811 @option{--list-targets} and @option{--target} options.
15813 The @option{--list-targets} option lists all the supported targets that
15814 can be passed as an argument to @option{--target}.
15817 $ guix build --list-targets
15818 The available targets are:
15820 - aarch64-linux-gnu
15821 - arm-linux-gnueabihf
15825 - mips64el-linux-gnu
15826 - powerpc-linux-gnu
15827 - powerpc64le-linux-gnu
15828 - riscv64-linux-gnu
15830 - x86_64-w64-mingw32
15833 Targets are specified as GNU triplets (@pxref{Specifying Target
15834 Triplets, GNU configuration triplets,, autoconf, Autoconf}).
15836 Those triplets are passed to GCC and the other underlying compilers
15837 possibly involved when building a package, a system image or any other
15841 $ guix build --target=aarch64-linux-gnu hello
15842 /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12
15844 $ file /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello
15845 /gnu/store/9926by9qrxa91ijkhw9ndgwp4bn24g9h-hello-2.12/bin/hello: ELF
15846 64-bit LSB executable, ARM aarch64 @dots{}
15849 The major benefit of cross-compilation is that there are no performance
15850 penaly compared to emulation using QEMU. There are however higher risks
15851 that some packages fail to cross-compile because few users are using
15852 this mechanism extensively.
15854 @node Native Builds
15855 @section Native Builds
15857 The commands that support impersonating a specific system have the
15858 @option{--list-systems} and @option{--system} options.
15860 The @option{--list-systems} option lists all the supported systems that
15861 can be passed as an argument to @option{--system}.
15864 $ guix build --list-systems
15865 The available systems are:
15867 - x86_64-linux [current]
15874 - powerpc64le-linux
15877 $ guix build --system=i686-linux hello
15878 /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12
15880 $ file /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello
15881 /gnu/store/cc0km35s8x2z4pmwkrqqjx46i8b1i3gm-hello-2.12/bin/hello: ELF
15882 32-bit LSB executable, Intel 80386 @dots{}
15885 In the above example, the current system is @var{x86_64-linux}. The
15886 @var{hello} package is however built for the @var{i686-linux} system.
15888 This is possible because the @var{i686} CPU instruction set is a subset
15889 of the @var{x86_64}, hence @var{i686} targeting binaries can be run on
15892 Still in the context of the previous example, if picking the
15893 @var{aarch64-linux} system and the @command{guix build
15894 --system=aarch64-linux hello} has to build some derivations, an extra
15895 step might be needed.
15897 The @var{aarch64-linux} targeting binaries cannot directly be run on a
15898 @var{x86_64-linux} system. An emulation layer is requested. The GNU
15899 Guix daemon can take advantage of the Linux kernel
15900 @uref{https://en.wikipedia.org/wiki/Binfmt_misc,binfmt_misc} mechanism
15901 for that. In short, the Linux kernel can defer the execution of a
15902 binary targeting a foreign platform, here @var{aarch64-linux}, to a
15903 userspace program, usually an emulator.
15905 There is a service that registers QEMU as a backend for the
15906 @code{binfmt_misc} mechanism (@pxref{Virtualization Services,
15907 @code{qemu-binfmt-service-type}}). On Debian based foreign
15908 distributions, the alternative would be the @code{qemu-user-static}
15911 If the @code{binfmt_misc} mechanism is not setup correctly, the building
15912 will fail this way:
15915 $ guix build --system=armhf-linux hello --check
15917 @ unsupported-platform /gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv aarch64-linux
15918 while setting up the build environment: a `aarch64-linux' is required to
15919 build `/gnu/store/jjn969pijv7hff62025yxpfmc8zy0aq0-hello-2.12.drv', but
15920 I am a `x86_64-linux'@dots{}
15923 whereas, with the @code{binfmt_misc} mechanism correctly linked with
15924 QEMU, one can expect to see:
15927 $ guix build --system=armhf-linux hello --check
15928 /gnu/store/13xz4nghg39wpymivlwghy08yzj97hlj-hello-2.12
15931 The main advantage of native building compared to cross-compiling, is
15932 that more packages are likely to build correctly. However it comes at a
15933 price: compilation backed by QEMU is @emph{way slower} than
15934 cross-compilation, because every instruction needs to be emulated.
15936 The availability of substitutes for the architecture targeted by the
15937 @code{--system} option can mitigate this problem. An other way to work
15938 around it is to install GNU Guix on a machine whose CPU supports
15939 the targeted instruction set, and set it up as an offload machine
15940 (@pxref{Daemon Offload Setup}).
15942 @node System Configuration
15943 @chapter System Configuration
15945 @cindex system configuration
15946 Guix System supports a consistent whole-system configuration
15947 mechanism. By that we mean that all aspects of the global system
15948 configuration---such as the available system services, timezone and
15949 locale settings, user accounts---are declared in a single place. Such
15950 a @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
15952 One of the advantages of putting all the system configuration under the
15953 control of Guix is that it supports transactional system upgrades, and
15954 makes it possible to roll back to a previous system instantiation,
15955 should something go wrong with the new one (@pxref{Features}). Another
15956 advantage is that it makes it easy to replicate the exact same configuration
15957 across different machines, or at different points in time, without
15958 having to resort to additional administration tools layered on top of
15959 the own tools of the system.
15960 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
15962 This section describes this mechanism. First we focus on the system
15963 administrator's viewpoint---explaining how the system is configured and
15964 instantiated. Then we show how this mechanism can be extended, for
15965 instance to support new system services.
15968 * Using the Configuration System:: Customizing your GNU system.
15969 * operating-system Reference:: Detail of operating-system declarations.
15970 * File Systems:: Configuring file system mounts.
15971 * Mapped Devices:: Block device extra processing.
15972 * Swap Space:: Backing RAM with disk space.
15973 * User Accounts:: Specifying user accounts.
15974 * Keyboard Layout:: How the system interprets key strokes.
15975 * Locales:: Language and cultural convention settings.
15976 * Services:: Specifying system services.
15977 * Setuid Programs:: Programs running with elevated privileges.
15978 * X.509 Certificates:: Authenticating HTTPS servers.
15979 * Name Service Switch:: Configuring libc's name service switch.
15980 * Initial RAM Disk:: Linux-Libre bootstrapping.
15981 * Bootloader Configuration:: Configuring the boot loader.
15982 * Invoking guix system:: Instantiating a system configuration.
15983 * Invoking guix deploy:: Deploying a system configuration to a remote host.
15984 * Running Guix in a VM:: How to run Guix System in a virtual machine.
15985 * Defining Services:: Adding new service definitions.
15988 @node Using the Configuration System
15989 @section Using the Configuration System
15991 The operating system is configured by providing an
15992 @code{operating-system} declaration in a file that can then be passed to
15993 the @command{guix system} command (@pxref{Invoking guix system}). A
15994 simple setup, with the default system services, the default Linux-Libre
15995 kernel, initial RAM disk, and boot loader looks like this:
15997 @findex operating-system
15999 @include os-config-bare-bones.texi
16002 This example should be self-describing. Some of the fields defined
16003 above, such as @code{host-name} and @code{bootloader}, are mandatory.
16004 Others, such as @code{packages} and @code{services}, can be omitted, in
16005 which case they get a default value.
16007 Below we discuss the effect of some of the most important fields
16008 (@pxref{operating-system Reference}, for details about all the available
16009 fields), and how to @dfn{instantiate} the operating system using
16010 @command{guix system}.
16012 @unnumberedsubsec Bootloader
16014 @cindex legacy boot, on Intel machines
16015 @cindex BIOS boot, on Intel machines
16018 The @code{bootloader} field describes the method that will be used to boot
16019 your system. Machines based on Intel processors can boot in ``legacy'' BIOS
16020 mode, as in the example above. However, more recent machines rely instead on
16021 the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that case,
16022 the @code{bootloader} field should contain something along these lines:
16025 (bootloader-configuration
16026 (bootloader grub-efi-bootloader)
16027 (targets '("/boot/efi")))
16030 @xref{Bootloader Configuration}, for more information on the available
16031 configuration options.
16033 @unnumberedsubsec Globally-Visible Packages
16035 @vindex %base-packages
16036 The @code{packages} field lists packages that will be globally visible
16037 on the system, for all user accounts---i.e., in every user's @env{PATH}
16038 environment variable---in addition to the per-user profiles
16039 (@pxref{Invoking guix package}). The @code{%base-packages} variable
16040 provides all the tools one would expect for basic user and administrator
16041 tasks---including the GNU Core Utilities, the GNU Networking Utilities,
16042 the @command{mg} lightweight text editor, @command{find}, @command{grep},
16043 etc. The example above adds GNU@tie{}Screen to those,
16044 taken from the @code{(gnu packages screen)}
16045 module (@pxref{Package Modules}). The
16046 @code{(list package output)} syntax can be used to add a specific output
16050 (use-modules (gnu packages))
16051 (use-modules (gnu packages dns))
16055 (packages (cons (list isc-bind "utils")
16059 @findex specification->package
16060 Referring to packages by variable name, like @code{isc-bind} above, has
16061 the advantage of being unambiguous; it also allows typos and such to be
16062 diagnosed right away as ``unbound variables''. The downside is that one
16063 needs to know which module defines which package, and to augment the
16064 @code{use-package-modules} line accordingly. To avoid that, one can use
16065 the @code{specification->package} procedure of the @code{(gnu packages)}
16066 module, which returns the best package for a given name or name and
16070 (use-modules (gnu packages))
16074 (packages (append (map specification->package
16075 '("tcpdump" "htop" "gnupg@@2.0"))
16079 @unnumberedsubsec System Services
16082 @vindex %base-services
16083 The @code{services} field lists @dfn{system services} to be made
16084 available when the system starts (@pxref{Services}).
16085 The @code{operating-system} declaration above specifies that, in
16086 addition to the basic services, we want the OpenSSH secure shell
16087 daemon listening on port 2222 (@pxref{Networking Services,
16088 @code{openssh-service-type}}). Under the hood,
16089 @code{openssh-service-type} arranges so that @command{sshd} is started with the
16090 right command-line options, possibly with supporting configuration files
16091 generated as needed (@pxref{Defining Services}).
16093 @cindex customization, of services
16094 @findex modify-services
16095 Occasionally, instead of using the base services as is, you will want to
16096 customize them. To do this, use @code{modify-services} (@pxref{Service
16097 Reference, @code{modify-services}}) to modify the list.
16099 @anchor{auto-login to TTY} For example, suppose you want to modify
16100 @code{guix-daemon} and Mingetty (the console log-in) in the
16101 @code{%base-services} list (@pxref{Base Services,
16102 @code{%base-services}}). To do that, you can write the following in
16103 your operating system declaration:
16106 (define %my-services
16107 ;; My very own list of services.
16108 (modify-services %base-services
16109 (guix-service-type config =>
16110 (guix-configuration
16112 ;; Fetch substitutes from example.org.
16114 (list "https://example.org/guix"
16115 "https://ci.guix.gnu.org"))))
16116 (mingetty-service-type config =>
16117 (mingetty-configuration
16119 ;; Automatically log in as "guest".
16120 (auto-login "guest")))))
16124 (services %my-services))
16127 This changes the configuration---i.e., the service parameters---of the
16128 @code{guix-service-type} instance, and that of all the
16129 @code{mingetty-service-type} instances in the @code{%base-services} list
16130 (@pxref{Auto-Login to a Specific TTY, see the cookbook for how to
16131 auto-login one user to a specific TTY,, guix-cookbook, GNU Guix Cookbook})).
16132 Observe how this is accomplished: first, we arrange for the original
16133 configuration to be bound to the identifier @code{config} in the
16134 @var{body}, and then we write the @var{body} so that it evaluates to the
16135 desired configuration. In particular, notice how we use @code{inherit}
16136 to create a new configuration which has the same values as the old
16137 configuration, but with a few modifications.
16139 @cindex encrypted disk
16140 The configuration for a typical ``desktop'' usage, with an encrypted
16141 root partition, a swap file on the root partition, the X11 display
16142 server, GNOME and Xfce (users can choose which of these desktop
16143 environments to use at the log-in screen by pressing @kbd{F1}), network
16144 management, power management, and more, would look like this:
16147 @include os-config-desktop.texi
16150 A graphical system with a choice of lightweight window managers
16151 instead of full-blown desktop environments would look like this:
16154 @include os-config-lightweight-desktop.texi
16157 This example refers to the @file{/boot/efi} file system by its UUID,
16158 @code{1234-ABCD}. Replace this UUID with the right UUID on your system,
16159 as returned by the @command{blkid} command.
16161 @xref{Desktop Services}, for the exact list of services provided by
16162 @code{%desktop-services}. @xref{X.509 Certificates}, for background
16163 information about the @code{nss-certs} package that is used here.
16165 Again, @code{%desktop-services} is just a list of service objects. If
16166 you want to remove services from there, you can do so using the
16167 procedures for list filtering (@pxref{SRFI-1 Filtering and
16168 Partitioning,,, guile, GNU Guile Reference Manual}). For instance, the
16169 following expression returns a list that contains all the services in
16170 @code{%desktop-services} minus the Avahi service:
16173 (remove (lambda (service)
16174 (eq? (service-kind service) avahi-service-type))
16178 Alternatively, the @code{modify-services} macro can be used:
16181 (modify-services %desktop-services
16182 (delete avahi-service-type))
16186 @unnumberedsubsec Instantiating the System
16188 Assuming the @code{operating-system} declaration
16189 is stored in the @file{my-system-config.scm}
16190 file, the @command{guix system reconfigure my-system-config.scm} command
16191 instantiates that configuration, and makes it the default GRUB boot
16192 entry (@pxref{Invoking guix system}).
16195 We recommend that you keep this @file{my-system-config.scm} file safe
16196 and under version control to easily track changes to your configuration.
16199 The normal way to change the system configuration is by updating this
16200 file and re-running @command{guix system reconfigure}. One should never
16201 have to touch files in @file{/etc} or to run commands that modify the
16202 system state such as @command{useradd} or @command{grub-install}. In
16203 fact, you must avoid that since that would not only void your warranty
16204 but also prevent you from rolling back to previous versions of your
16205 system, should you ever need to.
16207 @cindex roll-back, of the operating system
16208 Speaking of roll-back, each time you run @command{guix system
16209 reconfigure}, a new @dfn{generation} of the system is created---without
16210 modifying or deleting previous generations. Old system generations get
16211 an entry in the bootloader boot menu, allowing you to boot them in case
16212 something went wrong with the latest generation. Reassuring, no? The
16213 @command{guix system list-generations} command lists the system
16214 generations available on disk. It is also possible to roll back the
16215 system via the commands @command{guix system roll-back} and
16216 @command{guix system switch-generation}.
16218 Although the @command{guix system reconfigure} command will not modify
16219 previous generations, you must take care when the current generation is not
16220 the latest (e.g., after invoking @command{guix system roll-back}), since
16221 the operation might overwrite a later generation (@pxref{Invoking guix
16224 @unnumberedsubsec The Programming Interface
16226 At the Scheme level, the bulk of an @code{operating-system} declaration
16227 is instantiated with the following monadic procedure (@pxref{The Store
16230 @deffn {Monadic Procedure} operating-system-derivation os
16231 Return a derivation that builds @var{os}, an @code{operating-system}
16232 object (@pxref{Derivations}).
16234 The output of the derivation is a single directory that refers to all
16235 the packages, configuration files, and other supporting files needed to
16236 instantiate @var{os}.
16239 This procedure is provided by the @code{(gnu system)} module. Along
16240 with @code{(gnu services)} (@pxref{Services}), this module contains the
16241 guts of Guix System. Make sure to visit it!
16244 @node operating-system Reference
16245 @section @code{operating-system} Reference
16247 This section summarizes all the options available in
16248 @code{operating-system} declarations (@pxref{Using the Configuration
16251 @deftp {Data Type} operating-system
16252 This is the data type representing an operating system configuration.
16253 By that, we mean all the global system configuration, not per-user
16254 configuration (@pxref{Using the Configuration System}).
16257 @item @code{kernel} (default: @code{linux-libre})
16258 The package object of the operating system kernel to
16259 use@footnote{Currently only the Linux-libre kernel is fully supported.
16260 Using GNU@tie{}mach with the GNU@tie{}Hurd is experimental and only
16261 available when building a virtual machine disk image.}.
16264 @item @code{hurd} (default: @code{#f})
16265 The package object of the Hurd to be started by the kernel. When this
16266 field is set, produce a GNU/Hurd operating system. In that case,
16267 @code{kernel} must also be set to the @code{gnumach} package---the
16268 microkernel the Hurd runs on.
16271 This feature is experimental and only supported for disk images.
16274 @item @code{kernel-loadable-modules} (default: '())
16275 A list of objects (usually packages) to collect loadable kernel modules
16276 from--e.g. @code{(list ddcci-driver-linux)}.
16278 @item @code{kernel-arguments} (default: @code{%default-kernel-arguments})
16279 List of strings or gexps representing additional arguments to pass on
16280 the command-line of the kernel---e.g., @code{("console=ttyS0")}.
16282 @item @code{bootloader}
16283 The system bootloader configuration object. @xref{Bootloader Configuration}.
16286 This is the label (a string) as it appears in the bootloader's menu entry.
16287 The default label includes the kernel name and version.
16289 @item @code{keyboard-layout} (default: @code{#f})
16290 This field specifies the keyboard layout to use in the console. It can be
16291 either @code{#f}, in which case the default keyboard layout is used (usually
16292 US English), or a @code{<keyboard-layout>} record. @xref{Keyboard Layout},
16293 for more information.
16295 This keyboard layout is in effect as soon as the kernel has booted. For
16296 instance, it is the keyboard layout in effect when you type a passphrase if
16297 your root file system is on a @code{luks-device-mapping} mapped device
16298 (@pxref{Mapped Devices}).
16301 This does @emph{not} specify the keyboard layout used by the bootloader, nor
16302 that used by the graphical display server. @xref{Bootloader Configuration},
16303 for information on how to specify the bootloader's keyboard layout. @xref{X
16304 Window}, for information on how to specify the keyboard layout used by the X
16308 @item @code{initrd-modules} (default: @code{%base-initrd-modules})
16310 @cindex initial RAM disk
16311 The list of Linux kernel modules that need to be available in the
16312 initial RAM disk. @xref{Initial RAM Disk}.
16314 @item @code{initrd} (default: @code{base-initrd})
16315 A procedure that returns an initial RAM disk for the Linux
16316 kernel. This field is provided to support low-level customization and
16317 should rarely be needed for casual use. @xref{Initial RAM Disk}.
16319 @item @code{firmware} (default: @code{%base-firmware})
16321 List of firmware packages loadable by the operating system kernel.
16323 The default includes firmware needed for Atheros- and Broadcom-based
16324 WiFi devices (Linux-libre modules @code{ath9k} and @code{b43-open},
16325 respectively). @xref{Hardware Considerations}, for more info on
16326 supported hardware.
16328 @item @code{host-name}
16331 @item @code{hosts-file}
16333 A file-like object (@pxref{G-Expressions, file-like objects}) for use as
16334 @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library
16335 Reference Manual}). The default is a file with entries for
16336 @code{localhost} and @var{host-name}.
16338 @item @code{mapped-devices} (default: @code{'()})
16339 A list of mapped devices. @xref{Mapped Devices}.
16341 @item @code{file-systems}
16342 A list of file systems. @xref{File Systems}.
16344 @item @code{swap-devices} (default: @code{'()})
16345 @cindex swap devices
16346 A list of swap spaces. @xref{Swap Space}.
16348 @item @code{users} (default: @code{%base-user-accounts})
16349 @itemx @code{groups} (default: @code{%base-groups})
16350 List of user accounts and groups. @xref{User Accounts}.
16352 If the @code{users} list lacks a user account with UID@tie{}0, a
16353 ``root'' account with UID@tie{}0 is automatically added.
16355 @item @code{skeletons} (default: @code{(default-skeletons)})
16356 A list of target file name/file-like object tuples (@pxref{G-Expressions,
16357 file-like objects}). These are the skeleton files that will be added to
16358 the home directory of newly-created user accounts.
16360 For instance, a valid value may look like this:
16363 `((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
16364 (".guile" ,(plain-file "guile"
16365 "(use-modules (ice-9 readline))
16366 (activate-readline)")))
16369 @item @code{issue} (default: @code{%default-issue})
16370 A string denoting the contents of the @file{/etc/issue} file, which is
16371 displayed when users log in on a text console.
16373 @item @code{packages} (default: @code{%base-packages})
16374 A list of packages to be installed in the global profile, which is accessible
16375 at @file{/run/current-system/profile}. Each element is either a package
16376 variable or a package/output tuple. Here's a simple example of both:
16379 (cons* git ; the default "out" output
16380 (list git "send-email") ; another output of git
16381 %base-packages) ; the default set
16384 The default set includes core utilities and it is good practice to
16385 install non-core utilities in user profiles (@pxref{Invoking guix
16388 @item @code{timezone} (default: @code{"Etc/UTC"})
16389 A timezone identifying string---e.g., @code{"Europe/Paris"}.
16391 You can run the @command{tzselect} command to find out which timezone
16392 string corresponds to your region. Choosing an invalid timezone name
16393 causes @command{guix system} to fail.
16395 @item @code{locale} (default: @code{"en_US.utf8"})
16396 The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
16397 Library Reference Manual}). @xref{Locales}, for more information.
16399 @item @code{locale-definitions} (default: @code{%default-locale-definitions})
16400 The list of locale definitions to be compiled and that may be used at
16401 run time. @xref{Locales}.
16403 @item @code{locale-libcs} (default: @code{(list @var{glibc})})
16404 The list of GNU@tie{}libc packages whose locale data and tools are used
16405 to build the locale definitions. @xref{Locales}, for compatibility
16406 considerations that justify this option.
16408 @item @code{name-service-switch} (default: @code{%default-nss})
16409 Configuration of the libc name service switch (NSS)---a
16410 @code{<name-service-switch>} object. @xref{Name Service Switch}, for
16413 @item @code{services} (default: @code{%base-services})
16414 A list of service objects denoting system services. @xref{Services}.
16416 @cindex essential services
16417 @item @code{essential-services} (default: ...)
16418 The list of ``essential services''---i.e., things like instances of
16419 @code{system-service-type} and @code{host-name-service-type} (@pxref{Service
16420 Reference}), which are derived from the operating system definition itself.
16421 As a user you should @emph{never} need to touch this field.
16423 @item @code{pam-services} (default: @code{(base-pam-services)})
16425 @cindex pluggable authentication modules
16426 Linux @dfn{pluggable authentication module} (PAM) services.
16427 @c FIXME: Add xref to PAM services section.
16429 @item @code{setuid-programs} (default: @code{%setuid-programs})
16430 List of @code{<setuid-program>}. @xref{Setuid Programs}, for more
16433 @item @code{sudoers-file} (default: @code{%sudoers-specification})
16434 @cindex sudoers file
16435 The contents of the @file{/etc/sudoers} file as a file-like object
16436 (@pxref{G-Expressions, @code{local-file} and @code{plain-file}}).
16438 This file specifies which users can use the @command{sudo} command, what
16439 they are allowed to do, and what privileges they may gain. The default
16440 is that only @code{root} and members of the @code{wheel} group may use
16445 @deffn {Scheme Syntax} this-operating-system
16446 When used in the @emph{lexical scope} of an operating system field definition,
16447 this identifier resolves to the operating system being defined.
16449 The example below shows how to refer to the operating system being defined in
16450 the definition of the @code{label} field:
16453 (use-modules (gnu) (guix))
16457 (label (package-full-name
16458 (operating-system-kernel this-operating-system))))
16461 It is an error to refer to @code{this-operating-system} outside an operating
16468 @section File Systems
16470 The list of file systems to be mounted is specified in the
16471 @code{file-systems} field of the operating system declaration
16472 (@pxref{Using the Configuration System}). Each file system is declared
16473 using the @code{file-system} form, like this:
16477 (mount-point "/home")
16478 (device "/dev/sda3")
16482 As usual, some of the fields are mandatory---those shown in the example
16483 above---while others can be omitted. These are described below.
16485 @deftp {Data Type} file-system
16486 Objects of this type represent file systems to be mounted. They
16487 contain the following members:
16491 This is a string specifying the type of the file system---e.g.,
16494 @item @code{mount-point}
16495 This designates the place where the file system is to be mounted.
16497 @item @code{device}
16498 This names the ``source'' of the file system. It can be one of three
16499 things: a file system label, a file system UUID, or the name of a
16500 @file{/dev} node. Labels and UUIDs offer a way to refer to file
16501 systems without having to hard-code their actual device
16502 name@footnote{Note that, while it is tempting to use
16503 @file{/dev/disk/by-uuid} and similar device names to achieve the same
16504 result, this is not recommended: These special device nodes are created
16505 by the udev daemon and may be unavailable at the time the device is
16508 @findex file-system-label
16509 File system labels are created using the @code{file-system-label}
16510 procedure, UUIDs are created using @code{uuid}, and @file{/dev} node are
16511 plain strings. Here's an example of a file system referred to by its
16512 label, as shown by the @command{e2label} command:
16516 (mount-point "/home")
16518 (device (file-system-label "my-home")))
16522 UUIDs are converted from their string representation (as shown by the
16523 @command{tune2fs -l} command) using the @code{uuid} form@footnote{The
16524 @code{uuid} form expects 16-byte UUIDs as defined in
16525 @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the
16526 form of UUID used by the ext2 family of file systems and others, but it
16527 is different from ``UUIDs'' found in FAT file systems, for instance.},
16532 (mount-point "/home")
16534 (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
16537 When the source of a file system is a mapped device (@pxref{Mapped
16538 Devices}), its @code{device} field @emph{must} refer to the mapped
16539 device name---e.g., @file{"/dev/mapper/root-partition"}.
16540 This is required so that
16541 the system knows that mounting the file system depends on having the
16542 corresponding device mapping established.
16544 @item @code{flags} (default: @code{'()})
16545 This is a list of symbols denoting mount flags. Recognized flags
16546 include @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow
16547 access to special files), @code{no-suid} (ignore setuid and setgid
16548 bits), @code{no-atime} (do not update file access times),
16549 @code{no-diratime} (likewise for directories only),
16550 @code{strict-atime} (update file access time), @code{lazy-time} (only
16551 update time on the in-memory version of the file inode),
16552 @code{no-exec} (disallow program execution), and @code{shared} (make the
16554 @xref{Mount-Unmount-Remount,,, libc, The GNU C Library Reference
16555 Manual}, for more information on these flags.
16557 @item @code{options} (default: @code{#f})
16558 This is either @code{#f}, or a string denoting mount options passed to
16559 the file system driver. @xref{Mount-Unmount-Remount,,, libc, The GNU C
16560 Library Reference Manual}, for details.
16562 Run @command{man 8 mount} for options for various file systems, but
16563 beware that what it lists as file-system-independent ``mount options'' are
16564 in fact flags, and belong in the @code{flags} field described above.
16566 The @code{file-system-options->alist} and @code{alist->file-system-options}
16567 procedures from @code{(gnu system file-systems)} can be used to convert
16568 file system options given as an association list to the string
16569 representation, and vice-versa.
16571 @item @code{mount?} (default: @code{#t})
16572 This value indicates whether to automatically mount the file system when
16573 the system is brought up. When set to @code{#f}, the file system gets
16574 an entry in @file{/etc/fstab} (read by the @command{mount} command) but
16575 is not automatically mounted.
16577 @item @code{needed-for-boot?} (default: @code{#f})
16578 This Boolean value indicates whether the file system is needed when
16579 booting. If that is true, then the file system is mounted when the
16580 initial RAM disk (initrd) is loaded. This is always the case, for
16581 instance, for the root file system.
16583 @item @code{check?} (default: @code{#t})
16584 This Boolean indicates whether the file system should be checked for
16585 errors before being mounted. How and when this happens can be further
16586 adjusted with the following options.
16588 @item @code{skip-check-if-clean?} (default: @code{#t})
16589 When true, this Boolean indicates that a file system check triggered
16590 by @code{check?} may exit early if the file system is marked as
16591 ``clean'', meaning that it was previously correctly unmounted and
16592 should not contain errors.
16594 Setting this to false will always force a full consistency check when
16595 @code{check?} is true. This may take a very long time and is not
16596 recommended on healthy systems---in fact, it may reduce reliability!
16598 Conversely, some primitive file systems like @code{fat} do not keep
16599 track of clean shutdowns and will perform a full scan regardless of the
16600 value of this option.
16602 @item @code{repair} (default: @code{'preen})
16603 When @code{check?} finds errors, it can (try to) repair them and
16604 continue booting. This option controls when and how to do so.
16606 If false, try not to modify the file system at all. Checking certain
16607 file systems like @code{jfs} may still write to the device to replay
16608 the journal. No repairs will be attempted.
16610 If @code{#t}, try to repair any errors found and assume ``yes'' to
16611 all questions. This will fix the most errors, but may be risky.
16613 If @code{'preen}, repair only errors that are safe to fix without
16614 human interaction. What that means is left up to the developers of
16615 each file system and may be equivalent to ``none'' or ``all''.
16617 @item @code{create-mount-point?} (default: @code{#f})
16618 When true, the mount point is created if it does not exist yet.
16620 @item @code{mount-may-fail?} (default: @code{#f})
16621 When true, this indicates that mounting this file system can fail but
16622 that should not be considered an error. This is useful in unusual
16623 cases; an example of this is @code{efivarfs}, a file system that can
16624 only be mounted on EFI/UEFI systems.
16626 @item @code{dependencies} (default: @code{'()})
16627 This is a list of @code{<file-system>} or @code{<mapped-device>} objects
16628 representing file systems that must be mounted or mapped devices that
16629 must be opened before (and unmounted or closed after) this one.
16631 As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
16632 a dependency of @file{/sys/fs/cgroup/cpu} and
16633 @file{/sys/fs/cgroup/memory}.
16635 Another example is a file system that depends on a mapped device, for
16636 example for an encrypted partition (@pxref{Mapped Devices}).
16640 @deffn {Scheme Procedure} file-system-label @var{str}
16641 This procedure returns an opaque file system label from @var{str}, a
16645 (file-system-label "home")
16646 @result{} #<file-system-label "home">
16649 File system labels are used to refer to file systems by label rather
16650 than by device name. See above for examples.
16653 The @code{(gnu system file-systems)} exports the following useful
16656 @defvr {Scheme Variable} %base-file-systems
16657 These are essential file systems that are required on normal systems,
16658 such as @code{%pseudo-terminal-file-system} and @code{%immutable-store} (see
16659 below). Operating system declarations should always contain at least
16663 @defvr {Scheme Variable} %pseudo-terminal-file-system
16664 This is the file system to be mounted as @file{/dev/pts}. It supports
16665 @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar
16666 functions (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference
16667 Manual}). Pseudo-terminals are used by terminal emulators such as
16671 @defvr {Scheme Variable} %shared-memory-file-system
16672 This file system is mounted as @file{/dev/shm} and is used to support
16673 memory sharing across processes (@pxref{Memory-mapped I/O,
16674 @code{shm_open},, libc, The GNU C Library Reference Manual}).
16677 @defvr {Scheme Variable} %immutable-store
16678 This file system performs a read-only ``bind mount'' of
16679 @file{/gnu/store}, making it read-only for all the users including
16680 @code{root}. This prevents against accidental modification by software
16681 running as @code{root} or by system administrators.
16683 The daemon itself is still able to write to the store: it remounts it
16684 read-write in its own ``name space.''
16687 @defvr {Scheme Variable} %binary-format-file-system
16688 The @code{binfmt_misc} file system, which allows handling of arbitrary
16689 executable file types to be delegated to user space. This requires the
16690 @code{binfmt.ko} kernel module to be loaded.
16693 @defvr {Scheme Variable} %fuse-control-file-system
16694 The @code{fusectl} file system, which allows unprivileged users to mount
16695 and unmount user-space FUSE file systems. This requires the
16696 @code{fuse.ko} kernel module to be loaded.
16699 The @code{(gnu system uuid)} module provides tools to deal with file
16700 system ``unique identifiers'' (UUIDs).
16702 @deffn {Scheme Procedure} uuid @var{str} [@var{type}]
16703 Return an opaque UUID (unique identifier) object of the given @var{type}
16704 (a symbol) by parsing @var{str} (a string):
16707 (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")
16708 @result{} #<<uuid> type: dce bv: @dots{}>
16710 (uuid "1234-ABCD" 'fat)
16711 @result{} #<<uuid> type: fat bv: @dots{}>
16714 @var{type} may be one of @code{dce}, @code{iso9660}, @code{fat},
16715 @code{ntfs}, or one of the commonly found synonyms for these.
16717 UUIDs are another way to unambiguously refer to file systems in
16718 operating system configuration. See the examples above.
16722 @node Btrfs file system
16723 @subsection Btrfs file system
16725 The Btrfs has special features, such as subvolumes, that merit being
16726 explained in more details. The following section attempts to cover
16727 basic as well as complex uses of a Btrfs file system with the Guix
16730 In its simplest usage, a Btrfs file system can be described, for
16735 (mount-point "/home")
16737 (device (file-system-label "my-home")))
16740 The example below is more complex, as it makes use of a Btrfs
16741 subvolume, named @code{rootfs}. The parent Btrfs file system is labeled
16742 @code{my-btrfs-pool}, and is located on an encrypted device (hence the
16743 dependency on @code{mapped-devices}):
16747 (device (file-system-label "my-btrfs-pool"))
16750 (options "subvol=rootfs")
16751 (dependencies mapped-devices))
16754 Some bootloaders, for example GRUB, only mount a Btrfs partition at its
16755 top level during the early boot, and rely on their configuration to
16756 refer to the correct subvolume path within that top level. The
16757 bootloaders operating in this way typically produce their configuration
16758 on a running system where the Btrfs partitions are already mounted and
16759 where the subvolume information is readily available. As an example,
16760 @command{grub-mkconfig}, the configuration generator command shipped
16761 with GRUB, reads @file{/proc/self/mountinfo} to determine the top-level
16762 path of a subvolume.
16764 The Guix System produces a bootloader configuration using the operating
16765 system configuration as its sole input; it is therefore necessary to
16766 extract the subvolume name on which @file{/gnu/store} lives (if any)
16767 from that operating system configuration. To better illustrate,
16768 consider a subvolume named 'rootfs' which contains the root file system
16769 data. In such situation, the GRUB bootloader would only see the top
16770 level of the root Btrfs partition, e.g.:
16774 ├── rootfs (subvolume directory)
16775 ├── gnu (normal directory)
16776 ├── store (normal directory)
16780 Thus, the subvolume name must be prepended to the @file{/gnu/store} path
16781 of the kernel, initrd binaries and any other files referred to in the
16782 GRUB configuration that must be found during the early boot.
16784 The next example shows a nested hierarchy of subvolumes and
16789 ├── rootfs (subvolume)
16790 ├── gnu (normal directory)
16791 ├── store (subvolume)
16795 This scenario would work without mounting the 'store' subvolume.
16796 Mounting 'rootfs' is sufficient, since the subvolume name matches its
16797 intended mount point in the file system hierarchy. Alternatively, the
16798 'store' subvolume could be referred to by setting the @code{subvol}
16799 option to either @code{/rootfs/gnu/store} or @code{rootfs/gnu/store}.
16801 Finally, a more contrived example of nested subvolumes:
16805 ├── root-snapshots (subvolume)
16806 ├── root-current (subvolume)
16807 ├── guix-store (subvolume)
16811 Here, the 'guix-store' subvolume doesn't match its intended mount point,
16812 so it is necessary to mount it. The subvolume must be fully specified,
16813 by passing its file name to the @code{subvol} option. To illustrate,
16814 the 'guix-store' subvolume could be mounted on @file{/gnu/store} by using
16815 a file system declaration such as:
16819 (device (file-system-label "btrfs-pool-1"))
16820 (mount-point "/gnu/store")
16822 (options "subvol=root-snapshots/root-current/guix-store,\
16823 compress-force=zstd,space_cache=v2"))
16826 @node Mapped Devices
16827 @section Mapped Devices
16829 @cindex device mapping
16830 @cindex mapped devices
16831 The Linux kernel has a notion of @dfn{device mapping}: a block device,
16832 such as a hard disk partition, can be @dfn{mapped} into another device,
16833 usually in @code{/dev/mapper/},
16834 with additional processing over the data that flows through
16835 it@footnote{Note that the GNU@tie{}Hurd makes no difference between the
16836 concept of a ``mapped device'' and that of a file system: both boil down
16837 to @emph{translating} input/output operations made on a file to
16838 operations on its backing store. Thus, the Hurd implements mapped
16839 devices, like file systems, using the generic @dfn{translator} mechanism
16840 (@pxref{Translators,,, hurd, The GNU Hurd Reference Manual}).}. A
16841 typical example is encryption device mapping: all writes to the mapped
16842 device are encrypted, and all reads are deciphered, transparently.
16843 Guix extends this notion by considering any device or set of devices that
16844 are @dfn{transformed} in some way to create a new device; for instance,
16845 RAID devices are obtained by @dfn{assembling} several other devices, such
16846 as hard disks or partitions, into a new one that behaves as one partition.
16848 Mapped devices are declared using the @code{mapped-device} form,
16849 defined as follows; for examples, see below.
16851 @deftp {Data Type} mapped-device
16852 Objects of this type represent device mappings that will be made when
16853 the system boots up.
16857 This is either a string specifying the name of the block device to be mapped,
16858 such as @code{"/dev/sda3"}, or a list of such strings when several devices
16859 need to be assembled for creating a new one. In case of LVM this is a
16860 string specifying name of the volume group to be mapped.
16863 This string specifies the name of the resulting mapped device. For
16864 kernel mappers such as encrypted devices of type @code{luks-device-mapping},
16865 specifying @code{"my-partition"} leads to the creation of
16866 the @code{"/dev/mapper/my-partition"} device.
16867 For RAID devices of type @code{raid-device-mapping}, the full device name
16868 such as @code{"/dev/md0"} needs to be given.
16869 LVM logical volumes of type @code{lvm-device-mapping} need to
16870 be specified as @code{"VGNAME-LVNAME"}.
16873 This list of strings specifies names of the resulting mapped devices in case
16874 there are several. The format is identical to @var{target}.
16877 This must be a @code{mapped-device-kind} object, which specifies how
16878 @var{source} is mapped to @var{target}.
16882 @defvr {Scheme Variable} luks-device-mapping
16883 This defines LUKS block device encryption using the @command{cryptsetup}
16884 command from the package with the same name. It relies on the
16885 @code{dm-crypt} Linux kernel module.
16888 @defvr {Scheme Variable} raid-device-mapping
16889 This defines a RAID device, which is assembled using the @code{mdadm}
16890 command from the package with the same name. It requires a Linux kernel
16891 module for the appropriate RAID level to be loaded, such as @code{raid456}
16892 for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
16895 @cindex LVM, logical volume manager
16896 @defvr {Scheme Variable} lvm-device-mapping
16897 This defines one or more logical volumes for the Linux
16898 @uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.
16899 The volume group is activated by the @command{vgchange} command from the
16900 @code{lvm2} package.
16903 @cindex disk encryption
16905 The following example specifies a mapping from @file{/dev/sda3} to
16906 @file{/dev/mapper/home} using LUKS---the
16907 @url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a
16908 standard mechanism for disk encryption.
16909 The @file{/dev/mapper/home}
16910 device can then be used as the @code{device} of a @code{file-system}
16911 declaration (@pxref{File Systems}).
16915 (source "/dev/sda3")
16917 (type luks-device-mapping))
16920 Alternatively, to become independent of device numbering, one may obtain
16921 the LUKS UUID (@dfn{unique identifier}) of the source device by a
16925 cryptsetup luksUUID /dev/sda3
16928 and use it as follows:
16932 (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
16934 (type luks-device-mapping))
16937 @cindex swap encryption
16938 It is also desirable to encrypt swap space, since swap space may contain
16939 sensitive data. One way to accomplish that is to use a swap file in a
16940 file system on a device mapped via LUKS encryption. In this way, the
16941 swap file is encrypted because the entire device is encrypted.
16942 @xref{Swap Space}, or @xref{Preparing for Installation,,Disk
16943 Partitioning}, for an example.
16945 A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
16946 may be declared as follows:
16950 (source (list "/dev/sda1" "/dev/sdb1"))
16951 (target "/dev/md0")
16952 (type raid-device-mapping))
16955 The @file{/dev/md0} device can then be used as the @code{device} of a
16956 @code{file-system} declaration (@pxref{File Systems}).
16957 Note that the RAID level need not be given; it is chosen during the
16958 initial creation and formatting of the RAID device and is determined
16959 automatically later.
16961 LVM logical volumes ``alpha'' and ``beta'' from volume group ``vg0'' can
16962 be declared as follows:
16967 (targets (list "vg0-alpha" "vg0-beta"))
16968 (type lvm-device-mapping))
16971 Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can
16972 then be used as the @code{device} of a @code{file-system} declaration
16973 (@pxref{File Systems}).
16976 @section Swap Space
16979 Swap space, as it is commonly called, is a disk area specifically
16980 designated for paging: the process in charge of memory management
16981 (the Linux kernel or Hurd's default pager) can decide that some memory
16982 pages stored in RAM which belong to a running program but are unused
16983 should be stored on disk instead. It unloads those from the RAM,
16984 freeing up precious fast memory, and writes them to the swap space. If
16985 the program tries to access that very page, the memory management
16986 process loads it back into memory for the program to use.
16988 A common misconception about swap is that it is only useful when small
16989 amounts of RAM are available to the system. However, it should be noted
16990 that kernels often use all available RAM for disk access caching to make
16991 I/O faster, and thus paging out unused portions of program memory will
16992 expand the RAM available for such caching.
16994 For a more detailed description of how memory is managed from the
16995 viewpoint of a monolithic kernel, @xref{Memory
16996 Concepts,,, libc, The GNU C Library Reference Manual}.
16998 The Linux kernel has support for swap partitions and swap files: the
16999 former uses a whole disk partition for paging, whereas the second uses a
17000 file on a file system for that (the file system driver needs to support
17001 it). On a comparable setup, both have the same performance, so one
17002 should consider ease of use when deciding between them. Partitions are
17003 ``simpler'' and do not need file system support, but need to be
17004 allocated at disk formatting time (logical volumes notwithstanding),
17005 whereas files can be allocated and deallocated at any time.
17007 Note that swap space is not zeroed on shutdown, so sensitive data (such
17008 as passwords) may linger on it if it was paged out. As such, you should
17009 consider having your swap reside on an encrypted device (@pxref{Mapped
17012 @deftp {Data Type} swap-space
17013 Objects of this type represent swap spaces. They contain the following
17017 @item @code{target}
17018 The device or file to use, either a UUID, a @code{file-system-label} or
17019 a string, as in the definition of a @code{file-system} (@pxref{File
17022 @item @code{dependencies} (default: @code{'()})
17023 A list of @code{file-system} or @code{mapped-device} objects, upon which
17024 the availability of the space depends. Note that just like for
17025 @code{file-system} objects, dependencies which are needed for boot and
17026 mounted in early userspace are not managed by the Shepherd, and so
17027 automatically filtered out for you.
17029 @item @code{priority} (default: @code{#f})
17030 Only supported by the Linux kernel. Either @code{#f} to disable swap
17031 priority, or an integer between 0 and 32767. The kernel will first use
17032 swap spaces of higher priority when paging, and use same priority spaces
17033 on a round-robin basis. The kernel will use swap spaces without a set
17034 priority after prioritized spaces, and in the order that they appeared in
17037 @item @code{discard?} (default: @code{#f})
17038 Only supported by the Linux kernel. When true, the kernel will notify
17039 the disk controller of discarded pages, for example with the TRIM
17040 operation on Solid State Drives.
17045 Here are some examples:
17048 (swap-space (target (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
17051 Use the swap partition with the given UUID@. You can learn the UUID of a
17052 Linux swap partition by running @command{swaplabel @var{device}}, where
17053 @var{device} is the @file{/dev} file name of that partition.
17057 (target (file-system-label "swap"))
17058 (dependencies mapped-devices))
17061 Use the partition with label @code{swap}, which can be found after all
17062 the @var{mapped-devices} mapped devices have been opened. Again, the
17063 @command{swaplabel} command allows you to view and change the label of a
17064 Linux swap partition.
17066 Here's a more involved example with the corresponding @code{file-systems} part
17067 of an @code{operating-system} declaration.
17072 (device (file-system-label "root"))
17076 (device (file-system-label "btrfs"))
17077 (mount-point "/btrfs")
17083 (target "/btrfs/swapfile")
17084 (dependencies (filter (file-system-mount-point-predicate "/btrfs")
17088 Use the file @file{/btrfs/swapfile} as swap space, which depends on the
17089 file system mounted at @file{/btrfs}. Note how we use Guile's filter to
17090 select the file system in an elegant fashion!
17092 @node User Accounts
17093 @section User Accounts
17097 @cindex user accounts
17098 User accounts and groups are entirely managed through the
17099 @code{operating-system} declaration. They are specified with the
17100 @code{user-account} and @code{user-group} forms:
17106 (supplementary-groups '("wheel" ;allow use of sudo, etc.
17107 "audio" ;sound card
17108 "video" ;video devices such as webcams
17109 "cdrom")) ;the good ol' CD-ROM
17110 (comment "Bob's sister"))
17113 Here's a user account that uses a different shell and a custom home
17114 directory (the default would be @file{"/home/bob"}):
17120 (comment "Alice's bro")
17121 (shell (file-append zsh "/bin/zsh"))
17122 (home-directory "/home/robert"))
17125 When booting or upon completion of @command{guix system reconfigure},
17126 the system ensures that only the user accounts and groups specified in
17127 the @code{operating-system} declaration exist, and with the specified
17128 properties. Thus, account or group creations or modifications made by
17129 directly invoking commands such as @command{useradd} are lost upon
17130 reconfiguration or reboot. This ensures that the system remains exactly
17133 @deftp {Data Type} user-account
17134 Objects of this type represent user accounts. The following members may
17139 The name of the user account.
17143 This is the name (a string) or identifier (a number) of the user group
17144 this account belongs to.
17146 @item @code{supplementary-groups} (default: @code{'()})
17147 Optionally, this can be defined as a list of group names that this
17148 account belongs to.
17150 @item @code{uid} (default: @code{#f})
17151 This is the user ID for this account (a number), or @code{#f}. In the
17152 latter case, a number is automatically chosen by the system when the
17153 account is created.
17155 @item @code{comment} (default: @code{""})
17156 A comment about the account, such as the account owner's full name.
17158 Note that, for non-system accounts, users are free to change their real
17159 name as it appears in @file{/etc/passwd} using the @command{chfn}
17160 command. When they do, their choice prevails over the system
17161 administrator's choice; reconfiguring does @emph{not} change their name.
17163 @item @code{home-directory}
17164 This is the name of the home directory for the account.
17166 @item @code{create-home-directory?} (default: @code{#t})
17167 Indicates whether the home directory of this account should be created
17168 if it does not exist yet.
17170 @item @code{shell} (default: Bash)
17171 This is a G-expression denoting the file name of a program to be used as
17172 the shell (@pxref{G-Expressions}). For example, you would refer to the
17173 Bash executable like this:
17176 (file-append bash "/bin/bash")
17180 ... and to the Zsh executable like that:
17183 (file-append zsh "/bin/zsh")
17186 @item @code{system?} (default: @code{#f})
17187 This Boolean value indicates whether the account is a ``system''
17188 account. System accounts are sometimes treated specially; for instance,
17189 graphical login managers do not list them.
17191 @anchor{user-account-password}
17192 @cindex password, for user accounts
17193 @item @code{password} (default: @code{#f})
17194 You would normally leave this field to @code{#f}, initialize user
17195 passwords as @code{root} with the @command{passwd} command, and then let
17196 users change it with @command{passwd}. Passwords set with
17197 @command{passwd} are of course preserved across reboot and
17200 If you @emph{do} want to set an initial password for an account, then
17201 this field must contain the encrypted password, as a string. You can use the
17202 @code{crypt} procedure for this purpose:
17209 ;; Specify a SHA-512-hashed initial password.
17210 (password (crypt "InitialPassword!" "$6$abc")))
17214 The hash of this initial password will be available in a file in
17215 @file{/gnu/store}, readable by all the users, so this method must be used with
17219 @xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for
17220 more information on password encryption, and @ref{Encryption,,, guile, GNU
17221 Guile Reference Manual}, for information on Guile's @code{crypt} procedure.
17227 User group declarations are even simpler:
17230 (user-group (name "students"))
17233 @deftp {Data Type} user-group
17234 This type is for, well, user groups. There are just a few fields:
17238 The name of the group.
17240 @item @code{id} (default: @code{#f})
17241 The group identifier (a number). If @code{#f}, a new number is
17242 automatically allocated when the group is created.
17244 @item @code{system?} (default: @code{#f})
17245 This Boolean value indicates whether the group is a ``system'' group.
17246 System groups have low numerical IDs.
17248 @item @code{password} (default: @code{#f})
17249 What, user groups can have a password? Well, apparently yes. Unless
17250 @code{#f}, this field specifies the password of the group.
17255 For convenience, a variable lists all the basic user groups one may
17258 @defvr {Scheme Variable} %base-groups
17259 This is the list of basic user groups that users and/or packages expect
17260 to be present on the system. This includes groups such as ``root'',
17261 ``wheel'', and ``users'', as well as groups used to control access to
17262 specific devices such as ``audio'', ``disk'', and ``cdrom''.
17265 @defvr {Scheme Variable} %base-user-accounts
17266 This is the list of basic system accounts that programs may expect to
17267 find on a GNU/Linux system, such as the ``nobody'' account.
17269 Note that the ``root'' account is not included here. It is a
17270 special-case and is automatically added whether or not it is specified.
17273 @node Keyboard Layout
17274 @section Keyboard Layout
17276 @cindex keyboard layout
17278 To specify what each key of your keyboard does, you need to tell the operating
17279 system what @dfn{keyboard layout} you want to use. The default, when nothing
17280 is specified, is the US English QWERTY layout for 105-key PC keyboards.
17281 However, German speakers will usually prefer the German QWERTZ layout, French
17282 speakers will want the AZERTY layout, and so on; hackers might prefer Dvorak
17283 or bépo, and they might even want to further customize the effect of some of
17284 the keys. This section explains how to get that done.
17286 @cindex keyboard layout, definition
17287 There are three components that will want to know about your keyboard layout:
17291 The @emph{bootloader} may want to know what keyboard layout you want to use
17292 (@pxref{Bootloader Configuration, @code{keyboard-layout}}). This is useful if
17293 you want, for instance, to make sure that you can type the passphrase of your
17294 encrypted root partition using the right layout.
17297 The @emph{operating system kernel}, Linux, will need that so that the console
17298 is properly configured (@pxref{operating-system Reference,
17299 @code{keyboard-layout}}).
17302 The @emph{graphical display server}, usually Xorg, also has its own idea of
17303 the keyboard layout (@pxref{X Window, @code{keyboard-layout}}).
17306 Guix allows you to configure all three separately but, fortunately, it allows
17307 you to share the same keyboard layout for all three components.
17309 @cindex XKB, keyboard layouts
17310 Keyboard layouts are represented by records created by the
17311 @code{keyboard-layout} procedure of @code{(gnu system keyboard)}. Following
17312 the X Keyboard extension (XKB), each layout has four attributes: a name (often
17313 a language code such as ``fi'' for Finnish or ``jp'' for Japanese), an
17314 optional variant name, an optional keyboard model name, and a possibly empty
17315 list of additional options. In most cases the layout name is all you care
17318 @deffn {Scheme Procedure} keyboard-layout @var{name} [@var{variant}] @
17319 [#:model] [#:options '()]
17320 Return a new keyboard layout with the given @var{name} and @var{variant}.
17322 @var{name} must be a string such as @code{"fr"}; @var{variant} must be a
17323 string such as @code{"bepo"} or @code{"nodeadkeys"}. See the
17324 @code{xkeyboard-config} package for valid options.
17327 Here are a few examples:
17330 ;; The German QWERTZ layout. Here we assume a standard
17331 ;; "pc105" keyboard model.
17332 (keyboard-layout "de")
17334 ;; The bépo variant of the French layout.
17335 (keyboard-layout "fr" "bepo")
17337 ;; The Catalan layout.
17338 (keyboard-layout "es" "cat")
17340 ;; Arabic layout with "Alt-Shift" to switch to US layout.
17341 (keyboard-layout "ar,us" #:options '("grp:alt_shift_toggle"))
17343 ;; The Latin American Spanish layout. In addition, the
17344 ;; "Caps Lock" key is used as an additional "Ctrl" key,
17345 ;; and the "Menu" key is used as a "Compose" key to enter
17346 ;; accented letters.
17347 (keyboard-layout "latam"
17348 #:options '("ctrl:nocaps" "compose:menu"))
17350 ;; The Russian layout for a ThinkPad keyboard.
17351 (keyboard-layout "ru" #:model "thinkpad")
17353 ;; The "US international" layout, which is the US layout plus
17354 ;; dead keys to enter accented characters. This is for an
17355 ;; Apple MacBook keyboard.
17356 (keyboard-layout "us" "intl" #:model "macbook78")
17359 See the @file{share/X11/xkb} directory of the @code{xkeyboard-config} package
17360 for a complete list of supported layouts, variants, and models.
17362 @cindex keyboard layout, configuration
17363 Let's say you want your system to use the Turkish keyboard layout throughout
17364 your system---bootloader, console, and Xorg. Here's what your system
17365 configuration would look like:
17367 @findex set-xorg-configuration
17369 ;; Using the Turkish layout for the bootloader, the console,
17374 (keyboard-layout (keyboard-layout "tr")) ;for the console
17375 (bootloader (bootloader-configuration
17376 (bootloader grub-efi-bootloader)
17377 (targets '("/boot/efi"))
17378 (keyboard-layout keyboard-layout))) ;for GRUB
17379 (services (cons (set-xorg-configuration
17380 (xorg-configuration ;for Xorg
17381 (keyboard-layout keyboard-layout)))
17382 %desktop-services)))
17385 In the example above, for GRUB and for Xorg, we just refer to the
17386 @code{keyboard-layout} field defined above, but we could just as well refer to
17387 a different layout. The @code{set-xorg-configuration} procedure communicates
17388 the desired Xorg configuration to the graphical log-in manager, by default
17391 We've discussed how to specify the @emph{default} keyboard layout of your
17392 system when it starts, but you can also adjust it at run time:
17396 If you're using GNOME, its settings panel has a ``Region & Language'' entry
17397 where you can select one or more keyboard layouts.
17400 Under Xorg, the @command{setxkbmap} command (from the same-named package)
17401 allows you to change the current layout. For example, this is how you would
17402 change the layout to US Dvorak:
17405 setxkbmap us dvorak
17409 The @code{loadkeys} command changes the keyboard layout in effect in the Linux
17410 console. However, note that @code{loadkeys} does @emph{not} use the XKB
17411 keyboard layout categorization described above. The command below loads the
17412 French bépo layout:
17423 A @dfn{locale} defines cultural conventions for a particular language
17424 and region of the world (@pxref{Locales,,, libc, The GNU C Library
17425 Reference Manual}). Each locale has a name that typically has the form
17426 @code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
17427 @code{fr_LU.utf8} designates the locale for the French language, with
17428 cultural conventions from Luxembourg, and using the UTF-8 encoding.
17430 @cindex locale definition
17431 Usually, you will want to specify the default locale for the machine
17432 using the @code{locale} field of the @code{operating-system} declaration
17433 (@pxref{operating-system Reference, @code{locale}}).
17435 The selected locale is automatically added to the @dfn{locale
17436 definitions} known to the system if needed, with its codeset inferred
17437 from its name---e.g., @code{bo_CN.utf8} will be assumed to use the
17438 @code{UTF-8} codeset. Additional locale definitions can be specified in
17439 the @code{locale-definitions} slot of @code{operating-system}---this is
17440 useful, for instance, if the codeset could not be inferred from the
17441 locale name. The default set of locale definitions includes some widely
17442 used locales, but not all the available locales, in order to save space.
17444 For instance, to add the North Frisian locale for Germany, the value of
17448 (cons (locale-definition
17449 (name "fy_DE.utf8") (source "fy_DE"))
17450 %default-locale-definitions)
17453 Likewise, to save space, one might want @code{locale-definitions} to
17454 list only the locales that are actually used, as in:
17457 (list (locale-definition
17458 (name "ja_JP.eucjp") (source "ja_JP")
17459 (charset "EUC-JP")))
17463 The compiled locale definitions are available at
17464 @file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc
17465 version, which is the default location where the GNU@tie{}libc provided
17466 by Guix looks for locale data. This can be overridden using the
17467 @env{LOCPATH} environment variable (@pxref{locales-and-locpath,
17468 @env{LOCPATH} and locale packages}).
17470 The @code{locale-definition} form is provided by the @code{(gnu system
17471 locale)} module. Details are given below.
17473 @deftp {Data Type} locale-definition
17474 This is the data type of a locale definition.
17479 The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
17480 Reference Manual}, for more information on locale names.
17482 @item @code{source}
17483 The name of the source for that locale. This is typically the
17484 @code{@var{language}_@var{territory}} part of the locale name.
17486 @item @code{charset} (default: @code{"UTF-8"})
17487 The ``character set'' or ``code set'' for that locale,
17488 @uref{https://www.iana.org/assignments/character-sets, as defined by
17494 @defvr {Scheme Variable} %default-locale-definitions
17495 A list of commonly used UTF-8 locales, used as the default
17496 value of the @code{locale-definitions} field of @code{operating-system}
17499 @cindex locale name
17500 @cindex normalized codeset in locale names
17501 These locale definitions use the @dfn{normalized codeset} for the part
17502 that follows the dot in the name (@pxref{Using gettextized software,
17503 normalized codeset,, libc, The GNU C Library Reference Manual}). So for
17504 instance it has @code{uk_UA.utf8} but @emph{not}, say,
17505 @code{uk_UA.UTF-8}.
17508 @subsection Locale Data Compatibility Considerations
17510 @cindex incompatibility, of locale data
17511 @code{operating-system} declarations provide a @code{locale-libcs} field
17512 to specify the GNU@tie{}libc packages that are used to compile locale
17513 declarations (@pxref{operating-system Reference}). ``Why would I
17514 care?'', you may ask. Well, it turns out that the binary format of
17515 locale data is occasionally incompatible from one libc version to
17518 @c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
17519 @c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
17520 For instance, a program linked against libc version 2.21 is unable to
17521 read locale data produced with libc 2.22; worse, that program
17522 @emph{aborts} instead of simply ignoring the incompatible locale
17523 data@footnote{Versions 2.23 and later of GNU@tie{}libc will simply skip
17524 the incompatible locale data, which is already an improvement.}.
17525 Similarly, a program linked against libc 2.22 can read most, but not
17526 all, of the locale data from libc 2.21 (specifically, @env{LC_COLLATE}
17527 data is incompatible); thus calls to @code{setlocale} may fail, but
17528 programs will not abort.
17530 The ``problem'' with Guix is that users have a lot of freedom: They can
17531 choose whether and when to upgrade software in their profiles, and might
17532 be using a libc version different from the one the system administrator
17533 used to build the system-wide locale data.
17535 Fortunately, unprivileged users can also install their own locale data
17536 and define @env{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
17537 @env{GUIX_LOCPATH} and locale packages}).
17539 Still, it is best if the system-wide locale data at
17540 @file{/run/current-system/locale} is built for all the libc versions
17541 actually in use on the system, so that all the programs can access
17542 it---this is especially crucial on a multi-user system. To do that, the
17543 administrator can specify several libc packages in the
17544 @code{locale-libcs} field of @code{operating-system}:
17547 (use-package-modules base)
17551 (locale-libcs (list glibc-2.21 (canonical-package glibc))))
17554 This example would lead to a system containing locale definitions for
17555 both libc 2.21 and the current version of libc in
17556 @file{/run/current-system/locale}.
17562 @cindex system services
17563 An important part of preparing an @code{operating-system} declaration is
17564 listing @dfn{system services} and their configuration (@pxref{Using the
17565 Configuration System}). System services are typically daemons launched
17566 when the system boots, or other actions needed at that time---e.g.,
17567 configuring network access.
17569 Guix has a broad definition of ``service'' (@pxref{Service
17570 Composition}), but many services are managed by the GNU@tie{}Shepherd
17571 (@pxref{Shepherd Services}). On a running system, the @command{herd}
17572 command allows you to list the available services, show their status,
17573 start and stop them, or do other specific operations (@pxref{Jump
17574 Start,,, shepherd, The GNU Shepherd Manual}). For example:
17580 The above command, run as @code{root}, lists the currently defined
17581 services. The @command{herd doc} command shows a synopsis of the given
17582 service and its associated actions:
17586 Run libc's name service cache daemon (nscd).
17588 # herd doc nscd action invalidate
17589 invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
17592 The @command{start}, @command{stop}, and @command{restart} sub-commands
17593 have the effect you would expect. For instance, the commands below stop
17594 the nscd service and restart the Xorg display server:
17598 Service nscd has been stopped.
17599 # herd restart xorg-server
17600 Service xorg-server has been stopped.
17601 Service xorg-server has been started.
17604 The following sections document the available services, starting with
17605 the core services, that may be used in an @code{operating-system}
17609 * Base Services:: Essential system services.
17610 * Scheduled Job Execution:: The mcron service.
17611 * Log Rotation:: The rottlog service.
17612 * Networking Setup:: Setting up network interfaces.
17613 * Networking Services:: Firewall, SSH daemon, etc.
17614 * Unattended Upgrades:: Automated system upgrades.
17615 * X Window:: Graphical display.
17616 * Printing Services:: Local and remote printer support.
17617 * Desktop Services:: D-Bus and desktop services.
17618 * Sound Services:: ALSA and Pulseaudio services.
17619 * Database Services:: SQL databases, key-value stores, etc.
17620 * Mail Services:: IMAP, POP3, SMTP, and all that.
17621 * Messaging Services:: Messaging services.
17622 * Telephony Services:: Telephony services.
17623 * File-Sharing Services:: File-sharing services.
17624 * Monitoring Services:: Monitoring services.
17625 * Kerberos Services:: Kerberos services.
17626 * LDAP Services:: LDAP services.
17627 * Web Services:: Web servers.
17628 * Certificate Services:: TLS certificates via Let's Encrypt.
17629 * DNS Services:: DNS daemons.
17630 * VNC Services:: VNC daemons.
17631 * VPN Services:: VPN daemons.
17632 * Network File System:: NFS related services.
17633 * Samba Services:: Samba services.
17634 * Continuous Integration:: Cuirass and Laminar services.
17635 * Power Management Services:: Extending battery life.
17636 * Audio Services:: The MPD.
17637 * Virtualization Services:: Virtualization services.
17638 * Version Control Services:: Providing remote access to Git repositories.
17639 * Game Services:: Game servers.
17640 * PAM Mount Service:: Service to mount volumes when logging in.
17641 * Guix Services:: Services relating specifically to Guix.
17642 * Linux Services:: Services tied to the Linux kernel.
17643 * Hurd Services:: Services specific for a Hurd System.
17644 * Miscellaneous Services:: Other services.
17647 @node Base Services
17648 @subsection Base Services
17650 The @code{(gnu services base)} module provides definitions for the basic
17651 services that one expects from the system. The services exported by
17652 this module are listed below.
17654 @defvr {Scheme Variable} %base-services
17655 This variable contains a list of basic services (@pxref{Service Types
17656 and Services}, for more information on service objects) one would
17657 expect from the system: a login service (mingetty) on each tty, syslogd,
17658 the libc name service cache daemon (nscd), the udev device manager, and
17661 This is the default value of the @code{services} field of
17662 @code{operating-system} declarations. Usually, when customizing a
17663 system, you will want to append services to @code{%base-services}, like
17667 (append (list (service avahi-service-type)
17668 (service openssh-service-type))
17673 @defvr {Scheme Variable} special-files-service-type
17674 This is the service that sets up ``special files'' such as
17675 @file{/bin/sh}; an instance of it is part of @code{%base-services}.
17677 The value associated with @code{special-files-service-type} services
17678 must be a list of tuples where the first element is the ``special file''
17679 and the second element is its target. By default it is:
17681 @cindex @file{/bin/sh}
17682 @cindex @file{sh}, in @file{/bin}
17684 `(("/bin/sh" ,(file-append bash "/bin/sh")))
17687 @cindex @file{/usr/bin/env}
17688 @cindex @file{env}, in @file{/usr/bin}
17689 If you want to add, say, @code{/usr/bin/env} to your system, you can
17693 `(("/bin/sh" ,(file-append bash "/bin/sh"))
17694 ("/usr/bin/env" ,(file-append coreutils "/bin/env")))
17697 Since this is part of @code{%base-services}, you can use
17698 @code{modify-services} to customize the set of special files
17699 (@pxref{Service Reference, @code{modify-services}}). But the simple way
17700 to add a special file is @i{via} the @code{extra-special-file} procedure
17704 @deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
17705 Use @var{target} as the ``special file'' @var{file}.
17707 For example, adding the following lines to the @code{services} field of
17708 your operating system declaration leads to a @file{/usr/bin/env}
17712 (extra-special-file "/usr/bin/env"
17713 (file-append coreutils "/bin/env"))
17717 @deffn {Scheme Procedure} host-name-service @var{name}
17718 Return a service that sets the host name to @var{name}.
17721 @defvr {Scheme Variable} console-font-service-type
17722 Install the given fonts on the specified ttys (fonts are per
17723 virtual console on the kernel Linux). The value of this service is a list of
17724 tty/font pairs. The font can be the name of a font provided by the @code{kbd}
17725 package or any valid argument to @command{setfont}, as in this example:
17728 `(("tty1" . "LatGrkCyr-8x16")
17729 ("tty2" . ,(file-append
17731 "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
17732 ("tty3" . ,(file-append
17734 "/share/consolefonts/ter-132n"))) ; for HDPI
17738 @deffn {Scheme Procedure} login-service @var{config}
17739 Return a service to run login according to @var{config}, a
17740 @code{<login-configuration>} object, which specifies the message of the day,
17741 among other things.
17744 @deftp {Data Type} login-configuration
17745 This is the data type representing the configuration of login.
17750 @cindex message of the day
17751 A file-like object containing the ``message of the day''.
17753 @item @code{allow-empty-passwords?} (default: @code{#t})
17754 Allow empty passwords by default so that first-time users can log in when
17755 the 'root' account has just been created.
17760 @deffn {Scheme Procedure} mingetty-service @var{config}
17761 Return a service to run mingetty according to @var{config}, a
17762 @code{<mingetty-configuration>} object, which specifies the tty to run, among
17766 @deftp {Data Type} mingetty-configuration
17767 This is the data type representing the configuration of Mingetty, which
17768 provides the default implementation of virtual console log-in.
17773 The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
17775 @item @code{auto-login} (default: @code{#f})
17776 When true, this field must be a string denoting the user name under
17777 which the system automatically logs in. When it is @code{#f}, a
17778 user name and password must be entered to log in.
17780 @item @code{login-program} (default: @code{#f})
17781 This must be either @code{#f}, in which case the default log-in program
17782 is used (@command{login} from the Shadow tool suite), or a gexp denoting
17783 the name of the log-in program.
17785 @item @code{login-pause?} (default: @code{#f})
17786 When set to @code{#t} in conjunction with @var{auto-login}, the user
17787 will have to press a key before the log-in shell is launched.
17789 @item @code{clear-on-logout?} (default: @code{#t})
17790 When set to @code{#t}, the screen will be cleared after logout.
17792 @item @code{mingetty} (default: @var{mingetty})
17793 The Mingetty package to use.
17798 @deffn {Scheme Procedure} agetty-service @var{config}
17799 Return a service to run agetty according to @var{config}, an
17800 @code{<agetty-configuration>} object, which specifies the tty to run,
17801 among other things.
17804 @deftp {Data Type} agetty-configuration
17805 This is the data type representing the configuration of agetty, which
17806 implements virtual and serial console log-in. See the @code{agetty(8)}
17807 man page for more information.
17812 The name of the console this agetty runs on, as a string---e.g.,
17813 @code{"ttyS0"}. This argument is optional, it will default to
17814 a reasonable default serial port used by the kernel Linux.
17816 For this, if there is a value for an option @code{agetty.tty} in the kernel
17817 command line, agetty will extract the device name of the serial port
17818 from it and use that.
17820 If not and if there is a value for an option @code{console} with a tty in
17821 the Linux command line, agetty will extract the device name of the
17822 serial port from it and use that.
17824 In both cases, agetty will leave the other serial device settings
17825 (baud rate etc.)@: alone---in the hope that Linux pinned them to the
17828 @item @code{baud-rate} (default: @code{#f})
17829 A string containing a comma-separated list of one or more baud rates, in
17832 @item @code{term} (default: @code{#f})
17833 A string containing the value used for the @env{TERM} environment
17836 @item @code{eight-bits?} (default: @code{#f})
17837 When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection is
17840 @item @code{auto-login} (default: @code{#f})
17841 When passed a login name, as a string, the specified user will be logged
17842 in automatically without prompting for their login name or password.
17844 @item @code{no-reset?} (default: @code{#f})
17845 When @code{#t}, don't reset terminal cflags (control modes).
17847 @item @code{host} (default: @code{#f})
17848 This accepts a string containing the ``login_host'', which will be written
17849 into the @file{/var/run/utmpx} file.
17851 @item @code{remote?} (default: @code{#f})
17852 When set to @code{#t} in conjunction with @var{host}, this will add an
17853 @code{-r} fakehost option to the command line of the login program
17854 specified in @var{login-program}.
17856 @item @code{flow-control?} (default: @code{#f})
17857 When set to @code{#t}, enable hardware (RTS/CTS) flow control.
17859 @item @code{no-issue?} (default: @code{#f})
17860 When set to @code{#t}, the contents of the @file{/etc/issue} file will
17861 not be displayed before presenting the login prompt.
17863 @item @code{init-string} (default: @code{#f})
17864 This accepts a string that will be sent to the tty or modem before
17865 sending anything else. It can be used to initialize a modem.
17867 @item @code{no-clear?} (default: @code{#f})
17868 When set to @code{#t}, agetty will not clear the screen before showing
17871 @item @code{login-program} (default: (file-append shadow "/bin/login"))
17872 This must be either a gexp denoting the name of a log-in program, or
17873 unset, in which case the default value is the @command{login} from the
17876 @item @code{local-line} (default: @code{#f})
17877 Control the CLOCAL line flag. This accepts one of three symbols as
17878 arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f},
17879 the default value chosen by agetty is @code{'auto}.
17881 @item @code{extract-baud?} (default: @code{#f})
17882 When set to @code{#t}, instruct agetty to try to extract the baud rate
17883 from the status messages produced by certain types of modems.
17885 @item @code{skip-login?} (default: @code{#f})
17886 When set to @code{#t}, do not prompt the user for a login name. This
17887 can be used with @var{login-program} field to use non-standard login
17890 @item @code{no-newline?} (default: @code{#f})
17891 When set to @code{#t}, do not print a newline before printing the
17892 @file{/etc/issue} file.
17894 @c Is this dangerous only when used with login-program, or always?
17895 @item @code{login-options} (default: @code{#f})
17896 This option accepts a string containing options that are passed to the
17897 login program. When used with the @var{login-program}, be aware that a
17898 malicious user could try to enter a login name containing embedded
17899 options that could be parsed by the login program.
17901 @item @code{login-pause} (default: @code{#f})
17902 When set to @code{#t}, wait for any key before showing the login prompt.
17903 This can be used in conjunction with @var{auto-login} to save memory by
17904 lazily spawning shells.
17906 @item @code{chroot} (default: @code{#f})
17907 Change root to the specified directory. This option accepts a directory
17910 @item @code{hangup?} (default: @code{#f})
17911 Use the Linux system call @code{vhangup} to do a virtual hangup of the
17912 specified terminal.
17914 @item @code{keep-baud?} (default: @code{#f})
17915 When set to @code{#t}, try to keep the existing baud rate. The baud
17916 rates from @var{baud-rate} are used when agetty receives a @key{BREAK}
17919 @item @code{timeout} (default: @code{#f})
17920 When set to an integer value, terminate if no user name could be read
17921 within @var{timeout} seconds.
17923 @item @code{detect-case?} (default: @code{#f})
17924 When set to @code{#t}, turn on support for detecting an uppercase-only
17925 terminal. This setting will detect a login name containing only
17926 uppercase letters as indicating an uppercase-only terminal and turn on
17927 some upper-to-lower case conversions. Note that this will not support
17928 Unicode characters.
17930 @item @code{wait-cr?} (default: @code{#f})
17931 When set to @code{#t}, wait for the user or modem to send a
17932 carriage-return or linefeed character before displaying
17933 @file{/etc/issue} or login prompt. This is typically used with the
17934 @var{init-string} option.
17936 @item @code{no-hints?} (default: @code{#f})
17937 When set to @code{#t}, do not print hints about Num, Caps, and Scroll
17940 @item @code{no-hostname?} (default: @code{#f})
17941 By default, the hostname is printed. When this option is set to
17942 @code{#t}, no hostname will be shown at all.
17944 @item @code{long-hostname?} (default: @code{#f})
17945 By default, the hostname is only printed until the first dot. When this
17946 option is set to @code{#t}, the fully qualified hostname by
17947 @code{gethostname} or @code{getaddrinfo} is shown.
17949 @item @code{erase-characters} (default: @code{#f})
17950 This option accepts a string of additional characters that should be
17951 interpreted as backspace when the user types their login name.
17953 @item @code{kill-characters} (default: @code{#f})
17954 This option accepts a string that should be interpreted to mean ``ignore
17955 all previous characters'' (also called a ``kill'' character) when the user
17956 types their login name.
17958 @item @code{chdir} (default: @code{#f})
17959 This option accepts, as a string, a directory path that will be changed
17962 @item @code{delay} (default: @code{#f})
17963 This options accepts, as an integer, the number of seconds to sleep
17964 before opening the tty and displaying the login prompt.
17966 @item @code{nice} (default: @code{#f})
17967 This option accepts, as an integer, the nice value with which to run the
17968 @command{login} program.
17970 @item @code{extra-options} (default: @code{'()})
17971 This option provides an ``escape hatch'' for the user to provide arbitrary
17972 command-line arguments to @command{agetty} as a list of strings.
17974 @item @code{shepherd-requirement} (default: @code{'()})
17975 The option can be used to provides extra shepherd requirements (for example
17976 @code{'syslogd}) to the respective @code{'term-}* shepherd service.
17981 @deffn {Scheme Procedure} kmscon-service-type @var{config}
17982 Return a service to run @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon}
17983 according to @var{config}, a @code{<kmscon-configuration>} object, which
17984 specifies the tty to run, among other things.
17987 @deftp {Data Type} kmscon-configuration
17988 This is the data type representing the configuration of Kmscon, which
17989 implements virtual console log-in.
17993 @item @code{virtual-terminal}
17994 The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
17996 @item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
17997 A gexp denoting the name of the log-in program. The default log-in program is
17998 @command{login} from the Shadow tool suite.
18000 @item @code{login-arguments} (default: @code{'("-p")})
18001 A list of arguments to pass to @command{login}.
18003 @item @code{auto-login} (default: @code{#f})
18004 When passed a login name, as a string, the specified user will be logged
18005 in automatically without prompting for their login name or password.
18007 @item @code{hardware-acceleration?} (default: #f)
18008 Whether to use hardware acceleration.
18010 @item @code{font-engine} (default: @code{"pango"})
18011 Font engine used in Kmscon.
18013 @item @code{font-size} (default: @code{12})
18014 Font size used in Kmscon.
18016 @item @code{keyboard-layout} (default: @code{#f})
18017 If this is @code{#f}, Kmscon uses the default keyboard layout---usually US
18018 English (``qwerty'') for a 105-key PC keyboard.
18020 Otherwise this must be a @code{keyboard-layout} object specifying the
18021 keyboard layout. @xref{Keyboard Layout}, for more information on how to
18022 specify the keyboard layout.
18024 @item @code{kmscon} (default: @var{kmscon})
18025 The Kmscon package to use.
18030 @cindex name service cache daemon
18032 @deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
18033 [#:name-services '()]
18034 Return a service that runs the libc name service cache daemon (nscd) with the
18035 given @var{config}---an @code{<nscd-configuration>} object. @xref{Name
18036 Service Switch}, for an example.
18038 For convenience, the Shepherd service for nscd provides the following actions:
18042 @cindex cache invalidation, nscd
18043 @cindex nscd, cache invalidation
18044 This invalidate the given cache. For instance, running:
18047 herd invalidate nscd hosts
18051 invalidates the host name lookup cache of nscd.
18054 Running @command{herd statistics nscd} displays information about nscd usage
18060 @defvr {Scheme Variable} %nscd-default-configuration
18061 This is the default @code{<nscd-configuration>} value (see below) used
18062 by @code{nscd-service}. It uses the caches defined by
18063 @code{%nscd-default-caches}; see below.
18066 @deftp {Data Type} nscd-configuration
18067 This is the data type representing the name service cache daemon (nscd)
18072 @item @code{name-services} (default: @code{'()})
18073 List of packages denoting @dfn{name services} that must be visible to
18074 the nscd---e.g., @code{(list @var{nss-mdns})}.
18076 @item @code{glibc} (default: @var{glibc})
18077 Package object denoting the GNU C Library providing the @command{nscd}
18080 @item @code{log-file} (default: @code{"/var/log/nscd.log"})
18081 Name of the nscd log file. This is where debugging output goes when
18082 @code{debug-level} is strictly positive.
18084 @item @code{debug-level} (default: @code{0})
18085 Integer denoting the debugging levels. Higher numbers mean that more
18086 debugging output is logged.
18088 @item @code{caches} (default: @code{%nscd-default-caches})
18089 List of @code{<nscd-cache>} objects denoting things to be cached; see
18095 @deftp {Data Type} nscd-cache
18096 Data type representing a cache database of nscd and its parameters.
18100 @item @code{database}
18101 This is a symbol representing the name of the database to be cached.
18102 Valid values are @code{passwd}, @code{group}, @code{hosts}, and
18103 @code{services}, which designate the corresponding NSS database
18104 (@pxref{NSS Basics,,, libc, The GNU C Library Reference Manual}).
18106 @item @code{positive-time-to-live}
18107 @itemx @code{negative-time-to-live} (default: @code{20})
18108 A number representing the number of seconds during which a positive or
18109 negative lookup result remains in cache.
18111 @item @code{check-files?} (default: @code{#t})
18112 Whether to check for updates of the files corresponding to
18115 For instance, when @var{database} is @code{hosts}, setting this flag
18116 instructs nscd to check for updates in @file{/etc/hosts} and to take
18119 @item @code{persistent?} (default: @code{#t})
18120 Whether the cache should be stored persistently on disk.
18122 @item @code{shared?} (default: @code{#t})
18123 Whether the cache should be shared among users.
18125 @item @code{max-database-size} (default: 32@tie{}MiB)
18126 Maximum size in bytes of the database cache.
18128 @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
18129 @c settings, so leave them out.
18134 @defvr {Scheme Variable} %nscd-default-caches
18135 List of @code{<nscd-cache>} objects used by default by
18136 @code{nscd-configuration} (see above).
18138 It enables persistent and aggressive caching of service and host name
18139 lookups. The latter provides better host name lookup performance,
18140 resilience in the face of unreliable name servers, and also better
18141 privacy---often the result of host name lookups is in local cache, so
18142 external name servers do not even need to be queried.
18145 @anchor{syslog-configuration-type}
18148 @deftp {Data Type} syslog-configuration
18149 This data type represents the configuration of the syslog daemon.
18152 @item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
18153 The syslog daemon to use.
18155 @item @code{config-file} (default: @code{%default-syslog.conf})
18156 The syslog configuration file to use.
18161 @anchor{syslog-service}
18163 @deffn {Scheme Procedure} syslog-service @var{config}
18164 Return a service that runs a syslog daemon according to @var{config}.
18166 @xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more
18167 information on the configuration file syntax.
18170 @defvr {Scheme Variable} guix-service-type
18171 This is the type of the service that runs the build daemon,
18172 @command{guix-daemon} (@pxref{Invoking guix-daemon}). Its value must be a
18173 @code{guix-configuration} record as described below.
18176 @anchor{guix-configuration-type}
18177 @deftp {Data Type} guix-configuration
18178 This data type represents the configuration of the Guix build daemon.
18179 @xref{Invoking guix-daemon}, for more information.
18182 @item @code{guix} (default: @var{guix})
18183 The Guix package to use.
18185 @item @code{build-group} (default: @code{"guixbuild"})
18186 Name of the group for build user accounts.
18188 @item @code{build-accounts} (default: @code{10})
18189 Number of build user accounts to create.
18191 @item @code{authorize-key?} (default: @code{#t})
18192 @cindex substitutes, authorization thereof
18193 Whether to authorize the substitute keys listed in
18194 @code{authorized-keys}---by default that of
18195 @code{@value{SUBSTITUTE-SERVER-1}} and
18196 @code{@value{SUBSTITUTE-SERVER-2}}
18197 (@pxref{Substitutes}).
18199 When @code{authorize-key?} is true, @file{/etc/guix/acl} cannot be
18200 changed by invoking @command{guix archive --authorize}. You must
18201 instead adjust @code{guix-configuration} as you wish and reconfigure the
18202 system. This ensures that your operating system configuration file is
18206 When booting or reconfiguring to a system where @code{authorize-key?}
18207 is true, the existing @file{/etc/guix/acl} file is backed up as
18208 @file{/etc/guix/acl.bak} if it was determined to be a manually modified
18209 file. This is to facilitate migration from earlier versions, which
18210 allowed for in-place modifications to @file{/etc/guix/acl}.
18213 @vindex %default-authorized-guix-keys
18214 @item @code{authorized-keys} (default: @code{%default-authorized-guix-keys})
18215 The list of authorized key files for archive imports, as a list of
18216 string-valued gexps (@pxref{Invoking guix archive}). By default, it
18217 contains that of @code{@value{SUBSTITUTE-SERVER-1}} and
18218 @code{@value{SUBSTITUTE-SERVER-2}} (@pxref{Substitutes}). See
18219 @code{substitute-urls} below for an example on how to change it.
18221 @item @code{use-substitutes?} (default: @code{#t})
18222 Whether to use substitutes.
18224 @item @code{substitute-urls} (default: @code{%default-substitute-urls})
18225 The list of URLs where to look for substitutes by default.
18227 Suppose you would like to fetch substitutes from @code{guix.example.org}
18228 in addition to @code{@value{SUBSTITUTE-SERVER-1}}. You will need to do
18229 two things: (1) add @code{guix.example.org} to @code{substitute-urls},
18230 and (2) authorize its signing key, having done appropriate checks
18231 (@pxref{Substitute Server Authorization}). The configuration below does
18235 (guix-configuration
18237 (append (list "https://guix.example.org")
18238 %default-substitute-urls))
18240 (append (list (local-file "./guix.example.org-key.pub"))
18241 %default-authorized-guix-keys)))
18244 This example assumes that the file @file{./guix.example.org-key.pub}
18245 contains the public key that @code{guix.example.org} uses to sign
18248 @item @code{generate-substitute-key?} (default: @code{#t})
18249 Whether to generate a @dfn{substitute key pair} under
18250 @file{/etc/guix/signing-key.pub} and @file{/etc/guix/signing-key.sec} if
18251 there is not already one.
18253 This key pair is used when exporting store items, for instance with
18254 @command{guix publish} (@pxref{Invoking guix publish}) or @command{guix
18255 archive} (@pxref{Invoking guix archive}). Generating a key pair takes a
18256 few seconds when enough entropy is available and is only done once; you
18257 might want to turn it off for instance in a virtual machine that does
18258 not need it and where the extra boot time is a problem.
18260 @item @code{max-silent-time} (default: @code{0})
18261 @itemx @code{timeout} (default: @code{0})
18262 The number of seconds of silence and the number of seconds of activity,
18263 respectively, after which a build process times out. A value of zero
18264 disables the timeout.
18266 @item @code{log-compression} (default: @code{'gzip})
18267 The type of compression used for build logs---one of @code{gzip},
18268 @code{bzip2}, or @code{none}.
18270 @item @code{discover?} (default: @code{#f})
18271 Whether to discover substitute servers on the local network using mDNS
18274 @item @code{extra-options} (default: @code{'()})
18275 List of extra command-line options for @command{guix-daemon}.
18277 @item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
18278 File where @command{guix-daemon}'s standard output and standard error
18281 @cindex HTTP proxy, for @code{guix-daemon}
18282 @cindex proxy, for @code{guix-daemon} HTTP access
18283 @item @code{http-proxy} (default: @code{#f})
18284 The URL of the HTTP and HTTPS proxy used for downloading fixed-output
18285 derivations and substitutes.
18287 It is also possible to change the daemon's proxy at run time through the
18288 @code{set-http-proxy} action, which restarts it:
18291 herd set-http-proxy guix-daemon http://localhost:8118
18294 To clear the proxy settings, run:
18297 herd set-http-proxy guix-daemon
18300 @item @code{tmpdir} (default: @code{#f})
18301 A directory path where the @command{guix-daemon} will perform builds.
18306 @deftp {Data Type} guix-extension
18308 This data type represents the parameters of the Guix build daemon that
18309 are extendable. This is the type of the object that must be used within
18310 a guix service extension.
18311 @xref{Service Composition}, for more information.
18314 @item @code{authorized-keys} (default: @code{'()})
18315 A list of file-like objects where each element contains a public key.
18317 @item @code{substitute-urls} (default: @code{'()})
18318 A list of strings where each element is a substitute URL.
18320 @item @code{chroot-directories} (default: @code{'()})
18321 A list of file-like objects or strings pointing to additional directories the build daemon can use.
18325 @deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
18326 Run @var{udev}, which populates the @file{/dev} directory dynamically.
18327 udev rules can be provided as a list of files through the @var{rules}
18328 variable. The procedures @code{udev-rule}, @code{udev-rules-service}
18329 and @code{file->udev-rule} from @code{(gnu services base)} simplify the
18330 creation of such rule files.
18332 The @command{herd rules udev} command, as root, returns the name of the
18333 directory containing all the active udev rules.
18336 @deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
18337 Return a udev-rule file named @var{file-name} containing the rules
18338 defined by the @var{contents} literal.
18340 In the following example, a rule for a USB device is defined to be
18341 stored in the file @file{90-usb-thing.rules}. The rule runs a script
18342 upon detecting a USB device with a given product identifier.
18345 (define %example-udev-rule
18347 "90-usb-thing.rules"
18348 (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
18349 "ATTR@{product@}==\"Example\", "
18350 "RUN+=\"/path/to/script\"")))
18354 @deffn {Scheme Procedure} udev-rules-service [@var{name} @var{rules}] @
18355 [#:groups @var{groups}]
18356 Return a service that extends @code{udev-service-type } with @var{rules}
18357 and @code{account-service-type} with @var{groups} as system groups.
18358 This works by creating a singleton service type
18359 @code{@var{name}-udev-rules}, of which the returned service is an
18362 Here we show how it can be used to extend @code{udev-service-type} with the
18363 previously defined rule @code{%example-udev-rule}.
18369 (cons (udev-rules-service 'usb-thing %example-udev-rule)
18370 %desktop-services)))
18374 @deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
18375 Return a udev file named @var{file-name} containing the rules defined
18376 within @var{file}, a file-like object.
18378 The following example showcases how we can use an existing rule file.
18381 (use-modules (guix download) ;for url-fetch
18382 (guix packages) ;for origin
18385 (define %android-udev-rules
18387 "51-android-udev.rules"
18388 (let ((version "20170910"))
18391 (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
18392 "android-udev-rules/" version "/51-android.rules"))
18394 (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
18398 Additionally, Guix package definitions can be included in @var{rules} in
18399 order to extend the udev rules with the definitions found under their
18400 @file{lib/udev/rules.d} sub-directory. In lieu of the previous
18401 @var{file->udev-rule} example, we could have used the
18402 @var{android-udev-rules} package which exists in Guix in the @code{(gnu
18403 packages android)} module.
18405 The following example shows how to use the @var{android-udev-rules}
18406 package so that the Android tool @command{adb} can detect devices
18407 without root privileges. It also details how to create the
18408 @code{adbusers} group, which is required for the proper functioning of
18409 the rules defined within the @code{android-udev-rules} package. To
18410 create such a group, we must define it both as part of the
18411 @code{supplementary-groups} of our @code{user-account} declaration, as
18412 well as in the @var{groups} of the @code{udev-rules-service} procedure.
18415 (use-modules (gnu packages android) ;for android-udev-rules
18416 (gnu system shadow) ;for user-group
18421 (users (cons (user-account
18423 (supplementary-groups
18424 '("adbusers" ;for adb
18425 "wheel" "netdev" "audio" "video")))))
18428 (cons (udev-rules-service 'android android-udev-rules
18429 #:groups '("adbusers"))
18430 %desktop-services)))
18433 @defvr {Scheme Variable} urandom-seed-service-type
18434 Save some entropy in @code{%random-seed-file} to seed @file{/dev/urandom}
18435 when rebooting. It also tries to seed @file{/dev/urandom} from
18436 @file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
18440 @defvr {Scheme Variable} %random-seed-file
18441 This is the name of the file where some random bytes are saved by
18442 @var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting.
18443 It defaults to @file{/var/lib/random-seed}.
18448 @defvr {Scheme Variable} gpm-service-type
18449 This is the type of the service that runs GPM, the @dfn{general-purpose
18450 mouse daemon}, which provides mouse support to the Linux console. GPM
18451 allows users to use the mouse in the console, notably to select, copy,
18454 The value for services of this type must be a @code{gpm-configuration}
18455 (see below). This service is not part of @code{%base-services}.
18458 @deftp {Data Type} gpm-configuration
18459 Data type representing the configuration of GPM.
18462 @item @code{options} (default: @code{%default-gpm-options})
18463 Command-line options passed to @command{gpm}. The default set of
18464 options instruct @command{gpm} to listen to mouse events on
18465 @file{/dev/input/mice}. @xref{Command Line,,, gpm, gpm manual}, for
18468 @item @code{gpm} (default: @code{gpm})
18469 The GPM package to use.
18474 @anchor{guix-publish-service-type}
18475 @deffn {Scheme Variable} guix-publish-service-type
18476 This is the service type for @command{guix publish} (@pxref{Invoking
18477 guix publish}). Its value must be a @code{guix-publish-configuration}
18478 object, as described below.
18480 This assumes that @file{/etc/guix} already contains a signing key pair as
18481 created by @command{guix archive --generate-key} (@pxref{Invoking guix
18482 archive}). If that is not the case, the service will fail to start.
18485 @deftp {Data Type} guix-publish-configuration
18486 Data type representing the configuration of the @code{guix publish}
18490 @item @code{guix} (default: @code{guix})
18491 The Guix package to use.
18493 @item @code{port} (default: @code{80})
18494 The TCP port to listen for connections.
18496 @item @code{host} (default: @code{"localhost"})
18497 The host (and thus, network interface) to listen to. Use
18498 @code{"0.0.0.0"} to listen on all the network interfaces.
18500 @item @code{advertise?} (default: @code{#f})
18501 When true, advertise the service on the local network @i{via} the DNS-SD
18502 protocol, using Avahi.
18504 This allows neighboring Guix devices with discovery on (see
18505 @code{guix-configuration} above) to discover this @command{guix publish}
18506 instance and to automatically download substitutes from it.
18508 @item @code{compression} (default: @code{'(("gzip" 3) ("zstd" 3))})
18509 This is a list of compression method/level tuple used when compressing
18510 substitutes. For example, to compress all substitutes with @emph{both} lzip
18511 at level 7 and gzip at level 9, write:
18514 '(("lzip" 7) ("gzip" 9))
18517 Level 9 achieves the best compression ratio at the expense of increased CPU
18518 usage, whereas level 1 achieves fast compression. @xref{Invoking guix
18519 publish}, for more information on the available compression methods and
18520 the tradeoffs involved.
18522 An empty list disables compression altogether.
18524 @item @code{nar-path} (default: @code{"nar"})
18525 The URL path at which ``nars'' can be fetched. @xref{Invoking guix
18526 publish, @option{--nar-path}}, for details.
18528 @item @code{cache} (default: @code{#f})
18529 When it is @code{#f}, disable caching and instead generate archives on
18530 demand. Otherwise, this should be the name of a directory---e.g.,
18531 @code{"/var/cache/guix/publish"}---where @command{guix publish} caches
18532 archives and meta-data ready to be sent. @xref{Invoking guix publish,
18533 @option{--cache}}, for more information on the tradeoffs involved.
18535 @item @code{workers} (default: @code{#f})
18536 When it is an integer, this is the number of worker threads used for
18537 caching; when @code{#f}, the number of processors is used.
18538 @xref{Invoking guix publish, @option{--workers}}, for more information.
18540 @item @code{cache-bypass-threshold} (default: 10 MiB)
18541 When @code{cache} is true, this is the maximum size in bytes of a store
18542 item for which @command{guix publish} may bypass its cache in case of a
18543 cache miss. @xref{Invoking guix publish,
18544 @option{--cache-bypass-threshold}}, for more information.
18546 @item @code{ttl} (default: @code{#f})
18547 When it is an integer, this denotes the @dfn{time-to-live} in seconds
18548 of the published archives. @xref{Invoking guix publish, @option{--ttl}},
18549 for more information.
18551 @item @code{negative-ttl} (default: @code{#f})
18552 When it is an integer, this denotes the @dfn{time-to-live} in
18553 seconds for the negative lookups. @xref{Invoking guix publish,
18554 @option{--negative-ttl}}, for more information.
18558 @anchor{rngd-service}
18559 @deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
18560 [#:device "/dev/hwrng"]
18561 Return a service that runs the @command{rngd} program from @var{rng-tools}
18562 to add @var{device} to the kernel's entropy pool. The service will fail if
18563 @var{device} does not exist.
18566 @anchor{pam-limits-service}
18567 @cindex session limits
18573 @cindex open file descriptors
18574 @deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
18576 Return a service that installs a configuration file for the
18577 @uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
18578 @code{pam_limits} module}. The procedure optionally takes a list of
18579 @code{pam-limits-entry} values, which can be used to specify
18580 @code{ulimit} limits and @code{nice} priority limits to user sessions.
18582 The following limits definition sets two hard and soft limits for all
18583 login sessions of users in the @code{realtime} group:
18586 (pam-limits-service
18588 (pam-limits-entry "@@realtime" 'both 'rtprio 99)
18589 (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
18592 The first entry increases the maximum realtime priority for
18593 non-privileged processes; the second entry lifts any restriction of the
18594 maximum address space that can be locked in memory. These settings are
18595 commonly used for real-time audio systems.
18597 Another useful example is raising the maximum number of open file
18598 descriptors that can be used:
18601 (pam-limits-service
18603 (pam-limits-entry "*" 'both 'nofile 100000)))
18606 In the above example, the asterisk means the limit should apply to any
18607 user. It is important to ensure the chosen value doesn't exceed the
18608 maximum system value visible in the @file{/proc/sys/fs/file-max} file,
18609 else the users would be prevented from login in. For more information
18610 about the Pluggable Authentication Module (PAM) limits, refer to the
18611 @samp{pam_limits} man page from the @code{linux-pam} package.
18614 @defvr {Scheme Variable} greetd-service-type
18615 @uref{https://git.sr.ht/~kennylevinsen/greetd, @code{greetd}} is a minimal and
18616 flexible login manager daemon, that makes no assumptions about what you
18619 If you can run it from your shell in a TTY, greetd can start it. If it
18620 can be taught to speak a simple JSON-based IPC protocol, then it can be
18623 @code{greetd-service-type} provides necessary infrastructure for logging
18624 in users, including:
18628 @code{greetd} PAM service
18631 Special variation of @code{pam-mount} to mount @code{XDG_RUNTIME_DIR}
18634 Here is example of switching from @code{mingetty-service-type} to
18635 @code{greetd-service-type}, and how different terminals could be:
18639 (modify-services %base-services
18640 ;; greetd-service-type provides "greetd" PAM service
18641 (delete login-service-type)
18642 ;; and can be used in place of mingetty-service-type
18643 (delete mingetty-service-type))
18645 (service greetd-service-type
18646 (greetd-configuration
18649 ;; we can make any terminal active by default
18650 (greetd-terminal-configuration (terminal-vt "1") (terminal-switch #t))
18651 ;; we can make environment without XDG_RUNTIME_DIR set
18652 ;; even provide our own environment variables
18653 (greetd-terminal-configuration
18655 (default-session-command
18656 (greetd-agreety-session
18657 (extra-env '(("MY_VAR" . "1")))
18659 ;; we can use different shell instead of default bash
18660 (greetd-terminal-configuration
18662 (default-session-command
18663 (greetd-agreety-session (command (file-append zsh "/bin/zsh")))))
18664 ;; we can use any other executable command as greeter
18665 (greetd-terminal-configuration
18667 (default-session-command (program-file "my-noop-greeter" #~(exit))))
18668 (greetd-terminal-configuration (terminal-vt "5"))
18669 (greetd-terminal-configuration (terminal-vt "6"))))))
18670 ;; mingetty-service-type can be used in parallel
18671 ;; if needed to do so, do not (delete login-service-type)
18672 ;; as illustrated above
18673 #| (service mingetty-service-type (mingetty-configuration (tty "tty8"))) |#))
18677 @deftp {Data Type} greetd-configuration
18678 Configuration record for the @code{greetd-service-type}.
18682 A file-like object containing the ``message of the day''.
18684 @item @code{allow-empty-passwords?} (default: @code{#t})
18685 Allow empty passwords by default so that first-time users can log in when
18686 the 'root' account has just been created.
18688 @item @code{terminals} (default: @code{'()})
18689 List of @code{greetd-terminal-configuration} per terminal for which
18690 @code{greetd} should be started.
18692 @item @code{greeter-supplementary-groups} (default: @code{'()})
18693 List of groups which should be added to @code{greeter} user. For instance:
18695 (greeter-supplementary-groups '("seat" "video"))
18697 Note that this example will fail if @code{seat} group does not exist.
18701 @deftp {Data Type} greetd-terminal-configuration
18702 Configuration record for per terminal greetd daemon service.
18705 @item @code{greetd} (default: @code{greetd})
18706 The greetd package to use.
18708 @item @code{config-file-name}
18709 Configuration file name to use for greetd daemon. Generally, autogenerated
18710 derivation based on @code{terminal-vt} value.
18712 @item @code{log-file-name}
18713 Log file name to use for greetd daemon. Generally, autogenerated
18714 name based on @code{terminal-vt} value.
18716 @item @code{terminal-vt} (default: @samp{"7"})
18717 The VT to run on. Use of a specific VT with appropriate conflict avoidance
18720 @item @code{terminal-switch} (default: @code{#f})
18721 Make this terminal active on start of @code{greetd}.
18723 @item @code{default-session-user} (default: @samp{"greeter"})
18724 The user to use for running the greeter.
18726 @item @code{default-session-command} (default: @code{(greetd-agreety-session)})
18727 Can be either instance of @code{greetd-agreety-session} configuration or
18728 @code{gexp->script} like object to use as greeter.
18733 @deftp {Data Type} greetd-agreety-session
18734 Configuration record for the agreety greetd greeter.
18737 @item @code{agreety} (default: @code{greetd})
18738 The package with @command{/bin/agreety} command.
18740 @item @code{command} (default: @code{(file-append bash "/bin/bash")})
18741 Command to be started by @command{/bin/agreety} on successful login.
18743 @item @code{command-args} (default: @code{'("-l")})
18744 Command arguments to pass to command.
18746 @item @code{extra-env} (default: @code{'()})
18747 Extra environment variables to set on login.
18749 @item @code{xdg-env?} (default: @code{#t})
18750 If true @code{XDG_RUNTIME_DIR} and @code{XDG_SESSION_TYPE} will be set
18751 before starting command. One should note that, @code{extra-env} variables
18752 are set right after mentioned variables, so that they can be overriden.
18757 @deftp {Data Type} greetd-wlgreet-session
18758 Generic configuration record for the wlgreet greetd greeter.
18761 @item @code{wlgreet} (default: @code{wlgreet})
18762 The package with the @command{/bin/wlgreet} command.
18764 @item @code{command} (default: @code{(file-append sway "/bin/sway")})
18765 Command to be started by @command{/bin/wlgreet} on successful login.
18767 @item @code{command-args} (default: @code{'()})
18768 Command arguments to pass to command.
18770 @item @code{output-mode} (default: @code{"all"})
18771 Option to use for @code{outputMode} in the TOML configuration file.
18773 @item @code{scale} (default: @code{1})
18774 Option to use for @code{scale} in the TOML configuration file.
18776 @item @code{background} (default: @code{'(0 0 0 0.9)})
18777 RGBA list to use as the background colour of the login prompt.
18779 @item @code{headline} (default: @code{'(1 1 1 1)})
18780 RGBA list to use as the headline colour of the UI popup.
18782 @item @code{prompt} (default: @code{'(1 1 1 1)})
18783 RGBA list to use as the prompt colour of the UI popup.
18785 @item @code{prompt-error} (default: @code{'(1 1 1 1)})
18786 RGBA list to use as the error colour of the UI popup.
18788 @item @code{border} (default: @code{'(1 1 1 1)})
18789 RGBA list to use as the border colour of the UI popup.
18791 @item @code{extra-env} (default: @code{'()})
18792 Extra environment variables to set on login.
18797 @deftp {Data Type} greetd-wlgreet-sway-session
18798 Sway-specific configuration record for the wlgreet greetd greeter.
18801 @item @code{wlgreet-session} (default: @code{(greetd-wlgreet-session)})
18802 A @code{greetd-wlgreet-session} record for generic wlgreet configuration,
18803 on top of the Sway-specific @code{greetd-wlgreet-sway-session}.
18805 @item @code{sway} (default: @code{sway})
18806 The package providing the @command{/bin/sway} command.
18808 @item @code{sway-configuration} (default: #f)
18809 File-like object providing an additional Sway configuration file to be
18810 prepended to the mandatory part of the configuration.
18814 Here is an example of a greetd configuration that uses wlgreet and Sway:
18817 (greetd-configuration
18818 ;; We need to give the greeter user these permissions, otherwise
18819 ;; Sway will crash on launch.
18820 (greeter-supplementary-groups (list "video" "input" "seat"))
18822 (list (greetd-terminal-configuration
18824 (terminal-switch #t)
18825 (default-session-command
18826 (greetd-wlgreet-sway-session
18827 (sway-configuration
18828 (local-file "sway-greetd.conf"))))))))
18832 @node Scheduled Job Execution
18833 @subsection Scheduled Job Execution
18837 @cindex scheduling jobs
18838 The @code{(gnu services mcron)} module provides an interface to
18839 GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
18840 mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional
18841 Unix @command{cron} daemon; the main difference is that it is
18842 implemented in Guile Scheme, which provides a lot of flexibility when
18843 specifying the scheduling of jobs and their actions.
18845 The example below defines an operating system that runs the
18846 @command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files})
18847 and the @command{guix gc} commands (@pxref{Invoking guix gc}) daily, as
18848 well as the @command{mkid} command on behalf of an unprivileged user
18849 (@pxref{mkid invocation,,, idutils, ID Database Utilities}). It uses
18850 gexps to introduce job definitions that are passed to mcron
18851 (@pxref{G-Expressions}).
18854 (use-modules (guix) (gnu) (gnu services mcron))
18855 (use-package-modules base idutils)
18857 (define updatedb-job
18858 ;; Run 'updatedb' at 3AM every day. Here we write the
18859 ;; job's action as a Scheme procedure.
18860 #~(job '(next-hour '(3))
18862 (execl (string-append #$findutils "/bin/updatedb")
18864 "--prunepaths=/tmp /var/tmp /gnu/store"))
18867 (define garbage-collector-job
18868 ;; Collect garbage 5 minutes after midnight every day.
18869 ;; The job's action is a shell command.
18870 #~(job "5 0 * * *" ;Vixie cron syntax
18873 (define idutils-job
18874 ;; Update the index database as user "charlie" at 12:15PM
18875 ;; and 19:15PM. This runs from the user's home directory.
18876 #~(job '(next-minute-from (next-hour '(12 19)) '(15))
18877 (string-append #$idutils "/bin/mkid src")
18883 ;; %BASE-SERVICES already includes an instance of
18884 ;; 'mcron-service-type', which we extend with additional
18885 ;; jobs using 'simple-service'.
18886 (services (cons (simple-service 'my-cron-jobs
18888 (list garbage-collector-job
18895 When providing the action of a job specification as a procedure, you
18896 should provide an explicit name for the job via the optional 3rd
18897 argument as done in the @code{updatedb-job} example above. Otherwise,
18898 the job would appear as ``Lambda function'' in the output of
18899 @command{herd schedule mcron}, which is not nearly descriptive enough!
18902 For more complex jobs defined in Scheme where you need control over the top
18903 level, for instance to introduce a @code{use-modules} form, you can move your
18904 code to a separate program using the @code{program-file} procedure of the
18905 @code{(guix gexp)} module (@pxref{G-Expressions}). The example below
18909 (define %battery-alert-job
18910 ;; Beep when the battery percentage falls below %MIN-LEVEL.
18912 '(next-minute (range 0 60 1))
18914 "battery-alert.scm"
18915 (with-imported-modules (source-module-closure
18916 '((guix build utils)))
18918 (use-modules (guix build utils)
18921 (ice-9 textual-ports)
18924 (define %min-level 20)
18926 (setenv "LC_ALL" "C") ;ensure English output
18927 (and-let* ((input-pipe (open-pipe*
18929 #$(file-append acpi "/bin/acpi")))
18930 (output (get-string-all input-pipe))
18931 (m (string-match "Discharging, ([0-9]+)%" output))
18932 (level (string->number (match:substring m 1)))
18933 ((< level %min-level)))
18934 (format #t "warning: Battery level is low (~a%)~%" level)
18935 (invoke #$(file-append beep "/bin/beep") "-r5")))))))
18938 @xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron},
18939 for more information on mcron job specifications. Below is the
18940 reference of the mcron service.
18942 On a running system, you can use the @code{schedule} action of the service to
18943 visualize the mcron jobs that will be executed next:
18946 # herd schedule mcron
18950 The example above lists the next five tasks that will be executed, but you can
18951 also specify the number of tasks to display:
18954 # herd schedule mcron 10
18957 @defvr {Scheme Variable} mcron-service-type
18958 This is the type of the @code{mcron} service, whose value is an
18959 @code{mcron-configuration} object.
18961 This service type can be the target of a service extension that provides
18962 additional job specifications (@pxref{Service Composition}). In other
18963 words, it is possible to define services that provide additional mcron
18967 @deftp {Data Type} mcron-configuration
18968 Data type representing the configuration of mcron.
18971 @item @code{mcron} (default: @var{mcron})
18972 The mcron package to use.
18975 This is a list of gexps (@pxref{G-Expressions}), where each gexp
18976 corresponds to an mcron job specification (@pxref{Syntax, mcron job
18977 specifications,, mcron, GNU@tie{}mcron}).
18983 @subsection Log Rotation
18986 @cindex log rotation
18988 Log files such as those found in @file{/var/log} tend to grow endlessly,
18989 so it's a good idea to @dfn{rotate} them once in a while---i.e., archive
18990 their contents in separate files, possibly compressed. The @code{(gnu
18991 services admin)} module provides an interface to GNU@tie{}Rot[t]log, a
18992 log rotation tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
18994 This service is part of @code{%base-services}, and thus enabled by
18995 default, with the default settings, for commonly encountered log files.
18996 The example below shows how to extend it with an additional
18997 @dfn{rotation}, should you need to do that (usually, services that
18998 produce log files already take care of that):
19001 (use-modules (guix) (gnu))
19002 (use-service-modules admin)
19004 (define my-log-files
19005 ;; Log files that I want to rotate.
19006 '("/var/log/something.log" "/var/log/another.log"))
19010 (services (cons (simple-service 'rotate-my-stuff
19011 rottlog-service-type
19012 (list (log-rotation
19014 (files my-log-files))))
19018 @defvr {Scheme Variable} rottlog-service-type
19019 This is the type of the Rottlog service, whose value is a
19020 @code{rottlog-configuration} object.
19022 Other services can extend this one with new @code{log-rotation} objects
19023 (see below), thereby augmenting the set of files to be rotated.
19025 This service type can define mcron jobs (@pxref{Scheduled Job
19026 Execution}) to run the rottlog service.
19029 @deftp {Data Type} rottlog-configuration
19030 Data type representing the configuration of rottlog.
19033 @item @code{rottlog} (default: @code{rottlog})
19034 The Rottlog package to use.
19036 @item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
19037 The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
19038 rottlog, GNU Rot[t]log Manual}).
19040 @item @code{rotations} (default: @code{%default-rotations})
19041 A list of @code{log-rotation} objects as defined below.
19044 This is a list of gexps where each gexp corresponds to an mcron job
19045 specification (@pxref{Scheduled Job Execution}).
19049 @deftp {Data Type} log-rotation
19050 Data type representing the rotation of a group of log files.
19052 Taking an example from the Rottlog manual (@pxref{Period Related File
19053 Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be
19059 (files '("/var/log/apache/*"))
19060 (options '("storedir apache-archives"
19066 The list of fields is as follows:
19069 @item @code{frequency} (default: @code{'weekly})
19070 The log rotation frequency, a symbol.
19073 The list of files or file glob patterns to rotate.
19075 @vindex %default-log-rotation-options
19076 @item @code{options} (default: @code{%default-log-rotation-options})
19077 The list of rottlog options for this rotation (@pxref{Configuration
19078 parameters,,, rottlog, GNU Rot[t]log Manual}).
19080 @item @code{post-rotate} (default: @code{#f})
19081 Either @code{#f} or a gexp to execute once the rotation has completed.
19085 @defvr {Scheme Variable} %default-rotations
19086 Specifies weekly rotation of @code{%rotated-files} and of
19087 @file{/var/log/guix-daemon.log}.
19090 @defvr {Scheme Variable} %rotated-files
19091 The list of syslog-controlled files to be rotated. By default it is:
19092 @code{'("/var/log/messages" "/var/log/secure" "/var/log/debug" \
19093 "/var/log/maillog")}.
19096 Some log files just need to be deleted periodically once they are old,
19097 without any other criterion and without any archival step. This is the
19098 case of build logs stored by @command{guix-daemon} under
19099 @file{/var/log/guix/drvs} (@pxref{Invoking guix-daemon}). The
19100 @code{log-cleanup} service addresses this use case. For example,
19101 @code{%base-services} (@pxref{Base Services}) includes the following:
19104 ;; Periodically delete old build logs.
19105 (service log-cleanup-service-type
19106 (log-cleanup-configuration
19107 (directory "/var/log/guix/drvs")))
19110 That ensures build logs do not accumulate endlessly.
19112 @defvr {Scheme Variable} log-cleanup-service-type
19113 This is the type of the service to delete old logs. Its value must be a
19114 @code{log-cleanup-configuration} record as described below.
19117 @deftp {Data Type} log-cleanup-configuration
19118 Data type representing the log cleanup configuration
19121 @item @code{directory}
19122 Name of the directory containing log files.
19124 @item @code{expiry} (default: @code{(* 6 30 24 3600)})
19125 Age in seconds after which a file is subject to deletion (six months by
19128 @item @code{schedule} (default: @code{"30 12 01,08,15,22 * *"})
19129 String or gexp denoting the corresponding mcron job schedule
19130 (@pxref{Scheduled Job Execution}).
19134 @cindex logging, anonymization
19135 @subheading Anonip Service
19137 Anonip is a privacy filter that removes IP address from web server logs.
19138 This service creates a FIFO and filters any written lines with anonip
19139 before writing the filtered log to a target file.
19141 The following example sets up the FIFO
19142 @file{/var/run/anonip/https.access.log} and writes the filtered log file
19143 @file{/var/log/anonip/https.access.log}.
19146 (service anonip-service-type
19147 (anonip-configuration
19148 (input "/var/run/anonip/https.access.log")
19149 (output "/var/log/anonip/https.access.log")))
19152 Configure your web server to write its logs to the FIFO at
19153 @file{/var/run/anonip/https.access.log} and collect the anonymized log
19154 file at @file{/var/web-logs/https.access.log}.
19156 @deftp {Data Type} anonip-configuration
19157 This data type represents the configuration of anonip.
19158 It has the following parameters:
19161 @item @code{anonip} (default: @code{anonip})
19162 The anonip package to use.
19165 The file name of the input log file to process. The service creates a
19166 FIFO of this name. The web server should write its logs to this FIFO.
19168 @item @code{output}
19169 The file name of the processed log file.
19172 The following optional settings may be provided:
19175 @item @code{skip-private?}
19176 When @code{#true} do not mask addresses in private ranges.
19178 @item @code{column}
19179 A 1-based indexed column number. Assume IP address is in the specified
19180 column (default is 1).
19182 @item @code{replacement}
19183 Replacement string in case address parsing fails, e.g. @code{"0.0.0.0"}.
19185 @item @code{ipv4mask}
19186 Number of bits to mask in IPv4 addresses.
19188 @item @code{ipv6mask}
19189 Number of bits to mask in IPv6 addresses.
19191 @item @code{increment}
19192 Increment the IP address by the given number. By default this is zero.
19194 @item @code{delimiter}
19195 Log delimiter string.
19198 Regular expression for detecting IP addresses. Use this instead of @code{column}.
19203 @node Networking Setup
19204 @subsection Networking Setup
19206 The @code{(gnu services networking)} module provides services to
19207 configure network interfaces and set up networking on your machine.
19208 Those services provide different ways for you to set up your machine: by
19209 declaring a static network configuration, by running a Dynamic Host
19210 Configuration Protocol (DHCP) client, or by running daemons such as
19211 NetworkManager and Connman that automate the whole process,
19212 automatically adapt to connectivity changes, and provide a high-level
19215 On a laptop, NetworkManager and Connman are by far the most convenient
19216 options, which is why the default desktop services include
19217 NetworkManager (@pxref{Desktop Services, @code{%desktop-services}}).
19218 For a server, or for a virtual machine or a container, static network
19219 configuration or a simple DHCP client are often more appropriate.
19221 This section describes the various network setup services available,
19222 starting with static network configuration.
19224 @defvr {Scheme Variable} static-networking-service-type
19225 This is the type for statically-configured network interfaces. Its
19226 value must be a list of @code{static-networking} records. Each of them
19227 declares a set of @dfn{addresses}, @dfn{routes}, and @dfn{links}, as
19230 @cindex network interface controller (NIC)
19231 @cindex NIC, networking interface controller
19232 Here is the simplest configuration, with only one network interface
19233 controller (NIC) and only IPv4 connectivity:
19236 ;; Static networking for one NIC, IPv4-only.
19237 (service static-networking-service-type
19238 (list (static-networking
19240 (list (network-address
19242 (value "10.0.2.15/24"))))
19244 (list (network-route
19245 (destination "default")
19246 (gateway "10.0.2.2"))))
19247 (name-servers '("10.0.2.3")))))
19250 The snippet above can be added to the @code{services} field of your
19251 operating system configuration (@pxref{Using the Configuration System}).
19252 It will configure your machine to have 10.0.2.15 as its IP address, with
19253 a 24-bit netmask for the local network---meaning that any 10.0.2.@var{x}
19254 address is on the local area network (LAN). Traffic to addresses
19255 outside the local network is routed @i{via} 10.0.2.2. Host names are
19256 resolved by sending domain name system (DNS) queries to 10.0.2.3.
19259 @deftp {Data Type} static-networking
19260 This is the data type representing a static network configuration.
19262 As an example, here is how you would declare the configuration of a
19263 machine with a single network interface controller (NIC) available as
19264 @code{eno1}, and with one IPv4 and one IPv6 address:
19267 ;; Network configuration for one NIC, IPv4 + IPv6.
19269 (addresses (list (network-address
19271 (value "10.0.2.15/24"))
19274 (value "2001:123:4567:101::1/64"))))
19275 (routes (list (network-route
19276 (destination "default")
19277 (gateway "10.0.2.2"))
19279 (destination "default")
19280 (gateway "2020:321:4567:42::1"))))
19281 (name-servers '("10.0.2.3")))
19284 If you are familiar with the @command{ip} command of the
19285 @uref{https://wiki.linuxfoundation.org/networking/iproute2,
19286 @code{iproute2} package} found on Linux-based systems, the declaration
19287 above is equivalent to typing:
19290 ip address add 10.0.2.15/24 dev eno1
19291 ip address add 2001:123:4567:101::1/64 dev eno1
19292 ip route add default via inet 10.0.2.2
19293 ip route add default via inet6 2020:321:4567:42::1
19296 Run @command{man 8 ip} for more info. Venerable GNU/Linux users will
19297 certainly know how to do it with @command{ifconfig} and @command{route},
19298 but we'll spare you that.
19300 The available fields of this data type are as follows:
19303 @item @code{addresses}
19304 @itemx @code{links} (default: @code{'()})
19305 @itemx @code{routes} (default: @code{'()})
19306 The list of @code{network-address}, @code{network-link}, and
19307 @code{network-route} records for this network (see below).
19309 @item @code{name-servers} (default: @code{'()})
19310 The list of IP addresses (strings) of domain name servers. These IP
19311 addresses go to @file{/etc/resolv.conf}.
19313 @item @code{provision} (default: @code{'(networking)})
19314 If true, this should be a list of symbols for the Shepherd service
19315 corresponding to this network configuration.
19317 @item @code{requirement} (default @code{'()})
19318 The list of Shepherd services depended on.
19322 @deftp {Data Type} network-address
19323 This is the data type representing the IP address of a network
19328 The name of the network interface for this address---e.g.,
19332 The actual IP address and network mask, in
19333 @uref{https://en.wikipedia.org/wiki/CIDR#CIDR_notation, @acronym{CIDR,
19334 Classless Inter-Domain Routing} notation}, as a string.
19336 For example, @code{"10.0.2.15/24"} denotes IPv4 address 10.0.2.15 on a
19337 24-bit sub-network---all 10.0.2.@var{x} addresses are on the same local
19341 Whether @code{value} denotes an IPv6 address. By default this is
19342 automatically determined.
19346 @deftp {Data Type} network-route
19347 This is the data type representing a network route.
19350 @item @code{destination}
19351 The route destination (a string), either an IP address and network mask
19352 or @code{"default"} to denote the default route.
19354 @item @code{source} (default: @code{#f})
19357 @item @code{device} (default: @code{#f})
19358 The device used for this route---e.g., @code{"eno2"}.
19360 @item @code{ipv6?} (default: auto)
19361 Whether this is an IPv6 route. By default this is automatically
19362 determined based on @code{destination} or @code{gateway}.
19364 @item @code{gateway} (default: @code{#f})
19365 IP address (a string) through which traffic is routed.
19369 @deftp {Data Type} network-link
19370 Data type for a network link (@pxref{Link,,, guile-netlink,
19371 Guile-Netlink Manual}).
19375 The name of the link---e.g., @code{"v0p0"}.
19378 A symbol denoting the type of the link---e.g., @code{'veth}.
19381 List of arguments for this type of link.
19385 @cindex loopback device
19386 @defvr {Scheme Variable} %loopback-static-networking
19387 This is the @code{static-networking} record representing the ``loopback
19388 device'', @code{lo}, for IP addresses 127.0.0.1 and ::1, and providing
19389 the @code{loopback} Shepherd service.
19392 @cindex networking, with QEMU
19393 @cindex QEMU, networking
19394 @defvr {Scheme Variable} %qemu-static-networking
19395 This is the @code{static-networking} record representing network setup
19396 when using QEMU's user-mode network stack on @code{eth0} (@pxref{Using
19397 the user mode network stack,,, QEMU, QEMU Documentation}).
19400 @cindex DHCP, networking service
19401 @defvr {Scheme Variable} dhcp-client-service-type
19402 This is the type of services that run @var{dhcp}, a Dynamic Host Configuration
19403 Protocol (DHCP) client.
19406 @deftp {Data Type} dhcp-client-configuration
19407 Data type representing the configuration of the DHCP client service.
19410 @item @code{package} (default: @code{isc-dhcp})
19411 DHCP client package to use.
19413 @item @code{interfaces} (default: @code{'all})
19414 Either @code{'all} or the list of interface names that the DHCP client
19415 should listen on---e.g., @code{'("eno1")}.
19417 When set to @code{'all}, the DHCP client listens on all the available
19418 non-loopback interfaces that can be activated. Otherwise the DHCP
19419 client listens only on the specified interfaces.
19423 @cindex NetworkManager
19425 @defvr {Scheme Variable} network-manager-service-type
19426 This is the service type for the
19427 @uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
19428 service. The value for this service type is a
19429 @code{network-manager-configuration} record.
19431 This service is part of @code{%desktop-services} (@pxref{Desktop
19435 @deftp {Data Type} network-manager-configuration
19436 Data type representing the configuration of NetworkManager.
19439 @item @code{network-manager} (default: @code{network-manager})
19440 The NetworkManager package to use.
19442 @item @code{dns} (default: @code{"default"})
19443 Processing mode for DNS, which affects how NetworkManager uses the
19444 @code{resolv.conf} configuration file.
19448 NetworkManager will update @code{resolv.conf} to reflect the nameservers
19449 provided by currently active connections.
19452 NetworkManager will run @code{dnsmasq} as a local caching nameserver, using a
19453 @dfn{conditional forwarding} configuration if you are connected to a VPN, and
19454 then update @code{resolv.conf} to point to the local nameserver.
19456 With this setting, you can share your network connection. For example when
19457 you want to share your network connection to another laptop @i{via} an
19458 Ethernet cable, you can open @command{nm-connection-editor} and configure the
19459 Wired connection's method for IPv4 and IPv6 to be ``Shared to other computers''
19460 and reestablish the connection (or reboot).
19462 You can also set up a @dfn{host-to-guest connection} to QEMU VMs
19463 (@pxref{Installing Guix in a VM}). With a host-to-guest connection, you can
19464 e.g.@: access a Web server running on the VM (@pxref{Web Services}) from a Web
19465 browser on your host system, or connect to the VM @i{via} SSH
19466 (@pxref{Networking Services, @code{openssh-service-type}}). To set up a
19467 host-to-guest connection, run this command once:
19470 nmcli connection add type tun \
19471 connection.interface-name tap0 \
19472 tun.mode tap tun.owner $(id -u) \
19473 ipv4.method shared \
19474 ipv4.addresses 172.28.112.1/24
19477 Then each time you launch your QEMU VM (@pxref{Running Guix in a VM}), pass
19478 @option{-nic tap,ifname=tap0,script=no,downscript=no} to
19479 @command{qemu-system-...}.
19482 NetworkManager will not modify @code{resolv.conf}.
19485 @item @code{vpn-plugins} (default: @code{'()})
19486 This is the list of available plugins for virtual private networks
19487 (VPNs). An example of this is the @code{network-manager-openvpn}
19488 package, which allows NetworkManager to manage VPNs @i{via} OpenVPN.
19494 @deffn {Scheme Variable} connman-service-type
19495 This is the service type to run @url{https://01.org/connman,Connman},
19496 a network connection manager.
19498 Its value must be an
19499 @code{connman-configuration} record as in this example:
19502 (service connman-service-type
19503 (connman-configuration
19504 (disable-vpn? #t)))
19507 See below for details about @code{connman-configuration}.
19510 @deftp {Data Type} connman-configuration
19511 Data Type representing the configuration of connman.
19514 @item @code{connman} (default: @var{connman})
19515 The connman package to use.
19517 @item @code{disable-vpn?} (default: @code{#f})
19518 When true, disable connman's vpn plugin.
19522 @cindex WPA Supplicant
19523 @defvr {Scheme Variable} wpa-supplicant-service-type
19524 This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
19525 supplicant}, an authentication daemon required to authenticate against
19526 encrypted WiFi or ethernet networks.
19529 @deftp {Data Type} wpa-supplicant-configuration
19530 Data type representing the configuration of WPA Supplicant.
19532 It takes the following parameters:
19535 @item @code{wpa-supplicant} (default: @code{wpa-supplicant})
19536 The WPA Supplicant package to use.
19538 @item @code{requirement} (default: @code{'(user-processes loopback syslogd)}
19539 List of services that should be started before WPA Supplicant starts.
19541 @item @code{dbus?} (default: @code{#t})
19542 Whether to listen for requests on D-Bus.
19544 @item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"})
19545 Where to store the PID file.
19547 @item @code{interface} (default: @code{#f})
19548 If this is set, it must specify the name of a network interface that
19549 WPA supplicant will control.
19551 @item @code{config-file} (default: @code{#f})
19552 Optional configuration file to use.
19554 @item @code{extra-options} (default: @code{'()})
19555 List of additional command-line arguments to pass to the daemon.
19559 @cindex ModemManager
19560 Some networking devices such as modems require special care, and this is
19561 what the services below focus on.
19563 @defvr {Scheme Variable} modem-manager-service-type
19564 This is the service type for the
19565 @uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
19566 service. The value for this service type is a
19567 @code{modem-manager-configuration} record.
19569 This service is part of @code{%desktop-services} (@pxref{Desktop
19573 @deftp {Data Type} modem-manager-configuration
19574 Data type representing the configuration of ModemManager.
19577 @item @code{modem-manager} (default: @code{modem-manager})
19578 The ModemManager package to use.
19583 @cindex USB_ModeSwitch
19584 @cindex Modeswitching
19586 @defvr {Scheme Variable} usb-modeswitch-service-type
19587 This is the service type for the
19588 @uref{https://www.draisberghof.de/usb_modeswitch/, USB_ModeSwitch}
19589 service. The value for this service type is
19590 a @code{usb-modeswitch-configuration} record.
19592 When plugged in, some USB modems (and other USB devices) initially present
19593 themselves as a read-only storage medium and not as a modem. They need to be
19594 @dfn{modeswitched} before they are usable. The USB_ModeSwitch service type
19595 installs udev rules to automatically modeswitch these devices when they are
19598 This service is part of @code{%desktop-services} (@pxref{Desktop
19602 @deftp {Data Type} usb-modeswitch-configuration
19603 Data type representing the configuration of USB_ModeSwitch.
19606 @item @code{usb-modeswitch} (default: @code{usb-modeswitch})
19607 The USB_ModeSwitch package providing the binaries for modeswitching.
19609 @item @code{usb-modeswitch-data} (default: @code{usb-modeswitch-data})
19610 The package providing the device data and udev rules file used by
19613 @item @code{config-file} (default: @code{#~(string-append #$usb-modeswitch:dispatcher "/etc/usb_modeswitch.conf")})
19614 Which config file to use for the USB_ModeSwitch dispatcher. By default the
19615 config file shipped with USB_ModeSwitch is used which disables logging to
19616 @file{/var/log} among other default settings. If set to @code{#f}, no config
19623 @node Networking Services
19624 @subsection Networking Services
19626 The @code{(gnu services networking)} module discussed in the previous
19627 section provides services for more advanced setups: providing a DHCP
19628 service for others to use, filtering packets with iptables or nftables,
19629 running a WiFi access point with @command{hostapd}, running the
19630 @command{inetd} ``superdaemon'', and more. This section describes
19633 @deffn {Scheme Procedure} dhcpd-service-type
19634 This type defines a service that runs a DHCP daemon. To create a
19635 service of this type, you must supply a @code{<dhcpd-configuration>}.
19639 (service dhcpd-service-type
19640 (dhcpd-configuration
19641 (config-file (local-file "my-dhcpd.conf"))
19642 (interfaces '("enp0s25"))))
19646 @deftp {Data Type} dhcpd-configuration
19648 @item @code{package} (default: @code{isc-dhcp})
19649 The package that provides the DHCP daemon. This package is expected to
19650 provide the daemon at @file{sbin/dhcpd} relative to its output
19651 directory. The default package is the
19652 @uref{https://www.isc.org/dhcp/, ISC's DHCP server}.
19653 @item @code{config-file} (default: @code{#f})
19654 The configuration file to use. This is required. It will be passed to
19655 @code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
19656 object (@pxref{G-Expressions, file-like objects}). See @code{man
19657 dhcpd.conf} for details on the configuration file syntax.
19658 @item @code{version} (default: @code{"4"})
19659 The DHCP version to use. The ISC DHCP server supports the values ``4'',
19660 ``6'', and ``4o6''. These correspond to the @code{dhcpd} program
19661 options @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for
19663 @item @code{run-directory} (default: @code{"/run/dhcpd"})
19664 The run directory to use. At service activation time, this directory
19665 will be created if it does not exist.
19666 @item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
19667 The PID file to use. This corresponds to the @code{-pf} option of
19668 @code{dhcpd}. See @code{man dhcpd} for details.
19669 @item @code{interfaces} (default: @code{'()})
19670 The names of the network interfaces on which dhcpd should listen for
19671 broadcasts. If this list is not empty, then its elements (which must be
19672 strings) will be appended to the @code{dhcpd} invocation when starting
19673 the daemon. It may not be necessary to explicitly specify any
19674 interfaces here; see @code{man dhcpd} for details.
19678 @cindex hostapd service, for Wi-Fi access points
19679 @cindex Wi-Fi access points, hostapd service
19680 @defvr {Scheme Variable} hostapd-service-type
19681 This is the service type to run the @uref{https://w1.fi/hostapd/,
19682 hostapd} daemon to set up WiFi (IEEE 802.11) access points and
19683 authentication servers. Its associated value must be a
19684 @code{hostapd-configuration} as shown below:
19687 ;; Use wlan1 to run the access point for "My Network".
19688 (service hostapd-service-type
19689 (hostapd-configuration
19690 (interface "wlan1")
19691 (ssid "My Network")
19696 @deftp {Data Type} hostapd-configuration
19697 This data type represents the configuration of the hostapd service, with
19698 the following fields:
19701 @item @code{package} (default: @code{hostapd})
19702 The hostapd package to use.
19704 @item @code{interface} (default: @code{"wlan0"})
19705 The network interface to run the WiFi access point.
19708 The SSID (@dfn{service set identifier}), a string that identifies this
19711 @item @code{broadcast-ssid?} (default: @code{#t})
19712 Whether to broadcast this SSID.
19714 @item @code{channel} (default: @code{1})
19715 The WiFi channel to use.
19717 @item @code{driver} (default: @code{"nl80211"})
19718 The driver interface type. @code{"nl80211"} is used with all Linux
19719 mac80211 drivers. Use @code{"none"} if building hostapd as a standalone
19720 RADIUS server that does # not control any wireless/wired driver.
19722 @item @code{extra-settings} (default: @code{""})
19723 Extra settings to append as-is to the hostapd configuration file. See
19724 @uref{https://w1.fi/cgit/hostap/plain/hostapd/hostapd.conf} for the
19725 configuration file reference.
19729 @defvr {Scheme Variable} simulated-wifi-service-type
19730 This is the type of a service to simulate WiFi networking, which can be
19731 useful in virtual machines for testing purposes. The service loads the
19733 @uref{https://www.kernel.org/doc/html/latest/networking/mac80211_hwsim/mac80211_hwsim.html,
19734 @code{mac80211_hwsim} module} and starts hostapd to create a pseudo WiFi
19735 network that can be seen on @code{wlan0}, by default.
19737 The service's value is a @code{hostapd-configuration} record.
19742 @defvr {Scheme Variable} iptables-service-type
19743 This is the service type to set up an iptables configuration. iptables is a
19744 packet filtering framework supported by the Linux kernel. This service
19745 supports configuring iptables for both IPv4 and IPv6. A simple example
19746 configuration rejecting all incoming connections except those to the ssh port
19750 (service iptables-service-type
19751 (iptables-configuration
19752 (ipv4-rules (plain-file "iptables.rules" "*filter
19756 -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
19757 -A INPUT -p tcp --dport 22 -j ACCEPT
19758 -A INPUT -j REJECT --reject-with icmp-port-unreachable
19761 (ipv6-rules (plain-file "ip6tables.rules" "*filter
19765 -A INPUT -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT
19766 -A INPUT -p tcp --dport 22 -j ACCEPT
19767 -A INPUT -j REJECT --reject-with icmp6-port-unreachable
19773 @deftp {Data Type} iptables-configuration
19774 The data type representing the configuration of iptables.
19777 @item @code{iptables} (default: @code{iptables})
19778 The iptables package that provides @code{iptables-restore} and
19779 @code{ip6tables-restore}.
19780 @item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules})
19781 The iptables rules to use. It will be passed to @code{iptables-restore}.
19782 This may be any ``file-like'' object (@pxref{G-Expressions, file-like
19784 @item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules})
19785 The ip6tables rules to use. It will be passed to @code{ip6tables-restore}.
19786 This may be any ``file-like'' object (@pxref{G-Expressions, file-like
19792 @defvr {Scheme Variable} nftables-service-type
19793 This is the service type to set up a nftables configuration. nftables is a
19794 netfilter project that aims to replace the existing iptables, ip6tables,
19795 arptables and ebtables framework. It provides a new packet filtering
19796 framework, a new user-space utility @command{nft}, and a compatibility layer
19797 for iptables. This service comes with a default ruleset
19798 @code{%default-nftables-ruleset} that rejecting all incoming connections
19799 except those to the ssh port 22. To use it, simply write:
19802 (service nftables-service-type)
19806 @deftp {Data Type} nftables-configuration
19807 The data type representing the configuration of nftables.
19810 @item @code{package} (default: @code{nftables})
19811 The nftables package that provides @command{nft}.
19812 @item @code{ruleset} (default: @code{%default-nftables-ruleset})
19813 The nftables ruleset to use. This may be any ``file-like'' object
19814 (@pxref{G-Expressions, file-like objects}).
19818 @cindex NTP (Network Time Protocol), service
19819 @cindex ntpd, service for the Network Time Protocol daemon
19820 @cindex real time clock
19821 @defvr {Scheme Variable} ntp-service-type
19822 This is the type of the service running the @uref{https://www.ntp.org,
19823 Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep the
19824 system clock synchronized with that of the specified NTP servers.
19826 The value of this service is an @code{ntpd-configuration} object, as described
19830 @deftp {Data Type} ntp-configuration
19831 This is the data type for the NTP service configuration.
19834 @item @code{servers} (default: @code{%ntp-servers})
19835 This is the list of servers (@code{<ntp-server>} records) with which
19836 @command{ntpd} will be synchronized. See the @code{ntp-server} data type
19839 @item @code{allow-large-adjustment?} (default: @code{#t})
19840 This determines whether @command{ntpd} is allowed to make an initial
19841 adjustment of more than 1,000 seconds.
19843 @item @code{ntp} (default: @code{ntp})
19844 The NTP package to use.
19848 @defvr {Scheme Variable} %ntp-servers
19849 List of host names used as the default NTP servers. These are servers of the
19850 @uref{https://www.ntppool.org/en/, NTP Pool Project}.
19853 @deftp {Data Type} ntp-server
19854 The data type representing the configuration of a NTP server.
19857 @item @code{type} (default: @code{'server})
19858 The type of the NTP server, given as a symbol. One of @code{'pool},
19859 @code{'server}, @code{'peer}, @code{'broadcast} or @code{'manycastclient}.
19861 @item @code{address}
19862 The address of the server, as a string.
19864 @item @code{options}
19865 NTPD options to use with that specific server, given as a list of option names
19866 and/or of option names and values tuples. The following example define a server
19867 to use with the options @option{iburst} and @option{prefer}, as well as
19868 @option{version} 3 and a @option{maxpoll} time of 16 seconds.
19873 (address "some.ntp.server.org")
19874 (options `(iburst (version 3) (maxpoll 16) prefer))))
19880 @deffn {Scheme Procedure} openntpd-service-type
19881 Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as implemented
19882 by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will keep the system
19883 clock synchronized with that of the given servers.
19887 openntpd-service-type
19888 (openntpd-configuration
19889 (listen-on '("127.0.0.1" "::1"))
19890 (sensor '("udcf0 correction 70000"))
19891 (constraint-from '("www.gnu.org"))
19892 (constraints-from '("https://www.google.com/"))))
19897 @defvr {Scheme Variable} %openntpd-servers
19898 This variable is a list of the server addresses defined in
19899 @code{%ntp-servers}.
19902 @deftp {Data Type} openntpd-configuration
19904 @item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
19905 The openntpd executable to use.
19906 @item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
19907 A list of local IP addresses or hostnames the ntpd daemon should listen on.
19908 @item @code{query-from} (default: @code{'()})
19909 A list of local IP address the ntpd daemon should use for outgoing queries.
19910 @item @code{sensor} (default: @code{'()})
19911 Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
19912 will listen to each sensor that actually exists and ignore non-existent ones.
19913 See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} for more
19915 @item @code{server} (default: @code{'()})
19916 Specify a list of IP addresses or hostnames of NTP servers to synchronize to.
19917 @item @code{servers} (default: @code{%openntp-servers})
19918 Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
19919 @item @code{constraint-from} (default: @code{'()})
19920 @code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.
19921 This time information is not used for precision but acts as an authenticated
19922 constraint, thereby reducing the impact of unauthenticated NTP
19923 man-in-the-middle attacks.
19924 Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide
19926 @item @code{constraints-from} (default: @code{'()})
19927 As with constraint from, specify a list of URLs, IP addresses or hostnames of
19928 HTTPS servers to provide a constraint. Should the hostname resolve to multiple
19929 IP addresses, @code{ntpd} will calculate a median constraint from all of them.
19934 @deffn {Scheme variable} inetd-service-type
19935 This service runs the @command{inetd} (@pxref{inetd invocation,,,
19936 inetutils, GNU Inetutils}) daemon. @command{inetd} listens for
19937 connections on internet sockets, and lazily starts the specified server
19938 program when a connection is made on one of these sockets.
19940 The value of this service is an @code{inetd-configuration} object. The
19941 following example configures the @command{inetd} daemon to provide the
19942 built-in @command{echo} service, as well as an smtp service which
19943 forwards smtp traffic over ssh to a server @code{smtp-server} behind a
19944 gateway @code{hostname}:
19949 (inetd-configuration
19953 (socket-type 'stream)
19960 (socket-type 'stream)
19964 (program (file-append openssh "/bin/ssh"))
19966 '("ssh" "-qT" "-i" "/path/to/ssh_key"
19967 "-W" "smtp-server:25" "user@@hostname")))))))
19970 See below for more details about @code{inetd-configuration}.
19973 @deftp {Data Type} inetd-configuration
19974 Data type representing the configuration of @command{inetd}.
19977 @item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
19978 The @command{inetd} executable to use.
19980 @item @code{entries} (default: @code{'()})
19981 A list of @command{inetd} service entries. Each entry should be created
19982 by the @code{inetd-entry} constructor.
19986 @deftp {Data Type} inetd-entry
19987 Data type representing an entry in the @command{inetd} configuration.
19988 Each entry corresponds to a socket where @command{inetd} will listen for
19992 @item @code{node} (default: @code{#f})
19993 Optional string, a comma-separated list of local addresses
19994 @command{inetd} should use when listening for this service.
19995 @xref{Configuration file,,, inetutils, GNU Inetutils} for a complete
19996 description of all options.
19998 A string, the name must correspond to an entry in @code{/etc/services}.
19999 @item @code{socket-type}
20000 One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
20002 @item @code{protocol}
20003 A string, must correspond to an entry in @code{/etc/protocols}.
20004 @item @code{wait?} (default: @code{#t})
20005 Whether @command{inetd} should wait for the server to exit before
20006 listening to new service requests.
20008 A string containing the user (and, optionally, group) name of the user
20009 as whom the server should run. The group name can be specified in a
20010 suffix, separated by a colon or period, i.e.@: @code{"user"},
20011 @code{"user:group"} or @code{"user.group"}.
20012 @item @code{program} (default: @code{"internal"})
20013 The server program which will serve the requests, or @code{"internal"}
20014 if @command{inetd} should use a built-in service.
20015 @item @code{arguments} (default: @code{'()})
20016 A list strings or file-like objects, which are the server program's
20017 arguments, starting with the zeroth argument, i.e.@: the name of the
20018 program itself. For @command{inetd}'s internal services, this entry
20019 must be @code{'()} or @code{'("internal")}.
20022 @xref{Configuration file,,, inetutils, GNU Inetutils} for a more
20023 detailed discussion of each configuration field.
20026 @cindex opendht, distributed hash table network service
20027 @cindex dhtproxy, for use with jami
20028 @defvr {Scheme Variable} opendht-service-type
20029 This is the type of the service running a @uref{https://opendht.net,
20030 OpenDHT} node, @command{dhtnode}. The daemon can be used to host your
20031 own proxy service to the distributed hash table (DHT), for example to
20032 connect to with Jami, among other applications.
20034 @quotation Important
20035 When using the OpenDHT proxy server, the IP addresses it ``sees'' from
20036 the clients should be addresses reachable from other peers. In practice
20037 this means that a publicly reachable address is best suited for a proxy
20038 server, outside of your private network. For example, hosting the proxy
20039 server on a IPv4 private local network and exposing it via port
20040 forwarding could work for external peers, but peers local to the proxy
20041 would have their private addresses shared with the external peers,
20042 leading to connectivity problems.
20045 The value of this service is a @code{opendht-configuration} object, as
20049 @c The fields documentation has been auto-generated using the
20050 @c configuration->documentation procedure from
20051 @c (gnu services configuration).
20052 @deftp {Data Type} opendht-configuration
20053 Available @code{opendht-configuration} fields are:
20056 @item @code{opendht} (default: @code{opendht}) (type: file-like)
20057 The @code{opendht} package to use.
20059 @item @code{peer-discovery?} (default: @code{#f}) (type: boolean)
20060 Whether to enable the multicast local peer discovery mechanism.
20062 @item @code{enable-logging?} (default: @code{#f}) (type: boolean)
20063 Whether to enable logging messages to syslog. It is disabled by default
20064 as it is rather verbose.
20066 @item @code{debug?} (default: @code{#f}) (type: boolean)
20067 Whether to enable debug-level logging messages. This has no effect if
20068 logging is disabled.
20070 @item @code{bootstrap-host} (default: @code{"bootstrap.jami.net:4222"}) (type: maybe-string)
20071 The node host name that is used to make the first connection to the
20072 network. A specific port value can be provided by appending the
20073 @code{:PORT} suffix. By default, it uses the Jami bootstrap nodes, but
20074 any host can be specified here. It's also possible to disable
20075 bootstrapping by explicitly setting this field to the
20076 @code{%unset-value} value.
20078 @item @code{port} (default: @code{4222}) (type: maybe-number)
20079 The UDP port to bind to. When left unspecified, an available port is
20080 automatically selected.
20082 @item @code{proxy-server-port} (type: maybe-number)
20083 Spawn a proxy server listening on the specified port.
20085 @item @code{proxy-server-port-tls} (type: maybe-number)
20086 Spawn a proxy server listening to TLS connections on the specified port.
20092 @defvr {Scheme Variable} tor-service-type
20093 This is the type for a service that runs the @uref{https://torproject.org,
20094 Tor} anonymous networking daemon. The service is configured using a
20095 @code{<tor-configuration>} record. By default, the Tor daemon runs as the
20096 @code{tor} unprivileged user, which is a member of the @code{tor} group.
20100 @deftp {Data Type} tor-configuration
20102 @item @code{tor} (default: @code{tor})
20103 The package that provides the Tor daemon. This package is expected to provide
20104 the daemon at @file{bin/tor} relative to its output directory. The default
20105 package is the @uref{https://www.torproject.org, Tor Project's}
20108 @item @code{config-file} (default: @code{(plain-file "empty" "")})
20109 The configuration file to use. It will be appended to a default configuration
20110 file, and the final configuration file will be passed to @code{tor} via its
20111 @code{-f} option. This may be any ``file-like'' object (@pxref{G-Expressions,
20112 file-like objects}). See @code{man tor} for details on the configuration file
20115 @item @code{hidden-services} (default: @code{'()})
20116 The list of @code{<hidden-service>} records to use. For any hidden service
20117 you include in this list, appropriate configuration to enable the hidden
20118 service will be automatically added to the default configuration file. You
20119 may conveniently create @code{<hidden-service>} records using the
20120 @code{tor-hidden-service} procedure described below.
20122 @item @code{socks-socket-type} (default: @code{'tcp})
20123 The default socket type that Tor should use for its SOCKS socket. This must
20124 be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by default
20125 Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost).
20126 If it is @code{'unix}, then Tor will listen on the UNIX domain socket
20127 @file{/var/run/tor/socks-sock}, which will be made writable by members of the
20130 If you want to customize the SOCKS socket in more detail, leave
20131 @code{socks-socket-type} at its default value of @code{'tcp} and use
20132 @code{config-file} to override the default by providing your own
20133 @code{SocksPort} option.
20135 @item @code{control-socket?} (default: @code{#f})
20136 Whether or not to provide a ``control socket'' by which Tor can be
20137 controlled to, for instance, dynamically instantiate tor onion services.
20138 If @code{#t}, Tor will listen for control commands on the UNIX domain socket
20139 @file{/var/run/tor/control-sock}, which will be made writable by members of the
20145 @cindex hidden service
20146 @deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
20147 Define a new Tor @dfn{hidden service} called @var{name} and implementing
20148 @var{mapping}. @var{mapping} is a list of port/host tuples, such as:
20151 '((22 "127.0.0.1:22")
20152 (80 "127.0.0.1:8080"))
20155 In this example, port 22 of the hidden service is mapped to local port 22, and
20156 port 80 is mapped to local port 8080.
20158 This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, where
20159 the @file{hostname} file contains the @code{.onion} host name for the hidden
20162 See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the Tor
20163 project's documentation} for more information.
20166 The @code{(gnu services rsync)} module provides the following services:
20168 You might want an rsync daemon if you have files that you want available
20169 so anyone (or just yourself) can download existing files or upload new
20172 @deffn {Scheme Variable} rsync-service-type
20173 This is the service type for the @uref{https://rsync.samba.org, rsync} daemon,
20174 The value for this service type is a
20175 @command{rsync-configuration} record as in this example:
20178 ;; Export two directories over rsync. By default rsync listens on
20179 ;; all the network interfaces.
20180 (service rsync-service-type
20181 (rsync-configuration
20182 (modules (list (rsync-module
20184 (file-name "/srv/zik")
20188 (file-name "/home/charlie/movies"))))))
20191 See below for details about @code{rsync-configuration}.
20194 @deftp {Data Type} rsync-configuration
20195 Data type representing the configuration for @code{rsync-service}.
20198 @item @code{package} (default: @var{rsync})
20199 @code{rsync} package to use.
20201 @item @code{address} (default: @code{#f})
20202 IP address on which @command{rsync} listens for incoming connections.
20203 If unspecified, it defaults to listening on all available addresses.
20205 @item @code{port-number} (default: @code{873})
20206 TCP port on which @command{rsync} listens for incoming connections. If port
20207 is less than @code{1024} @command{rsync} needs to be started as the
20208 @code{root} user and group.
20210 @item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
20211 Name of the file where @command{rsync} writes its PID.
20213 @item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
20214 Name of the file where @command{rsync} writes its lock file.
20216 @item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
20217 Name of the file where @command{rsync} writes its log file.
20219 @item @code{user} (default: @code{"root"})
20220 Owner of the @code{rsync} process.
20222 @item @code{group} (default: @code{"root"})
20223 Group of the @code{rsync} process.
20225 @item @code{uid} (default: @code{"rsyncd"})
20226 User name or user ID that file transfers to and from that module should take
20227 place as when the daemon was run as @code{root}.
20229 @item @code{gid} (default: @code{"rsyncd"})
20230 Group name or group ID that will be used when accessing the module.
20232 @item @code{modules} (default: @code{%default-modules})
20233 List of ``modules''---i.e., directories exported over rsync. Each
20234 element must be a @code{rsync-module} record, as described below.
20238 @deftp {Data Type} rsync-module
20239 This is the data type for rsync ``modules''. A module is a directory
20240 exported over the rsync protocol. The available fields are as follows:
20244 The module name. This is the name that shows up in URLs. For example,
20245 if the module is called @code{music}, the corresponding URL will be
20246 @code{rsync://host.example.org/music}.
20248 @item @code{file-name}
20249 Name of the directory being exported.
20251 @item @code{comment} (default: @code{""})
20252 Comment associated with the module. Client user interfaces may display
20253 it when they obtain the list of available modules.
20255 @item @code{read-only?} (default: @code{#t})
20256 Whether or not client will be able to upload files. If this is false,
20257 the uploads will be authorized if permissions on the daemon side permit
20260 @item @code{chroot?} (default: @code{#t})
20261 When this is true, the rsync daemon changes root to the module's
20262 directory before starting file transfers with the client. This improves
20263 security, but requires rsync to run as root.
20265 @item @code{timeout} (default: @code{300})
20266 Idle time in seconds after which the daemon closes a connection with the
20271 The @code{(gnu services syncthing)} module provides the following services:
20274 You might want a syncthing daemon if you have files between two or more
20275 computers and want to sync them in real time, safely protected from
20278 @deffn {Scheme Variable} syncthing-service-type
20279 This is the service type for the @uref{https://syncthing.net/,
20280 syncthing} daemon, The value for this service type is a
20281 @command{syncthing-configuration} record as in this example:
20284 (service syncthing-service-type
20285 (syncthing-configuration (user "alice")))
20288 See below for details about @code{syncthing-configuration}.
20290 @deftp {Data Type} syncthing-configuration
20291 Data type representing the configuration for @code{syncthing-service-type}.
20294 @item @code{syncthing} (default: @var{syncthing})
20295 @code{syncthing} package to use.
20297 @item @code{arguments} (default: @var{'()})
20298 List of command-line arguments passing to @code{syncthing} binary.
20300 @item @code{logflags} (default: @var{0})
20301 Sum of logging flags, see
20302 @uref{https://docs.syncthing.net/users/syncthing.html#cmdoption-logflags, Syncthing documentation logflags}.
20304 @item @code{user} (default: @var{#f})
20305 The user as which the Syncthing service is to be run.
20306 This assumes that the specified user exists.
20308 @item @code{group} (default: @var{"users"})
20309 The group as which the Syncthing service is to be run.
20310 This assumes that the specified group exists.
20312 @item @code{home} (default: @var{#f})
20313 Common configuration and data directory. The default configuration
20314 directory is @file{$HOME} of the specified Syncthing @code{user}.
20320 Furthermore, @code{(gnu services ssh)} provides the following services.
20324 @deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
20325 [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
20326 [#:allow-empty-passwords? #f] [#:root-login? #f] @
20327 [#:syslog-output? #t] [#:x11-forwarding? #t] @
20328 [#:tcp/ip-forwarding? #t] [#:password-authentication? #t] @
20329 [#:public-key-authentication? #t] [#:initialize? #t]
20330 Run the @command{lshd} program from @var{lsh} to listen on port @var{port-number}.
20331 @var{host-key} must designate a file containing the host key, and readable
20334 When @var{daemonic?} is true, @command{lshd} will detach from the
20335 controlling terminal and log its output to syslogd, unless one sets
20336 @var{syslog-output?} to false. Obviously, it also makes lsh-service
20337 depend on existence of syslogd service. When @var{pid-file?} is true,
20338 @command{lshd} writes its PID to the file called @var{pid-file}.
20340 When @var{initialize?} is true, automatically create the seed and host key
20341 upon service activation if they do not exist yet. This may take long and
20342 require interaction.
20344 When @var{initialize?} is false, it is up to the user to initialize the
20345 randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to create
20346 a key pair with the private key stored in file @var{host-key} (@pxref{lshd
20347 basics,,, lsh, LSH Manual}).
20349 When @var{interfaces} is empty, lshd listens for connections on all the
20350 network interfaces; otherwise, @var{interfaces} must be a list of host names
20353 @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
20354 passwords, and @var{root-login?} specifies whether to accept log-ins as
20357 The other options should be self-descriptive.
20362 @deffn {Scheme Variable} openssh-service-type
20363 This is the type for the @uref{http://www.openssh.org, OpenSSH} secure
20364 shell daemon, @command{sshd}. Its value must be an
20365 @code{openssh-configuration} record as in this example:
20368 (service openssh-service-type
20369 (openssh-configuration
20370 (x11-forwarding? #t)
20371 (permit-root-login 'prohibit-password)
20373 `(("alice" ,(local-file "alice.pub"))
20374 ("bob" ,(local-file "bob.pub"))))))
20377 See below for details about @code{openssh-configuration}.
20379 This service can be extended with extra authorized keys, as in this
20383 (service-extension openssh-service-type
20384 (const `(("charlie"
20385 ,(local-file "charlie.pub")))))
20389 @deftp {Data Type} openssh-configuration
20390 This is the configuration record for OpenSSH's @command{sshd}.
20393 @item @code{openssh} (default @var{openssh})
20394 The OpenSSH package to use.
20396 @item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
20397 Name of the file where @command{sshd} writes its PID.
20399 @item @code{port-number} (default: @code{22})
20400 TCP port on which @command{sshd} listens for incoming connections.
20402 @item @code{max-connections} (default: @code{200})
20403 Hard limit on the maximum number of simultaneous client connections,
20404 enforced by the inetd-style Shepherd service (@pxref{Service De- and
20405 Constructors, @code{make-inetd-constructor},, shepherd, The GNU Shepherd
20408 @item @code{permit-root-login} (default: @code{#f})
20409 This field determines whether and when to allow logins as root. If
20410 @code{#f}, root logins are disallowed; if @code{#t}, they are allowed.
20411 If it's the symbol @code{'prohibit-password}, then root logins are
20412 permitted but not with password-based authentication.
20414 @item @code{allow-empty-passwords?} (default: @code{#f})
20415 When true, users with empty passwords may log in. When false, they may
20418 @item @code{password-authentication?} (default: @code{#t})
20419 When true, users may log in with their password. When false, they have
20420 other authentication methods.
20422 @item @code{public-key-authentication?} (default: @code{#t})
20423 When true, users may log in using public key authentication. When
20424 false, users have to use other authentication method.
20426 Authorized public keys are stored in @file{~/.ssh/authorized_keys}.
20427 This is used only by protocol version 2.
20429 @item @code{x11-forwarding?} (default: @code{#f})
20430 When true, forwarding of X11 graphical client connections is
20431 enabled---in other words, @command{ssh} options @option{-X} and
20432 @option{-Y} will work.
20434 @item @code{allow-agent-forwarding?} (default: @code{#t})
20435 Whether to allow agent forwarding.
20437 @item @code{allow-tcp-forwarding?} (default: @code{#t})
20438 Whether to allow TCP forwarding.
20440 @item @code{gateway-ports?} (default: @code{#f})
20441 Whether to allow gateway ports.
20443 @item @code{challenge-response-authentication?} (default: @code{#f})
20444 Specifies whether challenge response authentication is allowed (e.g.@: via
20447 @item @code{use-pam?} (default: @code{#t})
20448 Enables the Pluggable Authentication Module interface. If set to
20449 @code{#t}, this will enable PAM authentication using
20450 @code{challenge-response-authentication?} and
20451 @code{password-authentication?}, in addition to PAM account and session
20452 module processing for all authentication types.
20454 Because PAM challenge response authentication usually serves an
20455 equivalent role to password authentication, you should disable either
20456 @code{challenge-response-authentication?} or
20457 @code{password-authentication?}.
20459 @item @code{print-last-log?} (default: @code{#t})
20460 Specifies whether @command{sshd} should print the date and time of the
20461 last user login when a user logs in interactively.
20463 @item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
20464 Configures external subsystems (e.g.@: file transfer daemon).
20466 This is a list of two-element lists, each of which containing the
20467 subsystem name and a command (with optional arguments) to execute upon
20470 The command @command{internal-sftp} implements an in-process SFTP
20471 server. Alternatively, one can specify the @command{sftp-server} command:
20473 (service openssh-service-type
20474 (openssh-configuration
20476 `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
20479 @item @code{accepted-environment} (default: @code{'()})
20480 List of strings describing which environment variables may be exported.
20482 Each string gets on its own line. See the @code{AcceptEnv} option in
20483 @code{man sshd_config}.
20485 This example allows ssh-clients to export the @env{COLORTERM} variable.
20486 It is set by terminal emulators, which support colors. You can use it in
20487 your shell's resource file to enable colors for the prompt and commands
20488 if this variable is set.
20491 (service openssh-service-type
20492 (openssh-configuration
20493 (accepted-environment '("COLORTERM"))))
20496 @item @code{authorized-keys} (default: @code{'()})
20497 @cindex authorized keys, SSH
20498 @cindex SSH authorized keys
20499 This is the list of authorized keys. Each element of the list is a user
20500 name followed by one or more file-like objects that represent SSH public
20504 (openssh-configuration
20506 `(("rekado" ,(local-file "rekado.pub"))
20507 ("chris" ,(local-file "chris.pub"))
20508 ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
20512 registers the specified public keys for user accounts @code{rekado},
20513 @code{chris}, and @code{root}.
20515 Additional authorized keys can be specified @i{via}
20516 @code{service-extension}.
20518 Note that this does @emph{not} interfere with the use of
20519 @file{~/.ssh/authorized_keys}.
20521 @item @code{generate-host-keys?} (default: @code{#t})
20522 Whether to generate host key pairs with @command{ssh-keygen -A} under
20523 @file{/etc/ssh} if there are none.
20525 Generating key pairs takes a few seconds when enough entropy is
20526 available and is only done once. You might want to turn it off for
20527 instance in a virtual machine that does not need it because host keys
20528 are provided in some other way, and where the extra boot time is a
20531 @item @code{log-level} (default: @code{'info})
20532 This is a symbol specifying the logging level: @code{quiet}, @code{fatal},
20533 @code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man
20534 page for @file{sshd_config} for the full list of level names.
20536 @item @code{extra-content} (default: @code{""})
20537 This field can be used to append arbitrary text to the configuration file. It
20538 is especially useful for elaborate configurations that cannot be expressed
20539 otherwise. This configuration, for example, would generally disable root
20540 logins, but permit them from one specific IP address:
20543 (openssh-configuration
20545 Match Address 192.168.0.1
20546 PermitRootLogin yes"))
20552 @deffn {Scheme Procedure} dropbear-service [@var{config}]
20553 Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
20554 daemon} with the given @var{config}, a @code{<dropbear-configuration>}
20557 For example, to specify a Dropbear service listening on port 1234, add
20558 this call to the operating system's @code{services} field:
20561 (dropbear-service (dropbear-configuration
20562 (port-number 1234)))
20566 @deftp {Data Type} dropbear-configuration
20567 This data type represents the configuration of a Dropbear SSH daemon.
20570 @item @code{dropbear} (default: @var{dropbear})
20571 The Dropbear package to use.
20573 @item @code{port-number} (default: 22)
20574 The TCP port where the daemon waits for incoming connections.
20576 @item @code{syslog-output?} (default: @code{#t})
20577 Whether to enable syslog output.
20579 @item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
20580 File name of the daemon's PID file.
20582 @item @code{root-login?} (default: @code{#f})
20583 Whether to allow @code{root} logins.
20585 @item @code{allow-empty-passwords?} (default: @code{#f})
20586 Whether to allow empty passwords.
20588 @item @code{password-authentication?} (default: @code{#t})
20589 Whether to enable password-based authentication.
20594 @deffn {Scheme Variable} autossh-service-type
20595 This is the type for the @uref{https://www.harding.motd.ca/autossh,
20596 AutoSSH} program that runs a copy of @command{ssh} and monitors it,
20597 restarting it as necessary should it die or stop passing traffic.
20598 AutoSSH can be run manually from the command-line by passing arguments
20599 to the binary @command{autossh} from the package @code{autossh}, but it
20600 can also be run as a Guix service. This latter use case is documented
20603 AutoSSH can be used to forward local traffic to a remote machine using
20604 an SSH tunnel, and it respects the @file{~/.ssh/config} of the user it
20607 For example, to specify a service running autossh as the user
20608 @code{pino} and forwarding all local connections to port @code{8081} to
20609 @code{remote:8081} using an SSH tunnel, add this call to the operating
20610 system's @code{services} field:
20613 (service autossh-service-type
20614 (autossh-configuration
20616 (ssh-options (list "-T" "-N" "-L" "8081:localhost:8081" "remote.net"))))
20620 @deftp {Data Type} autossh-configuration
20621 This data type represents the configuration of an AutoSSH service.
20625 @item @code{user} (default @code{"autossh"})
20626 The user as which the AutoSSH service is to be run.
20627 This assumes that the specified user exists.
20629 @item @code{poll} (default @code{600})
20630 Specifies the connection poll time in seconds.
20632 @item @code{first-poll} (default @code{#f})
20633 Specifies how many seconds AutoSSH waits before the first connection
20634 test. After this first test, polling is resumed at the pace defined in
20635 @code{poll}. When set to @code{#f}, the first poll is not treated
20636 specially and will also use the connection poll specified in
20639 @item @code{gate-time} (default @code{30})
20640 Specifies how many seconds an SSH connection must be active before it is
20641 considered successful.
20643 @item @code{log-level} (default @code{1})
20644 The log level, corresponding to the levels used by syslog---so @code{0}
20645 is the most silent while @code{7} is the chattiest.
20647 @item @code{max-start} (default @code{#f})
20648 The maximum number of times SSH may be (re)started before AutoSSH exits.
20649 When set to @code{#f}, no maximum is configured and AutoSSH may restart indefinitely.
20651 @item @code{message} (default @code{""})
20652 The message to append to the echo message sent when testing connections.
20654 @item @code{port} (default @code{"0"})
20655 The ports used for monitoring the connection. When set to @code{"0"},
20656 monitoring is disabled. When set to @code{"@var{n}"} where @var{n} is
20657 a positive integer, ports @var{n} and @var{n}+1 are used for
20658 monitoring the connection, such that port @var{n} is the base
20659 monitoring port and @code{n+1} is the echo port. When set to
20660 @code{"@var{n}:@var{m}"} where @var{n} and @var{m} are positive
20661 integers, the ports @var{n} and @var{m} are used for monitoring the
20662 connection, such that port @var{n} is the base monitoring port and
20663 @var{m} is the echo port.
20665 @item @code{ssh-options} (default @code{'()})
20666 The list of command-line arguments to pass to @command{ssh} when it is
20667 run. Options @option{-f} and @option{-M} are reserved for AutoSSH and
20668 may cause undefined behaviour.
20674 @deffn {Scheme Variable} webssh-service-type
20675 This is the type for the @uref{https://webssh.huashengdun.org/, WebSSH}
20676 program that runs a web SSH client. WebSSH can be run manually from the
20677 command-line by passing arguments to the binary @command{wssh} from the
20678 package @code{webssh}, but it can also be run as a Guix service. This
20679 latter use case is documented here.
20681 For example, to specify a service running WebSSH on loopback interface
20682 on port @code{8888} with reject policy with a list of allowed to
20683 connection hosts, and NGINX as a reverse-proxy to this service listening
20684 for HTTPS connection, add this call to the operating system's
20685 @code{services} field:
20688 (service webssh-service-type
20689 (webssh-configuration (address "127.0.0.1")
20692 (known-hosts '("localhost ecdsa-sha2-nistp256 AAAA…"
20693 "127.0.0.1 ecdsa-sha2-nistp256 AAAA…"))))
20695 (service nginx-service-type
20696 (nginx-configuration
20699 (nginx-server-configuration
20700 (inherit %webssh-configuration-nginx)
20701 (server-name '("webssh.example.com"))
20702 (listen '("443 ssl"))
20703 (ssl-certificate (letsencrypt-certificate "webssh.example.com"))
20704 (ssl-certificate-key (letsencrypt-key "webssh.example.com"))
20706 (cons (nginx-location-configuration
20707 (uri "/.well-known")
20708 (body '("root /var/www;")))
20709 (nginx-server-configuration-locations %webssh-configuration-nginx))))))))
20713 @deftp {Data Type} webssh-configuration
20714 Data type representing the configuration for @code{webssh-service}.
20717 @item @code{package} (default: @var{webssh})
20718 @code{webssh} package to use.
20720 @item @code{user-name} (default: @var{"webssh"})
20721 User name or user ID that file transfers to and from that module should take
20724 @item @code{group-name} (default: @var{"webssh"})
20725 Group name or group ID that will be used when accessing the module.
20727 @item @code{address} (default: @var{#f})
20728 IP address on which @command{webssh} listens for incoming connections.
20730 @item @code{port} (default: @var{8888})
20731 TCP port on which @command{webssh} listens for incoming connections.
20733 @item @code{policy} (default: @var{#f})
20734 Connection policy. @var{reject} policy requires to specify @var{known-hosts}.
20736 @item @code{known-hosts} (default: @var{'()})
20737 List of hosts which allowed for SSH connection from @command{webssh}.
20739 @item @code{log-file} (default: @file{"/var/log/webssh.log"})
20740 Name of the file where @command{webssh} writes its log file.
20742 @item @code{log-level} (default: @var{#f})
20748 @defvr {Scheme Variable} %facebook-host-aliases
20749 This variable contains a string for use in @file{/etc/hosts}
20750 (@pxref{Host Names,,, libc, The GNU C Library Reference Manual}). Each
20751 line contains a entry that maps a known server name of the Facebook
20752 on-line service---e.g., @code{www.facebook.com}---to the local
20753 host---@code{127.0.0.1} or its IPv6 equivalent, @code{::1}.
20755 This variable is typically used in the @code{hosts-file} field of an
20756 @code{operating-system} declaration (@pxref{operating-system Reference,
20757 @file{/etc/hosts}}):
20760 (use-modules (gnu) (guix))
20763 (host-name "mymachine")
20766 ;; Create a /etc/hosts file with aliases for "localhost"
20767 ;; and "mymachine", as well as for Facebook servers.
20768 (plain-file "hosts"
20769 (string-append (local-host-aliases host-name)
20770 %facebook-host-aliases))))
20773 This mechanism can prevent programs running locally, such as Web
20774 browsers, from accessing Facebook.
20777 The @code{(gnu services avahi)} provides the following definition.
20779 @defvr {Scheme Variable} avahi-service-type
20780 This is the service that runs @command{avahi-daemon}, a system-wide
20781 mDNS/DNS-SD responder that allows for service discovery and
20782 ``zero-configuration'' host name lookups (see @uref{https://avahi.org/}).
20783 Its value must be an @code{avahi-configuration} record---see below.
20785 This service extends the name service cache daemon (nscd) so that it can
20786 resolve @code{.local} host names using
20787 @uref{https://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name
20788 Service Switch}, for information on host name resolution.
20790 Additionally, add the @var{avahi} package to the system profile so that
20791 commands such as @command{avahi-browse} are directly usable.
20794 @deftp {Data Type} avahi-configuration
20795 Data type representation the configuration for Avahi.
20799 @item @code{host-name} (default: @code{#f})
20800 If different from @code{#f}, use that as the host name to
20801 publish for this machine; otherwise, use the machine's actual host name.
20803 @item @code{publish?} (default: @code{#t})
20804 When true, allow host names and services to be published (broadcast) over the
20807 @item @code{publish-workstation?} (default: @code{#t})
20808 When true, @command{avahi-daemon} publishes the machine's host name and IP
20809 address via mDNS on the local network. To view the host names published on
20810 your local network, you can run:
20813 avahi-browse _workstation._tcp
20816 @item @code{wide-area?} (default: @code{#f})
20817 When true, DNS-SD over unicast DNS is enabled.
20819 @item @code{ipv4?} (default: @code{#t})
20820 @itemx @code{ipv6?} (default: @code{#t})
20821 These fields determine whether to use IPv4/IPv6 sockets.
20823 @item @code{domains-to-browse} (default: @code{'()})
20824 This is a list of domains to browse.
20828 @deffn {Scheme Variable} openvswitch-service-type
20829 This is the type of the @uref{https://www.openvswitch.org, Open vSwitch}
20830 service, whose value should be an @code{openvswitch-configuration}
20834 @deftp {Data Type} openvswitch-configuration
20835 Data type representing the configuration of Open vSwitch, a multilayer
20836 virtual switch which is designed to enable massive network automation
20837 through programmatic extension.
20840 @item @code{package} (default: @var{openvswitch})
20841 Package object of the Open vSwitch.
20846 @defvr {Scheme Variable} pagekite-service-type
20847 This is the service type for the @uref{https://pagekite.net, PageKite} service,
20848 a tunneling solution for making localhost servers publicly visible, even from
20849 behind restrictive firewalls or NAT without forwarded ports. The value for
20850 this service type is a @code{pagekite-configuration} record.
20852 Here's an example exposing the local HTTP and SSH daemons:
20855 (service pagekite-service-type
20856 (pagekite-configuration
20857 (kites '("http:@@kitename:localhost:80:@@kitesecret"
20858 "raw/22:@@kitename:localhost:22:@@kitesecret"))
20859 (extra-file "/etc/pagekite.rc")))
20863 @deftp {Data Type} pagekite-configuration
20864 Data type representing the configuration of PageKite.
20867 @item @code{package} (default: @var{pagekite})
20868 Package object of PageKite.
20870 @item @code{kitename} (default: @code{#f})
20871 PageKite name for authenticating to the frontend server.
20873 @item @code{kitesecret} (default: @code{#f})
20874 Shared secret for authenticating to the frontend server. You should probably
20875 put this inside @code{extra-file} instead.
20877 @item @code{frontend} (default: @code{#f})
20878 Connect to the named PageKite frontend server instead of the
20879 @uref{https://pagekite.net,,pagekite.net} service.
20881 @item @code{kites} (default: @code{'("http:@@kitename:localhost:80:@@kitesecret")})
20882 List of service kites to use. Exposes HTTP on port 80 by default. The format
20883 is @code{proto:kitename:host:port:secret}.
20885 @item @code{extra-file} (default: @code{#f})
20886 Extra configuration file to read, which you are expected to create manually.
20887 Use this to add additional options and manage shared secrets out-of-band.
20892 @defvr {Scheme Variable} yggdrasil-service-type
20893 The service type for connecting to the @uref{https://yggdrasil-network.github.io/,
20894 Yggdrasil network}, an early-stage implementation of a fully end-to-end
20895 encrypted IPv6 network.
20898 Yggdrasil provides name-independent routing with cryptographically generated
20899 addresses. Static addressing means you can keep the same address as long as
20900 you want, even if you move to a new location, or generate a new address (by
20901 generating new keys) whenever you want.
20902 @uref{https://yggdrasil-network.github.io/2018/07/28/addressing.html}
20905 Pass it a value of @code{yggdrasil-configuration} to connect it to public
20906 peers and/or local peers.
20908 Here is an example using public peers and a static address. The static
20909 signing and encryption keys are defined in @file{/etc/yggdrasil-private.conf}
20910 (the default value for @code{config-file}).
20913 ;; part of the operating-system declaration
20914 (service yggdrasil-service-type
20915 (yggdrasil-configuration
20916 (autoconf? #f) ;; use only the public peers
20919 ;; https://github.com/yggdrasil-network/public-peers
20920 '((peers . #("tcp://1.2.3.4:1337"))))
20921 ;; /etc/yggdrasil-private.conf is the default value for config-file
20925 # sample content for /etc/yggdrasil-private.conf
20927 # Your public key. Your peers may ask you for this to put
20928 # into their AllowedPublicKeys configuration.
20929 PublicKey: 64277...
20931 # Your private key. DO NOT share this with anyone!
20932 PrivateKey: 5c750...
20937 @deftp {Data Type} yggdrasil-configuration
20938 Data type representing the configuration of Yggdrasil.
20941 @item @code{package} (default: @code{yggdrasil})
20942 Package object of Yggdrasil.
20944 @item @code{json-config} (default: @code{'()})
20945 Contents of @file{/etc/yggdrasil.conf}. Will be merged with
20946 @file{/etc/yggdrasil-private.conf}. Note that these settings are stored in
20947 the Guix store, which is readable to all users. @strong{Do not store your
20948 private keys in it}. See the output of @code{yggdrasil -genconf} for a
20949 quick overview of valid keys and their default values.
20951 @item @code{autoconf?} (default: @code{#f})
20952 Whether to use automatic mode. Enabling it makes Yggdrasil use adynamic IP
20953 and peer with IPv6 neighbors.
20955 @item @code{log-level} (default: @code{'info})
20956 How much detail to include in logs. Use @code{'debug} for more detail.
20958 @item @code{log-to} (default: @code{'stdout})
20959 Where to send logs. By default, the service logs standard output to
20960 @file{/var/log/yggdrasil.log}. The alternative is @code{'syslog}, which
20961 sends output to the running syslog service.
20963 @item @code{config-file} (default: @code{"/etc/yggdrasil-private.conf"})
20964 What HJSON file to load sensitive data from. This is where private keys
20965 should be stored, which are necessary to specify if you don't want a
20966 randomized address after each restart. Use @code{#f} to disable. Options
20967 defined in this file take precedence over @code{json-config}. Use the output
20968 of @code{yggdrasil -genconf} as a starting point. To configure a static
20969 address, delete everything except these options:
20972 @item @code{EncryptionPublicKey}
20973 @item @code{EncryptionPrivateKey}
20974 @item @code{SigningPublicKey}
20975 @item @code{SigningPrivateKey}
20981 @defvr {Scheme Variable} ipfs-service-type
20982 The service type for connecting to the @uref{https://ipfs.io,IPFS network},
20983 a global, versioned, peer-to-peer file system. Pass it a
20984 @code{ipfs-configuration} to change the ports used for the gateway and API.
20986 Here's an example configuration, using some non-standard ports:
20989 (service ipfs-service-type
20990 (ipfs-configuration
20991 (gateway "/ip4/127.0.0.1/tcp/8880")
20992 (api "/ip4/127.0.0.1/tcp/8881")))
20996 @deftp {Data Type} ipfs-configuration
20997 Data type representing the configuration of IPFS.
21000 @item @code{package} (default: @code{go-ipfs})
21001 Package object of IPFS.
21003 @item @code{gateway} (default: @code{"/ip4/127.0.0.1/tcp/8082"})
21004 Address of the gateway, in ‘multiaddress’ format.
21006 @item @code{api} (default: @code{"/ip4/127.0.0.1/tcp/5001"})
21007 Address of the API endpoint, in ‘multiaddress’ format.
21012 @deffn {Scheme Variable} keepalived-service-type
21013 This is the type for the @uref{https://www.keepalived.org/, Keepalived}
21014 routing software, @command{keepalived}. Its value must be an
21015 @code{keepalived-configuration} record as in this example for master
21019 (service keepalived-service-type
21020 (keepalived-configuration
21021 (config-file (local-file "keepalived-master.conf"))))
21024 where @file{keepalived-master.conf}:
21027 vrrp_instance my-group @{
21030 virtual_router_id 100
21032 unicast_peer @{ 10.0.0.2 @}
21033 virtual_ipaddress @{
21039 and for backup machine:
21042 (service keepalived-service-type
21043 (keepalived-configuration
21044 (config-file (local-file "keepalived-backup.conf"))))
21047 where @file{keepalived-backup.conf}:
21050 vrrp_instance my-group @{
21053 virtual_router_id 100
21055 unicast_peer @{ 10.0.0.3 @}
21056 virtual_ipaddress @{
21063 @node Unattended Upgrades
21064 @subsection Unattended Upgrades
21066 @cindex unattended upgrades
21067 @cindex upgrades, unattended
21068 Guix provides a service to perform @emph{unattended upgrades}:
21069 periodically, the system automatically reconfigures itself from the
21070 latest Guix. Guix System has several properties that make unattended
21075 upgrades are transactional (either the upgrade succeeds or it fails, but
21076 you cannot end up with an ``in-between'' system state);
21078 the upgrade log is kept---you can view it with @command{guix system
21079 list-generations}---and you can roll back to any previous generation,
21080 should the upgraded system fail to behave as intended;
21082 channel code is authenticated so you know you can only run genuine code
21083 (@pxref{Channels});
21085 @command{guix system reconfigure} prevents downgrades, which makes it
21086 immune to @dfn{downgrade attacks}.
21089 To set up unattended upgrades, add an instance of
21090 @code{unattended-upgrade-service-type} like the one below to the list of
21091 your operating system services:
21094 (service unattended-upgrade-service-type)
21097 The defaults above set up weekly upgrades: every Sunday at midnight.
21098 You do not need to provide the operating system configuration file: it
21099 uses @file{/run/current-system/configuration.scm}, which ensures it
21100 always uses your latest configuration---@pxref{provenance-service-type},
21101 for more information about this file.
21103 There are several things that can be configured, in particular the
21104 periodicity and services (daemons) to be restarted upon completion.
21105 When the upgrade is successful, the service takes care of deleting
21106 system generations older that some threshold, as per @command{guix
21107 system delete-generations}. See the reference below for details.
21109 To ensure that upgrades are actually happening, you can run
21110 @command{guix system describe}. To investigate upgrade failures, visit
21111 the unattended upgrade log file (see below).
21113 @defvr {Scheme Variable} unattended-upgrade-service-type
21114 This is the service type for unattended upgrades. It sets up an mcron
21115 job (@pxref{Scheduled Job Execution}) that runs @command{guix system
21116 reconfigure} from the latest version of the specified channels.
21118 Its value must be a @code{unattended-upgrade-configuration} record (see
21122 @deftp {Data Type} unattended-upgrade-configuration
21123 This data type represents the configuration of the unattended upgrade
21124 service. The following fields are available:
21127 @item @code{schedule} (default: @code{"30 01 * * 0"})
21128 This is the schedule of upgrades, expressed as a gexp containing an
21129 mcron job schedule (@pxref{Guile Syntax, mcron job specifications,,
21130 mcron, GNU@tie{}mcron}).
21132 @item @code{channels} (default: @code{#~%default-channels})
21133 This gexp specifies the channels to use for the upgrade
21134 (@pxref{Channels}). By default, the tip of the official @code{guix}
21137 @item @code{operating-system-file} (default: @code{"/run/current-system/configuration.scm"})
21138 This field specifies the operating system configuration file to use.
21139 The default is to reuse the config file of the current configuration.
21141 There are cases, though, where referring to
21142 @file{/run/current-system/configuration.scm} is not enough, for instance
21143 because that file refers to extra files (SSH public keys, extra
21144 configuration files, etc.) @i{via} @code{local-file} and similar
21145 constructs. For those cases, we recommend something along these lines:
21148 (unattended-upgrade-configuration
21149 (operating-system-file
21150 (file-append (local-file "." "config-dir" #:recursive? #t)
21154 The effect here is to import all of the current directory into the
21155 store, and to refer to @file{config.scm} within that directory.
21156 Therefore, uses of @code{local-file} within @file{config.scm} will work
21157 as expected. @xref{G-Expressions}, for information about
21158 @code{local-file} and @code{file-append}.
21160 @item @code{services-to-restart} (default: @code{'(mcron)})
21161 This field specifies the Shepherd services to restart when the upgrade
21164 Those services are restarted right away upon completion, as with
21165 @command{herd restart}, which ensures that the latest version is
21166 running---remember that by default @command{guix system reconfigure}
21167 only restarts services that are not currently running, which is
21168 conservative: it minimizes disruption but leaves outdated services
21171 Use @command{herd status} to find out candidates for restarting.
21172 @xref{Services}, for general information about services. Common
21173 services to restart would include @code{ntpd} and @code{ssh-daemon}.
21175 By default, the @code{mcron} service is restarted. This ensures that
21176 the latest version of the unattended upgrade job will be used next time.
21178 @item @code{system-expiration} (default: @code{(* 3 30 24 3600)})
21179 This is the expiration time in seconds for system generations. System
21180 generations older that this amount of time are deleted with
21181 @command{guix system delete-generations} when an upgrade completes.
21184 The unattended upgrade service does not run the garbage collector. You
21185 will probably want to set up your own mcron job to run @command{guix gc}
21189 @item @code{maximum-duration} (default: @code{3600})
21190 Maximum duration in seconds for the upgrade; past that time, the upgrade
21193 This is primarily useful to ensure the upgrade does not end up
21194 rebuilding or re-downloading ``the world''.
21196 @item @code{log-file} (default: @code{"/var/log/unattended-upgrade.log"})
21197 File where unattended upgrades are logged.
21202 @subsection X Window
21205 @cindex X Window System
21206 @cindex login manager
21207 Support for the X Window graphical display system---specifically
21208 Xorg---is provided by the @code{(gnu services xorg)} module. Note that
21209 there is no @code{xorg-service} procedure. Instead, the X server is
21210 started by the @dfn{login manager}, by default the GNOME Display Manager (GDM).
21213 @cindex GNOME, login manager
21215 GDM of course allows users to log in into window managers and desktop
21216 environments other than GNOME; for those using GNOME, GDM is required for
21217 features such as automatic screen locking.
21219 @cindex window manager
21220 To use X11, you must install at least one @dfn{window manager}---for
21221 example the @code{windowmaker} or @code{openbox} packages---preferably
21222 by adding it to the @code{packages} field of your operating system
21223 definition (@pxref{operating-system Reference, system-wide packages}).
21225 @anchor{wayland-gdm}
21226 GDM also supports Wayland: it can itself use Wayland instead of X11 for
21227 its user interface, and it can also start Wayland sessions. The former is
21228 required for the latter, to enable, set @code{wayland?} to @code{#t} in
21229 @code{gdm-configuration}.
21231 @defvr {Scheme Variable} gdm-service-type
21232 This is the type for the @uref{https://wiki.gnome.org/Projects/GDM/, GNOME
21233 Desktop Manager} (GDM), a program that manages graphical display servers and
21234 handles graphical user logins. Its value must be a @code{gdm-configuration}
21237 @cindex session types
21238 GDM looks for @dfn{session types} described by the @file{.desktop} files in
21239 @file{/run/current-system/profile/share/xsessions} (for X11 sessions) and
21240 @file{/run/current-system/profile/share/wayland-sessions} (for Wayland
21241 sessions) and allows users to choose a session from the log-in screen.
21242 Packages such as @code{gnome}, @code{xfce}, @code{i3} and @code{sway} provide
21243 @file{.desktop} files; adding them to the system-wide set of packages
21244 automatically makes them available at the log-in screen.
21246 In addition, @file{~/.xsession} files are honored. When available,
21247 @file{~/.xsession} must be an executable that starts a window manager
21248 and/or other X clients.
21251 @deftp {Data Type} gdm-configuration
21253 @item @code{auto-login?} (default: @code{#f})
21254 @itemx @code{default-user} (default: @code{#f})
21255 When @code{auto-login?} is false, GDM presents a log-in screen.
21257 When @code{auto-login?} is true, GDM logs in directly as
21258 @code{default-user}.
21260 @item @code{auto-suspend?} (default @code{#t})
21261 When true, GDM will automatically suspend to RAM when nobody is
21262 physically connected. When a machine is used via remote desktop or SSH,
21263 this should be set to false to avoid GDM interrupting remote sessions or
21264 rendering the machine unavailable.
21266 @item @code{debug?} (default: @code{#f})
21267 When true, GDM writes debug messages to its log.
21269 @item @code{gnome-shell-assets} (default: ...)
21270 List of GNOME Shell assets needed by GDM: icon theme, fonts, etc.
21272 @item @code{xorg-configuration} (default: @code{(xorg-configuration)})
21273 Configuration of the Xorg graphical server.
21275 @item @code{x-session} (default: @code{(xinitrc)})
21276 Script to run before starting a X session.
21278 @item @code{xdmcp?} (default: @code{#f})
21279 When true, enable the X Display Manager Control Protocol (XDMCP). This
21280 should only be enabled in trusted environments, as the protocol is not
21281 secure. When enabled, GDM listens for XDMCP queries on the UDP port
21284 @item @code{dbus-daemon} (default: @code{dbus-daemon-wrapper})
21285 File name of the @code{dbus-daemon} executable.
21287 @item @code{gdm} (default: @code{gdm})
21288 The GDM package to use.
21290 @item @code{wayland?} (default: @code{#f})
21291 When true, enables Wayland in GDM, necessary to use Wayland sessions.
21293 @item @code{wayland-session} (default: @code{gdm-wayland-session-wrapper})
21294 The Wayland session wrapper to use, needed to setup the
21299 @defvr {Scheme Variable} slim-service-type
21300 This is the type for the SLiM graphical login manager for X11.
21302 Like GDM, SLiM looks for session types described by @file{.desktop} files and
21303 allows users to choose a session from the log-in screen using @kbd{F1}. It
21304 also honors @file{~/.xsession} files.
21306 Unlike GDM, SLiM does not spawn the user session on a different VT after
21307 logging in, which means that you can only start one graphical session. If you
21308 want to be able to run multiple graphical sessions at the same time you have
21309 to add multiple SLiM services to your system services. The following example
21310 shows how to replace the default GDM service with two SLiM services on tty7
21314 (use-modules (gnu services)
21315 (gnu services desktop)
21316 (gnu services xorg))
21320 (services (cons* (service slim-service-type (slim-configuration
21323 (service slim-service-type (slim-configuration
21326 (modify-services %desktop-services
21327 (delete gdm-service-type)))))
21332 @deftp {Data Type} slim-configuration
21333 Data type representing the configuration of @code{slim-service-type}.
21336 @item @code{allow-empty-passwords?} (default: @code{#t})
21337 Whether to allow logins with empty passwords.
21339 @item @code{gnupg?} (default: @code{#f})
21340 If enabled, @code{pam-gnupg} will attempt to automatically unlock the
21341 user's GPG keys with the login password via @code{gpg-agent}. The
21342 keygrips of all keys to be unlocked should be written to
21343 @file{~/.pam-gnupg}, and can be queried with @code{gpg -K
21344 --with-keygrip}. Presetting passphrases must be enabled by adding
21345 @code{allow-preset-passphrase} in @file{~/.gnupg/gpg-agent.conf}.
21347 @item @code{auto-login?} (default: @code{#f})
21348 @itemx @code{default-user} (default: @code{""})
21349 When @code{auto-login?} is false, SLiM presents a log-in screen.
21351 When @code{auto-login?} is true, SLiM logs in directly as
21352 @code{default-user}.
21354 @item @code{theme} (default: @code{%default-slim-theme})
21355 @itemx @code{theme-name} (default: @code{%default-slim-theme-name})
21356 The graphical theme to use and its name.
21358 @item @code{auto-login-session} (default: @code{#f})
21359 If true, this must be the name of the executable to start as the default
21360 session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.
21362 If false, a session described by one of the available @file{.desktop}
21363 files in @code{/run/current-system/profile} and @code{~/.guix-profile}
21367 You must install at least one window manager in the system profile or in
21368 your user profile. Failing to do that, if @code{auto-login-session} is
21369 false, you will be unable to log in.
21372 @item @code{xorg-configuration} (default @code{(xorg-configuration)})
21373 Configuration of the Xorg graphical server.
21375 @item @code{display} (default @code{":0"})
21376 The display on which to start the Xorg graphical server.
21378 @item @code{vt} (default @code{"vt7"})
21379 The VT on which to start the Xorg graphical server.
21381 @item @code{xauth} (default: @code{xauth})
21382 The XAuth package to use.
21384 @item @code{shepherd} (default: @code{shepherd})
21385 The Shepherd package used when invoking @command{halt} and
21388 @item @code{sessreg} (default: @code{sessreg})
21389 The sessreg package used in order to register the session.
21391 @item @code{slim} (default: @code{slim})
21392 The SLiM package to use.
21396 @defvr {Scheme Variable} %default-theme
21397 @defvrx {Scheme Variable} %default-theme-name
21398 The default SLiM theme and its name.
21402 @cindex login manager
21404 @defvr {Scheme Variable} sddm-service-type
21405 This is the type of the service to run the
21406 @uref{https://github.com/sddm/sddm,SDDM display manager}. Its value
21407 must be a @code{sddm-configuration} record (see below).
21409 Here's an example use:
21412 (service sddm-service-type
21413 (sddm-configuration
21414 (auto-login-user "alice")
21415 (auto-login-session "xfce.desktop")))
21419 @deftp {Data Type} sddm-configuration
21420 This data type represents the configuration of the SDDM login manager.
21421 The available fields are:
21424 @item @code{sddm} (default: @code{sddm})
21425 The SDDM package to use.
21427 @item @code{display-server} (default: "x11")
21428 Select display server to use for the greeter. Valid values are
21429 @samp{"x11"} or @samp{"wayland"}.
21431 @item @code{numlock} (default: "on")
21432 Valid values are @samp{"on"}, @samp{"off"} or @samp{"none"}.
21434 @item @code{halt-command} (default @code{#~(string-append #$shepherd "/sbin/halt")})
21435 Command to run when halting.
21437 @item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
21438 Command to run when rebooting.
21440 @item @code{theme} (default "maldives")
21441 Theme to use. Default themes provided by SDDM are @samp{"elarun"},
21442 @samp{"maldives"} or @samp{"maya"}.
21444 @item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
21445 Directory to look for themes.
21447 @item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
21448 Directory to look for faces.
21450 @item @code{default-path} (default "/run/current-system/profile/bin")
21451 Default PATH to use.
21453 @item @code{minimum-uid} (default: 1000)
21454 Minimum UID displayed in SDDM and allowed for log-in.
21456 @item @code{maximum-uid} (default: 2000)
21457 Maximum UID to display in SDDM.
21459 @item @code{remember-last-user?} (default #t)
21460 Remember last user.
21462 @item @code{remember-last-session?} (default #t)
21463 Remember last session.
21465 @item @code{hide-users} (default "")
21466 Usernames to hide from SDDM greeter.
21468 @item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
21469 Users with shells listed will be hidden from the SDDM greeter.
21471 @item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
21472 Script to run before starting a wayland session.
21474 @item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
21475 Directory to look for desktop files starting wayland sessions.
21477 @item @code{xorg-configuration} (default @code{(xorg-configuration)})
21478 Configuration of the Xorg graphical server.
21480 @item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
21483 @item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
21486 @item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
21487 Script to run after starting xorg-server.
21489 @item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
21490 Script to run before stopping xorg-server.
21492 @item @code{xsession-command} (default: @code{xinitrc})
21493 Script to run before starting a X session.
21495 @item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
21496 Directory to look for desktop files starting X sessions.
21498 @item @code{minimum-vt} (default: 7)
21501 @item @code{auto-login-user} (default "")
21502 User account that will be automatically logged in.
21503 Setting this to the empty string disables auto-login.
21505 @item @code{auto-login-session} (default "")
21506 The @file{.desktop} file name to use as the auto-login session, or the empty string.
21508 @item @code{relogin?} (default #f)
21509 Relogin after logout.
21514 @cindex lightdm, graphical login manager
21515 @cindex display manager, lightdm
21517 @defvr {Scheme Variable} lightdm-service-type
21518 This is the type of the service to run the
21519 @url{https://github.com/canonical/lightdm,LightDM display manager}. Its
21520 value must be a @code{lightdm-configuration} record, which is documented
21521 below. Among its distinguishing features are TigerVNC integration for
21522 easily remoting your desktop as well as support for the XDMCP protocol,
21523 which can be used by remote clients to start a session from the login
21526 In its most basic form, it can be used simply as:
21529 (service lightdm-service-type)
21532 A more elaborate example making use of the VNC capabilities and enabling
21533 more features and verbose logs could look like:
21536 (service lightdm-service-type
21537 (lightdm-configuration
21538 (allow-empty-passwords? #t)
21541 (vnc-server-command
21542 (file-append tigervnc-server "/bin/Xvnc"
21543 " -SecurityTypes None"))
21545 (list (lightdm-seat-configuration
21547 (user-session "ratpoison"))))))
21551 @c The LightDM service documentation can be auto-generated via the
21552 @c 'generate-doc' procedure at the bottom of the (gnu services lightdm)
21554 @c %start of fragment
21555 @deftp {Data Type} lightdm-configuration
21556 Available @code{lightdm-configuration} fields are:
21559 @item @code{lightdm} (default: @code{lightdm}) (type: file-like)
21560 The lightdm package to use.
21562 @item @code{allow-empty-passwords?} (default: @code{#f}) (type: boolean)
21563 Whether users not having a password set can login.
21565 @item @code{debug?} (default: @code{#f}) (type: boolean)
21566 Enable verbose output.
21568 @item @code{xorg-configuration} (type: xorg-configuration)
21569 The default Xorg server configuration to use to generate the Xorg server
21570 start script. It can be refined per seat via the @code{xserver-command}
21571 of the @code{<lightdm-seat-configuration>} record, if desired.
21573 @item @code{greeters} (type: list-of-greeter-configurations)
21574 The LightDM greeter configurations specifying the greeters to use.
21576 @item @code{seats} (type: list-of-seat-configurations)
21577 The seat configurations to use. A LightDM seat is akin to a user.
21579 @item @code{xdmcp?} (default: @code{#f}) (type: boolean)
21580 Whether a XDMCP server should listen on port UDP 177.
21582 @item @code{xdmcp-listen-address} (type: maybe-string)
21583 The host or IP address the XDMCP server listens for incoming
21584 connections. When unspecified, listen on for any hosts/IP addresses.
21586 @item @code{vnc-server?} (default: @code{#f}) (type: boolean)
21587 Whether a VNC server is started.
21589 @item @code{vnc-server-command} (type: file-like)
21590 The Xvnc command to use for the VNC server, it's possible to provide
21591 extra options not otherwise exposed along the command, for example to
21595 (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
21596 " -SecurityTypes None" ))
21599 Or to set a PasswordFile for the classic (unsecure) VncAuth
21603 (vnc-server-command (file-append tigervnc-server "/bin/Xvnc"
21604 " -PasswordFile /var/lib/lightdm/.vnc/passwd"))
21607 The password file should be manually created using the
21608 @command{vncpasswd} command. Note that LightDM will create new sessions
21609 for VNC users, which means they need to authenticate in the same way as
21612 @item @code{vnc-server-listen-address} (type: maybe-string)
21613 The host or IP address the VNC server listens for incoming connections.
21614 When unspecified, listen for any hosts/IP addresses.
21616 @item @code{vnc-server-port} (default: @code{5900}) (type: number)
21617 The TCP port the VNC server should listen to.
21619 @item @code{extra-config} (default: @code{()}) (type: list-of-strings)
21620 Extra configuration values to append to the LightDM configuration file.
21626 @c %end of fragment
21627 @c %start of fragment
21629 @deftp {Data Type} lightdm-gtk-greeter-configuration
21630 Available @code{lightdm-gtk-greeter-configuration} fields are:
21633 @item @code{lightdm-gtk-greeter} (default: @code{lightdm-gtk-greeter}) (type: file-like)
21634 The lightdm-gtk-greeter package to use.
21636 @item @code{assets} @
21637 (default: @code{(adwaita-icon-theme gnome-themes-extrahicolor-icon-theme)}) @
21638 (type: list-of-file-likes)
21639 The list of packages complementing the greeter, such as package
21640 providing icon themes.
21642 @item @code{theme-name} (default: @code{"Adwaita"}) (type: string)
21643 The name of the theme to use.
21645 @item @code{icon-theme-name} (default: @code{"Adwaita"}) (type: string)
21646 The name of the icon theme to use.
21648 @item @code{cursor-theme-name} (default: @code{"Adwaita"}) (type: string)
21649 The name of the cursor theme to use.
21651 @item @code{cursor-theme-size} (default: @code{16}) (type: number)
21652 The size to use for the cursor theme.
21654 @item @code{allow-debugging?} (type: maybe-boolean)
21655 Set to #t to enable debug log level.
21657 @item @code{background} (type: file-like)
21658 The background image to use.
21660 @item @code{at-spi-enabled?} (default: @code{#f}) (type: boolean)
21661 Enable accessibility support through the Assistive Technology Service
21662 Provider Interface (AT-SPI).
21664 @item @code{a11y-states} @
21665 (default: @code{(contrast font keyboard reader)}) (type: list-of-a11y-states)
21666 The accessibility features to enable, given as list of symbols.
21668 @item @code{reader} (type: maybe-file-like)
21669 The command to use to launch a screen reader.
21671 @item @code{extra-config} (default: @code{()}) (type: list-of-strings)
21672 Extra configuration values to append to the LightDM GTK Greeter
21673 configuration file.
21678 @c %end of fragment
21679 @c %start of fragment
21681 @deftp {Data Type} lightdm-seat-configuration
21682 Available @code{lightdm-seat-configuration} fields are:
21685 @item @code{name} (type: seat-name)
21686 The name of the seat. An asterisk (*) can be used in the name to apply
21687 the seat configuration to all the seat names it matches.
21689 @item @code{user-session} (type: maybe-string)
21690 The session to use by default. The session name must be provided as a
21691 lowercase string, such as @code{"gnome"}, @code{"ratpoison"}, etc.
21693 @item @code{type} (default: @code{local}) (type: seat-type)
21694 The type of the seat, either the @code{local} or @code{xremote} symbol.
21696 @item @code{autologin-user} (type: maybe-string)
21697 The username to automatically log in with by default.
21699 @item @code{greeter-session} @
21700 (default: @code{lightdm-gtk-greeter}) (type: greeter-session)
21701 The greeter session to use, specified as a symbol. Currently, only
21702 @code{lightdm-gtk-greeter} is supported.
21704 @item @code{xserver-command} (type: maybe-file-like)
21705 The Xorg server command to run.
21707 @item @code{session-wrapper} (type: file-like)
21708 The xinitrc session wrapper to use.
21710 @item @code{extra-config} (default: @code{()}) (type: list-of-strings)
21711 Extra configuration values to append to the seat configuration section.
21715 @c %end of fragment
21718 @cindex Xorg, configuration
21719 @deftp {Data Type} xorg-configuration
21720 This data type represents the configuration of the Xorg graphical
21721 display server. Note that there is no Xorg service; instead, the X
21722 server is started by a ``display manager'' such as GDM, SDDM, LightDM or
21723 SLiM@. Thus, the configuration of these display managers aggregates an
21724 @code{xorg-configuration} record.
21727 @item @code{modules} (default: @code{%default-xorg-modules})
21728 This is a list of @dfn{module packages} loaded by the Xorg
21729 server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so on.
21731 @item @code{fonts} (default: @code{%default-xorg-fonts})
21732 This is a list of font directories to add to the server's @dfn{font path}.
21734 @item @code{drivers} (default: @code{'()})
21735 This must be either the empty list, in which case Xorg chooses a graphics
21736 driver automatically, or a list of driver names that will be tried in this
21737 order---e.g., @code{("modesetting" "vesa")}.
21739 @item @code{resolutions} (default: @code{'()})
21740 When @code{resolutions} is the empty list, Xorg chooses an appropriate screen
21741 resolution. Otherwise, it must be a list of resolutions---e.g., @code{((1024
21744 @cindex keyboard layout, for Xorg
21745 @cindex keymap, for Xorg
21746 @item @code{keyboard-layout} (default: @code{#f})
21747 If this is @code{#f}, Xorg uses the default keyboard layout---usually US
21748 English (``qwerty'') for a 105-key PC keyboard.
21750 Otherwise this must be a @code{keyboard-layout} object specifying the keyboard
21751 layout in use when Xorg is running. @xref{Keyboard Layout}, for more
21752 information on how to specify the keyboard layout.
21754 @item @code{extra-config} (default: @code{'()})
21755 This is a list of strings or objects appended to the configuration file. It
21756 is used to pass extra text to be added verbatim to the configuration file.
21758 @item @code{server} (default: @code{xorg-server})
21759 This is the package providing the Xorg server.
21761 @item @code{server-arguments} (default: @code{%default-xorg-server-arguments})
21762 This is the list of command-line arguments to pass to the X server. The
21763 default is @code{-nolisten tcp}.
21767 @deffn {Scheme Procedure} set-xorg-configuration @var{config} @
21768 [@var{login-manager-service-type}]
21769 Tell the log-in manager (of type @var{login-manager-service-type}) to use
21770 @var{config}, an @code{<xorg-configuration>} record.
21772 Since the Xorg configuration is embedded in the log-in manager's
21773 configuration---e.g., @code{gdm-configuration}---this procedure provides a
21774 shorthand to set the Xorg configuration.
21777 @deffn {Scheme Procedure} xorg-start-command [@var{config}]
21778 Return a @code{startx} script in which the modules, fonts, etc. specified
21779 in @var{config}, are available. The result should be used in place of
21782 Usually the X server is started by a login manager.
21786 @deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
21787 Add @var{package}, a package for a screen locker or screen saver whose
21788 command is @var{program}, to the set of setuid programs and add a PAM entry
21789 for it. For example:
21792 (screen-locker-service xlockmore "xlock")
21795 makes the good ol' XlockMore usable.
21799 @node Printing Services
21800 @subsection Printing Services
21802 @cindex printer support with CUPS
21803 The @code{(gnu services cups)} module provides a Guix service definition
21804 for the CUPS printing service. To add printer support to a Guix
21805 system, add a @code{cups-service} to the operating system definition:
21807 @deffn {Scheme Variable} cups-service-type
21808 The service type for the CUPS print server. Its value should be a valid
21809 CUPS configuration (see below). To use the default settings, simply
21812 (service cups-service-type)
21816 The CUPS configuration controls the basic things about your CUPS
21817 installation: what interfaces it listens on, what to do if a print job
21818 fails, how much logging to do, and so on. To actually add a printer,
21819 you have to visit the @url{http://localhost:631} URL, or use a tool such
21820 as GNOME's printer configuration services. By default, configuring a
21821 CUPS service will generate a self-signed certificate if needed, for
21822 secure connections to the print server.
21824 Suppose you want to enable the Web interface of CUPS and also add
21825 support for Epson printers @i{via} the @code{epson-inkjet-printer-escpr}
21826 package and for HP printers @i{via} the @code{hplip-minimal} package.
21827 You can do that directly, like this (you need to use the
21828 @code{(gnu packages cups)} module):
21831 (service cups-service-type
21832 (cups-configuration
21833 (web-interface? #t)
21835 (list cups-filters epson-inkjet-printer-escpr hplip-minimal))))
21839 If you wish to use the Qt5 based GUI which comes with the hplip
21840 package then it is suggested that you install the @code{hplip} package,
21841 either in your OS configuration file or as your user.
21844 The available configuration parameters follow. Each parameter
21845 definition is preceded by its type; for example, @samp{string-list foo}
21846 indicates that the @code{foo} parameter should be specified as a list of
21847 strings. There is also a way to specify the configuration as a string,
21848 if you have an old @code{cupsd.conf} file that you want to port over
21849 from some other system; see the end for more details.
21851 @c The following documentation was initially generated by
21852 @c (generate-documentation) in (gnu services cups). Manually maintained
21853 @c documentation is better, so we shouldn't hesitate to edit below as
21854 @c needed. However if the change you want to make to this documentation
21855 @c can be done in an automated way, it's probably easier to change
21856 @c (generate-documentation) than to make it below and have to deal with
21857 @c the churn as CUPS updates.
21860 Available @code{cups-configuration} fields are:
21862 @deftypevr {@code{cups-configuration} parameter} package cups
21866 @deftypevr {@code{cups-configuration} parameter} package-list extensions (default: @code{(list brlaser cups-filters epson-inkjet-printer-escpr foomatic-filters hplip-minimal splix)})
21867 Drivers and other extensions to the CUPS package.
21870 @deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
21871 Configuration of where to write logs, what directories to use for print
21872 spools, and related privileged configuration parameters.
21874 Available @code{files-configuration} fields are:
21876 @deftypevr {@code{files-configuration} parameter} log-location access-log
21877 Defines the access log filename. Specifying a blank filename disables
21878 access log generation. The value @code{stderr} causes log entries to be
21879 sent to the standard error file when the scheduler is running in the
21880 foreground, or to the system log daemon when run in the background. The
21881 value @code{syslog} causes log entries to be sent to the system log
21882 daemon. The server name may be included in filenames using the string
21883 @code{%s}, as in @code{/var/log/cups/%s-access_log}.
21885 Defaults to @samp{"/var/log/cups/access_log"}.
21888 @deftypevr {@code{files-configuration} parameter} file-name cache-dir
21889 Where CUPS should cache data.
21891 Defaults to @samp{"/var/cache/cups"}.
21894 @deftypevr {@code{files-configuration} parameter} string config-file-perm
21895 Specifies the permissions for all configuration files that the scheduler
21898 Note that the permissions for the printers.conf file are currently
21899 masked to only allow access from the scheduler user (typically root).
21900 This is done because printer device URIs sometimes contain sensitive
21901 authentication information that should not be generally known on the
21902 system. There is no way to disable this security feature.
21904 Defaults to @samp{"0640"}.
21907 @deftypevr {@code{files-configuration} parameter} log-location error-log
21908 Defines the error log filename. Specifying a blank filename disables
21909 error log generation. The value @code{stderr} causes log entries to be
21910 sent to the standard error file when the scheduler is running in the
21911 foreground, or to the system log daemon when run in the background. The
21912 value @code{syslog} causes log entries to be sent to the system log
21913 daemon. The server name may be included in filenames using the string
21914 @code{%s}, as in @code{/var/log/cups/%s-error_log}.
21916 Defaults to @samp{"/var/log/cups/error_log"}.
21919 @deftypevr {@code{files-configuration} parameter} string fatal-errors
21920 Specifies which errors are fatal, causing the scheduler to exit. The
21925 No errors are fatal.
21928 All of the errors below are fatal.
21931 Browsing initialization errors are fatal, for example failed connections
21932 to the DNS-SD daemon.
21935 Configuration file syntax errors are fatal.
21938 Listen or Port errors are fatal, except for IPv6 failures on the
21939 loopback or @code{any} addresses.
21942 Log file creation or write errors are fatal.
21945 Bad startup file permissions are fatal, for example shared TLS
21946 certificate and key files with world-read permissions.
21949 Defaults to @samp{"all -browse"}.
21952 @deftypevr {@code{files-configuration} parameter} boolean file-device?
21953 Specifies whether the file pseudo-device can be used for new printer
21954 queues. The URI @uref{file:///dev/null} is always allowed.
21956 Defaults to @samp{#f}.
21959 @deftypevr {@code{files-configuration} parameter} string group
21960 Specifies the group name or ID that will be used when executing external
21963 Defaults to @samp{"lp"}.
21966 @deftypevr {@code{files-configuration} parameter} string log-file-group
21967 Specifies the group name or ID that will be used for log files.
21969 Defaults to @samp{"lpadmin"}.
21972 @deftypevr {@code{files-configuration} parameter} string log-file-perm
21973 Specifies the permissions for all log files that the scheduler writes.
21975 Defaults to @samp{"0644"}.
21978 @deftypevr {@code{files-configuration} parameter} log-location page-log
21979 Defines the page log filename. Specifying a blank filename disables
21980 page log generation. The value @code{stderr} causes log entries to be
21981 sent to the standard error file when the scheduler is running in the
21982 foreground, or to the system log daemon when run in the background. The
21983 value @code{syslog} causes log entries to be sent to the system log
21984 daemon. The server name may be included in filenames using the string
21985 @code{%s}, as in @code{/var/log/cups/%s-page_log}.
21987 Defaults to @samp{"/var/log/cups/page_log"}.
21990 @deftypevr {@code{files-configuration} parameter} string remote-root
21991 Specifies the username that is associated with unauthenticated accesses
21992 by clients claiming to be the root user. The default is @code{remroot}.
21994 Defaults to @samp{"remroot"}.
21997 @deftypevr {@code{files-configuration} parameter} file-name request-root
21998 Specifies the directory that contains print jobs and other HTTP request
22001 Defaults to @samp{"/var/spool/cups"}.
22004 @deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
22005 Specifies the level of security sandboxing that is applied to print
22006 filters, backends, and other child processes of the scheduler; either
22007 @code{relaxed} or @code{strict}. This directive is currently only
22008 used/supported on macOS.
22010 Defaults to @samp{strict}.
22013 @deftypevr {@code{files-configuration} parameter} file-name server-keychain
22014 Specifies the location of TLS certificates and private keys. CUPS will
22015 look for public and private keys in this directory: @file{.crt} files
22016 for PEM-encoded certificates and corresponding @file{.key} files for
22017 PEM-encoded private keys.
22019 Defaults to @samp{"/etc/cups/ssl"}.
22022 @deftypevr {@code{files-configuration} parameter} file-name server-root
22023 Specifies the directory containing the server configuration files.
22025 Defaults to @samp{"/etc/cups"}.
22028 @deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
22029 Specifies whether the scheduler calls fsync(2) after writing
22030 configuration or state files.
22032 Defaults to @samp{#f}.
22035 @deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
22036 Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
22039 @deftypevr {@code{files-configuration} parameter} file-name temp-dir
22040 Specifies the directory where temporary files are stored.
22042 Defaults to @samp{"/var/spool/cups/tmp"}.
22045 @deftypevr {@code{files-configuration} parameter} string user
22046 Specifies the user name or ID that is used when running external
22049 Defaults to @samp{"lp"}.
22052 @deftypevr {@code{files-configuration} parameter} string set-env
22053 Set the specified environment variable to be passed to child processes.
22055 Defaults to @samp{"variable value"}.
22059 @deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
22060 Specifies the logging level for the AccessLog file. The @code{config}
22061 level logs when printers and classes are added, deleted, or modified and
22062 when configuration files are accessed or updated. The @code{actions}
22063 level logs when print jobs are submitted, held, released, modified, or
22064 canceled, and any of the conditions for @code{config}. The @code{all}
22065 level logs all requests.
22067 Defaults to @samp{actions}.
22070 @deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
22071 Specifies whether to purge job history data automatically when it is no
22072 longer required for quotas.
22074 Defaults to @samp{#f}.
22077 @deftypevr {@code{cups-configuration} parameter} comma-separated-string-list browse-dns-sd-sub-types
22078 Specifies a list of DNS-SD sub-types to advertise for each shared printer.
22079 For example, @samp{"_cups" "_print"} will tell network clients that both
22080 CUPS sharing and IPP Everywhere are supported.
22082 Defaults to @samp{"_cups"}.
22085 @deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
22086 Specifies which protocols to use for local printer sharing.
22088 Defaults to @samp{dnssd}.
22091 @deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
22092 Specifies whether the CUPS web interface is advertised.
22094 Defaults to @samp{#f}.
22097 @deftypevr {@code{cups-configuration} parameter} boolean browsing?
22098 Specifies whether shared printers are advertised.
22100 Defaults to @samp{#f}.
22103 @deftypevr {@code{cups-configuration} parameter} string classification
22104 Specifies the security classification of the server. Any valid banner
22105 name can be used, including @samp{"classified"}, @samp{"confidential"},
22106 @samp{"secret"}, @samp{"topsecret"}, and @samp{"unclassified"}, or the
22107 banner can be omitted to disable secure printing functions.
22109 Defaults to @samp{""}.
22112 @deftypevr {@code{cups-configuration} parameter} boolean classify-override?
22113 Specifies whether users may override the classification (cover page) of
22114 individual print jobs using the @code{job-sheets} option.
22116 Defaults to @samp{#f}.
22119 @deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
22120 Specifies the default type of authentication to use.
22122 Defaults to @samp{Basic}.
22125 @deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
22126 Specifies whether encryption will be used for authenticated requests.
22128 Defaults to @samp{Required}.
22131 @deftypevr {@code{cups-configuration} parameter} string default-language
22132 Specifies the default language to use for text and web content.
22134 Defaults to @samp{"en"}.
22137 @deftypevr {@code{cups-configuration} parameter} string default-paper-size
22138 Specifies the default paper size for new print queues. @samp{"Auto"}
22139 uses a locale-specific default, while @samp{"None"} specifies there is
22140 no default paper size. Specific size names are typically
22141 @samp{"Letter"} or @samp{"A4"}.
22143 Defaults to @samp{"Auto"}.
22146 @deftypevr {@code{cups-configuration} parameter} string default-policy
22147 Specifies the default access policy to use.
22149 Defaults to @samp{"default"}.
22152 @deftypevr {@code{cups-configuration} parameter} boolean default-shared?
22153 Specifies whether local printers are shared by default.
22155 Defaults to @samp{#t}.
22158 @deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
22159 Specifies the delay for updating of configuration and state files, in
22160 seconds. A value of 0 causes the update to happen as soon as possible,
22161 typically within a few milliseconds.
22163 Defaults to @samp{30}.
22166 @deftypevr {@code{cups-configuration} parameter} error-policy error-policy
22167 Specifies what to do when an error occurs. Possible values are
22168 @code{abort-job}, which will discard the failed print job;
22169 @code{retry-job}, which will retry the job at a later time;
22170 @code{retry-current-job}, which retries the failed job immediately; and
22171 @code{stop-printer}, which stops the printer.
22173 Defaults to @samp{stop-printer}.
22176 @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
22177 Specifies the maximum cost of filters that are run concurrently, which
22178 can be used to minimize disk, memory, and CPU resource problems. A
22179 limit of 0 disables filter limiting. An average print to a
22180 non-PostScript printer needs a filter limit of about 200. A PostScript
22181 printer needs about half that (100). Setting the limit below these
22182 thresholds will effectively limit the scheduler to printing a single job
22185 Defaults to @samp{0}.
22188 @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
22189 Specifies the scheduling priority of filters that are run to print a
22190 job. The nice value ranges from 0, the highest priority, to 19, the
22193 Defaults to @samp{0}.
22196 @deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
22197 Specifies whether to do reverse lookups on connecting clients. The
22198 @code{double} setting causes @code{cupsd} to verify that the hostname
22199 resolved from the address matches one of the addresses returned for that
22200 hostname. Double lookups also prevent clients with unregistered
22201 addresses from connecting to your server. Only set this option to
22202 @code{#t} or @code{double} if absolutely required.
22204 Defaults to @samp{#f}.
22207 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
22208 Specifies the number of seconds to wait before killing the filters and
22209 backend associated with a canceled or held job.
22211 Defaults to @samp{30}.
22214 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
22215 Specifies the interval between retries of jobs in seconds. This is
22216 typically used for fax queues but can also be used with normal print
22217 queues whose error policy is @code{retry-job} or
22218 @code{retry-current-job}.
22220 Defaults to @samp{30}.
22223 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
22224 Specifies the number of retries that are done for jobs. This is
22225 typically used for fax queues but can also be used with normal print
22226 queues whose error policy is @code{retry-job} or
22227 @code{retry-current-job}.
22229 Defaults to @samp{5}.
22232 @deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
22233 Specifies whether to support HTTP keep-alive connections.
22235 Defaults to @samp{#t}.
22238 @deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
22239 Specifies the maximum size of print files, IPP requests, and HTML form
22240 data. A limit of 0 disables the limit check.
22242 Defaults to @samp{0}.
22245 @deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
22246 Listens on the specified interfaces for connections. Valid values are
22247 of the form @var{address}:@var{port}, where @var{address} is either an
22248 IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to
22249 indicate all addresses. Values can also be file names of local UNIX
22250 domain sockets. The Listen directive is similar to the Port directive
22251 but allows you to restrict access to specific interfaces or networks.
22254 @deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
22255 Specifies the number of pending connections that will be allowed. This
22256 normally only affects very busy servers that have reached the MaxClients
22257 limit, but can also be triggered by large numbers of simultaneous
22258 connections. When the limit is reached, the operating system will
22259 refuse additional connections until the scheduler can accept the pending
22262 Defaults to @samp{128}.
22265 @deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
22266 Specifies a set of additional access controls.
22268 Available @code{location-access-controls} fields are:
22270 @deftypevr {@code{location-access-controls} parameter} file-name path
22271 Specifies the URI path to which the access control applies.
22274 @deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
22275 Access controls for all access to this path, in the same format as the
22276 @code{access-controls} of @code{operation-access-control}.
22278 Defaults to @samp{()}.
22281 @deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
22282 Access controls for method-specific access to this path.
22284 Defaults to @samp{()}.
22286 Available @code{method-access-controls} fields are:
22288 @deftypevr {@code{method-access-controls} parameter} boolean reverse?
22289 If @code{#t}, apply access controls to all methods except the listed
22290 methods. Otherwise apply to only the listed methods.
22292 Defaults to @samp{#f}.
22295 @deftypevr {@code{method-access-controls} parameter} method-list methods
22296 Methods to which this access control applies.
22298 Defaults to @samp{()}.
22301 @deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
22302 Access control directives, as a list of strings. Each string should be
22303 one directive, such as @samp{"Order allow,deny"}.
22305 Defaults to @samp{()}.
22310 @deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
22311 Specifies the number of debugging messages that are retained for logging
22312 if an error occurs in a print job. Debug messages are logged regardless
22313 of the LogLevel setting.
22315 Defaults to @samp{100}.
22318 @deftypevr {@code{cups-configuration} parameter} log-level log-level
22319 Specifies the level of logging for the ErrorLog file. The value
22320 @code{none} stops all logging while @code{debug2} logs everything.
22322 Defaults to @samp{info}.
22325 @deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
22326 Specifies the format of the date and time in the log files. The value
22327 @code{standard} logs whole seconds while @code{usecs} logs microseconds.
22329 Defaults to @samp{standard}.
22332 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
22333 Specifies the maximum number of simultaneous clients that are allowed by
22336 Defaults to @samp{100}.
22339 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
22340 Specifies the maximum number of simultaneous clients that are allowed
22341 from a single address.
22343 Defaults to @samp{100}.
22346 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
22347 Specifies the maximum number of copies that a user can print of each
22350 Defaults to @samp{9999}.
22353 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
22354 Specifies the maximum time a job may remain in the @code{indefinite}
22355 hold state before it is canceled. A value of 0 disables cancellation of
22358 Defaults to @samp{0}.
22361 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
22362 Specifies the maximum number of simultaneous jobs that are allowed. Set
22363 to 0 to allow an unlimited number of jobs.
22365 Defaults to @samp{500}.
22368 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
22369 Specifies the maximum number of simultaneous jobs that are allowed per
22370 printer. A value of 0 allows up to MaxJobs jobs per printer.
22372 Defaults to @samp{0}.
22375 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
22376 Specifies the maximum number of simultaneous jobs that are allowed per
22377 user. A value of 0 allows up to MaxJobs jobs per user.
22379 Defaults to @samp{0}.
22382 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
22383 Specifies the maximum time a job may take to print before it is
22384 canceled, in seconds. Set to 0 to disable cancellation of ``stuck'' jobs.
22386 Defaults to @samp{10800}.
22389 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
22390 Specifies the maximum size of the log files before they are rotated, in
22391 bytes. The value 0 disables log rotation.
22393 Defaults to @samp{1048576}.
22396 @deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
22397 Specifies the maximum amount of time to allow between files in a
22398 multiple file print job, in seconds.
22400 Defaults to @samp{900}.
22403 @deftypevr {@code{cups-configuration} parameter} string page-log-format
22404 Specifies the format of PageLog lines. Sequences beginning with percent
22405 (@samp{%}) characters are replaced with the corresponding information,
22406 while all other characters are copied literally. The following percent
22407 sequences are recognized:
22411 insert a single percent character
22414 insert the value of the specified IPP attribute
22417 insert the number of copies for the current page
22420 insert the current page number
22423 insert the current date and time in common log format
22429 insert the printer name
22432 insert the username
22435 A value of the empty string disables page logging. The string @code{%p
22436 %u %j %T %P %C %@{job-billing@} %@{job-originating-host-name@}
22437 %@{job-name@} %@{media@} %@{sides@}} creates a page log with the
22440 Defaults to @samp{""}.
22443 @deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
22444 Passes the specified environment variable(s) to child processes; a list
22447 Defaults to @samp{()}.
22450 @deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
22451 Specifies named access control policies.
22453 Available @code{policy-configuration} fields are:
22455 @deftypevr {@code{policy-configuration} parameter} string name
22456 Name of the policy.
22459 @deftypevr {@code{policy-configuration} parameter} string job-private-access
22460 Specifies an access list for a job's private values. @code{@@ACL} maps
22461 to the printer's requesting-user-name-allowed or
22462 requesting-user-name-denied values. @code{@@OWNER} maps to the job's
22463 owner. @code{@@SYSTEM} maps to the groups listed for the
22464 @code{system-group} field of the @code{files-configuration},
22465 which is reified into the @code{cups-files.conf(5)} file. Other
22466 possible elements of the access list include specific user names, and
22467 @code{@@@var{group}} to indicate members of a specific group. The
22468 access list may also be simply @code{all} or @code{default}.
22470 Defaults to @samp{"@@OWNER @@SYSTEM"}.
22473 @deftypevr {@code{policy-configuration} parameter} string job-private-values
22474 Specifies the list of job values to make private, or @code{all},
22475 @code{default}, or @code{none}.
22477 Defaults to @samp{"job-name job-originating-host-name
22478 job-originating-user-name phone"}.
22481 @deftypevr {@code{policy-configuration} parameter} string subscription-private-access
22482 Specifies an access list for a subscription's private values.
22483 @code{@@ACL} maps to the printer's requesting-user-name-allowed or
22484 requesting-user-name-denied values. @code{@@OWNER} maps to the job's
22485 owner. @code{@@SYSTEM} maps to the groups listed for the
22486 @code{system-group} field of the @code{files-configuration},
22487 which is reified into the @code{cups-files.conf(5)} file. Other
22488 possible elements of the access list include specific user names, and
22489 @code{@@@var{group}} to indicate members of a specific group. The
22490 access list may also be simply @code{all} or @code{default}.
22492 Defaults to @samp{"@@OWNER @@SYSTEM"}.
22495 @deftypevr {@code{policy-configuration} parameter} string subscription-private-values
22496 Specifies the list of job values to make private, or @code{all},
22497 @code{default}, or @code{none}.
22499 Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
22500 notify-subscriber-user-name notify-user-data"}.
22503 @deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
22504 Access control by IPP operation.
22506 Defaults to @samp{()}.
22510 @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
22511 Specifies whether job files (documents) are preserved after a job is
22512 printed. If a numeric value is specified, job files are preserved for
22513 the indicated number of seconds after printing. Otherwise a boolean
22514 value applies indefinitely.
22516 Defaults to @samp{86400}.
22519 @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
22520 Specifies whether the job history is preserved after a job is printed.
22521 If a numeric value is specified, the job history is preserved for the
22522 indicated number of seconds after printing. If @code{#t}, the job
22523 history is preserved until the MaxJobs limit is reached.
22525 Defaults to @samp{#t}.
22528 @deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
22529 Specifies the amount of time to wait for job completion before
22530 restarting the scheduler.
22532 Defaults to @samp{30}.
22535 @deftypevr {@code{cups-configuration} parameter} string rip-cache
22536 Specifies the maximum amount of memory to use when converting documents
22537 into bitmaps for a printer.
22539 Defaults to @samp{"128m"}.
22542 @deftypevr {@code{cups-configuration} parameter} string server-admin
22543 Specifies the email address of the server administrator.
22545 Defaults to @samp{"root@@localhost.localdomain"}.
22548 @deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
22549 The ServerAlias directive is used for HTTP Host header validation when
22550 clients connect to the scheduler from external interfaces. Using the
22551 special name @code{*} can expose your system to known browser-based DNS
22552 rebinding attacks, even when accessing sites through a firewall. If the
22553 auto-discovery of alternate names does not work, we recommend listing
22554 each alternate name with a ServerAlias directive instead of using
22557 Defaults to @samp{*}.
22560 @deftypevr {@code{cups-configuration} parameter} string server-name
22561 Specifies the fully-qualified host name of the server.
22563 Defaults to @samp{"localhost"}.
22566 @deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
22567 Specifies what information is included in the Server header of HTTP
22568 responses. @code{None} disables the Server header. @code{ProductOnly}
22569 reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
22570 reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
22571 @code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is
22572 the output of the @code{uname} command. @code{Full} reports @code{CUPS
22573 2.0.0 (@var{uname}) IPP/2.0}.
22575 Defaults to @samp{Minimal}.
22578 @deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
22579 Listens on the specified interfaces for encrypted connections. Valid
22580 values are of the form @var{address}:@var{port}, where @var{address} is
22581 either an IPv6 address enclosed in brackets, an IPv4 address, or
22582 @code{*} to indicate all addresses.
22584 Defaults to @samp{()}.
22587 @deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
22588 Sets encryption options. By default, CUPS only supports encryption
22589 using TLS v1.0 or higher using known secure cipher suites. Security is
22590 reduced when @code{Allow} options are used, and enhanced when @code{Deny}
22591 options are used. The @code{AllowRC4} option enables the 128-bit RC4 cipher
22592 suites, which are required for some older clients. The @code{AllowSSL3} option
22593 enables SSL v3.0, which is required for some older clients that do not support
22594 TLS v1.0. The @code{DenyCBC} option disables all CBC cipher suites. The
22595 @code{DenyTLS1.0} option disables TLS v1.0 support - this sets the minimum
22596 protocol version to TLS v1.1.
22598 Defaults to @samp{()}.
22601 @deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
22602 Specifies whether the scheduler requires clients to strictly adhere to
22603 the IPP specifications.
22605 Defaults to @samp{#f}.
22608 @deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
22609 Specifies the HTTP request timeout, in seconds.
22611 Defaults to @samp{900}.
22615 @deftypevr {@code{cups-configuration} parameter} boolean web-interface?
22616 Specifies whether the web interface is enabled.
22618 Defaults to @samp{#f}.
22621 At this point you're probably thinking ``oh dear, Guix manual, I like
22622 you but you can stop already with the configuration options''. Indeed.
22623 However, one more point: it could be that you have an existing
22624 @code{cupsd.conf} that you want to use. In that case, you can pass an
22625 @code{opaque-cups-configuration} as the configuration of a
22626 @code{cups-service-type}.
22628 Available @code{opaque-cups-configuration} fields are:
22630 @deftypevr {@code{opaque-cups-configuration} parameter} package cups
22634 @deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
22635 The contents of the @code{cupsd.conf}, as a string.
22638 @deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
22639 The contents of the @code{cups-files.conf} file, as a string.
22642 For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
22643 strings of the same name, you could instantiate a CUPS service like
22647 (service cups-service-type
22648 (opaque-cups-configuration
22649 (cupsd.conf cupsd.conf)
22650 (cups-files.conf cups-files.conf)))
22654 @node Desktop Services
22655 @subsection Desktop Services
22657 The @code{(gnu services desktop)} module provides services that are
22658 usually useful in the context of a ``desktop'' setup---that is, on a
22659 machine running a graphical display server, possibly with graphical user
22660 interfaces, etc. It also defines services that provide specific desktop
22661 environments like GNOME, Xfce or MATE.
22663 To simplify things, the module defines a variable containing the set of
22664 services that users typically expect on a machine with a graphical
22665 environment and networking:
22667 @defvr {Scheme Variable} %desktop-services
22668 This is a list of services that builds upon @code{%base-services} and
22669 adds or adjusts services for a typical ``desktop'' setup.
22671 In particular, it adds a graphical login manager (@pxref{X Window,
22672 @code{gdm-service-type}}), screen lockers, a network management tool
22673 (@pxref{Networking Services, @code{network-manager-service-type}}) with modem
22674 support (@pxref{Networking Services, @code{modem-manager-service-type}}),
22675 energy and color management services, the @code{elogind} login and seat
22676 manager, the Polkit privilege service, the GeoClue location service, the
22677 AccountsService daemon that allows authorized users change system passwords,
22678 an NTP client (@pxref{Networking Services}), the Avahi daemon, and has the
22679 name service switch service configured to be able to use @code{nss-mdns}
22680 (@pxref{Name Service Switch, mDNS}).
22683 The @code{%desktop-services} variable can be used as the @code{services}
22684 field of an @code{operating-system} declaration (@pxref{operating-system
22685 Reference, @code{services}}).
22687 Additionally, the @code{gnome-desktop-service-type},
22688 @code{xfce-desktop-service}, @code{mate-desktop-service-type},
22689 @code{lxqt-desktop-service-type} and @code{enlightenment-desktop-service-type}
22690 procedures can add GNOME, Xfce, MATE and/or Enlightenment to a system. To
22691 ``add GNOME'' means that system-level services like the backlight adjustment
22692 helpers and the power management utilities are added to the system, extending
22693 @code{polkit} and @code{dbus} appropriately, allowing GNOME to operate with
22694 elevated privileges on a limited number of special-purpose system interfaces.
22695 Additionally, adding a service made by @code{gnome-desktop-service-type} adds
22696 the GNOME metapackage to the system profile. Likewise, adding the Xfce
22697 service not only adds the @code{xfce} metapackage to the system profile, but
22698 it also gives the Thunar file manager the ability to open a ``root-mode'' file
22699 management window, if the user authenticates using the administrator's
22700 password via the standard polkit graphical interface. To ``add MATE'' means
22701 that @code{polkit} and @code{dbus} are extended appropriately, allowing MATE
22702 to operate with elevated privileges on a limited number of special-purpose
22703 system interfaces. Additionally, adding a service of type
22704 @code{mate-desktop-service-type} adds the MATE metapackage to the system
22705 profile. ``Adding Enlightenment'' means that @code{dbus} is extended
22706 appropriately, and several of Enlightenment's binaries are set as setuid,
22707 allowing Enlightenment's screen locker and other functionality to work as
22710 The desktop environments in Guix use the Xorg display server by
22711 default. If you'd like to use the newer display server protocol
22712 called Wayland, you need to enable Wayland support in GDM
22713 (@pxref{wayland-gdm}). Another solution is to use the
22714 @code{sddm-service} instead of GDM as the graphical login manager.
22715 You should then select the ``GNOME (Wayland)'' session in SDDM@.
22716 Alternatively you can also try starting GNOME on Wayland manually from a
22717 TTY with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session
22718 gnome-session``. Currently only GNOME has support for Wayland.
22720 @defvr {Scheme Variable} gnome-desktop-service-type
22721 This is the type of the service that adds the @uref{https://www.gnome.org,
22722 GNOME} desktop environment. Its value is a @code{gnome-desktop-configuration}
22723 object (see below).
22725 This service adds the @code{gnome} package to the system profile, and extends
22726 polkit with the actions from @code{gnome-settings-daemon}.
22729 @deftp {Data Type} gnome-desktop-configuration
22730 Configuration record for the GNOME desktop environment.
22733 @item @code{gnome} (default: @code{gnome})
22734 The GNOME package to use.
22738 @defvr {Scheme Variable} xfce-desktop-service-type
22739 This is the type of a service to run the @uref{Xfce, https://xfce.org/}
22740 desktop environment. Its value is an @code{xfce-desktop-configuration} object
22743 This service adds the @code{xfce} package to the system profile, and
22744 extends polkit with the ability for @code{thunar} to manipulate the file
22745 system as root from within a user session, after the user has authenticated
22746 with the administrator's password.
22748 Note that @code{xfce4-panel} and its plugin packages should be installed in
22749 the same profile to ensure compatibility. When using this service, you should
22750 add extra plugins (@code{xfce4-whiskermenu-plugin},
22751 @code{xfce4-weather-plugin}, etc.) to the @code{packages} field of your
22752 @code{operating-system}.
22755 @deftp {Data Type} xfce-desktop-configuration
22756 Configuration record for the Xfce desktop environment.
22759 @item @code{xfce} (default: @code{xfce})
22760 The Xfce package to use.
22764 @deffn {Scheme Variable} mate-desktop-service-type
22765 This is the type of the service that runs the @uref{https://mate-desktop.org/,
22766 MATE desktop environment}. Its value is a @code{mate-desktop-configuration}
22767 object (see below).
22769 This service adds the @code{mate} package to the system
22770 profile, and extends polkit with the actions from
22771 @code{mate-settings-daemon}.
22774 @deftp {Data Type} mate-desktop-configuration
22775 Configuration record for the MATE desktop environment.
22778 @item @code{mate} (default: @code{mate})
22779 The MATE package to use.
22783 @deffn {Scheme Variable} lxqt-desktop-service-type
22784 This is the type of the service that runs the @uref{https://lxqt-project.org,
22785 LXQt desktop environment}. Its value is a @code{lxqt-desktop-configuration}
22786 object (see below).
22788 This service adds the @code{lxqt} package to the system
22792 @deftp {Data Type} lxqt-desktop-configuration
22793 Configuration record for the LXQt desktop environment.
22796 @item @code{lxqt} (default: @code{lxqt})
22797 The LXQT package to use.
22801 @deffn {Scheme Variable} enlightenment-desktop-service-type
22802 Return a service that adds the @code{enlightenment} package to the system
22803 profile, and extends dbus with actions from @code{efl}.
22806 @deftp {Data Type} enlightenment-desktop-service-configuration
22808 @item @code{enlightenment} (default: @code{enlightenment})
22809 The enlightenment package to use.
22813 Because the GNOME, Xfce and MATE desktop services pull in so many packages,
22814 the default @code{%desktop-services} variable doesn't include any of
22815 them by default. To add GNOME, Xfce or MATE, just @code{cons} them onto
22816 @code{%desktop-services} in the @code{services} field of your
22817 @code{operating-system}:
22820 (use-modules (gnu))
22821 (use-service-modules desktop)
22824 ;; cons* adds items to the list given as its last argument.
22825 (services (cons* (service gnome-desktop-service-type)
22826 (service xfce-desktop-service)
22827 %desktop-services))
22831 These desktop environments will then be available as options in the
22832 graphical login window.
22834 The actual service definitions included in @code{%desktop-services} and
22835 provided by @code{(gnu services dbus)} and @code{(gnu services desktop)}
22836 are described below.
22838 @deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] @
22840 Return a service that runs the ``system bus'', using @var{dbus}, with
22841 support for @var{services}. When @var{verbose?} is true, it causes the
22842 @samp{DBUS_VERBOSE} environment variable to be set to @samp{1}; a
22843 verbose-enabled D-Bus package such as @code{dbus-verbose} should be
22844 provided as @var{dbus} in this scenario. The verbose output is logged
22845 to @file{/var/log/dbus-daemon.log}.
22847 @uref{https://dbus.freedesktop.org/, D-Bus} is an inter-process communication
22848 facility. Its system bus is used to allow system services to communicate
22849 and to be notified of system-wide events.
22851 @var{services} must be a list of packages that provide an
22852 @file{etc/dbus-1/system.d} directory containing additional D-Bus configuration
22853 and policy files. For example, to allow avahi-daemon to use the system bus,
22854 @var{services} must be equal to @code{(list avahi)}.
22857 @deffn {Scheme Procedure} elogind-service [#:config @var{config}]
22858 Return a service that runs the @code{elogind} login and
22859 seat management daemon. @uref{https://github.com/elogind/elogind,
22860 Elogind} exposes a D-Bus interface that can be used to know which users
22861 are logged in, know what kind of sessions they have open, suspend the
22862 system, inhibit system suspend, reboot the system, and other tasks.
22864 Elogind handles most system-level power events for a computer, for
22865 example suspending the system when a lid is closed, or shutting it down
22866 when the power button is pressed.
22868 The @var{config} keyword argument specifies the configuration for
22869 elogind, and should be the result of an @code{(elogind-configuration
22870 (@var{parameter} @var{value})...)} invocation. Available parameters and
22871 their default values are:
22874 @item kill-user-processes?
22876 @item kill-only-users
22878 @item kill-exclude-users
22880 @item inhibit-delay-max-seconds
22882 @item handle-power-key
22884 @item handle-suspend-key
22886 @item handle-hibernate-key
22888 @item handle-lid-switch
22890 @item handle-lid-switch-docked
22892 @item handle-lid-switch-external-power
22893 @code{*unspecified*}
22894 @item power-key-ignore-inhibited?
22896 @item suspend-key-ignore-inhibited?
22898 @item hibernate-key-ignore-inhibited?
22900 @item lid-switch-ignore-inhibited?
22902 @item holdoff-timeout-seconds
22906 @item idle-action-seconds
22908 @item runtime-directory-size-percent
22910 @item runtime-directory-size
22914 @item suspend-state
22915 @code{("mem" "standby" "freeze")}
22918 @item hibernate-state
22920 @item hibernate-mode
22921 @code{("platform" "shutdown")}
22922 @item hybrid-sleep-state
22924 @item hybrid-sleep-mode
22925 @code{("suspend" "platform" "shutdown")}
22929 @deffn {Scheme Procedure} accountsservice-service @
22930 [#:accountsservice @var{accountsservice}]
22931 Return a service that runs AccountsService, a system service that can
22932 list available accounts, change their passwords, and so on.
22933 AccountsService integrates with PolicyKit to enable unprivileged users
22934 to acquire the capability to modify their system configuration.
22935 @uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
22936 accountsservice web site} for more information.
22938 The @var{accountsservice} keyword argument is the @code{accountsservice}
22939 package to expose as a service.
22942 @deffn {Scheme Procedure} polkit-service @
22943 [#:polkit @var{polkit}]
22944 Return a service that runs the
22945 @uref{https://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
22946 management service}, which allows system administrators to grant access to
22947 privileged operations in a structured way. By querying the Polkit service, a
22948 privileged system component can know when it should grant additional
22949 capabilities to ordinary users. For example, an ordinary user can be granted
22950 the capability to suspend the system if the user is logged in locally.
22953 @defvr {Scheme Variable} polkit-wheel-service
22954 Service that adds the @code{wheel} group as admins to the Polkit
22955 service. This makes it so that users in the @code{wheel} group are queried
22956 for their own passwords when performing administrative actions instead of
22957 @code{root}'s, similar to the behaviour used by @code{sudo}.
22960 @defvr {Scheme Variable} upower-service-type
22961 Service that runs @uref{https://upower.freedesktop.org/, @command{upowerd}}, a
22962 system-wide monitor for power consumption and battery levels, with the given
22963 configuration settings.
22965 It implements the @code{org.freedesktop.UPower} D-Bus interface, and is
22966 notably used by GNOME.
22969 @deftp {Data Type} upower-configuration
22970 Data type representation the configuration for UPower.
22974 @item @code{upower} (default: @var{upower})
22975 Package to use for @code{upower}.
22977 @item @code{watts-up-pro?} (default: @code{#f})
22978 Enable the Watts Up Pro device.
22980 @item @code{poll-batteries?} (default: @code{#t})
22981 Enable polling the kernel for battery level changes.
22983 @item @code{ignore-lid?} (default: @code{#f})
22984 Ignore the lid state, this can be useful if it's incorrect on a device.
22986 @item @code{use-percentage-for-policy?} (default: @code{#t})
22987 Whether to use a policy based on battery percentage rather than on
22988 estimated time left. A policy based on battery percentage is usually
22991 @item @code{percentage-low} (default: @code{20})
22992 When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
22993 at which the battery is considered low.
22995 @item @code{percentage-critical} (default: @code{5})
22996 When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
22997 at which the battery is considered critical.
22999 @item @code{percentage-action} (default: @code{2})
23000 When @code{use-percentage-for-policy?} is @code{#t}, this sets the percentage
23001 at which action will be taken.
23003 @item @code{time-low} (default: @code{1200})
23004 When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
23005 seconds at which the battery is considered low.
23007 @item @code{time-critical} (default: @code{300})
23008 When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
23009 seconds at which the battery is considered critical.
23011 @item @code{time-action} (default: @code{120})
23012 When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining in
23013 seconds at which action will be taken.
23015 @item @code{critical-power-action} (default: @code{'hybrid-sleep})
23016 The action taken when @code{percentage-action} or @code{time-action} is
23017 reached (depending on the configuration of @code{use-percentage-for-policy?}).
23019 Possible values are:
23029 @code{'hybrid-sleep}.
23035 @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
23036 Return a service for @uref{https://udisks.freedesktop.org/docs/latest/,
23037 UDisks}, a @dfn{disk management} daemon that provides user interfaces
23038 with notifications and ways to mount/unmount disks. Programs that talk
23039 to UDisks include the @command{udisksctl} command, part of UDisks, and
23040 GNOME Disks. Note that Udisks relies on the @command{mount} command, so
23041 it will only be able to use the file-system utilities installed in the
23042 system profile. For example if you want to be able to mount NTFS
23043 file-systems in read and write fashion, you'll need to have
23044 @code{ntfs-3g} installed system-wide.
23047 @deffn {Scheme Variable} colord-service-type
23048 This is the type of the service that runs @command{colord}, a system
23049 service with a D-Bus
23050 interface to manage the color profiles of input and output devices such as
23051 screens and scanners. It is notably used by the GNOME Color Manager graphical
23052 tool. See @uref{https://www.freedesktop.org/software/colord/, the colord web
23053 site} for more information.
23056 @cindex scanner access
23057 @defvr {Scheme Variable} sane-service-type
23058 This service provides access to scanners @i{via}
23059 @uref{http://www.sane-project.org, SANE} by installing the necessary
23060 udev rules. It is included in @code{%desktop-services} (@pxref{Desktop
23061 Services}) and relies by default on @code{sane-backends-minimal} package
23062 (see below) for hardware support.
23065 @defvr {Scheme Variable} sane-backends-minimal
23066 The default package which the @code{sane-service-type} installs. It
23067 supports many recent scanners.
23070 @defvr {Scheme Variable} sane-backends
23071 This package includes support for all scanners that
23072 @code{sane-backends-minimal} supports, plus older Hewlett-Packard
23073 scanners supported by @code{hplip} package. In order to use this on
23074 a system which relies on @code{%desktop-services}, you may use
23075 @code{modify-services} (@pxref{Service Reference,
23076 @code{modify-services}}) as illustrated below:
23079 (use-modules (gnu))
23080 (use-service-modules
23083 (use-package-modules
23087 (define %my-desktop-services
23088 ;; List of desktop services that supports a broader range of scanners.
23089 (modify-services %desktop-services
23090 (sane-service-type _ => sane-backends)))
23094 (services %my-desktop-services))
23098 @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
23099 Return a configuration allowing an application to access GeoClue
23100 location data. @var{name} is the Desktop ID of the application, without
23101 the @code{.desktop} part. If @var{allowed?} is true, the application
23102 will have access to location information by default. The boolean
23103 @var{system?} value indicates whether an application is a system component
23104 or not. Finally @var{users} is a list of UIDs of all users for which
23105 this application is allowed location info access. An empty users list
23106 means that all users are allowed.
23109 @defvr {Scheme Variable} %standard-geoclue-applications
23110 The standard list of well-known GeoClue application configurations,
23111 granting authority to the GNOME date-and-time utility to ask for the
23112 current location in order to set the time zone, and allowing the
23113 IceCat and Epiphany web browsers to request location information.
23114 IceCat and Epiphany both query the user before allowing a web page to
23115 know the user's location.
23118 @deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
23119 [#:whitelist '()] @
23120 [#:wifi-geolocation-url "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
23121 [#:submit-data? #f]
23122 [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
23123 [#:submission-nick "geoclue"] @
23124 [#:applications %standard-geoclue-applications]
23125 Return a service that runs the GeoClue location service. This service
23126 provides a D-Bus interface to allow applications to request access to a
23127 user's physical location, and optionally to add information to online
23128 location databases. See
23129 @uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue
23130 web site} for more information.
23133 @deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
23134 [@w{#:auto-enable? #f}]
23135 Return a service that runs the @command{bluetoothd} daemon, which
23136 manages all the Bluetooth devices and provides a number of D-Bus
23137 interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
23138 powered automatically at boot, which can be useful when using a
23139 bluetooth keyboard or mouse.
23141 Users need to be in the @code{lp} group to access the D-Bus service.
23144 @deffn {Scheme Variable} bluetooth-service-type
23145 This is the type for the @uref{https://bluez.org/, Linux Bluetooth Protocol
23146 Stack} (BlueZ) system, which generates the @file{/etc/bluetooth/main.conf}
23147 configuration file. The value for this type is a @command{bluetooth-configuration}
23148 record as in this example:
23151 (service bluetooth-service-type)
23154 See below for details about @code{bluetooth-configuration}.
23157 @deftp {Data Type} bluetooth-configuration
23158 Data type representing the configuration for @code{bluetooth-service}.
23161 @item @code{bluez} (default: @code{bluez})
23162 @code{bluez} package to use.
23164 @item @code{name} (default: @code{"BlueZ"})
23165 Default adapter name.
23167 @item @code{class} (default: @code{#x000000})
23168 Default device class. Only the major and minor device class bits are considered.
23170 @item @code{discoverable-timeout} (default: @code{180})
23171 How long to stay in discoverable mode before going back to non-discoverable. The
23172 value is in seconds.
23174 @item @code{always-pairable?} (default: @code{#f})
23175 Always allow pairing even if there are no agents registered.
23177 @item @code{pairable-timeout} (default: @code{0})
23178 How long to stay in pairable mode before going back to non-discoverable. The
23179 value is in seconds.
23181 @item @code{device-id} (default: @code{#f})
23182 Use vendor id source (assigner), vendor, product and version information for
23183 DID profile support. The values are separated by ":" and @var{assigner}, @var{VID},
23184 @var{PID} and @var{version}.
23186 Possible values are:
23190 @code{#f} to disable it,
23193 @code{"assigner:1234:5678:abcd"}, where @var{assigner} is either @code{usb} (default)
23194 or @code{bluetooth}.
23198 @item @code{reverse-service-discovery?} (default: @code{#t})
23199 Do reverse service discovery for previously unknown devices that connect to
23200 us. For BR/EDR this option is really only needed for qualification since the
23201 BITE tester doesn't like us doing reverse SDP for some test cases, for LE
23202 this disables the GATT client functionally so it can be used in system which
23203 can only operate as peripheral.
23205 @item @code{name-resolving?} (default: @code{#t})
23206 Enable name resolving after inquiry. Set it to @code{#f} if you don't need
23207 remote devices name and want shorter discovery cycle.
23209 @item @code{debug-keys?} (default: @code{#f})
23210 Enable runtime persistency of debug link keys. Default is false which makes
23211 debug link keys valid only for the duration of the connection that they were
23214 @item @code{controller-mode} (default: @code{'dual})
23215 Restricts all controllers to the specified transport. @code{'dual} means both
23216 BR/EDR and LE are enabled (if supported by the hardware).
23218 Possible values are:
23232 @item @code{multi-profile} (default: @code{'off})
23233 Enables Multi Profile Specification support. This allows to specify if system
23234 supports only Multiple Profiles Single Device (MPSD) configuration or both
23235 Multiple Profiles Single Device (MPSD) and Multiple Profiles Multiple Devices
23236 (MPMD) configurations.
23238 Possible values are:
23252 @item @code{fast-connectable?} (default: @code{#f})
23253 Permanently enables the Fast Connectable setting for adapters that support
23254 it. When enabled other devices can connect faster to us, however the
23255 tradeoff is increased power consumptions. This feature will fully work only
23256 on kernel version 4.1 and newer.
23258 @item @code{privacy} (default: @code{'off})
23259 Default privacy settings.
23263 @code{'off}: Disable local privacy
23266 @code{'network/on}: A device will only accept advertising packets from peer
23267 devices that contain private addresses. It may not be compatible with some
23268 legacy devices since it requires the use of RPA(s) all the time
23271 @code{'device}: A device in device privacy mode is only concerned about the
23272 privacy of the device and will accept advertising packets from peer devices
23273 that contain their Identity Address as well as ones that contain a private
23274 address, even if the peer device has distributed its IRK in the past
23278 and additionally, if @var{controller-mode} is set to @code{'dual}:
23282 @code{'limited-network}: Apply Limited Discoverable Mode to advertising, which
23283 follows the same policy as to BR/EDR that publishes the identity address when
23284 discoverable, and Network Privacy Mode for scanning
23287 @code{'limited-device}: Apply Limited Discoverable Mode to advertising, which
23288 follows the same policy as to BR/EDR that publishes the identity address when
23289 discoverable, and Device Privacy Mode for scanning.
23293 @item @code{just-works-repairing} (default: @code{'never})
23294 Specify the policy to the JUST-WORKS repairing initiated by peer.
23309 @item @code{temporary-timeout} (default: @code{30})
23310 How long to keep temporary devices around. The value is in seconds. @code{0}
23311 disables the timer completely.
23313 @item @code{refresh-discovery?} (default: @code{#t})
23314 Enables the device to issue an SDP request to update known services when
23315 profile is connected.
23317 @item @code{experimental} (default: @code{#f})
23318 Enables experimental features and interfaces, alternatively a list of UUIDs
23331 @code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
23334 List of possible UUIDs:
23337 @code{d4992530-b9ec-469f-ab01-6c481c47da1c}: BlueZ Experimental Debug,
23340 @code{671b10b5-42c0-4696-9227-eb28d1b049d6}: BlueZ Experimental Simultaneous Central and Peripheral,
23343 @code{"15c0a148-c273-11ea-b3de-0242ac130004}: BlueZ Experimental LL privacy,
23346 @code{330859bc-7506-492d-9370-9a6f0614037f}: BlueZ Experimental Bluetooth Quality Report,
23349 @code{a6695ace-ee7f-4fb9-881a-5fac66c629af}: BlueZ Experimental Offload Codecs.
23352 @item @code{remote-name-request-retry-delay} (default: @code{300})
23353 The duration to avoid retrying to resolve a peer's name, if the previous
23356 @item @code{page-scan-type} (default: @code{#f})
23357 BR/EDR Page scan activity type.
23359 @item @code{page-scan-interval} (default: @code{#f})
23360 BR/EDR Page scan activity interval.
23362 @item @code{page-scan-window} (default: @code{#f})
23363 BR/EDR Page scan activity window.
23365 @item @code{inquiry-scan-type} (default: @code{#f})
23366 BR/EDR Inquiry scan activity type.
23368 @item @code{inquiry-scan-interval} (default: @code{#f})
23369 BR/EDR Inquiry scan activity interval.
23371 @item @code{inquiry-scan-window} (default: @code{#f})
23372 BR/EDR Inquiry scan activity window.
23374 @item @code{link-supervision-timeout} (default: @code{#f})
23375 BR/EDR Link supervision timeout.
23377 @item @code{page-timeout} (default: @code{#f})
23378 BR/EDR Page timeout.
23380 @item @code{min-sniff-interval} (default: @code{#f})
23381 BR/EDR minimum sniff interval.
23383 @item @code{max-sniff-interval} (default: @code{#f})
23384 BR/EDR maximum sniff interval.
23386 @item @code{min-advertisement-interval} (default: @code{#f})
23387 LE minimum advertisement interval (used for legacy advertisement only).
23389 @item @code{max-advertisement-interval} (default: @code{#f})
23390 LE maximum advertisement interval (used for legacy advertisement only).
23392 @item @code{multi-advertisement-rotation-interval} (default: @code{#f})
23393 LE multiple advertisement rotation interval.
23395 @item @code{scan-interval-auto-connect} (default: @code{#f})
23396 LE scanning interval used for passive scanning supporting auto connect.
23398 @item @code{scan-window-auto-connect} (default: @code{#f})
23399 LE scanning window used for passive scanning supporting auto connect.
23401 @item @code{scan-interval-suspend} (default: @code{#f})
23402 LE scanning interval used for active scanning supporting wake from suspend.
23404 @item @code{scan-window-suspend} (default: @code{#f})
23405 LE scanning window used for active scanning supporting wake from suspend.
23407 @item @code{scan-interval-discovery} (default: @code{#f})
23408 LE scanning interval used for active scanning supporting discovery.
23410 @item @code{scan-window-discovery} (default: @code{#f})
23411 LE scanning window used for active scanning supporting discovery.
23413 @item @code{scan-interval-adv-monitor} (default: @code{#f})
23414 LE scanning interval used for passive scanning supporting the advertisement monitor APIs.
23416 @item @code{scan-window-adv-monitor} (default: @code{#f})
23417 LE scanning window used for passive scanning supporting the advertisement monitor APIs.
23419 @item @code{scan-interval-connect} (default: @code{#f})
23420 LE scanning interval used for connection establishment.
23422 @item @code{scan-window-connect} (default: @code{#f})
23423 LE scanning window used for connection establishment.
23425 @item @code{min-connection-interval} (default: @code{#f})
23426 LE default minimum connection interval. This value is superseded by any specific
23427 value provided via the Load Connection Parameters interface.
23429 @item @code{max-connection-interval} (default: @code{#f})
23430 LE default maximum connection interval. This value is superseded by any specific
23431 value provided via the Load Connection Parameters interface.
23433 @item @code{connection-latency} (default: @code{#f})
23434 LE default connection latency. This value is superseded by any specific
23435 value provided via the Load Connection Parameters interface.
23437 @item @code{connection-supervision-timeout} (default: @code{#f})
23438 LE default connection supervision timeout. This value is superseded by any specific
23439 value provided via the Load Connection Parameters interface.
23441 @item @code{autoconnect-timeout} (default: @code{#f})
23442 LE default autoconnect timeout. This value is superseded by any specific
23443 value provided via the Load Connection Parameters interface.
23445 @item @code{adv-mon-allowlist-scan-duration} (default: @code{300})
23446 Allowlist scan duration during interleaving scan. Only used when scanning for ADV
23447 monitors. The units are msec.
23449 @item @code{adv-mon-no-filter-scan-duration} (default: @code{500})
23450 No filter scan duration during interleaving scan. Only used when scanning for ADV
23451 monitors. The units are msec.
23453 @item @code{enable-adv-mon-interleave-scan?} (default: @code{#t})
23454 Enable/Disable Advertisement Monitor interleave scan for power saving.
23456 @item @code{cache} (default: @code{'always})
23457 GATT attribute cache.
23459 Possible values are:
23462 @code{'always}: Always cache attributes even for devices not paired, this is
23463 recommended as it is best for interoperability, with more consistent
23464 reconnection times and enables proper tracking of notifications for all
23468 @code{'yes}: Only cache attributes of paired devices
23471 @code{'no}: Never cache attributes.
23474 @item @code{key-size} (default: @code{0})
23475 Minimum required Encryption Key Size for accessing secured characteristics.
23477 Possible values are:
23480 @code{0}: Don't care
23483 @code{7 <= N <= 16}
23486 @item @code{exchange-mtu} (default: @code{517})
23487 Exchange MTU size. Possible values are:
23491 @code{23 <= N <= 517}
23494 @item @code{att-channels} (default: @code{3})
23495 Number of ATT channels. Possible values are:
23499 @code{1}: Disables EATT
23505 @item @code{session-mode} (default: @code{'basic})
23506 AVDTP L2CAP signalling channel mode.
23508 Possible values are:
23512 @code{'basic}: Use L2CAP basic mode
23515 @code{'ertm}: Use L2CAP enhanced retransmission mode.
23518 @item @code{stream-mode} (default: @code{'basic})
23519 AVDTP L2CAP transport channel mode.
23521 Possible values are:
23525 @code{'basic}: Use L2CAP basic mode
23528 @code{'streaming}: Use L2CAP streaming mode.
23531 @item @code{reconnect-uuids} (default: @code{'()})
23532 The ReconnectUUIDs defines the set of remote services that should try
23533 to be reconnected to in case of a link loss (link supervision
23534 timeout). The policy plugin should contain a sane set of values by
23535 default, but this list can be overridden here. By setting the list to
23536 empty the reconnection feature gets disabled.
23545 @code{(list (uuid <uuid-1>) (uuid <uuid-2>) ...)}.
23548 @item @code{reconnect-attempts} (default: @code{7})
23549 Defines the number of attempts to reconnect after a link lost. Setting
23550 the value to 0 disables reconnecting feature.
23552 @item @code{reconnect-intervals} (default: @code{'(1 2 4 8 16 32 64)})
23553 Defines a list of intervals in seconds to use in between attempts. If
23554 the number of attempts defined in @var{reconnect-attempts} is bigger than
23555 the list of intervals the last interval is repeated until the last attempt.
23557 @item @code{auto-enable?} (default: @code{#f})
23558 Defines option to enable all controllers when they are found. This includes
23559 adapters present on start as well as adapters that are plugged in later on.
23561 @item @code{resume-delay} (default: @code{2})
23562 Audio devices that were disconnected due to suspend will be reconnected on
23563 resume. @var{resume-delay} determines the delay between when the controller
23564 resumes from suspend and a connection attempt is made. A longer delay is
23565 better for better co-existence with Wi-Fi. The value is in seconds.
23567 @item @code{rssi-sampling-period} (default: @code{#xFF})
23568 Default RSSI Sampling Period. This is used when a client registers an
23569 advertisement monitor and leaves the RSSISamplingPeriod unset.
23571 Possible values are:
23574 @code{#x0}: Report all advertisements
23577 @code{N = #xXX}: Report advertisements every N x 100 msec (range: #x01 to #xFE)
23580 @code{#xFF}: Report only one advertisement per device during monitoring period.
23586 @defvr {Scheme Variable} gnome-keyring-service-type
23587 This is the type of the service that adds the
23588 @uref{https://wiki.gnome.org/Projects/GnomeKeyring, GNOME Keyring}. Its
23589 value is a @code{gnome-keyring-configuration} object (see below).
23591 This service adds the @code{gnome-keyring} package to the system profile
23592 and extends PAM with entries using @code{pam_gnome_keyring.so}, unlocking
23593 a user's login keyring when they log in or setting its password with passwd.
23596 @deftp {Data Type} gnome-keyring-configuration
23597 Configuration record for the GNOME Keyring service.
23600 @item @code{keyring} (default: @code{gnome-keyring})
23601 The GNOME keyring package to use.
23603 @item @code{pam-services}
23604 A list of @code{(@var{service} . @var{kind})} pairs denoting PAM
23605 services to extend, where @var{service} is the name of an existing
23606 service to extend and @var{kind} is one of @code{login} or
23609 If @code{login} is given, it adds an optional
23610 @code{pam_gnome_keyring.so} to the auth block without arguments and to
23611 the session block with @code{auto_start}. If @code{passwd} is given, it
23612 adds an optional @code{pam_gnome_keyring.so} to the password block
23615 By default, this field contains ``gdm-password'' with the value @code{login}
23616 and ``passwd'' is with the value @code{passwd}.
23620 @defvr {Scheme Variable} seatd-service-type
23621 @uref{https://sr.ht/~kennylevinsen/seatd/, seatd} is a minimal seat
23624 Seat management takes care of mediating access to shared devices (graphics,
23625 input), without requiring the applications needing access to be root.
23630 ;; make sure seatd is running
23631 (service seatd-service-type))
23633 ;; normally one would want %base-services
23638 @code{seatd} operates over a UNIX domain socket, with @code{libseat}
23639 providing the client side of the protocol. Applications that acquire
23640 access to the shared resources via @code{seatd} (e.g. @code{sway})
23641 need to be able to talk to this socket.
23642 This can be achieved by adding the user they run under to the group
23643 owning @code{seatd}'s socket (usually ``seat''), like so:
23649 (supplementary-groups '("wheel" ; allow use of sudo, etc.
23650 "seat" ; seat management
23651 "audio" ; sound card
23652 "video" ; video devices such as webcams
23653 "cdrom")) ; the good ol' CD-ROM
23654 (comment "Bob's sister"))
23657 Depending on your setup, you will have to not only add regular users,
23658 but also system users to this group. For instance, some greetd greeters
23659 require graphics and therefore also need to negotiate with seatd.
23663 @deftp {Data Type} seatd-configuration
23664 Configuration record for the seatd daemon service.
23667 @item @code{seatd} (default: @code{seatd})
23668 The seatd package to use.
23670 @item @code{group} (default: @samp{"seat"})
23671 Group to own the seatd socket.
23673 @item @code{socket} (default: @samp{"/run/seatd.sock"})
23674 Where to create the seatd socket.
23676 @item @code{logfile} (default: @samp{"/var/log/seatd.log"})
23677 Log file to write to.
23679 @item @code{loglevel} (default: @samp{"error"})
23680 Log level to output logs. Possible values: @samp{"silent"}, @samp{"error"},
23681 @samp{"info"} and @samp{"debug"}.
23687 @node Sound Services
23688 @subsection Sound Services
23690 @cindex sound support
23692 @cindex PulseAudio, sound support
23694 The @code{(gnu services sound)} module provides a service to configure the
23695 Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
23696 preferred ALSA output driver.
23698 @deffn {Scheme Variable} alsa-service-type
23699 This is the type for the @uref{https://alsa-project.org/, Advanced Linux Sound
23700 Architecture} (ALSA) system, which generates the @file{/etc/asound.conf}
23701 configuration file. The value for this type is a @command{alsa-configuration}
23702 record as in this example:
23705 (service alsa-service-type)
23708 See below for details about @code{alsa-configuration}.
23711 @deftp {Data Type} alsa-configuration
23712 Data type representing the configuration for @code{alsa-service}.
23715 @item @code{alsa-plugins} (default: @var{alsa-plugins})
23716 @code{alsa-plugins} package to use.
23718 @item @code{pulseaudio?} (default: @var{#t})
23719 Whether ALSA applications should transparently be made to use the
23720 @uref{https://www.pulseaudio.org/, PulseAudio} sound server.
23722 Using PulseAudio allows you to run several sound-producing applications
23723 at the same time and to individual control them @i{via}
23724 @command{pavucontrol}, among other things.
23726 @item @code{extra-options} (default: @var{""})
23727 String to append to the @file{/etc/asound.conf} file.
23732 Individual users who want to override the system configuration of ALSA can do
23733 it with the @file{~/.asoundrc} file:
23736 # In guix, we have to specify the absolute path for plugins.
23738 lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
23741 # Routing ALSA to jack:
23742 # <http://jackaudio.org/faq/routing_alsa.html>.
23746 0 system:playback_1
23747 1 system:playback_2
23764 See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
23767 @deffn {Scheme Variable} pulseaudio-service-type
23768 This is the type for the @uref{https://www.pulseaudio.org/, PulseAudio}
23769 sound server. It exists to allow system overrides of the default settings
23770 via @code{pulseaudio-configuration}, see below.
23773 This service overrides per-user configuration files. If you want
23774 PulseAudio to honor configuration files in @file{~/.config/pulse} you
23775 have to unset the environment variables @env{PULSE_CONFIG} and
23776 @env{PULSE_CLIENTCONFIG} in your @file{~/.bash_profile}.
23780 This service on its own does not ensure, that the @code{pulseaudio} package
23781 exists on your machine. It merely adds configuration files for it, as
23782 detailed below. In the (admittedly unlikely) case, that you find yourself
23783 without a @code{pulseaudio} package, consider enabling it through the
23784 @code{alsa-service-type} above.
23788 @deftp {Data Type} pulseaudio-configuration
23789 Data type representing the configuration for @code{pulseaudio-service}.
23792 @item @code{client-conf} (default: @code{'()})
23793 List of settings to set in @file{client.conf}.
23794 Accepts a list of strings or symbol-value pairs. A string will be
23795 inserted as-is with a newline added. A pair will be formatted as
23796 ``key = value'', again with a newline added.
23798 @item @code{daemon-conf} (default: @code{'((flat-volumes . no))})
23799 List of settings to set in @file{daemon.conf}, formatted just like
23802 @item @code{script-file} (default: @code{(file-append pulseaudio "/etc/pulse/default.pa")})
23803 Script file to use as @file{default.pa}. In case the
23804 @code{extra-script-files} field below is used, an @code{.include}
23805 directive pointing to @file{/etc/pulse/default.pa.d} is appended to the
23808 @item @code{extra-script-files} (default: @code{'()})
23809 A list of file-like objects defining extra PulseAudio scripts to run at
23810 the initialization of the @command{pulseaudio} daemon, after the main
23811 @code{script-file}. The scripts are deployed to the
23812 @file{/etc/pulse/default.pa.d} directory; they should have the
23813 @samp{.pa} file name extension. For a reference of the available
23814 commands, refer to @command{man pulse-cli-syntax}.
23816 @item @code{system-script-file} (default: @code{(file-append pulseaudio "/etc/pulse/system.pa")})
23817 Script file to use as @file{system.pa}.
23820 The example below sets the default PulseAudio card profile, the default
23821 sink and the default source to use for a old SoundBlaster Audigy sound
23824 (pulseaudio-configuration
23825 (extra-script-files
23826 (list (plain-file "audigy.pa"
23828 set-card-profile alsa_card.pci-0000_01_01.0 \
23829 output:analog-surround-40+input:analog-mono
23830 set-default-source alsa_input.pci-0000_01_01.0.analog-mono
23831 set-default-sink alsa_output.pci-0000_01_01.0.analog-surround-40\n")))))
23834 Note that @code{pulseaudio-service-type} is part of
23835 @code{%desktop-services}; if your operating system declaration was
23836 derived from one of the desktop templates, you'll want to adjust the
23837 above example to modify the existing @code{pulseaudio-service-type} via
23838 @code{modify-services} (@pxref{Service Reference,
23839 @code{modify-services}}), instead of defining a new one.
23843 @deffn {Scheme Variable} ladspa-service-type
23844 This service sets the @var{LADSPA_PATH} variable, so that programs, which
23845 respect it, e.g. PulseAudio, can load LADSPA plugins.
23847 The following example will setup the service to enable modules from the
23848 @code{swh-plugins} package:
23851 (service ladspa-service-type
23852 (ladspa-configuration (plugins (list swh-plugins))))
23855 See @uref{http://plugin.org.uk/ladspa-swh/docs/ladspa-swh.html} for the
23860 @node Database Services
23861 @subsection Database Services
23865 The @code{(gnu services databases)} module provides the following services.
23867 @subsubheading PostgreSQL
23869 The following example describes a PostgreSQL service with the default
23873 (service postgresql-service-type
23874 (postgresql-configuration
23875 (postgresql postgresql-10)))
23878 If the services fails to start, it may be due to an incompatible
23879 cluster already present in @var{data-directory}. Adjust it (or, if you
23880 don't need the cluster anymore, delete @var{data-directory}), then
23881 restart the service.
23883 Peer authentication is used by default and the @code{postgres} user
23884 account has no shell, which prevents the direct execution of @code{psql}
23885 commands as this user. To use @code{psql}, you can temporarily log in
23886 as @code{postgres} using a shell, create a PostgreSQL superuser with the
23887 same name as one of the system users and then create the associated
23891 sudo -u postgres -s /bin/sh
23892 createuser --interactive
23893 createdb $MY_USER_LOGIN # Replace appropriately.
23896 @deftp {Data Type} postgresql-configuration
23897 Data type representing the configuration for the
23898 @code{postgresql-service-type}.
23901 @item @code{postgresql}
23902 PostgreSQL package to use for the service.
23904 @item @code{port} (default: @code{5432})
23905 Port on which PostgreSQL should listen.
23907 @item @code{locale} (default: @code{"en_US.utf8"})
23908 Locale to use as the default when creating the database cluster.
23910 @item @code{config-file} (default: @code{(postgresql-config-file)})
23911 The configuration file to use when running PostgreSQL@. The default
23912 behaviour uses the postgresql-config-file record with the default values
23915 @item @code{log-directory} (default: @code{"/var/log/postgresql"})
23916 The directory where @command{pg_ctl} output will be written in a file
23917 named @code{"pg_ctl.log"}. This file can be useful to debug PostgreSQL
23918 configuration errors for instance.
23920 @item @code{data-directory} (default: @code{"/var/lib/postgresql/data"})
23921 Directory in which to store the data.
23923 @item @code{extension-packages} (default: @code{'()})
23924 @cindex postgresql extension-packages
23925 Additional extensions are loaded from packages listed in
23926 @var{extension-packages}. Extensions are available at runtime. For instance,
23927 to create a geographic database using the @code{postgis} extension, a user can
23928 configure the postgresql-service as in this example:
23932 (use-package-modules databases geo)
23936 ;; postgresql is required to run `psql' but postgis is not required for
23937 ;; proper operation.
23938 (packages (cons* postgresql %base-packages))
23941 (service postgresql-service-type
23942 (postgresql-configuration
23943 (postgresql postgresql-10)
23944 (extension-packages (list postgis))))
23948 Then the extension becomes visible and you can initialise an empty geographic
23949 database in this way:
23953 > create database postgistest;
23954 > \connect postgistest;
23955 > create extension postgis;
23956 > create extension postgis_topology;
23959 There is no need to add this field for contrib extensions such as hstore or
23960 dblink as they are already loadable by postgresql. This field is only
23961 required to add extensions provided by other packages.
23966 @deftp {Data Type} postgresql-config-file
23967 Data type representing the PostgreSQL configuration file. As shown in
23968 the following example, this can be used to customize the configuration
23969 of PostgreSQL@. Note that you can use any G-expression or filename in
23970 place of this record, if you already have a configuration file you'd
23971 like to use for example.
23974 (service postgresql-service-type
23975 (postgresql-configuration
23977 (postgresql-config-file
23978 (log-destination "stderr")
23980 (plain-file "pg_hba.conf"
23982 local all all trust
23983 host all all 127.0.0.1/32 md5
23984 host all all ::1/128 md5"))
23986 '(("session_preload_libraries" "auto_explain")
23987 ("random_page_cost" 2)
23988 ("auto_explain.log_min_duration" "100 ms")
23989 ("work_mem" "500 MB")
23990 ("logging_collector" #t)
23991 ("log_directory" "/var/log/postgresql")))))))
23995 @item @code{log-destination} (default: @code{"syslog"})
23996 The logging method to use for PostgreSQL@. Multiple values are accepted,
23997 separated by commas.
23999 @item @code{hba-file} (default: @code{%default-postgres-hba})
24000 Filename or G-expression for the host-based authentication
24003 @item @code{ident-file} (default: @code{%default-postgres-ident})
24004 Filename or G-expression for the user name mapping configuration.
24006 @item @code{socket-directory} (default: @code{"/var/run/postgresql"})
24007 Specifies the directory of the Unix-domain socket(s) on which PostgreSQL
24008 is to listen for connections from client applications. If set to
24009 @code{""} PostgreSQL does not listen on any Unix-domain sockets, in
24010 which case only TCP/IP sockets can be used to connect to the server.
24012 By default, the @code{#false} value means the PostgreSQL default value
24013 will be used, which is currently @samp{/tmp}.
24015 @item @code{extra-config} (default: @code{'()})
24016 List of additional keys and values to include in the PostgreSQL config
24017 file. Each entry in the list should be a list where the first element
24018 is the key, and the remaining elements are the values.
24020 The values can be numbers, booleans or strings and will be mapped to
24021 PostgreSQL parameters types @code{Boolean}, @code{String},
24022 @code{Numeric}, @code{Numeric with Unit} and @code{Enumerated} described
24023 @uref{https://www.postgresql.org/docs/current/config-setting.html,
24029 @deffn {Scheme Variable} postgresql-role-service-type
24030 This service allows to create PostgreSQL roles and databases after
24031 PostgreSQL service start. Here is an example of its use.
24034 (service postgresql-role-service-type
24035 (postgresql-role-configuration
24037 (list (postgresql-role
24039 (create-database? #t))))))
24042 This service can be extended with extra roles, as in this
24046 (service-extension postgresql-role-service-type
24047 (const (postgresql-role
24049 (create-database? #t))))
24053 @deftp {Data Type} postgresql-role
24054 PostgreSQL manages database access permissions using the concept of
24055 roles. A role can be thought of as either a database user, or a group
24056 of database users, depending on how the role is set up. Roles can own
24057 database objects (for example, tables) and can assign privileges on
24058 those objects to other roles to control who has access to which objects.
24064 @item @code{permissions} (default: @code{'(createdb login)})
24065 The role permissions list. Supported permissions are @code{bypassrls},
24066 @code{createdb}, @code{createrole}, @code{login}, @code{replication} and
24069 @item @code{create-database?} (default: @code{#f})
24070 Whether to create a database with the same name as the role.
24075 @deftp {Data Type} postgresql-role-configuration
24076 Data type representing the configuration of
24077 @var{postgresql-role-service-type}.
24080 @item @code{host} (default: @code{"/var/run/postgresql"})
24081 The PostgreSQL host to connect to.
24083 @item @code{log} (default: @code{"/var/log/postgresql_roles.log"})
24084 File name of the log file.
24086 @item @code{roles} (default: @code{'()})
24087 The initial PostgreSQL roles to create.
24091 @subsubheading MariaDB/MySQL
24093 @defvr {Scheme Variable} mysql-service-type
24094 This is the service type for a MySQL or MariaDB database server. Its value
24095 is a @code{mysql-configuration} object that specifies which package to use,
24096 as well as various settings for the @command{mysqld} daemon.
24099 @deftp {Data Type} mysql-configuration
24100 Data type representing the configuration of @var{mysql-service-type}.
24103 @item @code{mysql} (default: @var{mariadb})
24104 Package object of the MySQL database server, can be either @var{mariadb}
24107 For MySQL, a temporary root password will be displayed at activation time.
24108 For MariaDB, the root password is empty.
24110 @item @code{bind-address} (default: @code{"127.0.0.1"})
24111 The IP on which to listen for network connections. Use @code{"0.0.0.0"}
24112 to bind to all available network interfaces.
24114 @item @code{port} (default: @code{3306})
24115 TCP port on which the database server listens for incoming connections.
24117 @item @code{socket} (default: @code{"/run/mysqld/mysqld.sock"})
24118 Socket file to use for local (non-network) connections.
24120 @item @code{extra-content} (default: @code{""})
24121 Additional settings for the @file{my.cnf} configuration file.
24123 @item @code{extra-environment} (default: @code{#~'()})
24124 List of environment variables passed to the @command{mysqld} process.
24126 @item @code{auto-upgrade?} (default: @code{#t})
24127 Whether to automatically run @command{mysql_upgrade} after starting the
24128 service. This is necessary to upgrade the @dfn{system schema} after
24129 ``major'' updates (such as switching from MariaDB 10.4 to 10.5), but can
24130 be disabled if you would rather do that manually.
24135 @subsubheading Memcached
24137 @defvr {Scheme Variable} memcached-service-type
24138 This is the service type for the @uref{https://memcached.org/,
24139 Memcached} service, which provides a distributed in memory cache. The
24140 value for the service type is a @code{memcached-configuration} object.
24144 (service memcached-service-type)
24147 @deftp {Data Type} memcached-configuration
24148 Data type representing the configuration of memcached.
24151 @item @code{memcached} (default: @code{memcached})
24152 The Memcached package to use.
24154 @item @code{interfaces} (default: @code{'("0.0.0.0")})
24155 Network interfaces on which to listen.
24157 @item @code{tcp-port} (default: @code{11211})
24158 Port on which to accept connections.
24160 @item @code{udp-port} (default: @code{11211})
24161 Port on which to accept UDP connections on, a value of 0 will disable
24162 listening on a UDP socket.
24164 @item @code{additional-options} (default: @code{'()})
24165 Additional command line options to pass to @code{memcached}.
24169 @subsubheading Redis
24171 @defvr {Scheme Variable} redis-service-type
24172 This is the service type for the @uref{https://redis.io/, Redis}
24173 key/value store, whose value is a @code{redis-configuration} object.
24176 @deftp {Data Type} redis-configuration
24177 Data type representing the configuration of redis.
24180 @item @code{redis} (default: @code{redis})
24181 The Redis package to use.
24183 @item @code{bind} (default: @code{"127.0.0.1"})
24184 Network interface on which to listen.
24186 @item @code{port} (default: @code{6379})
24187 Port on which to accept connections on, a value of 0 will disable
24188 listening on a TCP socket.
24190 @item @code{working-directory} (default: @code{"/var/lib/redis"})
24191 Directory in which to store the database and related files.
24195 @node Mail Services
24196 @subsection Mail Services
24200 The @code{(gnu services mail)} module provides Guix service definitions
24201 for email services: IMAP, POP3, and LMTP servers, as well as mail
24202 transport agents (MTAs). Lots of acronyms! These services are detailed
24203 in the subsections below.
24205 @subsubheading Dovecot Service
24207 @deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
24208 Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
24211 By default, Dovecot does not need much configuration; the default
24212 configuration object created by @code{(dovecot-configuration)} will
24213 suffice if your mail is delivered to @code{~/Maildir}. A self-signed
24214 certificate will be generated for TLS-protected connections, though
24215 Dovecot will also listen on cleartext ports by default. There are a
24216 number of options, though, which mail administrators might need to change,
24217 and as is the case with other services, Guix allows the system
24218 administrator to specify these parameters via a uniform Scheme interface.
24220 For example, to specify that mail is located at @code{maildir~/.mail},
24221 one would instantiate the Dovecot service like this:
24224 (dovecot-service #:config
24225 (dovecot-configuration
24226 (mail-location "maildir:~/.mail")))
24229 The available configuration parameters follow. Each parameter
24230 definition is preceded by its type; for example, @samp{string-list foo}
24231 indicates that the @code{foo} parameter should be specified as a list of
24232 strings. There is also a way to specify the configuration as a string,
24233 if you have an old @code{dovecot.conf} file that you want to port over
24234 from some other system; see the end for more details.
24236 @c The following documentation was initially generated by
24237 @c (generate-documentation) in (gnu services mail). Manually maintained
24238 @c documentation is better, so we shouldn't hesitate to edit below as
24239 @c needed. However if the change you want to make to this documentation
24240 @c can be done in an automated way, it's probably easier to change
24241 @c (generate-documentation) than to make it below and have to deal with
24242 @c the churn as dovecot updates.
24244 Available @code{dovecot-configuration} fields are:
24246 @deftypevr {@code{dovecot-configuration} parameter} package dovecot
24247 The dovecot package.
24250 @deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
24251 A list of IPs or hosts where to listen for connections. @samp{*}
24252 listens on all IPv4 interfaces, @samp{::} listens on all IPv6
24253 interfaces. If you want to specify non-default ports or anything more
24254 complex, customize the address and port fields of the
24255 @samp{inet-listener} of the specific services you are interested in.
24258 @deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
24259 List of protocols we want to serve. Available protocols include
24260 @samp{imap}, @samp{pop3}, and @samp{lmtp}.
24262 Available @code{protocol-configuration} fields are:
24264 @deftypevr {@code{protocol-configuration} parameter} string name
24265 The name of the protocol.
24268 @deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
24269 UNIX socket path to the master authentication server to find users.
24270 This is used by imap (for shared users) and lda.
24271 It defaults to @samp{"/var/run/dovecot/auth-userdb"}.
24274 @deftypevr {@code{protocol-configuration} parameter} boolean imap-metadata?
24275 Whether to enable the @code{IMAP METADATA} extension as defined in
24276 @uref{https://tools.ietf.org/html/rfc5464,RFC@tie{}5464}, which provides
24277 a means for clients to set and retrieve per-mailbox, per-user metadata
24278 and annotations over IMAP.
24280 If this is @samp{#t}, you must also specify a dictionary @i{via} the
24281 @code{mail-attribute-dict} setting.
24283 Defaults to @samp{#f}.
24287 @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-notify-capabilities
24288 Which NOTIFY capabilities to report to clients that first connect to
24289 the ManageSieve service, before authentication. These may differ from the
24290 capabilities offered to authenticated users. If this field is left empty,
24291 report what the Sieve interpreter supports by default.
24293 Defaults to @samp{()}.
24296 @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list managesieve-sieve-capability
24297 Which SIEVE capabilities to report to clients that first connect to
24298 the ManageSieve service, before authentication. These may differ from the
24299 capabilities offered to authenticated users. If this field is left empty,
24300 report what the Sieve interpreter supports by default.
24302 Defaults to @samp{()}.
24306 @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
24307 Space separated list of plugins to load.
24310 @deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
24311 Maximum number of IMAP connections allowed for a user from each IP
24312 address. NOTE: The username is compared case-sensitively.
24313 Defaults to @samp{10}.
24318 @deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
24319 List of services to enable. Available services include @samp{imap},
24320 @samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
24323 Available @code{service-configuration} fields are:
24325 @deftypevr {@code{service-configuration} parameter} string kind
24326 The service kind. Valid values include @code{director},
24327 @code{imap-login}, @code{pop3-login}, @code{lmtp}, @code{imap},
24328 @code{pop3}, @code{auth}, @code{auth-worker}, @code{dict},
24329 @code{tcpwrap}, @code{quota-warning}, or anything else.
24332 @deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
24333 Listeners for the service. A listener is either a
24334 @code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
24335 an @code{inet-listener-configuration}.
24336 Defaults to @samp{()}.
24338 Available @code{unix-listener-configuration} fields are:
24340 @deftypevr {@code{unix-listener-configuration} parameter} string path
24341 Path to the file, relative to @code{base-dir} field. This is also used as
24345 @deftypevr {@code{unix-listener-configuration} parameter} string mode
24346 The access mode for the socket.
24347 Defaults to @samp{"0600"}.
24350 @deftypevr {@code{unix-listener-configuration} parameter} string user
24351 The user to own the socket.
24352 Defaults to @samp{""}.
24355 @deftypevr {@code{unix-listener-configuration} parameter} string group
24356 The group to own the socket.
24357 Defaults to @samp{""}.
24361 Available @code{fifo-listener-configuration} fields are:
24363 @deftypevr {@code{fifo-listener-configuration} parameter} string path
24364 Path to the file, relative to @code{base-dir} field. This is also used as
24368 @deftypevr {@code{fifo-listener-configuration} parameter} string mode
24369 The access mode for the socket.
24370 Defaults to @samp{"0600"}.
24373 @deftypevr {@code{fifo-listener-configuration} parameter} string user
24374 The user to own the socket.
24375 Defaults to @samp{""}.
24378 @deftypevr {@code{fifo-listener-configuration} parameter} string group
24379 The group to own the socket.
24380 Defaults to @samp{""}.
24384 Available @code{inet-listener-configuration} fields are:
24386 @deftypevr {@code{inet-listener-configuration} parameter} string protocol
24387 The protocol to listen for.
24390 @deftypevr {@code{inet-listener-configuration} parameter} string address
24391 The address on which to listen, or empty for all addresses.
24392 Defaults to @samp{""}.
24395 @deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
24396 The port on which to listen.
24399 @deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
24400 Whether to use SSL for this service; @samp{yes}, @samp{no}, or
24402 Defaults to @samp{#t}.
24407 @deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
24408 Maximum number of simultaneous client connections per process. Once
24409 this number of connections is received, the next incoming connection
24410 will prompt Dovecot to spawn another process. If set to 0,
24411 @code{default-client-limit} is used instead.
24413 Defaults to @samp{0}.
24417 @deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
24418 Number of connections to handle before starting a new process.
24419 Typically the only useful values are 0 (unlimited) or 1. 1 is more
24420 secure, but 0 is faster. <doc/wiki/LoginProcess.txt>.
24421 Defaults to @samp{1}.
24425 @deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
24426 Maximum number of processes that can exist for this service. If set to
24427 0, @code{default-process-limit} is used instead.
24429 Defaults to @samp{0}.
24433 @deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
24434 Number of processes to always keep waiting for more connections.
24435 Defaults to @samp{0}.
24438 @deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
24439 If you set @samp{service-count 0}, you probably need to grow
24441 Defaults to @samp{256000000}.
24446 @deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
24447 Dict configuration, as created by the @code{dict-configuration}
24450 Available @code{dict-configuration} fields are:
24452 @deftypevr {@code{dict-configuration} parameter} free-form-fields entries
24453 A list of key-value pairs that this dict should hold.
24454 Defaults to @samp{()}.
24459 @deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
24460 A list of passdb configurations, each one created by the
24461 @code{passdb-configuration} constructor.
24463 Available @code{passdb-configuration} fields are:
24465 @deftypevr {@code{passdb-configuration} parameter} string driver
24466 The driver that the passdb should use. Valid values include
24467 @samp{pam}, @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and
24469 Defaults to @samp{"pam"}.
24472 @deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
24473 Space separated list of arguments to the passdb driver.
24474 Defaults to @samp{""}.
24479 @deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
24480 List of userdb configurations, each one created by the
24481 @code{userdb-configuration} constructor.
24483 Available @code{userdb-configuration} fields are:
24485 @deftypevr {@code{userdb-configuration} parameter} string driver
24486 The driver that the userdb should use. Valid values include
24487 @samp{passwd} and @samp{static}.
24488 Defaults to @samp{"passwd"}.
24491 @deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
24492 Space separated list of arguments to the userdb driver.
24493 Defaults to @samp{""}.
24496 @deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
24497 Override fields from passwd.
24498 Defaults to @samp{()}.
24503 @deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
24504 Plug-in configuration, created by the @code{plugin-configuration}
24508 @deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
24509 List of namespaces. Each item in the list is created by the
24510 @code{namespace-configuration} constructor.
24512 Available @code{namespace-configuration} fields are:
24514 @deftypevr {@code{namespace-configuration} parameter} string name
24515 Name for this namespace.
24518 @deftypevr {@code{namespace-configuration} parameter} string type
24519 Namespace type: @samp{private}, @samp{shared} or @samp{public}.
24520 Defaults to @samp{"private"}.
24523 @deftypevr {@code{namespace-configuration} parameter} string separator
24524 Hierarchy separator to use. You should use the same separator for
24525 all namespaces or some clients get confused. @samp{/} is usually a good
24526 one. The default however depends on the underlying mail storage
24528 Defaults to @samp{""}.
24531 @deftypevr {@code{namespace-configuration} parameter} string prefix
24532 Prefix required to access this namespace. This needs to be
24533 different for all namespaces. For example @samp{Public/}.
24534 Defaults to @samp{""}.
24537 @deftypevr {@code{namespace-configuration} parameter} string location
24538 Physical location of the mailbox. This is in the same format as
24539 mail_location, which is also the default for it.
24540 Defaults to @samp{""}.
24543 @deftypevr {@code{namespace-configuration} parameter} boolean inbox?
24544 There can be only one INBOX, and this setting defines which
24546 Defaults to @samp{#f}.
24549 @deftypevr {@code{namespace-configuration} parameter} boolean hidden?
24550 If namespace is hidden, it's not advertised to clients via NAMESPACE
24551 extension. You'll most likely also want to set @samp{list? #f}. This is mostly
24552 useful when converting from another server with different namespaces
24553 which you want to deprecate but still keep working. For example you can
24554 create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/}
24556 Defaults to @samp{#f}.
24559 @deftypevr {@code{namespace-configuration} parameter} boolean list?
24560 Show the mailboxes under this namespace with the LIST command. This
24561 makes the namespace visible for clients that do not support the NAMESPACE
24562 extension. The special @code{children} value lists child mailboxes, but
24563 hides the namespace prefix.
24564 Defaults to @samp{#t}.
24567 @deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
24568 Namespace handles its own subscriptions. If set to @code{#f}, the
24569 parent namespace handles them. The empty prefix should always have this
24571 Defaults to @samp{#t}.
24574 @deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
24575 List of predefined mailboxes in this namespace.
24576 Defaults to @samp{()}.
24578 Available @code{mailbox-configuration} fields are:
24580 @deftypevr {@code{mailbox-configuration} parameter} string name
24581 Name for this mailbox.
24584 @deftypevr {@code{mailbox-configuration} parameter} string auto
24585 @samp{create} will automatically create this mailbox.
24586 @samp{subscribe} will both create and subscribe to the mailbox.
24587 Defaults to @samp{"no"}.
24590 @deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
24591 List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154.
24592 Valid values are @code{\All}, @code{\Archive}, @code{\Drafts},
24593 @code{\Flagged}, @code{\Junk}, @code{\Sent}, and @code{\Trash}.
24594 Defaults to @samp{()}.
24601 @deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
24602 Base directory where to store runtime data.
24603 Defaults to @samp{"/var/run/dovecot/"}.
24606 @deftypevr {@code{dovecot-configuration} parameter} string login-greeting
24607 Greeting message for clients.
24608 Defaults to @samp{"Dovecot ready."}.
24611 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
24612 List of trusted network ranges. Connections from these IPs are
24613 allowed to override their IP addresses and ports (for logging and for
24614 authentication checks). @samp{disable-plaintext-auth} is also ignored
24615 for these networks. Typically you would specify your IMAP proxy servers
24617 Defaults to @samp{()}.
24620 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
24621 List of login access check sockets (e.g.@: tcpwrap).
24622 Defaults to @samp{()}.
24625 @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
24626 Show more verbose process titles (in ps). Currently shows user name
24627 and IP address. Useful for seeing who is actually using the IMAP
24628 processes (e.g.@: shared mailboxes or if the same uid is used for multiple
24630 Defaults to @samp{#f}.
24633 @deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
24634 Should all processes be killed when Dovecot master process shuts down.
24635 Setting this to @code{#f} means that Dovecot can be upgraded without
24636 forcing existing client connections to close (although that could also
24637 be a problem if the upgrade is e.g.@: due to a security fix).
24638 Defaults to @samp{#t}.
24641 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
24642 If non-zero, run mail commands via this many connections to doveadm
24643 server, instead of running them directly in the same process.
24644 Defaults to @samp{0}.
24647 @deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
24648 UNIX socket or host:port used for connecting to doveadm server.
24649 Defaults to @samp{"doveadm-server"}.
24652 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
24653 List of environment variables that are preserved on Dovecot startup
24654 and passed down to all of its child processes. You can also give
24655 key=value pairs to always set specific settings.
24658 @deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
24659 Disable LOGIN command and all other plaintext authentications unless
24660 SSL/TLS is used (LOGINDISABLED capability). Note that if the remote IP
24661 matches the local IP (i.e.@: you're connecting from the same computer),
24662 the connection is considered secure and plaintext authentication is
24663 allowed. See also ssl=required setting.
24664 Defaults to @samp{#t}.
24667 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size
24668 Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled.
24669 Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set
24670 for caching to be used.
24671 Defaults to @samp{0}.
24674 @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl
24675 Time to live for cached data. After TTL expires the cached record
24676 is no longer used, *except* if the main database lookup returns internal
24677 failure. We also try to handle password changes automatically: If
24678 user's previous authentication was successful, but this one wasn't, the
24679 cache isn't used. For now this works only with plaintext
24681 Defaults to @samp{"1 hour"}.
24684 @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl
24685 TTL for negative hits (user not found, password mismatch).
24686 0 disables caching them completely.
24687 Defaults to @samp{"1 hour"}.
24690 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms
24691 List of realms for SASL authentication mechanisms that need them.
24692 You can leave it empty if you don't want to support multiple realms.
24693 Many clients simply use the first one listed here, so keep the default
24695 Defaults to @samp{()}.
24698 @deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
24699 Default realm/domain to use if none was specified. This is used for
24700 both SASL realms and appending @@domain to username in plaintext
24702 Defaults to @samp{""}.
24705 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
24706 List of allowed characters in username. If the user-given username
24707 contains a character not listed in here, the login automatically fails.
24708 This is just an extra check to make sure user can't exploit any
24709 potential quote escaping vulnerabilities with SQL/LDAP databases. If
24710 you want to allow all characters, set this value to empty.
24711 Defaults to @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.
24714 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation
24715 Username character translations before it's looked up from
24716 databases. The value contains series of from -> to characters. For
24717 example @samp{#@@/@@} means that @samp{#} and @samp{/} characters are
24718 translated to @samp{@@}.
24719 Defaults to @samp{""}.
24722 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-format
24723 Username formatting before it's looked up from databases. You can
24724 use the standard variables here, e.g.@: %Lu would lowercase the username,
24725 %n would drop away the domain if it was given, or @samp{%n-AT-%d} would
24726 change the @samp{@@} into @samp{-AT-}. This translation is done after
24727 @samp{auth-username-translation} changes.
24728 Defaults to @samp{"%Lu"}.
24731 @deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
24732 If you want to allow master users to log in by specifying the master
24733 username within the normal username string (i.e.@: not using SASL
24734 mechanism's support for it), you can specify the separator character
24735 here. The format is then <username><separator><master username>.
24736 UW-IMAP uses @samp{*} as the separator, so that could be a good
24738 Defaults to @samp{""}.
24741 @deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username
24742 Username to use for users logging in with ANONYMOUS SASL
24744 Defaults to @samp{"anonymous"}.
24747 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
24748 Maximum number of dovecot-auth worker processes. They're used to
24749 execute blocking passdb and userdb queries (e.g.@: MySQL and PAM).
24750 They're automatically created and destroyed as needed.
24751 Defaults to @samp{30}.
24754 @deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname
24755 Host name to use in GSSAPI principal names. The default is to use
24756 the name returned by gethostname(). Use @samp{$ALL} (with quotes) to
24757 allow all keytab entries.
24758 Defaults to @samp{""}.
24761 @deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
24762 Kerberos keytab to use for the GSSAPI mechanism. Will use the
24763 system default (usually @file{/etc/krb5.keytab}) if not specified. You may
24764 need to change the auth service to run as root to be able to read this
24766 Defaults to @samp{""}.
24769 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind?
24770 Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon
24771 and @samp{ntlm-auth} helper.
24772 <doc/wiki/Authentication/Mechanisms/Winbind.txt>.
24773 Defaults to @samp{#f}.
24776 @deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path
24777 Path for Samba's @samp{ntlm-auth} helper binary.
24778 Defaults to @samp{"/usr/bin/ntlm_auth"}.
24781 @deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay
24782 Time to delay before replying to failed authentications.
24783 Defaults to @samp{"2 secs"}.
24786 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert?
24787 Require a valid SSL client certificate or the authentication
24789 Defaults to @samp{#f}.
24792 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
24793 Take the username from client's SSL certificate, using
24794 @code{X509_NAME_get_text_by_NID()} which returns the subject's DN's
24796 Defaults to @samp{#f}.
24799 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms
24800 List of wanted authentication mechanisms. Supported mechanisms are:
24801 @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5},
24802 @samp{ntlm}, @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi},
24803 @samp{otp}, @samp{skey}, and @samp{gss-spnego}. NOTE: See also
24804 @samp{disable-plaintext-auth} setting.
24807 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
24808 List of IPs or hostnames to all director servers, including ourself.
24809 Ports can be specified as ip:port. The default port is the same as what
24810 director service's @samp{inet-listener} is using.
24811 Defaults to @samp{()}.
24814 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
24815 List of IPs or hostnames to all backend mail servers. Ranges are
24816 allowed too, like 10.0.0.10-10.0.0.30.
24817 Defaults to @samp{()}.
24820 @deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
24821 How long to redirect users to a specific server after it no longer
24822 has any connections.
24823 Defaults to @samp{"15 min"}.
24826 @deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
24827 How the username is translated before being hashed. Useful values
24828 include %Ln if user can log in with or without @@domain, %Ld if mailboxes
24829 are shared within domain.
24830 Defaults to @samp{"%Lu"}.
24833 @deftypevr {@code{dovecot-configuration} parameter} string log-path
24834 Log file to use for error messages. @samp{syslog} logs to syslog,
24835 @samp{/dev/stderr} logs to stderr.
24836 Defaults to @samp{"syslog"}.
24839 @deftypevr {@code{dovecot-configuration} parameter} string info-log-path
24840 Log file to use for informational messages. Defaults to
24842 Defaults to @samp{""}.
24845 @deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
24846 Log file to use for debug messages. Defaults to
24847 @samp{info-log-path}.
24848 Defaults to @samp{""}.
24851 @deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
24852 Syslog facility to use if you're logging to syslog. Usually if you
24853 don't want to use @samp{mail}, you'll use local0..local7. Also other
24854 standard facilities are supported.
24855 Defaults to @samp{"mail"}.
24858 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
24859 Log unsuccessful authentication attempts and the reasons why they
24861 Defaults to @samp{#f}.
24864 @deftypevr {@code{dovecot-configuration} parameter} string auth-verbose-passwords
24865 In case of password mismatches, log the attempted password. Valid
24866 values are no, plain and sha1. sha1 can be useful for detecting brute
24867 force password attempts vs. user simply trying the same password over
24868 and over again. You can also truncate the value to n chars by appending
24869 ":n" (e.g.@: sha1:6).
24870 Defaults to @samp{"no"}.
24873 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
24874 Even more verbose logging for debugging purposes. Shows for example
24876 Defaults to @samp{#f}.
24879 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
24880 In case of password mismatches, log the passwords and used scheme so
24881 the problem can be debugged. Enabling this also enables
24883 Defaults to @samp{#f}.
24886 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
24887 Enable mail process debugging. This can help you figure out why
24888 Dovecot isn't finding your mails.
24889 Defaults to @samp{#f}.
24892 @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
24893 Show protocol level SSL errors.
24894 Defaults to @samp{#f}.
24897 @deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
24898 Prefix for each line written to log file. % codes are in
24899 strftime(3) format.
24900 Defaults to @samp{"\"%b %d %H:%M:%S \""}.
24903 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
24904 List of elements we want to log. The elements which have a
24905 non-empty variable value are joined together to form a comma-separated
24909 @deftypevr {@code{dovecot-configuration} parameter} string login-log-format
24910 Login log format. %s contains @samp{login-log-format-elements}
24911 string, %$ contains the data we want to log.
24912 Defaults to @samp{"%$: %s"}.
24915 @deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
24916 Log prefix for mail processes. See doc/wiki/Variables.txt for list
24917 of possible variables you can use.
24918 Defaults to @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
24921 @deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
24922 Format to use for logging mail deliveries. You can use variables:
24925 Delivery status message (e.g.@: @samp{saved to INBOX})
24937 Defaults to @samp{"msgid=%m: %$"}.
24940 @deftypevr {@code{dovecot-configuration} parameter} string mail-location
24941 Location for users' mailboxes. The default is empty, which means
24942 that Dovecot tries to find the mailboxes automatically. This won't work
24943 if the user doesn't yet have any mail, so you should explicitly tell
24944 Dovecot the full location.
24946 If you're using mbox, giving a path to the INBOX
24947 file (e.g.@: @file{/var/mail/%u}) isn't enough. You'll also need to tell Dovecot
24948 where the other mailboxes are kept. This is called the @emph{root mail
24949 directory}, and it must be the first path given in the
24950 @samp{mail-location} setting.
24952 There are a few special variables you can use, e.g.:
24958 user part in user@@domain, same as %u if there's no domain
24960 domain part in user@@domain, empty if there's no domain
24965 See doc/wiki/Variables.txt for full list. Some examples:
24967 @item maildir:~/Maildir
24968 @item mbox:~/mail:INBOX=/var/mail/%u
24969 @item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
24971 Defaults to @samp{""}.
24974 @deftypevr {@code{dovecot-configuration} parameter} string mail-uid
24975 System user and group used to access mails. If you use multiple,
24976 userdb can override these by returning uid or gid fields. You can use
24977 either numbers or names. <doc/wiki/UserIds.txt>.
24978 Defaults to @samp{""}.
24981 @deftypevr {@code{dovecot-configuration} parameter} string mail-gid
24983 Defaults to @samp{""}.
24986 @deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
24987 Group to enable temporarily for privileged operations. Currently
24988 this is used only with INBOX when either its initial creation or
24989 dotlocking fails. Typically this is set to @samp{"mail"} to give access to
24991 Defaults to @samp{""}.
24994 @deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
24995 Grant access to these supplementary groups for mail processes.
24996 Typically these are used to set up access to shared mailboxes. Note
24997 that it may be dangerous to set these if users can create symlinks
24998 (e.g.@: if @samp{mail} group is set here, @code{ln -s /var/mail ~/mail/var}
24999 could allow a user to delete others' mailboxes, or @code{ln -s
25000 /secret/shared/box ~/mail/mybox} would allow reading it). Defaults to
25004 @deftypevr {@code{dovecot-configuration} parameter} string mail-attribute-dict
25005 The location of a dictionary used to store @code{IMAP METADATA}
25006 as defined by @uref{https://tools.ietf.org/html/rfc5464, RFC@tie{}5464}.
25008 The IMAP METADATA commands are available only if the ``imap''
25009 protocol configuration's @code{imap-metadata?} field is @samp{#t}.
25011 Defaults to @samp{""}.
25015 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
25016 Allow full file system access to clients. There's no access checks
25017 other than what the operating system does for the active UID/GID@. It
25018 works with both maildir and mboxes, allowing you to prefix mailboxes
25019 names with e.g.@: @file{/path/} or @file{~user/}.
25020 Defaults to @samp{#f}.
25023 @deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
25024 Don't use @code{mmap()} at all. This is required if you store indexes to
25025 shared file systems (NFS or clustered file system).
25026 Defaults to @samp{#f}.
25029 @deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
25030 Rely on @samp{O_EXCL} to work when creating dotlock files. NFS
25031 supports @samp{O_EXCL} since version 3, so this should be safe to use
25032 nowadays by default.
25033 Defaults to @samp{#t}.
25036 @deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
25037 When to use fsync() or fdatasync() calls:
25040 Whenever necessary to avoid losing important data
25042 Useful with e.g.@: NFS when @code{write()}s are delayed
25044 Never use it (best performance, but crashes can lose data).
25046 Defaults to @samp{"optimized"}.
25049 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
25050 Mail storage exists in NFS@. Set this to yes to make Dovecot flush
25051 NFS caches whenever needed. If you're using only a single mail server
25053 Defaults to @samp{#f}.
25056 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
25057 Mail index files also exist in NFS@. Setting this to yes requires
25058 @samp{mmap-disable? #t} and @samp{fsync-disable? #f}.
25059 Defaults to @samp{#f}.
25062 @deftypevr {@code{dovecot-configuration} parameter} string lock-method
25063 Locking method for index files. Alternatives are fcntl, flock and
25064 dotlock. Dotlocking uses some tricks which may create more disk I/O
25065 than other locking methods. NFS users: flock doesn't work, remember to
25066 change @samp{mmap-disable}.
25067 Defaults to @samp{"fcntl"}.
25070 @deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
25071 Directory in which LDA/LMTP temporarily stores incoming mails >128
25073 Defaults to @samp{"/tmp"}.
25076 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
25077 Valid UID range for users. This is mostly to make sure that users can't
25078 log in as daemons or other system users. Note that denying root logins is
25079 hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
25081 Defaults to @samp{500}.
25084 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid
25086 Defaults to @samp{0}.
25089 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
25090 Valid GID range for users. Users having non-valid GID as primary group ID
25091 aren't allowed to log in. If user belongs to supplementary groups with
25092 non-valid GIDs, those groups are not set.
25093 Defaults to @samp{1}.
25096 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid
25098 Defaults to @samp{0}.
25101 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
25102 Maximum allowed length for mail keyword name. It's only forced when
25103 trying to create new keywords.
25104 Defaults to @samp{50}.
25107 @deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
25108 List of directories under which chrooting is allowed for mail
25109 processes (i.e.@: @file{/var/mail} will allow chrooting to @file{/var/mail/foo/bar}
25110 too). This setting doesn't affect @samp{login-chroot}
25111 @samp{mail-chroot} or auth chroot settings. If this setting is empty,
25112 @samp{/./} in home dirs are ignored. WARNING: Never add directories here
25113 which local users can modify, that may lead to root exploit. Usually
25114 this should be done only if you don't allow shell access for users.
25115 <doc/wiki/Chrooting.txt>.
25116 Defaults to @samp{()}.
25119 @deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
25120 Default chroot directory for mail processes. This can be overridden
25121 for specific users in user database by giving @samp{/./} in user's home
25122 directory (e.g.@: @samp{/home/./user} chroots into @file{/home}). Note that usually
25123 there is no real need to do chrooting, Dovecot doesn't allow users to
25124 access files outside their mail directory anyway. If your home
25125 directories are prefixed with the chroot directory, append @samp{/.} to
25126 @samp{mail-chroot}. <doc/wiki/Chrooting.txt>.
25127 Defaults to @samp{""}.
25130 @deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path
25131 UNIX socket path to master authentication server to find users.
25132 This is used by imap (for shared users) and lda.
25133 Defaults to @samp{"/var/run/dovecot/auth-userdb"}.
25136 @deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
25137 Directory where to look up mail plugins.
25138 Defaults to @samp{"/usr/lib/dovecot"}.
25141 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
25142 List of plugins to load for all services. Plugins specific to IMAP,
25143 LDA, etc.@: are added to this list in their own .conf files.
25144 Defaults to @samp{()}.
25147 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
25148 The minimum number of mails in a mailbox before updates are done to
25149 cache file. This allows optimizing Dovecot's behavior to do less disk
25150 writes at the cost of more disk reads.
25151 Defaults to @samp{0}.
25154 @deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
25155 When IDLE command is running, mailbox is checked once in a while to
25156 see if there are any new mails or other changes. This setting defines
25157 the minimum time to wait between those checks. Dovecot can also use
25158 dnotify, inotify and kqueue to find out immediately when changes
25160 Defaults to @samp{"30 secs"}.
25163 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
25164 Save mails with CR+LF instead of plain LF@. This makes sending those
25165 mails take less CPU, especially with sendfile() syscall with Linux and
25166 FreeBSD@. But it also creates a bit more disk I/O which may just make it
25167 slower. Also note that if other software reads the mboxes/maildirs,
25168 they may handle the extra CRs wrong and cause problems.
25169 Defaults to @samp{#f}.
25172 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
25173 By default LIST command returns all entries in maildir beginning
25174 with a dot. Enabling this option makes Dovecot return only entries
25175 which are directories. This is done by stat()ing each entry, so it
25176 causes more disk I/O.
25177 (For systems setting struct @samp{dirent->d_type} this check is free
25178 and it's done always regardless of this setting).
25179 Defaults to @samp{#f}.
25182 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
25183 When copying a message, do it with hard links whenever possible.
25184 This makes the performance much better, and it's unlikely to have any
25186 Defaults to @samp{#t}.
25189 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
25190 Assume Dovecot is the only MUA accessing Maildir: Scan cur/
25191 directory only when its mtime changes unexpectedly or when we can't find
25192 the mail otherwise.
25193 Defaults to @samp{#f}.
25196 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
25197 Which locking methods to use for locking mbox. There are four
25202 Create <mailbox>.lock file. This is the oldest and most NFS-safe
25203 solution. If you want to use /var/mail/ like directory, the users will
25204 need write access to that directory.
25206 Same as dotlock, but if it fails because of permissions or because there
25207 isn't enough disk space, just skip it.
25209 Use this if possible. Works with NFS too if lockd is used.
25211 May not exist in all systems. Doesn't work with NFS.
25213 May not exist in all systems. Doesn't work with NFS.
25216 You can use multiple locking methods; if you do the order they're declared
25217 in is important to avoid deadlocks if other MTAs/MUAs are using multiple
25218 locking methods as well. Some operating systems don't allow using some of
25219 them simultaneously.
25222 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks
25226 @deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
25227 Maximum time to wait for lock (all of them) before aborting.
25228 Defaults to @samp{"5 mins"}.
25231 @deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
25232 If dotlock exists but the mailbox isn't modified in any way,
25233 override the lock file after this much time.
25234 Defaults to @samp{"2 mins"}.
25237 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
25238 When mbox changes unexpectedly we have to fully read it to find out
25239 what changed. If the mbox is large this can take a long time. Since
25240 the change is usually just a newly appended mail, it'd be faster to
25241 simply read the new mails. If this setting is enabled, Dovecot does
25242 this but still safely fallbacks to re-reading the whole mbox file
25243 whenever something in mbox isn't how it's expected to be. The only real
25244 downside to this setting is that if some other MUA changes message
25245 flags, Dovecot doesn't notice it immediately. Note that a full sync is
25246 done with SELECT, EXAMINE, EXPUNGE and CHECK commands.
25247 Defaults to @samp{#t}.
25250 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
25251 Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
25252 EXAMINE, EXPUNGE or CHECK commands. If this is set,
25253 @samp{mbox-dirty-syncs} is ignored.
25254 Defaults to @samp{#f}.
25257 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
25258 Delay writing mbox headers until doing a full write sync (EXPUNGE
25259 and CHECK commands and when closing the mailbox). This is especially
25260 useful for POP3 where clients often delete all mails. The downside is
25261 that our changes aren't immediately visible to other MUAs.
25262 Defaults to @samp{#t}.
25265 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
25266 If mbox size is smaller than this (e.g.@: 100k), don't write index
25267 files. If an index file already exists it's still read, just not
25269 Defaults to @samp{0}.
25272 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
25273 Maximum dbox file size until it's rotated.
25274 Defaults to @samp{10000000}.
25277 @deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
25278 Maximum dbox file age until it's rotated. Typically in days. Day
25279 begins from midnight, so 1d = today, 2d = yesterday, etc. 0 = check
25281 Defaults to @samp{"1d"}.
25284 @deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
25285 When creating new mdbox files, immediately preallocate their size to
25286 @samp{mdbox-rotate-size}. This setting currently works only in Linux
25287 with some file systems (ext4, xfs).
25288 Defaults to @samp{#f}.
25291 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
25292 sdbox and mdbox support saving mail attachments to external files,
25293 which also allows single instance storage for them. Other backends
25294 don't support this for now.
25296 WARNING: This feature hasn't been tested much yet. Use at your own risk.
25298 Directory root where to store mail attachments. Disabled, if empty.
25299 Defaults to @samp{""}.
25302 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
25303 Attachments smaller than this aren't saved externally. It's also
25304 possible to write a plugin to disable saving specific attachments
25306 Defaults to @samp{128000}.
25309 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
25310 File system backend to use for saving attachments:
25313 No SiS done by Dovecot (but this might help FS's own deduplication)
25315 SiS with immediate byte-by-byte comparison during saving
25316 @item sis-queue posix
25317 SiS with delayed comparison and deduplication.
25319 Defaults to @samp{"sis posix"}.
25322 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
25323 Hash format to use in attachment filenames. You can add any text and
25324 variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
25325 @code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be
25326 truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
25327 Defaults to @samp{"%@{sha1@}"}.
25330 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit
25332 Defaults to @samp{100}.
25335 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit
25337 Defaults to @samp{1000}.
25340 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
25341 Default VSZ (virtual memory size) limit for service processes.
25342 This is mainly intended to catch and kill processes that leak memory
25343 before they eat up everything.
25344 Defaults to @samp{256000000}.
25347 @deftypevr {@code{dovecot-configuration} parameter} string default-login-user
25348 Login user is internally used by login processes. This is the most
25349 untrusted user in Dovecot system. It shouldn't have access to anything
25351 Defaults to @samp{"dovenull"}.
25354 @deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
25355 Internal user is used by unprivileged processes. It should be
25356 separate from login user, so that login processes can't disturb other
25358 Defaults to @samp{"dovecot"}.
25361 @deftypevr {@code{dovecot-configuration} parameter} string ssl?
25362 SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>.
25363 Defaults to @samp{"required"}.
25366 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
25367 PEM encoded X.509 SSL/TLS certificate (public key).
25368 Defaults to @samp{"</etc/dovecot/default.pem"}.
25371 @deftypevr {@code{dovecot-configuration} parameter} string ssl-key
25372 PEM encoded SSL/TLS private key. The key is opened before
25373 dropping root privileges, so keep the key file unreadable by anyone but
25375 Defaults to @samp{"</etc/dovecot/private/default.pem"}.
25378 @deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
25379 If key file is password protected, give the password here.
25380 Alternatively give it when starting dovecot with -p parameter. Since
25381 this file is often world-readable, you may want to place this setting
25382 instead to a different.
25383 Defaults to @samp{""}.
25386 @deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
25387 PEM encoded trusted certificate authority. Set this only if you
25388 intend to use @samp{ssl-verify-client-cert? #t}. The file should
25389 contain the CA certificate(s) followed by the matching
25390 CRL(s). (e.g.@: @samp{ssl-ca </etc/ssl/certs/ca.pem}).
25391 Defaults to @samp{""}.
25394 @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
25395 Require that CRL check succeeds for client certificates.
25396 Defaults to @samp{#t}.
25399 @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
25400 Request client to send a certificate. If you also want to require
25401 it, set @samp{auth-ssl-require-client-cert? #t} in auth section.
25402 Defaults to @samp{#f}.
25405 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
25406 Which field from certificate to use for username. commonName and
25407 x500UniqueIdentifier are the usual choices. You'll also need to set
25408 @samp{auth-ssl-username-from-cert? #t}.
25409 Defaults to @samp{"commonName"}.
25412 @deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
25413 Minimum SSL protocol version to accept.
25414 Defaults to @samp{"TLSv1"}.
25417 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
25418 SSL ciphers to use.
25419 Defaults to @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
25422 @deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
25423 SSL crypto device to use, for valid values run "openssl engine".
25424 Defaults to @samp{""}.
25427 @deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
25428 Address to use when sending rejection mails.
25429 %d expands to recipient domain.
25430 Defaults to @samp{"postmaster@@%d"}.
25433 @deftypevr {@code{dovecot-configuration} parameter} string hostname
25434 Hostname to use in various parts of sent mails (e.g.@: in Message-Id)
25435 and in LMTP replies. Default is the system's real hostname@@domain.
25436 Defaults to @samp{""}.
25439 @deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
25440 If user is over quota, return with temporary failure instead of
25442 Defaults to @samp{#f}.
25445 @deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
25446 Binary to use for sending mails.
25447 Defaults to @samp{"/usr/sbin/sendmail"}.
25450 @deftypevr {@code{dovecot-configuration} parameter} string submission-host
25451 If non-empty, send mails via this SMTP host[:port] instead of
25453 Defaults to @samp{""}.
25456 @deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
25457 Subject: header to use for rejection mails. You can use the same
25458 variables as for @samp{rejection-reason} below.
25459 Defaults to @samp{"Rejected: %s"}.
25462 @deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
25463 Human readable error message for rejection mails. You can use
25476 Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
25479 @deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
25480 Delimiter character between local-part and detail in email
25482 Defaults to @samp{"+"}.
25485 @deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
25486 Header where the original recipient address (SMTP's RCPT TO:
25487 address) is taken from if not available elsewhere. With dovecot-lda -a
25488 parameter overrides this. A commonly used header for this is
25490 Defaults to @samp{""}.
25493 @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
25494 Should saving a mail to a nonexistent mailbox automatically create
25496 Defaults to @samp{#f}.
25499 @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
25500 Should automatically created mailboxes be also automatically
25502 Defaults to @samp{#f}.
25505 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
25506 Maximum IMAP command line length. Some clients generate very long
25507 command lines with huge mailboxes, so you may need to raise this if you
25508 get "Too long argument" or "IMAP command line too large" errors
25510 Defaults to @samp{64000}.
25513 @deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
25514 IMAP logout format string:
25517 total number of bytes read from client
25519 total number of bytes sent to client.
25521 See @file{doc/wiki/Variables.txt} for a list of all the variables you can use.
25522 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@}"}.
25525 @deftypevr {@code{dovecot-configuration} parameter} string imap-capability
25526 Override the IMAP CAPABILITY response. If the value begins with '+',
25527 add the given capabilities on top of the defaults (e.g.@: +XFOO XBAR).
25528 Defaults to @samp{""}.
25531 @deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
25532 How long to wait between "OK Still here" notifications when client
25534 Defaults to @samp{"2 mins"}.
25537 @deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
25538 ID field names and values to send to clients. Using * as the value
25539 makes Dovecot use the default value. The following fields have default
25540 values currently: name, version, os, os-version, support-url,
25542 Defaults to @samp{""}.
25545 @deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
25546 ID fields sent by client to log. * means everything.
25547 Defaults to @samp{""}.
25550 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
25551 Workarounds for various client bugs:
25554 @item delay-newmail
25555 Send EXISTS/RECENT new mail notifications only when replying to NOOP and
25556 CHECK commands. Some clients ignore them otherwise, for example OSX
25557 Mail (<v2.1). Outlook Express breaks more badly though, without this it
25558 may show user "Message no longer in server" errors. Note that OE6
25559 still breaks even with this workaround if synchronization is set to
25562 @item tb-extra-mailbox-sep
25563 Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and
25564 adds extra @samp{/} suffixes to mailbox names. This option causes Dovecot to
25565 ignore the extra @samp{/} instead of treating it as invalid mailbox name.
25567 @item tb-lsub-flags
25568 Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox).
25569 This makes Thunderbird realize they aren't selectable and show them
25570 greyed out, instead of only later giving "not selectable" popup error.
25572 Defaults to @samp{()}.
25575 @deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
25576 Host allowed in URLAUTH URLs sent by client. "*" allows all.
25577 Defaults to @samp{""}.
25581 Whew! Lots of configuration options. The nice thing about it though is
25582 that Guix has a complete interface to Dovecot's configuration
25583 language. This allows not only a nice way to declare configurations,
25584 but also offers reflective capabilities as well: users can write code to
25585 inspect and transform configurations from within Scheme.
25587 However, it could be that you just want to get a @code{dovecot.conf} up
25588 and running. In that case, you can pass an
25589 @code{opaque-dovecot-configuration} as the @code{#:config} parameter to
25590 @code{dovecot-service}. As its name indicates, an opaque configuration
25591 does not have easy reflective capabilities.
25593 Available @code{opaque-dovecot-configuration} fields are:
25595 @deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
25596 The dovecot package.
25599 @deftypevr {@code{opaque-dovecot-configuration} parameter} string string
25600 The contents of the @code{dovecot.conf}, as a string.
25603 For example, if your @code{dovecot.conf} is just the empty string, you
25604 could instantiate a dovecot service like this:
25607 (dovecot-service #:config
25608 (opaque-dovecot-configuration
25612 @subsubheading OpenSMTPD Service
25614 @deffn {Scheme Variable} opensmtpd-service-type
25615 This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD}
25616 service, whose value should be an @code{opensmtpd-configuration} object
25617 as in this example:
25620 (service opensmtpd-service-type
25621 (opensmtpd-configuration
25622 (config-file (local-file "./my-smtpd.conf"))))
25626 @deftp {Data Type} opensmtpd-configuration
25627 Data type representing the configuration of opensmtpd.
25630 @item @code{package} (default: @var{opensmtpd})
25631 Package object of the OpenSMTPD SMTP server.
25633 @item @code{config-file} (default: @code{%default-opensmtpd-config-file})
25634 File-like object of the OpenSMTPD configuration file to use. By default
25635 it listens on the loopback network interface, and allows for mail from
25636 users and daemons on the local machine, as well as permitting email to
25637 remote servers. Run @command{man smtpd.conf} for more information.
25639 @item @code{setgid-commands?} (default: @code{#t})
25640 Make the following commands setgid to @code{smtpq} so they can be
25641 executed: @command{smtpctl}, @command{sendmail}, @command{send-mail},
25642 @command{makemap}, @command{mailq}, and @command{newaliases}.
25643 @xref{Setuid Programs}, for more information on setgid programs.
25647 @subsubheading Exim Service
25649 @cindex mail transfer agent (MTA)
25650 @cindex MTA (mail transfer agent)
25653 @deffn {Scheme Variable} exim-service-type
25654 This is the type of the @uref{https://exim.org, Exim} mail transfer
25655 agent (MTA), whose value should be an @code{exim-configuration} object
25656 as in this example:
25659 (service exim-service-type
25660 (exim-configuration
25661 (config-file (local-file "./my-exim.conf"))))
25665 In order to use an @code{exim-service-type} service you must also have a
25666 @code{mail-aliases-service-type} service present in your
25667 @code{operating-system} (even if it has no aliases).
25669 @deftp {Data Type} exim-configuration
25670 Data type representing the configuration of exim.
25673 @item @code{package} (default: @var{exim})
25674 Package object of the Exim server.
25676 @item @code{config-file} (default: @code{#f})
25677 File-like object of the Exim configuration file to use. If its value is
25678 @code{#f} then use the default configuration file from the package
25679 provided in @code{package}. The resulting configuration file is loaded
25680 after setting the @code{exim_user} and @code{exim_group} configuration
25686 @subsubheading Getmail service
25691 @deffn {Scheme Variable} getmail-service-type
25692 This is the type of the @uref{http://pyropus.ca/software/getmail/, Getmail}
25693 mail retriever, whose value should be an @code{getmail-configuration}.
25696 Available @code{getmail-configuration} fields are:
25698 @deftypevr {@code{getmail-configuration} parameter} symbol name
25699 A symbol to identify the getmail service.
25701 Defaults to @samp{"unset"}.
25705 @deftypevr {@code{getmail-configuration} parameter} package package
25706 The getmail package to use.
25710 @deftypevr {@code{getmail-configuration} parameter} string user
25711 The user to run getmail as.
25713 Defaults to @samp{"getmail"}.
25717 @deftypevr {@code{getmail-configuration} parameter} string group
25718 The group to run getmail as.
25720 Defaults to @samp{"getmail"}.
25724 @deftypevr {@code{getmail-configuration} parameter} string directory
25725 The getmail directory to use.
25727 Defaults to @samp{"/var/lib/getmail/default"}.
25731 @deftypevr {@code{getmail-configuration} parameter} getmail-configuration-file rcfile
25732 The getmail configuration file to use.
25734 Available @code{getmail-configuration-file} fields are:
25736 @deftypevr {@code{getmail-configuration-file} parameter} getmail-retriever-configuration retriever
25737 What mail account to retrieve mail from, and how to access that account.
25739 Available @code{getmail-retriever-configuration} fields are:
25741 @deftypevr {@code{getmail-retriever-configuration} parameter} string type
25742 The type of mail retriever to use. Valid values include @samp{passwd}
25745 Defaults to @samp{"SimpleIMAPSSLRetriever"}.
25749 @deftypevr {@code{getmail-retriever-configuration} parameter} string server
25750 Username to login to the mail server with.
25752 Defaults to @samp{unset}.
25756 @deftypevr {@code{getmail-retriever-configuration} parameter} string username
25757 Username to login to the mail server with.
25759 Defaults to @samp{unset}.
25763 @deftypevr {@code{getmail-retriever-configuration} parameter} non-negative-integer port
25764 Port number to connect to.
25766 Defaults to @samp{#f}.
25770 @deftypevr {@code{getmail-retriever-configuration} parameter} string password
25771 Override fields from passwd.
25773 Defaults to @samp{""}.
25777 @deftypevr {@code{getmail-retriever-configuration} parameter} list password-command
25778 Override fields from passwd.
25780 Defaults to @samp{()}.
25784 @deftypevr {@code{getmail-retriever-configuration} parameter} string keyfile
25785 PEM-formatted key file to use for the TLS negotiation.
25787 Defaults to @samp{""}.
25791 @deftypevr {@code{getmail-retriever-configuration} parameter} string certfile
25792 PEM-formatted certificate file to use for the TLS negotiation.
25794 Defaults to @samp{""}.
25798 @deftypevr {@code{getmail-retriever-configuration} parameter} string ca-certs
25799 CA certificates to use.
25801 Defaults to @samp{""}.
25805 @deftypevr {@code{getmail-retriever-configuration} parameter} parameter-alist extra-parameters
25806 Extra retriever parameters.
25808 Defaults to @samp{()}.
25814 @deftypevr {@code{getmail-configuration-file} parameter} getmail-destination-configuration destination
25815 What to do with retrieved messages.
25817 Available @code{getmail-destination-configuration} fields are:
25819 @deftypevr {@code{getmail-destination-configuration} parameter} string type
25820 The type of mail destination. Valid values include @samp{Maildir},
25821 @samp{Mboxrd} and @samp{MDA_external}.
25823 Defaults to @samp{unset}.
25827 @deftypevr {@code{getmail-destination-configuration} parameter} string-or-filelike path
25828 The path option for the mail destination. The behaviour depends on the
25831 Defaults to @samp{""}.
25835 @deftypevr {@code{getmail-destination-configuration} parameter} parameter-alist extra-parameters
25836 Extra destination parameters
25838 Defaults to @samp{()}.
25844 @deftypevr {@code{getmail-configuration-file} parameter} getmail-options-configuration options
25847 Available @code{getmail-options-configuration} fields are:
25849 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer verbose
25850 If set to @samp{0}, getmail will only print warnings and errors. A
25851 value of @samp{1} means that messages will be printed about retrieving
25852 and deleting messages. If set to @samp{2}, getmail will print messages
25853 about each of its actions.
25855 Defaults to @samp{1}.
25859 @deftypevr {@code{getmail-options-configuration} parameter} boolean read-all
25860 If true, getmail will retrieve all available messages. Otherwise it
25861 will only retrieve messages it hasn't seen previously.
25863 Defaults to @samp{#t}.
25867 @deftypevr {@code{getmail-options-configuration} parameter} boolean delete
25868 If set to true, messages will be deleted from the server after
25869 retrieving and successfully delivering them. Otherwise, messages will
25870 be left on the server.
25872 Defaults to @samp{#f}.
25876 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-after
25877 Getmail will delete messages this number of days after seeing them, if
25878 they have been delivered. This means messages will be left on the
25879 server this number of days after delivering them. A value of @samp{0}
25880 disabled this feature.
25882 Defaults to @samp{0}.
25886 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer delete-bigger-than
25887 Delete messages larger than this of bytes after retrieving them, even if
25888 the delete and delete-after options are disabled. A value of @samp{0}
25889 disables this feature.
25891 Defaults to @samp{0}.
25895 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-bytes-per-session
25896 Retrieve messages totalling up to this number of bytes before closing
25897 the session with the server. A value of @samp{0} disables this feature.
25899 Defaults to @samp{0}.
25903 @deftypevr {@code{getmail-options-configuration} parameter} non-negative-integer max-message-size
25904 Don't retrieve messages larger than this number of bytes. A value of
25905 @samp{0} disables this feature.
25907 Defaults to @samp{0}.
25911 @deftypevr {@code{getmail-options-configuration} parameter} boolean delivered-to
25912 If true, getmail will add a Delivered-To header to messages.
25914 Defaults to @samp{#t}.
25918 @deftypevr {@code{getmail-options-configuration} parameter} boolean received
25919 If set, getmail adds a Received header to the messages.
25921 Defaults to @samp{#t}.
25925 @deftypevr {@code{getmail-options-configuration} parameter} string message-log
25926 Getmail will record a log of its actions to the named file. A value of
25927 @samp{""} disables this feature.
25929 Defaults to @samp{""}.
25933 @deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-syslog
25934 If true, getmail will record a log of its actions using the system
25937 Defaults to @samp{#f}.
25941 @deftypevr {@code{getmail-options-configuration} parameter} boolean message-log-verbose
25942 If true, getmail will log information about messages not retrieved and
25943 the reason for not retrieving them, as well as starting and ending
25946 Defaults to @samp{#f}.
25950 @deftypevr {@code{getmail-options-configuration} parameter} parameter-alist extra-parameters
25951 Extra options to include.
25953 Defaults to @samp{()}.
25961 @deftypevr {@code{getmail-configuration} parameter} list idle
25962 A list of mailboxes that getmail should wait on the server for new mail
25963 notifications. This depends on the server supporting the IDLE
25966 Defaults to @samp{()}.
25970 @deftypevr {@code{getmail-configuration} parameter} list environment-variables
25971 Environment variables to set for getmail.
25973 Defaults to @samp{()}.
25977 @subsubheading Mail Aliases Service
25979 @cindex email aliases
25980 @cindex aliases, for email addresses
25982 @deffn {Scheme Variable} mail-aliases-service-type
25983 This is the type of the service which provides @code{/etc/aliases},
25984 specifying how to deliver mail to users on this system.
25987 (service mail-aliases-service-type
25988 '(("postmaster" "bob")
25989 ("bob" "bob@@example.com" "bob@@example2.com")))
25993 The configuration for a @code{mail-aliases-service-type} service is an
25994 association list denoting how to deliver mail that comes to this
25995 system. Each entry is of the form @code{(alias addresses ...)}, with
25996 @code{alias} specifying the local alias and @code{addresses} specifying
25997 where to deliver this user's mail.
25999 The aliases aren't required to exist as users on the local system. In
26000 the above example, there doesn't need to be a @code{postmaster} entry in
26001 the @code{operating-system}'s @code{user-accounts} in order to deliver
26002 the @code{postmaster} mail to @code{bob} (which subsequently would
26003 deliver mail to @code{bob@@example.com} and @code{bob@@example2.com}).
26005 @subsubheading GNU Mailutils IMAP4 Daemon
26006 @cindex GNU Mailutils IMAP4 Daemon
26008 @deffn {Scheme Variable} imap4d-service-type
26009 This is the type of the GNU Mailutils IMAP4 Daemon (@pxref{imap4d,,,
26010 mailutils, GNU Mailutils Manual}), whose value should be an
26011 @code{imap4d-configuration} object as in this example:
26014 (service imap4d-service-type
26015 (imap4d-configuration
26016 (config-file (local-file "imap4d.conf"))))
26020 @deftp {Data Type} imap4d-configuration
26021 Data type representing the configuration of @command{imap4d}.
26024 @item @code{package} (default: @code{mailutils})
26025 The package that provides @command{imap4d}.
26027 @item @code{config-file} (default: @code{%default-imap4d-config-file})
26028 File-like object of the configuration file to use, by default it will listen
26029 on TCP port 143 of @code{localhost}. @xref{Conf-imap4d,,, mailutils, GNU
26030 Mailutils Manual}, for details.
26035 @subsubheading Radicale Service
26039 @deffn {Scheme Variable} radicale-service-type
26040 This is the type of the @uref{https://radicale.org, Radicale} CalDAV/CardDAV
26041 server whose value should be a @code{radicale-configuration}.
26044 @deftp {Data Type} radicale-configuration
26045 Data type representing the configuration of @command{radicale}.
26048 @item @code{package} (default: @code{radicale})
26049 The package that provides @command{radicale}.
26051 @item @code{config-file} (default: @code{%default-radicale-config-file})
26052 File-like object of the configuration file to use, by default it will listen
26053 on TCP port 5232 of @code{localhost} and use the @code{htpasswd} file at
26054 @file{/var/lib/radicale/users} with no (@code{plain}) encryption.
26059 @node Messaging Services
26060 @subsection Messaging Services
26065 The @code{(gnu services messaging)} module provides Guix service
26066 definitions for messaging services. Currently it provides the following
26069 @subsubheading Prosody Service
26071 @deffn {Scheme Variable} prosody-service-type
26072 This is the type for the @uref{https://prosody.im, Prosody XMPP
26073 communication server}. Its value must be a @code{prosody-configuration}
26074 record as in this example:
26077 (service prosody-service-type
26078 (prosody-configuration
26079 (modules-enabled (cons* "groups" "mam" %default-modules-enabled))
26082 (int-component-configuration
26083 (hostname "conference.example.net")
26085 (mod-muc (mod-muc-configuration)))))
26088 (virtualhost-configuration
26089 (domain "example.net"))))))
26092 See below for details about @code{prosody-configuration}.
26096 By default, Prosody does not need much configuration. Only one
26097 @code{virtualhosts} field is needed: it specifies the domain you wish
26100 You can perform various sanity checks on the generated configuration
26101 with the @code{prosodyctl check} command.
26103 Prosodyctl will also help you to import certificates from the
26104 @code{letsencrypt} directory so that the @code{prosody} user can access
26105 them. See @url{https://prosody.im/doc/letsencrypt}.
26108 prosodyctl --root cert import /etc/letsencrypt/live
26111 The available configuration parameters follow. Each parameter
26112 definition is preceded by its type; for example, @samp{string-list foo}
26113 indicates that the @code{foo} parameter should be specified as a list of
26114 strings. Types starting with @code{maybe-} denote parameters that won't
26115 show up in @code{prosody.cfg.lua} when their value is left unspecified.
26117 There is also a way to specify the configuration as a string, if you
26118 have an old @code{prosody.cfg.lua} file that you want to port over from
26119 some other system; see the end for more details.
26121 The @code{file-object} type designates either a file-like object
26122 (@pxref{G-Expressions, file-like objects}) or a file name.
26124 @c The following documentation was initially generated by
26125 @c (generate-documentation) in (gnu services messaging). Manually maintained
26126 @c documentation is better, so we shouldn't hesitate to edit below as
26127 @c needed. However if the change you want to make to this documentation
26128 @c can be done in an automated way, it's probably easier to change
26129 @c (generate-documentation) than to make it below and have to deal with
26130 @c the churn as Prosody updates.
26132 Available @code{prosody-configuration} fields are:
26134 @deftypevr {@code{prosody-configuration} parameter} package prosody
26135 The Prosody package.
26138 @deftypevr {@code{prosody-configuration} parameter} file-name data-path
26139 Location of the Prosody data storage directory. See
26140 @url{https://prosody.im/doc/configure}.
26141 Defaults to @samp{"/var/lib/prosody"}.
26144 @deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
26145 Additional plugin directories. They are searched in all the specified
26146 paths in order. See @url{https://prosody.im/doc/plugins_directory}.
26147 Defaults to @samp{()}.
26150 @deftypevr {@code{prosody-configuration} parameter} file-name certificates
26151 Every virtual host and component needs a certificate so that clients and
26152 servers can securely verify its identity. Prosody will automatically load
26153 certificates/keys from the directory specified here.
26154 Defaults to @samp{"/etc/prosody/certs"}.
26157 @deftypevr {@code{prosody-configuration} parameter} string-list admins
26158 This is a list of accounts that are admins for the server. Note that you
26159 must create the accounts separately. See @url{https://prosody.im/doc/admins} and
26160 @url{https://prosody.im/doc/creating_accounts}.
26161 Example: @code{(admins '("user1@@example.com" "user2@@example.net"))}
26162 Defaults to @samp{()}.
26165 @deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
26166 Enable use of libevent for better performance under high load. See
26167 @url{https://prosody.im/doc/libevent}.
26168 Defaults to @samp{#f}.
26171 @deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
26172 This is the list of modules Prosody will load on startup. It looks for
26173 @code{mod_modulename.lua} in the plugins folder, so make sure that exists too.
26174 Documentation on modules can be found at:
26175 @url{https://prosody.im/doc/modules}.
26176 Defaults to @samp{("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
26179 @deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
26180 @samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but
26181 should you want to disable them then add them to this list.
26182 Defaults to @samp{()}.
26185 @deftypevr {@code{prosody-configuration} parameter} file-object groups-file
26186 Path to a text file where the shared groups are defined. If this path is
26187 empty then @samp{mod_groups} does nothing. See
26188 @url{https://prosody.im/doc/modules/mod_groups}.
26189 Defaults to @samp{"/var/lib/prosody/sharedgroups.txt"}.
26192 @deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
26193 Disable account creation by default, for security. See
26194 @url{https://prosody.im/doc/creating_accounts}.
26195 Defaults to @samp{#f}.
26198 @deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
26199 These are the SSL/TLS-related settings. Most of them are disabled so to
26200 use Prosody's defaults. If you do not completely understand these options, do
26201 not add them to your config, it is easy to lower the security of your server
26202 using them. See @url{https://prosody.im/doc/advanced_ssl_config}.
26204 Available @code{ssl-configuration} fields are:
26206 @deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
26207 This determines what handshake to use.
26210 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name key
26211 Path to your private key file.
26214 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate
26215 Path to your certificate file.
26218 @deftypevr {@code{ssl-configuration} parameter} file-object capath
26219 Path to directory containing root certificates that you wish Prosody to
26220 trust when verifying the certificates of remote servers.
26221 Defaults to @samp{"/etc/ssl/certs"}.
26224 @deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
26225 Path to a file containing root certificates that you wish Prosody to trust.
26226 Similar to @code{capath} but with all certificates concatenated together.
26229 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
26230 A list of verification options (these mostly map to OpenSSL's
26231 @code{set_verify()} flags).
26234 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
26235 A list of general options relating to SSL/TLS@. These map to OpenSSL's
26236 @code{set_options()}. For a full list of options available in LuaSec, see the
26240 @deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
26241 How long a chain of certificate authorities to check when looking for a
26242 trusted root certificate.
26245 @deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
26246 An OpenSSL cipher string. This selects what ciphers Prosody will offer to
26247 clients, and in what order.
26250 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
26251 A path to a file containing parameters for Diffie-Hellman key exchange. You
26252 can create such a file with:
26253 @code{openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048}
26256 @deftypevr {@code{ssl-configuration} parameter} maybe-string curve
26257 Curve for Elliptic curve Diffie-Hellman. Prosody's default is
26258 @samp{"secp384r1"}.
26261 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
26262 A list of ``extra'' verification options.
26265 @deftypevr {@code{ssl-configuration} parameter} maybe-string password
26266 Password for encrypted private keys.
26271 @deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
26272 Whether to force all client-to-server connections to be encrypted or not.
26273 See @url{https://prosody.im/doc/modules/mod_tls}.
26274 Defaults to @samp{#f}.
26277 @deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
26278 Set of mechanisms that will never be offered. See
26279 @url{https://prosody.im/doc/modules/mod_saslauth}.
26280 Defaults to @samp{("DIGEST-MD5")}.
26283 @deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
26284 Whether to force all server-to-server connections to be encrypted or not.
26285 See @url{https://prosody.im/doc/modules/mod_tls}.
26286 Defaults to @samp{#f}.
26289 @deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
26290 Whether to require encryption and certificate authentication. This
26291 provides ideal security, but requires servers you communicate with to support
26292 encryption AND present valid, trusted certificates. See
26293 @url{https://prosody.im/doc/s2s#security}.
26294 Defaults to @samp{#f}.
26297 @deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
26298 Many servers don't support encryption or have invalid or self-signed
26299 certificates. You can list domains here that will not be required to
26300 authenticate using certificates. They will be authenticated using DNS@. See
26301 @url{https://prosody.im/doc/s2s#security}.
26302 Defaults to @samp{()}.
26305 @deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
26306 Even if you leave @code{s2s-secure-auth?} disabled, you can still require
26307 valid certificates for some domains by specifying a list here. See
26308 @url{https://prosody.im/doc/s2s#security}.
26309 Defaults to @samp{()}.
26312 @deftypevr {@code{prosody-configuration} parameter} string authentication
26313 Select the authentication backend to use. The default provider stores
26314 passwords in plaintext and uses Prosody's configured data storage to store the
26315 authentication data. If you do not trust your server please see
26316 @url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for information
26317 about using the hashed backend. See also
26318 @url{https://prosody.im/doc/authentication}
26319 Defaults to @samp{"internal_plain"}.
26322 @deftypevr {@code{prosody-configuration} parameter} maybe-string log
26323 Set logging options. Advanced logging configuration is not yet supported
26324 by the Prosody service. See @url{https://prosody.im/doc/logging}.
26325 Defaults to @samp{"*syslog"}.
26328 @deftypevr {@code{prosody-configuration} parameter} file-name pidfile
26329 File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}.
26330 Defaults to @samp{"/var/run/prosody/prosody.pid"}.
26333 @deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size
26334 Maximum allowed size of the HTTP body (in bytes).
26337 @deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url
26338 Some modules expose their own URL in various ways. This URL is built
26339 from the protocol, host and port used. If Prosody sits behind a proxy, the
26340 public URL will be @code{http-external-url} instead. See
26341 @url{https://prosody.im/doc/http#external_url}.
26344 @deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
26345 A host in Prosody is a domain on which user accounts can be created. For
26346 example if you want your users to have addresses like
26347 @samp{"john.smith@@example.com"} then you need to add a host
26348 @samp{"example.com"}. All options in this list will apply only to this host.
26351 The name @emph{virtual} host is used in configuration to avoid confusion with
26352 the actual physical host that Prosody is installed on. A single Prosody
26353 instance can serve many domains, each one defined as a VirtualHost entry in
26354 Prosody's configuration. Conversely a server that hosts a single domain would
26355 have just one VirtualHost entry.
26357 See @url{https://prosody.im/doc/configure#virtual_host_settings}.
26360 Available @code{virtualhost-configuration} fields are:
26362 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:
26363 @deftypevr {@code{virtualhost-configuration} parameter} string domain
26364 Domain you wish Prosody to serve.
26369 @deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components
26370 Components are extra services on a server which are available to clients,
26371 usually on a subdomain of the main server (such as
26372 @samp{"mycomponent.example.com"}). Example components might be chatroom
26373 servers, user directories, or gateways to other protocols.
26375 Internal components are implemented with Prosody-specific plugins. To add an
26376 internal component, you simply fill the hostname field, and the plugin you wish
26377 to use for the component.
26379 See @url{https://prosody.im/doc/components}.
26380 Defaults to @samp{()}.
26382 Available @code{int-component-configuration} fields are:
26384 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:
26385 @deftypevr {@code{int-component-configuration} parameter} string hostname
26386 Hostname of the component.
26389 @deftypevr {@code{int-component-configuration} parameter} string plugin
26390 Plugin you wish to use for the component.
26393 @deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc
26394 Multi-user chat (MUC) is Prosody's module for allowing you to create
26395 hosted chatrooms/conferences for XMPP users.
26397 General information on setting up and using multi-user chatrooms can be found
26398 in the ``Chatrooms'' documentation (@url{https://prosody.im/doc/chatrooms}),
26399 which you should read if you are new to XMPP chatrooms.
26401 See also @url{https://prosody.im/doc/modules/mod_muc}.
26403 Available @code{mod-muc-configuration} fields are:
26405 @deftypevr {@code{mod-muc-configuration} parameter} string name
26406 The name to return in service discovery responses.
26407 Defaults to @samp{"Prosody Chatrooms"}.
26410 @deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation
26411 If @samp{#t}, this will only allow admins to create new chatrooms.
26412 Otherwise anyone can create a room. The value @samp{"local"} restricts room
26413 creation to users on the service's parent domain. E.g.@: @samp{user@@example.com}
26414 can create rooms on @samp{rooms.example.com}. The value @samp{"admin"}
26415 restricts to service administrators only.
26416 Defaults to @samp{#f}.
26419 @deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages
26420 Maximum number of history messages that will be sent to the member that has
26421 just joined the room.
26422 Defaults to @samp{20}.
26429 @deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
26430 External components use XEP-0114, which most standalone components
26431 support. To add an external component, you simply fill the hostname field. See
26432 @url{https://prosody.im/doc/components}.
26433 Defaults to @samp{()}.
26435 Available @code{ext-component-configuration} fields are:
26437 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:
26438 @deftypevr {@code{ext-component-configuration} parameter} string component-secret
26439 Password which the component will use to log in.
26442 @deftypevr {@code{ext-component-configuration} parameter} string hostname
26443 Hostname of the component.
26448 @deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
26449 Port(s) Prosody listens on for component connections.
26450 Defaults to @samp{(5347)}.
26453 @deftypevr {@code{prosody-configuration} parameter} string component-interface
26454 Interface Prosody listens on for component connections.
26455 Defaults to @samp{"127.0.0.1"}.
26458 @deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content
26459 Raw content that will be added to the configuration file.
26462 It could be that you just want to get a @code{prosody.cfg.lua}
26463 up and running. In that case, you can pass an
26464 @code{opaque-prosody-configuration} record as the value of
26465 @code{prosody-service-type}. As its name indicates, an opaque configuration
26466 does not have easy reflective capabilities.
26467 Available @code{opaque-prosody-configuration} fields are:
26469 @deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
26470 The prosody package.
26473 @deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
26474 The contents of the @code{prosody.cfg.lua} to use.
26477 For example, if your @code{prosody.cfg.lua} is just the empty
26478 string, you could instantiate a prosody service like this:
26481 (service prosody-service-type
26482 (opaque-prosody-configuration
26483 (prosody.cfg.lua "")))
26486 @c end of Prosody auto-generated documentation
26488 @subsubheading BitlBee Service
26490 @cindex IRC (Internet Relay Chat)
26491 @cindex IRC gateway
26492 @url{https://bitlbee.org,BitlBee} is a gateway that provides an IRC
26493 interface to a variety of messaging protocols such as XMPP.
26495 @defvr {Scheme Variable} bitlbee-service-type
26496 This is the service type for the @url{https://bitlbee.org,BitlBee} IRC
26497 gateway daemon. Its value is a @code{bitlbee-configuration} (see
26500 To have BitlBee listen on port 6667 on localhost, add this line to your
26504 (service bitlbee-service-type)
26508 @deftp {Data Type} bitlbee-configuration
26509 This is the configuration for BitlBee, with the following fields:
26512 @item @code{interface} (default: @code{"127.0.0.1"})
26513 @itemx @code{port} (default: @code{6667})
26514 Listen on the network interface corresponding to the IP address
26515 specified in @var{interface}, on @var{port}.
26517 When @var{interface} is @code{127.0.0.1}, only local clients can
26518 connect; when it is @code{0.0.0.0}, connections can come from any
26519 networking interface.
26521 @item @code{bitlbee} (default: @code{bitlbee})
26522 The BitlBee package to use.
26524 @item @code{plugins} (default: @code{'()})
26525 List of plugin packages to use---e.g., @code{bitlbee-discord}.
26527 @item @code{extra-settings} (default: @code{""})
26528 Configuration snippet added as-is to the BitlBee configuration file.
26532 @subsubheading Quassel Service
26534 @cindex IRC (Internet Relay Chat)
26535 @url{https://quassel-irc.org/,Quassel} is a distributed IRC client,
26536 meaning that one or more clients can attach to and detach from the
26539 @defvr {Scheme Variable} quassel-service-type
26540 This is the service type for the @url{https://quassel-irc.org/,Quassel}
26541 IRC backend daemon. Its value is a @code{quassel-configuration}
26545 @deftp {Data Type} quassel-configuration
26546 This is the configuration for Quassel, with the following fields:
26549 @item @code{quassel} (default: @code{quassel})
26550 The Quassel package to use.
26552 @item @code{interface} (default: @code{"::,0.0.0.0"})
26553 @item @code{port} (default: @code{4242})
26554 Listen on the network interface(s) corresponding to the IPv4 or IPv6
26555 interfaces specified in the comma delimited @var{interface}, on
26558 @item @code{loglevel} (default: @code{"Info"})
26559 The level of logging desired. Accepted values are Debug, Info, Warning
26564 @node Telephony Services
26565 @subsection Telephony Services
26567 @cindex telephony, services
26568 The @code{(gnu services telephony)} module contains Guix service
26569 definitions for telephony services. Currently it provides the following
26572 @subsubheading Jami
26574 @cindex jami, service
26576 This section describes how to configure a Jami server that can be used
26577 to host video (or audio) conferences, among other uses. The following
26578 example demonstrates how to specify Jami account archives (backups) to
26579 be provisioned automatically:
26582 (service jami-service-type
26583 (jami-configuration
26585 (list (jami-account
26586 (archive "/etc/jami/unencrypted-account-1.gz"))
26588 (archive "/etc/jami/unencrypted-account-2.gz"))))))
26591 When the accounts field is specified, the Jami account files of the
26592 service found under @file{/var/lib/jami} are recreated every time the
26595 Jami accounts and their corresponding backup archives can be generated
26596 using the @code{jami} or @code{jami-gnome} Jami clients. The accounts
26597 should not be password-protected, but it is wise to ensure their files
26598 are only readable by @samp{root}.
26600 The next example shows how to declare that only some contacts should be
26601 allowed to communicate with a given account:
26604 (service jami-service-type
26605 (jami-configuration
26607 (list (jami-account
26608 (archive "/etc/jami/unencrypted-account-1.gz")
26609 (peer-discovery? #t)
26610 (rendezvous-point? #t)
26612 '("1dbcb0f5f37324228235564b79f2b9737e9a008f"
26613 "2dbcb0f5f37324228235564b79f2b9737e9a008f")))))))
26616 In this mode, only the declared @code{allowed-contacts} can initiate
26617 communication with the Jami account. This can be used, for example,
26618 with rendezvous point accounts to create a private video conferencing
26621 To put the system administrator in full control of the conferences
26622 hosted on their system, the Jami service supports the following actions:
26625 # herd doc jami list-actions
26627 list-account-details
26628 list-banned-contacts
26637 The above actions aim to provide the most valuable actions for
26638 moderation purposes, not to cover the whole Jami API. Users wanting to
26639 interact with the Jami daemon from Guile may be interested in
26640 experimenting with the @code{(gnu build jami-service)} module, which
26641 powers the above Shepherd actions.
26643 @c TODO: This should be auto-generated from the doc already defined on
26644 @c the shepherd-actions themselves in (gnu services telephony).
26645 The @code{add-moderator} and @code{ban-contact} actions accept a contact
26646 @emph{fingerprint} (40 characters long hash) as first argument and an
26647 account fingerprint or username as second argument:
26650 # herd add-moderator jami 1dbcb0f5f37324228235564b79f2b9737e9a008f \
26651 f3345f2775ddfe07a4b0d95daea111d15fbc1199
26653 # herd list-moderators jami
26654 Moderators for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
26655 - 1dbcb0f5f37324228235564b79f2b9737e9a008f
26659 In the case of @code{ban-contact}, the second username argument is
26660 optional; when omitted, the account is banned from all Jami accounts:
26663 # herd ban-contact jami 1dbcb0f5f37324228235564b79f2b9737e9a008f
26665 # herd list-banned-contacts jami
26666 Banned contacts for account f3345f2775ddfe07a4b0d95daea111d15fbc1199:
26667 - 1dbcb0f5f37324228235564b79f2b9737e9a008f
26671 Banned contacts are also stripped from their moderation privileges.
26673 The @code{disable-account} action allows to completely disconnect an
26674 account from the network, making it unreachable, while
26675 @code{enable-account} does the inverse. They accept a single account
26676 username or fingerprint as first argument:
26679 # herd disable-account jami f3345f2775ddfe07a4b0d95daea111d15fbc1199
26681 # herd list-accounts jami
26682 The following Jami accounts are available:
26683 - f3345f2775ddfe07a4b0d95daea111d15fbc1199 (dummy) [disabled]
26687 The @code{list-account-details} action prints the detailed parameters of
26688 each accounts in the Recutils format, which means the @command{recsel}
26689 command can be used to select accounts of interest (@pxref{Selection
26690 Expressions,,,recutils, GNU recutils manual}). Note that period
26691 characters (@samp{.}) found in the account parameter keys are mapped to
26692 underscores (@samp{_}) in the output, to meet the requirements of the
26693 Recutils format. The following example shows how to print the account
26694 fingerprints for all accounts operating in the rendezvous point mode:
26697 # herd list-account-details jami | \
26698 recsel -p Account.username -e 'Account.rendezVous ~ "true"'
26699 Account_username: f3345f2775ddfe07a4b0d95daea111d15fbc1199
26702 The remaining actions should be self-explanatory.
26704 The complete set of available configuration options is detailed below.
26706 @c TODO: Ideally, the following fragments would be auto-generated at
26707 @c build time, so that they needn't be manually duplicated.
26708 @c Auto-generated via (configuration->documentation 'jami-configuration)
26709 @deftp {Data Type} jami-configuration
26710 Available @code{jami-configuration} fields are:
26713 @item @code{libjami} (default: @code{libjami}) (type: package)
26714 The Jami daemon package to use.
26716 @item @code{dbus} (default: @code{dbus-for-jami}) (type: package)
26717 The D-Bus package to use to start the required D-Bus session.
26719 @item @code{nss-certs} (default: @code{nss-certs}) (type: package)
26720 The nss-certs package to use to provide TLS certificates.
26722 @item @code{enable-logging?} (default: @code{#t}) (type: boolean)
26723 Whether to enable logging to syslog.
26725 @item @code{debug?} (default: @code{#f}) (type: boolean)
26726 Whether to enable debug level messages.
26728 @item @code{auto-answer?} (default: @code{#f}) (type: boolean)
26729 Whether to force automatic answer to incoming calls.
26731 @item @code{accounts} (type: maybe-jami-account-list)
26732 A list of Jami accounts to be (re-)provisioned every time the Jami
26733 daemon service starts. When providing this field, the account
26734 directories under @file{/var/lib/jami/} are recreated every time the
26735 service starts, ensuring a consistent state.
26741 @c Auto-generated via (configuration->documentation 'jami-account)
26742 @deftp {Data Type} jami-account
26743 Available @code{jami-account} fields are:
26746 @item @code{archive} (type: string-or-computed-file)
26747 The account archive (backup) file name of the account. This is used to
26748 provision the account when the service starts. The account archive
26749 should @emph{not} be encrypted. It is highly recommended to make it
26750 readable only to the @samp{root} user (i.e., not in the store), to guard
26751 against leaking the secret key material of the Jami account it contains.
26753 @item @code{allowed-contacts} (type: maybe-account-fingerprint-list)
26754 The list of allowed contacts for the account, entered as their 40
26755 characters long fingerprint. Messages or calls from accounts not in
26756 that list will be rejected. When left specified, the configuration of
26757 the account archive is used as-is with respect to contacts and public
26758 inbound calls/messaging allowance, which typically defaults to allow any
26759 contact to communicate with the account.
26761 @item @code{moderators} (type: maybe-account-fingerprint-list)
26762 The list of contacts that should have moderation privileges (to ban,
26763 mute, etc. other users) in rendezvous conferences, entered as their 40
26764 characters long fingerprint. When left unspecified, the configuration
26765 of the account archive is used as-is with respect to moderation, which
26766 typically defaults to allow anyone to moderate.
26768 @item @code{rendezvous-point?} (type: maybe-boolean)
26769 Whether the account should operate in the rendezvous mode. In this
26770 mode, all the incoming audio/video calls are mixed into a conference.
26771 When left unspecified, the value from the account archive prevails.
26773 @item @code{peer-discovery?} (type: maybe-boolean)
26774 Whether peer discovery should be enabled. Peer discovery is used to
26775 discover other OpenDHT nodes on the local network, which can be useful
26776 to maintain communication between devices on such network even when the
26777 connection to the Internet has been lost. When left unspecified,
26778 the value from the account archive prevails.
26780 @item @code{bootstrap-hostnames} (type: maybe-string-list)
26781 A list of hostnames or IPs pointing to OpenDHT nodes, that should be
26782 used to initially join the OpenDHT network. When left unspecified, the
26783 value from the account archive prevails.
26785 @item @code{name-server-uri} (type: maybe-string)
26786 The URI of the name server to use, that can be used to retrieve the
26787 account fingerprint for a registered username.
26793 @subsubheading Mumble server
26797 @cindex VoIP server
26798 This section describes how to set up and run a
26799 @uref{https://mumble.info, Mumble} server (formerly known as Murmur).
26801 @deftp {Data Type} mumble-server-configuration
26802 The service type for the Mumble server. An example configuration can
26806 (service mumble-server-service-type
26807 (mumble-server-configuration
26809 "Welcome to this Mumble server running on Guix!")
26810 (cert-required? #t) ;disallow text password logins
26811 (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
26812 (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
26815 After reconfiguring your system, you can manually set the mumble-server
26817 password with the command that is printed during the activation phase.
26819 It is recommended to register a normal Mumble user account
26820 and grant it admin or moderator rights.
26821 You can use the @code{mumble} client to
26822 login as new normal user, register yourself, and log out.
26823 For the next step login with the name @code{SuperUser} use
26824 the @code{SuperUser} password that you set previously,
26825 and grant your newly registered mumble user administrator or moderator
26826 rights and create some channels.
26828 Available @code{mumble-server-configuration} fields are:
26831 @item @code{package} (default: @code{mumble})
26832 Package that contains @code{bin/mumble-server}.
26834 @item @code{user} (default: @code{"mumble-server"})
26835 User who will run the Mumble-Server server.
26837 @item @code{group} (default: @code{"mumble-server"})
26838 Group of the user who will run the mumble-server server.
26840 @item @code{port} (default: @code{64738})
26841 Port on which the server will listen.
26843 @item @code{welcome-text} (default: @code{""})
26844 Welcome text sent to clients when they connect.
26846 @item @code{server-password} (default: @code{""})
26847 Password the clients have to enter in order to connect.
26849 @item @code{max-users} (default: @code{100})
26850 Maximum of users that can be connected to the server at once.
26852 @item @code{max-user-bandwidth} (default: @code{#f})
26853 Maximum voice traffic a user can send per second.
26855 @item @code{database-file} (default: @code{"/var/lib/mumble-server/db.sqlite"})
26856 File name of the sqlite database.
26857 The service's user will become the owner of the directory.
26859 @item @code{log-file} (default: @code{"/var/log/mumble-server/mumble-server.log"})
26860 File name of the log file.
26861 The service's user will become the owner of the directory.
26863 @item @code{autoban-attempts} (default: @code{10})
26864 Maximum number of logins a user can make in @code{autoban-timeframe}
26865 without getting auto banned for @code{autoban-time}.
26867 @item @code{autoban-timeframe} (default: @code{120})
26868 Timeframe for autoban in seconds.
26870 @item @code{autoban-time} (default: @code{300})
26871 Amount of time in seconds for which a client gets banned
26872 when violating the autoban limits.
26874 @item @code{opus-threshold} (default: @code{100})
26875 Percentage of clients that need to support opus
26876 before switching over to opus audio codec.
26878 @item @code{channel-nesting-limit} (default: @code{10})
26879 How deep channels can be nested at maximum.
26881 @item @code{channelname-regex} (default: @code{#f})
26882 A string in form of a Qt regular expression that channel names must conform to.
26884 @item @code{username-regex} (default: @code{#f})
26885 A string in form of a Qt regular expression that user names must conform to.
26887 @item @code{text-message-length} (default: @code{5000})
26888 Maximum size in bytes that a user can send in one text chat message.
26890 @item @code{image-message-length} (default: @code{(* 128 1024)})
26891 Maximum size in bytes that a user can send in one image message.
26893 @item @code{cert-required?} (default: @code{#f})
26894 If it is set to @code{#t} clients that use weak password authentication
26895 will not be accepted. Users must have completed the certificate wizard to join.
26897 @item @code{remember-channel?} (default: @code{#f})
26898 Should mumble-server remember the last channel each user was in when
26899 they disconnected and put them into the remembered channel when they
26902 @item @code{allow-html?} (default: @code{#f})
26903 Should html be allowed in text messages, user comments, and channel descriptions.
26905 @item @code{allow-ping?} (default: @code{#f})
26906 Setting to true exposes the current user count, the maximum user count, and
26907 the server's maximum bandwidth per client to unauthenticated users. In the
26908 Mumble client, this information is shown in the Connect dialog.
26910 Disabling this setting will prevent public listing of the server.
26912 @item @code{bonjour?} (default: @code{#f})
26913 Should the server advertise itself in the local network through the bonjour protocol.
26915 @item @code{send-version?} (default: @code{#f})
26916 Should the mumble-server server version be exposed in ping requests.
26918 @item @code{log-days} (default: @code{31})
26919 Mumble also stores logs in the database, which are accessible via RPC.
26920 The default is 31 days of months, but you can set this setting to 0 to keep logs forever,
26921 or -1 to disable logging to the database.
26923 @item @code{obfuscate-ips?} (default: @code{#t})
26924 Should logged ips be obfuscated to protect the privacy of users.
26926 @item @code{ssl-cert} (default: @code{#f})
26927 File name of the SSL/TLS certificate used for encrypted connections.
26930 (ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")
26932 @item @code{ssl-key} (default: @code{#f})
26933 Filepath to the ssl private key used for encrypted connections.
26935 (ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")
26938 @item @code{ssl-dh-params} (default: @code{#f})
26939 File name of a PEM-encoded file with Diffie-Hellman parameters
26940 for the SSL/TLS encryption. Alternatively you set it to
26941 @code{"@@ffdhe2048"}, @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"}
26942 or @code{"@@ffdhe8192"} to use bundled parameters from RFC 7919.
26944 @item @code{ssl-ciphers} (default: @code{#f})
26945 The @code{ssl-ciphers} option chooses the cipher suites to make available for use
26948 This option is specified using
26949 @uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
26950 OpenSSL cipher list notation}.
26952 It is recommended that you try your cipher string using
26953 'openssl ciphers <string>' before setting it here, to get a feel for
26954 which cipher suites you will get.
26955 After setting this option, it is recommend that you inspect your Mumble
26956 server log to ensure that Mumble is using the cipher suites that you
26960 Changing this option may impact the backwards compatibility of your
26961 Mumble-Server server, and can remove the ability for older Mumble clients to be able to connect to it.
26964 @item @code{public-registration} (default: @code{#f})
26965 Must be a @code{<mumble-server-public-registration-configuration>}
26966 record or @code{#f}.
26968 You can optionally register your server in the public server list that the
26969 @code{mumble} client shows on startup.
26970 You cannot register your server if you have set a @code{server-password},
26971 or set @code{allow-ping} to @code{#f}.
26973 It might take a few hours until it shows up in the public list.
26975 @item @code{file} (default: @code{#f})
26976 Optional alternative override for this configuration.
26980 @deftp {Data Type} mumble-server-public-registration-configuration
26981 Configuration for public registration of a mumble-server service.
26985 This is a display name for your server. Not to be confused with the hostname.
26987 @item @code{password}
26988 A password to identify your registration.
26989 Subsequent updates will need the same password. Don't lose your password.
26992 This should be a @code{http://} or @code{https://} link to your web
26995 @item @code{hostname} (default: @code{#f})
26996 By default your server will be listed by its IP address.
26997 If it is set your server will be linked by this host name instead.
27001 @quotation Deprecation notice
27002 Due to historical reasons, all of the above @code{mumble-server-}
27003 procedures are also exported with the @code{murmur-} prefix.
27004 It is recommended that you switch to using @code{mumble-server-}
27008 @node File-Sharing Services
27009 @subsection File-Sharing Services
27011 The @code{(gnu services file-sharing)} module provides services that
27012 assist with transferring files over peer-to-peer file-sharing networks.
27014 @subsubheading Transmission Daemon Service
27016 @uref{https://transmissionbt.com/, Transmission} is a flexible
27017 BitTorrent client that offers a variety of graphical and command-line
27018 interfaces. A @code{transmission-daemon-service-type} service provides
27019 Transmission's headless variant, @command{transmission-daemon}, as a
27020 system service, allowing users to share files via BitTorrent even when
27021 they are not logged in.
27023 @deffn {Scheme Variable} transmission-daemon-service-type
27024 The service type for the Transmission Daemon BitTorrent client. Its
27025 value must be a @code{transmission-daemon-configuration} object as in
27029 (service transmission-daemon-service-type
27030 (transmission-daemon-configuration
27031 ;; Restrict access to the RPC ("control") interface
27032 (rpc-authentication-required? #t)
27033 (rpc-username "transmission")
27035 (transmission-password-hash
27036 "transmission" ; desired password
27037 "uKd1uMs9")) ; arbitrary salt value
27039 ;; Accept requests from this and other hosts on the
27041 (rpc-whitelist-enabled? #t)
27042 (rpc-whitelist '("::1" "127.0.0.1" "192.168.0.*"))
27044 ;; Limit bandwidth use during work hours
27045 (alt-speed-down (* 1024 2)) ; 2 MB/s
27046 (alt-speed-up 512) ; 512 kB/s
27048 (alt-speed-time-enabled? #t)
27049 (alt-speed-time-day 'weekdays)
27050 (alt-speed-time-begin
27051 (+ (* 60 8) 30)) ; 8:30 am
27052 (alt-speed-time-end
27053 (+ (* 60 (+ 12 5)) 30)))) ; 5:30 pm
27057 Once the service is started, users can interact with the daemon through
27058 its Web interface (at @code{http://localhost:9091/}) or by using the
27059 @command{transmission-remote} command-line tool, available in the
27060 @code{transmission} package. (Emacs users may want to also consider the
27061 @code{emacs-transmission} package.) Both communicate with the daemon
27062 through its remote procedure call (RPC) interface, which by default is
27063 available to all users on the system; you may wish to change this by
27064 assigning values to the @code{rpc-authentication-required?},
27065 @code{rpc-username} and @code{rpc-password} settings, as shown in the
27066 example above and documented further below.
27068 The value for @code{rpc-password} must be a password hash of the type
27069 generated and used by Transmission clients. This can be copied verbatim
27070 from an existing @file{settings.json} file, if another Transmission
27071 client is already being used. Otherwise, the
27072 @code{transmission-password-hash} and @code{transmission-random-salt}
27073 procedures provided by this module can be used to obtain a suitable hash
27076 @deffn {Scheme Procedure} transmission-password-hash @var{password} @var{salt}
27077 Returns a string containing the result of hashing @var{password}
27078 together with @var{salt}, in the format recognized by Transmission
27079 clients for their @code{rpc-password} configuration setting.
27081 @var{salt} must be an eight-character string. The
27082 @code{transmission-random-salt} procedure can be used to generate a
27083 suitable salt value at random.
27086 @deffn {Scheme Procedure} transmission-random-salt
27087 Returns a string containing a random, eight-character salt value of the
27088 type generated and used by Transmission clients, suitable for passing to
27089 the @code{transmission-password-hash} procedure.
27092 These procedures are accessible from within a Guile REPL started with
27093 the @command{guix repl} command (@pxref{Invoking guix repl}). This is
27094 useful for obtaining a random salt value to provide as the second
27095 parameter to `transmission-password-hash`, as in this example session:
27099 scheme@@(guix-user)> ,use (gnu services file-sharing)
27100 scheme@@(guix-user)> (transmission-random-salt)
27104 Alternatively, a complete password hash can generated in a single step:
27107 scheme@@(guix-user)> (transmission-password-hash "transmission"
27108 (transmission-random-salt))
27109 $2 = "@{c8bbc6d1740cd8dc819a6e25563b67812c1c19c9VtFPfdsX"
27112 The resulting string can be used as-is for the value of
27113 @code{rpc-password}, allowing the password to be kept hidden even in the
27114 operating-system configuration.
27116 Torrent files downloaded by the daemon are directly accessible only to
27117 users in the ``transmission'' user group, who receive read-only access
27118 to the directory specified by the @code{download-dir} configuration
27119 setting (and also the directory specified by @code{incomplete-dir}, if
27120 @code{incomplete-dir-enabled?} is @code{#t}). Downloaded files can be
27121 moved to another directory or deleted altogether using
27122 @command{transmission-remote} with its @code{--move} and
27123 @code{--remove-and-delete} options.
27125 If the @code{watch-dir-enabled?} setting is set to @code{#t}, users in
27126 the ``transmission'' group are able also to place @file{.torrent} files
27127 in the directory specified by @code{watch-dir} to have the corresponding
27128 torrents added by the daemon. (The @code{trash-original-torrent-files?}
27129 setting controls whether the daemon deletes these files after processing
27132 Some of the daemon's configuration settings can be changed temporarily
27133 by @command{transmission-remote} and similar tools. To undo these
27134 changes, use the service's @code{reload} action to have the daemon
27135 reload its settings from disk:
27138 # herd reload transmission-daemon
27141 The full set of available configuration settings is defined by the
27142 @code{transmission-daemon-configuration} data type.
27144 @deftp {Data Type} transmission-daemon-configuration
27145 The data type representing configuration settings for Transmission
27146 Daemon. These correspond directly to the settings recognized by
27147 Transmission clients in their @file{settings.json} file.
27150 @c The following documentation was initially generated by
27151 @c (generate-transmission-daemon-documentation) in (gnu services
27152 @c file-sharing). Manually maintained documentation is better, so we
27153 @c shouldn't hesitate to edit below as needed. However if the change
27154 @c you want to make to this documentation can be done in an automated
27155 @c way, it's probably easier to change (generate-documentation) than to
27156 @c make it below and have to deal with the churn as Transmission Daemon
27159 @c %start of fragment
27161 Available @code{transmission-daemon-configuration} fields are:
27163 @deftypevr {@code{transmission-daemon-configuration} parameter} package transmission
27164 The Transmission package to use.
27168 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer stop-wait-period
27169 The period, in seconds, to wait when stopping the service for
27170 @command{transmission-daemon} to exit before killing its process. This
27171 allows the daemon time to complete its housekeeping and send a final
27172 update to trackers as it shuts down. On slow hosts, or hosts with a
27173 slow network connection, this value may need to be increased.
27175 Defaults to @samp{10}.
27179 @deftypevr {@code{transmission-daemon-configuration} parameter} string download-dir
27180 The directory to which torrent files are downloaded.
27182 Defaults to @samp{"/var/lib/transmission-daemon/downloads"}.
27186 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean incomplete-dir-enabled?
27187 If @code{#t}, files will be held in @code{incomplete-dir} while their
27188 torrent is being downloaded, then moved to @code{download-dir} once the
27189 torrent is complete. Otherwise, files for all torrents (including those
27190 still being downloaded) will be placed in @code{download-dir}.
27192 Defaults to @samp{#f}.
27196 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string incomplete-dir
27197 The directory in which files from incompletely downloaded torrents will
27198 be held when @code{incomplete-dir-enabled?} is @code{#t}.
27200 Defaults to @samp{disabled}.
27204 @deftypevr {@code{transmission-daemon-configuration} parameter} umask umask
27205 The file mode creation mask used for downloaded files. (See the
27206 @command{umask} man page for more information.)
27208 Defaults to @samp{18}.
27212 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rename-partial-files?
27213 When @code{#t}, ``.part'' is appended to the name of partially
27216 Defaults to @samp{#t}.
27220 @deftypevr {@code{transmission-daemon-configuration} parameter} preallocation-mode preallocation
27221 The mode by which space should be preallocated for downloaded files, one
27222 of @code{none}, @code{fast} (or @code{sparse}) and @code{full}.
27223 Specifying @code{full} will minimize disk fragmentation at a cost to
27224 file-creation speed.
27226 Defaults to @samp{fast}.
27230 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean watch-dir-enabled?
27231 If @code{#t}, the directory specified by @code{watch-dir} will be
27232 watched for new @file{.torrent} files and the torrents they describe
27233 added automatically (and the original files removed, if
27234 @code{trash-original-torrent-files?} is @code{#t}).
27236 Defaults to @samp{#f}.
27240 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string watch-dir
27241 The directory to be watched for @file{.torrent} files indicating new
27242 torrents to be added, when @code{watch-dir-enabled} is @code{#t}.
27244 Defaults to @samp{disabled}.
27248 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean trash-original-torrent-files?
27249 When @code{#t}, @file{.torrent} files will be deleted from the watch
27250 directory once their torrent has been added (see
27251 @code{watch-directory-enabled?}).
27253 Defaults to @samp{#f}.
27257 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-down-enabled?
27258 When @code{#t}, the daemon's download speed will be limited to the rate
27259 specified by @code{speed-limit-down}.
27261 Defaults to @samp{#f}.
27265 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-down
27266 The default global-maximum download speed, in kilobytes per second.
27268 Defaults to @samp{100}.
27272 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean speed-limit-up-enabled?
27273 When @code{#t}, the daemon's upload speed will be limited to the rate
27274 specified by @code{speed-limit-up}.
27276 Defaults to @samp{#f}.
27280 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer speed-limit-up
27281 The default global-maximum upload speed, in kilobytes per second.
27283 Defaults to @samp{100}.
27287 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-enabled?
27288 When @code{#t}, the alternate speed limits @code{alt-speed-down} and
27289 @code{alt-speed-up} are used (in place of @code{speed-limit-down} and
27290 @code{speed-limit-up}, if they are enabled) to constrain the daemon's
27291 bandwidth usage. This can be scheduled to occur automatically at
27292 certain times during the week; see @code{alt-speed-time-enabled?}.
27294 Defaults to @samp{#f}.
27298 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-down
27299 The alternate global-maximum download speed, in kilobytes per second.
27301 Defaults to @samp{50}.
27305 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-up
27306 The alternate global-maximum upload speed, in kilobytes per second.
27308 Defaults to @samp{50}.
27312 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean alt-speed-time-enabled?
27313 When @code{#t}, the alternate speed limits @code{alt-speed-down} and
27314 @code{alt-speed-up} will be enabled automatically during the periods
27315 specified by @code{alt-speed-time-day}, @code{alt-speed-time-begin} and
27316 @code{alt-time-speed-end}.
27318 Defaults to @samp{#f}.
27322 @deftypevr {@code{transmission-daemon-configuration} parameter} day-list alt-speed-time-day
27323 The days of the week on which the alternate-speed schedule should be
27324 used, specified either as a list of days (@code{sunday}, @code{monday},
27325 and so on) or using one of the symbols @code{weekdays}, @code{weekends}
27328 Defaults to @samp{all}.
27332 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-begin
27333 The time of day at which to enable the alternate speed limits, expressed
27334 as a number of minutes since midnight.
27336 Defaults to @samp{540}.
27340 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer alt-speed-time-end
27341 The time of day at which to disable the alternate speed limits,
27342 expressed as a number of minutes since midnight.
27344 Defaults to @samp{1020}.
27348 @deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv4
27349 The IP address at which to listen for peer connections, or ``0.0.0.0''
27350 to listen at all available IP addresses.
27352 Defaults to @samp{"0.0.0.0"}.
27356 @deftypevr {@code{transmission-daemon-configuration} parameter} string bind-address-ipv6
27357 The IPv6 address at which to listen for peer connections, or ``::'' to
27358 listen at all available IPv6 addresses.
27360 Defaults to @samp{"::"}.
27364 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean peer-port-random-on-start?
27365 If @code{#t}, when the daemon starts it will select a port at random on
27366 which to listen for peer connections, from the range specified
27367 (inclusively) by @code{peer-port-random-low} and
27368 @code{peer-port-random-high}. Otherwise, it listens on the port
27369 specified by @code{peer-port}.
27371 Defaults to @samp{#f}.
27375 @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-low
27376 The lowest selectable port number when @code{peer-port-random-on-start?}
27379 Defaults to @samp{49152}.
27383 @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port-random-high
27384 The highest selectable port number when @code{peer-port-random-on-start}
27387 Defaults to @samp{65535}.
27391 @deftypevr {@code{transmission-daemon-configuration} parameter} port-number peer-port
27392 The port on which to listen for peer connections when
27393 @code{peer-port-random-on-start?} is @code{#f}.
27395 Defaults to @samp{51413}.
27399 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean port-forwarding-enabled?
27400 If @code{#t}, the daemon will attempt to configure port-forwarding on an
27401 upstream gateway automatically using @acronym{UPnP} and
27404 Defaults to @samp{#t}.
27408 @deftypevr {@code{transmission-daemon-configuration} parameter} encryption-mode encryption
27409 The encryption preference for peer connections, one of
27410 @code{prefer-unencrypted-connections},
27411 @code{prefer-encrypted-connections} or
27412 @code{require-encrypted-connections}.
27414 Defaults to @samp{prefer-encrypted-connections}.
27418 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string peer-congestion-algorithm
27419 The TCP congestion-control algorithm to use for peer connections,
27420 specified using a string recognized by the operating system in calls to
27421 @code{setsockopt}. When left unspecified, the operating-system default
27424 Note that on GNU/Linux systems, the kernel must be configured to allow
27425 processes to use a congestion-control algorithm not in the default set;
27426 otherwise, it will deny these requests with ``Operation not permitted''.
27427 To see which algorithms are available on your system and which are
27428 currently permitted for use, look at the contents of the files
27429 @file{tcp_available_congestion_control} and
27430 @file{tcp_allowed_congestion_control} in the @file{/proc/sys/net/ipv4}
27433 As an example, to have Transmission Daemon use
27434 @uref{http://www-ece.rice.edu/networks/TCP-LP/,the TCP Low Priority
27435 congestion-control algorithm}, you'll need to modify your kernel
27436 configuration to build in support for the algorithm, then update your
27437 operating-system configuration to allow its use by adding a
27438 @code{sysctl-service-type} service (or updating the existing one's
27439 configuration) with lines like the following:
27442 (service sysctl-service-type
27443 (sysctl-configuration
27445 ("net.ipv4.tcp_allowed_congestion_control" .
27446 "reno cubic lp"))))
27449 The Transmission Daemon configuration can then be updated with
27452 (peer-congestion-algorithm "lp")
27455 and the system reconfigured to have the changes take effect.
27457 Defaults to @samp{disabled}.
27461 @deftypevr {@code{transmission-daemon-configuration} parameter} tcp-type-of-service peer-socket-tos
27462 The type of service to request in outgoing @acronym{TCP} packets, one of
27463 @code{default}, @code{low-cost}, @code{throughput}, @code{low-delay} and
27464 @code{reliability}.
27466 Defaults to @samp{default}.
27470 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-global
27471 The global limit on the number of connected peers.
27473 Defaults to @samp{200}.
27477 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-limit-per-torrent
27478 The per-torrent limit on the number of connected peers.
27480 Defaults to @samp{50}.
27484 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer upload-slots-per-torrent
27485 The maximum number of peers to which the daemon will upload data
27486 simultaneously for each torrent.
27488 Defaults to @samp{14}.
27492 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer peer-id-ttl-hours
27493 The maximum lifespan, in hours, of the peer ID associated with each
27494 public torrent before it is regenerated.
27496 Defaults to @samp{6}.
27500 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean blocklist-enabled?
27501 When @code{#t}, the daemon will ignore peers mentioned in the blocklist
27502 it has most recently downloaded from @code{blocklist-url}.
27504 Defaults to @samp{#f}.
27508 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string blocklist-url
27509 The URL of a peer blocklist (in @acronym{P2P}-plaintext or eMule
27510 @file{.dat} format) to be periodically downloaded and applied when
27511 @code{blocklist-enabled?} is @code{#t}.
27513 Defaults to @samp{disabled}.
27517 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean download-queue-enabled?
27518 If @code{#t}, the daemon will be limited to downloading at most
27519 @code{download-queue-size} non-stalled torrents simultaneously.
27521 Defaults to @samp{#t}.
27525 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer download-queue-size
27526 The size of the daemon's download queue, which limits the number of
27527 non-stalled torrents it will download at any one time when
27528 @code{download-queue-enabled?} is @code{#t}.
27530 Defaults to @samp{5}.
27534 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean seed-queue-enabled?
27535 If @code{#t}, the daemon will be limited to seeding at most
27536 @code{seed-queue-size} non-stalled torrents simultaneously.
27538 Defaults to @samp{#f}.
27542 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer seed-queue-size
27543 The size of the daemon's seed queue, which limits the number of
27544 non-stalled torrents it will seed at any one time when
27545 @code{seed-queue-enabled?} is @code{#t}.
27547 Defaults to @samp{10}.
27551 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean queue-stalled-enabled?
27552 When @code{#t}, the daemon will consider torrents for which it has not
27553 shared data in the past @code{queue-stalled-minutes} minutes to be
27554 stalled and not count them against its @code{download-queue-size} and
27555 @code{seed-queue-size} limits.
27557 Defaults to @samp{#t}.
27561 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer queue-stalled-minutes
27562 The maximum period, in minutes, a torrent may be idle before it is
27563 considered to be stalled, when @code{queue-stalled-enabled?} is
27566 Defaults to @samp{30}.
27570 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean ratio-limit-enabled?
27571 When @code{#t}, a torrent being seeded will automatically be paused once
27572 it reaches the ratio specified by @code{ratio-limit}.
27574 Defaults to @samp{#f}.
27578 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-rational ratio-limit
27579 The ratio at which a torrent being seeded will be paused, when
27580 @code{ratio-limit-enabled?} is @code{#t}.
27582 Defaults to @samp{2.0}.
27586 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean idle-seeding-limit-enabled?
27587 When @code{#t}, a torrent being seeded will automatically be paused once
27588 it has been idle for @code{idle-seeding-limit} minutes.
27590 Defaults to @samp{#f}.
27594 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer idle-seeding-limit
27595 The maximum period, in minutes, a torrent being seeded may be idle
27596 before it is paused, when @code{idle-seeding-limit-enabled?} is
27599 Defaults to @samp{30}.
27603 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean dht-enabled?
27604 Enable @uref{http://bittorrent.org/beps/bep_0005.html,the distributed
27605 hash table (@acronym{DHT}) protocol}, which supports the use of
27606 trackerless torrents.
27608 Defaults to @samp{#t}.
27612 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean lpd-enabled?
27613 Enable @uref{https://en.wikipedia.org/wiki/Local_Peer_Discovery,local
27614 peer discovery} (@acronym{LPD}), which allows the discovery of peers on
27615 the local network and may reduce the amount of data sent over the public
27618 Defaults to @samp{#f}.
27622 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean pex-enabled?
27623 Enable @uref{https://en.wikipedia.org/wiki/Peer_exchange,peer exchange}
27624 (@acronym{PEX}), which reduces the daemon's reliance on external
27625 trackers and may improve its performance.
27627 Defaults to @samp{#t}.
27631 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean utp-enabled?
27632 Enable @uref{http://bittorrent.org/beps/bep_0029.html,the micro
27633 transport protocol} (@acronym{uTP}), which aims to reduce the impact of
27634 BitTorrent traffic on other users of the local network while maintaining
27635 full utilization of the available bandwidth.
27637 Defaults to @samp{#t}.
27641 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-enabled?
27642 If @code{#t}, enable the remote procedure call (@acronym{RPC})
27643 interface, which allows remote control of the daemon via its Web
27644 interface, the @command{transmission-remote} command-line client, and
27647 Defaults to @samp{#t}.
27651 @deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-bind-address
27652 The IP address at which to listen for @acronym{RPC} connections, or
27653 ``0.0.0.0'' to listen at all available IP addresses.
27655 Defaults to @samp{"0.0.0.0"}.
27659 @deftypevr {@code{transmission-daemon-configuration} parameter} port-number rpc-port
27660 The port on which to listen for @acronym{RPC} connections.
27662 Defaults to @samp{9091}.
27666 @deftypevr {@code{transmission-daemon-configuration} parameter} string rpc-url
27667 The path prefix to use in the @acronym{RPC}-endpoint @acronym{URL}.
27669 Defaults to @samp{"/transmission/"}.
27673 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-authentication-required?
27674 When @code{#t}, clients must authenticate (see @code{rpc-username} and
27675 @code{rpc-password}) when using the @acronym{RPC} interface. Note this
27676 has the side effect of disabling host-name whitelisting (see
27677 @code{rpc-host-whitelist-enabled?}.
27679 Defaults to @samp{#f}.
27683 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-string rpc-username
27684 The username required by clients to access the @acronym{RPC} interface
27685 when @code{rpc-authentication-required?} is @code{#t}.
27687 Defaults to @samp{disabled}.
27691 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-transmission-password-hash rpc-password
27692 The password required by clients to access the @acronym{RPC} interface
27693 when @code{rpc-authentication-required?} is @code{#t}. This must be
27694 specified using a password hash in the format recognized by Transmission
27695 clients, either copied from an existing @file{settings.json} file or
27696 generated using the @code{transmission-password-hash} procedure.
27698 Defaults to @samp{disabled}.
27702 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-whitelist-enabled?
27703 When @code{#t}, @acronym{RPC} requests will be accepted only when they
27704 originate from an address specified in @code{rpc-whitelist}.
27706 Defaults to @samp{#t}.
27710 @deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-whitelist
27711 The list of IP and IPv6 addresses from which @acronym{RPC} requests will
27712 be accepted when @code{rpc-whitelist-enabled?} is @code{#t}. Wildcards
27713 may be specified using @samp{*}.
27715 Defaults to @samp{("127.0.0.1" "::1")}.
27719 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean rpc-host-whitelist-enabled?
27720 When @code{#t}, @acronym{RPC} requests will be accepted only when they
27721 are addressed to a host named in @code{rpc-host-whitelist}. Note that
27722 requests to ``localhost'' or ``localhost.'', or to a numeric address,
27723 are always accepted regardless of these settings.
27725 Note also this functionality is disabled when
27726 @code{rpc-authentication-required?} is @code{#t}.
27728 Defaults to @samp{#t}.
27732 @deftypevr {@code{transmission-daemon-configuration} parameter} string-list rpc-host-whitelist
27733 The list of host names recognized by the @acronym{RPC} server when
27734 @code{rpc-host-whitelist-enabled?} is @code{#t}.
27736 Defaults to @samp{()}.
27740 @deftypevr {@code{transmission-daemon-configuration} parameter} message-level message-level
27741 The minimum severity level of messages to be logged (to
27742 @file{/var/log/transmission.log}) by the daemon, one of @code{none} (no
27743 logging), @code{error}, @code{info} and @code{debug}.
27745 Defaults to @samp{info}.
27749 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean start-added-torrents?
27750 When @code{#t}, torrents are started as soon as they are added;
27751 otherwise, they are added in ``paused'' state.
27753 Defaults to @samp{#t}.
27757 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean script-torrent-done-enabled?
27758 When @code{#t}, the script specified by
27759 @code{script-torrent-done-filename} will be invoked each time a torrent
27762 Defaults to @samp{#f}.
27766 @deftypevr {@code{transmission-daemon-configuration} parameter} maybe-file-object script-torrent-done-filename
27767 A file name or file-like object specifying a script to run each time a
27768 torrent completes, when @code{script-torrent-done-enabled?} is
27771 Defaults to @samp{disabled}.
27775 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean scrape-paused-torrents-enabled?
27776 When @code{#t}, the daemon will scrape trackers for a torrent even when
27777 the torrent is paused.
27779 Defaults to @samp{#t}.
27783 @deftypevr {@code{transmission-daemon-configuration} parameter} non-negative-integer cache-size-mb
27784 The amount of memory, in megabytes, to allocate for the daemon's
27785 in-memory cache. A larger value may increase performance by reducing
27786 the frequency of disk I/O.
27788 Defaults to @samp{4}.
27792 @deftypevr {@code{transmission-daemon-configuration} parameter} boolean prefetch-enabled?
27793 When @code{#t}, the daemon will try to improve I/O performance by
27794 hinting to the operating system which data is likely to be read next
27795 from disk to satisfy requests from peers.
27797 Defaults to @samp{#t}.
27802 @c %end of fragment
27806 @node Monitoring Services
27807 @subsection Monitoring Services
27809 @subsubheading Tailon Service
27811 @uref{https://tailon.readthedocs.io/, Tailon} is a web application for
27812 viewing and searching log files.
27814 The following example will configure the service with default values.
27815 By default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
27818 (service tailon-service-type)
27821 The following example customises more of the Tailon configuration,
27822 adding @command{sed} to the list of allowed commands.
27825 (service tailon-service-type
27826 (tailon-configuration
27828 (tailon-configuration-file
27829 (allowed-commands '("tail" "grep" "awk" "sed"))))))
27833 @deftp {Data Type} tailon-configuration
27834 Data type representing the configuration of Tailon.
27835 This type has the following parameters:
27838 @item @code{config-file} (default: @code{(tailon-configuration-file)})
27839 The configuration file to use for Tailon. This can be set to a
27840 @dfn{tailon-configuration-file} record value, or any gexp
27841 (@pxref{G-Expressions}).
27843 For example, to instead use a local file, the @code{local-file} function
27847 (service tailon-service-type
27848 (tailon-configuration
27849 (config-file (local-file "./my-tailon.conf"))))
27852 @item @code{package} (default: @code{tailon})
27853 The tailon package to use.
27858 @deftp {Data Type} tailon-configuration-file
27859 Data type representing the configuration options for Tailon.
27860 This type has the following parameters:
27863 @item @code{files} (default: @code{(list "/var/log")})
27864 List of files to display. The list can include strings for a single file
27865 or directory, or a list, where the first item is the name of a
27866 subsection, and the remaining items are the files or directories in that
27869 @item @code{bind} (default: @code{"localhost:8080"})
27870 Address and port to which Tailon should bind on.
27872 @item @code{relative-root} (default: @code{#f})
27873 URL path to use for Tailon, set to @code{#f} to not use a path.
27875 @item @code{allow-transfers?} (default: @code{#t})
27876 Allow downloading the log files in the web interface.
27878 @item @code{follow-names?} (default: @code{#t})
27879 Allow tailing of not-yet existent files.
27881 @item @code{tail-lines} (default: @code{200})
27882 Number of lines to read initially from each file.
27884 @item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
27885 Commands to allow running. By default, @code{sed} is disabled.
27887 @item @code{debug?} (default: @code{#f})
27888 Set @code{debug?} to @code{#t} to show debug messages.
27890 @item @code{wrap-lines} (default: @code{#t})
27891 Initial line wrapping state in the web interface. Set to @code{#t} to
27892 initially wrap lines (the default), or to @code{#f} to initially not
27895 @item @code{http-auth} (default: @code{#f})
27896 HTTP authentication type to use. Set to @code{#f} to disable
27897 authentication (the default). Supported values are @code{"digest"} or
27900 @item @code{users} (default: @code{#f})
27901 If HTTP authentication is enabled (see @code{http-auth}), access will be
27902 restricted to the credentials provided here. To configure users, use a
27903 list of pairs, where the first element of the pair is the username, and
27904 the 2nd element of the pair is the password.
27907 (tailon-configuration-file
27908 (http-auth "basic")
27909 (users '(("user1" . "password1")
27910 ("user2" . "password2"))))
27917 @subsubheading Darkstat Service
27919 Darkstat is a packet sniffer that captures network traffic, calculates
27920 statistics about usage, and serves reports over HTTP.
27922 @defvar {Scheme Variable} darkstat-service-type
27923 This is the service type for the
27924 @uref{https://unix4lyfe.org/darkstat/, darkstat}
27925 service, its value must be a @code{darkstat-configuration} record as in
27929 (service darkstat-service-type
27930 (darkstat-configuration
27931 (interface "eno1")))
27935 @deftp {Data Type} darkstat-configuration
27936 Data type representing the configuration of @command{darkstat}.
27939 @item @code{package} (default: @code{darkstat})
27940 The darkstat package to use.
27942 @item @code{interface}
27943 Capture traffic on the specified network interface.
27945 @item @code{port} (default: @code{"667"})
27946 Bind the web interface to the specified port.
27948 @item @code{bind-address} (default: @code{"127.0.0.1"})
27949 Bind the web interface to the specified address.
27951 @item @code{base} (default: @code{"/"})
27952 Specify the path of the base URL@. This can be useful if
27953 @command{darkstat} is accessed via a reverse proxy.
27958 @anchor{prometheus-node-exporter}
27959 @subsubheading Prometheus Node Exporter Service
27960 @cindex prometheus-node-exporter
27962 The Prometheus ``node exporter'' makes hardware and operating system statistics
27963 provided by the Linux kernel available for the Prometheus monitoring system.
27964 This service should be deployed on all physical nodes and virtual machines,
27965 where monitoring these statistics is desirable.
27967 @defvar {Scheme variable} prometheus-node-exporter-service-type
27968 This is the service type for the
27969 @uref{https://github.com/prometheus/node_exporter/, prometheus-node-exporter}
27970 service, its value must be a @code{prometheus-node-exporter-configuration}.
27973 (service prometheus-node-exporter-service-type)
27977 @deftp {Data Type} prometheus-node-exporter-configuration
27978 Data type representing the configuration of @command{node_exporter}.
27981 @item @code{package} (default: @code{go-github-com-prometheus-node-exporter})
27982 The prometheus-node-exporter package to use.
27984 @item @code{web-listen-address} (default: @code{":9100"})
27985 Bind the web interface to the specified address.
27987 @item @code{textfile-directory} (default: @code{"/var/lib/prometheus/node-exporter"})
27988 This directory can be used to export metrics specific to this machine.
27989 Files containing metrics in the text format, with the filename ending in
27990 @code{.prom} should be placed in this directory.
27992 @item @code{extra-options} (default: @code{'()})
27993 Extra options to pass to the Prometheus node exporter.
27998 @subsubheading Zabbix server
27999 @cindex zabbix zabbix-server
28000 Zabbix is a high performance monitoring system that can collect data from a
28001 variety of sources and provide the results in a web-based interface. Alerting
28002 and reporting is built-in, as well as @dfn{templates} for common operating
28003 system metrics such as network utilization, CPU load, and disk space consumption.
28005 This service provides the central Zabbix monitoring service; you also need
28006 @ref{zabbix-front-end,@code{zabbix-front-end-service-type}} to configure Zabbix
28007 and display results, and optionally @ref{zabbix-agent,
28008 @code{zabbix-agent-service-type}} on machines that should be monitored (other
28009 data sources are supported, such as @ref{prometheus-node-exporter,
28010 Prometheus Node Exporter}).
28012 @defvar {Scheme variable} zabbix-server-service-type
28013 This is the service type for the Zabbix server service. Its value must be a
28014 @code{zabbix-server-configuration} record, shown below.
28017 @c %start of fragment
28019 @deftp {Data Type} zabbix-server-configuration
28020 Available @code{zabbix-server-configuration} fields are:
28023 @item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
28024 The zabbix-server package.
28026 @item @code{user} (default: @code{"zabbix"}) (type: string)
28027 User who will run the Zabbix server.
28029 @item @code{group} (default: @code{"zabbix"}) (type: group)
28030 Group who will run the Zabbix server.
28032 @item @code{db-host} (default: @code{"127.0.0.1"}) (type: string)
28033 Database host name.
28035 @item @code{db-name} (default: @code{"zabbix"}) (type: string)
28038 @item @code{db-user} (default: @code{"zabbix"}) (type: string)
28041 @item @code{db-password} (default: @code{""}) (type: string)
28042 Database password. Please, use @code{include-files} with
28043 @code{DBPassword=SECRET} inside a specified file instead.
28045 @item @code{db-port} (default: @code{5432}) (type: number)
28048 @item @code{log-type} (default: @code{""}) (type: string)
28049 Specifies where log messages are written to:
28053 @item @code{system} - syslog.
28055 @item @code{file} - file specified with @code{log-file} parameter.
28057 @item @code{console} - standard output.
28061 @item @code{log-file} (default: @code{"/var/log/zabbix/server.log"}) (type: string)
28062 Log file name for @code{log-type} @code{file} parameter.
28064 @item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_server.pid"}) (type: string)
28067 @item @code{ssl-ca-location} (default: @code{"/etc/ssl/certs/ca-certificates.crt"}) (type: string)
28068 The location of certificate authority (CA) files for SSL server
28069 certificate verification.
28071 @item @code{ssl-cert-location} (default: @code{"/etc/ssl/certs"}) (type: string)
28072 Location of SSL client certificates.
28074 @item @code{extra-options} (default: @code{""}) (type: extra-options)
28075 Extra options will be appended to Zabbix server configuration file.
28077 @item @code{include-files} (default: @code{()}) (type: include-files)
28078 You may include individual files or all files in a directory in the
28079 configuration file.
28086 @c %end of fragment
28088 @anchor{zabbix-agent}
28089 @subsubheading Zabbix agent
28090 @cindex zabbix zabbix-agent
28092 The Zabbix agent gathers information about the running system for the Zabbix
28093 monitoring server. It has a variety of built-in checks, and can be extended
28095 @uref{https://www.zabbix.com/documentation/current/en/manual/config/items/userparameters,
28096 @dfn{user parameters}}.
28098 @defvar {Scheme variable} zabbix-agent-service-type
28099 This is the service type for the Zabbix agent service. Its value must be a
28100 @code{zabbix-agent-configuration} record, shown below.
28103 @c %start of fragment
28105 @deftp {Data Type} zabbix-agent-configuration
28106 Available @code{zabbix-agent-configuration} fields are:
28109 @item @code{zabbix-agent} (default: @code{zabbix-agentd}) (type: file-like)
28110 The zabbix-agent package.
28112 @item @code{user} (default: @code{"zabbix"}) (type: string)
28113 User who will run the Zabbix agent.
28115 @item @code{group} (default: @code{"zabbix"}) (type: group)
28116 Group who will run the Zabbix agent.
28118 @item @code{hostname} (default: @code{""}) (type: string)
28119 Unique, case sensitive hostname which is required for active checks and
28120 must match hostname as configured on the server.
28122 @item @code{log-type} (default: @code{""}) (type: string)
28123 Specifies where log messages are written to:
28127 @code{system} - syslog.
28129 @item @code{file} - file specified with
28130 @code{log-file} parameter.
28132 @item @code{console} - standard output.
28136 @item @code{log-file} (default: @code{"/var/log/zabbix/agent.log"}) (type: string)
28137 Log file name for @code{log-type} @code{file} parameter.
28139 @item @code{pid-file} (default: @code{"/var/run/zabbix/zabbix_agent.pid"}) (type: string)
28142 @item @code{server} (default: @code{("127.0.0.1")}) (type: list)
28143 List of IP addresses, optionally in CIDR notation, or hostnames of
28144 Zabbix servers and Zabbix proxies. Incoming connections will be
28145 accepted only from the hosts listed here.
28147 @item @code{server-active} (default: @code{("127.0.0.1")}) (type: list)
28148 List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix
28149 proxies for active checks. If port is not specified, default port is
28150 used. If this parameter is not specified, active checks are disabled.
28152 @item @code{extra-options} (default: @code{""}) (type: extra-options)
28153 Extra options will be appended to Zabbix server configuration file.
28155 @item @code{include-files} (default: @code{()}) (type: include-files)
28156 You may include individual files or all files in a directory in the
28157 configuration file.
28164 @c %end of fragment
28166 @anchor{zabbix-front-end}
28167 @subsubheading Zabbix front-end
28168 @cindex zabbix zabbix-front-end
28170 The Zabbix front-end provides a web interface to Zabbix. It does not need
28171 to run on the same machine as the Zabbix server. This service works by
28172 extending the @ref{PHP-FPM} and @ref{NGINX} services with the configuration
28173 necessary for loading the Zabbix user interface.
28175 @defvar {Scheme variable} zabbix-front-end-service-type
28176 This is the service type for the Zabbix web frontend. Its value must be a
28177 @code{zabbix-front-end-configuration} record, shown below.
28180 @c %start of fragment
28182 @deftp {Data Type} zabbix-front-end-configuration
28183 Available @code{zabbix-front-end-configuration} fields are:
28186 @item @code{zabbix-server} (default: @code{zabbix-server}) (type: file-like)
28187 The Zabbix server package to use.
28189 @item @code{nginx} (default: @code{()}) (type: list)
28190 List of @ref{nginx-server-configuration,@code{nginx-server-configuration}}
28191 blocks for the Zabbix front-end. When empty, a default that listens on
28194 @item @code{db-host} (default: @code{"localhost"}) (type: string)
28195 Database host name.
28197 @item @code{db-port} (default: @code{5432}) (type: number)
28200 @item @code{db-name} (default: @code{"zabbix"}) (type: string)
28203 @item @code{db-user} (default: @code{"zabbix"}) (type: string)
28206 @item @code{db-password} (default: @code{""}) (type: string)
28207 Database password. Please, use @code{db-secret-file} instead.
28209 @item @code{db-secret-file} (default: @code{""}) (type: string)
28210 Secret file which will be appended to @file{zabbix.conf.php} file. This
28211 file contains credentials for use by Zabbix front-end. You are expected
28212 to create it manually.
28214 @item @code{zabbix-host} (default: @code{"localhost"}) (type: string)
28215 Zabbix server hostname.
28217 @item @code{zabbix-port} (default: @code{10051}) (type: number)
28218 Zabbix server port.
28225 @c %end of fragment
28227 @node Kerberos Services
28228 @subsection Kerberos Services
28231 The @code{(gnu services kerberos)} module provides services relating to
28232 the authentication protocol @dfn{Kerberos}.
28234 @subsubheading Krb5 Service
28236 Programs using a Kerberos client library normally
28237 expect a configuration file in @file{/etc/krb5.conf}.
28238 This service generates such a file from a definition provided in the
28239 operating system declaration.
28240 It does not cause any daemon to be started.
28242 No ``keytab'' files are provided by this service---you must explicitly create them.
28243 This service is known to work with the MIT client library, @code{mit-krb5}.
28244 Other implementations have not been tested.
28246 @defvr {Scheme Variable} krb5-service-type
28247 A service type for Kerberos 5 clients.
28251 Here is an example of its use:
28253 (service krb5-service-type
28254 (krb5-configuration
28255 (default-realm "EXAMPLE.COM")
28256 (allow-weak-crypto? #t)
28259 (name "EXAMPLE.COM")
28260 (admin-server "groucho.example.com")
28261 (kdc "karl.example.com"))
28264 (admin-server "kerb-admin.argrx.edu")
28265 (kdc "keys.argrx.edu"))))))
28269 This example provides a Kerberos@tie{}5 client configuration which:
28271 @item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both
28272 of which have distinct administration servers and key distribution centers;
28273 @item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly
28274 specified by clients;
28275 @item Accepts services which only support encryption types known to be weak.
28278 The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
28279 Only the most commonly used ones are described here.
28280 For a full list, and more detailed explanation of each, see the MIT
28281 @uref{https://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
28285 @deftp {Data Type} krb5-realm
28286 @cindex realm, kerberos
28289 This field is a string identifying the name of the realm.
28290 A common convention is to use the fully qualified DNS name of your organization,
28291 converted to upper case.
28293 @item @code{admin-server}
28294 This field is a string identifying the host where the administration server is
28298 This field is a string identifying the key distribution center
28303 @deftp {Data Type} krb5-configuration
28306 @item @code{allow-weak-crypto?} (default: @code{#f})
28307 If this flag is @code{#t} then services which only offer encryption algorithms
28308 known to be weak will be accepted.
28310 @item @code{default-realm} (default: @code{#f})
28311 This field should be a string identifying the default Kerberos
28312 realm for the client.
28313 You should set this field to the name of your Kerberos realm.
28314 If this value is @code{#f}
28315 then a realm must be specified with every Kerberos principal when invoking programs
28316 such as @command{kinit}.
28318 @item @code{realms}
28319 This should be a non-empty list of @code{krb5-realm} objects, which clients may
28321 Normally, one of them will have a @code{name} field matching the @code{default-realm}
28327 @subsubheading PAM krb5 Service
28330 The @code{pam-krb5} service allows for login authentication and password
28331 management via Kerberos.
28332 You will need this service if you want PAM enabled applications to authenticate
28333 users using Kerberos.
28335 @defvr {Scheme Variable} pam-krb5-service-type
28336 A service type for the Kerberos 5 PAM module.
28339 @deftp {Data Type} pam-krb5-configuration
28340 Data type representing the configuration of the Kerberos 5 PAM module.
28341 This type has the following parameters:
28343 @item @code{pam-krb5} (default: @code{pam-krb5})
28344 The pam-krb5 package to use.
28346 @item @code{minimum-uid} (default: @code{1000})
28347 The smallest user ID for which Kerberos authentications should be attempted.
28348 Local accounts with lower values will silently fail to authenticate.
28353 @node LDAP Services
28354 @subsection LDAP Services
28356 @cindex nslcd, LDAP service
28358 The @code{(gnu services authentication)} module provides the
28359 @code{nslcd-service-type}, which can be used to authenticate against an LDAP
28360 server. In addition to configuring the service itself, you may want to add
28361 @code{ldap} as a name service to the Name Service Switch. @xref{Name Service
28362 Switch} for detailed information.
28364 Here is a simple operating system declaration with a default configuration of
28365 the @code{nslcd-service-type} and a Name Service Switch configuration that
28366 consults the @code{ldap} name service last:
28369 (use-service-modules authentication)
28370 (use-modules (gnu system nss))
28376 (service nslcd-service-type)
28377 (service dhcp-client-service-type)
28379 (name-service-switch
28380 (let ((services (list (name-service (name "db"))
28381 (name-service (name "files"))
28382 (name-service (name "ldap")))))
28383 (name-service-switch
28384 (inherit %mdns-host-lookup-nss)
28385 (password services)
28388 (netgroup services)
28389 (gshadow services)))))
28392 @c %start of generated documentation for nslcd-configuration
28394 Available @code{nslcd-configuration} fields are:
28396 @deftypevr {@code{nslcd-configuration} parameter} package nss-pam-ldapd
28397 The @code{nss-pam-ldapd} package to use.
28401 @deftypevr {@code{nslcd-configuration} parameter} maybe-number threads
28402 The number of threads to start that can handle requests and perform LDAP
28403 queries. Each thread opens a separate connection to the LDAP server.
28404 The default is to start 5 threads.
28406 Defaults to @samp{disabled}.
28410 @deftypevr {@code{nslcd-configuration} parameter} string uid
28411 This specifies the user id with which the daemon should be run.
28413 Defaults to @samp{"nslcd"}.
28417 @deftypevr {@code{nslcd-configuration} parameter} string gid
28418 This specifies the group id with which the daemon should be run.
28420 Defaults to @samp{"nslcd"}.
28424 @deftypevr {@code{nslcd-configuration} parameter} log-option log
28425 This option controls the way logging is done via a list containing
28426 SCHEME and LEVEL@. The SCHEME argument may either be the symbols
28427 @samp{none} or @samp{syslog}, or an absolute file name. The LEVEL
28428 argument is optional and specifies the log level. The log level may be
28429 one of the following symbols: @samp{crit}, @samp{error}, @samp{warning},
28430 @samp{notice}, @samp{info} or @samp{debug}. All messages with the
28431 specified log level or higher are logged.
28433 Defaults to @samp{("/var/log/nslcd" info)}.
28437 @deftypevr {@code{nslcd-configuration} parameter} list uri
28438 The list of LDAP server URIs. Normally, only the first server will be
28439 used with the following servers as fall-back.
28441 Defaults to @samp{("ldap://localhost:389/")}.
28445 @deftypevr {@code{nslcd-configuration} parameter} maybe-string ldap-version
28446 The version of the LDAP protocol to use. The default is to use the
28447 maximum version supported by the LDAP library.
28449 Defaults to @samp{disabled}.
28453 @deftypevr {@code{nslcd-configuration} parameter} maybe-string binddn
28454 Specifies the distinguished name with which to bind to the directory
28455 server for lookups. The default is to bind anonymously.
28457 Defaults to @samp{disabled}.
28461 @deftypevr {@code{nslcd-configuration} parameter} maybe-string bindpw
28462 Specifies the credentials with which to bind. This option is only
28463 applicable when used with binddn.
28465 Defaults to @samp{disabled}.
28469 @deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmoddn
28470 Specifies the distinguished name to use when the root user tries to
28471 modify a user's password using the PAM module.
28473 Defaults to @samp{disabled}.
28477 @deftypevr {@code{nslcd-configuration} parameter} maybe-string rootpwmodpw
28478 Specifies the credentials with which to bind if the root user tries to
28479 change a user's password. This option is only applicable when used with
28482 Defaults to @samp{disabled}.
28486 @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-mech
28487 Specifies the SASL mechanism to be used when performing SASL
28490 Defaults to @samp{disabled}.
28494 @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-realm
28495 Specifies the SASL realm to be used when performing SASL authentication.
28497 Defaults to @samp{disabled}.
28501 @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authcid
28502 Specifies the authentication identity to be used when performing SASL
28505 Defaults to @samp{disabled}.
28509 @deftypevr {@code{nslcd-configuration} parameter} maybe-string sasl-authzid
28510 Specifies the authorization identity to be used when performing SASL
28513 Defaults to @samp{disabled}.
28517 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean sasl-canonicalize?
28518 Determines whether the LDAP server host name should be canonicalised. If
28519 this is enabled the LDAP library will do a reverse host name lookup. By
28520 default, it is left up to the LDAP library whether this check is
28523 Defaults to @samp{disabled}.
28527 @deftypevr {@code{nslcd-configuration} parameter} maybe-string krb5-ccname
28528 Set the name for the GSS-API Kerberos credentials cache.
28530 Defaults to @samp{disabled}.
28534 @deftypevr {@code{nslcd-configuration} parameter} string base
28535 The directory search base.
28537 Defaults to @samp{"dc=example,dc=com"}.
28541 @deftypevr {@code{nslcd-configuration} parameter} scope-option scope
28542 Specifies the search scope (subtree, onelevel, base or children). The
28543 default scope is subtree; base scope is almost never useful for name
28544 service lookups; children scope is not supported on all servers.
28546 Defaults to @samp{(subtree)}.
28550 @deftypevr {@code{nslcd-configuration} parameter} maybe-deref-option deref
28551 Specifies the policy for dereferencing aliases. The default policy is
28552 to never dereference aliases.
28554 Defaults to @samp{disabled}.
28558 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean referrals
28559 Specifies whether automatic referral chasing should be enabled. The
28560 default behaviour is to chase referrals.
28562 Defaults to @samp{disabled}.
28566 @deftypevr {@code{nslcd-configuration} parameter} list-of-map-entries maps
28567 This option allows for custom attributes to be looked up instead of the
28568 default RFC 2307 attributes. It is a list of maps, each consisting of
28569 the name of a map, the RFC 2307 attribute to match and the query
28570 expression for the attribute as it is available in the directory.
28572 Defaults to @samp{()}.
28576 @deftypevr {@code{nslcd-configuration} parameter} list-of-filter-entries filters
28577 A list of filters consisting of the name of a map to which the filter
28578 applies and an LDAP search filter expression.
28580 Defaults to @samp{()}.
28584 @deftypevr {@code{nslcd-configuration} parameter} maybe-number bind-timelimit
28585 Specifies the time limit in seconds to use when connecting to the
28586 directory server. The default value is 10 seconds.
28588 Defaults to @samp{disabled}.
28592 @deftypevr {@code{nslcd-configuration} parameter} maybe-number timelimit
28593 Specifies the time limit (in seconds) to wait for a response from the
28594 LDAP server. A value of zero, which is the default, is to wait
28595 indefinitely for searches to be completed.
28597 Defaults to @samp{disabled}.
28601 @deftypevr {@code{nslcd-configuration} parameter} maybe-number idle-timelimit
28602 Specifies the period if inactivity (in seconds) after which the con‐
28603 nection to the LDAP server will be closed. The default is not to time
28606 Defaults to @samp{disabled}.
28610 @deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-sleeptime
28611 Specifies the number of seconds to sleep when connecting to all LDAP
28612 servers fails. By default one second is waited between the first
28613 failure and the first retry.
28615 Defaults to @samp{disabled}.
28619 @deftypevr {@code{nslcd-configuration} parameter} maybe-number reconnect-retrytime
28620 Specifies the time after which the LDAP server is considered to be
28621 permanently unavailable. Once this time is reached retries will be done
28622 only once per this time period. The default value is 10 seconds.
28624 Defaults to @samp{disabled}.
28628 @deftypevr {@code{nslcd-configuration} parameter} maybe-ssl-option ssl
28629 Specifies whether to use SSL/TLS or not (the default is not to). If
28630 'start-tls is specified then StartTLS is used rather than raw LDAP over
28633 Defaults to @samp{disabled}.
28637 @deftypevr {@code{nslcd-configuration} parameter} maybe-tls-reqcert-option tls-reqcert
28638 Specifies what checks to perform on a server-supplied certificate. The
28639 meaning of the values is described in the ldap.conf(5) manual page.
28641 Defaults to @samp{disabled}.
28645 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertdir
28646 Specifies the directory containing X.509 certificates for peer authen‐
28647 tication. This parameter is ignored when using GnuTLS.
28649 Defaults to @samp{disabled}.
28653 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cacertfile
28654 Specifies the path to the X.509 certificate for peer authentication.
28656 Defaults to @samp{disabled}.
28660 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-randfile
28661 Specifies the path to an entropy source. This parameter is ignored when
28664 Defaults to @samp{disabled}.
28668 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-ciphers
28669 Specifies the ciphers to use for TLS as a string.
28671 Defaults to @samp{disabled}.
28675 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-cert
28676 Specifies the path to the file containing the local certificate for
28677 client TLS authentication.
28679 Defaults to @samp{disabled}.
28683 @deftypevr {@code{nslcd-configuration} parameter} maybe-string tls-key
28684 Specifies the path to the file containing the private key for client TLS
28687 Defaults to @samp{disabled}.
28691 @deftypevr {@code{nslcd-configuration} parameter} maybe-number pagesize
28692 Set this to a number greater than 0 to request paged results from the
28693 LDAP server in accordance with RFC2696. The default (0) is to not
28694 request paged results.
28696 Defaults to @samp{disabled}.
28700 @deftypevr {@code{nslcd-configuration} parameter} maybe-ignore-users-option nss-initgroups-ignoreusers
28701 This option prevents group membership lookups through LDAP for the
28702 specified users. Alternatively, the value 'all-local may be used. With
28703 that value nslcd builds a full list of non-LDAP users on startup.
28705 Defaults to @samp{disabled}.
28709 @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-min-uid
28710 This option ensures that LDAP users with a numeric user id lower than
28711 the specified value are ignored.
28713 Defaults to @samp{disabled}.
28717 @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-uid-offset
28718 This option specifies an offset that is added to all LDAP numeric user
28719 ids. This can be used to avoid user id collisions with local users.
28721 Defaults to @samp{disabled}.
28725 @deftypevr {@code{nslcd-configuration} parameter} maybe-number nss-gid-offset
28726 This option specifies an offset that is added to all LDAP numeric group
28727 ids. This can be used to avoid user id collisions with local groups.
28729 Defaults to @samp{disabled}.
28733 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-nested-groups
28734 If this option is set, the member attribute of a group may point to
28735 another group. Members of nested groups are also returned in the higher
28736 level group and parent groups are returned when finding groups for a
28737 specific user. The default is not to perform extra searches for nested
28740 Defaults to @samp{disabled}.
28744 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-getgrent-skipmembers
28745 If this option is set, the group member list is not retrieved when
28746 looking up groups. Lookups for finding which groups a user belongs to
28747 will remain functional so the user will likely still get the correct
28748 groups assigned on login.
28750 Defaults to @samp{disabled}.
28754 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean nss-disable-enumeration
28755 If this option is set, functions which cause all user/group entries to
28756 be loaded from the directory will not succeed in doing so. This can
28757 dramatically reduce LDAP server load in situations where there are a
28758 great number of users and/or groups. This option is not recommended for
28759 most configurations.
28761 Defaults to @samp{disabled}.
28765 @deftypevr {@code{nslcd-configuration} parameter} maybe-string validnames
28766 This option can be used to specify how user and group names are verified
28767 within the system. This pattern is used to check all user and group
28768 names that are requested and returned from LDAP.
28770 Defaults to @samp{disabled}.
28774 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean ignorecase
28775 This specifies whether or not to perform searches using case-insensitive
28776 matching. Enabling this could open up the system to authorization
28777 bypass vulnerabilities and introduce nscd cache poisoning
28778 vulnerabilities which allow denial of service.
28780 Defaults to @samp{disabled}.
28784 @deftypevr {@code{nslcd-configuration} parameter} maybe-boolean pam-authc-ppolicy
28785 This option specifies whether password policy controls are requested and
28786 handled from the LDAP server when performing user authentication.
28788 Defaults to @samp{disabled}.
28792 @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authc-search
28793 By default nslcd performs an LDAP search with the user's credentials
28794 after BIND (authentication) to ensure that the BIND operation was
28795 successful. The default search is a simple check to see if the user's
28796 DN exists. A search filter can be specified that will be used instead.
28797 It should return at least one entry.
28799 Defaults to @samp{disabled}.
28803 @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-authz-search
28804 This option allows flexible fine tuning of the authorisation check that
28805 should be performed. The search filter specified is executed and if any
28806 entries match, access is granted, otherwise access is denied.
28808 Defaults to @samp{disabled}.
28812 @deftypevr {@code{nslcd-configuration} parameter} maybe-string pam-password-prohibit-message
28813 If this option is set password modification using pam_ldap will be
28814 denied and the specified message will be presented to the user instead.
28815 The message can be used to direct the user to an alternative means of
28816 changing their password.
28818 Defaults to @samp{disabled}.
28822 @deftypevr {@code{nslcd-configuration} parameter} list pam-services
28823 List of pam service names for which LDAP authentication should suffice.
28825 Defaults to @samp{()}.
28829 @c %end of generated documentation for nslcd-configuration
28833 @subsection Web Services
28838 The @code{(gnu services web)} module provides the Apache HTTP Server,
28839 the nginx web server, and also a fastcgi wrapper daemon.
28841 @subsubheading Apache HTTP Server
28843 @deffn {Scheme Variable} httpd-service-type
28844 Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
28845 (@dfn{httpd}). The value for this service type is a
28846 @code{httpd-configuration} record.
28848 A simple example configuration is given below.
28851 (service httpd-service-type
28852 (httpd-configuration
28855 (server-name "www.example.com")
28856 (document-root "/srv/http/www.example.com")))))
28859 Other services can also extend the @code{httpd-service-type} to add to
28863 (simple-service 'www.example.com-server httpd-service-type
28867 (list (string-join '("ServerName www.example.com"
28868 "DocumentRoot /srv/http/www.example.com")
28873 The details for the @code{httpd-configuration}, @code{httpd-module},
28874 @code{httpd-config-file} and @code{httpd-virtualhost} record types are
28877 @deffn {Data Type} httpd-configuration
28878 This data type represents the configuration for the httpd service.
28881 @item @code{package} (default: @code{httpd})
28882 The httpd package to use.
28884 @item @code{pid-file} (default: @code{"/var/run/httpd"})
28885 The pid file used by the shepherd-service.
28887 @item @code{config} (default: @code{(httpd-config-file)})
28888 The configuration file to use with the httpd service. The default value
28889 is a @code{httpd-config-file} record, but this can also be a different
28890 G-expression that generates a file, for example a @code{plain-file}. A
28891 file outside of the store can also be specified through a string.
28896 @deffn {Data Type} httpd-module
28897 This data type represents a module for the httpd service.
28901 The name of the module.
28904 The file for the module. This can be relative to the httpd package being
28905 used, the absolute location of a file, or a G-expression for a file
28906 within the store, for example @code{(file-append mod-wsgi
28907 "/modules/mod_wsgi.so")}.
28912 @defvr {Scheme Variable} %default-httpd-modules
28913 A default list of @code{httpd-module} objects.
28916 @deffn {Data Type} httpd-config-file
28917 This data type represents a configuration file for the httpd service.
28920 @item @code{modules} (default: @code{%default-httpd-modules})
28921 The modules to load. Additional modules can be added here, or loaded by
28922 additional configuration.
28924 For example, in order to handle requests for PHP files, you can use Apache’s
28925 @code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}:
28928 (service httpd-service-type
28929 (httpd-configuration
28934 (name "proxy_module")
28935 (file "modules/mod_proxy.so"))
28937 (name "proxy_fcgi_module")
28938 (file "modules/mod_proxy_fcgi.so"))
28939 %default-httpd-modules))
28940 (extra-config (list "\
28941 <FilesMatch \\.php$>
28942 SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
28943 </FilesMatch>"))))))
28944 (service php-fpm-service-type
28945 (php-fpm-configuration
28946 (socket "/var/run/php-fpm.sock")
28947 (socket-group "httpd")))
28950 @item @code{server-root} (default: @code{httpd})
28951 The @code{ServerRoot} in the configuration file, defaults to the httpd
28952 package. Directives including @code{Include} and @code{LoadModule} are
28953 taken as relative to the server root.
28955 @item @code{server-name} (default: @code{#f})
28956 The @code{ServerName} in the configuration file, used to specify the
28957 request scheme, hostname and port that the server uses to identify
28960 This doesn't need to be set in the server config, and can be specified
28961 in virtual hosts. The default is @code{#f} to not specify a
28964 @item @code{document-root} (default: @code{"/srv/http"})
28965 The @code{DocumentRoot} from which files will be served.
28967 @item @code{listen} (default: @code{'("80")})
28968 The list of values for the @code{Listen} directives in the config
28969 file. The value should be a list of strings, when each string can
28970 specify the port number to listen on, and optionally the IP address and
28973 @item @code{pid-file} (default: @code{"/var/run/httpd"})
28974 The @code{PidFile} to use. This should match the @code{pid-file} set in
28975 the @code{httpd-configuration} so that the Shepherd service is
28976 configured correctly.
28978 @item @code{error-log} (default: @code{"/var/log/httpd/error_log"})
28979 The @code{ErrorLog} to which the server will log errors.
28981 @item @code{user} (default: @code{"httpd"})
28982 The @code{User} which the server will answer requests as.
28984 @item @code{group} (default: @code{"httpd"})
28985 The @code{Group} which the server will answer requests as.
28987 @item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")})
28988 A flat list of strings and G-expressions which will be added to the end
28989 of the configuration file.
28991 Any values which the service is extended with will be appended to this
28997 @deffn {Data Type} httpd-virtualhost
28998 This data type represents a virtualhost configuration block for the httpd service.
29000 These should be added to the extra-config for the httpd-service.
29003 (simple-service 'www.example.com-server httpd-service-type
29007 (list (string-join '("ServerName www.example.com"
29008 "DocumentRoot /srv/http/www.example.com")
29013 @item @code{addresses-and-ports}
29014 The addresses and ports for the @code{VirtualHost} directive.
29016 @item @code{contents}
29017 The contents of the @code{VirtualHost} directive, this should be a list
29018 of strings and G-expressions.
29024 @subsubheading NGINX
29026 @deffn {Scheme Variable} nginx-service-type
29027 Service type for the @uref{https://nginx.org/,NGinx} web server. The
29028 value for this service type is a @code{<nginx-configuration>} record.
29030 A simple example configuration is given below.
29033 (service nginx-service-type
29034 (nginx-configuration
29036 (list (nginx-server-configuration
29037 (server-name '("www.example.com"))
29038 (root "/srv/http/www.example.com"))))))
29041 In addition to adding server blocks to the service configuration
29042 directly, this service can be extended by other services to add server
29043 blocks, as in this example:
29046 (simple-service 'my-extra-server nginx-service-type
29047 (list (nginx-server-configuration
29048 (root "/srv/http/extra-website")
29049 (try-files (list "$uri" "$uri/index.html")))))
29053 At startup, @command{nginx} has not yet read its configuration file, so
29054 it uses a default file to log error messages. If it fails to load its
29055 configuration file, that is where error messages are logged. After the
29056 configuration file is loaded, the default error log file changes as per
29057 configuration. In our case, startup error messages can be found in
29058 @file{/var/run/nginx/logs/error.log}, and after configuration in
29059 @file{/var/log/nginx/error.log}. The second location can be changed
29060 with the @var{log-directory} configuration option.
29062 @deffn {Data Type} nginx-configuration
29063 This data type represents the configuration for NGinx. Some
29064 configuration can be done through this and the other provided record
29065 types, or alternatively, a config file can be provided.
29068 @item @code{nginx} (default: @code{nginx})
29069 The nginx package to use.
29071 @item @code{shepherd-requirement} (default: @code{'()})
29072 This is a list of symbols naming Shepherd services the nginx service
29075 This is useful if you would like @command{nginx} to be started after a
29076 back-end web server or a logging service such as Anonip has been
29079 @item @code{log-directory} (default: @code{"/var/log/nginx"})
29080 The directory to which NGinx will write log files.
29082 @item @code{run-directory} (default: @code{"/var/run/nginx"})
29083 The directory in which NGinx will create a pid file, and write temporary
29086 @item @code{server-blocks} (default: @code{'()})
29087 A list of @dfn{server blocks} to create in the generated configuration
29088 file, the elements should be of type
29089 @code{<nginx-server-configuration>}.
29091 The following example would setup NGinx to serve @code{www.example.com}
29092 from the @code{/srv/http/www.example.com} directory, without using
29095 (service nginx-service-type
29096 (nginx-configuration
29098 (list (nginx-server-configuration
29099 (server-name '("www.example.com"))
29100 (root "/srv/http/www.example.com"))))))
29103 @item @code{upstream-blocks} (default: @code{'()})
29104 A list of @dfn{upstream blocks} to create in the generated configuration
29105 file, the elements should be of type
29106 @code{<nginx-upstream-configuration>}.
29108 Configuring upstreams through the @code{upstream-blocks} can be useful
29109 when combined with @code{locations} in the
29110 @code{<nginx-server-configuration>} records. The following example
29111 creates a server configuration with one location configuration, that
29112 will proxy requests to a upstream configuration, which will handle
29113 requests with two servers.
29118 (nginx-configuration
29120 (list (nginx-server-configuration
29121 (server-name '("www.example.com"))
29122 (root "/srv/http/www.example.com")
29125 (nginx-location-configuration
29127 (body '("proxy_pass http://server-proxy;"))))))))
29129 (list (nginx-upstream-configuration
29130 (name "server-proxy")
29131 (servers (list "server1.example.com"
29132 "server2.example.com")))))))
29135 @item @code{file} (default: @code{#f})
29136 If a configuration @var{file} is provided, this will be used, rather than
29137 generating a configuration file from the provided @code{log-directory},
29138 @code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For
29139 proper operation, these arguments should match what is in @var{file} to ensure
29140 that the directories are created when the service is activated.
29142 This can be useful if you have an existing configuration file, or it's
29143 not possible to do what is required through the other parts of the
29144 nginx-configuration record.
29146 @item @code{server-names-hash-bucket-size} (default: @code{#f})
29147 Bucket size for the server names hash tables, defaults to @code{#f} to
29148 use the size of the processors cache line.
29150 @item @code{server-names-hash-bucket-max-size} (default: @code{#f})
29151 Maximum bucket size for the server names hash tables.
29153 @item @code{modules} (default: @code{'()})
29154 List of nginx dynamic modules to load. This should be a list of file
29155 names of loadable modules, as in this example:
29160 (file-append nginx-accept-language-module "\
29161 /etc/nginx/modules/ngx_http_accept_language_module.so")
29162 (file-append nginx-lua-module "\
29163 /etc/nginx/modules/ngx_http_lua_module.so")))
29166 @item @code{lua-package-path} (default: @code{'()})
29167 List of nginx lua packages to load. This should be a list of package
29168 names of loadable lua modules, as in this example:
29171 (lua-package-path (list lua-resty-core
29178 @item @code{lua-package-cpath} (default: @code{'()})
29179 List of nginx lua C packages to load. This should be a list of package
29180 names of loadable lua C modules, as in this example:
29183 (lua-package-cpath (list lua-resty-signal))
29186 @item @code{global-directives} (default: @code{'((events . ()))})
29187 Association list of global directives for the top level of the nginx
29188 configuration. Values may themselves be association lists.
29192 `((worker_processes . 16)
29194 (events . ((worker_connections . 1024)))))
29197 @item @code{extra-content} (default: @code{""})
29198 Extra content for the @code{http} block. Should be string or a string
29199 valued G-expression.
29204 @anchor{nginx-server-configuration}
29205 @deftp {Data Type} nginx-server-configuration
29206 Data type representing the configuration of an nginx server block.
29207 This type has the following parameters:
29210 @item @code{listen} (default: @code{'("80" "443 ssl")})
29211 Each @code{listen} directive sets the address and port for IP, or the
29212 path for a UNIX-domain socket on which the server will accept requests.
29213 Both address and port, or only address or only port can be specified.
29214 An address may also be a hostname, for example:
29217 '("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")
29220 @item @code{server-name} (default: @code{(list 'default)})
29221 A list of server names this server represents. @code{'default} represents the
29222 default server for connections matching no other server.
29224 @item @code{root} (default: @code{"/srv/http"})
29225 Root of the website nginx will serve.
29227 @item @code{locations} (default: @code{'()})
29228 A list of @dfn{nginx-location-configuration} or
29229 @dfn{nginx-named-location-configuration} records to use within this
29232 @item @code{index} (default: @code{(list "index.html")})
29233 Index files to look for when clients ask for a directory. If it cannot be found,
29234 Nginx will send the list of files in the directory.
29236 @item @code{try-files} (default: @code{'()})
29237 A list of files whose existence is checked in the specified order.
29238 @code{nginx} will use the first file it finds to process the request.
29240 @item @code{ssl-certificate} (default: @code{#f})
29241 Where to find the certificate for secure connections. Set it to @code{#f} if
29242 you don't have a certificate or you don't want to use HTTPS.
29244 @item @code{ssl-certificate-key} (default: @code{#f})
29245 Where to find the private key for secure connections. Set it to @code{#f} if
29246 you don't have a key or you don't want to use HTTPS.
29248 @item @code{server-tokens?} (default: @code{#f})
29249 Whether the server should add its configuration to response.
29251 @item @code{raw-content} (default: @code{'()})
29252 A list of raw lines added to the server block.
29257 @deftp {Data Type} nginx-upstream-configuration
29258 Data type representing the configuration of an nginx @code{upstream}
29259 block. This type has the following parameters:
29263 Name for this group of servers.
29265 @item @code{servers}
29266 Specify the addresses of the servers in the group. The address can be
29267 specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name
29268 (e.g.@: @samp{backend1.example.com}) or a path to a UNIX socket using the
29269 prefix @samp{unix:}. For addresses using an IP address or domain name,
29270 the default port is 80, and a different port can be specified
29273 @item @code{extra-content}
29274 A string or list of strings to add to the upstream block.
29279 @deftp {Data Type} nginx-location-configuration
29280 Data type representing the configuration of an nginx @code{location}
29281 block. This type has the following parameters:
29285 URI which this location block matches.
29287 @anchor{nginx-location-configuration body}
29289 Body of the location block, specified as a list of strings. This can contain
29291 configuration directives. For example, to pass requests to a upstream
29292 server group defined using an @code{nginx-upstream-configuration} block,
29293 the following directive would be specified in the body @samp{(list "proxy_pass
29294 http://upstream-name;")}.
29299 @deftp {Data Type} nginx-named-location-configuration
29300 Data type representing the configuration of an nginx named location
29301 block. Named location blocks are used for request redirection, and not
29302 used for regular request processing. This type has the following
29307 Name to identify this location block.
29310 @xref{nginx-location-configuration body}, as the body for named location
29311 blocks can be used in a similar way to the
29312 @code{nginx-location-configuration body}. One restriction is that the
29313 body of a named location block cannot contain location blocks.
29318 @subsubheading Varnish Cache
29320 Varnish is a fast cache server that sits in between web applications
29321 and end users. It proxies requests from clients and caches the
29322 accessed URLs such that multiple requests for the same resource only
29323 creates one request to the back-end.
29325 @defvr {Scheme Variable} varnish-service-type
29326 Service type for the Varnish daemon.
29329 @deftp {Data Type} varnish-configuration
29330 Data type representing the @code{varnish} service configuration.
29331 This type has the following parameters:
29334 @item @code{package} (default: @code{varnish})
29335 The Varnish package to use.
29337 @item @code{name} (default: @code{"default"})
29338 A name for this Varnish instance. Varnish will create a directory in
29339 @file{/var/varnish/} with this name and keep temporary files there. If
29340 the name starts with a forward slash, it is interpreted as an absolute
29343 Pass the @code{-n} argument to other Varnish programs to connect to the
29344 named instance, e.g.@: @command{varnishncsa -n default}.
29346 @item @code{backend} (default: @code{"localhost:8080"})
29347 The backend to use. This option has no effect if @code{vcl} is set.
29349 @item @code{vcl} (default: #f)
29350 The @dfn{VCL} (Varnish Configuration Language) program to run. If this
29351 is @code{#f}, Varnish will proxy @code{backend} using the default
29352 configuration. Otherwise this must be a file-like object with valid
29355 @c Varnish does not support HTTPS, so keep this URL to avoid confusion.
29356 For example, to mirror @url{https://www.gnu.org,www.gnu.org} with VCL you
29357 can do something along these lines:
29360 (define %gnu-mirror
29361 (plain-file "gnu.vcl"
29363 backend gnu @{ .host = \"www.gnu.org\"; @}"))
29367 (services (cons (service varnish-service-type
29368 (varnish-configuration
29370 (vcl %gnu-mirror)))
29374 The configuration of an already running Varnish instance can be inspected
29375 and changed using the @command{varnishadm} program.
29377 Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and
29378 @url{https://book.varnish-software.com/4.0/,Varnish Book} for
29379 comprehensive documentation on Varnish and its configuration language.
29381 @item @code{listen} (default: @code{'("localhost:80")})
29382 List of addresses Varnish will listen on.
29384 @item @code{storage} (default: @code{'("malloc,128m")})
29385 List of storage backends that will be available in VCL.
29387 @item @code{parameters} (default: @code{'()})
29388 List of run-time parameters in the form @code{'(("parameter" . "value"))}.
29390 @item @code{extra-options} (default: @code{'()})
29391 Additional arguments to pass to the @command{varnishd} process.
29396 @subsubheading Patchwork
29398 Patchwork is a patch tracking system. It can collect patches sent to a
29399 mailing list, and display them in a web interface.
29401 @defvr {Scheme Variable} patchwork-service-type
29402 Service type for Patchwork.
29405 The following example is an example of a minimal service for Patchwork, for
29406 the @code{patchwork.example.com} domain.
29409 (service patchwork-service-type
29410 (patchwork-configuration
29411 (domain "patchwork.example.com")
29413 (patchwork-settings-module
29414 (allowed-hosts (list domain))
29415 (default-from-email "patchwork@@patchwork.example.com")))
29416 (getmail-retriever-config
29417 (getmail-retriever-configuration
29418 (type "SimpleIMAPSSLRetriever")
29419 (server "imap.example.com")
29421 (username "patchwork")
29423 (list (file-append coreutils "/bin/cat")
29424 "/etc/getmail-patchwork-imap-password"))
29426 '((mailboxes . ("Patches"))))))))
29430 There are three records for configuring the Patchwork service. The
29431 @code{<patchwork-configuration>} relates to the configuration for Patchwork
29432 within the HTTPD service.
29434 The @code{settings-module} field within the @code{<patchwork-configuration>}
29435 record can be populated with the @code{<patchwork-settings-module>} record,
29436 which describes a settings module that is generated within the Guix store.
29438 For the @code{database-configuration} field within the
29439 @code{<patchwork-settings-module>}, the
29440 @code{<patchwork-database-configuration>} must be used.
29442 @deftp {Data Type} patchwork-configuration
29443 Data type representing the Patchwork service configuration. This type has the
29444 following parameters:
29447 @item @code{patchwork} (default: @code{patchwork})
29448 The Patchwork package to use.
29450 @item @code{domain}
29451 The domain to use for Patchwork, this is used in the HTTPD service virtual
29454 @item @code{settings-module}
29455 The settings module to use for Patchwork. As a Django application, Patchwork
29456 is configured with a Python module containing the settings. This can either be
29457 an instance of the @code{<patchwork-settings-module>} record, any other record
29458 that represents the settings in the store, or a directory outside of the
29461 @item @code{static-path} (default: @code{"/static/"})
29462 The path under which the HTTPD service should serve the static files.
29464 @item @code{getmail-retriever-config}
29465 The getmail-retriever-configuration record value to use with
29466 Patchwork. Getmail will be configured with this value, the messages will be
29467 delivered to Patchwork.
29472 @deftp {Data Type} patchwork-settings-module
29473 Data type representing a settings module for Patchwork. Some of these
29474 settings relate directly to Patchwork, but others relate to Django, the web
29475 framework used by Patchwork, or the Django Rest Framework library. This type
29476 has the following parameters:
29479 @item @code{database-configuration} (default: @code{(patchwork-database-configuration)})
29480 The database connection settings used for Patchwork. See the
29481 @code{<patchwork-database-configuration>} record type for more information.
29483 @item @code{secret-key-file} (default: @code{"/etc/patchwork/django-secret-key"})
29484 Patchwork, as a Django web application uses a secret key for cryptographically
29485 signing values. This file should contain a unique unpredictable value.
29487 If this file does not exist, it will be created and populated with a random
29488 value by the patchwork-setup shepherd service.
29490 This setting relates to Django.
29492 @item @code{allowed-hosts}
29493 A list of valid hosts for this Patchwork service. This should at least include
29494 the domain specified in the @code{<patchwork-configuration>} record.
29496 This is a Django setting.
29498 @item @code{default-from-email}
29499 The email address from which Patchwork should send email by default.
29501 This is a Patchwork setting.
29503 @item @code{static-url} (default: @code{#f})
29504 The URL to use when serving static assets. It can be part of a URL, or a full
29505 URL, but must end in a @code{/}.
29507 If the default value is used, the @code{static-path} value from the
29508 @code{<patchwork-configuration>} record will be used.
29510 This is a Django setting.
29512 @item @code{admins} (default: @code{'()})
29513 Email addresses to send the details of errors that occur. Each value should
29514 be a list containing two elements, the name and then the email address.
29516 This is a Django setting.
29518 @item @code{debug?} (default: @code{#f})
29519 Whether to run Patchwork in debug mode. If set to @code{#t}, detailed error
29520 messages will be shown.
29522 This is a Django setting.
29524 @item @code{enable-rest-api?} (default: @code{#t})
29525 Whether to enable the Patchwork REST API.
29527 This is a Patchwork setting.
29529 @item @code{enable-xmlrpc?} (default: @code{#t})
29530 Whether to enable the XML RPC API.
29532 This is a Patchwork setting.
29534 @item @code{force-https-links?} (default: @code{#t})
29535 Whether to use HTTPS links on Patchwork pages.
29537 This is a Patchwork setting.
29539 @item @code{extra-settings} (default: @code{""})
29540 Extra code to place at the end of the Patchwork settings module.
29545 @deftp {Data Type} patchwork-database-configuration
29546 Data type representing the database configuration for Patchwork.
29549 @item @code{engine} (default: @code{"django.db.backends.postgresql_psycopg2"})
29550 The database engine to use.
29552 @item @code{name} (default: @code{"patchwork"})
29553 The name of the database to use.
29555 @item @code{user} (default: @code{"httpd"})
29556 The user to connect to the database as.
29558 @item @code{password} (default: @code{""})
29559 The password to use when connecting to the database.
29561 @item @code{host} (default: @code{""})
29562 The host to make the database connection to.
29564 @item @code{port} (default: @code{""})
29565 The port on which to connect to the database.
29570 @subsubheading Mumi
29572 @cindex Mumi, Debbugs Web interface
29573 @cindex Debbugs, Mumi Web interface
29574 @uref{https://git.elephly.net/gitweb.cgi?p=software/mumi.git, Mumi} is a
29575 Web interface to the Debbugs bug tracker, by default for
29576 @uref{https://bugs.gnu.org, the GNU instance}. Mumi is a Web server,
29577 but it also fetches and indexes mail retrieved from Debbugs.
29579 @defvr {Scheme Variable} mumi-service-type
29580 This is the service type for Mumi.
29583 @deftp {Data Type} mumi-configuration
29584 Data type representing the Mumi service configuration. This type has the
29588 @item @code{mumi} (default: @code{mumi})
29589 The Mumi package to use.
29591 @item @code{mailer?} (default: @code{#true})
29592 Whether to enable or disable the mailer component.
29594 @item @code{mumi-configuration-sender}
29595 The email address used as the sender for comments.
29597 @item @code{mumi-configuration-smtp}
29598 A URI to configure the SMTP settings for Mailutils. This could be
29599 something like @code{sendmail:///path/to/bin/msmtp} or any other URI
29600 supported by Mailutils. @xref{SMTP Mailboxes, SMTP Mailboxes,,
29601 mailutils, GNU@tie{}Mailutils}.
29607 @subsubheading FastCGI
29610 FastCGI is an interface between the front-end and the back-end of a web
29611 service. It is a somewhat legacy facility; new web services should
29612 generally just talk HTTP between the front-end and the back-end.
29613 However there are a number of back-end services such as PHP or the
29614 optimized HTTP Git repository access that use FastCGI, so we have
29615 support for it in Guix.
29617 To use FastCGI, you configure the front-end web server (e.g., nginx) to
29618 dispatch some subset of its requests to the fastcgi backend, which
29619 listens on a local TCP or UNIX socket. There is an intermediary
29620 @code{fcgiwrap} program that sits between the actual backend process and
29621 the web server. The front-end indicates which backend program to run,
29622 passing that information to the @code{fcgiwrap} process.
29624 @defvr {Scheme Variable} fcgiwrap-service-type
29625 A service type for the @code{fcgiwrap} FastCGI proxy.
29628 @deftp {Data Type} fcgiwrap-configuration
29629 Data type representing the configuration of the @code{fcgiwrap} service.
29630 This type has the following parameters:
29632 @item @code{package} (default: @code{fcgiwrap})
29633 The fcgiwrap package to use.
29635 @item @code{socket} (default: @code{tcp:127.0.0.1:9000})
29636 The socket on which the @code{fcgiwrap} process should listen, as a
29637 string. Valid @var{socket} values include
29638 @code{unix:@var{/path/to/unix/socket}},
29639 @code{tcp:@var{dot.ted.qu.ad}:@var{port}} and
29640 @code{tcp6:[@var{ipv6_addr}]:port}.
29642 @item @code{user} (default: @code{fcgiwrap})
29643 @itemx @code{group} (default: @code{fcgiwrap})
29644 The user and group names, as strings, under which to run the
29645 @code{fcgiwrap} process. The @code{fastcgi} service will ensure that if
29646 the user asks for the specific user or group names @code{fcgiwrap} that
29647 the corresponding user and/or group is present on the system.
29649 It is possible to configure a FastCGI-backed web service to pass HTTP
29650 authentication information from the front-end to the back-end, and to
29651 allow @code{fcgiwrap} to run the back-end process as a corresponding
29652 local user. To enable this capability on the back-end, run
29653 @code{fcgiwrap} as the @code{root} user and group. Note that this
29654 capability also has to be configured on the front-end as well.
29659 @subsubheading PHP-FPM
29661 PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation
29662 with some additional features useful for sites of any size.
29664 These features include:
29666 @item Adaptive process spawning
29667 @item Basic statistics (similar to Apache's mod_status)
29668 @item Advanced process management with graceful stop/start
29669 @item Ability to start workers with different uid/gid/chroot/environment
29670 and different php.ini (replaces safe_mode)
29671 @item Stdout & stderr logging
29672 @item Emergency restart in case of accidental opcode cache destruction
29673 @item Accelerated upload support
29674 @item Support for a "slowlog"
29675 @item Enhancements to FastCGI, such as fastcgi_finish_request() -
29676 a special function to finish request & flush all data while continuing to do
29677 something time-consuming (video converting, stats processing, etc.)
29679 ...@: and much more.
29681 @defvr {Scheme Variable} php-fpm-service-type
29682 A Service type for @code{php-fpm}.
29685 @deftp {Data Type} php-fpm-configuration
29686 Data Type for php-fpm service configuration.
29688 @item @code{php} (default: @code{php})
29689 The php package to use.
29690 @item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")})
29691 The address on which to accept FastCGI requests. Valid syntaxes are:
29693 @item @code{"ip.add.re.ss:port"}
29694 Listen on a TCP socket to a specific address on a specific port.
29695 @item @code{"port"}
29696 Listen on a TCP socket to all addresses on a specific port.
29697 @item @code{"/path/to/unix/socket"}
29698 Listen on a unix socket.
29701 @item @code{user} (default: @code{php-fpm})
29702 User who will own the php worker processes.
29703 @item @code{group} (default: @code{php-fpm})
29704 Group of the worker processes.
29705 @item @code{socket-user} (default: @code{php-fpm})
29706 User who can speak to the php-fpm socket.
29707 @item @code{socket-group} (default: @code{nginx})
29708 Group that can speak to the php-fpm socket.
29709 @item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
29710 The process id of the php-fpm process is written to this file
29711 once the service has started.
29712 @item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")})
29713 Log for the php-fpm master process.
29714 @item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
29715 Detailed settings for the php-fpm process manager.
29718 @item @code{<php-fpm-dynamic-process-manager-configuration>}
29719 @item @code{<php-fpm-static-process-manager-configuration>}
29720 @item @code{<php-fpm-on-demand-process-manager-configuration>}
29722 @item @code{display-errors} (default @code{#f})
29723 Determines whether php errors and warning should be sent to clients
29724 and displayed in their browsers.
29725 This is useful for local php development, but a security risk for public sites,
29726 as error messages can reveal passwords and personal data.
29727 @item @code{timezone} (default @code{#f})
29728 Specifies @code{php_admin_value[date.timezone]} parameter.
29729 @item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")})
29730 This file will log the @code{stderr} outputs of php worker processes.
29731 Can be set to @code{#f} to disable logging.
29732 @item @code{file} (default @code{#f})
29733 An optional override of the whole configuration.
29734 You can use the @code{mixed-text-file} function or an absolute filepath for it.
29735 @item @code{php-ini-file} (default @code{#f})
29736 An optional override of the default php settings.
29737 It may be any ``file-like'' object (@pxref{G-Expressions, file-like objects}).
29738 You can use the @code{mixed-text-file} function or an absolute filepath for it.
29740 For local development it is useful to set a higher timeout and memory
29741 limit for spawned php processes. This be accomplished with the
29742 following operating system configuration snippet:
29744 (define %local-php-ini
29745 (plain-file "php.ini"
29747 max_execution_time = 1800"))
29751 (services (cons (service php-fpm-service-type
29752 (php-fpm-configuration
29753 (php-ini-file %local-php-ini)))
29757 Consult the @url{https://www.php.net/manual/en/ini.core.php,core php.ini
29758 directives} for comprehensive documentation on the acceptable
29759 @file{php.ini} directives.
29763 @deftp {Data type} php-fpm-dynamic-process-manager-configuration
29764 Data Type for the @code{dynamic} php-fpm process manager. With the
29765 @code{dynamic} process manager, spare worker processes are kept around
29766 based on its configured limits.
29768 @item @code{max-children} (default: @code{5})
29769 Maximum of worker processes.
29770 @item @code{start-servers} (default: @code{2})
29771 How many worker processes should be started on start-up.
29772 @item @code{min-spare-servers} (default: @code{1})
29773 How many spare worker processes should be kept around at minimum.
29774 @item @code{max-spare-servers} (default: @code{3})
29775 How many spare worker processes should be kept around at maximum.
29779 @deftp {Data type} php-fpm-static-process-manager-configuration
29780 Data Type for the @code{static} php-fpm process manager. With the
29781 @code{static} process manager, an unchanging number of worker processes
29784 @item @code{max-children} (default: @code{5})
29785 Maximum of worker processes.
29789 @deftp {Data type} php-fpm-on-demand-process-manager-configuration
29790 Data Type for the @code{on-demand} php-fpm process manager. With the
29791 @code{on-demand} process manager, worker processes are only created as
29794 @item @code{max-children} (default: @code{5})
29795 Maximum of worker processes.
29796 @item @code{process-idle-timeout} (default: @code{10})
29797 The time in seconds after which a process with no requests is killed.
29802 @deffn {Scheme Procedure} nginx-php-location @
29803 [#:nginx-package nginx] @
29804 [socket (string-append "/var/run/php" @
29805 (version-major (package-version php)) @
29807 A helper function to quickly add php to an @code{nginx-server-configuration}.
29810 A simple services setup for nginx with php can look like this:
29812 (services (cons* (service dhcp-client-service-type)
29813 (service php-fpm-service-type)
29814 (service nginx-service-type
29815 (nginx-server-configuration
29816 (server-name '("example.com"))
29817 (root "/srv/http/")
29819 (list (nginx-php-location)))
29821 (ssl-certificate #f)
29822 (ssl-certificate-key #f)))
29826 @cindex cat-avatar-generator
29827 The cat avatar generator is a simple service to demonstrate the use of php-fpm
29828 in @code{Nginx}. It is used to generate cat avatar from a seed, for instance
29829 the hash of a user's email address.
29831 @deffn {Scheme Procedure} cat-avatar-generator-service @
29832 [#:cache-dir "/var/cache/cat-avatar-generator"] @
29833 [#:package cat-avatar-generator] @
29834 [#:configuration (nginx-server-configuration)]
29835 Returns an nginx-server-configuration that inherits @code{configuration}. It
29836 extends the nginx configuration to add a server block that serves @code{package},
29837 a version of cat-avatar-generator. During execution, cat-avatar-generator will
29838 be able to use @code{cache-dir} as its cache directory.
29841 A simple setup for cat-avatar-generator can look like this:
29843 (services (cons* (cat-avatar-generator-service
29845 (nginx-server-configuration
29846 (server-name '("example.com"))))
29851 @subsubheading Hpcguix-web
29853 @cindex hpcguix-web
29854 The @uref{https://github.com/UMCUGenetics/hpcguix-web/, hpcguix-web}
29855 program is a customizable web interface to browse Guix packages,
29856 initially designed for users of high-performance computing (HPC)
29859 @defvr {Scheme Variable} hpcguix-web-service-type
29860 The service type for @code{hpcguix-web}.
29863 @deftp {Data Type} hpcguix-web-configuration
29864 Data type for the hpcguix-web service configuration.
29868 A gexp (@pxref{G-Expressions}) specifying the hpcguix-web service
29869 configuration. The main items available in this spec are:
29872 @item @code{title-prefix} (default: @code{"hpcguix | "})
29873 The page title prefix.
29875 @item @code{guix-command} (default: @code{"guix"})
29876 The @command{guix} command.
29878 @item @code{package-filter-proc} (default: @code{(const #t)})
29879 A procedure specifying how to filter packages that are displayed.
29881 @item @code{package-page-extension-proc} (default: @code{(const '())})
29882 Extension package for @code{hpcguix-web}.
29884 @item @code{menu} (default: @code{'()})
29885 Additional entry in page @code{menu}.
29887 @item @code{channels} (default: @code{%default-channels})
29888 List of channels from which the package list is built (@pxref{Channels}).
29890 @item @code{package-list-expiration} (default: @code{(* 12 3600)})
29891 The expiration time, in seconds, after which the package list is rebuilt from
29892 the latest instances of the given channels.
29895 See the hpcguix-web repository for a
29896 @uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
29899 @item @code{package} (default: @code{hpcguix-web})
29900 The hpcguix-web package to use.
29902 @item @code{address} (default: @code{"127.0.0.1"})
29903 The IP address to listen to.
29905 @item @code{port} (default: @code{5000})
29906 The port number to listen to.
29910 A typical hpcguix-web service declaration looks like this:
29913 (service hpcguix-web-service-type
29914 (hpcguix-web-configuration
29916 #~(define site-config
29917 (hpcweb-configuration
29918 (title-prefix "Guix-HPC - ")
29919 (menu '(("/about" "ABOUT"))))))))
29923 The hpcguix-web service periodically updates the package list it publishes by
29924 pulling channels from Git. To that end, it needs to access X.509 certificates
29925 so that it can authenticate Git servers when communicating over HTTPS, and it
29926 assumes that @file{/etc/ssl/certs} contains those certificates.
29928 Thus, make sure to add @code{nss-certs} or another certificate package to the
29929 @code{packages} field of your configuration. @ref{X.509 Certificates}, for
29930 more information on X.509 certificates.
29933 @subsubheading gmnisrv
29936 The @uref{https://git.sr.ht/~sircmpwn/gmnisrv, gmnisrv} program is a
29937 simple @uref{https://gemini.circumlunar.space/, Gemini} protocol server.
29939 @deffn {Scheme Variable} gmnisrv-service-type
29940 This is the type of the gmnisrv service, whose value should be a
29941 @code{gmnisrv-configuration} object, as in this example:
29944 (service gmnisrv-service-type
29945 (gmnisrv-configuration
29946 (config-file (local-file "./my-gmnisrv.ini"))))
29950 @deftp {Data Type} gmnisrv-configuration
29951 Data type representing the configuration of gmnisrv.
29954 @item @code{package} (default: @var{gmnisrv})
29955 Package object of the gmnisrv server.
29957 @item @code{config-file} (default: @code{%default-gmnisrv-config-file})
29958 File-like object of the gmnisrv configuration file to use. The default
29959 configuration listens on port 1965 and serves files from
29960 @file{/srv/gemini}. Certificates are stored in
29961 @file{/var/lib/gemini/certs}. For more information, run @command{man
29962 gmnisrv} and @command{man gmnisrv.ini}.
29967 @subsubheading Agate
29970 The @uref{gemini://qwertqwefsday.eu/agate.gmi, Agate}
29971 (@uref{https://github.com/mbrubeck/agate, GitHub page over HTTPS})
29972 program is a simple @uref{https://gemini.circumlunar.space/, Gemini}
29973 protocol server written in Rust.
29975 @deffn {Scheme Variable} agate-service-type
29976 This is the type of the agate service, whose value should be an
29977 @code{agate-service-type} object, as in this example:
29980 (service agate-service-type
29981 (agate-configuration
29982 (content "/srv/gemini")
29983 (cert "/srv/cert.pem")
29984 (key "/srv/key.rsa")))
29987 The example above represents the minimal tweaking necessary to get Agate
29988 up and running. Specifying the path to the certificate and key is
29989 always necessary, as the Gemini protocol requires TLS by default.
29991 To obtain a certificate and a key, you could, for example, use OpenSSL,
29992 running a command similar to the following example:
29995 openssl req -x509 -newkey rsa:4096 -keyout key.rsa -out cert.pem \
29996 -days 3650 -nodes -subj "/CN=example.com"
29999 Of course, you'll have to replace @i{example.com} with your own domain
30000 name, and then point the Agate configuration towards the path of the
30001 generated key and certificate.
30005 @deftp {Data Type} agate-configuration
30006 Data type representing the configuration of Agate.
30009 @item @code{package} (default: @code{agate})
30010 The package object of the Agate server.
30012 @item @code{content} (default: @file{"/srv/gemini"})
30013 The directory from which Agate will serve files.
30015 @item @code{cert} (default: @code{#f})
30016 The path to the TLS certificate PEM file to be used for encrypted
30017 connections. Must be filled in with a value from the user.
30019 @item @code{key} (default: @code{#f})
30020 The path to the PKCS8 private key file to be used for encrypted
30021 connections. Must be filled in with a value from the user.
30023 @item @code{addr} (default: @code{'("0.0.0.0:1965" "[::]:1965")})
30024 A list of the addresses to listen on.
30026 @item @code{hostname} (default: @code{#f})
30027 The domain name of this Gemini server. Optional.
30029 @item @code{lang} (default: @code{#f})
30030 RFC 4646 language code(s) for text/gemini documents. Optional.
30032 @item @code{silent?} (default: @code{#f})
30033 Set to @code{#t} to disable logging output.
30035 @item @code{serve-secret?} (default: @code{#f})
30036 Set to @code{#t} to serve secret files (files/directories starting with
30039 @item @code{log-ip?} (default: @code{#t})
30040 Whether or not to output IP addresses when logging.
30042 @item @code{user} (default: @code{"agate"})
30043 Owner of the @code{agate} process.
30045 @item @code{group} (default: @code{"agate"})
30046 Owner's group of the @code{agate} process.
30048 @item @code{log-file} (default: @file{"/var/log/agate.log"})
30049 The file which should store the logging output of Agate.
30054 @node Certificate Services
30055 @subsection Certificate Services
30058 @cindex HTTP, HTTPS
30059 @cindex Let's Encrypt
30060 @cindex TLS certificates
30061 The @code{(gnu services certbot)} module provides a service to
30062 automatically obtain a valid TLS certificate from the Let's Encrypt
30063 certificate authority. These certificates can then be used to serve
30064 content securely over HTTPS or other TLS-based protocols, with the
30065 knowledge that the client will be able to verify the server's
30068 @url{https://letsencrypt.org/, Let's Encrypt} provides the
30069 @code{certbot} tool to automate the certification process. This tool
30070 first securely generates a key on the server. It then makes a request
30071 to the Let's Encrypt certificate authority (CA) to sign the key. The CA
30072 checks that the request originates from the host in question by using a
30073 challenge-response protocol, requiring the server to provide its
30074 response over HTTP@. If that protocol completes successfully, the CA
30075 signs the key, resulting in a certificate. That certificate is valid
30076 for a limited period of time, and therefore to continue to provide TLS
30077 services, the server needs to periodically ask the CA to renew its
30080 The certbot service automates this process: the initial key
30081 generation, the initial certification request to the Let's Encrypt
30082 service, the web server challenge/response integration, writing the
30083 certificate to disk, the automated periodic renewals, and the deployment
30084 tasks associated with the renewal (e.g.@: reloading services, copying keys
30085 with different permissions).
30087 Certbot is run twice a day, at a random minute within the hour. It
30088 won't do anything until your certificates are due for renewal or
30089 revoked, but running it regularly would give your service a chance of
30090 staying online in case a Let's Encrypt-initiated revocation happened for
30093 By using this service, you agree to the ACME Subscriber Agreement, which
30094 can be found there:
30095 @url{https://acme-v01.api.letsencrypt.org/directory}.
30097 @defvr {Scheme Variable} certbot-service-type
30098 A service type for the @code{certbot} Let's Encrypt client. Its value
30099 must be a @code{certbot-configuration} record as in this example:
30102 (define %nginx-deploy-hook
30104 "nginx-deploy-hook"
30105 #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read)))
30106 (kill pid SIGHUP))))
30108 (service certbot-service-type
30109 (certbot-configuration
30110 (email "foo@@example.net")
30113 (certificate-configuration
30114 (domains '("example.net" "www.example.net"))
30115 (deploy-hook %nginx-deploy-hook))
30116 (certificate-configuration
30117 (domains '("bar.example.net")))))))
30120 See below for details about @code{certbot-configuration}.
30123 @deftp {Data Type} certbot-configuration
30124 Data type representing the configuration of the @code{certbot} service.
30125 This type has the following parameters:
30128 @item @code{package} (default: @code{certbot})
30129 The certbot package to use.
30131 @item @code{webroot} (default: @code{/var/www})
30132 The directory from which to serve the Let's Encrypt challenge/response
30135 @item @code{certificates} (default: @code{()})
30136 A list of @code{certificates-configuration}s for which to generate
30137 certificates and request signatures. Each certificate has a @code{name}
30138 and several @code{domains}.
30140 @item @code{email} (default: @code{#f})
30141 Optional email address used for registration and recovery contact.
30142 Setting this is encouraged as it allows you to receive important
30143 notifications about the account and issued certificates.
30145 @item @code{server} (default: @code{#f})
30146 Optional URL of ACME server. Setting this overrides certbot's default,
30147 which is the Let's Encrypt server.
30149 @item @code{rsa-key-size} (default: @code{2048})
30150 Size of the RSA key.
30152 @item @code{default-location} (default: @i{see below})
30153 The default @code{nginx-location-configuration}. Because @code{certbot}
30154 needs to be able to serve challenges and responses, it needs to be able
30155 to run a web server. It does so by extending the @code{nginx} web
30156 service with an @code{nginx-server-configuration} listening on the
30157 @var{domains} on port 80, and which has a
30158 @code{nginx-location-configuration} for the @code{/.well-known/} URI
30159 path subspace used by Let's Encrypt. @xref{Web Services}, for more on
30160 these nginx configuration data types.
30162 Requests to other URL paths will be matched by the
30163 @code{default-location}, which if present is added to all
30164 @code{nginx-server-configuration}s.
30166 By default, the @code{default-location} will issue a redirect from
30167 @code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving
30168 you to define what to serve on your site via @code{https}.
30170 Pass @code{#f} to not issue a default location.
30174 @deftp {Data Type} certificate-configuration
30175 Data type representing the configuration of a certificate.
30176 This type has the following parameters:
30179 @item @code{name} (default: @i{see below})
30180 This name is used by Certbot for housekeeping and in file paths; it
30181 doesn't affect the content of the certificate itself. To see
30182 certificate names, run @code{certbot certificates}.
30184 Its default is the first provided domain.
30186 @item @code{domains} (default: @code{()})
30187 The first domain provided will be the subject CN of the certificate, and
30188 all domains will be Subject Alternative Names on the certificate.
30190 @item @code{challenge} (default: @code{#f})
30191 The challenge type that has to be run by certbot. If @code{#f} is specified,
30192 default to the HTTP challenge. If a value is specified, defaults to the
30193 manual plugin (see @code{authentication-hook}, @code{cleanup-hook} and
30194 the documentation at @url{https://certbot.eff.org/docs/using.html#hooks}),
30195 and gives Let's Encrypt permission to log the public IP address of the
30196 requesting machine.
30198 @item @code{csr} (default: @code{#f})
30199 File name of Certificate Signing Request (CSR) in DER or PEM format.
30200 If @code{#f} is specified, this argument will not be passed to certbot.
30201 If a value is specified, certbot will use it to obtain a certificate, instead of
30202 using a self-generated CSR.
30203 The domain-name(s) mentioned in @code{domains}, must be consistent with the
30204 domain-name(s) mentioned in CSR file.
30206 @item @code{authentication-hook} (default: @code{#f})
30207 Command to be run in a shell once for each certificate challenge to be
30208 answered. For this command, the shell variable @code{$CERTBOT_DOMAIN}
30209 will contain the domain being authenticated, @code{$CERTBOT_VALIDATION}
30210 contains the validation string and @code{$CERTBOT_TOKEN} contains the
30211 file name of the resource requested when performing an HTTP-01 challenge.
30213 @item @code{cleanup-hook} (default: @code{#f})
30214 Command to be run in a shell once for each certificate challenge that
30215 have been answered by the @code{auth-hook}. For this command, the shell
30216 variables available in the @code{auth-hook} script are still available, and
30217 additionally @code{$CERTBOT_AUTH_OUTPUT} will contain the standard output
30218 of the @code{auth-hook} script.
30220 @item @code{deploy-hook} (default: @code{#f})
30221 Command to be run in a shell once for each successfully issued
30222 certificate. For this command, the shell variable
30223 @code{$RENEWED_LINEAGE} will point to the config live subdirectory (for
30224 example, @samp{"/etc/letsencrypt/live/example.com"}) containing the new
30225 certificates and keys; the shell variable @code{$RENEWED_DOMAINS} will
30226 contain a space-delimited list of renewed certificate domains (for
30227 example, @samp{"example.com www.example.com"}.
30232 For each @code{certificate-configuration}, the certificate is saved to
30233 @code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is
30234 saved to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}.
30236 @subsection DNS Services
30237 @cindex DNS (domain name system)
30238 @cindex domain name system (DNS)
30240 The @code{(gnu services dns)} module provides services related to the
30241 @dfn{domain name system} (DNS). It provides a server service for hosting
30242 an @emph{authoritative} DNS server for multiple zones, slave or master.
30243 This service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a
30244 caching and forwarding DNS server for the LAN, which uses
30245 @uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}.
30247 @subsubheading Knot Service
30249 An example configuration of an authoritative server for two zones, one master
30253 (define-zone-entries example.org.zone
30254 ;; Name TTL Class Type Data
30255 ("@@" "" "IN" "A" "127.0.0.1")
30256 ("@@" "" "IN" "NS" "ns")
30257 ("ns" "" "IN" "A" "127.0.0.1"))
30259 (define master-zone
30260 (knot-zone-configuration
30261 (domain "example.org")
30263 (origin "example.org")
30264 (entries example.org.zone)))))
30267 (knot-zone-configuration
30268 (domain "plop.org")
30269 (dnssec-policy "default")
30270 (master (list "plop-master"))))
30272 (define plop-master
30273 (knot-remote-configuration
30275 (address (list "208.76.58.171"))))
30279 (services (cons* (service knot-service-type
30280 (knot-configuration
30281 (remotes (list plop-master))
30282 (zones (list master-zone slave-zone))))
30287 @deffn {Scheme Variable} knot-service-type
30288 This is the type for the Knot DNS server.
30290 Knot DNS is an authoritative DNS server, meaning that it can serve multiple
30291 zones, that is to say domain names you would buy from a registrar. This server
30292 is not a resolver, meaning that it can only resolve names for which it is
30293 authoritative. This server can be configured to serve zones as a master server
30294 or a slave server as a per-zone basis. Slave zones will get their data from
30295 masters, and will serve it as an authoritative server. From the point of view
30296 of a resolver, there is no difference between master and slave.
30298 The following data types are used to configure the Knot DNS server:
30301 @deftp {Data Type} knot-key-configuration
30302 Data type representing a key.
30303 This type has the following parameters:
30306 @item @code{id} (default: @code{""})
30307 An identifier for other configuration fields to refer to this key. IDs must
30308 be unique and must not be empty.
30310 @item @code{algorithm} (default: @code{#f})
30311 The algorithm to use. Choose between @code{#f}, @code{'hmac-md5},
30312 @code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, @code{'hmac-sha384}
30313 and @code{'hmac-sha512}.
30315 @item @code{secret} (default: @code{""})
30316 The secret key itself.
30321 @deftp {Data Type} knot-acl-configuration
30322 Data type representing an Access Control List (ACL) configuration.
30323 This type has the following parameters:
30326 @item @code{id} (default: @code{""})
30327 An identifier for other configuration fields to refer to this key. IDs must be
30328 unique and must not be empty.
30330 @item @code{address} (default: @code{'()})
30331 An ordered list of IP addresses, network subnets, or network ranges represented
30332 with strings. The query must match one of them. Empty value means that
30333 address match is not required.
30335 @item @code{key} (default: @code{'()})
30336 An ordered list of references to keys represented with strings. The string
30337 must match a key ID defined in a @code{knot-key-configuration}. No key means
30338 that a key is not require to match that ACL.
30340 @item @code{action} (default: @code{'()})
30341 An ordered list of actions that are permitted or forbidden by this ACL@. Possible
30342 values are lists of zero or more elements from @code{'transfer}, @code{'notify}
30343 and @code{'update}.
30345 @item @code{deny?} (default: @code{#f})
30346 When true, the ACL defines restrictions. Listed actions are forbidden. When
30347 false, listed actions are allowed.
30352 @deftp {Data Type} zone-entry
30353 Data type representing a record entry in a zone file.
30354 This type has the following parameters:
30357 @item @code{name} (default: @code{"@@"})
30358 The name of the record. @code{"@@"} refers to the origin of the zone. Names
30359 are relative to the origin of the zone. For example, in the @code{example.org}
30360 zone, @code{"ns.example.org"} actually refers to @code{ns.example.org.example.org}.
30361 Names ending with a dot are absolute, which means that @code{"ns.example.org."}
30362 refers to @code{ns.example.org}.
30364 @item @code{ttl} (default: @code{""})
30365 The Time-To-Live (TTL) of this record. If not set, the default TTL is used.
30367 @item @code{class} (default: @code{"IN"})
30368 The class of the record. Knot currently supports only @code{"IN"} and
30369 partially @code{"CH"}.
30371 @item @code{type} (default: @code{"A"})
30372 The type of the record. Common types include A (IPv4 address), AAAA (IPv6
30373 address), NS (Name Server) and MX (Mail eXchange). Many other types are
30376 @item @code{data} (default: @code{""})
30377 The data contained in the record. For instance an IP address associated with
30378 an A record, or a domain name associated with an NS record. Remember that
30379 domain names are relative to the origin unless they end with a dot.
30384 @deftp {Data Type} zone-file
30385 Data type representing the content of a zone file.
30386 This type has the following parameters:
30389 @item @code{entries} (default: @code{'()})
30390 The list of entries. The SOA record is taken care of, so you don't need to
30391 put it in the list of entries. This list should probably contain an entry
30392 for your primary authoritative DNS server. Other than using a list of entries
30393 directly, you can use @code{define-zone-entries} to define a object containing
30394 the list of entries more easily, that you can later pass to the @code{entries}
30395 field of the @code{zone-file}.
30397 @item @code{origin} (default: @code{""})
30398 The name of your zone. This parameter cannot be empty.
30400 @item @code{ns} (default: @code{"ns"})
30401 The domain of your primary authoritative DNS server. The name is relative to
30402 the origin, unless it ends with a dot. It is mandatory that this primary
30403 DNS server corresponds to an NS record in the zone and that it is associated
30404 to an IP address in the list of entries.
30406 @item @code{mail} (default: @code{"hostmaster"})
30407 An email address people can contact you at, as the owner of the zone. This
30408 is translated as @code{<mail>@@<origin>}.
30410 @item @code{serial} (default: @code{1})
30411 The serial number of the zone. As this is used to keep track of changes by
30412 both slaves and resolvers, it is mandatory that it @emph{never} decreases.
30413 Always increment it when you make a change in your zone.
30415 @item @code{refresh} (default: @code{(* 2 24 3600)})
30416 The frequency at which slaves will do a zone transfer. This value is a number
30417 of seconds. It can be computed by multiplications or with
30418 @code{(string->duration)}.
30420 @item @code{retry} (default: @code{(* 15 60)})
30421 The period after which a slave will retry to contact its master when it fails
30422 to do so a first time.
30424 @item @code{expiry} (default: @code{(* 14 24 3600)})
30425 Default TTL of records. Existing records are considered correct for at most
30426 this amount of time. After this period, resolvers will invalidate their cache
30427 and check again that it still exists.
30429 @item @code{nx} (default: @code{3600})
30430 Default TTL of inexistent records. This delay is usually short because you want
30431 your new domains to reach everyone quickly.
30436 @deftp {Data Type} knot-remote-configuration
30437 Data type representing a remote configuration.
30438 This type has the following parameters:
30441 @item @code{id} (default: @code{""})
30442 An identifier for other configuration fields to refer to this remote. IDs must
30443 be unique and must not be empty.
30445 @item @code{address} (default: @code{'()})
30446 An ordered list of destination IP addresses. Addresses are tried in sequence.
30447 An optional port can be given with the @@ separator. For instance:
30448 @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53.
30450 @item @code{via} (default: @code{'()})
30451 An ordered list of source IP addresses. An empty list will have Knot choose
30452 an appropriate source IP@. An optional port can be given with the @@ separator.
30453 The default is to choose at random.
30455 @item @code{key} (default: @code{#f})
30456 A reference to a key, that is a string containing the identifier of a key
30457 defined in a @code{knot-key-configuration} field.
30462 @deftp {Data Type} knot-keystore-configuration
30463 Data type representing a keystore to hold dnssec keys.
30464 This type has the following parameters:
30467 @item @code{id} (default: @code{""})
30468 The id of the keystore. It must not be empty.
30470 @item @code{backend} (default: @code{'pem})
30471 The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}.
30473 @item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
30474 The configuration string of the backend. An example for the PKCS#11 is:
30475 @code{"pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}.
30476 For the pem backend, the string represents a path in the file system.
30481 @deftp {Data Type} knot-policy-configuration
30482 Data type representing a dnssec policy. Knot DNS is able to automatically
30483 sign your zones. It can either generate and manage your keys automatically or
30484 use keys that you generate.
30486 Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that is
30487 used to sign the second, and a Zone Signing Key (ZSK) that is used to sign the
30488 zone. In order to be trusted, the KSK needs to be present in the parent zone
30489 (usually a top-level domain). If your registrar supports dnssec, you will
30490 have to send them your KSK's hash so they can add a DS record in their zone.
30491 This is not automated and need to be done each time you change your KSK.
30493 The policy also defines the lifetime of keys. Usually, ZSK can be changed
30494 easily and use weaker cryptographic functions (they use lower parameters) in
30495 order to sign records quickly, so they are changed often. The KSK however
30496 requires manual interaction with the registrar, so they are changed less often
30497 and use stronger parameters because they sign only one record.
30499 This type has the following parameters:
30502 @item @code{id} (default: @code{""})
30503 The id of the policy. It must not be empty.
30505 @item @code{keystore} (default: @code{"default"})
30506 A reference to a keystore, that is a string containing the identifier of a
30507 keystore defined in a @code{knot-keystore-configuration} field. The
30508 @code{"default"} identifier means the default keystore (a kasp database that
30509 was setup by this service).
30511 @item @code{manual?} (default: @code{#f})
30512 Whether the key management is manual or automatic.
30514 @item @code{single-type-signing?} (default: @code{#f})
30515 When @code{#t}, use the Single-Type Signing Scheme.
30517 @item @code{algorithm} (default: @code{"ecdsap256sha256"})
30518 An algorithm of signing keys and issued signatures.
30520 @item @code{ksk-size} (default: @code{256})
30521 The length of the KSK@. Note that this value is correct for the default
30522 algorithm, but would be unsecure for other algorithms.
30524 @item @code{zsk-size} (default: @code{256})
30525 The length of the ZSK@. Note that this value is correct for the default
30526 algorithm, but would be unsecure for other algorithms.
30528 @item @code{dnskey-ttl} (default: @code{'default})
30529 The TTL value for DNSKEY records added into zone apex. The special
30530 @code{'default} value means same as the zone SOA TTL.
30532 @item @code{zsk-lifetime} (default: @code{(* 30 24 3600)})
30533 The period between ZSK publication and the next rollover initiation.
30535 @item @code{propagation-delay} (default: @code{(* 24 3600)})
30536 An extra delay added for each key rollover step. This value should be high
30537 enough to cover propagation of data from the master server to all slaves.
30539 @item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)})
30540 A validity period of newly issued signatures.
30542 @item @code{rrsig-refresh} (default: @code{(* 7 24 3600)})
30543 A period how long before a signature expiration the signature will be refreshed.
30545 @item @code{nsec3?} (default: @code{#f})
30546 When @code{#t}, NSEC3 will be used instead of NSEC.
30548 @item @code{nsec3-iterations} (default: @code{5})
30549 The number of additional times the hashing is performed.
30551 @item @code{nsec3-salt-length} (default: @code{8})
30552 The length of a salt field in octets, which is appended to the original owner
30553 name before hashing.
30555 @item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)})
30556 The validity period of newly issued salt field.
30561 @deftp {Data Type} knot-zone-configuration
30562 Data type representing a zone served by Knot.
30563 This type has the following parameters:
30566 @item @code{domain} (default: @code{""})
30567 The domain served by this configuration. It must not be empty.
30569 @item @code{file} (default: @code{""})
30570 The file where this zone is saved. This parameter is ignored by master zones.
30571 Empty means default location that depends on the domain name.
30573 @item @code{zone} (default: @code{(zone-file)})
30574 The content of the zone file. This parameter is ignored by slave zones. It
30575 must contain a zone-file record.
30577 @item @code{master} (default: @code{'()})
30578 A list of master remotes. When empty, this zone is a master. When set, this
30579 zone is a slave. This is a list of remotes identifiers.
30581 @item @code{ddns-master} (default: @code{#f})
30582 The main master. When empty, it defaults to the first master in the list of
30585 @item @code{notify} (default: @code{'()})
30586 A list of slave remote identifiers.
30588 @item @code{acl} (default: @code{'()})
30589 A list of acl identifiers.
30591 @item @code{semantic-checks?} (default: @code{#f})
30592 When set, this adds more semantic checks to the zone.
30594 @item @code{zonefile-sync} (default: @code{0})
30595 The delay between a modification in memory and on disk. 0 means immediate
30598 @item @code{zonefile-load} (default: @code{#f})
30599 The way the zone file contents are applied during zone load. Possible values
30603 @item @code{#f} for using the default value from Knot,
30604 @item @code{'none} for not using the zone file at all,
30605 @item @code{'difference} for computing the difference between already available
30606 contents and zone contents and applying it to the current zone contents,
30607 @item @code{'difference-no-serial} for the same as @code{'difference}, but
30608 ignoring the SOA serial in the zone file, while the server takes care of it
30610 @item @code{'whole} for loading zone contents from the zone file.
30613 @item @code{journal-content} (default: @code{#f})
30614 The way the journal is used to store zone and its changes. Possible values
30615 are @code{'none} to not use it at all, @code{'changes} to store changes and
30616 @code{'all} to store contents. @code{#f} does not set this option, so the
30617 default value from Knot is used.
30619 @item @code{max-journal-usage} (default: @code{#f})
30620 The maximum size for the journal on disk. @code{#f} does not set this option,
30621 so the default value from Knot is used.
30623 @item @code{max-journal-depth} (default: @code{#f})
30624 The maximum size of the history. @code{#f} does not set this option, so the
30625 default value from Knot is used.
30627 @item @code{max-zone-size} (default: @code{#f})
30628 The maximum size of the zone file. This limit is enforced for incoming
30629 transfer and updates. @code{#f} does not set this option, so the default
30630 value from Knot is used.
30632 @item @code{dnssec-policy} (default: @code{#f})
30633 A reference to a @code{knot-policy-configuration} record, or the special
30634 name @code{"default"}. If the value is @code{#f}, there is no dnssec signing
30637 @item @code{serial-policy} (default: @code{'increment})
30638 A policy between @code{'increment} and @code{'unixtime}.
30643 @deftp {Data Type} knot-configuration
30644 Data type representing the Knot configuration.
30645 This type has the following parameters:
30648 @item @code{knot} (default: @code{knot})
30651 @item @code{run-directory} (default: @code{"/var/run/knot"})
30652 The run directory. This directory will be used for pid file and sockets.
30654 @item @code{includes} (default: @code{'()})
30655 A list of strings or file-like objects denoting other files that must be
30656 included at the top of the configuration file.
30658 @cindex secrets, Knot service
30659 This can be used to manage secrets out-of-band. For example, secret
30660 keys may be stored in an out-of-band file not managed by Guix, and
30661 thus not visible in @file{/gnu/store}---e.g., you could store secret
30662 key configuration in @file{/etc/knot/secrets.conf} and add this file
30663 to the @code{includes} list.
30665 One can generate a secret tsig key (for nsupdate and zone transfers with the
30666 keymgr command from the knot package. Note that the package is not automatically
30667 installed by the service. The following example shows how to generate a new
30671 keymgr -t mysecret > /etc/knot/secrets.conf
30672 chmod 600 /etc/knot/secrets.conf
30675 Also note that the generated key will be named @var{mysecret}, so it is the
30676 name that needs to be used in the @var{key} field of the
30677 @code{knot-acl-configuration} record and in other places that need to refer
30680 It can also be used to add configuration not supported by this interface.
30682 @item @code{listen-v4} (default: @code{"0.0.0.0"})
30683 An ip address on which to listen.
30685 @item @code{listen-v6} (default: @code{"::"})
30686 An ip address on which to listen.
30688 @item @code{listen-port} (default: @code{53})
30689 A port on which to listen.
30691 @item @code{keys} (default: @code{'()})
30692 The list of knot-key-configuration used by this configuration.
30694 @item @code{acls} (default: @code{'()})
30695 The list of knot-acl-configuration used by this configuration.
30697 @item @code{remotes} (default: @code{'()})
30698 The list of knot-remote-configuration used by this configuration.
30700 @item @code{zones} (default: @code{'()})
30701 The list of knot-zone-configuration used by this configuration.
30706 @subsubheading Knot Resolver Service
30708 @deffn {Scheme Variable} knot-resolver-service-type
30709 This is the type of the knot resolver service, whose value should be
30710 an @code{knot-resolver-configuration} object as in this example:
30713 (service knot-resolver-service-type
30714 (knot-resolver-configuration
30715 (kresd-config-file (plain-file "kresd.conf" "
30716 net.listen('192.168.0.1', 5353)
30717 user('knot-resolver', 'knot-resolver')
30718 modules = @{ 'hints > iterate', 'stats', 'predict' @}
30719 cache.size = 100 * MB
30723 For more information, refer its @url{https://knot-resolver.readthedocs.org/en/stable/daemon.html#configuration, manual}.
30726 @deftp {Data Type} knot-resolver-configuration
30727 Data type representing the configuration of knot-resolver.
30730 @item @code{package} (default: @var{knot-resolver})
30731 Package object of the knot DNS resolver.
30733 @item @code{kresd-config-file} (default: %kresd.conf)
30734 File-like object of the kresd configuration file to use, by default it
30735 will listen on @code{127.0.0.1} and @code{::1}.
30737 @item @code{garbage-collection-interval} (default: 1000)
30738 Number of milliseconds for @code{kres-cache-gc} to periodically trim the cache.
30744 @subsubheading Dnsmasq Service
30746 @deffn {Scheme Variable} dnsmasq-service-type
30747 This is the type of the dnsmasq service, whose value should be an
30748 @code{dnsmasq-configuration} object as in this example:
30751 (service dnsmasq-service-type
30752 (dnsmasq-configuration
30754 (servers '("192.168.1.1"))))
30758 @deftp {Data Type} dnsmasq-configuration
30759 Data type representing the configuration of dnsmasq.
30762 @item @code{package} (default: @var{dnsmasq})
30763 Package object of the dnsmasq server.
30765 @item @code{no-hosts?} (default: @code{#f})
30766 When true, don't read the hostnames in /etc/hosts.
30768 @item @code{port} (default: @code{53})
30769 The port to listen on. Setting this to zero completely disables DNS
30770 responses, leaving only DHCP and/or TFTP functions.
30772 @item @code{local-service?} (default: @code{#t})
30773 Accept DNS queries only from hosts whose address is on a local subnet,
30774 ie a subnet for which an interface exists on the server.
30776 @item @code{listen-addresses} (default: @code{'()})
30777 Listen on the given IP addresses.
30779 @item @code{resolv-file} (default: @code{"/etc/resolv.conf"})
30780 The file to read the IP address of the upstream nameservers from.
30782 @item @code{no-resolv?} (default: @code{#f})
30783 When true, don't read @var{resolv-file}.
30785 @item @code{forward-private-reverse-lookup?} (default: @code{#t})
30786 When false, all reverse lookups for private IP ranges are answered with
30787 "no such domain" rather than being forwarded upstream.
30789 @item @code{query-servers-in-order?} (default: @code{#f})
30790 When true, dnsmasq queries the servers in the same order as they appear
30793 @item @code{servers} (default: @code{'()})
30794 Specify IP address of upstream servers directly.
30796 @item @code{addresses} (default: @code{'()})
30797 For each entry, specify an IP address to return for any host in the
30798 given domains. Queries in the domains are never forwarded and always
30799 replied to with the specified IP address.
30801 This is useful for redirecting hosts locally, for example:
30804 (service dnsmasq-service-type
30805 (dnsmasq-configuration
30807 '(; Redirect to a local web-server.
30808 "/example.org/127.0.0.1"
30809 ; Redirect subdomain to a specific IP.
30810 "/subdomain.example.org/192.168.1.42"))))
30813 Note that rules in @file{/etc/hosts} take precedence over this.
30815 @item @code{cache-size} (default: @code{150})
30816 Set the size of dnsmasq's cache. Setting the cache size to zero
30819 @item @code{negative-cache?} (default: @code{#t})
30820 When false, disable negative caching.
30822 @item @code{cpe-id} (default: @code{#f})
30823 If set, add a CPE (Customer-Premises Equipment) identifier to DNS
30824 queries which are forwarded upstream.
30826 @item @code{tftp-enable?} (default: @code{#f})
30827 Whether to enable the built-in TFTP server.
30829 @item @code{tftp-no-fail?} (default: @code{#f})
30830 If true, does not fail dnsmasq if the TFTP server could not start up.
30832 @item @code{tftp-single-port?} (default: @code{#f})
30833 Whether to use only one single port for TFTP.
30835 @item @code{tftp-secure?} (default: @code{#f})
30836 If true, only files owned by the user running the dnsmasq process are accessible.
30838 If dnsmasq is being run as root, different rules apply:
30839 @code{tftp-secure?} has no effect, but only files which have the
30840 world-readable bit set are accessible.
30842 @item @code{tftp-max} (default: @code{#f})
30843 If set, sets the maximal number of concurrent connections allowed.
30845 @item @code{tftp-mtu} (default: @code{#f})
30846 If set, sets the MTU for TFTP packets to that value.
30848 @item @code{tftp-no-blocksize?} (default: @code{#f})
30849 If true, stops the TFTP server from negotiating the blocksize with a client.
30851 @item @code{tftp-lowercase?} (default: @code{#f})
30852 Whether to convert all filenames in TFTP requests to lowercase.
30854 @item @code{tftp-port-range} (default: @code{#f})
30855 If set, fixes the dynamical ports (one per client) to the given range
30856 (@code{"<start>,<end>"}).
30858 @item @code{tftp-root} (default: @code{/var/empty,lo})
30859 Look for files to transfer using TFTP relative to the given directory.
30860 When this is set, TFTP paths which include @samp{..} are rejected, to stop clients
30861 getting outside the specified root. Absolute paths (starting with @samp{/}) are
30862 allowed, but they must be within the TFTP-root. If the optional interface
30863 argument is given, the directory is only used for TFTP requests via that
30866 @item @code{tftp-unique-root} (default: @code{#f})
30867 If set, add the IP or hardware address of the TFTP client as a path component
30868 on the end of the TFTP-root. Only valid if a TFTP root is set and the
30869 directory exists. Defaults to adding IP address (in standard dotted-quad
30872 For instance, if @option{--tftp-root} is @samp{/tftp} and client
30873 @samp{1.2.3.4} requests file @file{myfile} then the effective path will
30874 be @file{/tftp/1.2.3.4/myfile} if @file{/tftp/1.2.3.4} exists or
30875 @file{/tftp/myfile} otherwise. When @samp{=mac} is specified it will
30876 append the MAC address instead, using lowercase zero padded digits
30877 separated by dashes, e.g.: @samp{01-02-03-04-aa-bb}. Note that
30878 resolving MAC addresses is only possible if the client is in the local
30879 network or obtained a DHCP lease from dnsmasq.
30884 @subsubheading ddclient Service
30887 The ddclient service described below runs the ddclient daemon, which takes
30888 care of automatically updating DNS entries for service providers such as
30889 @uref{https://dyn.com/dns/, Dyn}.
30891 The following example show instantiates the service with its default
30895 (service ddclient-service-type)
30898 Note that ddclient needs to access credentials that are stored in a
30899 @dfn{secret file}, by default @file{/etc/ddclient/secrets} (see
30900 @code{secret-file} below). You are expected to create this file manually, in
30901 an ``out-of-band'' fashion (you @emph{could} make this file part of the
30902 service configuration, for instance by using @code{plain-file}, but it will be
30903 world-readable @i{via} @file{/gnu/store}). See the examples in the
30904 @file{share/ddclient} directory of the @code{ddclient} package.
30906 @c %start of fragment
30908 Available @code{ddclient-configuration} fields are:
30910 @deftypevr {@code{ddclient-configuration} parameter} package ddclient
30911 The ddclient package.
30915 @deftypevr {@code{ddclient-configuration} parameter} integer daemon
30916 The period after which ddclient will retry to check IP and domain name.
30918 Defaults to @samp{300}.
30922 @deftypevr {@code{ddclient-configuration} parameter} boolean syslog
30923 Use syslog for the output.
30925 Defaults to @samp{#t}.
30929 @deftypevr {@code{ddclient-configuration} parameter} string mail
30932 Defaults to @samp{"root"}.
30936 @deftypevr {@code{ddclient-configuration} parameter} string mail-failure
30937 Mail failed update to user.
30939 Defaults to @samp{"root"}.
30943 @deftypevr {@code{ddclient-configuration} parameter} string pid
30944 The ddclient PID file.
30946 Defaults to @samp{"/var/run/ddclient/ddclient.pid"}.
30950 @deftypevr {@code{ddclient-configuration} parameter} boolean ssl
30951 Enable SSL support.
30953 Defaults to @samp{#t}.
30957 @deftypevr {@code{ddclient-configuration} parameter} string user
30958 Specifies the user name or ID that is used when running ddclient
30961 Defaults to @samp{"ddclient"}.
30965 @deftypevr {@code{ddclient-configuration} parameter} string group
30966 Group of the user who will run the ddclient program.
30968 Defaults to @samp{"ddclient"}.
30972 @deftypevr {@code{ddclient-configuration} parameter} string secret-file
30973 Secret file which will be appended to @file{ddclient.conf} file. This
30974 file contains credentials for use by ddclient. You are expected to
30975 create it manually.
30977 Defaults to @samp{"/etc/ddclient/secrets.conf"}.
30981 @deftypevr {@code{ddclient-configuration} parameter} list extra-options
30982 Extra options will be appended to @file{ddclient.conf} file.
30984 Defaults to @samp{()}.
30989 @c %end of fragment
30992 @subsection VNC Services
30993 @cindex VNC (virtual network computing)
30994 @cindex XDMCP (x display manager control protocol)
30996 The @code{(gnu services vnc)} module provides services related to
30997 @dfn{Virtual Network Computing} (VNC), which makes it possible to
30998 locally use graphical Xorg applications running on a remote machine.
30999 Combined with a graphical manager that supports the @dfn{X Display
31000 Manager Control Protocol}, such as GDM (@pxref{gdm}) or LightDM
31001 (@pxref{lightdm}), it is possible to remote an entire desktop for a
31002 multi-user environment.
31004 @subsubheading Xvnc
31006 Xvnc is a VNC server that spawns its own X window server; which means it
31007 can run on headless servers. The Xvnc implementations provided by the
31008 @code{tigervnc-server} and @code{turbovnc} aim to be fast and efficient.
31010 @defvar {Scheme Variable} xvnc-service-type
31012 The @code{xvnc-server-type} service can be configured via the
31013 @code{xvnc-configuration} record, documented below. A second virtual
31014 display could be made available on a remote machine via the
31015 following configuration:
31019 (service xvnc-service-type (xvnc-configuration (display-number 10)
31022 As a demonstration, the @command{xclock} command could then be started
31023 on the remote machine on display number 10, and it could be displayed
31024 locally via the @command{vncviewer} command:
31026 # Start xclock on the remote machine.
31027 ssh -L5910:localhost:5910 -- guix shell xclock -- env DISPLAY=:10 xclock
31028 # Access it via VNC.
31029 guix shell tigervnc-client -- vncviewer localhost:5910
31032 The following configuration combines XDMCP and Inetd to allow multiple
31033 users to concurrently use the remote system, login in graphically via
31034 the GDM display manager:
31041 (service xvnc-service-type (xvnc-configuration
31046 (modify-services %desktop-services
31047 (gdm-service-type config => (gdm-configuration
31053 A remote user could then connect to it by using the @command{vncviewer}
31054 command or a compatible VNC client and start a desktop session of their
31057 vncviewer remote-host:5905
31061 Unless your machine is in a controlled environment, for security
31062 reasons, the @code{localhost?} configuration of the
31063 @code{xvnc-configuration} record should be left to its default @code{#t}
31064 value and exposed via a secure means such as an SSH port forward. The
31065 XDMCP port, UDP 177 should also be blocked from the outside by a
31066 firewall, as it is not a secure protocol and can expose login
31067 credentials in clear.
31070 @c Use (configuration->documentation 'xvnc-configuration) to regenerate
31071 @c the documentation.
31072 @c %start of fragment
31073 @deftp {Data Type} xvnc-configuration
31074 Available @code{xvnc-configuration} fields are:
31077 @item @code{xvnc} (default: @code{tigervnc-server}) (type: file-like)
31078 The package that provides the Xvnc binary.
31080 @item @code{display-number} (default: @code{0}) (type: number)
31081 The display number used by Xvnc. You should set this to a number not
31082 already used a Xorg server.
31084 @item @code{geometry} (default: @code{"1024x768"}) (type: string)
31085 The size of the desktop to be created.
31087 @item @code{depth} (default: @code{24}) (type: color-depth)
31088 The pixel depth in bits of the desktop to be created. Accepted values
31091 @item @code{port} (type: maybe-port)
31092 The port on which to listen for connections from viewers. When left
31093 unspecified, it defaults to 5900 plus the display number.
31095 @item @code{ipv4?} (default: @code{#t}) (type: boolean)
31096 Use IPv4 for incoming and outgoing connections.
31098 @item @code{ipv6?} (default: @code{#t}) (type: boolean)
31099 Use IPv6 for incoming and outgoing connections.
31101 @item @code{password-file} (type: maybe-string)
31102 The password file to use, if any. Refer to vncpasswd(1) to learn how to
31103 generate such a file.
31105 @item @code{xdmcp?} (default: @code{#f}) (type: boolean)
31106 Query the XDMCP server for a session. This enables users to log in a
31107 desktop session from the login manager screen. For a multiple users
31108 scenario, you'll want to enable the @code{inetd?} option as well, so
31109 that each connection to the VNC server is handled separately rather than
31112 @item @code{inetd?} (default: @code{#f}) (type: boolean)
31113 Use an Inetd-style service, which runs the Xvnc server on demand.
31115 @item @code{frame-rate} (default: @code{60}) (type: number)
31116 The maximum number of updates per second sent to each client.
31118 @item @code{security-types} (default: @code{("None")}) (type: security-types)
31119 The allowed security schemes to use for incoming connections. The
31120 default is "None", which is safe given that Xvnc is configured to
31121 authenticate the user via the display manager, and only for local
31122 connections. Accepted values are any of the following: ("None"
31123 "VncAuth" "Plain" "TLSNone" "TLSVnc" "TLSPlain" "X509None" "X509Vnc")
31125 @item @code{localhost?} (default: @code{#t}) (type: boolean)
31126 Only allow connections from the same machine. It is set to #true by
31127 default for security, which means SSH or another secure means should be
31128 used to expose the remote port.
31130 @item @code{log-level} (default: @code{30}) (type: log-level)
31131 The log level, a number between 0 and 100, 100 meaning most verbose
31132 output. The log messages are output to syslog.
31134 @item @code{extra-options} (default: @code{()}) (type: strings)
31135 This can be used to provide extra Xvnc options not exposed via this
31136 <xvnc-configuration> record.
31141 @c %end of fragment
31144 @subsection VPN Services
31145 @cindex VPN (virtual private network)
31146 @cindex virtual private network (VPN)
31148 The @code{(gnu services vpn)} module provides services related to
31149 @dfn{virtual private networks} (VPNs).
31151 @subsubheading Bitmask
31153 @defvr {Scheme Variable} bitmask-service-type
31154 A service type for the @uref{https://bitmask.net, Bitmask} VPN client. It makes
31155 the client available in the system and loads its polkit policy. Please note that
31156 the client expects an active polkit-agent, which is either run by your
31157 desktop-environment or should be run manually.
31160 @subsubheading OpenVPN
31162 It provides a @emph{client} service for your machine to connect to a
31163 VPN, and a @emph{server} service for your machine to host a VPN@.
31165 @deffn {Scheme Procedure} openvpn-client-service @
31166 [#:config (openvpn-client-configuration)]
31168 Return a service that runs @command{openvpn}, a VPN daemon, as a client.
31171 @deffn {Scheme Procedure} openvpn-server-service @
31172 [#:config (openvpn-server-configuration)]
31174 Return a service that runs @command{openvpn}, a VPN daemon, as a server.
31176 Both can be run simultaneously.
31179 @c %automatically generated documentation
31181 @deftp {Data Type} openvpn-client-configuration
31182 Available @code{openvpn-client-configuration} fields are:
31185 @item @code{openvpn} (default: @code{openvpn}) (type: file-like)
31186 The OpenVPN package.
31188 @item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
31189 The OpenVPN pid file.
31191 @item @code{proto} (default: @code{udp}) (type: proto)
31192 The protocol (UDP or TCP) used to open a channel between clients and
31195 @item @code{dev} (default: @code{tun}) (type: dev)
31196 The device type used to represent the VPN connection.
31198 @item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
31199 The certificate authority to check connections against.
31201 @item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
31202 The certificate of the machine the daemon is running on. It should be
31203 signed by the authority given in @code{ca}.
31205 @item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
31206 The key of the machine the daemon is running on. It must be the key
31207 whose certificate is @code{cert}.
31209 @item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
31210 Whether to use the lzo compression algorithm.
31212 @item @code{persist-key?} (default: @code{#t}) (type: boolean)
31213 Don't re-read key files across SIGUSR1 or --ping-restart.
31215 @item @code{persist-tun?} (default: @code{#t}) (type: boolean)
31216 Don't close and reopen TUN/TAP device or run up/down scripts across
31217 SIGUSR1 or --ping-restart restarts.
31219 @item @code{fast-io?} (default: @code{#f}) (type: boolean)
31220 (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
31221 poll/epoll/select prior to the write operation.
31223 @item @code{verbosity} (default: @code{3}) (type: number)
31226 @item @code{tls-auth} (default: @code{#f}) (type: tls-auth-client)
31227 Add an additional layer of HMAC authentication on top of the TLS control
31228 channel to protect against DoS attacks.
31230 @item @code{auth-user-pass} (type: maybe-string)
31231 Authenticate with server using username/password. The option is a file
31232 containing username/password on 2 lines. Do not use a file-like object
31233 as it would be added to the store and readable by any user.
31235 @item @code{verify-key-usage?} (default: @code{#t}) (type: key-usage)
31236 Whether to check the server certificate has server usage extension.
31238 @item @code{bind?} (default: @code{#f}) (type: bind)
31239 Bind to a specific local port number.
31241 @item @code{resolv-retry?} (default: @code{#t}) (type: resolv-retry)
31242 Retry resolving server address.
31244 @item @code{remote} (default: @code{()}) (type: openvpn-remote-list)
31245 A list of remote servers to connect to.
31247 @deftp {Data Type} openvpn-remote-configuration
31248 Available @code{openvpn-remote-configuration} fields are:
31251 @item @code{name} (default: @code{"my-server"}) (type: string)
31254 @item @code{port} (default: @code{1194}) (type: number)
31255 Port number the server listens to.
31265 @c %end of automatic openvpn-client documentation
31267 @c %automatically generated documentation
31269 @deftp {Data Type} openvpn-server-configuration
31270 Available @code{openvpn-server-configuration} fields are:
31273 @item @code{openvpn} (default: @code{openvpn}) (type: file-like)
31274 The OpenVPN package.
31276 @item @code{pid-file} (default: @code{"/var/run/openvpn/openvpn.pid"}) (type: string)
31277 The OpenVPN pid file.
31279 @item @code{proto} (default: @code{udp}) (type: proto)
31280 The protocol (UDP or TCP) used to open a channel between clients and
31283 @item @code{dev} (default: @code{tun}) (type: dev)
31284 The device type used to represent the VPN connection.
31286 @item @code{ca} (default: @code{"/etc/openvpn/ca.crt"}) (type: maybe-string)
31287 The certificate authority to check connections against.
31289 @item @code{cert} (default: @code{"/etc/openvpn/client.crt"}) (type: maybe-string)
31290 The certificate of the machine the daemon is running on. It should be
31291 signed by the authority given in @code{ca}.
31293 @item @code{key} (default: @code{"/etc/openvpn/client.key"}) (type: maybe-string)
31294 The key of the machine the daemon is running on. It must be the key
31295 whose certificate is @code{cert}.
31297 @item @code{comp-lzo?} (default: @code{#t}) (type: boolean)
31298 Whether to use the lzo compression algorithm.
31300 @item @code{persist-key?} (default: @code{#t}) (type: boolean)
31301 Don't re-read key files across SIGUSR1 or --ping-restart.
31303 @item @code{persist-tun?} (default: @code{#t}) (type: boolean)
31304 Don't close and reopen TUN/TAP device or run up/down scripts across
31305 SIGUSR1 or --ping-restart restarts.
31307 @item @code{fast-io?} (default: @code{#f}) (type: boolean)
31308 (Experimental) Optimize TUN/TAP/UDP I/O writes by avoiding a call to
31309 poll/epoll/select prior to the write operation.
31311 @item @code{verbosity} (default: @code{3}) (type: number)
31314 @item @code{tls-auth} (default: @code{#f}) (type: tls-auth-server)
31315 Add an additional layer of HMAC authentication on top of the TLS control
31316 channel to protect against DoS attacks.
31318 @item @code{port} (default: @code{1194}) (type: number)
31319 Specifies the port number on which the server listens.
31321 @item @code{server} (default: @code{"10.8.0.0 255.255.255.0"}) (type: ip-mask)
31322 An ip and mask specifying the subnet inside the virtual network.
31324 @item @code{server-ipv6} (default: @code{#f}) (type: cidr6)
31325 A CIDR notation specifying the IPv6 subnet inside the virtual network.
31327 @item @code{dh} (default: @code{"/etc/openvpn/dh2048.pem"}) (type: string)
31328 The Diffie-Hellman parameters file.
31330 @item @code{ifconfig-pool-persist} (default: @code{"/etc/openvpn/ipp.txt"}) (type: string)
31331 The file that records client IPs.
31333 @item @code{redirect-gateway?} (default: @code{#f}) (type: gateway)
31334 When true, the server will act as a gateway for its clients.
31336 @item @code{client-to-client?} (default: @code{#f}) (type: boolean)
31337 When true, clients are allowed to talk to each other inside the VPN.
31339 @item @code{keepalive} (default: @code{(10 120)}) (type: keepalive)
31340 Causes ping-like messages to be sent back and forth over the link so
31341 that each side knows when the other side has gone down. @code{keepalive}
31342 requires a pair. The first element is the period of the ping sending,
31343 and the second element is the timeout before considering the other side
31346 @item @code{max-clients} (default: @code{100}) (type: number)
31347 The maximum number of clients.
31349 @item @code{status} (default: @code{"/var/run/openvpn/status"}) (type: string)
31350 The status file. This file shows a small report on current connection.
31351 It is truncated and rewritten every minute.
31353 @item @code{client-config-dir} (default: @code{()}) (type: openvpn-ccd-list)
31354 The list of configuration for some clients.
31360 @c %end of automatic openvpn-server documentation
31362 @subheading strongSwan
31364 Currently, the strongSwan service only provides legacy-style configuration with
31365 @file{ipsec.conf} and @file{ipsec.secrets} files.
31367 @defvr {Scheme Variable} strongswan-service-type
31368 A service type for configuring strongSwan for IPsec @acronym{VPN,
31369 Virtual Private Networking}. Its value must be a
31370 @code{strongswan-configuration} record as in this example:
31373 (service strongswan-service-type
31374 (strongswan-configuration
31375 (ipsec-conf "/etc/ipsec.conf")
31376 (ipsec-secrets "/etc/ipsec.secrets")))
31381 @deftp {Data Type} strongswan-configuration
31382 Data type representing the configuration of the StrongSwan service.
31385 @item @code{strongswan}
31386 The strongSwan package to use for this service.
31388 @item @code{ipsec-conf} (default: @code{#f})
31389 The file name of your @file{ipsec.conf}. If not @code{#f}, then this and
31390 @code{ipsec-secrets} must both be strings.
31392 @item @code{ipsec-secrets} (default @code{#f})
31393 The file name of your @file{ipsec.secrets}. If not @code{#f}, then this and
31394 @code{ipsec-conf} must both be strings.
31399 @subsubheading Wireguard
31401 @defvr {Scheme Variable} wireguard-service-type
31402 A service type for a Wireguard tunnel interface. Its value must be a
31403 @code{wireguard-configuration} record as in this example:
31406 (service wireguard-service-type
31407 (wireguard-configuration
31412 (endpoint "my.wireguard.com:51820")
31413 (public-key "hzpKg9X1yqu1axN6iJp0mWf6BZGo8m1wteKwtTmDGF4=")
31414 (allowed-ips '("10.0.0.2/32")))))))
31419 @deftp {Data Type} wireguard-configuration
31420 Data type representing the configuration of the Wireguard service.
31423 @item @code{wireguard}
31424 The wireguard package to use for this service.
31426 @item @code{interface} (default: @code{"wg0"})
31427 The interface name for the VPN.
31429 @item @code{addresses} (default: @code{'("10.0.0.1/32")})
31430 The IP addresses to be assigned to the above interface.
31432 @item @code{port} (default: @code{51820})
31433 The port on which to listen for incoming connections.
31435 @item @code{dns} (default: @code{#f})
31436 The DNS server(s) to announce to VPN clients via DHCP.
31438 @item @code{private-key} (default: @code{"/etc/wireguard/private.key"})
31439 The private key file for the interface. It is automatically generated if
31440 the file does not exist.
31442 @item @code{peers} (default: @code{'()})
31443 The authorized peers on this interface. This is a list of
31444 @var{wireguard-peer} records.
31446 @item @code{pre-up} (default: @code{'()})
31447 The script commands to be run before setting up the interface.
31449 @item @code{post-up} (default: @code{'()})
31450 The script commands to be run after setting up the interface.
31452 @item @code{pre-down} (default: @code{'()})
31453 The script commands to be run before tearing down the interface.
31455 @item @code{post-down} (default: @code{'()})
31456 The script commands to be run after tearing down the interface.
31458 @item @code{table} (default: @code{"auto"})
31459 The routing table to which routes are added, as a string. There are two
31460 special values: @code{"off"} that disables the creation of routes
31461 altogether, and @code{"auto"} (the default) that adds routes to the
31462 default table and enables special handling of default routes.
31467 @deftp {Data Type} wireguard-peer
31468 Data type representing a Wireguard peer attached to a given interface.
31474 @item @code{endpoint} (default: @code{#f})
31475 The optional endpoint for the peer, such as
31476 @code{"demo.wireguard.com:51820"}.
31478 @item @code{public-key}
31479 The peer public-key represented as a base64 string.
31481 @item @code{allowed-ips}
31482 A list of IP addresses from which incoming traffic for this peer is
31483 allowed and to which incoming traffic for this peer is directed.
31485 @item @code{keep-alive} (default: @code{#f})
31486 An optional time interval in seconds. A packet will be sent to the
31487 server endpoint once per time interval. This helps receiving
31488 incoming connections from this peer when you are behind a NAT or
31494 @node Network File System
31495 @subsection Network File System
31498 The @code{(gnu services nfs)} module provides the following services,
31499 which are most commonly used in relation to mounting or exporting
31500 directory trees as @dfn{network file systems} (NFS).
31502 While it is possible to use the individual components that together make
31503 up a Network File System service, we recommended to configure an NFS
31504 server with the @code{nfs-service-type}.
31506 @subsubheading NFS Service
31507 @cindex NFS, server
31509 The NFS service takes care of setting up all NFS component services,
31510 kernel configuration file systems, and installs configuration files in
31511 the locations that NFS expects.
31513 @defvr {Scheme Variable} nfs-service-type
31514 A service type for a complete NFS server.
31517 @deftp {Data Type} nfs-configuration
31518 This data type represents the configuration of the NFS service and all
31521 It has the following parameters:
31523 @item @code{nfs-utils} (default: @code{nfs-utils})
31524 The nfs-utils package to use.
31526 @item @code{nfs-versions} (default: @code{'("4.2" "4.1" "4.0")})
31527 If a list of string values is provided, the @command{rpc.nfsd} daemon
31528 will be limited to supporting the given versions of the NFS protocol.
31530 @item @code{exports} (default: @code{'()})
31531 This is a list of directories the NFS server should export. Each entry
31532 is a list consisting of two elements: a directory name and a string
31533 containing all options. This is an example in which the directory
31534 @file{/export} is served to all NFS clients as a read-only share:
31540 "*(ro,insecure,no_subtree_check,crossmnt,fsid=0)"))))
31543 @item @code{rpcmountd-port} (default: @code{#f})
31544 The network port that the @command{rpc.mountd} daemon should use.
31546 @item @code{rpcstatd-port} (default: @code{#f})
31547 The network port that the @command{rpc.statd} daemon should use.
31549 @item @code{rpcbind} (default: @code{rpcbind})
31550 The rpcbind package to use.
31552 @item @code{idmap-domain} (default: @code{"localdomain"})
31553 The local NFSv4 domain name.
31555 @item @code{nfsd-port} (default: @code{2049})
31556 The network port that the @command{nfsd} daemon should use.
31558 @item @code{nfsd-threads} (default: @code{8})
31559 The number of threads used by the @command{nfsd} daemon.
31561 @item @code{nfsd-tcp?} (default: @code{#t})
31562 Whether the @command{nfsd} daemon should listen on a TCP socket.
31564 @item @code{nfsd-udp?} (default: @code{#f})
31565 Whether the @command{nfsd} daemon should listen on a UDP socket.
31567 @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
31568 The directory where the pipefs file system is mounted.
31570 @item @code{debug} (default: @code{'()"})
31571 A list of subsystems for which debugging output should be enabled. This
31572 is a list of symbols. Any of these symbols are valid: @code{nfsd},
31573 @code{nfs}, @code{rpc}, @code{idmap}, @code{statd}, or @code{mountd}.
31577 If you don't need a complete NFS service or prefer to build it yourself
31578 you can use the individual component services that are documented below.
31580 @subsubheading RPC Bind Service
31583 The RPC Bind service provides a facility to map program numbers into
31584 universal addresses.
31585 Many NFS related services use this facility. Hence it is automatically
31586 started when a dependent service starts.
31588 @defvr {Scheme Variable} rpcbind-service-type
31589 A service type for the RPC portmapper daemon.
31593 @deftp {Data Type} rpcbind-configuration
31594 Data type representing the configuration of the RPC Bind Service.
31595 This type has the following parameters:
31597 @item @code{rpcbind} (default: @code{rpcbind})
31598 The rpcbind package to use.
31600 @item @code{warm-start?} (default: @code{#t})
31601 If this parameter is @code{#t}, then the daemon will read a
31602 state file on startup thus reloading state information saved by a previous
31608 @subsubheading Pipefs Pseudo File System
31612 The pipefs file system is used to transfer NFS related data
31613 between the kernel and user space programs.
31615 @defvr {Scheme Variable} pipefs-service-type
31616 A service type for the pipefs pseudo file system.
31619 @deftp {Data Type} pipefs-configuration
31620 Data type representing the configuration of the pipefs pseudo file system service.
31621 This type has the following parameters:
31623 @item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
31624 The directory to which the file system is to be attached.
31629 @subsubheading GSS Daemon Service
31632 @cindex global security system
31634 The @dfn{global security system} (GSS) daemon provides strong security for RPC
31636 Before exchanging RPC requests an RPC client must establish a security
31637 context. Typically this is done using the Kerberos command @command{kinit}
31638 or automatically at login time using PAM services (@pxref{Kerberos Services}).
31640 @defvr {Scheme Variable} gss-service-type
31641 A service type for the Global Security System (GSS) daemon.
31644 @deftp {Data Type} gss-configuration
31645 Data type representing the configuration of the GSS daemon service.
31646 This type has the following parameters:
31648 @item @code{nfs-utils} (default: @code{nfs-utils})
31649 The package in which the @command{rpc.gssd} command is to be found.
31651 @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
31652 The directory where the pipefs file system is mounted.
31658 @subsubheading IDMAP Daemon Service
31660 @cindex name mapper
31662 The idmap daemon service provides mapping between user IDs and user names.
31663 Typically it is required in order to access file systems mounted via NFSv4.
31665 @defvr {Scheme Variable} idmap-service-type
31666 A service type for the Identity Mapper (IDMAP) daemon.
31669 @deftp {Data Type} idmap-configuration
31670 Data type representing the configuration of the IDMAP daemon service.
31671 This type has the following parameters:
31673 @item @code{nfs-utils} (default: @code{nfs-utils})
31674 The package in which the @command{rpc.idmapd} command is to be found.
31676 @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
31677 The directory where the pipefs file system is mounted.
31679 @item @code{domain} (default: @code{#f})
31680 The local NFSv4 domain name.
31681 This must be a string or @code{#f}.
31682 If it is @code{#f} then the daemon will use the host's fully qualified domain name.
31684 @item @code{verbosity} (default: @code{0})
31685 The verbosity level of the daemon.
31690 @node Samba Services, Continuous Integration, Network File System, Services
31691 @subsection Samba Services
31695 The @code{(gnu services samba)} module provides service definitions for
31696 Samba as well as additional helper services. Currently it provides the
31697 following services.
31699 @subsubheading Samba
31701 @uref{https://www.samba.org, Samba} provides network shares for folders
31702 and printers using the SMB/CIFS protocol commonly used on Windows. It
31703 can also act as an Active Directory Domain Controller (AD DC) for other
31704 hosts in an heterougenious network with different types of Computer
31707 @defvar {Scheme variable} samba-service-type
31709 The service type to enable the samba services @code{samba}, @code{nmbd},
31710 @code{smbd} and @code{winbindd}. By default this service type does not
31711 run any of the Samba daemons; they must be enabled individually.
31713 Below is a basic example that configures a simple, anonymous
31714 (unauthenticated) Samba file share exposing the @file{/public}
31718 The @file{/public} directory and its contents must be world
31719 readable/writable, so you'll want to run @samp{chmod -R 777 /public} on
31724 Such a Samba configuration should only be used in controlled
31725 environments, and you should not share any private files using it, as
31726 anyone connecting to your network would be able to access them.
31730 (service samba-service-type (samba-configuration
31732 (config-file (plain-file "smb.conf" "\
31734 map to guest = Bad User
31735 logging = syslog@@1
31742 guest only = yes\n"))))
31747 @deftp{Data Type} samba-service-configuration
31748 Configuration record for the Samba suite.
31751 @item @code{package} (default: @code{samba})
31752 The samba package to use.
31754 @item @code{config-file} (default: @code{#f})
31755 The config file to use. To learn about its syntax, run @samp{man
31758 @item @code{enable-samba?} (default: @code{#f})
31759 Enable the @code{samba} daemon.
31761 @item @code{enable-smbd?} (default: @code{#f})
31762 Enable the @code{smbd} daemon.
31764 @item @code{enable-nmbd?} (default: @code{#f})
31765 Enable the @code{nmbd} daemon.
31767 @item @code{enable-winbindd?} (default: @code{#f})
31768 Enable the @code{winbindd} daemon.
31773 @cindex wsdd, Web service discovery daemon
31774 @subsubheading Web Service Discovery Daemon
31776 The @acronym{WSDD, Web Service Discovery daemon} implements the
31777 @uref{http://docs.oasis-open.org/ws-dd/discovery/1.1/os/wsdd-discovery-1.1-spec-os.html,
31778 Web Services Dynamic Discovery} protocol that enables host discovery
31779 over Multicast DNS, similar to what Avahi does. It is a drop-in
31780 replacement for SMB hosts that have had SMBv1 disabled for security
31783 @defvr {Scheme Variable} wsdd-service-type
31784 Service type for the WSD host daemon. The value for
31785 this service type is a @code{wsdd-configuration} record. The details
31786 for the @code{wsdd-configuration} record type are given below.
31789 @deftp {Data Type} wsdd-configuration
31790 This data type represents the configuration for the wsdd service.
31794 @item @code{package} (default: @code{wsdd})
31795 The wsdd package to use.
31797 @item @code{ipv4only?} (default: @code{#f})
31798 Only listen to IPv4 addresses.
31800 @item @code{ipv6only} (default: @code{#f})
31801 Only listen to IPv6 addresses. Please note: Activating both options is
31802 not possible, since there would be no IP versions to listen to.
31804 @item @code{chroot} (default: @code{#f})
31805 Chroot into a separate directory to prevent access to other directories.
31806 This is to increase security in case there is a vulnerability in
31809 @item @code{hop-limit} (default: @code{1})
31810 Limit to the level of hops for multicast packets. The default is
31811 @var{1} which should prevent packets from leaving the local network.
31813 @item @code{interface} (default: @code{'()})
31814 Limit to the given list of interfaces to listen to. By default wsdd
31815 will listen to all interfaces. Except the loopback interface is never
31818 @item @code{uuid-device} (default: @code{#f})
31819 The WSD protocol requires a device to have a UUID. Set this to manually
31820 assign the service a UUID.
31822 @item @code{domain} (default: @code{#f})
31823 Notify this host is a member of an Active Directory.
31825 @item @code{host-name} (default: @code{#f})
31826 Manually set the hostname rather than letting @command{wsdd} inherit
31827 this host's hostname. Only the host name part of a possible FQDN will
31828 be used in the default case.
31830 @item @code{preserve-case?} (default: @code{#f})
31831 By default @command{wsdd} will convert the hostname in workgroup to all
31832 uppercase. The opposite is true for hostnames in domains. Setting this
31833 parameter will preserve case.
31835 @item @code{workgroup} (default: @var{"WORKGROUP"})
31836 Change the name of the workgroup. By default @command{wsdd} reports
31837 this host being member of a workgroup.
31842 @node Continuous Integration
31843 @subsection Continuous Integration
31845 @cindex continuous integration
31846 @uref{https://guix.gnu.org/cuirass/, Cuirass} is a continuous
31847 integration tool for Guix. It can be used both for development and for
31848 providing substitutes to others (@pxref{Substitutes}).
31850 The @code{(gnu services cuirass)} module provides the following service.
31852 @defvr {Scheme Procedure} cuirass-service-type
31853 The type of the Cuirass service. Its value must be a
31854 @code{cuirass-configuration} object, as described below.
31857 To add build jobs, you have to set the @code{specifications} field of
31858 the configuration. For instance, the following example will build all
31859 the packages provided by the @code{my-channel} channel.
31862 (define %cuirass-specs
31863 #~(list (specification
31864 (name "my-channel")
31865 (build '(channels my-channel))
31869 (url "https://my-channel.git"))
31870 %default-channels)))))
31872 (service cuirass-service-type
31873 (cuirass-configuration
31874 (specifications %cuirass-specs)))
31877 To build the @code{linux-libre} package defined by the default Guix
31878 channel, one can use the following configuration.
31881 (define %cuirass-specs
31882 #~(list (specification
31884 (build '(packages "linux-libre")))))
31886 (service cuirass-service-type
31887 (cuirass-configuration
31888 (specifications %cuirass-specs)))
31891 The other configuration possibilities, as well as the specification
31892 record itself are described in the Cuirass manual
31893 (@pxref{Specifications,,, cuirass, Cuirass}).
31895 While information related to build jobs is located directly in the
31896 specifications, global settings for the @command{cuirass} process are
31897 accessible in other @code{cuirass-configuration} fields.
31899 @deftp {Data Type} cuirass-configuration
31900 Data type representing the configuration of Cuirass.
31903 @item @code{cuirass} (default: @code{cuirass})
31904 The Cuirass package to use.
31906 @item @code{log-file} (default: @code{"/var/log/cuirass.log"})
31907 Location of the log file.
31909 @item @code{web-log-file} (default: @code{"/var/log/cuirass-web.log"})
31910 Location of the log file used by the web interface.
31912 @item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
31913 Location of the repository cache.
31915 @item @code{user} (default: @code{"cuirass"})
31916 Owner of the @code{cuirass} process.
31918 @item @code{group} (default: @code{"cuirass"})
31919 Owner's group of the @code{cuirass} process.
31921 @item @code{interval} (default: @code{60})
31922 Number of seconds between the poll of the repositories followed by the
31925 @item @code{parameters} (default: @code{#f})
31926 Read parameters from the given @var{parameters} file. The supported
31927 parameters are described here (@pxref{Parameters,,, cuirass, Cuirass}).
31929 @item @code{remote-server} (default: @code{#f})
31930 A @code{cuirass-remote-server-configuration} record to use the build
31931 remote mechanism or @code{#f} to use the default build mechanism.
31933 @item @code{database} (default: @code{"dbname=cuirass host=/var/run/postgresql"})
31934 Use @var{database} as the database containing the jobs and the past
31935 build results. Since Cuirass uses PostgreSQL as a database engine,
31936 @var{database} must be a string such as @code{"dbname=cuirass
31939 @item @code{port} (default: @code{8081})
31940 Port number used by the HTTP server.
31942 @item @code{host} (default: @code{"localhost"})
31943 Listen on the network interface for @var{host}. The default is to
31944 accept connections from localhost.
31946 @item @code{specifications} (default: @code{#~'()})
31947 A gexp (@pxref{G-Expressions}) that evaluates to a list of
31948 specifications records. The specification record is described in the
31949 Cuirass manual (@pxref{Specifications,,, cuirass, Cuirass}).
31951 @item @code{use-substitutes?} (default: @code{#f})
31952 This allows using substitutes to avoid building every dependencies of a job
31955 @item @code{one-shot?} (default: @code{#f})
31956 Only evaluate specifications and build derivations once.
31958 @item @code{fallback?} (default: @code{#f})
31959 When substituting a pre-built binary fails, fall back to building
31962 @item @code{extra-options} (default: @code{'()})
31963 Extra options to pass when running the Cuirass processes.
31968 @cindex remote build
31969 @subsubheading Cuirass remote building
31971 Cuirass supports two mechanisms to build derivations.
31974 @item Using the local Guix daemon.
31975 This is the default build mechanism. Once the build jobs are
31976 evaluated, they are sent to the local Guix daemon. Cuirass then
31977 listens to the Guix daemon output to detect the various build events.
31979 @item Using the remote build mechanism.
31980 The build jobs are not submitted to the local Guix daemon. Instead, a
31981 remote server dispatches build requests to the connect remote workers,
31982 according to the build priorities.
31986 To enable this build mode a @code{cuirass-remote-server-configuration}
31987 record must be passed as @code{remote-server} argument of the
31988 @code{cuirass-configuration} record. The
31989 @code{cuirass-remote-server-configuration} record is described below.
31991 This build mode scales way better than the default build mode. This is
31992 the build mode that is used on the GNU Guix build farm at
31993 @url{https://ci.guix.gnu.org}. It should be preferred when using
31994 Cuirass to build large amount of packages.
31996 @deftp {Data Type} cuirass-remote-server-configuration
31997 Data type representing the configuration of the Cuirass remote-server.
32000 @item @code{backend-port} (default: @code{5555})
32001 The TCP port for communicating with @code{remote-worker} processes
32002 using ZMQ. It defaults to @code{5555}.
32004 @item @code{log-port} (default: @code{5556})
32005 The TCP port of the log server. It defaults to @code{5556}.
32007 @item @code{publish-port} (default: @code{5557})
32008 The TCP port of the publish server. It defaults to @code{5557}.
32010 @item @code{log-file} (default: @code{"/var/log/cuirass-remote-server.log"})
32011 Location of the log file.
32013 @item @code{cache} (default: @code{"/var/cache/cuirass/remote"})
32014 Use @var{cache} directory to cache build log files.
32016 @item @code{trigger-url} (default: @code{#f})
32017 Once a substitute is successfully fetched, trigger substitute baking at
32020 @item @code{publish?} (default: @code{#t})
32021 If set to false, do not start a publish server and ignore the
32022 @code{publish-port} argument. This can be useful if there is already a
32023 standalone publish server standing next to the remote server.
32025 @item @code{public-key}
32026 @item @code{private-key}
32027 Use the specific @var{file}s as the public/private key pair used to sign
32028 the store items being published.
32033 At least one remote worker must also be started on any machine of the
32034 local network to actually perform the builds and report their status.
32036 @deftp {Data Type} cuirass-remote-worker-configuration
32037 Data type representing the configuration of the Cuirass remote-worker.
32040 @item @code{cuirass} (default: @code{cuirass})
32041 The Cuirass package to use.
32043 @item @code{workers} (default: @code{1})
32044 Start @var{workers} parallel workers.
32046 @item @code{server} (default: @code{#f})
32047 Do not use Avahi discovery and connect to the given @code{server} IP
32050 @item @code{systems} (default: @code{(list (%current-system))})
32051 Only request builds for the given @var{systems}.
32053 @item @code{log-file} (default: @code{"/var/log/cuirass-remote-worker.log"})
32054 Location of the log file.
32056 @item @code{publish-port} (default: @code{5558})
32057 The TCP port of the publish server. It defaults to @code{5558}.
32059 @item @code{substitute-urls} (default: @code{%default-substitute-urls})
32060 The list of URLs where to look for substitutes by default.
32062 @item @code{public-key}
32063 @item @code{private-key}
32064 Use the specific @var{file}s as the public/private key pair used to sign
32065 the store items being published.
32070 @subsubheading Laminar
32072 @uref{https://laminar.ohwg.net/, Laminar} is a lightweight and modular
32073 Continuous Integration service. It doesn't have a configuration web UI
32074 instead uses version-controllable configuration files and scripts.
32076 Laminar encourages the use of existing tools such as bash and cron
32077 instead of reinventing them.
32079 @defvr {Scheme Procedure} laminar-service-type
32080 The type of the Laminar service. Its value must be a
32081 @code{laminar-configuration} object, as described below.
32083 All configuration values have defaults, a minimal configuration to get
32084 Laminar running is shown below. By default, the web interface is
32085 available on port 8080.
32088 (service laminar-service-type)
32092 @deftp {Data Type} laminar-configuration
32093 Data type representing the configuration of Laminar.
32096 @item @code{laminar} (default: @code{laminar})
32097 The Laminar package to use.
32099 @item @code{home-directory} (default: @code{"/var/lib/laminar"})
32100 The directory for job configurations and run directories.
32102 @item @code{bind-http} (default: @code{"*:8080"})
32103 The interface/port or unix socket on which laminard should listen for
32104 incoming connections to the web frontend.
32106 @item @code{bind-rpc} (default: @code{"unix-abstract:laminar"})
32107 The interface/port or unix socket on which laminard should listen for
32108 incoming commands such as build triggers.
32110 @item @code{title} (default: @code{"Laminar"})
32111 The page title to show in the web frontend.
32113 @item @code{keep-rundirs} (default: @code{0})
32114 Set to an integer defining how many rundirs to keep per job. The
32115 lowest-numbered ones will be deleted. The default is 0, meaning all run
32116 dirs will be immediately deleted.
32118 @item @code{archive-url} (default: @code{#f})
32119 The web frontend served by laminard will use this URL to form links to
32120 artefacts archived jobs.
32122 @item @code{base-url} (default: @code{#f})
32123 Base URL to use for links to laminar itself.
32128 @node Power Management Services
32129 @subsection Power Management Services
32132 @cindex power management with TLP
32133 @subsubheading TLP daemon
32135 The @code{(gnu services pm)} module provides a Guix service definition
32136 for the Linux power management tool TLP.
32138 TLP enables various powersaving modes in userspace and kernel.
32139 Contrary to @code{upower-service}, it is not a passive,
32140 monitoring tool, as it will apply custom settings each time a new power
32141 source is detected. More information can be found at
32142 @uref{https://linrunner.de/en/tlp/tlp.html, TLP home page}.
32144 @deffn {Scheme Variable} tlp-service-type
32145 The service type for the TLP tool. The default settings are optimised
32146 for battery life on most systems, but you can tweak them to your heart's
32147 content by adding a valid @code{tlp-configuration}:
32149 (service tlp-service-type
32151 (cpu-scaling-governor-on-ac (list "performance"))
32152 (sched-powersave-on-bat? #t)))
32156 Each parameter definition is preceded by its type; for example,
32157 @samp{boolean foo} indicates that the @code{foo} parameter should be
32158 specified as a boolean. Types starting with @code{maybe-} denote
32159 parameters that won't show up in TLP config file when their value is
32160 left unset, or is explicitly set to the @code{%unset-value} value.
32162 @c The following documentation was initially generated by
32163 @c (generate-tlp-documentation) in (gnu services pm). Manually maintained
32164 @c documentation is better, so we shouldn't hesitate to edit below as
32165 @c needed. However if the change you want to make to this documentation
32166 @c can be done in an automated way, it's probably easier to change
32167 @c (generate-documentation) than to make it below and have to deal with
32168 @c the churn as TLP updates.
32170 Available @code{tlp-configuration} fields are:
32172 @deftypevr {@code{tlp-configuration} parameter} package tlp
32177 @deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable?
32178 Set to true if you wish to enable TLP.
32180 Defaults to @samp{#t}.
32184 @deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode
32185 Default mode when no power supply can be detected. Alternatives are AC
32188 Defaults to @samp{"AC"}.
32192 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac
32193 Number of seconds Linux kernel has to wait after the disk goes idle,
32194 before syncing on AC.
32196 Defaults to @samp{0}.
32200 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat
32201 Same as @code{disk-idle-ac} but on BAT mode.
32203 Defaults to @samp{2}.
32207 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac
32208 Dirty pages flushing periodicity, expressed in seconds.
32210 Defaults to @samp{15}.
32214 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat
32215 Same as @code{max-lost-work-secs-on-ac} but on BAT mode.
32217 Defaults to @samp{60}.
32221 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac
32222 CPU frequency scaling governor on AC mode. With intel_pstate driver,
32223 alternatives are powersave and performance. With acpi-cpufreq driver,
32224 alternatives are ondemand, powersave, performance and conservative.
32226 Defaults to @samp{disabled}.
32230 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat
32231 Same as @code{cpu-scaling-governor-on-ac} but on BAT mode.
32233 Defaults to @samp{disabled}.
32237 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac
32238 Set the min available frequency for the scaling governor on AC.
32240 Defaults to @samp{disabled}.
32244 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac
32245 Set the max available frequency for the scaling governor on AC.
32247 Defaults to @samp{disabled}.
32251 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat
32252 Set the min available frequency for the scaling governor on BAT.
32254 Defaults to @samp{disabled}.
32258 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat
32259 Set the max available frequency for the scaling governor on BAT.
32261 Defaults to @samp{disabled}.
32265 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac
32266 Limit the min P-state to control the power dissipation of the CPU, in AC
32267 mode. Values are stated as a percentage of the available performance.
32269 Defaults to @samp{disabled}.
32273 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac
32274 Limit the max P-state to control the power dissipation of the CPU, in AC
32275 mode. Values are stated as a percentage of the available performance.
32277 Defaults to @samp{disabled}.
32281 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat
32282 Same as @code{cpu-min-perf-on-ac} on BAT mode.
32284 Defaults to @samp{disabled}.
32288 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat
32289 Same as @code{cpu-max-perf-on-ac} on BAT mode.
32291 Defaults to @samp{disabled}.
32295 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac?
32296 Enable CPU turbo boost feature on AC mode.
32298 Defaults to @samp{disabled}.
32302 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat?
32303 Same as @code{cpu-boost-on-ac?} on BAT mode.
32305 Defaults to @samp{disabled}.
32309 @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac?
32310 Allow Linux kernel to minimize the number of CPU cores/hyper-threads
32311 used under light load conditions.
32313 Defaults to @samp{#f}.
32317 @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat?
32318 Same as @code{sched-powersave-on-ac?} but on BAT mode.
32320 Defaults to @samp{#t}.
32324 @deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog?
32325 Enable Linux kernel NMI watchdog.
32327 Defaults to @samp{#f}.
32331 @deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls
32332 For Linux kernels with PHC patch applied, change CPU voltages. An
32333 example value would be @samp{"F:V F:V F:V F:V"}.
32335 Defaults to @samp{disabled}.
32339 @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac
32340 Set CPU performance versus energy saving policy on AC@. Alternatives are
32341 performance, normal, powersave.
32343 Defaults to @samp{"performance"}.
32347 @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat
32348 Same as @code{energy-perf-policy-ac} but on BAT mode.
32350 Defaults to @samp{"powersave"}.
32354 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices
32359 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac
32360 Hard disk advanced power management level.
32364 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat
32365 Same as @code{disk-apm-bat} but on BAT mode.
32369 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac
32370 Hard disk spin down timeout. One value has to be specified for each
32371 declared hard disk.
32373 Defaults to @samp{disabled}.
32377 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat
32378 Same as @code{disk-spindown-timeout-on-ac} but on BAT mode.
32380 Defaults to @samp{disabled}.
32384 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched
32385 Select IO scheduler for disk devices. One value has to be specified for
32386 each declared hard disk. Example alternatives are cfq, deadline and
32389 Defaults to @samp{disabled}.
32393 @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac
32394 SATA aggressive link power management (ALPM) level. Alternatives are
32395 min_power, medium_power, max_performance.
32397 Defaults to @samp{"max_performance"}.
32401 @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat
32402 Same as @code{sata-linkpwr-ac} but on BAT mode.
32404 Defaults to @samp{"min_power"}.
32408 @deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist
32409 Exclude specified SATA host devices for link power management.
32411 Defaults to @samp{disabled}.
32415 @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac?
32416 Enable Runtime Power Management for AHCI controller and disks on AC
32419 Defaults to @samp{disabled}.
32423 @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat?
32424 Same as @code{ahci-runtime-pm-on-ac} on BAT mode.
32426 Defaults to @samp{disabled}.
32430 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout
32431 Seconds of inactivity before disk is suspended.
32433 Defaults to @samp{15}.
32437 @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac
32438 PCI Express Active State Power Management level. Alternatives are
32439 default, performance, powersave.
32441 Defaults to @samp{"performance"}.
32445 @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat
32446 Same as @code{pcie-aspm-ac} but on BAT mode.
32448 Defaults to @samp{"powersave"}.
32452 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat0
32453 Percentage when battery 0 should begin charging. Only supported on some laptops.
32455 Defaults to @samp{disabled}.
32459 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat0
32460 Percentage when battery 0 should stop charging. Only supported on some laptops.
32462 Defaults to @samp{disabled}.
32466 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer start-charge-thresh-bat1
32467 Percentage when battery 1 should begin charging. Only supported on some laptops.
32469 Defaults to @samp{disabled}.
32473 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer stop-charge-thresh-bat1
32474 Percentage when battery 1 should stop charging. Only supported on some laptops.
32476 Defaults to @samp{disabled}.
32480 @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac
32481 Radeon graphics clock speed level. Alternatives are low, mid, high,
32484 Defaults to @samp{"high"}.
32488 @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat
32489 Same as @code{radeon-power-ac} but on BAT mode.
32491 Defaults to @samp{"low"}.
32495 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac
32496 Radeon dynamic power management method (DPM). Alternatives are battery,
32499 Defaults to @samp{"performance"}.
32503 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat
32504 Same as @code{radeon-dpm-state-ac} but on BAT mode.
32506 Defaults to @samp{"battery"}.
32510 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac
32511 Radeon DPM performance level. Alternatives are auto, low, high.
32513 Defaults to @samp{"auto"}.
32517 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat
32518 Same as @code{radeon-dpm-perf-ac} but on BAT mode.
32520 Defaults to @samp{"auto"}.
32524 @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac?
32525 Wifi power saving mode.
32527 Defaults to @samp{#f}.
32531 @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat?
32532 Same as @code{wifi-power-ac?} but on BAT mode.
32534 Defaults to @samp{#t}.
32538 @deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable?
32539 Disable wake on LAN.
32541 Defaults to @samp{#t}.
32545 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac
32546 Timeout duration in seconds before activating audio power saving on
32547 Intel HDA and AC97 devices. A value of 0 disables power saving.
32549 Defaults to @samp{0}.
32553 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat
32554 Same as @code{sound-powersave-ac} but on BAT mode.
32556 Defaults to @samp{1}.
32560 @deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller?
32561 Disable controller in powersaving mode on Intel HDA devices.
32563 Defaults to @samp{#t}.
32567 @deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat?
32568 Enable optical drive in UltraBay/MediaBay on BAT mode. Drive can be
32569 powered on again by releasing (and reinserting) the eject lever or by
32570 pressing the disc eject button on newer models.
32572 Defaults to @samp{#f}.
32576 @deftypevr {@code{tlp-configuration} parameter} string bay-device
32577 Name of the optical drive device to power off.
32579 Defaults to @samp{"sr0"}.
32583 @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac
32584 Runtime Power Management for PCI(e) bus devices. Alternatives are on
32587 Defaults to @samp{"on"}.
32591 @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat
32592 Same as @code{runtime-pm-ac} but on BAT mode.
32594 Defaults to @samp{"auto"}.
32598 @deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all?
32599 Runtime Power Management for all PCI(e) bus devices, except blacklisted
32602 Defaults to @samp{#t}.
32606 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist
32607 Exclude specified PCI(e) device addresses from Runtime Power Management.
32609 Defaults to @samp{disabled}.
32613 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist
32614 Exclude PCI(e) devices assigned to the specified drivers from Runtime
32619 @deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend?
32620 Enable USB autosuspend feature.
32622 Defaults to @samp{#t}.
32626 @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist
32627 Exclude specified devices from USB autosuspend.
32629 Defaults to @samp{disabled}.
32633 @deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan?
32634 Exclude WWAN devices from USB autosuspend.
32636 Defaults to @samp{#t}.
32640 @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist
32641 Include specified devices into USB autosuspend, even if they are already
32642 excluded by the driver or via @code{usb-blacklist-wwan?}.
32644 Defaults to @samp{disabled}.
32648 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown?
32649 Enable USB autosuspend before shutdown.
32651 Defaults to @samp{disabled}.
32655 @deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup?
32656 Restore radio device state (bluetooth, wifi, wwan) from previous
32657 shutdown on system startup.
32659 Defaults to @samp{#f}.
32664 @cindex CPU frequency scaling with thermald
32665 @subsubheading Thermald daemon
32667 The @code{(gnu services pm)} module provides an interface to
32668 thermald, a CPU frequency scaling service which helps prevent overheating.
32670 @defvr {Scheme Variable} thermald-service-type
32671 This is the service type for
32672 @uref{https://01.org/linux-thermal-daemon/, thermald}, the Linux
32673 Thermal Daemon, which is responsible for controlling the thermal state
32674 of processors and preventing overheating.
32677 @deftp {Data Type} thermald-configuration
32678 Data type representing the configuration of @code{thermald-service-type}.
32681 @item @code{adaptive?} (default: @code{#f})
32682 Use @acronym{DPTF, Dynamic Power and Thermal Framework} adaptive tables
32685 @item @code{ignore-cpuid-check?} (default: @code{#f})
32686 Ignore cpuid check for supported CPU models.
32688 @item @code{thermald} (default: @var{thermald})
32689 Package object of thermald.
32694 @node Audio Services
32695 @subsection Audio Services
32697 The @code{(gnu services audio)} module provides a service to start MPD
32698 (the Music Player Daemon).
32701 @subsubheading Music Player Daemon
32703 The Music Player Daemon (MPD) is a service that can play music while
32704 being controlled from the local machine or over the network by a variety
32707 The following example shows how one might run @code{mpd} as user
32708 @code{"bob"} on port @code{6666}. It uses pulseaudio for output.
32711 (service mpd-service-type
32717 @defvr {Scheme Variable} mpd-service-type
32718 The service type for @command{mpd}
32721 @deftp {Data Type} mpd-configuration
32722 Data type representing the configuration of @command{mpd}.
32725 @item @code{user} (default: @code{"mpd"})
32726 The user to run mpd as.
32728 @item @code{music-dir} (default: @code{"~/Music"})
32729 The directory to scan for music files.
32731 @item @code{playlist-dir} (default: @code{"~/.mpd/playlists"})
32732 The directory to store playlists.
32734 @item @code{db-file} (default: @code{"~/.mpd/tag_cache"})
32735 The location of the music database.
32737 @item @code{state-file} (default: @code{"~/.mpd/state"})
32738 The location of the file that stores current MPD's state.
32740 @item @code{sticker-file} (default: @code{"~/.mpd/sticker.sql"})
32741 The location of the sticker database.
32743 @item @code{port} (default: @code{"6600"})
32744 The port to run mpd on.
32746 @item @code{address} (default: @code{"any"})
32747 The address that mpd will bind to. To use a Unix domain socket,
32748 an absolute path can be specified here.
32750 @item @code{outputs} (default: @code{"(list (mpd-output))"})
32751 The audio outputs that MPD can use. By default this is a single output using pulseaudio.
32756 @deftp {Data Type} mpd-output
32757 Data type representing an @command{mpd} audio output.
32760 @item @code{name} (default: @code{"MPD"})
32761 The name of the audio output.
32763 @item @code{type} (default: @code{"pulse"})
32764 The type of audio output.
32766 @item @code{enabled?} (default: @code{#t})
32767 Specifies whether this audio output is enabled when MPD is started. By
32768 default, all audio outputs are enabled. This is just the default
32769 setting when there is no state file; with a state file, the previous
32772 @item @code{tags?} (default: @code{#t})
32773 If set to @code{#f}, then MPD will not send tags to this output. This
32774 is only useful for output plugins that can receive tags, for example the
32775 @code{httpd} output plugin.
32777 @item @code{always-on?} (default: @code{#f})
32778 If set to @code{#t}, then MPD attempts to keep this audio output always
32779 open. This may be useful for streaming servers, when you don’t want to
32780 disconnect all listeners even when playback is accidentally stopped.
32782 @item @code{mixer-type}
32783 This field accepts a symbol that specifies which mixer should be used
32784 for this audio output: the @code{hardware} mixer, the @code{software}
32785 mixer, the @code{null} mixer (allows setting the volume, but with no
32786 effect; this can be used as a trick to implement an external mixer
32787 External Mixer) or no mixer (@code{none}).
32789 @item @code{extra-options} (default: @code{'()})
32790 An association list of option symbols to string values to be appended to
32791 the audio output configuration.
32796 The following example shows a configuration of @code{mpd} that provides
32797 an HTTP audio streaming output.
32800 (service mpd-service-type
32808 `((encoder . "vorbis")
32809 (port . "8080"))))))))
32813 @node Virtualization Services
32814 @subsection Virtualization Services
32816 The @code{(gnu services virtualization)} module provides services for
32817 the libvirt and virtlog daemons, as well as other virtualization-related
32820 @subsubheading Libvirt daemon
32822 @code{libvirtd} is the server side daemon component of the libvirt
32823 virtualization management system. This daemon runs on host servers
32824 and performs required management tasks for virtualized guests.
32826 @deffn {Scheme Variable} libvirt-service-type
32827 This is the type of the @uref{https://libvirt.org, libvirt daemon}.
32828 Its value must be a @code{libvirt-configuration}.
32831 (service libvirt-service-type
32832 (libvirt-configuration
32833 (unix-sock-group "libvirt")
32834 (tls-port "16555")))
32838 @c Auto-generated with (generate-libvirt-documentation)
32839 Available @code{libvirt-configuration} fields are:
32841 @deftypevr {@code{libvirt-configuration} parameter} package libvirt
32846 @deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls?
32847 Flag listening for secure TLS connections on the public TCP/IP port.
32848 You must set @code{listen} for this to have any effect.
32850 It is necessary to setup a CA and issue server certificates before using
32853 Defaults to @samp{#t}.
32857 @deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp?
32858 Listen for unencrypted TCP connections on the public TCP/IP port. You must
32859 set @code{listen} for this to have any effect.
32861 Using the TCP socket requires SASL authentication by default. Only SASL
32862 mechanisms which support data encryption are allowed. This is
32863 DIGEST_MD5 and GSSAPI (Kerberos5).
32865 Defaults to @samp{#f}.
32869 @deftypevr {@code{libvirt-configuration} parameter} string tls-port
32870 Port for accepting secure TLS connections. This can be a port number,
32873 Defaults to @samp{"16514"}.
32877 @deftypevr {@code{libvirt-configuration} parameter} string tcp-port
32878 Port for accepting insecure TCP connections. This can be a port number,
32881 Defaults to @samp{"16509"}.
32885 @deftypevr {@code{libvirt-configuration} parameter} string listen-addr
32886 IP address or hostname used for client connections.
32888 Defaults to @samp{"0.0.0.0"}.
32892 @deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv?
32893 Flag toggling mDNS advertisement of the libvirt service.
32895 Alternatively can disable for all services on a host by stopping the
32898 Defaults to @samp{#f}.
32902 @deftypevr {@code{libvirt-configuration} parameter} string mdns-name
32903 Default mDNS advertisement name. This must be unique on the immediate
32906 Defaults to @samp{"Virtualization Host <hostname>"}.
32910 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group
32911 UNIX domain socket group ownership. This can be used to allow a
32912 'trusted' set of users access to management capabilities without
32915 Defaults to @samp{"root"}.
32919 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms
32920 UNIX socket permissions for the R/O socket. This is used for monitoring
32923 Defaults to @samp{"0777"}.
32927 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms
32928 UNIX socket permissions for the R/W socket. Default allows only root.
32929 If PolicyKit is enabled on the socket, the default will change to allow
32930 everyone (eg, 0777)
32932 Defaults to @samp{"0770"}.
32936 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms
32937 UNIX socket permissions for the admin socket. Default allows only owner
32938 (root), do not change it unless you are sure to whom you are exposing
32941 Defaults to @samp{"0777"}.
32945 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir
32946 The directory in which sockets will be found/created.
32948 Defaults to @samp{"/var/run/libvirt"}.
32952 @deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro
32953 Authentication scheme for UNIX read-only sockets. By default socket
32954 permissions allow anyone to connect
32956 Defaults to @samp{"polkit"}.
32960 @deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw
32961 Authentication scheme for UNIX read-write sockets. By default socket
32962 permissions only allow root. If PolicyKit support was compiled into
32963 libvirt, the default will be to use 'polkit' auth.
32965 Defaults to @samp{"polkit"}.
32969 @deftypevr {@code{libvirt-configuration} parameter} string auth-tcp
32970 Authentication scheme for TCP sockets. If you don't enable SASL, then
32971 all TCP traffic is cleartext. Don't do this outside of a dev/test
32974 Defaults to @samp{"sasl"}.
32978 @deftypevr {@code{libvirt-configuration} parameter} string auth-tls
32979 Authentication scheme for TLS sockets. TLS sockets already have
32980 encryption provided by the TLS layer, and limited authentication is done
32983 It is possible to make use of any SASL authentication mechanism as well,
32984 by using 'sasl' for this option
32986 Defaults to @samp{"none"}.
32990 @deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers
32991 API access control scheme.
32993 By default an authenticated user is allowed access to all APIs. Access
32994 drivers can place restrictions on this.
32996 Defaults to @samp{()}.
33000 @deftypevr {@code{libvirt-configuration} parameter} string key-file
33001 Server key file path. If set to an empty string, then no private key is
33004 Defaults to @samp{""}.
33008 @deftypevr {@code{libvirt-configuration} parameter} string cert-file
33009 Server key file path. If set to an empty string, then no certificate is
33012 Defaults to @samp{""}.
33016 @deftypevr {@code{libvirt-configuration} parameter} string ca-file
33017 Server key file path. If set to an empty string, then no CA certificate
33020 Defaults to @samp{""}.
33024 @deftypevr {@code{libvirt-configuration} parameter} string crl-file
33025 Certificate revocation list path. If set to an empty string, then no
33028 Defaults to @samp{""}.
33032 @deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert
33033 Disable verification of our own server certificates.
33035 When libvirtd starts it performs some sanity checks against its own
33038 Defaults to @samp{#f}.
33042 @deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert
33043 Disable verification of client certificates.
33045 Client certificate verification is the primary authentication mechanism.
33046 Any client which does not present a certificate signed by the CA will be
33049 Defaults to @samp{#f}.
33053 @deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list
33054 Whitelist of allowed x509 Distinguished Name.
33056 Defaults to @samp{()}.
33060 @deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames
33061 Whitelist of allowed SASL usernames. The format for username depends on
33062 the SASL authentication mechanism.
33064 Defaults to @samp{()}.
33068 @deftypevr {@code{libvirt-configuration} parameter} string tls-priority
33069 Override the compile time default TLS priority string. The default is
33070 usually @samp{"NORMAL"} unless overridden at build time. Only set this is it
33071 is desired for libvirt to deviate from the global default settings.
33073 Defaults to @samp{"NORMAL"}.
33077 @deftypevr {@code{libvirt-configuration} parameter} integer max-clients
33078 Maximum number of concurrent client connections to allow over all
33081 Defaults to @samp{5000}.
33085 @deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients
33086 Maximum length of queue of connections waiting to be accepted by the
33087 daemon. Note, that some protocols supporting retransmission may obey
33088 this so that a later reattempt at connection succeeds.
33090 Defaults to @samp{1000}.
33094 @deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients
33095 Maximum length of queue of accepted but not yet authenticated clients.
33096 Set this to zero to turn this feature off
33098 Defaults to @samp{20}.
33102 @deftypevr {@code{libvirt-configuration} parameter} integer min-workers
33103 Number of workers to start up initially.
33105 Defaults to @samp{5}.
33109 @deftypevr {@code{libvirt-configuration} parameter} integer max-workers
33110 Maximum number of worker threads.
33112 If the number of active clients exceeds @code{min-workers}, then more
33113 threads are spawned, up to max_workers limit. Typically you'd want
33114 max_workers to equal maximum number of clients allowed.
33116 Defaults to @samp{20}.
33120 @deftypevr {@code{libvirt-configuration} parameter} integer prio-workers
33121 Number of priority workers. If all workers from above pool are stuck,
33122 some calls marked as high priority (notably domainDestroy) can be
33123 executed in this pool.
33125 Defaults to @samp{5}.
33129 @deftypevr {@code{libvirt-configuration} parameter} integer max-requests
33130 Total global limit on concurrent RPC calls.
33132 Defaults to @samp{20}.
33136 @deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests
33137 Limit on concurrent requests from a single client connection. To avoid
33138 one client monopolizing the server this should be a small fraction of
33139 the global max_requests and max_workers parameter.
33141 Defaults to @samp{5}.
33145 @deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers
33146 Same as @code{min-workers} but for the admin interface.
33148 Defaults to @samp{1}.
33152 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers
33153 Same as @code{max-workers} but for the admin interface.
33155 Defaults to @samp{5}.
33159 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients
33160 Same as @code{max-clients} but for the admin interface.
33162 Defaults to @samp{5}.
33166 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients
33167 Same as @code{max-queued-clients} but for the admin interface.
33169 Defaults to @samp{5}.
33173 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests
33174 Same as @code{max-client-requests} but for the admin interface.
33176 Defaults to @samp{5}.
33180 @deftypevr {@code{libvirt-configuration} parameter} integer log-level
33181 Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
33183 Defaults to @samp{3}.
33187 @deftypevr {@code{libvirt-configuration} parameter} string log-filters
33190 A filter allows to select a different logging level for a given category
33191 of logs. The format for a filter is one of:
33202 where @code{name} is a string which is matched against the category
33203 given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
33204 file, e.g., @samp{"remote"}, @samp{"qemu"}, or @samp{"util.json"} (the
33205 name in the filter can be a substring of the full category name, in
33206 order to match multiple similar categories), the optional @samp{"+"}
33207 prefix tells libvirt to log stack trace for each message matching name,
33208 and @code{x} is the minimal level where matching messages should be
33226 Multiple filters can be defined in a single filters statement, they just
33227 need to be separated by spaces.
33229 Defaults to @samp{"3:remote 4:event"}.
33233 @deftypevr {@code{libvirt-configuration} parameter} string log-outputs
33236 An output is one of the places to save logging information. The format
33237 for an output can be:
33241 output goes to stderr
33243 @item x:syslog:name
33244 use syslog for the output and use the given name as the ident
33246 @item x:file:file_path
33247 output to a file, with the given filepath
33250 output to journald logging system
33254 In all case the x prefix is the minimal level, acting as a filter
33271 Multiple outputs can be defined, they just need to be separated by
33274 Defaults to @samp{"3:stderr"}.
33278 @deftypevr {@code{libvirt-configuration} parameter} integer audit-level
33279 Allows usage of the auditing subsystem to be altered
33283 0: disable all auditing
33286 1: enable auditing, only if enabled on host
33289 2: enable auditing, and exit if disabled on host.
33293 Defaults to @samp{1}.
33297 @deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging
33298 Send audit messages via libvirt logging infrastructure.
33300 Defaults to @samp{#f}.
33304 @deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid
33305 Host UUID@. UUID must not have all digits be the same.
33307 Defaults to @samp{""}.
33311 @deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source
33312 Source to read host UUID.
33316 @code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid}
33319 @code{machine-id}: fetch the UUID from @code{/etc/machine-id}
33323 If @code{dmidecode} does not provide a valid UUID a temporary UUID will
33326 Defaults to @samp{"smbios"}.
33330 @deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval
33331 A keepalive message is sent to a client after @code{keepalive_interval}
33332 seconds of inactivity to check if the client is still responding. If
33333 set to -1, libvirtd will never send keepalive requests; however clients
33334 can still send them and the daemon will send responses.
33336 Defaults to @samp{5}.
33340 @deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count
33341 Maximum number of keepalive messages that are allowed to be sent to the
33342 client without getting any response before the connection is considered
33345 In other words, the connection is automatically closed approximately
33346 after @code{keepalive_interval * (keepalive_count + 1)} seconds since
33347 the last message received from the client. When @code{keepalive-count}
33348 is set to 0, connections will be automatically closed after
33349 @code{keepalive-interval} seconds of inactivity without sending any
33350 keepalive messages.
33352 Defaults to @samp{5}.
33356 @deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval
33357 Same as above but for admin interface.
33359 Defaults to @samp{5}.
33363 @deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count
33364 Same as above but for admin interface.
33366 Defaults to @samp{5}.
33370 @deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout
33371 Timeout for Open vSwitch calls.
33373 The @code{ovs-vsctl} utility is used for the configuration and its
33374 timeout option is set by default to 5 seconds to avoid potential
33375 infinite waits blocking libvirt.
33377 Defaults to @samp{5}.
33381 @c %end of autogenerated docs
33383 @subsubheading Virtlog daemon
33384 The virtlogd service is a server side daemon component of libvirt that is
33385 used to manage logs from virtual machine consoles.
33387 This daemon is not used directly by libvirt client applications, rather it
33388 is called on their behalf by @code{libvirtd}. By maintaining the logs in a
33389 standalone daemon, the main @code{libvirtd} daemon can be restarted without
33390 risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec()
33391 itself upon receiving @code{SIGUSR1}, to allow live upgrades without downtime.
33393 @deffn {Scheme Variable} virtlog-service-type
33394 This is the type of the virtlog daemon.
33395 Its value must be a @code{virtlog-configuration}.
33398 (service virtlog-service-type
33399 (virtlog-configuration
33400 (max-clients 1000)))
33404 @deftypevar {@code{libvirt} parameter} package libvirt
33408 @deftypevr {@code{virtlog-configuration} parameter} integer log-level
33409 Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
33411 Defaults to @samp{3}.
33415 @deftypevr {@code{virtlog-configuration} parameter} string log-filters
33418 A filter allows to select a different logging level for a given category
33419 of logs The format for a filter is one of:
33430 where @code{name} is a string which is matched against the category
33431 given in the @code{VIR_LOG_INIT()} at the top of each libvirt source
33432 file, e.g., "remote", "qemu", or "util.json" (the name in the filter can
33433 be a substring of the full category name, in order to match multiple
33434 similar categories), the optional "+" prefix tells libvirt to log stack
33435 trace for each message matching name, and @code{x} is the minimal level
33436 where matching messages should be logged:
33453 Multiple filters can be defined in a single filters statement, they just
33454 need to be separated by spaces.
33456 Defaults to @samp{"3:remote 4:event"}.
33460 @deftypevr {@code{virtlog-configuration} parameter} string log-outputs
33463 An output is one of the places to save logging information The format
33464 for an output can be:
33468 output goes to stderr
33470 @item x:syslog:name
33471 use syslog for the output and use the given name as the ident
33473 @item x:file:file_path
33474 output to a file, with the given filepath
33477 output to journald logging system
33481 In all case the x prefix is the minimal level, acting as a filter
33498 Multiple outputs can be defined, they just need to be separated by
33501 Defaults to @samp{"3:stderr"}.
33505 @deftypevr {@code{virtlog-configuration} parameter} integer max-clients
33506 Maximum number of concurrent client connections to allow over all
33509 Defaults to @samp{1024}.
33513 @deftypevr {@code{virtlog-configuration} parameter} integer max-size
33514 Maximum file size before rolling over.
33516 Defaults to @samp{2MB}
33520 @deftypevr {@code{virtlog-configuration} parameter} integer max-backups
33521 Maximum number of backup files to keep.
33523 Defaults to @samp{3}
33527 @anchor{transparent-emulation-qemu}
33528 @subsubheading Transparent Emulation with QEMU
33531 @cindex @code{binfmt_misc}
33532 @code{qemu-binfmt-service-type} provides support for transparent
33533 emulation of program binaries built for different architectures---e.g.,
33534 it allows you to transparently execute an ARMv7 program on an x86_64
33535 machine. It achieves this by combining the @uref{https://www.qemu.org,
33536 QEMU} emulator and the @code{binfmt_misc} feature of the kernel Linux.
33537 This feature only allows you to emulate GNU/Linux on a different
33538 architecture, but see below for GNU/Hurd support.
33540 @defvr {Scheme Variable} qemu-binfmt-service-type
33541 This is the type of the QEMU/binfmt service for transparent emulation.
33542 Its value must be a @code{qemu-binfmt-configuration} object, which
33543 specifies the QEMU package to use as well as the architecture we want to
33547 (service qemu-binfmt-service-type
33548 (qemu-binfmt-configuration
33549 (platforms (lookup-qemu-platforms "arm" "aarch64"))))
33552 In this example, we enable transparent emulation for the ARM and aarch64
33553 platforms. Running @code{herd stop qemu-binfmt} turns it off, and
33554 running @code{herd start qemu-binfmt} turns it back on (@pxref{Invoking
33555 herd, the @command{herd} command,, shepherd, The GNU Shepherd Manual}).
33558 @deftp {Data Type} qemu-binfmt-configuration
33559 This is the configuration for the @code{qemu-binfmt} service.
33562 @item @code{platforms} (default: @code{'()})
33563 The list of emulated QEMU platforms. Each item must be a @dfn{platform
33564 object} as returned by @code{lookup-qemu-platforms} (see below).
33566 For example, let's suppose you're on an x86_64 machine and you have this
33570 (service qemu-binfmt-service-type
33571 (qemu-binfmt-configuration
33572 (platforms (lookup-qemu-platforms "arm"))))
33578 guix build -s armhf-linux inkscape
33582 and it will build Inkscape for ARMv7 @emph{as if it were a native
33583 build}, transparently using QEMU to emulate the ARMv7 CPU@. Pretty handy
33584 if you'd like to test a package build for an architecture you don't have
33587 @item @code{qemu} (default: @code{qemu})
33588 The QEMU package to use.
33592 @deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{}
33593 Return the list of QEMU platform objects corresponding to
33594 @var{platforms}@dots{}. @var{platforms} must be a list of strings
33595 corresponding to platform names, such as @code{"arm"}, @code{"sparc"},
33596 @code{"mips64el"}, and so on.
33599 @deffn {Scheme Procedure} qemu-platform? @var{obj}
33600 Return true if @var{obj} is a platform object.
33603 @deffn {Scheme Procedure} qemu-platform-name @var{platform}
33604 Return the name of @var{platform}---a string such as @code{"arm"}.
33608 @subsubheading QEMU Guest Agent
33612 The QEMU guest agent provides control over the emulated system to the
33613 host. The @code{qemu-guest-agent} service runs the agent on Guix
33614 guests. To control the agent from the host, open a socket by invoking
33615 QEMU with the following arguments:
33618 qemu-system-x86_64 \
33619 -chardev socket,path=/tmp/qga.sock,server=on,wait=off,id=qga0 \
33620 -device virtio-serial \
33621 -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0 \
33625 This creates a socket at @file{/tmp/qga.sock} on the host. Once the
33626 guest agent is running, you can issue commands with @code{socat}:
33629 $ guix shell socat -- socat unix-connect:/tmp/qga.sock stdio
33630 @{"execute": "guest-get-host-name"@}
33631 @{"return": @{"host-name": "guix"@}@}
33634 See @url{https://wiki.qemu.org/Features/GuestAgent,QEMU guest agent
33635 documentation} for more options and commands.
33637 @defvr {Scheme Variable} qemu-guest-agent-service-type
33638 Service type for the QEMU guest agent service.
33641 @deftp {Data Type} qemu-guest-agent-configuration
33642 Configuration for the @code{qemu-guest-agent} service.
33645 @item @code{qemu} (default: @code{qemu-minimal})
33646 The QEMU package to use.
33648 @item @code{device} (default: @code{""})
33649 File name of the device or socket the agent uses to communicate with the
33650 host. If empty, QEMU uses a default file name.
33655 @subsubheading The Hurd in a Virtual Machine
33657 @cindex @code{hurd}
33661 Service @code{hurd-vm} provides support for running GNU/Hurd in a
33662 virtual machine (VM), a so-called @dfn{childhurd}. This service is meant
33663 to be used on GNU/Linux and the given GNU/Hurd operating system
33664 configuration is cross-compiled. The virtual machine is a Shepherd
33665 service that can be referred to by the names @code{hurd-vm} and
33666 @code{childhurd} and be controlled with commands such as:
33670 herd stop childhurd
33673 When the service is running, you can view its console by connecting to
33674 it with a VNC client, for example with:
33677 guix shell tigervnc-client -- vncviewer localhost:5900
33680 The default configuration (see @code{hurd-vm-configuration} below)
33681 spawns a secure shell (SSH) server in your GNU/Hurd system, which QEMU
33682 (the virtual machine emulator) redirects to port 10222 on the host.
33683 Thus, you can connect over SSH to the childhurd with:
33686 ssh root@@localhost -p 10022
33689 The childhurd is volatile and stateless: it starts with a fresh root
33690 file system every time you restart it. By default though, all the files
33691 under @file{/etc/childhurd} on the host are copied as is to the root
33692 file system of the childhurd when it boots. This allows you to
33693 initialize ``secrets'' inside the VM: SSH host keys, authorized
33694 substitute keys, and so on---see the explanation of @code{secret-root}
33697 @defvr {Scheme Variable} hurd-vm-service-type
33698 This is the type of the Hurd in a Virtual Machine service. Its value
33699 must be a @code{hurd-vm-configuration} object, which specifies the
33700 operating system (@pxref{operating-system Reference}) and the disk size
33701 for the Hurd Virtual Machine, the QEMU package to use as well as the
33702 options for running it.
33707 (service hurd-vm-service-type
33708 (hurd-vm-configuration
33709 (disk-size (* 5000 (expt 2 20))) ;5G
33710 (memory-size 1024))) ;1024MiB
33713 would create a disk image big enough to build GNU@tie{}Hello, with some
33717 @deftp {Data Type} hurd-vm-configuration
33718 The data type representing the configuration for
33719 @code{hurd-vm-service-type}.
33722 @item @code{os} (default: @var{%hurd-vm-operating-system})
33723 The operating system to instantiate. This default is bare-bones with a
33724 permissive OpenSSH secure shell daemon listening on port 2222
33725 (@pxref{Networking Services, @code{openssh-service-type}}).
33727 @item @code{qemu} (default: @code{qemu-minimal})
33728 The QEMU package to use.
33730 @item @code{image} (default: @var{hurd-vm-disk-image})
33731 The procedure used to build the disk-image built from this
33734 @item @code{disk-size} (default: @code{'guess})
33735 The size of the disk image.
33737 @item @code{memory-size} (default: @code{512})
33738 The memory size of the Virtual Machine in mebibytes.
33740 @item @code{options} (default: @code{'("--snapshot")})
33741 The extra options for running QEMU.
33743 @item @code{id} (default: @code{#f})
33744 If set, a non-zero positive integer used to parameterize Childhurd
33745 instances. It is appended to the service's name,
33746 e.g. @code{childhurd1}.
33748 @item @code{net-options} (default: @var{hurd-vm-net-options})
33749 The procedure used to produce the list of QEMU networking options.
33751 By default, it produces
33754 '("--device" "rtl8139,netdev=net0"
33755 "--netdev" (string-append
33757 "hostfwd=tcp:127.0.0.1:@var{secrets-port}-:1004,"
33758 "hostfwd=tcp:127.0.0.1:@var{ssh-port}-:2222,"
33759 "hostfwd=tcp:127.0.0.1:@var{vnc-port}-:5900"))
33762 with forwarded ports:
33765 @var{secrets-port}: @code{(+ 11004 (* 1000 @var{ID}))}
33766 @var{ssh-port}: @code{(+ 10022 (* 1000 @var{ID}))}
33767 @var{vnc-port}: @code{(+ 15900 (* 1000 @var{ID}))}
33770 @item @code{secret-root} (default: @file{/etc/childhurd})
33771 The root directory with out-of-band secrets to be installed into the
33772 childhurd once it runs. Childhurds are volatile which means that on
33773 every startup, secrets such as the SSH host keys and Guix signing key
33776 If the @file{/etc/childhurd} directory does not exist, the
33777 @code{secret-service} running in the Childhurd will be sent an empty
33780 By default, the service automatically populates @file{/etc/childhurd}
33781 with the following non-volatile secrets, unless they already exist:
33784 /etc/childhurd/etc/guix/acl
33785 /etc/childhurd/etc/guix/signing-key.pub
33786 /etc/childhurd/etc/guix/signing-key.sec
33787 /etc/childhurd/etc/ssh/ssh_host_ed25519_key
33788 /etc/childhurd/etc/ssh/ssh_host_ecdsa_key
33789 /etc/childhurd/etc/ssh/ssh_host_ed25519_key.pub
33790 /etc/childhurd/etc/ssh/ssh_host_ecdsa_key.pub
33793 These files are automatically sent to the guest Hurd VM when it boots,
33794 including permissions.
33796 @cindex childhurd, offloading
33797 @cindex Hurd, offloading
33798 Having these files in place means that only a couple of things are
33799 missing to allow the host to offload @code{i586-gnu} builds to the
33804 Authorizing the childhurd's key on the host so that the host accepts
33805 build results coming from the childhurd, which can be done like so:
33808 guix archive --authorize < \
33809 /etc/childhurd/etc/guix/signing-key.pub
33813 Adding the childhurd to @file{/etc/guix/machines.scm} (@pxref{Daemon
33817 We're working towards making that happen automatically---get in touch
33818 with us at @email{guix-devel@@gnu.org} to discuss it!
33822 Note that by default the VM image is volatile, i.e., once stopped the
33823 contents are lost. If you want a stateful image instead, override the
33824 configuration's @code{image} and @code{options} without
33825 the @code{--snapshot} flag using something along these lines:
33828 (service hurd-vm-service-type
33829 (hurd-vm-configuration
33830 (image (const "/out/of/store/writable/hurd.img"))
33834 @subsubheading Ganeti
33839 This service is considered experimental. Configuration options may be changed
33840 in a backwards-incompatible manner, and not all features have been thorougly
33841 tested. Users of this service are encouraged to share their experience at
33842 @email{guix-devel@@gnu.org}.
33845 Ganeti is a virtual machine management system. It is designed to keep virtual
33846 machines running on a cluster of servers even in the event of hardware failures,
33847 and to make maintenance and recovery tasks easy. It consists of multiple
33848 services which are described later in this section. In addition to the Ganeti
33849 service, you will need the OpenSSH service (@pxref{Networking Services,
33850 @code{openssh-service-type}}), and update the @file{/etc/hosts} file
33851 (@pxref{operating-system Reference, @code{hosts-file}}) with the cluster name
33852 and address (or use a DNS server).
33854 All nodes participating in a Ganeti cluster should have the same Ganeti and
33855 @file{/etc/hosts} configuration. Here is an example configuration for a Ganeti
33856 cluster node that supports multiple storage backends, and installs the
33857 @code{debootstrap} and @code{guix} @dfn{OS providers}:
33860 (use-package-modules virtualization)
33861 (use-service-modules base ganeti networking ssh)
33864 (host-name "node1")
33865 (hosts-file (plain-file "hosts" (format #f "
33866 127.0.0.1 localhost
33869 192.168.1.200 ganeti.example.com
33870 192.168.1.201 node1.example.com node1
33871 192.168.1.202 node2.example.com node2
33874 ;; Install QEMU so we can use KVM-based instances, and LVM, DRBD and Ceph
33875 ;; in order to use the "plain", "drbd" and "rbd" storage backends.
33876 (packages (append (map specification->package
33877 '("qemu" "lvm2" "drbd-utils" "ceph"
33878 ;; Add the debootstrap and guix OS providers.
33879 "ganeti-instance-guix" "ganeti-instance-debootstrap"))
33882 (append (list (service static-networking-service-type
33883 (list (static-networking
33885 (list (network-address
33887 (value "192.168.1.201/24"))))
33889 (list (network-route
33890 (destination "default")
33891 (gateway "192.168.1.254"))))
33892 (name-servers '("192.168.1.252"
33893 "192.168.1.253")))))
33895 ;; Ganeti uses SSH to communicate between nodes.
33896 (service openssh-service-type
33897 (openssh-configuration
33898 (permit-root-login 'prohibit-password)))
33900 (service ganeti-service-type
33901 (ganeti-configuration
33902 ;; This list specifies allowed file system paths
33903 ;; for storing virtual machine images.
33904 (file-storage-paths '("/srv/ganeti/file-storage"))
33905 ;; This variable configures a single "variant" for
33906 ;; both Debootstrap and Guix that works with KVM.
33907 (os %default-ganeti-os))))
33911 Users are advised to read the
33912 @url{http://docs.ganeti.org/ganeti/master/html/admin.html,Ganeti
33913 administrators guide} to learn about the various cluster options and
33914 day-to-day operations. There is also a
33915 @url{https://guix.gnu.org/blog/2020/running-a-ganeti-cluster-on-guix/,blog post}
33916 describing how to configure and initialize a small cluster.
33918 @defvr {Scheme Variable} ganeti-service-type
33919 This is a service type that includes all the various services that Ganeti
33922 Its value is a @code{ganeti-configuration} object that defines the package
33923 to use for CLI operations, as well as configuration for the various daemons.
33924 Allowed file storage paths and available guest operating systems are also
33925 configured through this data type.
33928 @deftp {Data Type} ganeti-configuration
33929 The @code{ganeti} service takes the following configuration options:
33932 @item @code{ganeti} (default: @code{ganeti})
33933 The @code{ganeti} package to use. It will be installed to the system profile
33934 and make @command{gnt-cluster}, @command{gnt-instance}, etc available. Note
33935 that the value specified here does not affect the other services as each refer
33936 to a specific @code{ganeti} package (see below).
33938 @item @code{noded-configuration} (default: @code{(ganeti-noded-configuration)})
33939 @itemx @code{confd-configuration} (default: @code{(ganeti-confd-configuration)})
33940 @itemx @code{wconfd-configuration} (default: @code{(ganeti-wconfd-configuration)})
33941 @itemx @code{luxid-configuration} (default: @code{(ganeti-luxid-configuration)})
33942 @itemx @code{rapi-configuration} (default: @code{(ganeti-rapi-configuration)})
33943 @itemx @code{kvmd-configuration} (default: @code{(ganeti-kvmd-configuration)})
33944 @itemx @code{mond-configuration} (default: @code{(ganeti-mond-configuration)})
33945 @itemx @code{metad-configuration} (default: @code{(ganeti-metad-configuration)})
33946 @itemx @code{watcher-configuration} (default: @code{(ganeti-watcher-configuration)})
33947 @itemx @code{cleaner-configuration} (default: @code{(ganeti-cleaner-configuration)})
33949 These options control the various daemons and cron jobs that are distributed
33950 with Ganeti. The possible values for these are described in detail below.
33951 To override a setting, you must use the configuration type for that service:
33954 (service ganeti-service-type
33955 (ganeti-configuration
33956 (rapi-configuration
33957 (ganeti-rapi-configuration
33958 (interface "eth1"))))
33959 (watcher-configuration
33960 (ganeti-watcher-configuration
33961 (rapi-ip "10.0.0.1"))))
33964 @item @code{file-storage-paths} (default: @code{'()})
33965 List of allowed directories for file storage backend.
33967 @item @code{os} (default: @code{%default-ganeti-os})
33968 List of @code{<ganeti-os>} records.
33971 In essence @code{ganeti-service-type} is shorthand for declaring each service
33975 (service ganeti-noded-service-type)
33976 (service ganeti-confd-service-type)
33977 (service ganeti-wconfd-service-type)
33978 (service ganeti-luxid-service-type)
33979 (service ganeti-kvmd-service-type)
33980 (service ganeti-mond-service-type)
33981 (service ganeti-metad-service-type)
33982 (service ganeti-watcher-service-type)
33983 (service ganeti-cleaner-service-type)
33986 Plus a service extension for @code{etc-service-type} that configures the file
33987 storage backend and OS variants.
33991 @deftp {Data Type} ganeti-os
33992 This data type is suitable for passing to the @code{os} parameter of
33993 @code{ganeti-configuration}. It takes the following parameters:
33997 The name for this OS provider. It is only used to specify where the
33998 configuration ends up. Setting it to ``debootstrap'' will create
33999 @file{/etc/ganeti/instance-debootstrap}.
34001 @item @code{extension}
34002 The file extension for variants of this OS type. For example
34003 @file{.conf} or @file{.scm}.
34005 @item @code{variants} (default: @code{'()})
34006 List of @code{ganeti-os-variant} objects for this OS.
34011 @deftp {Data Type} ganeti-os-variant
34012 This is the data type for a Ganeti OS variant. It takes the following
34017 The name of this variant.
34019 @item @code{configuration}
34020 A configuration file for this variant.
34024 @defvr {Scheme Variable} %default-debootstrap-hooks
34025 This variable contains hooks to configure networking and the GRUB bootloader.
34028 @defvr {Scheme Variable} %default-debootstrap-extra-pkgs
34029 This variable contains a list of packages suitable for a fully-virtualized guest.
34032 @deftp {Data Type} debootstrap-configuration
34034 This data type creates configuration files suitable for the debootstrap OS provider.
34037 @item @code{hooks} (default: @code{%default-debootstrap-hooks})
34038 When not @code{#f}, this must be a G-expression that specifies a directory with
34039 scripts that will run when the OS is installed. It can also be a list of
34040 @code{(name . file-like)} pairs. For example:
34043 `((99-hello-world . ,(plain-file "#!/bin/sh\necho Hello, World")))
34046 That will create a directory with one executable named @code{99-hello-world}
34047 and run it every time this variant is installed. If set to @code{#f}, hooks
34048 in @file{/etc/ganeti/instance-debootstrap/hooks} will be used, if any.
34049 @item @code{proxy} (default: @code{#f})
34050 Optional HTTP proxy to use.
34051 @item @code{mirror} (default: @code{#f})
34052 The Debian mirror. Typically something like @code{http://ftp.no.debian.org/debian}.
34053 The default varies depending on the distribution.
34054 @item @code{arch} (default: @code{#f})
34055 The dpkg architecture. Set to @code{armhf} to debootstrap an ARMv7 instance
34056 on an AArch64 host. Default is to use the current system architecture.
34057 @item @code{suite} (default: @code{"stable"})
34058 When set, this must be a Debian distribution ``suite'' such as @code{buster}
34059 or @code{focal}. If set to @code{#f}, the default for the OS provider is used.
34060 @item @code{extra-pkgs} (default: @code{%default-debootstrap-extra-pkgs})
34061 List of extra packages that will get installed by dpkg in addition
34062 to the minimal system.
34063 @item @code{components} (default: @code{#f})
34064 When set, must be a list of Debian repository ``components''. For example
34065 @code{'("main" "contrib")}.
34066 @item @code{generate-cache?} (default: @code{#t})
34067 Whether to automatically cache the generated debootstrap archive.
34068 @item @code{clean-cache} (default: @code{14})
34069 Discard the cache after this amount of days. Use @code{#f} to never
34071 @item @code{partition-style} (default: @code{'msdos})
34072 The type of partition to create. When set, it must be one of
34073 @code{'msdos}, @code{'none} or a string.
34074 @item @code{partition-alignment} (default: @code{2048})
34075 Alignment of the partition in sectors.
34079 @deffn {Scheme Procedure} debootstrap-variant @var{name} @var{configuration}
34080 This is a helper procedure that creates a @code{ganeti-os-variant} record. It
34081 takes two parameters: a name and a @code{debootstrap-configuration} object.
34084 @deffn {Scheme Procedure} debootstrap-os @var{variants}@dots{}
34085 This is a helper procedure that creates a @code{ganeti-os} record. It takes
34086 a list of variants created with @code{debootstrap-variant}.
34089 @deffn {Scheme Procedure} guix-variant @var{name} @var{configuration}
34090 This is a helper procedure that creates a @code{ganeti-os-variant} record for
34091 use with the Guix OS provider. It takes a name and a G-expression that returns
34092 a ``file-like'' (@pxref{G-Expressions, file-like objects}) object containing a
34093 Guix System configuration.
34096 @deffn {Scheme Procedure} guix-os @var{variants}@dots{}
34097 This is a helper procedure that creates a @code{ganeti-os} record. It
34098 takes a list of variants produced by @code{guix-variant}.
34101 @defvr {Scheme Variable} %default-debootstrap-variants
34102 This is a convenience variable to make the debootstrap provider work
34103 ``out of the box'' without users having to declare variants manually. It
34104 contains a single debootstrap variant with the default configuration:
34107 (list (debootstrap-variant
34109 (debootstrap-configuration)))
34113 @defvr {Scheme Variable} %default-guix-variants
34114 This is a convenience variable to make the Guix OS provider work without
34115 additional configuration. It creates a virtual machine that has an SSH
34116 server, a serial console, and authorizes the Ganeti hosts SSH keys.
34119 (list (guix-variant
34121 (file-append ganeti-instance-guix
34122 "/share/doc/ganeti-instance-guix/examples/dynamic.scm")))
34126 Users can implement support for OS providers unbeknownst to Guix by extending
34127 the @code{ganeti-os} and @code{ganeti-os-variant} records appropriately.
34133 (extension ".conf")
34135 (list (ganeti-os-variant
34137 (configuration (plain-file "bar" "this is fine"))))))
34140 That creates @file{/etc/ganeti/instance-custom/variants/foo.conf} which points
34141 to a file in the store with contents @code{this is fine}. It also creates
34142 @file{/etc/ganeti/instance-custom/variants/variants.list} with contents @code{foo}.
34144 Obviously this may not work for all OS providers out there. If you find the
34145 interface limiting, please reach out to @email{guix-devel@@gnu.org}.
34147 The rest of this section documents the various services that are included by
34148 @code{ganeti-service-type}.
34150 @defvr {Scheme Variable} ganeti-noded-service-type
34151 @command{ganeti-noded} is the daemon responsible for node-specific functions
34152 within the Ganeti system. The value of this service must be a
34153 @code{ganeti-noded-configuration} object.
34156 @deftp {Data Type} ganeti-noded-configuration
34157 This is the configuration for the @code{ganeti-noded} service.
34160 @item @code{ganeti} (default: @code{ganeti})
34161 The @code{ganeti} package to use for this service.
34163 @item @code{port} (default: @code{1811})
34164 The TCP port on which the node daemon listens for network requests.
34166 @item @code{address} (default: @code{"0.0.0.0"})
34167 The network address that the daemon will bind to. The default address means
34168 bind to all available addresses.
34170 @item @code{interface} (default: @code{#f})
34171 When this is set, it must be a specific network interface (e.g.@: @code{eth0})
34172 that the daemon will bind to.
34174 @item @code{max-clients} (default: @code{20})
34175 This sets a limit on the maximum number of simultaneous client connections
34176 that the daemon will handle. Connections above this count are accepted, but
34177 no responses will be sent until enough connections have closed.
34179 @item @code{ssl?} (default: @code{#t})
34180 Whether to use SSL/TLS to encrypt network communications. The certificate
34181 is automatically provisioned by the cluster and can be rotated with
34182 @command{gnt-cluster renew-crypto}.
34184 @item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
34185 This can be used to provide a specific encryption key for TLS communications.
34187 @item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
34188 This can be used to provide a specific certificate for TLS communications.
34190 @item @code{debug?} (default: @code{#f})
34191 When true, the daemon performs additional logging for debugging purposes.
34192 Note that this will leak encryption details to the log files, use with caution.
34197 @defvr {Scheme Variable} ganeti-confd-service-type
34198 @command{ganeti-confd} answers queries related to the configuration of a
34199 Ganeti cluster. The purpose of this daemon is to have a highly available
34200 and fast way to query cluster configuration values. It is automatically
34201 active on all @dfn{master candidates}. The value of this service must be a
34202 @code{ganeti-confd-configuration} object.
34206 @deftp {Data Type} ganeti-confd-configuration
34207 This is the configuration for the @code{ganeti-confd} service.
34210 @item @code{ganeti} (default: @code{ganeti})
34211 The @code{ganeti} package to use for this service.
34213 @item @code{port} (default: @code{1814})
34214 The UDP port on which to listen for network requests.
34216 @item @code{address} (default: @code{"0.0.0.0"})
34217 Network address that the daemon will bind to.
34219 @item @code{debug?} (default: @code{#f})
34220 When true, the daemon performs additional logging for debugging purposes.
34225 @defvr {Scheme Variable} ganeti-wconfd-service-type
34226 @command{ganeti-wconfd} is the daemon that has authoritative knowledge
34227 about the cluster configuration and is the only entity that can accept
34228 changes to it. All jobs that need to modify the configuration will do so
34229 by sending appropriate requests to this daemon. It only runs on the
34230 @dfn{master node} and will automatically disable itself on other nodes.
34232 The value of this service must be a
34233 @code{ganeti-wconfd-configuration} object.
34236 @deftp {Data Type} ganeti-wconfd-configuration
34237 This is the configuration for the @code{ganeti-wconfd} service.
34240 @item @code{ganeti} (default: @code{ganeti})
34241 The @code{ganeti} package to use for this service.
34243 @item @code{no-voting?} (default: @code{#f})
34244 The daemon will refuse to start if the majority of cluster nodes does not
34245 agree that it is running on the master node. Set to @code{#t} to start
34246 even if a quorum can not be reached (dangerous, use with caution).
34248 @item @code{debug?} (default: @code{#f})
34249 When true, the daemon performs additional logging for debugging purposes.
34254 @defvr {Scheme Variable} ganeti-luxid-service-type
34255 @command{ganeti-luxid} is a daemon used to answer queries related to the
34256 configuration and the current live state of a Ganeti cluster. Additionally,
34257 it is the authoritative daemon for the Ganeti job queue. Jobs can be
34258 submitted via this daemon and it schedules and starts them.
34260 It takes a @code{ganeti-luxid-configuration} object.
34263 @deftp {Data Type} ganeti-luxid-configuration
34264 This is the configuration for the @code{ganeti-luxid} service.
34267 @item @code{ganeti} (default: @code{ganeti})
34268 The @code{ganeti} package to use for this service.
34270 @item @code{no-voting?} (default: @code{#f})
34271 The daemon will refuse to start if it cannot verify that the majority of
34272 cluster nodes believes that it is running on the master node. Set to
34273 @code{#t} to ignore such checks and start anyway (this can be dangerous).
34275 @item @code{debug?} (default: @code{#f})
34276 When true, the daemon performs additional logging for debugging purposes.
34281 @defvr {Scheme Variable} ganeti-rapi-service-type
34282 @command{ganeti-rapi} provides a remote API for Ganeti clusters. It runs on
34283 the master node and can be used to perform cluster actions programmatically
34284 via a JSON-based RPC protocol.
34286 Most query operations are allowed without authentication (unless
34287 @var{require-authentication?} is set), whereas write operations require
34288 explicit authorization via the @file{/var/lib/ganeti/rapi/users} file. See
34289 the @url{http://docs.ganeti.org/ganeti/master/html/rapi.html, Ganeti Remote
34290 API documentation} for more information.
34292 The value of this service must be a @code{ganeti-rapi-configuration} object.
34295 @deftp {Data Type} ganeti-rapi-configuration
34296 This is the configuration for the @code{ganeti-rapi} service.
34299 @item @code{ganeti} (default: @code{ganeti})
34300 The @code{ganeti} package to use for this service.
34302 @item @code{require-authentication?} (default: @code{#f})
34303 Whether to require authentication even for read-only operations.
34305 @item @code{port} (default: @code{5080})
34306 The TCP port on which to listen to API requests.
34308 @item @code{address} (default: @code{"0.0.0.0"})
34309 The network address that the service will bind to. By default it listens
34310 on all configured addresses.
34312 @item @code{interface} (default: @code{#f})
34313 When set, it must specify a specific network interface such as @code{eth0}
34314 that the daemon will bind to.
34316 @item @code{max-clients} (default: @code{20})
34317 The maximum number of simultaneous client requests to handle. Further
34318 connections are allowed, but no responses are sent until enough connections
34321 @item @code{ssl?} (default: @code{#t})
34322 Whether to use SSL/TLS encryption on the RAPI port.
34324 @item @code{ssl-key} (default: @file{"/var/lib/ganeti/server.pem"})
34325 This can be used to provide a specific encryption key for TLS communications.
34327 @item @code{ssl-cert} (default: @file{"/var/lib/ganeti/server.pem"})
34328 This can be used to provide a specific certificate for TLS communications.
34330 @item @code{debug?} (default: @code{#f})
34331 When true, the daemon performs additional logging for debugging purposes.
34332 Note that this will leak encryption details to the log files, use with caution.
34337 @defvr {Scheme Variable} ganeti-kvmd-service-type
34338 @command{ganeti-kvmd} is responsible for determining whether a given KVM
34339 instance was shut down by an administrator or a user. Normally Ganeti will
34340 restart an instance that was not stopped through Ganeti itself. If the
34341 cluster option @code{user_shutdown} is true, this daemon monitors the
34342 @code{QMP} socket provided by QEMU and listens for shutdown events, and
34343 marks the instance as @dfn{USER_down} instead of @dfn{ERROR_down} when
34344 it shuts down gracefully by itself.
34346 It takes a @code{ganeti-kvmd-configuration} object.
34349 @deftp {Data Type} ganeti-kvmd-configuration
34352 @item @code{ganeti} (default: @code{ganeti})
34353 The @code{ganeti} package to use for this service.
34355 @item @code{debug?} (default: @code{#f})
34356 When true, the daemon performs additional logging for debugging purposes.
34361 @defvr {Scheme Variable} ganeti-mond-service-type
34362 @command{ganeti-mond} is an optional daemon that provides Ganeti monitoring
34363 functionality. It is responsible for running data collectors and publish the
34364 collected information through a HTTP interface.
34366 It takes a @code{ganeti-mond-configuration} object.
34369 @deftp {Data Type} ganeti-mond-configuration
34372 @item @code{ganeti} (default: @code{ganeti})
34373 The @code{ganeti} package to use for this service.
34375 @item @code{port} (default: @code{1815})
34376 The port on which the daemon will listen.
34378 @item @code{address} (default: @code{"0.0.0.0"})
34379 The network address that the daemon will bind to. By default it binds to all
34380 available interfaces.
34382 @item @code{debug?} (default: @code{#f})
34383 When true, the daemon performs additional logging for debugging purposes.
34388 @defvr {Scheme Variable} ganeti-metad-service-type
34389 @command{ganeti-metad} is an optional daemon that can be used to provide
34390 information about the cluster to instances or OS install scripts.
34392 It takes a @code{ganeti-metad-configuration} object.
34395 @deftp {Data Type} ganeti-metad-configuration
34398 @item @code{ganeti} (default: @code{ganeti})
34399 The @code{ganeti} package to use for this service.
34401 @item @code{port} (default: @code{80})
34402 The port on which the daemon will listen.
34404 @item @code{address} (default: @code{#f})
34405 If set, the daemon will bind to this address only. If left unset, the behavior
34406 depends on the cluster configuration.
34408 @item @code{debug?} (default: @code{#f})
34409 When true, the daemon performs additional logging for debugging purposes.
34414 @defvr {Scheme Variable} ganeti-watcher-service-type
34415 @command{ganeti-watcher} is a script designed to run periodically and ensure
34416 the health of a cluster. It will automatically restart instances that have
34417 stopped without Ganeti's consent, and repairs DRBD links in case a node has
34418 rebooted. It also archives old cluster jobs and restarts Ganeti daemons
34419 that are not running. If the cluster parameter @code{ensure_node_health}
34420 is set, the watcher will also shutdown instances and DRBD devices if the
34421 node it is running on is declared offline by known master candidates.
34423 It can be paused on all nodes with @command{gnt-cluster watcher pause}.
34425 The service takes a @code{ganeti-watcher-configuration} object.
34428 @deftp {Data Type} ganeti-watcher-configuration
34431 @item @code{ganeti} (default: @code{ganeti})
34432 The @code{ganeti} package to use for this service.
34434 @item @code{schedule} (default: @code{'(next-second-from (next-minute (range 0 60 5)))})
34435 How often to run the script. The default is every five minutes.
34437 @item @code{rapi-ip} (default: @code{#f})
34438 This option needs to be specified only if the RAPI daemon is configured to use
34439 a particular interface or address. By default the cluster address is used.
34441 @item @code{job-age} (default: @code{(* 6 3600)})
34442 Archive cluster jobs older than this age, specified in seconds. The default
34443 is 6 hours. This keeps @command{gnt-job list} manageable.
34445 @item @code{verify-disks?} (default: @code{#t})
34446 If this is @code{#f}, the watcher will not try to repair broken DRBD links
34447 automatically. Administrators will need to use @command{gnt-cluster verify-disks}
34450 @item @code{debug?} (default: @code{#f})
34451 When @code{#t}, the script performs additional logging for debugging purposes.
34456 @defvr {Scheme Variable} ganeti-cleaner-service-type
34457 @command{ganeti-cleaner} is a script designed to run periodically and remove
34458 old files from the cluster. This service type controls two @dfn{cron jobs}:
34459 one intended for the master node that permanently purges old cluster jobs,
34460 and one intended for every node that removes expired X509 certificates, keys,
34461 and outdated @command{ganeti-watcher} information. Like all Ganeti services,
34462 it is safe to include even on non-master nodes as it will disable itself as
34465 It takes a @code{ganeti-cleaner-configuration} object.
34468 @deftp {Data Type} ganeti-cleaner-configuration
34471 @item @code{ganeti} (default: @code{ganeti})
34472 The @code{ganeti} package to use for the @command{gnt-cleaner} command.
34474 @item @code{master-schedule} (default: @code{"45 1 * * *"})
34475 How often to run the master cleaning job. The default is once per day, at
34478 @item @code{node-schedule} (default: @code{"45 2 * * *"})
34479 How often to run the node cleaning job. The default is once per day, at
34485 @node Version Control Services
34486 @subsection Version Control Services
34488 The @code{(gnu services version-control)} module provides a service to
34489 allow remote access to local Git repositories. There are three options:
34490 the @code{git-daemon-service}, which provides access to repositories via
34491 the @code{git://} unsecured TCP-based protocol, extending the
34492 @code{nginx} web server to proxy some requests to
34493 @code{git-http-backend}, or providing a web interface with
34494 @code{cgit-service-type}.
34496 @deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)]
34498 Return a service that runs @command{git daemon}, a simple TCP server to
34499 expose repositories over the Git protocol for anonymous access.
34501 The optional @var{config} argument should be a
34502 @code{<git-daemon-configuration>} object, by default it allows read-only
34503 access to exported@footnote{By creating the magic file
34504 @file{git-daemon-export-ok} in the repository directory.} repositories under
34509 @deftp {Data Type} git-daemon-configuration
34510 Data type representing the configuration for @code{git-daemon-service}.
34513 @item @code{package} (default: @code{git})
34514 Package object of the Git distributed version control system.
34516 @item @code{export-all?} (default: @code{#f})
34517 Whether to allow access for all Git repositories, even if they do not
34518 have the @file{git-daemon-export-ok} file.
34520 @item @code{base-path} (default: @file{/srv/git})
34521 Whether to remap all the path requests as relative to the given path.
34522 If you run @command{git daemon} with @code{(base-path "/srv/git")} on
34523 @samp{example.com}, then if you later try to pull
34524 @indicateurl{git://example.com/hello.git}, git daemon will interpret the
34525 path as @file{/srv/git/hello.git}.
34527 @item @code{user-path} (default: @code{#f})
34528 Whether to allow @code{~user} notation to be used in requests. When
34529 specified with empty string, requests to
34530 @indicateurl{git://host/~alice/foo} is taken as a request to access
34531 @code{foo} repository in the home directory of user @code{alice}. If
34532 @code{(user-path "@var{path}")} is specified, the same request is taken
34533 as a request to access @file{@var{path}/foo} repository in the home
34534 directory of user @code{alice}.
34536 @item @code{listen} (default: @code{'()})
34537 Whether to listen on specific IP addresses or hostnames, defaults to
34540 @item @code{port} (default: @code{#f})
34541 Whether to listen on an alternative port, which defaults to 9418.
34543 @item @code{whitelist} (default: @code{'()})
34544 If not empty, only allow access to this list of directories.
34546 @item @code{extra-options} (default: @code{'()})
34547 Extra options will be passed to @command{git daemon}, please run
34548 @command{man git-daemon} for more information.
34553 The @code{git://} protocol lacks authentication. When you pull from a
34554 repository fetched via @code{git://}, you don't know whether the data you
34555 receive was modified or is even coming from the specified host, and your
34556 connection is subject to eavesdropping. It's better to use an authenticated
34557 and encrypted transport, such as @code{https}. Although Git allows you
34558 to serve repositories using unsophisticated file-based web servers,
34559 there is a faster protocol implemented by the @code{git-http-backend}
34560 program. This program is the back-end of a proper Git web service. It
34561 is designed to sit behind a FastCGI proxy. @xref{Web Services}, for more
34562 on running the necessary @code{fcgiwrap} daemon.
34564 Guix has a separate configuration data type for serving Git repositories
34567 @deftp {Data Type} git-http-configuration
34568 Data type representing the configuration for a future
34569 @code{git-http-service-type}; can currently be used to configure Nginx
34570 through @code{git-http-nginx-location-configuration}.
34573 @item @code{package} (default: @var{git})
34574 Package object of the Git distributed version control system.
34576 @item @code{git-root} (default: @file{/srv/git})
34577 Directory containing the Git repositories to expose to the world.
34579 @item @code{export-all?} (default: @code{#f})
34580 Whether to expose access for all Git repositories in @var{git-root},
34581 even if they do not have the @file{git-daemon-export-ok} file.
34583 @item @code{uri-path} (default: @samp{/git/})
34584 Path prefix for Git access. With the default @samp{/git/} prefix, this
34585 will map @indicateurl{http://@var{server}/git/@var{repo}.git} to
34586 @file{/srv/git/@var{repo}.git}. Requests whose URI paths do not begin
34587 with this prefix are not passed on to this Git instance.
34589 @item @code{fcgiwrap-socket} (default: @code{127.0.0.1:9000})
34590 The socket on which the @code{fcgiwrap} daemon is listening. @xref{Web
34595 There is no @code{git-http-service-type}, currently; instead you can
34596 create an @code{nginx-location-configuration} from a
34597 @code{git-http-configuration} and then add that location to a web
34600 @deffn {Scheme Procedure} git-http-nginx-location-configuration @
34601 [config=(git-http-configuration)]
34602 Compute an @code{nginx-location-configuration} that corresponds to the
34603 given Git http configuration. An example nginx service definition to
34604 serve the default @file{/srv/git} over HTTPS might be:
34607 (service nginx-service-type
34608 (nginx-configuration
34611 (nginx-server-configuration
34612 (listen '("443 ssl"))
34613 (server-name "git.my-host.org")
34615 "/etc/letsencrypt/live/git.my-host.org/fullchain.pem")
34616 (ssl-certificate-key
34617 "/etc/letsencrypt/live/git.my-host.org/privkey.pem")
34620 (git-http-nginx-location-configuration
34621 (git-http-configuration (uri-path "/"))))))))))
34624 This example assumes that you are using Let's Encrypt to get your TLS
34625 certificate. @xref{Certificate Services}. The default @code{certbot}
34626 service will redirect all HTTP traffic on @code{git.my-host.org} to
34627 HTTPS@. You will also need to add an @code{fcgiwrap} proxy to your
34628 system services. @xref{Web Services}.
34631 @subsubheading Cgit Service
34633 @cindex Cgit service
34634 @cindex Git, web interface
34635 @uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
34636 repositories written in C.
34638 The following example will configure the service with default values.
34639 By default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
34642 (service cgit-service-type)
34645 The @code{file-object} type designates either a file-like object
34646 (@pxref{G-Expressions, file-like objects}) or a string.
34648 @c %start of fragment
34650 Available @code{cgit-configuration} fields are:
34652 @deftypevr {@code{cgit-configuration} parameter} package package
34657 @deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx
34658 NGINX configuration.
34662 @deftypevr {@code{cgit-configuration} parameter} file-object about-filter
34663 Specifies a command which will be invoked to format the content of about
34664 pages (both top-level and for each repository).
34666 Defaults to @samp{""}.
34670 @deftypevr {@code{cgit-configuration} parameter} string agefile
34671 Specifies a path, relative to each repository path, which can be used to
34672 specify the date and time of the youngest commit in the repository.
34674 Defaults to @samp{""}.
34678 @deftypevr {@code{cgit-configuration} parameter} file-object auth-filter
34679 Specifies a command that will be invoked for authenticating repository
34682 Defaults to @samp{""}.
34686 @deftypevr {@code{cgit-configuration} parameter} string branch-sort
34687 Flag which, when set to @samp{age}, enables date ordering in the branch
34688 ref list, and when set @samp{name} enables ordering by branch name.
34690 Defaults to @samp{"name"}.
34694 @deftypevr {@code{cgit-configuration} parameter} string cache-root
34695 Path used to store the cgit cache entries.
34697 Defaults to @samp{"/var/cache/cgit"}.
34701 @deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl
34702 Number which specifies the time-to-live, in minutes, for the cached
34703 version of repository pages accessed with a fixed SHA1.
34705 Defaults to @samp{-1}.
34709 @deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl
34710 Number which specifies the time-to-live, in minutes, for the cached
34711 version of repository pages accessed without a fixed SHA1.
34713 Defaults to @samp{5}.
34717 @deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl
34718 Number which specifies the time-to-live, in minutes, for the cached
34719 version of the repository summary page.
34721 Defaults to @samp{5}.
34725 @deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl
34726 Number which specifies the time-to-live, in minutes, for the cached
34727 version of the repository index page.
34729 Defaults to @samp{5}.
34733 @deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl
34734 Number which specifies the time-to-live, in minutes, for the result of
34735 scanning a path for Git repositories.
34737 Defaults to @samp{15}.
34741 @deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl
34742 Number which specifies the time-to-live, in minutes, for the cached
34743 version of the repository about page.
34745 Defaults to @samp{15}.
34749 @deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl
34750 Number which specifies the time-to-live, in minutes, for the cached
34751 version of snapshots.
34753 Defaults to @samp{5}.
34757 @deftypevr {@code{cgit-configuration} parameter} integer cache-size
34758 The maximum number of entries in the cgit cache. When set to @samp{0},
34759 caching is disabled.
34761 Defaults to @samp{0}.
34765 @deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort?
34766 Sort items in the repo list case sensitively.
34768 Defaults to @samp{#t}.
34772 @deftypevr {@code{cgit-configuration} parameter} list clone-prefix
34773 List of common prefixes which, when combined with a repository URL,
34774 generates valid clone URLs for the repository.
34776 Defaults to @samp{()}.
34780 @deftypevr {@code{cgit-configuration} parameter} list clone-url
34781 List of @code{clone-url} templates.
34783 Defaults to @samp{()}.
34787 @deftypevr {@code{cgit-configuration} parameter} file-object commit-filter
34788 Command which will be invoked to format commit messages.
34790 Defaults to @samp{""}.
34794 @deftypevr {@code{cgit-configuration} parameter} string commit-sort
34795 Flag which, when set to @samp{date}, enables strict date ordering in the
34796 commit log, and when set to @samp{topo} enables strict topological
34799 Defaults to @samp{"git log"}.
34803 @deftypevr {@code{cgit-configuration} parameter} file-object css
34804 URL which specifies the css document to include in all cgit pages.
34806 Defaults to @samp{"/share/cgit/cgit.css"}.
34810 @deftypevr {@code{cgit-configuration} parameter} file-object email-filter
34811 Specifies a command which will be invoked to format names and email
34812 address of committers, authors, and taggers, as represented in various
34813 places throughout the cgit interface.
34815 Defaults to @samp{""}.
34819 @deftypevr {@code{cgit-configuration} parameter} boolean embedded?
34820 Flag which, when set to @samp{#t}, will make cgit generate a HTML
34821 fragment suitable for embedding in other HTML pages.
34823 Defaults to @samp{#f}.
34827 @deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph?
34828 Flag which, when set to @samp{#t}, will make cgit print an ASCII-art
34829 commit history graph to the left of the commit messages in the
34830 repository log page.
34832 Defaults to @samp{#f}.
34836 @deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides?
34837 Flag which, when set to @samp{#t}, allows all filter settings to be
34838 overridden in repository-specific cgitrc files.
34840 Defaults to @samp{#f}.
34844 @deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links?
34845 Flag which, when set to @samp{#t}, allows users to follow a file in the
34848 Defaults to @samp{#f}.
34852 @deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone?
34853 If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git
34856 Defaults to @samp{#t}.
34860 @deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links?
34861 Flag which, when set to @samp{#t}, will make cgit generate extra links
34862 "summary", "commit", "tree" for each repo in the repository index.
34864 Defaults to @samp{#f}.
34868 @deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner?
34869 Flag which, when set to @samp{#t}, will make cgit display the owner of
34870 each repo in the repository index.
34872 Defaults to @samp{#t}.
34876 @deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount?
34877 Flag which, when set to @samp{#t}, will make cgit print the number of
34878 modified files for each commit on the repository log page.
34880 Defaults to @samp{#f}.
34884 @deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount?
34885 Flag which, when set to @samp{#t}, will make cgit print the number of
34886 added and removed lines for each commit on the repository log page.
34888 Defaults to @samp{#f}.
34892 @deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches?
34893 Flag which, when set to @code{#t}, will make cgit display remote
34894 branches in the summary and refs views.
34896 Defaults to @samp{#f}.
34900 @deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links?
34901 Flag which, when set to @code{1}, will make cgit use the subject of the
34902 parent commit as link text when generating links to parent commits in
34905 Defaults to @samp{#f}.
34909 @deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving?
34910 Flag which, when set to @samp{#t}, will make cgit use the subject of the
34911 parent commit as link text when generating links to parent commits in
34914 Defaults to @samp{#f}.
34918 @deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers?
34919 Flag which, when set to @samp{#t}, will make cgit generate linenumber
34920 links for plaintext blobs printed in the tree view.
34922 Defaults to @samp{#t}.
34926 @deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config?
34927 Flag which, when set to @samp{#f}, will allow cgit to use Git config to
34928 set any repo specific settings.
34930 Defaults to @samp{#f}.
34934 @deftypevr {@code{cgit-configuration} parameter} file-object favicon
34935 URL used as link to a shortcut icon for cgit.
34937 Defaults to @samp{"/favicon.ico"}.
34941 @deftypevr {@code{cgit-configuration} parameter} string footer
34942 The content of the file specified with this option will be included
34943 verbatim at the bottom of all pages (i.e.@: it replaces the standard
34944 "generated by..."@: message).
34946 Defaults to @samp{""}.
34950 @deftypevr {@code{cgit-configuration} parameter} string head-include
34951 The content of the file specified with this option will be included
34952 verbatim in the HTML HEAD section on all pages.
34954 Defaults to @samp{""}.
34958 @deftypevr {@code{cgit-configuration} parameter} string header
34959 The content of the file specified with this option will be included
34960 verbatim at the top of all pages.
34962 Defaults to @samp{""}.
34966 @deftypevr {@code{cgit-configuration} parameter} file-object include
34967 Name of a configfile to include before the rest of the current config-
34970 Defaults to @samp{""}.
34974 @deftypevr {@code{cgit-configuration} parameter} string index-header
34975 The content of the file specified with this option will be included
34976 verbatim above the repository index.
34978 Defaults to @samp{""}.
34982 @deftypevr {@code{cgit-configuration} parameter} string index-info
34983 The content of the file specified with this option will be included
34984 verbatim below the heading on the repository index page.
34986 Defaults to @samp{""}.
34990 @deftypevr {@code{cgit-configuration} parameter} boolean local-time?
34991 Flag which, if set to @samp{#t}, makes cgit print commit and tag times
34992 in the servers timezone.
34994 Defaults to @samp{#f}.
34998 @deftypevr {@code{cgit-configuration} parameter} file-object logo
34999 URL which specifies the source of an image which will be used as a logo
35002 Defaults to @samp{"/share/cgit/cgit.png"}.
35006 @deftypevr {@code{cgit-configuration} parameter} string logo-link
35007 URL loaded when clicking on the cgit logo image.
35009 Defaults to @samp{""}.
35013 @deftypevr {@code{cgit-configuration} parameter} file-object owner-filter
35014 Command which will be invoked to format the Owner column of the main
35017 Defaults to @samp{""}.
35021 @deftypevr {@code{cgit-configuration} parameter} integer max-atom-items
35022 Number of items to display in atom feeds view.
35024 Defaults to @samp{10}.
35028 @deftypevr {@code{cgit-configuration} parameter} integer max-commit-count
35029 Number of entries to list per page in "log" view.
35031 Defaults to @samp{50}.
35035 @deftypevr {@code{cgit-configuration} parameter} integer max-message-length
35036 Number of commit message characters to display in "log" view.
35038 Defaults to @samp{80}.
35042 @deftypevr {@code{cgit-configuration} parameter} integer max-repo-count
35043 Specifies the number of entries to list per page on the repository index
35046 Defaults to @samp{50}.
35050 @deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length
35051 Specifies the maximum number of repo description characters to display
35052 on the repository index page.
35054 Defaults to @samp{80}.
35058 @deftypevr {@code{cgit-configuration} parameter} integer max-blob-size
35059 Specifies the maximum size of a blob to display HTML for in KBytes.
35061 Defaults to @samp{0}.
35065 @deftypevr {@code{cgit-configuration} parameter} string max-stats
35066 Maximum statistics period. Valid values are @samp{week},@samp{month},
35067 @samp{quarter} and @samp{year}.
35069 Defaults to @samp{""}.
35073 @deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype
35074 Mimetype for the specified filename extension.
35076 Defaults to @samp{((gif "image/gif") (html "text/html") (jpg
35077 "image/jpeg") (jpeg "image/jpeg") (pdf "application/pdf") (png
35078 "image/png") (svg "image/svg+xml"))}.
35082 @deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file
35083 Specifies the file to use for automatic mimetype lookup.
35085 Defaults to @samp{""}.
35089 @deftypevr {@code{cgit-configuration} parameter} string module-link
35090 Text which will be used as the formatstring for a hyperlink when a
35091 submodule is printed in a directory listing.
35093 Defaults to @samp{""}.
35097 @deftypevr {@code{cgit-configuration} parameter} boolean nocache?
35098 If set to the value @samp{#t} caching will be disabled.
35100 Defaults to @samp{#f}.
35104 @deftypevr {@code{cgit-configuration} parameter} boolean noplainemail?
35105 If set to @samp{#t} showing full author email addresses will be
35108 Defaults to @samp{#f}.
35112 @deftypevr {@code{cgit-configuration} parameter} boolean noheader?
35113 Flag which, when set to @samp{#t}, will make cgit omit the standard
35114 header on all pages.
35116 Defaults to @samp{#f}.
35120 @deftypevr {@code{cgit-configuration} parameter} project-list project-list
35121 A list of subdirectories inside of @code{repository-directory}, relative
35122 to it, that should loaded as Git repositories. An empty list means that
35123 all subdirectories will be loaded.
35125 Defaults to @samp{()}.
35129 @deftypevr {@code{cgit-configuration} parameter} file-object readme
35130 Text which will be used as default value for @code{cgit-repo-readme}.
35132 Defaults to @samp{""}.
35136 @deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix?
35137 If set to @code{#t} and @code{repository-directory} is enabled, if any
35138 repositories are found with a suffix of @code{.git}, this suffix will be
35139 removed for the URL and name.
35141 Defaults to @samp{#f}.
35145 @deftypevr {@code{cgit-configuration} parameter} integer renamelimit
35146 Maximum number of files to consider when detecting renames.
35148 Defaults to @samp{-1}.
35152 @deftypevr {@code{cgit-configuration} parameter} string repository-sort
35153 The way in which repositories in each section are sorted.
35155 Defaults to @samp{""}.
35159 @deftypevr {@code{cgit-configuration} parameter} robots-list robots
35160 Text used as content for the @code{robots} meta-tag.
35162 Defaults to @samp{("noindex" "nofollow")}.
35166 @deftypevr {@code{cgit-configuration} parameter} string root-desc
35167 Text printed below the heading on the repository index page.
35169 Defaults to @samp{"a fast webinterface for the git dscm"}.
35173 @deftypevr {@code{cgit-configuration} parameter} string root-readme
35174 The content of the file specified with this option will be included
35175 verbatim below the ``about'' link on the repository index page.
35177 Defaults to @samp{""}.
35181 @deftypevr {@code{cgit-configuration} parameter} string root-title
35182 Text printed as heading on the repository index page.
35184 Defaults to @samp{""}.
35188 @deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path
35189 If set to @samp{#t} and repository-directory is enabled,
35190 repository-directory will recurse into directories whose name starts
35191 with a period. Otherwise, repository-directory will stay away from such
35192 directories, considered as ``hidden''. Note that this does not apply to
35193 the @file{.git} directory in non-bare repos.
35195 Defaults to @samp{#f}.
35199 @deftypevr {@code{cgit-configuration} parameter} list snapshots
35200 Text which specifies the default set of snapshot formats that cgit
35201 generates links for.
35203 Defaults to @samp{()}.
35207 @deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory
35208 Name of the directory to scan for repositories (represents
35211 Defaults to @samp{"/srv/git"}.
35215 @deftypevr {@code{cgit-configuration} parameter} string section
35216 The name of the current repository section - all repositories defined
35217 after this option will inherit the current section name.
35219 Defaults to @samp{""}.
35223 @deftypevr {@code{cgit-configuration} parameter} string section-sort
35224 Flag which, when set to @samp{1}, will sort the sections on the
35225 repository listing by name.
35227 Defaults to @samp{""}.
35231 @deftypevr {@code{cgit-configuration} parameter} integer section-from-path
35232 A number which, if defined prior to repository-directory, specifies how
35233 many path elements from each repo path to use as a default section name.
35235 Defaults to @samp{0}.
35239 @deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs?
35240 If set to @samp{#t} shows side-by-side diffs instead of unidiffs per
35243 Defaults to @samp{#f}.
35247 @deftypevr {@code{cgit-configuration} parameter} file-object source-filter
35248 Specifies a command which will be invoked to format plaintext blobs in
35251 Defaults to @samp{""}.
35255 @deftypevr {@code{cgit-configuration} parameter} integer summary-branches
35256 Specifies the number of branches to display in the repository ``summary''
35259 Defaults to @samp{10}.
35263 @deftypevr {@code{cgit-configuration} parameter} integer summary-log
35264 Specifies the number of log entries to display in the repository
35267 Defaults to @samp{10}.
35271 @deftypevr {@code{cgit-configuration} parameter} integer summary-tags
35272 Specifies the number of tags to display in the repository ``summary''
35275 Defaults to @samp{10}.
35279 @deftypevr {@code{cgit-configuration} parameter} string strict-export
35280 Filename which, if specified, needs to be present within the repository
35281 for cgit to allow access to that repository.
35283 Defaults to @samp{""}.
35287 @deftypevr {@code{cgit-configuration} parameter} string virtual-root
35288 URL which, if specified, will be used as root for all cgit links.
35290 Defaults to @samp{"/"}.
35294 @deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories
35295 A list of @dfn{cgit-repo} records to use with config.
35297 Defaults to @samp{()}.
35299 Available @code{repository-cgit-configuration} fields are:
35301 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots
35302 A mask of snapshot formats for this repo that cgit generates links for,
35303 restricted by the global @code{snapshots} setting.
35305 Defaults to @samp{()}.
35309 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter
35310 Override the default @code{source-filter}.
35312 Defaults to @samp{""}.
35316 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string url
35317 The relative URL used to access the repository.
35319 Defaults to @samp{""}.
35323 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter
35324 Override the default @code{about-filter}.
35326 Defaults to @samp{""}.
35330 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort
35331 Flag which, when set to @samp{age}, enables date ordering in the branch
35332 ref list, and when set to @samp{name} enables ordering by branch name.
35334 Defaults to @samp{""}.
35338 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url
35339 A list of URLs which can be used to clone repo.
35341 Defaults to @samp{()}.
35345 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter
35346 Override the default @code{commit-filter}.
35348 Defaults to @samp{""}.
35352 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort
35353 Flag which, when set to @samp{date}, enables strict date ordering in the
35354 commit log, and when set to @samp{topo} enables strict topological
35357 Defaults to @samp{""}.
35361 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch
35362 The name of the default branch for this repository. If no such branch
35363 exists in the repository, the first branch name (when sorted) is used as
35364 default instead. By default branch pointed to by HEAD, or ``master'' if
35365 there is no suitable HEAD.
35367 Defaults to @samp{""}.
35371 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc
35372 The value to show as repository description.
35374 Defaults to @samp{""}.
35378 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage
35379 The value to show as repository homepage.
35381 Defaults to @samp{""}.
35385 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter
35386 Override the default @code{email-filter}.
35388 Defaults to @samp{""}.
35392 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph?
35393 A flag which can be used to disable the global setting
35394 @code{enable-commit-graph?}.
35396 Defaults to @samp{disabled}.
35400 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount?
35401 A flag which can be used to disable the global setting
35402 @code{enable-log-filecount?}.
35404 Defaults to @samp{disabled}.
35408 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount?
35409 A flag which can be used to disable the global setting
35410 @code{enable-log-linecount?}.
35412 Defaults to @samp{disabled}.
35416 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches?
35417 Flag which, when set to @code{#t}, will make cgit display remote
35418 branches in the summary and refs views.
35420 Defaults to @samp{disabled}.
35424 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links?
35425 A flag which can be used to override the global setting
35426 @code{enable-subject-links?}.
35428 Defaults to @samp{disabled}.
35432 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving?
35433 A flag which can be used to override the global setting
35434 @code{enable-html-serving?}.
35436 Defaults to @samp{disabled}.
35440 @deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide?
35441 Flag which, when set to @code{#t}, hides the repository from the
35444 Defaults to @samp{#f}.
35448 @deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore?
35449 Flag which, when set to @samp{#t}, ignores the repository.
35451 Defaults to @samp{#f}.
35455 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo
35456 URL which specifies the source of an image which will be used as a logo
35457 on this repo’s pages.
35459 Defaults to @samp{""}.
35463 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link
35464 URL loaded when clicking on the cgit logo image.
35466 Defaults to @samp{""}.
35470 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter
35471 Override the default @code{owner-filter}.
35473 Defaults to @samp{""}.
35477 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link
35478 Text which will be used as the formatstring for a hyperlink when a
35479 submodule is printed in a directory listing. The arguments for the
35480 formatstring are the path and SHA1 of the submodule commit.
35482 Defaults to @samp{""}.
35486 @deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path
35487 Text which will be used as the formatstring for a hyperlink when a
35488 submodule with the specified subdirectory path is printed in a directory
35491 Defaults to @samp{()}.
35495 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats
35496 Override the default maximum statistics period.
35498 Defaults to @samp{""}.
35502 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string name
35503 The value to show as repository name.
35505 Defaults to @samp{""}.
35509 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner
35510 A value used to identify the owner of the repository.
35512 Defaults to @samp{""}.
35516 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string path
35517 An absolute path to the repository directory.
35519 Defaults to @samp{""}.
35523 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme
35524 A path (relative to repo) which specifies a file to include verbatim as
35525 the ``About'' page for this repo.
35527 Defaults to @samp{""}.
35531 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string section
35532 The name of the current repository section - all repositories defined
35533 after this option will inherit the current section name.
35535 Defaults to @samp{""}.
35539 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options
35540 Extra options will be appended to cgitrc file.
35542 Defaults to @samp{()}.
35548 @deftypevr {@code{cgit-configuration} parameter} list extra-options
35549 Extra options will be appended to cgitrc file.
35551 Defaults to @samp{()}.
35556 @c %end of fragment
35558 However, it could be that you just want to get a @code{cgitrc} up and
35559 running. In that case, you can pass an @code{opaque-cgit-configuration}
35560 as a record to @code{cgit-service-type}. As its name indicates, an
35561 opaque configuration does not have easy reflective capabilities.
35563 Available @code{opaque-cgit-configuration} fields are:
35565 @deftypevr {@code{opaque-cgit-configuration} parameter} package cgit
35569 @deftypevr {@code{opaque-cgit-configuration} parameter} string string
35570 The contents of the @code{cgitrc}, as a string.
35573 For example, if your @code{cgitrc} is just the empty string, you
35574 could instantiate a cgit service like this:
35577 (service cgit-service-type
35578 (opaque-cgit-configuration
35582 @subsubheading Gitolite Service
35584 @cindex Gitolite service
35585 @cindex Git, hosting
35586 @uref{https://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
35587 repositories on a central server.
35589 Gitolite can handle multiple repositories and users, and supports flexible
35590 configuration of the permissions for the users on the repositories.
35592 The following example will configure Gitolite using the default @code{git}
35593 user, and the provided SSH public key.
35596 (service gitolite-service-type
35597 (gitolite-configuration
35598 (admin-pubkey (plain-file
35600 "ssh-rsa AAAA... guix@@example.com"))))
35603 Gitolite is configured through a special admin repository which you can clone,
35604 for example, if you setup Gitolite on @code{example.com}, you would run the
35605 following command to clone the admin repository.
35608 git clone git@@example.com:gitolite-admin
35611 When the Gitolite service is activated, the provided @code{admin-pubkey} will
35612 be inserted in to the @file{keydir} directory in the gitolite-admin
35613 repository. If this results in a change in the repository, it will be
35614 committed using the message ``gitolite setup by GNU Guix''.
35616 @deftp {Data Type} gitolite-configuration
35617 Data type representing the configuration for @code{gitolite-service-type}.
35620 @item @code{package} (default: @var{gitolite})
35621 Gitolite package to use. There are optional Gitolite dependencies that
35622 are not included in the default package, such as Redis and git-annex.
35623 These features can be made available by using the @code{make-gitolite}
35624 procedure in the @code{(gnu packages version-control}) module to produce
35625 a variant of Gitolite with the desired additional dependencies.
35627 The following code returns a package in which the Redis and git-annex
35628 programs can be invoked by Gitolite's scripts:
35631 (use-modules (gnu packages databases)
35632 (gnu packages haskell-apps)
35633 (gnu packages version-control))
35634 (make-gitolite (list redis git-annex))
35637 @item @code{user} (default: @var{git})
35638 User to use for Gitolite. This will be user that you use when accessing
35641 @item @code{group} (default: @var{git})
35642 Group to use for Gitolite.
35644 @item @code{home-directory} (default: @var{"/var/lib/gitolite"})
35645 Directory in which to store the Gitolite configuration and repositories.
35647 @item @code{rc-file} (default: @var{(gitolite-rc-file)})
35648 A ``file-like'' object (@pxref{G-Expressions, file-like objects}),
35649 representing the configuration for Gitolite.
35651 @item @code{admin-pubkey} (default: @var{#f})
35652 A ``file-like'' object (@pxref{G-Expressions, file-like objects}) used to
35653 setup Gitolite. This will be inserted in to the @file{keydir} directory
35654 within the gitolite-admin repository.
35656 To specify the SSH key as a string, use the @code{plain-file} function.
35659 (plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com")
35665 @deftp {Data Type} gitolite-rc-file
35666 Data type representing the Gitolite RC file.
35669 @item @code{umask} (default: @code{#o0077})
35670 This controls the permissions Gitolite sets on the repositories and their
35673 A value like @code{#o0027} will give read access to the group used by Gitolite
35674 (by default: @code{git}). This is necessary when using Gitolite with software
35675 like cgit or gitweb.
35677 @item @code{unsafe-pattern} (default: @code{#f})
35678 An optional Perl regular expression for catching unsafe configurations in
35679 the configuration file. See
35680 @uref{https://gitolite.com/gitolite/git-config.html#compensating-for-unsafe_patt,
35681 Gitolite's documentation} for more information.
35683 When the value is not @code{#f}, it should be a string containing a Perl
35684 regular expression, such as @samp{"[`~#\$\&()|;<>]"}, which is the default
35685 value used by gitolite. It rejects any special character in configuration
35686 that might be interpreted by a shell, which is useful when sharing the
35687 administration burden with other people that do not otherwise have shell
35688 access on the server.
35690 @item @code{git-config-keys} (default: @code{""})
35691 Gitolite allows you to set git config values using the @samp{config}
35692 keyword. This setting allows control over the config keys to accept.
35694 @item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
35695 Set the role names allowed to be used by users running the perms command.
35697 @item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")})
35698 This setting controls the commands and features to enable within Gitolite.
35704 @subsubheading Gitile Service
35706 @cindex Gitile service
35708 @uref{https://git.lepiller.eu/gitile, Gitile} is a Git forge for viewing
35709 public git repository contents from a web browser.
35711 Gitile works best in collaboration with Gitolite, and will serve the public
35712 repositories from Gitolite by default. The service should listen only on
35713 a local port, and a webserver should be configured to serve static resources.
35714 The gitile service provides an easy way to extend the Nginx service for
35715 that purpose (@pxref{NGINX}).
35717 The following example will configure Gitile to serve repositories from a
35718 custom location, with some default messages for the home page and the
35722 (service gitile-service-type
35723 (gitile-configuration
35724 (repositories "/srv/git")
35725 (base-git-url "https://myweb.site/git")
35726 (index-title "My git repositories")
35727 (intro '((p "This is all my public work!")))
35728 (footer '((p "This is the end")))
35729 (nginx-server-block
35730 (nginx-server-configuration
35732 "/etc/letsencrypt/live/myweb.site/fullchain.pem")
35733 (ssl-certificate-key
35734 "/etc/letsencrypt/live/myweb.site/privkey.pem")
35735 (listen '("443 ssl http2" "[::]:443 ssl http2"))
35738 ;; Allow for https anonymous fetch on /git/ urls.
35739 (git-http-nginx-location-configuration
35740 (git-http-configuration
35742 (git-root "/var/lib/gitolite/repositories")))))))))
35745 In addition to the configuration record, you should configure your git
35746 repositories to contain some optional information. First, your public
35747 repositories need to contain the @file{git-daemon-export-ok} magic file
35748 that allows Git to export the repository. Gitile uses the presence of this
35749 file to detect public repositories it should make accessible. To do so with
35750 Gitolite for instance, modify your @file{conf/gitolite.conf} to include
35751 this in the repositories you want to make public:
35758 In addition, Gitile can read the repository configuration to display more
35759 information on the repository. Gitile uses the gitweb namespace for its
35760 configuration. As an example, you can use the following in your
35761 @file{conf/gitolite.conf}:
35766 desc = A long description, optionally with <i>HTML</i>, shown on the index page
35767 config gitweb.name = The Foo Project
35768 config gitweb.synopsis = A short description, shown on the main page of the project
35771 Do not forget to commit and push these changes once you are satisfied. You
35772 may need to change your gitolite configuration to allow the previous
35773 configuration options to be set. One way to do that is to add the
35774 following service definition:
35777 (service gitolite-service-type
35778 (gitolite-configuration
35779 (admin-pubkey (local-file "key.pub"))
35783 ;; Allow to set any configuration key
35784 (git-config-keys ".*")
35785 ;; Allow any text as a valid configuration value
35786 (unsafe-patt "^$")))))
35789 @deftp {Data Type} gitile-configuration
35790 Data type representing the configuration for @code{gitile-service-type}.
35793 @item @code{package} (default: @var{gitile})
35794 Gitile package to use.
35796 @item @code{host} (default: @code{"localhost"})
35797 The host on which gitile is listening.
35799 @item @code{port} (default: @code{8080})
35800 The port on which gitile is listening.
35802 @item @code{database} (default: @code{"/var/lib/gitile/gitile-db.sql"})
35803 The location of the database.
35805 @item @code{repositories} (default: @code{"/var/lib/gitolite/repositories"})
35806 The location of the repositories. Note that only public repositories will
35807 be shown by Gitile. To make a repository public, add an empty
35808 @file{git-daemon-export-ok} file at the root of that repository.
35810 @item @code{base-git-url}
35811 The base git url that will be used to show clone commands.
35813 @item @code{index-title} (default: @code{"Index"})
35814 The page title for the index page that lists all the available repositories.
35816 @item @code{intro} (default: @code{'()})
35817 The intro content, as a list of sxml expressions. This is shown above the list
35818 of repositories, on the index page.
35820 @item @code{footer} (default: @code{'()})
35821 The footer content, as a list of sxml expressions. This is shown on every
35822 page served by Gitile.
35824 @item @code{nginx-server-block}
35825 An nginx server block that will be extended and used as a reverse proxy by
35826 Gitile to serve its pages, and as a normal web server to serve its assets.
35828 You can use this block to add more custom URLs to your domain, such as a
35829 @code{/git/} URL for anonymous clones, or serving any other files you would
35835 @node Game Services
35836 @subsection Game Services
35838 @subsubheading The Battle for Wesnoth Service
35840 @uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn
35841 based tactical strategy game, with several single player campaigns, and
35842 multiplayer games (both networked and local).
35844 @defvar {Scheme Variable} wesnothd-service-type
35845 Service type for the wesnothd service. Its value must be a
35846 @code{wesnothd-configuration} object. To run wesnothd in the default
35847 configuration, instantiate it as:
35850 (service wesnothd-service-type)
35854 @deftp {Data Type} wesnothd-configuration
35855 Data type representing the configuration of @command{wesnothd}.
35858 @item @code{package} (default: @code{wesnoth-server})
35859 The wesnoth server package to use.
35861 @item @code{port} (default: @code{15000})
35862 The port to bind the server to.
35867 @node PAM Mount Service
35868 @subsection PAM Mount Service
35871 The @code{(gnu services pam-mount)} module provides a service allowing
35872 users to mount volumes when they log in. It should be able to mount any
35873 volume format supported by the system.
35875 @defvar {Scheme Variable} pam-mount-service-type
35876 Service type for PAM Mount support.
35879 @deftp {Data Type} pam-mount-configuration
35880 Data type representing the configuration of PAM Mount.
35882 It takes the following parameters:
35886 The configuration rules that will be used to generate
35887 @file{/etc/security/pam_mount.conf.xml}.
35889 The configuration rules are SXML elements (@pxref{SXML,,, guile, GNU
35890 Guile Reference Manual}), and the default ones don't mount anything for
35894 `((debug (@@ (enable "0")))
35895 (mntoptions (@@ (allow ,(string-join
35896 '("nosuid" "nodev" "loop"
35897 "encryption" "fsck" "nonempty"
35898 "allow_root" "allow_other")
35900 (mntoptions (@@ (require "nosuid,nodev")))
35901 (logout (@@ (wait "0")
35905 (mkmountpoint (@@ (enable "1")
35909 Some @code{volume} elements must be added to automatically mount volumes
35910 at login. Here's an example allowing the user @code{alice} to mount her
35911 encrypted @env{HOME} directory and allowing the user @code{bob} to mount
35912 the partition where he stores his data:
35915 (define pam-mount-rules
35916 `((debug (@@ (enable "0")))
35917 (volume (@@ (user "alice")
35920 (mountpoint "/home/alice")))
35921 (volume (@@ (user "bob")
35924 (mountpoint "/home/bob/data")
35925 (options "defaults,autodefrag,compress")))
35926 (mntoptions (@@ (allow ,(string-join
35927 '("nosuid" "nodev" "loop"
35928 "encryption" "fsck" "nonempty"
35929 "allow_root" "allow_other")
35931 (mntoptions (@@ (require "nosuid,nodev")))
35932 (logout (@@ (wait "0")
35936 (mkmountpoint (@@ (enable "1")
35937 (remove "true")))))
35939 (service pam-mount-service-type
35940 (pam-mount-configuration
35941 (rules pam-mount-rules)))
35944 The complete list of possible options can be found in the man page for
35945 @uref{http://pam-mount.sourceforge.net/pam_mount.conf.5.html, pam_mount.conf}.
35950 @node Guix Services
35951 @subsection Guix Services
35953 @subsubheading Guix Build Coordinator
35954 The @uref{https://git.cbaines.net/guix/build-coordinator/,Guix Build
35955 Coordinator} aids in distributing derivation builds among machines
35956 running an @dfn{agent}. The build daemon is still used to build the
35957 derivations, but the Guix Build Coordinator manages allocating builds
35958 and working with the results.
35960 The Guix Build Coordinator consists of one @dfn{coordinator}, and one or
35961 more connected @dfn{agent} processes. The coordinator process handles
35962 clients submitting builds, and allocating builds to agents. The agent
35963 processes talk to a build daemon to actually perform the builds, then
35964 send the results back to the coordinator.
35966 There is a script to run the coordinator component of the Guix Build
35967 Coordinator, but the Guix service uses a custom Guile script instead, to
35968 provide better integration with G-expressions used in the configuration.
35970 @defvar {Scheme Variable} guix-build-coordinator-service-type
35971 Service type for the Guix Build Coordinator. Its value must be a
35972 @code{guix-build-coordinator-configuration} object.
35975 @deftp {Data Type} guix-build-coordinator-configuration
35976 Data type representing the configuration of the Guix Build Coordinator.
35979 @item @code{package} (default: @code{guix-build-coordinator})
35980 The Guix Build Coordinator package to use.
35982 @item @code{user} (default: @code{"guix-build-coordinator"})
35983 The system user to run the service as.
35985 @item @code{group} (default: @code{"guix-build-coordinator"})
35986 The system group to run the service as.
35988 @item @code{database-uri-string} (default: @code{"sqlite:///var/lib/guix-build-coordinator/guix_build_coordinator.db"})
35989 The URI to use for the database.
35991 @item @code{agent-communication-uri} (default: @code{"http://0.0.0.0:8745"})
35992 The URI describing how to listen to requests from agent processes.
35994 @item @code{client-communication-uri} (default: @code{"http://127.0.0.1:8746"})
35995 The URI describing how to listen to requests from clients. The client
35996 API allows submitting builds and currently isn't authenticated, so take
35997 care when configuring this value.
35999 @item @code{allocation-strategy} (default: @code{#~basic-build-allocation-strategy})
36000 A G-expression for the allocation strategy to be used. This is a
36001 procedure that takes the datastore as an argument and populates the
36002 allocation plan in the database.
36004 @item @code{hooks} (default: @var{'()})
36005 An association list of hooks. These provide a way to execute arbitrary
36006 code upon certain events, like a build result being processed.
36008 @item @code{parallel-hooks} (default: @var{'()})
36009 Hooks can be configured to run in parallel. This parameter is an
36010 association list of hooks to do in parallel, where the key is the symbol
36011 for the hook and the value is the number of threads to run.
36013 @item @code{guile} (default: @code{guile-3.0-latest})
36014 The Guile package with which to run the Guix Build Coordinator.
36019 @defvar {Scheme Variable} guix-build-coordinator-agent-service-type
36020 Service type for a Guix Build Coordinator agent. Its value must be a
36021 @code{guix-build-coordinator-agent-configuration} object.
36024 @deftp {Data Type} guix-build-coordinator-agent-configuration
36025 Data type representing the configuration a Guix Build Coordinator agent.
36028 @item @code{package} (default: @code{guix-build-coordinator/agent-only})
36029 The Guix Build Coordinator package to use.
36031 @item @code{user} (default: @code{"guix-build-coordinator-agent"})
36032 The system user to run the service as.
36034 @item @code{coordinator} (default: @code{"http://localhost:8745"})
36035 The URI to use when connecting to the coordinator.
36037 @item @code{authentication}
36038 Record describing how this agent should authenticate with the
36039 coordinator. Possible record types are described below.
36041 @item @code{systems} (default: @code{#f})
36042 The systems for which this agent should fetch builds. The agent process
36043 will use the current system it's running on as the default.
36045 @item @code{max-parallel-builds} (default: @code{1})
36046 The number of builds to perform in parallel.
36048 @item @code{max-allocated-builds} (default: @code{#f})
36049 The maximum number of builds this agent can be allocated.
36051 @item @code{max-1min-load-average} (default: @code{#f})
36052 Load average value to look at when considering starting new builds, if
36053 the 1 minute load average exceeds this value, the agent will wait before
36054 starting new builds.
36056 This will be unspecified if the value is @code{#f}, and the agent will
36057 use the number of cores reported by the system as the max 1 minute load
36060 @item @code{derivation-substitute-urls} (default: @code{#f})
36061 URLs from which to attempt to fetch substitutes for derivations, if the
36062 derivations aren't already available.
36064 @item @code{non-derivation-substitute-urls} (default: @code{#f})
36065 URLs from which to attempt to fetch substitutes for build inputs, if the
36066 input store items aren't already available.
36071 @deftp {Data Type} guix-build-coordinator-agent-password-auth
36072 Data type representing an agent authenticating with a coordinator via a
36077 The UUID of the agent. This should be generated by the coordinator
36078 process, stored in the coordinator database, and used by the intended
36081 @item @code{password}
36082 The password to use when connecting to the coordinator.
36087 @deftp {Data Type} guix-build-coordinator-agent-password-file-auth
36088 Data type representing an agent authenticating with a coordinator via a
36089 UUID and password read from a file.
36093 The UUID of the agent. This should be generated by the coordinator
36094 process, stored in the coordinator database, and used by the intended
36097 @item @code{password-file}
36098 A file containing the password to use when connecting to the
36104 @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth
36105 Data type representing an agent authenticating with a coordinator via a
36106 dynamic auth token and agent name.
36109 @item @code{agent-name}
36110 Name of an agent, this is used to match up to an existing entry in the
36111 database if there is one. When no existing entry is found, a new entry
36112 is automatically added.
36115 Dynamic auth token, this is created and stored in the coordinator
36116 database, and is used by the agent to authenticate.
36121 @deftp {Data Type} guix-build-coordinator-agent-dynamic-auth-with-file
36122 Data type representing an agent authenticating with a coordinator via a
36123 dynamic auth token read from a file and agent name.
36126 @item @code{agent-name}
36127 Name of an agent, this is used to match up to an existing entry in the
36128 database if there is one. When no existing entry is found, a new entry
36129 is automatically added.
36131 @item @code{token-file}
36132 File containing the dynamic auth token, this is created and stored in
36133 the coordinator database, and is used by the agent to authenticate.
36138 The Guix Build Coordinator package contains a script to query an
36139 instance of the Guix Data Service for derivations to build, and then
36140 submit builds for those derivations to the coordinator. The service
36141 type below assists in running this script. This is an additional tool
36142 that may be useful when building derivations contained within an
36143 instance of the Guix Data Service.
36145 @defvar {Scheme Variable} guix-build-coordinator-queue-builds-service-type
36146 Service type for the
36147 guix-build-coordinator-queue-builds-from-guix-data-service script. Its
36148 value must be a @code{guix-build-coordinator-queue-builds-configuration}
36152 @deftp {Data Type} guix-build-coordinator-queue-builds-configuration
36153 Data type representing the options to the queue builds from guix data
36157 @item @code{package} (default: @code{guix-build-coordinator})
36158 The Guix Build Coordinator package to use.
36160 @item @code{user} (default: @code{"guix-build-coordinator-queue-builds"})
36161 The system user to run the service as.
36163 @item @code{coordinator} (default: @code{"http://localhost:8746"})
36164 The URI to use when connecting to the coordinator.
36166 @item @code{systems} (default: @code{#f})
36167 The systems for which to fetch derivations to build.
36169 @item @code{systems-and-targets} (default: @code{#f})
36170 An association list of system and target pairs for which to fetch
36171 derivations to build.
36173 @item @code{guix-data-service} (default: @code{"https://data.guix.gnu.org"})
36174 The Guix Data Service instance from which to query to find out about
36175 derivations to build.
36177 @item @code{guix-data-service-build-server-id} (default: @code{#f})
36178 The Guix Data Service build server ID corresponding to the builds being
36179 submitted. Providing this speeds up the submitting of builds as
36180 derivations that have already been submitted can be skipped before
36181 asking the coordinator to build them.
36183 @item @code{processed-commits-file} (default: @code{"/var/cache/guix-build-coordinator-queue-builds/processed-commits"})
36184 A file to record which commits have been processed, to avoid needlessly
36185 processing them again if the service is restarted.
36190 @subsubheading Guix Data Service
36191 The @uref{http://data.guix.gnu.org,Guix Data Service} processes, stores
36192 and provides data about GNU Guix. This includes information about
36193 packages, derivations and lint warnings.
36195 The data is stored in a PostgreSQL database, and available through a web
36198 @defvar {Scheme Variable} guix-data-service-type
36199 Service type for the Guix Data Service. Its value must be a
36200 @code{guix-data-service-configuration} object. The service optionally
36201 extends the getmail service, as the guix-commits mailing list is used to
36202 find out about changes in the Guix git repository.
36205 @deftp {Data Type} guix-data-service-configuration
36206 Data type representing the configuration of the Guix Data Service.
36209 @item @code{package} (default: @code{guix-data-service})
36210 The Guix Data Service package to use.
36212 @item @code{user} (default: @code{"guix-data-service"})
36213 The system user to run the service as.
36215 @item @code{group} (default: @code{"guix-data-service"})
36216 The system group to run the service as.
36218 @item @code{port} (default: @code{8765})
36219 The port to bind the web service to.
36221 @item @code{host} (default: @code{"127.0.0.1"})
36222 The host to bind the web service to.
36224 @item @code{getmail-idle-mailboxes} (default: @code{#f})
36225 If set, this is the list of mailboxes that the getmail service will be
36226 configured to listen to.
36228 @item @code{commits-getmail-retriever-configuration} (default: @code{#f})
36229 If set, this is the @code{getmail-retriever-configuration} object with
36230 which to configure getmail to fetch mail from the guix-commits mailing
36233 @item @code{extra-options} (default: @var{'()})
36234 Extra command line options for @code{guix-data-service}.
36236 @item @code{extra-process-jobs-options} (default: @var{'()})
36237 Extra command line options for @code{guix-data-service-process-jobs}.
36242 @subsubheading Nar Herder
36243 The @uref{https://git.cbaines.net/guix/nar-herder/about/,Nar Herder} is
36244 a utility for managing a collection of nars.
36246 @defvar {Scheme Variable} nar-herder-type
36247 Service type for the Guix Data Service. Its value must be a
36248 @code{nar-herder-configuration} object. The service optionally
36249 extends the getmail service, as the guix-commits mailing list is used to
36250 find out about changes in the Guix git repository.
36253 @deftp {Data Type} nar-herder-configuration
36254 Data type representing the configuration of the Guix Data Service.
36257 @item @code{package} (default: @code{nar-herder})
36258 The Nar Herder package to use.
36260 @item @code{user} (default: @code{"nar-herder"})
36261 The system user to run the service as.
36263 @item @code{group} (default: @code{"nar-herder"})
36264 The system group to run the service as.
36266 @item @code{port} (default: @code{8734})
36267 The port to bind the server to.
36269 @item @code{host} (default: @code{"127.0.0.1"})
36270 The host to bind the server to.
36272 @item @code{mirror} (default: @code{#f})
36273 Optional URL of the other Nar Herder instance which should be mirrored.
36274 This means that this Nar Herder instance will download it's database,
36275 and keep it up to date.
36277 @item @code{database} (default: @code{"/var/lib/nar-herder/nar_herder.db"})
36278 Location for the database. If this Nar Herder instance is mirroring
36279 another, the database will be downloaded if it doesn't exist. If this
36280 Nar Herder instance isn't mirroring another, an empty database will be
36283 @item @code{database-dump} (default: @code{"/var/lib/nar-herder/nar_herder_dump.db"})
36284 Location of the database dump. This is created and regularly updated by
36285 taking a copy of the database. This is the version of the database that
36286 is available to download.
36288 @item @code{storage} (default: @code{#f})
36289 Optional location in which to store nars.
36291 @item @code{storage-limit} (default: @code{"none"})
36292 Limit in bytes for the nars stored in the storage location. This can
36293 also be set to ``none'' so that there is no limit.
36295 When the storage location exceeds this size, nars are removed according
36296 to the nar removal criteria.
36298 @item @code{storage-nar-removal-criteria} (default: @code{'()})
36299 Criteria used to remove nars from the storage location. These are used
36300 in conjunction with the storage limit.
36302 When the storage location exceeds the storage limit size, nars will be
36303 checked against the nar removal criteria and if any of the criteria
36304 match, they will be removed. This will continue until the storage
36305 location is below the storage limit size.
36307 Each criteria is specified by a string, then an equals sign, then
36308 another string. Currently, only one criteria is supported, checking if a
36309 nar is stored on another Nar Herder instance.
36311 @item @code{ttl} (default: @code{#f})
36312 Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
36313 (TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
36314 days, @code{1m} means 1 month, and so on.
36316 This allows the user's Guix to keep substitute information in cache for
36319 @item @code{negative-ttl} (default: @code{#f})
36320 Similarly produce @code{Cache-Control} HTTP headers to advertise the
36321 time-to-live (TTL) of @emph{negative} lookups---missing store items, for
36322 which the HTTP 404 code is returned. By default, no negative TTL is
36325 @item @code{log-level} (default: @code{'DEBUG})
36326 Log level to use, specify a log level like @code{'INFO} to stop logging
36327 individual requests.
36332 @node Linux Services
36333 @subsection Linux Services
36336 @cindex out of memory killer
36338 @cindex early out of memory daemon
36339 @subsubheading Early OOM Service
36341 @uref{https://github.com/rfjakob/earlyoom,Early OOM}, also known as
36342 Earlyoom, is a minimalist out of memory (OOM) daemon that runs in user
36343 space and provides a more responsive and configurable alternative to the
36344 in-kernel OOM killer. It is useful to prevent the system from becoming
36345 unresponsive when it runs out of memory.
36347 @deffn {Scheme Variable} earlyoom-service-type
36348 The service type for running @command{earlyoom}, the Early OOM daemon.
36349 Its value must be a @code{earlyoom-configuration} object, described
36350 below. The service can be instantiated in its default configuration
36354 (service earlyoom-service-type)
36358 @deftp {Data Type} earlyoom-configuration
36359 This is the configuration record for the @code{earlyoom-service-type}.
36362 @item @code{earlyoom} (default: @var{earlyoom})
36363 The Earlyoom package to use.
36365 @item @code{minimum-available-memory} (default: @code{10})
36366 The threshold for the minimum @emph{available} memory, in percentages.
36368 @item @code{minimum-free-swap} (default: @code{10})
36369 The threshold for the minimum free swap memory, in percentages.
36371 @item @code{prefer-regexp} (default: @code{#f})
36372 A regular expression (as a string) to match the names of the processes
36373 that should be preferably killed.
36375 @item @code{avoid-regexp} (default: @code{#f})
36376 A regular expression (as a string) to match the names of the processes
36377 that should @emph{not} be killed.
36379 @item @code{memory-report-interval} (default: @code{0})
36380 The interval in seconds at which a memory report is printed. It is
36381 disabled by default.
36383 @item @code{ignore-positive-oom-score-adj?} (default: @code{#f})
36384 A boolean indicating whether the positive adjustments set in
36385 @file{/proc/*/oom_score_adj} should be ignored.
36387 @item @code{show-debug-messages?} (default: @code{#f})
36388 A boolean indicating whether debug messages should be printed. The logs
36389 are saved at @file{/var/log/earlyoom.log}.
36391 @item @code{send-notification-command} (default: @code{#f})
36392 This can be used to provide a custom command used for sending
36398 @cindex kernel module loader
36399 @subsubheading Kernel Module Loader Service
36401 The kernel module loader service allows one to load loadable kernel
36402 modules at boot. This is especially useful for modules that don't
36403 autoload and need to be manually loaded, as is the case with
36406 @deffn {Scheme Variable} kernel-module-loader-service-type
36407 The service type for loading loadable kernel modules at boot with
36408 @command{modprobe}. Its value must be a list of strings representing
36409 module names. For example loading the drivers provided by
36410 @code{ddcci-driver-linux}, in debugging mode by passing some module
36411 parameters, can be done as follow:
36414 (use-modules (gnu) (gnu services))
36415 (use-package-modules linux)
36416 (use-service-modules linux)
36418 (define ddcci-config
36419 (plain-file "ddcci.conf"
36420 "options ddcci dyndbg delay=120"))
36424 (services (cons* (service kernel-module-loader-service-type
36425 '("ddcci" "ddcci_backlight"))
36426 (simple-service 'ddcci-config etc-service-type
36427 (list `("modprobe.d/ddcci.conf"
36430 (kernel-loadable-modules (list ddcci-driver-linux)))
36435 @cindex Platform Reliability, Availability and Serviceability daemon
36436 @subsubheading Rasdaemon Service
36438 The Rasdaemon service provides a daemon which monitors platform
36439 @acronym{RAS, Reliability@comma{} Availability@comma{} and Serviceability} reports from
36440 Linux kernel trace events, logging them to syslogd.
36442 Reliability, Availability and Serviceability is a concept used on servers meant
36443 to measure their robustness.
36445 @strong{Relability} is the probability that a system will produce correct
36449 @item Generally measured as Mean Time Between Failures (MTBF), and
36450 @item Enhanced by features that help to avoid, detect and repair hardware
36454 @strong{Availability} is the probability that a system is operational at a
36458 @item Generally measured as a percentage of downtime per a period of time, and
36459 @item Often uses mechanisms to detect and correct hardware faults in runtime.
36462 @strong{Serviceability} is the simplicity and speed with which a system can be
36463 repaired or maintained:
36466 @item Generally measured on Mean Time Between Repair (MTBR).
36470 Among the monitoring measures, the most usual ones include:
36473 @item CPU – detect errors at instruction execution and at L1/L2/L3 caches;
36474 @item Memory – add error correction logic (ECC) to detect and correct errors;
36475 @item I/O – add CRC checksums for transferred data;
36476 @item Storage – RAID, journal file systems, checksums, Self-Monitoring,
36477 Analysis and Reporting Technology (SMART).
36480 By monitoring the number of occurrences of error detections, it is possible to
36481 identify if the probability of hardware errors is increasing, and, on such
36482 case, do a preventive maintenance to replace a degraded component while those
36483 errors are correctable.
36485 For detailed information about the types of error events gathered and how to
36486 make sense of them, see the kernel administrator's guide at
36487 @url{https://www.kernel.org/doc/html/latest/admin-guide/ras.html}.
36489 @defvr {Scheme Variable} rasdaemon-service-type
36490 Service type for the @command{rasdaemon} service. It accepts a
36491 @code{rasdaemon-configuration} object. Instantiating like
36494 (service rasdaemon-service-type)
36497 will load with a default configuration, which monitors all events and logs to
36501 @deftp {Data Type} rasdaemon-configuration
36502 The data type representing the configuration of @command{rasdaemon}.
36505 @item @code{record?} (default: @code{#f})
36507 A boolean indicating whether to record the events in an SQLite database. This
36508 provides a more structured access to the information contained in the log file.
36509 The database location is hard-coded to @file{/var/lib/rasdaemon/ras-mc_event.db}.
36515 @cindex compressed swap
36516 @cindex Compressed RAM-based block devices
36517 @subsubheading Zram Device Service
36519 The Zram device service provides a compressed swap device in system
36520 memory. The Linux Kernel documentation has more information about
36521 @uref{https://www.kernel.org/doc/html/latest/admin-guide/blockdev/zram.html,zram}
36524 @deffn {Scheme Variable} zram-device-service-type
36525 This service creates the zram block device, formats it as swap and
36526 enables it as a swap device. The service's value is a
36527 @code{zram-device-configuration} record.
36529 @deftp {Data Type} zram-device-configuration
36530 This is the data type representing the configuration for the zram-device
36534 @item @code{size} (default @code{"1G"})
36535 This is the amount of space you wish to provide for the zram device. It
36536 accepts a string and can be a number of bytes or use a suffix, eg.:
36537 @code{"512M"} or @code{1024000}.
36538 @item @code{compression-algorithm} (default @code{'lzo})
36539 This is the compression algorithm you wish to use. It is difficult to
36540 list all the possible compression options, but common ones supported by
36541 Guix's Linux Libre Kernel include @code{'lzo}, @code{'lz4} and @code{'zstd}.
36542 @item @code{memory-limit} (default @code{0})
36543 This is the maximum amount of memory which the zram device can use.
36544 Setting it to '0' disables the limit. While it is generally expected
36545 that compression will be 2:1, it is possible that uncompressable data
36546 can be written to swap and this is a method to limit how much memory can
36547 be used. It accepts a string and can be a number of bytes or use a
36548 suffix, eg.: @code{"2G"}.
36549 @item @code{priority} (default @code{#f})
36550 This is the priority of the swap device created from the zram device.
36551 @xref{Swap Space} for a description of swap priorities. You might want
36552 to set a specific priority for the zram device, otherwise it could end
36553 up not being used much for the reasons described there.
36559 @node Hurd Services
36560 @subsection Hurd Services
36562 @defvr {Scheme Variable} hurd-console-service-type
36563 This service starts the fancy @code{VGA} console client on the Hurd.
36565 The service's value is a @code{hurd-console-configuration} record.
36568 @deftp {Data Type} hurd-console-configuration
36569 This is the data type representing the configuration for the
36570 hurd-console-service.
36573 @item @code{hurd} (default: @var{hurd})
36574 The Hurd package to use.
36578 @defvr {Scheme Variable} hurd-getty-service-type
36579 This service starts a tty using the Hurd @code{getty} program.
36581 The service's value is a @code{hurd-getty-configuration} record.
36584 @deftp {Data Type} hurd-getty-configuration
36585 This is the data type representing the configuration for the
36586 hurd-getty-service.
36589 @item @code{hurd} (default: @var{hurd})
36590 The Hurd package to use.
36593 The name of the console this Getty runs on---e.g., @code{"tty1"}.
36595 @item @code{baud-rate} (default: @code{38400})
36596 An integer specifying the baud rate of the tty.
36601 @node Miscellaneous Services
36602 @subsection Miscellaneous Services
36604 @cindex fingerprint
36605 @subsubheading Fingerprint Service
36607 The @code{(gnu services authentication)} module provides a DBus service to
36608 read and identify fingerprints via a fingerprint sensor.
36610 @defvr {Scheme Variable} fprintd-service-type
36611 The service type for @command{fprintd}, which provides the fingerprint
36612 reading capability.
36615 (service fprintd-service-type)
36620 @subsubheading System Control Service
36622 The @code{(gnu services sysctl)} provides a service to configure kernel
36623 parameters at boot.
36625 @defvr {Scheme Variable} sysctl-service-type
36626 The service type for @command{sysctl}, which modifies kernel parameters
36627 under @file{/proc/sys/}. To enable IPv4 forwarding, it can be
36631 (service sysctl-service-type
36632 (sysctl-configuration
36633 (settings '(("net.ipv4.ip_forward" . "1")))))
36636 Since @code{sysctl-service-type} is used in the default lists of
36637 services, @code{%base-services} and @code{%desktop-services}, you can
36638 use @code{modify-services} to change its configuration and add the
36639 kernel parameters that you want (@pxref{Service Reference,
36640 @code{modify-services}}).
36643 (modify-services %base-services
36644 (sysctl-service-type config =>
36645 (sysctl-configuration
36646 (settings (append '(("net.ipv4.ip_forward" . "1"))
36647 %default-sysctl-settings)))))
36652 @deftp {Data Type} sysctl-configuration
36653 The data type representing the configuration of @command{sysctl}.
36656 @item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
36657 The @command{sysctl} executable to use.
36659 @item @code{settings} (default: @code{%default-sysctl-settings})
36660 An association list specifies kernel parameters and their values.
36664 @defvr {Scheme Variable} %default-sysctl-settings
36665 An association list specifying the default @command{sysctl} parameters
36670 @subsubheading PC/SC Smart Card Daemon Service
36672 The @code{(gnu services security-token)} module provides the following service
36673 to run @command{pcscd}, the PC/SC Smart Card Daemon. @command{pcscd} is the
36674 daemon program for pcsc-lite and the MuscleCard framework. It is a resource
36675 manager that coordinates communications with smart card readers, smart cards
36676 and cryptographic tokens that are connected to the system.
36678 @defvr {Scheme Variable} pcscd-service-type
36679 Service type for the @command{pcscd} service. Its value must be a
36680 @code{pcscd-configuration} object. To run pcscd in the default
36681 configuration, instantiate it as:
36684 (service pcscd-service-type)
36688 @deftp {Data Type} pcscd-configuration
36689 The data type representing the configuration of @command{pcscd}.
36692 @item @code{pcsc-lite} (default: @code{pcsc-lite})
36693 The pcsc-lite package that provides pcscd.
36694 @item @code{usb-drivers} (default: @code{(list ccid)})
36695 List of packages that provide USB drivers to pcscd. Drivers are expected to be
36696 under @file{pcsc/drivers} in the store directory of the package.
36701 @subsubheading Lirc Service
36703 The @code{(gnu services lirc)} module provides the following service.
36705 @deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
36706 [#:device #f] [#:driver #f] [#:config-file #f] @
36707 [#:extra-options '()]
36708 Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
36709 decodes infrared signals from remote controls.
36711 Optionally, @var{device}, @var{driver} and @var{config-file}
36712 (configuration file name) may be specified. See @command{lircd} manual
36715 Finally, @var{extra-options} is a list of additional command-line options
36716 passed to @command{lircd}.
36720 @subsubheading Spice Service
36722 The @code{(gnu services spice)} module provides the following service.
36724 @deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
36725 Returns a service that runs @url{https://www.spice-space.org,VDAGENT}, a daemon
36726 that enables sharing the clipboard with a vm and setting the guest display
36727 resolution when the graphical console window resizes.
36730 @cindex inputattach
36731 @subsubheading inputattach Service
36733 @cindex tablet input, for Xorg
36734 @cindex touchscreen input, for Xorg
36735 The @uref{https://linuxwacom.github.io/, inputattach} service allows you to
36736 use input devices such as Wacom tablets, touchscreens, or joysticks with the
36737 Xorg display server.
36739 @deffn {Scheme Variable} inputattach-service-type
36740 Type of a service that runs @command{inputattach} on a device and
36741 dispatches events from it.
36744 @deftp {Data Type} inputattach-configuration
36746 @item @code{device-type} (default: @code{"wacom"})
36747 The type of device to connect to. Run @command{inputattach --help}, from the
36748 @code{inputattach} package, to see the list of supported device types.
36750 @item @code{device} (default: @code{"/dev/ttyS0"})
36751 The device file to connect to the device.
36753 @item @code{baud-rate} (default: @code{#f})
36754 Baud rate to use for the serial connection.
36755 Should be a number or @code{#f}.
36757 @item @code{log-file} (default: @code{#f})
36758 If true, this must be the name of a file to log messages to.
36762 @subsubheading Dictionary Service
36764 The @code{(gnu services dict)} module provides the following service:
36766 @defvr {Scheme Variable} dicod-service-type
36767 This is the type of the service that runs the @command{dicod} daemon, an
36768 implementation of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
36771 @deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
36772 Return a service that runs the @command{dicod} daemon, an implementation
36773 of DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
36775 The optional @var{config} argument specifies the configuration for
36776 @command{dicod}, which should be a @code{<dicod-configuration>} object, by
36777 default it serves the GNU Collaborative International Dictionary of English.
36779 You can add @command{open localhost} to your @file{~/.dico} file to make
36780 @code{localhost} the default server for @command{dico} client
36781 (@pxref{Initialization File,,, dico, GNU Dico Manual}).
36784 @deftp {Data Type} dicod-configuration
36785 Data type representing the configuration of dicod.
36788 @item @code{dico} (default: @var{dico})
36789 Package object of the GNU Dico dictionary server.
36791 @item @code{interfaces} (default: @var{'("localhost")})
36792 This is the list of IP addresses and ports and possibly socket file
36793 names to listen to (@pxref{Server Settings, @code{listen} directive,,
36794 dico, GNU Dico Manual}).
36796 @item @code{handlers} (default: @var{'()})
36797 List of @code{<dicod-handler>} objects denoting handlers (module instances).
36799 @item @code{databases} (default: @var{(list %dicod-database:gcide)})
36800 List of @code{<dicod-database>} objects denoting dictionaries to be served.
36804 @deftp {Data Type} dicod-handler
36805 Data type representing a dictionary handler (module instance).
36809 Name of the handler (module instance).
36811 @item @code{module} (default: @var{#f})
36812 Name of the dicod module of the handler (instance). If it is @code{#f},
36813 the module has the same name as the handler.
36814 (@pxref{Modules,,, dico, GNU Dico Manual}).
36816 @item @code{options}
36817 List of strings or gexps representing the arguments for the module handler
36821 @deftp {Data Type} dicod-database
36822 Data type representing a dictionary database.
36826 Name of the database, will be used in DICT commands.
36828 @item @code{handler}
36829 Name of the dicod handler (module instance) used by this database
36830 (@pxref{Handlers,,, dico, GNU Dico Manual}).
36832 @item @code{complex?} (default: @var{#f})
36833 Whether the database configuration complex. The complex configuration
36834 will need a corresponding @code{<dicod-handler>} object, otherwise not.
36836 @item @code{options}
36837 List of strings or gexps representing the arguments for the database
36838 (@pxref{Databases,,, dico, GNU Dico Manual}).
36842 @defvr {Scheme Variable} %dicod-database:gcide
36843 A @code{<dicod-database>} object serving the GNU Collaborative International
36844 Dictionary of English using the @code{gcide} package.
36847 The following is an example @code{dicod-service} configuration.
36850 (dicod-service #:config
36851 (dicod-configuration
36852 (handlers (list (dicod-handler
36856 (list #~(string-append "dbdir=" #$wordnet))))))
36857 (databases (list (dicod-database
36860 (handler "wordnet")
36861 (options '("database=wn")))
36862 %dicod-database:gcide))))
36866 @subsubheading Docker Service
36868 The @code{(gnu services docker)} module provides the following services.
36870 @defvr {Scheme Variable} docker-service-type
36872 This is the type of the service that runs @url{https://www.docker.com,Docker},
36873 a daemon that can execute application bundles (sometimes referred to as
36874 ``containers'') in isolated environments.
36878 @deftp {Data Type} docker-configuration
36879 This is the data type representing the configuration of Docker and Containerd.
36883 @item @code{docker} (default: @code{docker})
36884 The Docker daemon package to use.
36886 @item @code{docker-cli} (default: @code{docker-cli})
36887 The Docker client package to use.
36889 @item @code{containerd} (default: @var{containerd})
36890 The Containerd package to use.
36892 @item @code{proxy} (default @var{docker-libnetwork-cmd-proxy})
36893 The Docker user-land networking proxy package to use.
36895 @item @code{enable-proxy?} (default @code{#t})
36896 Enable or disable the use of the Docker user-land networking proxy.
36898 @item @code{debug?} (default @code{#f})
36899 Enable or disable debug output.
36901 @item @code{enable-iptables?} (default @code{#t})
36902 Enable or disable the addition of iptables rules.
36904 @item @code{environment-variables} (default: @code{()})
36905 List of environment variables to set for @command{dockerd}.
36907 This must be a list of strings where each string has the form
36908 @samp{@var{key}=@var{value}} as in this example:
36911 (list "LANGUAGE=eo:ca:eu"
36912 "TMPDIR=/tmp/dockerd")
36918 @cindex Singularity, container service
36919 @defvr {Scheme Variable} singularity-service-type
36920 This is the type of the service that allows you to run
36921 @url{https://www.sylabs.io/singularity/, Singularity}, a Docker-style tool to
36922 create and run application bundles (aka. ``containers''). The value for this
36923 service is the Singularity package to use.
36925 The service does not install a daemon; instead, it installs helper programs as
36926 setuid-root (@pxref{Setuid Programs}) such that unprivileged users can invoke
36927 @command{singularity run} and similar commands.
36931 @subsubheading Auditd Service
36933 The @code{(gnu services auditd)} module provides the following service.
36935 @defvr {Scheme Variable} auditd-service-type
36937 This is the type of the service that runs
36938 @url{https://people.redhat.com/sgrubb/audit/,auditd},
36939 a daemon that tracks security-relevant information on your system.
36941 Examples of things that can be tracked:
36951 Failed login attempts
36958 @command{auditctl} from the @code{audit} package can be used in order
36959 to add or remove events to be tracked (until the next reboot).
36960 In order to permanently track events, put the command line arguments
36961 of auditctl into a file called @code{audit.rules} in the configuration
36962 directory (see below).
36963 @command{aureport} from the @code{audit} package can be used in order
36964 to view a report of all recorded events.
36965 The audit daemon by default logs into the file
36966 @file{/var/log/audit.log}.
36970 @deftp {Data Type} auditd-configuration
36971 This is the data type representing the configuration of auditd.
36975 @item @code{audit} (default: @code{audit})
36976 The audit package to use.
36978 @item @code{configuration-directory} (default: @code{%default-auditd-configuration-directory})
36979 The directory containing the configuration file for the audit package, which
36980 must be named @code{auditd.conf}, and optionally some audit rules to
36981 instantiate on startup.
36987 @subsubheading R-Shiny service
36989 The @code{(gnu services science)} module provides the following service.
36991 @defvr {Scheme Variable} rshiny-service-type
36993 This is a type of service which is used to run a webapp created with
36994 @code{r-shiny}. This service sets the @env{R_LIBS_USER} environment
36995 variable and runs the provided script to call @code{runApp}.
36997 @deftp {Data Type} rshiny-configuration
36998 This is the data type representing the configuration of rshiny.
37002 @item @code{package} (default: @code{r-shiny})
37003 The package to use.
37005 @item @code{binary} (default @code{"rshiny"})
37006 The name of the binary or shell script located at @code{package/bin/} to
37007 run when the service is run.
37009 The common way to create this file is as follows:
37013 (let* ((out (assoc-ref %outputs "out"))
37014 (targetdir (string-append out "/share/" ,name))
37015 (app (string-append out "/bin/" ,name))
37016 (Rbin (search-input-file %build-inputs "/bin/Rscript")))
37018 (mkdir-p (string-append out "/bin"))
37019 (call-with-output-file app
37025 runApp(launch.browser=0, port=4202)~%\n"
37034 @subsubheading Nix service
37036 The @code{(gnu services nix)} module provides the following service.
37038 @defvr {Scheme Variable} nix-service-type
37040 This is the type of the service that runs build daemon of the
37041 @url{https://nixos.org/nix/, Nix} package manager. Here is an example showing
37045 (use-modules (gnu))
37046 (use-service-modules nix)
37047 (use-package-modules package-management)
37051 (packages (append (list nix)
37054 (services (append (list (service nix-service-type))
37058 After @command{guix system reconfigure} configure Nix for your user:
37061 @item Add a Nix channel and update it. See
37062 @url{https://nixos.org/nix/manual/, Nix Package Manager Guide}.
37064 @item Create a symlink to your profile and activate Nix profile:
37068 $ ln -s "/nix/var/nix/profiles/per-user/$USER/profile" ~/.nix-profile
37069 $ source /run/current-system/profile/etc/profile.d/nix.sh
37074 @deftp {Data Type} nix-configuration
37075 This data type represents the configuration of the Nix daemon.
37078 @item @code{nix} (default: @code{nix})
37079 The Nix package to use.
37081 @item @code{sandbox} (default: @code{#t})
37082 Specifies whether builds are sandboxed by default.
37084 @item @code{build-sandbox-items} (default: @code{'()})
37085 This is a list of strings or objects appended to the
37086 @code{build-sandbox-items} field of the configuration file.
37088 @item @code{extra-config} (default: @code{'()})
37089 This is a list of strings or objects appended to the configuration file.
37090 It is used to pass extra text to be added verbatim to the configuration
37093 @item @code{extra-options} (default: @code{'()})
37094 Extra command line options for @code{nix-service-type}.
37099 @subsubheading Fail2Ban service
37101 @uref{http://www.fail2ban.org/, @code{fail2ban}} scans log files
37102 (e.g. @code{/var/log/apache/error_log}) and bans IP addresses that show
37103 malicious signs -- repeated password failures, attempts to make use of
37106 @code{fail2ban-service-type} service type is provided by the @code{(gnu
37107 services security)} module.
37109 This service type runs the @code{fail2ban} daemon. It can be configured
37110 in various ways, which are:
37113 @item Basic configuration
37114 The basic parameters of the Fail2Ban service can be configured via its
37115 @code{fail2ban} configuration, which is documented below.
37117 @item User-specified jail extensions
37118 The @code{fail2ban-jail-service} function can be used to add new
37121 @item Shepherd extension mechanism
37122 Service developers can extend the @code{fail2ban-service-type} service
37123 type itself via the usual service extension mechanism.
37126 @defvr {Scheme Variable} fail2ban-service-type
37128 This is the type of the service that runs @code{fail2ban} daemon. Below
37129 is an example of a basic, explicit configuration:
37134 (service fail2ban-service-type
37135 (fail2ban-configuration
37138 (fail2ban-jail-configuration
37141 ;; There is no implicit dependency on an actual SSH
37142 ;; service, so you need to provide one.
37143 (service openssh-service-type))
37148 @deffn {Scheme Procedure} fail2ban-jail-service @var{svc-type} @var{jail}
37149 Extend @var{svc-type}, a @code{<service-type>} object with @var{jail}, a
37150 @code{fail2ban-jail-configuration} object.
37158 ;; The 'fail2ban-jail-service' procedure can extend any service type
37159 ;; with a fail2ban jail. This removes the requirement to explicitly
37160 ;; extend services with fail2ban-service-type.
37161 (fail2ban-jail-service
37162 openssh-service-type
37163 (fail2ban-jail-configuration
37166 (openssh-configuration ...))))
37170 Below is the reference for the different @code{jail-service-type}
37171 configuration records.
37173 @c The documentation is to be auto-generated via
37174 @c 'generate-documentation'. See at the bottom of (gnu services
37177 @deftp {Data Type} fail2ban-configuration
37178 Available @code{fail2ban-configuration} fields are:
37181 @item @code{fail2ban} (default: @code{fail2ban}) (type: package)
37182 The @code{fail2ban} package to use. It is used for both binaries and as
37183 base default configuration that is to be extended with
37184 @code{<fail2ban-jail-configuration>} objects.
37186 @item @code{run-directory} (default: @code{"/var/run/fail2ban"}) (type: string)
37187 The state directory for the @code{fail2ban} daemon.
37189 @item @code{jails} (default: @code{()}) (type: list-of-fail2ban-jail-configurations)
37190 Instances of @code{<fail2ban-jail-configuration>} collected from
37193 @item @code{extra-jails} (default: @code{()}) (type: list-of-fail2ban-jail-configurations)
37194 Instances of @code{<fail2ban-jail-configuration>} explicitly provided.
37196 @item @code{extra-content} (default: @code{()}) (type: text-config)
37197 Extra raw content to add to the end of the @file{jail.local} file,
37198 provided as a list of file-like objects.
37204 @deftp {Data Type} fail2ban-ignore-cache-configuration
37205 Available @code{fail2ban-ignore-cache-configuration} fields are:
37208 @item @code{key} (type: string)
37211 @item @code{max-count} (type: integer)
37214 @item @code{max-time} (type: integer)
37221 @deftp {Data Type} fail2ban-jail-action-configuration
37222 Available @code{fail2ban-jail-action-configuration} fields are:
37225 @item @code{name} (type: string)
37228 @item @code{arguments} (default: @code{()}) (type: list-of-arguments)
37235 @deftp {Data Type} fail2ban-jail-configuration
37236 Available @code{fail2ban-jail-configuration} fields are:
37239 @item @code{name} (type: string)
37240 Required name of this jail configuration.
37242 @item @code{enabled?} (default: @code{#t}) (type: boolean)
37243 Whether this jail is enabled.
37245 @item @code{backend} (type: maybe-symbol)
37246 Backend to use to detect changes in the @code{log-path}. The default is
37247 'auto. To consult the defaults of the jail configuration, refer to the
37248 @file{/etc/fail2ban/jail.conf} file of the @code{fail2ban} package.
37250 @item @code{max-retry} (type: maybe-integer)
37251 The number of failures before a host get banned (e.g. @code{(max-retry
37254 @item @code{max-matches} (type: maybe-integer)
37255 The number of matches stored in ticket (resolvable via tag
37256 @code{<matches>}) in action.
37258 @item @code{find-time} (type: maybe-string)
37259 The time window during which the maximum retry count must be reached for
37260 an IP address to be banned. A host is banned if it has generated
37261 @code{max-retry} during the last @code{find-time} seconds (e.g.
37262 @code{(find-time "10m")}). It can be provided in seconds or using
37263 Fail2Ban's "time abbreviation format", as described in @command{man 5
37266 @item @code{ban-time} (type: maybe-string)
37267 The duration, in seconds or time abbreviated format, that a ban should
37268 last. (e.g. @code{(ban-time "10m")}).
37270 @item @code{ban-time-increment?} (type: maybe-boolean)
37271 Whether to consider past bans to compute increases to the default ban
37272 time of a specific IP address.
37274 @item @code{ban-time-factor} (type: maybe-string)
37275 The coefficient to use to compute an exponentially growing ban time.
37277 @item @code{ban-time-formula} (type: maybe-string)
37278 This is the formula used to calculate the next value of a ban time.
37280 @item @code{ban-time-multipliers} (type: maybe-string)
37281 Used to calculate next value of ban time instead of formula.
37283 @item @code{ban-time-max-time} (type: maybe-string)
37284 The maximum number of seconds a ban should last.
37286 @item @code{ban-time-rnd-time} (type: maybe-string)
37287 The maximum number of seconds a randomized ban time should last. This
37288 can be useful to stop ``clever'' botnets calculating the exact time an
37289 IP address can be unbanned again.
37291 @item @code{ban-time-overall-jails?} (type: maybe-boolean)
37292 When true, it specifies the search of an IP address in the database
37293 should be made across all jails. Otherwise, only the current jail of
37294 the ban IP address is considered.
37296 @item @code{ignore-self?} (type: maybe-boolean)
37297 Never ban the local machine's own IP address.
37299 @item @code{ignore-ip} (default: @code{()}) (type: list-of-strings)
37300 A list of IP addresses, CIDR masks or DNS hosts to ignore.
37301 @code{fail2ban} will not ban a host which matches an address in this
37304 @item @code{ignore-cache} (type: maybe-fail2ban-ignore-cache-configuration)
37305 Provide cache parameters for the ignore failure check.
37307 @item @code{filter} (type: maybe-fail2ban-jail-filter-configuration)
37308 The filter to use by the jail, specified via a
37309 @code{<fail2ban-jail-filter-configuration>} object. By default, jails
37310 have names matching their filter name.
37312 @item @code{log-time-zone} (type: maybe-string)
37313 The default time zone for log lines that do not have one.
37315 @item @code{log-encoding} (type: maybe-symbol)
37316 The encoding of the log files handled by the jail. Possible values are:
37317 @code{'ascii}, @code{'utf-8} and @code{'auto}.
37319 @item @code{log-path} (default: @code{()}) (type: list-of-strings)
37320 The file names of the log files to be monitored.
37322 @item @code{action} (default: @code{()}) (type: list-of-fail2ban-jail-actions)
37323 A list of @code{<fail2ban-jail-action-configuration>}.
37325 @item @code{extra-content} (default: @code{()}) (type: text-config)
37326 Extra content for the jail configuration, provided as a list of file-like
37333 @deftp {Data Type} fail2ban-jail-filter-configuration
37334 Available @code{fail2ban-jail-filter-configuration} fields are:
37337 @item @code{name} (type: string)
37340 @item @code{mode} (type: maybe-string)
37347 @c End of auto-generated fail2ban documentation.
37349 @node Setuid Programs
37350 @section Setuid Programs
37352 @cindex setuid programs
37353 @cindex setgid programs
37354 Some programs need to run with elevated privileges, even when they are
37355 launched by unprivileged users. A notorious example is the
37356 @command{passwd} program, which users can run to change their
37357 password, and which needs to access the @file{/etc/passwd} and
37358 @file{/etc/shadow} files---something normally restricted to root, for
37359 obvious security reasons. To address that, @command{passwd} should be
37360 @dfn{setuid-root}, meaning that it always runs with root privileges
37361 (@pxref{How Change Persona,,, libc, The GNU C Library Reference Manual},
37362 for more info about the setuid mechanism).
37364 The store itself @emph{cannot} contain setuid programs: that would be a
37365 security issue since any user on the system can write derivations that
37366 populate the store (@pxref{The Store}). Thus, a different mechanism is
37367 used: instead of changing the setuid or setgid bits directly on files that
37368 are in the store, we let the system administrator @emph{declare} which
37369 programs should be entrusted with these additional privileges.
37371 The @code{setuid-programs} field of an @code{operating-system}
37372 declaration contains a list of @code{<setuid-program>} denoting the
37373 names of programs to have a setuid or setgid bit set (@pxref{Using the
37374 Configuration System}). For instance, the @command{mount.nfs} program,
37375 which is part of the nfs-utils package, with a setuid root can be
37376 designated like this:
37380 (program (file-append nfs-utils "/sbin/mount.nfs")))
37383 And then, to make @command{mount.nfs} setuid on your system, add the
37384 previous example to your operating system declaration by appending it to
37385 @code{%setuid-programs} like this:
37389 ;; Some fields omitted...
37391 (append (list (setuid-program
37392 (program (file-append nfs-utils "/sbin/mount.nfs"))))
37393 %setuid-programs)))
37396 @deftp {Data Type} setuid-program
37397 This data type represents a program with a setuid or setgid bit set.
37400 @item @code{program}
37401 A file-like object having its setuid and/or setgid bit set.
37403 @item @code{setuid?} (default: @code{#t})
37404 Whether to set user setuid bit.
37406 @item @code{setgid?} (default: @code{#f})
37407 Whether to set group setgid bit.
37409 @item @code{user} (default: @code{0})
37410 UID (integer) or user name (string) for the user owner of the program,
37413 @item @code{group} (default: @code{0})
37414 GID (integer) goup name (string) for the group owner of the program,
37420 A default set of setuid programs is defined by the
37421 @code{%setuid-programs} variable of the @code{(gnu system)} module.
37423 @defvr {Scheme Variable} %setuid-programs
37424 A list of @code{<setuid-program>} denoting common programs that are
37427 The list includes commands such as @command{passwd}, @command{ping},
37428 @command{su}, and @command{sudo}.
37431 Under the hood, the actual setuid programs are created in the
37432 @file{/run/setuid-programs} directory at system activation time. The
37433 files in this directory refer to the ``real'' binaries, which are in the
37436 @node X.509 Certificates
37437 @section X.509 Certificates
37439 @cindex HTTPS, certificates
37440 @cindex X.509 certificates
37442 Web servers available over HTTPS (that is, HTTP over the transport-layer
37443 security mechanism, TLS) send client programs an @dfn{X.509 certificate}
37444 that the client can then use to @emph{authenticate} the server. To do
37445 that, clients verify that the server's certificate is signed by a
37446 so-called @dfn{certificate authority} (CA). But to verify the CA's
37447 signature, clients must have first acquired the CA's certificate.
37449 Web browsers such as GNU@tie{}IceCat include their own set of CA
37450 certificates, such that they are able to verify CA signatures
37453 However, most other programs that can talk HTTPS---@command{wget},
37454 @command{git}, @command{w3m}, etc.---need to be told where CA
37455 certificates can be found.
37457 @cindex @code{nss-certs}
37458 In Guix, this is done by adding a package that provides certificates
37459 to the @code{packages} field of the @code{operating-system} declaration
37460 (@pxref{operating-system Reference}). Guix includes one such package,
37461 @code{nss-certs}, which is a set of CA certificates provided as part of
37462 Mozilla's Network Security Services.
37464 Note that it is @emph{not} part of @code{%base-packages}, so you need to
37465 explicitly add it. The @file{/etc/ssl/certs} directory, which is where
37466 most applications and libraries look for certificates by default, points
37467 to the certificates installed globally.
37469 Unprivileged users, including users of Guix on a foreign distro,
37470 can also install their own certificate package in
37471 their profile. A number of environment variables need to be defined so
37472 that applications and libraries know where to find them. Namely, the
37473 OpenSSL library honors the @env{SSL_CERT_DIR} and @env{SSL_CERT_FILE}
37474 variables. Some applications add their own environment variables; for
37475 instance, the Git version control system honors the certificate bundle
37476 pointed to by the @env{GIT_SSL_CAINFO} environment variable. Thus, you
37477 would typically run something like:
37480 guix install nss-certs
37481 export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
37482 export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
37483 export GIT_SSL_CAINFO="$SSL_CERT_FILE"
37486 As another example, R requires the @env{CURL_CA_BUNDLE} environment
37487 variable to point to a certificate bundle, so you would have to run
37488 something like this:
37491 guix install nss-certs
37492 export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
37495 For other applications you may want to look up the required environment
37496 variable in the relevant documentation.
37499 @node Name Service Switch
37500 @section Name Service Switch
37502 @cindex name service switch
37504 The @code{(gnu system nss)} module provides bindings to the
37505 configuration file of the libc @dfn{name service switch} or @dfn{NSS}
37506 (@pxref{NSS Configuration File,,, libc, The GNU C Library Reference
37507 Manual}). In a nutshell, the NSS is a mechanism that allows libc to be
37508 extended with new ``name'' lookup methods for system databases, which
37509 includes host names, service names, user accounts, and more (@pxref{Name
37510 Service Switch, System Databases and Name Service Switch,, libc, The GNU
37511 C Library Reference Manual}).
37513 The NSS configuration specifies, for each system database, which lookup
37514 method is to be used, and how the various methods are chained
37515 together---for instance, under which circumstances NSS should try the
37516 next method in the list. The NSS configuration is given in the
37517 @code{name-service-switch} field of @code{operating-system} declarations
37518 (@pxref{operating-system Reference, @code{name-service-switch}}).
37521 @cindex .local, host name lookup
37522 As an example, the declaration below configures the NSS to use the
37523 @uref{https://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
37524 back-end}, which supports host name lookups over multicast DNS (mDNS)
37525 for host names ending in @code{.local}:
37528 (name-service-switch
37529 (hosts (list %files ;first, check /etc/hosts
37531 ;; If the above did not succeed, try
37532 ;; with 'mdns_minimal'.
37534 (name "mdns_minimal")
37536 ;; 'mdns_minimal' is authoritative for
37537 ;; '.local'. When it returns "not found",
37538 ;; no need to try the next methods.
37539 (reaction (lookup-specification
37540 (not-found => return))))
37542 ;; Then fall back to DNS.
37546 ;; Finally, try with the "full" 'mdns'.
37551 Do not worry: the @code{%mdns-host-lookup-nss} variable (see below)
37552 contains this configuration, so you will not have to type it if all you
37553 want is to have @code{.local} host lookup working.
37555 Note that, in this case, in addition to setting the
37556 @code{name-service-switch} of the @code{operating-system} declaration,
37557 you also need to use @code{avahi-service-type} (@pxref{Networking Services,
37558 @code{avahi-service-type}}), or @code{%desktop-services}, which includes it
37559 (@pxref{Desktop Services}). Doing this makes @code{nss-mdns} accessible
37560 to the name service cache daemon (@pxref{Base Services,
37561 @code{nscd-service}}).
37563 For convenience, the following variables provide typical NSS
37566 @defvr {Scheme Variable} %default-nss
37567 This is the default name service switch configuration, a
37568 @code{name-service-switch} object.
37571 @defvr {Scheme Variable} %mdns-host-lookup-nss
37572 This is the name service switch configuration with support for host name
37573 lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
37576 The reference for name service switch configuration is given below. It
37577 is a direct mapping of the configuration file format of the C library , so
37578 please refer to the C library manual for more information (@pxref{NSS
37579 Configuration File,,, libc, The GNU C Library Reference Manual}).
37580 Compared to the configuration file format of libc NSS, it has the advantage
37581 not only of adding this warm parenthetic feel that we like, but also
37582 static checks: you will know about syntax errors and typos as soon as you
37583 run @command{guix system}.
37585 @deftp {Data Type} name-service-switch
37587 This is the data type representation the configuration of libc's name
37588 service switch (NSS). Each field below represents one of the supported
37605 The system databases handled by the NSS@. Each of these fields must be a
37606 list of @code{<name-service>} objects (see below).
37610 @deftp {Data Type} name-service
37612 This is the data type representing an actual name service and the
37613 associated lookup action.
37617 A string denoting the name service (@pxref{Services in the NSS
37618 configuration,,, libc, The GNU C Library Reference Manual}).
37620 Note that name services listed here must be visible to nscd. This is
37621 achieved by passing the @code{#:name-services} argument to
37622 @code{nscd-service} the list of packages providing the needed name
37623 services (@pxref{Base Services, @code{nscd-service}}).
37626 An action specified using the @code{lookup-specification} macro
37627 (@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
37628 Reference Manual}). For example:
37631 (lookup-specification (unavailable => continue)
37632 (success => return))
37637 @node Initial RAM Disk
37638 @section Initial RAM Disk
37641 @cindex initial RAM disk
37642 For bootstrapping purposes, the Linux-Libre kernel is passed an
37643 @dfn{initial RAM disk}, or @dfn{initrd}. An initrd contains a temporary
37644 root file system as well as an initialization script. The latter is
37645 responsible for mounting the real root file system, and for loading any
37646 kernel modules that may be needed to achieve that.
37648 The @code{initrd-modules} field of an @code{operating-system}
37649 declaration allows you to specify Linux-libre kernel modules that must
37650 be available in the initrd. In particular, this is where you would list
37651 modules needed to actually drive the hard disk where your root partition
37652 is---although the default value of @code{initrd-modules} should cover
37653 most use cases. For example, assuming you need the @code{megaraid_sas}
37654 module in addition to the default modules to be able to access your root
37655 file system, you would write:
37660 (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
37663 @defvr {Scheme Variable} %base-initrd-modules
37664 This is the list of kernel modules included in the initrd by default.
37667 Furthermore, if you need lower-level customization, the @code{initrd}
37668 field of an @code{operating-system} declaration allows
37669 you to specify which initrd you would like to use. The @code{(gnu
37670 system linux-initrd)} module provides three ways to build an initrd: the
37671 high-level @code{base-initrd} procedure and the low-level
37672 @code{raw-initrd} and @code{expression->initrd} procedures.
37674 The @code{base-initrd} procedure is intended to cover most common uses.
37675 For example, if you want to add a bunch of kernel modules to be loaded
37676 at boot time, you can define the @code{initrd} field of the operating
37677 system declaration like this:
37680 (initrd (lambda (file-systems . rest)
37681 ;; Create a standard initrd but set up networking
37682 ;; with the parameters QEMU expects by default.
37683 (apply base-initrd file-systems
37684 #:qemu-networking? #t
37688 The @code{base-initrd} procedure also handles common use cases that
37689 involves using the system as a QEMU guest, or as a ``live'' system with
37690 volatile root file system.
37692 The @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
37693 Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level,
37694 such as trying to guess which kernel modules and packages should be included
37695 to the initrd. An example use of @code{raw-initrd} is when a user has
37696 a custom Linux kernel configuration and default kernel modules included by
37697 @code{base-initrd} are not available.
37699 The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd}
37700 honors several options passed on the Linux kernel command line
37701 (that is, arguments passed @i{via} the @code{linux} command of GRUB, or the
37702 @code{-append} option of QEMU), notably:
37705 @item gnu.load=@var{boot}
37706 Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
37707 program, once it has mounted the root file system.
37709 Guix uses this option to yield control to a boot program that runs the
37710 service activation programs and then spawns the GNU@tie{}Shepherd, the
37711 initialization system.
37713 @item root=@var{root}
37714 Mount @var{root} as the root file system. @var{root} can be a device
37715 name like @code{/dev/sda1}, a file system label, or a file system UUID.
37716 When unspecified, the device name from the root file system of the
37717 operating system declaration is used.
37719 @item rootfstype=@var{type}
37720 Set the type of the root file system. It overrides the @code{type}
37721 field of the root file system specified via the @code{operating-system}
37722 declaration, if any.
37724 @item rootflags=@var{options}
37725 Set the mount @emph{options} of the root file system. It overrides the
37726 @code{options} field of the root file system specified via the
37727 @code{operating-system} declaration, if any.
37729 @item fsck.mode=@var{mode}
37730 Whether to check the @var{root} file system for errors before mounting
37731 it. @var{mode} is one of @code{skip} (never check), @code{force} (always
37732 check), or @code{auto} to respect the root @code{<file-system>} object's
37733 @code{check?} setting (@pxref{File Systems}) and run a full scan only if
37734 the file system was not cleanly shut down.
37736 @code{auto} is the default if this option is not present or if @var{mode}
37737 is not one of the above.
37739 @item fsck.repair=@var{level}
37740 The level of repairs to perform automatically if errors are found in the
37741 @var{root} file system. @var{level} is one of @code{no} (do not write to
37742 @var{root} at all if possible), @code{yes} (repair as much as possible),
37743 or @code{preen} to repair problems considered safe to repair automatically.
37745 @code{preen} is the default if this option is not present or if @var{level}
37746 is not one of the above.
37748 @item gnu.system=@var{system}
37749 Have @file{/run/booted-system} and @file{/run/current-system} point to
37752 @item modprobe.blacklist=@var{modules}@dots{}
37753 @cindex module, black-listing
37754 @cindex black list, of kernel modules
37755 Instruct the initial RAM disk as well as the @command{modprobe} command
37756 (from the kmod package) to refuse to load @var{modules}. @var{modules}
37757 must be a comma-separated list of module names---e.g.,
37758 @code{usbkbd,9pnet}.
37761 Start a read-eval-print loop (REPL) from the initial RAM disk before it
37762 tries to load kernel modules and to mount the root file system. Our
37763 marketing team calls it @dfn{boot-to-Guile}. The Schemer in you will
37764 love it. @xref{Using Guile Interactively,,, guile, GNU Guile Reference
37765 Manual}, for more information on Guile's REPL.
37769 Now that you know all the features that initial RAM disks produced by
37770 @code{base-initrd} and @code{raw-initrd} provide,
37771 here is how to use it and customize it further.
37774 @cindex initial RAM disk
37775 @deffn {Scheme Procedure} raw-initrd @var{file-systems} @
37776 [#:linux-modules '()] [#:mapped-devices '()] @
37777 [#:keyboard-layout #f] @
37778 [#:helper-packages '()] [#:qemu-networking? #f] [#:volatile-root? #f]
37779 Return a derivation that builds a raw initrd. @var{file-systems} is
37780 a list of file systems to be mounted by the initrd, possibly in addition to
37781 the root file system specified on the kernel command line via @option{root}.
37782 @var{linux-modules} is a list of kernel modules to be loaded at boot time.
37783 @var{mapped-devices} is a list of device mappings to realize before
37784 @var{file-systems} are mounted (@pxref{Mapped Devices}).
37785 @var{helper-packages} is a list of packages to be copied in the initrd.
37787 include @code{e2fsck/static} or other packages needed by the initrd to check
37788 the root file system.
37790 When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
37791 the desired console keyboard layout. This is done before @var{mapped-devices}
37792 are set up and before @var{file-systems} are mounted such that, should the
37793 user need to enter a passphrase or use the REPL, this happens using the
37794 intended keyboard layout.
37796 When @var{qemu-networking?} is true, set up networking with the standard QEMU
37797 parameters. When @var{virtio?} is true, load additional modules so that the
37798 initrd can be used as a QEMU guest with para-virtualized I/O drivers.
37800 When @var{volatile-root?} is true, the root file system is writable but any changes
37804 @deffn {Scheme Procedure} base-initrd @var{file-systems} @
37805 [#:mapped-devices '()] [#:keyboard-layout #f] @
37806 [#:qemu-networking? #f] [#:volatile-root? #f] @
37807 [#:linux-modules '()]
37808 Return as a file-like object a generic initrd, with kernel
37809 modules taken from @var{linux}. @var{file-systems} is a list of file-systems to be
37810 mounted by the initrd, possibly in addition to the root file system specified
37811 on the kernel command line via @option{root}. @var{mapped-devices} is a list of device
37812 mappings to realize before @var{file-systems} are mounted.
37814 When true, @var{keyboard-layout} is a @code{<keyboard-layout>} record denoting
37815 the desired console keyboard layout. This is done before @var{mapped-devices}
37816 are set up and before @var{file-systems} are mounted such that, should the
37817 user need to enter a passphrase or use the REPL, this happens using the
37818 intended keyboard layout.
37820 @var{qemu-networking?} and @var{volatile-root?} behaves as in @code{raw-initrd}.
37822 The initrd is automatically populated with all the kernel modules necessary
37823 for @var{file-systems} and for the given options. Additional kernel
37824 modules can be listed in @var{linux-modules}. They will be added to the initrd, and
37825 loaded at boot time in the order in which they appear.
37828 Needless to say, the initrds we produce and use embed a
37829 statically-linked Guile, and the initialization program is a Guile
37830 program. That gives a lot of flexibility. The
37831 @code{expression->initrd} procedure builds such an initrd, given the
37832 program to run in that initrd.
37834 @deffn {Scheme Procedure} expression->initrd @var{exp} @
37835 [#:guile %guile-static-stripped] [#:name "guile-initrd"]
37836 Return as a file-like object a Linux initrd (a gzipped cpio archive)
37837 containing @var{guile} and that evaluates @var{exp}, a G-expression,
37838 upon booting. All the derivations referenced by @var{exp} are
37839 automatically copied to the initrd.
37842 @node Bootloader Configuration
37843 @section Bootloader Configuration
37846 @cindex boot loader
37848 The operating system supports multiple bootloaders. The bootloader is
37849 configured using @code{bootloader-configuration} declaration. All the
37850 fields of this structure are bootloader agnostic except for one field,
37851 @code{bootloader} that indicates the bootloader to be configured and
37854 Some of the bootloaders do not honor every field of
37855 @code{bootloader-configuration}. For instance, the extlinux
37856 bootloader does not support themes and thus ignores the @code{theme}
37859 @deftp {Data Type} bootloader-configuration
37860 The type of a bootloader configuration declaration.
37864 @item @code{bootloader}
37865 @cindex EFI, bootloader
37866 @cindex UEFI, bootloader
37867 @cindex BIOS, bootloader
37868 The bootloader to use, as a @code{bootloader} object. For now
37869 @code{grub-bootloader}, @code{grub-efi-bootloader},
37870 @code{grub-efi-netboot-bootloader}, @code{grub-efi-removable-bootloader},
37871 @code{extlinux-bootloader} and @code{u-boot-bootloader} are supported.
37873 @cindex ARM, bootloaders
37874 @cindex AArch64, bootloaders
37875 Available bootloaders are described in @code{(gnu bootloader @dots{})}
37876 modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
37877 of bootloaders for a wide range of ARM and AArch64 systems, using the
37878 @uref{https://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
37880 @vindex grub-efi-bootloader
37881 @code{grub-efi-bootloader} allows to boot on modern systems using the
37882 @dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should
37883 use if the installation image contains a @file{/sys/firmware/efi} directory
37884 when you boot it on your system.
37886 @vindex grub-bootloader
37887 @code{grub-bootloader} allows you to boot in particular Intel-based machines
37888 in ``legacy'' BIOS mode.
37890 @vindex grub-efi-netboot-bootloader
37891 @code{grub-efi-netboot-bootloader} allows you to boot your system over network
37892 through TFTP@. In combination with an NFS root file system this allows you to
37893 build a diskless Guix system.
37895 The installation of the @code{grub-efi-netboot-bootloader} generates the
37896 content of the TFTP root directory at @code{targets} (@pxref{Bootloader
37897 Configuration, @code{targets}}), to be served by a TFTP server. You may
37898 want to mount your TFTP server directories onto the @code{targets} to
37899 move the required files to the TFTP server automatically.
37901 If you plan to use an NFS root file system as well (actually if you mount the
37902 store from an NFS share), then the TFTP server needs to serve the file
37903 @file{/boot/grub/grub.cfg} and other files from the store (like GRUBs background
37904 image, the kernel (@pxref{operating-system Reference, @code{kernel}}) and the
37905 initrd (@pxref{operating-system Reference, @code{initrd}})), too. All these
37906 files from the store will be accessed by GRUB through TFTP with their normal
37907 store path, for example as
37908 @file{tftp://tftp-server/gnu/store/…-initrd/initrd.cpio.gz}.
37910 Two symlinks are created to make this possible. For each target in the
37911 @code{targets} field, the first symlink is
37912 @samp{target}@file{/efi/Guix/boot/grub/grub.cfg} pointing to
37913 @file{../../../boot/grub/grub.cfg}, where @samp{target} may be
37914 @file{/boot}. In this case the link is not leaving the served TFTP root
37915 directory, but otherwise it does. The second link is
37916 @samp{target}@file{/gnu/store} and points to @file{../gnu/store}. This
37917 link is leaving the served TFTP root directory.
37919 The assumption behind all this is that you have an NFS server exporting
37920 the root file system for your Guix system, and additionally a TFTP
37921 server exporting your @code{targets} directories—usually a single
37922 @file{/boot}—from that same root file system for your Guix system. In
37923 this constellation the symlinks will work.
37925 For other constellations you will have to program your own bootloader
37926 installer, which then takes care to make necessary files from the store
37927 accessible through TFTP, for example by copying them into the TFTP root
37928 directory to your @code{targets}.
37930 It is important to note that symlinks pointing outside the TFTP root directory
37931 may need to be allowed in the configuration of your TFTP server. Further the
37932 store link exposes the whole store through TFTP@. Both points need to be
37933 considered carefully for security aspects.
37935 Beside the @code{grub-efi-netboot-bootloader}, the already mentioned TFTP and
37936 NFS servers, you also need a properly configured DHCP server to make the booting
37937 over netboot possible. For all this we can currently only recommend you to look
37938 for instructions about @acronym{PXE, Preboot eXecution Environment}.
37940 @vindex grub-efi-removable-bootloader
37941 @code{grub-efi-removable-bootloader} allows you to boot your system from
37942 removable media by writing the GRUB file to the UEFI-specification location of
37943 @file{/EFI/BOOT/BOOTX64.efi} of the boot directory, usually @file{/boot/efi}.
37944 This is also useful for some UEFI firmwares that ``forget'' their configuration
37945 from their non-volatile storage. Like @code{grub-efi-bootloader}, this can only
37946 be used if the @file{/sys/firmware/efi} directory is available.
37949 This @emph{will} overwrite the GRUB file from any other operating systems that
37950 also place their GRUB file in the UEFI-specification location; making them
37954 @item @code{targets}
37955 This is a list of strings denoting the targets onto which to install the
37958 The interpretation of targets depends on the bootloader in question.
37959 For @code{grub-bootloader}, for example, they should be device names
37960 understood by the bootloader @command{installer} command, such as
37961 @code{/dev/sda} or @code{(hd0)} (@pxref{Invoking grub-install,,, grub,
37962 GNU GRUB Manual}). For @code{grub-efi-bootloader} and
37963 @code{grub-efi-removable-bootloader} they should be mount
37964 points of the EFI file system, usually @file{/boot/efi}. For
37965 @code{grub-efi-netboot-bootloader}, @code{targets} should be the mount
37966 points corresponding to TFTP root directories served by your TFTP
37969 @item @code{menu-entries} (default: @code{()})
37970 A possibly empty list of @code{menu-entry} objects (see below), denoting
37971 entries to appear in the bootloader menu, in addition to the current
37972 system entry and the entry pointing to previous system generations.
37974 @item @code{default-entry} (default: @code{0})
37975 The index of the default boot menu entry. Index 0 is for the entry of the
37978 @item @code{timeout} (default: @code{5})
37979 The number of seconds to wait for keyboard input before booting. Set to
37980 0 to boot immediately, and to -1 to wait indefinitely.
37982 @cindex keyboard layout, for the bootloader
37983 @item @code{keyboard-layout} (default: @code{#f})
37984 If this is @code{#f}, the bootloader's menu (if any) uses the default keyboard
37985 layout, usually US@tie{}English (``qwerty'').
37987 Otherwise, this must be a @code{keyboard-layout} object (@pxref{Keyboard
37991 This option is currently ignored by bootloaders other than @code{grub} and
37995 @item @code{theme} (default: @var{#f})
37996 The bootloader theme object describing the theme to use. If no theme
37997 is provided, some bootloaders might use a default theme, that's true
38000 @item @code{terminal-outputs} (default: @code{'(gfxterm)})
38001 The output terminals used for the bootloader boot menu, as a list of
38002 symbols. GRUB accepts the values: @code{console}, @code{serial},
38003 @code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text},
38004 @code{mda_text}, @code{morse}, and @code{pkmodem}. This field
38005 corresponds to the GRUB variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple
38006 configuration,,, grub,GNU GRUB manual}).
38008 @item @code{terminal-inputs} (default: @code{'()})
38009 The input terminals used for the bootloader boot menu, as a list of
38010 symbols. For GRUB, the default is the native platform terminal as
38011 determined at run-time. GRUB accepts the values: @code{console},
38012 @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
38013 @code{usb_keyboard}. This field corresponds to the GRUB variable
38014 @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB
38017 @item @code{serial-unit} (default: @code{#f})
38018 The serial unit used by the bootloader, as an integer from 0 to 3.
38019 For GRUB, it is chosen at run-time; currently GRUB chooses 0, which
38020 corresponds to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
38022 @item @code{serial-speed} (default: @code{#f})
38023 The speed of the serial interface, as an integer. For GRUB, the
38024 default value is chosen at run-time; currently GRUB chooses
38025 9600@tie{}bps (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
38027 @item @code{device-tree-support?} (default: @code{#t})
38028 Whether to support Linux @uref{https://en.wikipedia.org/wiki/Devicetree,
38029 device tree} files loading.
38031 This option in enabled by default. In some cases involving the
38032 @code{u-boot} bootloader, where the device tree has already been loaded
38033 in RAM, it can be handy to disable the option by setting it to
38041 Should you want to list additional boot menu entries @i{via} the
38042 @code{menu-entries} field above, you will need to create them with the
38043 @code{menu-entry} form. For example, imagine you want to be able to
38044 boot another distro (hard to imagine!), you can define a menu entry
38049 (label "The Other Distro")
38050 (linux "/boot/old/vmlinux-2.6.32")
38051 (linux-arguments '("root=/dev/sda2"))
38052 (initrd "/boot/old/initrd"))
38057 @deftp {Data Type} menu-entry
38058 The type of an entry in the bootloader menu.
38063 The label to show in the menu---e.g., @code{"GNU"}.
38065 @item @code{linux} (default: @code{#f})
38066 The Linux kernel image to boot, for example:
38069 (file-append linux-libre "/bzImage")
38072 For GRUB, it is also possible to specify a device explicitly in the
38073 file path using GRUB's device naming convention (@pxref{Naming
38074 convention,,, grub, GNU GRUB manual}), for example:
38077 "(hd0,msdos1)/boot/vmlinuz"
38080 If the device is specified explicitly as above, then the @code{device}
38081 field is ignored entirely.
38083 @item @code{linux-arguments} (default: @code{()})
38084 The list of extra Linux kernel command-line arguments---e.g.,
38085 @code{("console=ttyS0")}.
38087 @item @code{initrd} (default: @code{#f})
38088 A G-Expression or string denoting the file name of the initial RAM disk
38089 to use (@pxref{G-Expressions}).
38091 @item @code{device} (default: @code{#f})
38092 The device where the kernel and initrd are to be found---i.e., for GRUB,
38093 @dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
38095 This may be a file system label (a string), a file system UUID (a
38096 bytevector, @pxref{File Systems}), or @code{#f}, in which case
38097 the bootloader will search the device containing the file specified by
38098 the @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It
38099 must @emph{not} be an OS device name such as @file{/dev/sda1}.
38101 @item @code{multiboot-kernel} (default: @code{#f})
38102 The kernel to boot in Multiboot-mode (@pxref{multiboot,,, grub, GNU GRUB
38103 manual}). When this field is set, a Multiboot menu-entry is generated.
38107 (file-append mach "/boot/gnumach")
38110 @item @code{multiboot-arguments} (default: @code{()})
38111 The list of extra command-line arguments for the multiboot-kernel.
38113 @item @code{multiboot-modules} (default: @code{()})
38114 The list of commands for loading Multiboot modules. For example:
38117 (list (list (file-append hurd "/hurd/ext2fs.static") "ext2fs"
38119 (list (file-append libc "/lib/ld.so.1") "exec"
38123 @item @code{chain-loader} (default: @code{#f})
38124 A string that can be accepted by @code{grub}'s @code{chainloader}
38125 directive. This has no effect if either @code{linux} or
38126 @code{multiboot-kernel} fields are specified. The following is an
38127 example of chainloading a different GNU/Linux system.
38131 (bootloader-configuration
38136 (label "GNU/Linux")
38137 (device (uuid "1C31-A17C" 'fat))
38138 (chain-loader "/EFI/GNULinux/grubx64.efi"))))))
38147 @c FIXME: Write documentation once it's stable.
38148 For now only GRUB has theme support. GRUB themes are created using
38149 the @code{grub-theme} form, which is not fully documented yet.
38151 @deftp {Data Type} grub-theme
38152 Data type representing the configuration of the GRUB theme.
38155 @item @code{gfxmode} (default: @code{'("auto")})
38156 The GRUB @code{gfxmode} to set (a list of screen resolution strings,
38157 @pxref{gfxmode,,, grub, GNU GRUB manual}).
38161 @deffn {Scheme Procedure} grub-theme
38162 Return the default GRUB theme used by the operating system if no
38163 @code{theme} field is specified in @code{bootloader-configuration}
38166 It comes with a fancy background image displaying the GNU and Guix
38170 For example, to override the default resolution, you may use something
38175 (bootloader-configuration
38178 (inherit (grub-theme))
38179 (gfxmode '("1024x786x32" "auto"))))))
38182 @node Invoking guix system
38183 @section Invoking @command{guix system}
38185 @cindex @command{guix system}
38186 Once you have written an operating system declaration as seen in the
38187 previous section, it can be @dfn{instantiated} using the @command{guix
38188 system} command. The synopsis is:
38191 guix system @var{options}@dots{} @var{action} @var{file}
38194 @var{file} must be the name of a file containing an
38195 @code{operating-system} declaration. @var{action} specifies how the
38196 operating system is instantiated. Currently the following values are
38201 Display available service type definitions that match the given regular
38202 expressions, sorted by relevance:
38208 $ guix system search console
38209 name: console-fonts
38210 location: gnu/services/base.scm:806:2
38211 extends: shepherd-root
38212 description: Install the given fonts on the specified ttys (fonts are per
38213 + virtual console on GNU/Linux). The value of this service is a list of
38214 + tty/font pairs. The font can be the name of a font provided by the `kbd'
38215 + package or any valid argument to `setfont', as in this example:
38217 + '(("tty1" . "LatGrkCyr-8x16")
38218 + ("tty2" . (file-append
38220 + "/share/kbd/consolefonts/TamzenForPowerline10x20.psf"))
38221 + ("tty3" . (file-append
38223 + "/share/consolefonts/ter-132n"))) ; for HDPI
38227 location: gnu/services/base.scm:1190:2
38228 extends: shepherd-root
38229 description: Provide console login using the `mingetty' program.
38233 location: gnu/services/base.scm:860:2
38235 description: Provide a console log-in service as specified by its
38236 + configuration value, a `login-configuration' object.
38242 As for @command{guix package --search}, the result is written in
38243 @code{recutils} format, which makes it easy to filter the output
38244 (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
38246 @cindex service type definition, editing
38247 @cindex editing, service type definition
38249 Edit or view the definition of the given service types.
38251 For example, the command below opens your editor, as specified by the
38252 @env{EDITOR} environment variable, on the definition of the
38253 @code{openssh} service type:
38256 guix system edit openssh
38260 Build the operating system described in @var{file}, activate it, and
38261 switch to it@footnote{This action (and the related actions
38262 @code{switch-generation} and @code{roll-back}) are usable only on
38263 systems already running Guix System.}.
38266 @c The paragraph below refers to the problem discussed at
38267 @c <https://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
38268 It is highly recommended to run @command{guix pull} once before you run
38269 @command{guix system reconfigure} for the first time (@pxref{Invoking
38270 guix pull}). Failing to do that you would see an older version of Guix
38271 once @command{reconfigure} has completed.
38274 This effects all the configuration specified in @var{file}: user
38275 accounts, system services, global package list, setuid programs, etc.
38276 The command starts system services specified in @var{file} that are not
38277 currently running; if a service is currently running this command will
38278 arrange for it to be upgraded the next time it is stopped (e.g.@: by
38279 @code{herd stop X} or @code{herd restart X}).
38281 This command creates a new generation whose number is one greater than
38282 the current generation (as reported by @command{guix system
38283 list-generations}). If that generation already exists, it will be
38284 overwritten. This behavior mirrors that of @command{guix package}
38285 (@pxref{Invoking guix package}).
38287 It also adds a bootloader menu entry for the new OS configuration,
38288 ---unless @option{--no-bootloader} is passed. For GRUB, it moves
38289 entries for older configurations to a submenu, allowing you to choose
38290 an older system generation at boot time should you need it.
38292 @cindex provenance tracking, of the operating system
38293 Upon completion, the new system is deployed under
38294 @file{/run/current-system}. This directory contains @dfn{provenance
38295 meta-data}: the list of channels in use (@pxref{Channels}) and
38296 @var{file} itself, when available. You can view it by running:
38299 guix system describe
38302 This information is useful should you later want to inspect how this
38303 particular generation was built. In fact, assuming @var{file} is
38304 self-contained, you can later rebuild generation @var{n} of your
38305 operating system with:
38308 guix time-machine \
38309 -C /var/guix/profiles/system-@var{n}-link/channels.scm -- \
38310 system reconfigure \
38311 /var/guix/profiles/system-@var{n}-link/configuration.scm
38314 You can think of it as some sort of built-in version control! Your
38315 system is not just a binary artifact: @emph{it carries its own source}.
38316 @xref{Service Reference, @code{provenance-service-type}}, for more
38317 information on provenance tracking.
38319 By default, @command{reconfigure} @emph{prevents you from downgrading
38320 your system}, which could (re)introduce security vulnerabilities and
38321 also cause problems with ``stateful'' services such as database
38322 management systems. You can override that behavior by passing
38323 @option{--allow-downgrades}.
38325 @item switch-generation
38326 @cindex generations
38327 Switch to an existing system generation. This action atomically
38328 switches the system profile to the specified system generation. It
38329 also rearranges the system's existing bootloader menu entries. It
38330 makes the menu entry for the specified system generation the default,
38331 and it moves the entries for the other generations to a submenu, if
38332 supported by the bootloader being used. The next time the system
38333 boots, it will use the specified system generation.
38335 The bootloader itself is not being reinstalled when using this
38336 command. Thus, the installed bootloader is used with an updated
38337 configuration file.
38339 The target generation can be specified explicitly by its generation
38340 number. For example, the following invocation would switch to system
38344 guix system switch-generation 7
38347 The target generation can also be specified relative to the current
38348 generation with the form @code{+N} or @code{-N}, where @code{+3} means
38349 ``3 generations ahead of the current generation,'' and @code{-1} means
38350 ``1 generation prior to the current generation.'' When specifying a
38351 negative value such as @code{-1}, you must precede it with @code{--} to
38352 prevent it from being parsed as an option. For example:
38355 guix system switch-generation -- -1
38358 Currently, the effect of invoking this action is @emph{only} to switch
38359 the system profile to an existing generation and rearrange the
38360 bootloader menu entries. To actually start using the target system
38361 generation, you must reboot after running this action. In the future,
38362 it will be updated to do the same things as @command{reconfigure},
38363 like activating and deactivating services.
38365 This action will fail if the specified generation does not exist.
38368 @cindex rolling back
38369 Switch to the preceding system generation. The next time the system
38370 boots, it will use the preceding system generation. This is the inverse
38371 of @command{reconfigure}, and it is exactly the same as invoking
38372 @command{switch-generation} with an argument of @code{-1}.
38374 Currently, as with @command{switch-generation}, you must reboot after
38375 running this action to actually start using the preceding system
38378 @item delete-generations
38379 @cindex deleting system generations
38380 @cindex saving space
38381 Delete system generations, making them candidates for garbage collection
38382 (@pxref{Invoking guix gc}, for information on how to run the ``garbage
38385 This works in the same way as @samp{guix package --delete-generations}
38386 (@pxref{Invoking guix package, @option{--delete-generations}}). With no
38387 arguments, all system generations but the current one are deleted:
38390 guix system delete-generations
38393 You can also select the generations you want to delete. The example below
38394 deletes all the system generations that are more than two months old:
38397 guix system delete-generations 2m
38400 Running this command automatically reinstalls the bootloader with an updated
38401 list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no
38402 longer lists the generations that have been deleted.
38405 Build the derivation of the operating system, which includes all the
38406 configuration files and programs needed to boot and run the system.
38407 This action does not actually install anything.
38410 Populate the given directory with all the files necessary to run the
38411 operating system specified in @var{file}. This is useful for first-time
38412 installations of Guix System. For instance:
38415 guix system init my-os-config.scm /mnt
38418 copies to @file{/mnt} all the store items required by the configuration
38419 specified in @file{my-os-config.scm}. This includes configuration
38420 files, packages, and so on. It also creates other essential files
38421 needed for the system to operate correctly---e.g., the @file{/etc},
38422 @file{/var}, and @file{/run} directories, and the @file{/bin/sh} file.
38424 This command also installs bootloader on the targets specified in
38425 @file{my-os-config}, unless the @option{--no-bootloader} option was
38429 @cindex virtual machine
38431 @anchor{guix system vm}
38432 Build a virtual machine (VM) that contains the operating system declared
38433 in @var{file}, and return a script to run that VM.
38436 The @code{vm} action and others below
38437 can use KVM support in the Linux-libre kernel. Specifically, if the
38438 machine has hardware virtualization support, the corresponding
38439 KVM kernel module should be loaded, and the @file{/dev/kvm} device node
38440 must exist and be readable and writable by the user and by the
38441 build users of the daemon (@pxref{Build Environment Setup}).
38444 Arguments given to the script are passed to QEMU as in the example
38445 below, which enables networking and requests 1@tie{}GiB of RAM for the
38449 $ /gnu/store/@dots{}-run-vm.sh -m 1024 -smp 2 -nic user,model=virtio-net-pci
38452 It's possible to combine the two steps into one:
38455 $ $(guix system vm my-config.scm) -m 1024 -smp 2 -nic user,model=virtio-net-pci
38458 The VM shares its store with the host system.
38460 By default, the root file system of the VM is mounted volatile; the
38461 @option{--persistent} option can be provided to make it persistent
38462 instead. In that case, the VM disk-image file will be copied from the
38463 store to the @env{TMPDIR} directory to make it writable.
38465 Additional file systems can be shared between the host and the VM using
38466 the @option{--share} and @option{--expose} command-line options: the former
38467 specifies a directory to be shared with write access, while the latter
38468 provides read-only access to the shared directory.
38470 The example below creates a VM in which the user's home directory is
38471 accessible read-only, and where the @file{/exchange} directory is a
38472 read-write mapping of @file{$HOME/tmp} on the host:
38475 guix system vm my-config.scm \
38476 --expose=$HOME --share=$HOME/tmp=/exchange
38479 On GNU/Linux, the default is to boot directly to the kernel; this has
38480 the advantage of requiring only a very tiny root disk image since the
38481 store of the host can then be mounted.
38483 The @option{--full-boot} option forces a complete boot sequence, starting
38484 with the bootloader. This requires more disk space since a root image
38485 containing at least the kernel, initrd, and bootloader data files must
38488 The @option{--image-size} option can be used to specify the size of the
38491 The @option{--no-graphic} option will instruct @command{guix system} to
38492 spawn a headless VM that will use the invoking tty for IO. Among other
38493 things, this enables copy-pasting, and scrollback. Use the @kbd{ctrl-a}
38494 prefix to issue QEMU commands; e.g. @kbd{ctrl-a h} prints a help,
38495 @kbd{ctrl-a x} quits the VM, and @kbd{ctrl-a c} switches between the
38496 QEMU monitor and the VM.
38498 @cindex System images, creation in various formats
38499 @cindex Creating system images in various formats
38501 @cindex image, creating disk images
38502 The @code{image} command can produce various image types. The image
38503 type can be selected using the @option{--image-type} option. It
38504 defaults to @code{efi-raw}. When its value is @code{iso9660}, the
38505 @option{--label} option can be used to specify a volume ID with
38506 @code{image}. By default, the root file system of a disk image is
38507 mounted non-volatile; the @option{--volatile} option can be provided to
38508 make it volatile instead. When using @code{image}, the bootloader
38509 installed on the generated image is taken from the provided
38510 @code{operating-system} definition. The following example demonstrates
38511 how to generate an image that uses the @code{grub-efi-bootloader}
38512 bootloader and boot it with QEMU:
38515 image=$(guix system image --image-type=qcow2 \
38516 gnu/system/examples/lightweight-desktop.tmpl)
38517 cp $image /tmp/my-image.qcow2
38518 chmod +w /tmp/my-image.qcow2
38519 qemu-system-x86_64 -enable-kvm -hda /tmp/my-image.qcow2 -m 1000 \
38520 -bios $(guix build ovmf)/share/firmware/ovmf_x64.bin
38523 When using the @code{efi-raw} image type, a raw disk image is produced;
38524 it can be copied as is to a USB stick, for instance. Assuming
38525 @code{/dev/sdc} is the device corresponding to a USB stick, one can copy
38526 the image to it using the following command:
38529 # dd if=$(guix system image my-os.scm) of=/dev/sdc status=progress
38532 The @code{--list-image-types} command lists all the available image
38535 @cindex creating virtual machine images
38536 When using the @code{qcow2} image type, the returned image is in qcow2
38537 format, which the QEMU emulator can efficiently use. @xref{Running Guix
38538 in a VM}, for more information on how to run the image in a virtual
38539 machine. The @code{grub-bootloader} bootloader is always used
38540 independently of what is declared in the @code{operating-system} file
38541 passed as argument. This is to make it easier to work with QEMU, which
38542 uses the SeaBIOS BIOS by default, expecting a bootloader to be installed
38543 in the Master Boot Record (MBR).
38545 @cindex docker-image, creating docker images
38546 When using the @code{docker} image type, a Docker image is produced.
38547 Guix builds the image from scratch, not from a pre-existing Docker base
38548 image. As a result, it contains @emph{exactly} what you define in the
38549 operating system configuration file. You can then load the image and
38550 launch a Docker container using commands like the following:
38553 image_id="$(docker load < guix-system-docker-image.tar.gz)"
38554 container_id="$(docker create $image_id)"
38555 docker start $container_id
38558 This command starts a new Docker container from the specified image. It
38559 will boot the Guix system in the usual manner, which means it will
38560 start any services you have defined in the operating system
38561 configuration. You can get an interactive shell running in the container
38562 using @command{docker exec}:
38565 docker exec -ti $container_id /run/current-system/profile/bin/bash --login
38568 Depending on what you run in the Docker container, it
38569 may be necessary to give the container additional permissions. For
38570 example, if you intend to build software using Guix inside of the Docker
38571 container, you may need to pass the @option{--privileged} option to
38572 @code{docker create}.
38574 Last, the @option{--network} option applies to @command{guix system
38575 docker-image}: it produces an image where network is supposedly shared
38576 with the host, and thus without services like nscd or NetworkManager.
38579 Return a script to run the operating system declared in @var{file}
38580 within a container. Containers are a set of lightweight isolation
38581 mechanisms provided by the kernel Linux-libre. Containers are
38582 substantially less resource-demanding than full virtual machines since
38583 the kernel, shared objects, and other resources can be shared with the
38584 host system; this also means they provide thinner isolation.
38586 Currently, the script must be run as root in order to support more than
38587 a single user and group. The container shares its store with the host
38590 As with the @code{vm} action (@pxref{guix system vm}), additional file
38591 systems to be shared between the host and container can be specified
38592 using the @option{--share} and @option{--expose} options:
38595 guix system container my-config.scm \
38596 --expose=$HOME --share=$HOME/tmp=/exchange
38599 The @option{--share} and @option{--expose} options can also be passed to
38600 the generated script to bind-mount additional directories into the
38604 This option requires Linux-libre 3.19 or newer.
38609 @var{options} can contain any of the common build options (@pxref{Common
38610 Build Options}). In addition, @var{options} can contain one of the
38614 @item --expression=@var{expr}
38615 @itemx -e @var{expr}
38616 Consider the operating-system @var{expr} evaluates to.
38617 This is an alternative to specifying a file which evaluates to an
38619 This is used to generate the Guix system installer @pxref{Building the
38620 Installation Image}).
38622 @item --system=@var{system}
38623 @itemx -s @var{system}
38624 Attempt to build for @var{system} instead of the host system type.
38625 This works as per @command{guix build} (@pxref{Invoking guix build}).
38627 @item --target=@var{triplet}
38628 Cross-build for @var{triplet}, which must be a valid GNU triplet, such
38629 as @code{"aarch64-linux-gnu"} (@pxref{Specifying target triplets, GNU
38630 configuration triplets,, autoconf, Autoconf}).
38634 Return the derivation file name of the given operating system without
38637 @cindex provenance tracking, of the operating system
38638 @item --save-provenance
38639 As discussed above, @command{guix system init} and @command{guix system
38640 reconfigure} always save provenance information @i{via} a dedicated
38641 service (@pxref{Service Reference, @code{provenance-service-type}}).
38642 However, other commands don't do that by default. If you wish to, say,
38643 create a virtual machine image that contains provenance information, you
38647 guix system image -t qcow2 --save-provenance config.scm
38650 That way, the resulting image will effectively ``embed its own source''
38651 in the form of meta-data in @file{/run/current-system}. With that
38652 information, one can rebuild the image to make sure it really contains
38653 what it pretends to contain; or they could use that to derive a variant
38656 @item --image-type=@var{type}
38657 @itemx -t @var{type}
38658 For the @code{image} action, create an image with given @var{type}.
38660 When this option is omitted, @command{guix system} uses the
38661 @code{efi-raw} image type.
38663 @cindex ISO-9660 format
38664 @cindex CD image format
38665 @cindex DVD image format
38666 @option{--image-type=iso9660} produces an ISO-9660 image, suitable
38667 for burning on CDs and DVDs.
38669 @item --image-size=@var{size}
38670 For the @code{image} action, create an image of the given @var{size}.
38671 @var{size} may be a number of bytes, or it may include a unit as a
38672 suffix (@pxref{Block size, size specifications,, coreutils, GNU
38675 When this option is omitted, @command{guix system} computes an estimate
38676 of the image size as a function of the size of the system declared in
38681 For the @code{container} action, allow containers to access the host network,
38682 that is, do not create a network namespace.
38684 @item --root=@var{file}
38685 @itemx -r @var{file}
38686 Make @var{file} a symlink to the result, and register it as a garbage
38689 @item --skip-checks
38690 Skip pre-installation safety checks.
38692 By default, @command{guix system init} and @command{guix system
38693 reconfigure} perform safety checks: they make sure the file systems that
38694 appear in the @code{operating-system} declaration actually exist
38695 (@pxref{File Systems}), and that any Linux kernel modules that may be
38696 needed at boot time are listed in @code{initrd-modules} (@pxref{Initial
38697 RAM Disk}). Passing this option skips these tests altogether.
38699 @item --allow-downgrades
38700 Instruct @command{guix system reconfigure} to allow system downgrades.
38702 By default, @command{reconfigure} prevents you from downgrading your
38703 system. It achieves that by comparing the provenance info of your
38704 system (shown by @command{guix system describe}) with that of your
38705 @command{guix} command (shown by @command{guix describe}). If the
38706 commits for @command{guix} are not descendants of those used for your
38707 system, @command{guix system reconfigure} errors out. Passing
38708 @option{--allow-downgrades} allows you to bypass these checks.
38711 Make sure you understand its security implications before using
38712 @option{--allow-downgrades}.
38716 @cindex on-error strategy
38717 @cindex error strategy
38718 @item --on-error=@var{strategy}
38719 Apply @var{strategy} when an error occurs when reading @var{file}.
38720 @var{strategy} may be one of the following:
38723 @item nothing-special
38724 Report the error concisely and exit. This is the default strategy.
38727 Likewise, but also display a backtrace.
38730 Report the error and enter Guile's debugger. From there, you can run
38731 commands such as @code{,bt} to get a backtrace, @code{,locals} to
38732 display local variable values, and more generally inspect the state of the
38733 program. @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for
38734 a list of available debugging commands.
38738 Once you have built, configured, re-configured, and re-re-configured
38739 your Guix installation, you may find it useful to list the operating
38740 system generations available on disk---and that you can choose from the
38741 bootloader boot menu:
38746 Describe the running system generation: its file name, the kernel and
38747 bootloader used, etc., as well as provenance information when available.
38749 The @code{--list-installed} flag is available, with the same
38750 syntax that is used in @command{guix package --list-installed}
38751 (@pxref{Invoking guix package}). When the flag is used,
38752 the description will include a list of packages that are currently
38753 installed in the system profile, with optional filtering based on a
38754 regular expression.
38757 The @emph{running} system generation---referred to by
38758 @file{/run/current-system}---is not necessarily the @emph{current}
38759 system generation---referred to by @file{/var/guix/profiles/system}: it
38760 differs when, for instance, you chose from the bootloader menu to boot
38761 an older generation.
38763 It can also differ from the @emph{booted} system generation---referred
38764 to by @file{/run/booted-system}---for instance because you reconfigured
38765 the system in the meantime.
38768 @item list-generations
38769 List a summary of each generation of the operating system available on
38770 disk, in a human-readable way. This is similar to the
38771 @option{--list-generations} option of @command{guix package}
38772 (@pxref{Invoking guix package}).
38774 Optionally, one can specify a pattern, with the same syntax that is used
38775 in @command{guix package --list-generations}, to restrict the list of
38776 generations displayed. For instance, the following command displays
38777 generations that are up to 10 days old:
38780 $ guix system list-generations 10d
38783 The @code{--list-installed} flag may also be specified, with the same
38784 syntax that is used in @command{guix package --list-installed}. This
38785 may be helpful if trying to determine when a package was added to the
38790 The @command{guix system} command has even more to offer! The following
38791 sub-commands allow you to visualize how your system services relate to
38794 @anchor{system-extension-graph}
38797 @item extension-graph
38798 Emit to standard output the @dfn{service
38799 extension graph} of the operating system defined in @var{file}
38800 (@pxref{Service Composition}, for more information on service
38801 extensions). By default the output is in Dot/Graphviz format, but you
38802 can choose a different format with @option{--graph-backend}, as with
38803 @command{guix graph} (@pxref{Invoking guix graph, @option{--backend}}):
38808 $ guix system extension-graph @var{file} | xdot -
38811 shows the extension relations among services.
38814 The @command{dot} program is provided by the @code{graphviz} package.
38817 @anchor{system-shepherd-graph}
38818 @item shepherd-graph
38819 Emit to standard output the @dfn{dependency
38820 graph} of shepherd services of the operating system defined in
38821 @var{file}. @xref{Shepherd Services}, for more information and for an
38824 Again, the default output format is Dot/Graphviz, but you can pass
38825 @option{--graph-backend} to select a different one.
38829 @node Invoking guix deploy
38830 @section Invoking @command{guix deploy}
38832 @cindex @command{guix deploy}
38833 We've already seen @code{operating-system} declarations used to manage a
38834 machine's configuration locally. Suppose you need to configure multiple
38835 machines, though---perhaps you're managing a service on the web that's
38836 comprised of several servers. @command{guix deploy} enables you to use those
38837 same @code{operating-system} declarations to manage multiple remote hosts at
38838 once as a logical ``deployment''.
38841 The functionality described in this section is still under development
38842 and is subject to change. Get in touch with us on
38843 @email{guix-devel@@gnu.org}!
38847 guix deploy @var{file}
38850 Such an invocation will deploy the machines that the code within @var{file}
38851 evaluates to. As an example, @var{file} might contain a definition like this:
38854 ;; This is a Guix deployment of a "bare bones" setup, with
38855 ;; no X11 display server, to a machine with an SSH daemon
38856 ;; listening on localhost:2222. A configuration such as this
38857 ;; may be appropriate for virtual machine with ports
38858 ;; forwarded to the host's loopback interface.
38860 (use-service-modules networking ssh)
38861 (use-package-modules bootloaders)
38865 (host-name "gnu-deployed")
38866 (timezone "Etc/UTC")
38867 (bootloader (bootloader-configuration
38868 (bootloader grub-bootloader)
38869 (targets '("/dev/vda"))
38870 (terminal-outputs '(console))))
38871 (file-systems (cons (file-system
38873 (device "/dev/vda1")
38875 %base-file-systems))
38877 (append (list (service dhcp-client-service-type)
38878 (service openssh-service-type
38879 (openssh-configuration
38880 (permit-root-login #t)
38881 (allow-empty-passwords? #t))))
38885 (operating-system %system)
38886 (environment managed-host-environment-type)
38887 (configuration (machine-ssh-configuration
38888 (host-name "localhost")
38889 (system "x86_64-linux")
38891 (identity "./id_rsa")
38895 The file should evaluate to a list of @var{machine} objects. This example,
38896 upon being deployed, will create a new generation on the remote system
38897 realizing the @code{operating-system} declaration @code{%system}.
38898 @code{environment} and @code{configuration} specify how the machine should be
38899 provisioned---that is, how the computing resources should be created and
38900 managed. The above example does not create any resources, as a
38901 @code{'managed-host} is a machine that is already running the Guix system and
38902 available over the network. This is a particularly simple case; a more
38903 complex deployment may involve, for example, starting virtual machines through
38904 a Virtual Private Server (VPS) provider. In such a case, a different
38905 @var{environment} type would be used.
38907 Do note that you first need to generate a key pair on the coordinator machine
38908 to allow the daemon to export signed archives of files from the store
38909 (@pxref{Invoking guix archive}), though this step is automatic on Guix
38913 # guix archive --generate-key
38917 Each target machine must authorize the key of the master machine so that it
38918 accepts store items it receives from the coordinator:
38921 # guix archive --authorize < coordinator-public-key.txt
38924 @code{user}, in this example, specifies the name of the user account to log in
38925 as to perform the deployment. Its default value is @code{root}, but root
38926 login over SSH may be forbidden in some cases. To work around this,
38927 @command{guix deploy} can log in as an unprivileged user and employ
38928 @code{sudo} to escalate privileges. This will only work if @code{sudo} is
38929 currently installed on the remote and can be invoked non-interactively as
38930 @code{user}. That is, the line in @code{sudoers} granting @code{user} the
38931 ability to use @code{sudo} must contain the @code{NOPASSWD} tag. This can
38932 be accomplished with the following operating system configuration snippet:
38936 (gnu system)) ;for %sudoers-specification
38938 (define %user "username")
38943 (plain-file "sudoers"
38944 (string-append (plain-file-content %sudoers-specification)
38945 (format #f "~a ALL = NOPASSWD: ALL~%"
38950 For more information regarding the format of the @file{sudoers} file,
38951 consult @command{man sudoers}.
38953 Once you've deployed a system on a set of machines, you may find it
38954 useful to run a command on all of them. The @option{--execute} or
38955 @option{-x} option lets you do that; the example below runs
38956 @command{uname -a} on all the machines listed in the deployment file:
38959 guix deploy @var{file} -x -- uname -a
38962 One thing you may often need to do after deployment is restart specific
38963 services on all the machines, which you can do like so:
38966 guix deploy @var{file} -x -- herd restart @var{service}
38969 The @command{guix deploy -x} command returns zero if and only if the
38970 command succeeded on all the machines.
38972 @c FIXME/TODO: Separate the API doc from the CLI doc.
38974 Below are the data types you need to know about when writing a
38977 @deftp {Data Type} machine
38978 This is the data type representing a single machine in a heterogeneous Guix
38982 @item @code{operating-system}
38983 The object of the operating system configuration to deploy.
38985 @item @code{environment}
38986 An @code{environment-type} describing how the machine should be provisioned.
38988 @item @code{configuration} (default: @code{#f})
38989 An object describing the configuration for the machine's @code{environment}.
38990 If the @code{environment} has a default configuration, @code{#f} may be used.
38991 If @code{#f} is used for an environment with no default configuration,
38992 however, an error will be thrown.
38996 @deftp {Data Type} machine-ssh-configuration
38997 This is the data type representing the SSH client parameters for a machine
38998 with an @code{environment} of @code{managed-host-environment-type}.
39001 @item @code{host-name}
39002 @item @code{build-locally?} (default: @code{#t})
39003 If false, system derivations will be built on the machine being deployed to.
39004 @item @code{system}
39005 The system type describing the architecture of the machine being deployed
39006 to---e.g., @code{"x86_64-linux"}.
39007 @item @code{authorize?} (default: @code{#t})
39008 If true, the coordinator's signing key will be added to the remote's ACL
39010 @item @code{port} (default: @code{22})
39011 @item @code{user} (default: @code{"root"})
39012 @item @code{identity} (default: @code{#f})
39013 If specified, the path to the SSH private key to use to authenticate with the
39016 @item @code{host-key} (default: @code{#f})
39017 This should be the SSH host key of the machine, which looks like this:
39020 ssh-ed25519 AAAAC3Nz@dots{} root@@example.org
39023 When @code{host-key} is @code{#f}, the server is authenticated against
39024 the @file{~/.ssh/known_hosts} file, just like the OpenSSH @command{ssh}
39027 @item @code{allow-downgrades?} (default: @code{#f})
39028 Whether to allow potential downgrades.
39030 Like @command{guix system reconfigure}, @command{guix deploy} compares
39031 the channel commits currently deployed on the remote host (as returned
39032 by @command{guix system describe}) to those currently in use (as
39033 returned by @command{guix describe}) to determine whether commits
39034 currently in use are descendants of those deployed. When this is not
39035 the case and @code{allow-downgrades?} is false, it raises an error.
39036 This ensures you do not accidentally downgrade remote machines.
39038 @item @code{safety-checks?} (default: @code{#t})
39039 Whether to perform ``safety checks'' before deployment. This includes
39040 verifying that devices and file systems referred to in the operating
39041 system configuration actually exist on the target machine, and making
39042 sure that Linux modules required to access storage devices at boot time
39043 are listed in the @code{initrd-modules} field of the operating system.
39045 These safety checks ensure that you do not inadvertently deploy a system
39046 that would fail to boot. Be careful before turning them off!
39050 @deftp {Data Type} digital-ocean-configuration
39051 This is the data type describing the Droplet that should be created for a
39052 machine with an @code{environment} of @code{digital-ocean-environment-type}.
39055 @item @code{ssh-key}
39056 The path to the SSH private key to use to authenticate with the remote
39057 host. In the future, this field may not exist.
39059 A list of string ``tags'' that uniquely identify the machine. Must be given
39060 such that no two machines in the deployment have the same set of tags.
39061 @item @code{region}
39062 A Digital Ocean region slug, such as @code{"nyc3"}.
39064 A Digital Ocean size slug, such as @code{"s-1vcpu-1gb"}
39065 @item @code{enable-ipv6?}
39066 Whether or not the droplet should be created with IPv6 networking.
39070 @node Running Guix in a VM
39071 @section Running Guix in a Virtual Machine
39073 @cindex virtual machine
39074 To run Guix in a virtual machine (VM), one can use the pre-built Guix VM
39075 image distributed at
39076 @url{@value{BASE-URL}/guix-system-vm-image-@value{VERSION}.x86_64-linux.qcow2}.
39077 This image is a compressed image in QCOW format. You can pass it to an
39078 emulator such as @uref{https://qemu.org/, QEMU} (see below for details).
39080 This image boots the Xfce graphical environment and it contains some
39081 commonly used tools. You can install more software in the image by running
39082 @command{guix package} in a terminal (@pxref{Invoking guix package}). You can
39083 also reconfigure the system based on its initial configuration file available
39084 as @file{/run/current-system/configuration.scm} (@pxref{Using the
39085 Configuration System}).
39087 Instead of using this pre-built image, one can also build their own
39088 image using @command{guix system image} (@pxref{Invoking guix system}).
39091 If you built your own image, you must copy it out of the store
39092 (@pxref{The Store}) and give yourself permission to write to the copy
39093 before you can use it. When invoking QEMU, you must choose a system
39094 emulator that is suitable for your hardware platform. Here is a minimal
39095 QEMU invocation that will boot the result of @command{guix system
39096 image -t qcow2} on x86_64 hardware:
39099 $ qemu-system-x86_64 \
39100 -nic user,model=virtio-net-pci \
39101 -enable-kvm -m 2048 \
39102 -device virtio-blk,drive=myhd \
39103 -drive if=none,file=/tmp/qemu-image,id=myhd
39106 Here is what each of these options means:
39109 @item qemu-system-x86_64
39110 This specifies the hardware platform to emulate. This should match the
39113 @item -nic user,model=virtio-net-pci
39114 Enable the unprivileged user-mode network stack. The guest OS can
39115 access the host but not vice versa. This is the simplest way to get the
39116 guest OS online. @code{model} specifies which network device to emulate:
39117 @code{virtio-net-pci} is a special device made for virtualized operating
39118 systems and recommended for most uses. Assuming your hardware platform is
39119 x86_64, you can get a list of available NIC models by running
39120 @command{qemu-system-x86_64 -nic model=help}.
39123 If your system has hardware virtualization extensions, enabling the
39124 virtual machine support (KVM) of the Linux kernel will make things run
39127 @c To run Xfce + 'guix pull', we need at least 1G of RAM.
39129 RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
39130 which may be insufficient for some operations.
39132 @item -device virtio-blk,drive=myhd
39133 Create a @code{virtio-blk} drive called ``myhd''. @code{virtio-blk} is a
39134 ``paravirtualization'' mechanism for block devices that allows QEMU to achieve
39135 better performance than if it were emulating a complete disk drive. See the
39136 QEMU and KVM documentation for more info.
39138 @item -drive if=none,file=/tmp/qemu-image,id=myhd
39139 Use our QCOW image, the @file{/tmp/qemu-image} file, as the backing
39140 store of the ``myhd'' drive.
39143 The default @command{run-vm.sh} script that is returned by an invocation of
39144 @command{guix system vm} does not add a @command{-nic user} flag by default.
39145 To get network access from within the vm add the @code{(dhcp-client-service)}
39146 to your system definition and start the VM using
39147 @command{$(guix system vm config.scm) -nic user}. An important caveat of using
39148 @command{-nic user} for networking is that @command{ping} will not work, because
39149 it uses the ICMP protocol. You'll have to use a different command to check for
39150 network connectivity, for example @command{guix download}.
39152 @subsection Connecting Through SSH
39156 To enable SSH inside a VM you need to add an SSH server like
39157 @code{openssh-service-type} to your VM (@pxref{Networking Services,
39158 @code{openssh-service-type}}). In addition you need to forward the SSH port,
39159 22 by default, to the host. You can do this with
39162 $(guix system vm config.scm) -nic user,model=virtio-net-pci,hostfwd=tcp::10022-:22
39165 To connect to the VM you can run
39168 ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 localhost
39171 The @command{-p} tells @command{ssh} the port you want to connect to.
39172 @command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from complaining
39173 every time you modify your @command{config.scm} file and the
39174 @command{-o StrictHostKeyChecking=no} prevents you from having to allow a
39175 connection to an unknown host every time you connect.
39178 If you find the above @samp{hostfwd} example not to be working (e.g.,
39179 your SSH client hangs attempting to connect to the mapped port of your
39180 VM), make sure that your Guix System VM has networking support, such as
39181 by using the @code{dhcp-client-service-type} service type.
39184 @subsection Using @command{virt-viewer} with Spice
39186 As an alternative to the default @command{qemu} graphical client you can
39187 use the @command{remote-viewer} from the @command{virt-viewer} package. To
39188 connect pass the @command{-spice port=5930,disable-ticketing} flag to
39189 @command{qemu}. See previous section for further information on how to do this.
39191 Spice also allows you to do some nice stuff like share your clipboard with your
39192 VM@. To enable that you'll also have to pass the following flags to @command{qemu}:
39195 -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
39196 -chardev spicevmc,name=vdagent,id=vdagent
39197 -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,\
39198 name=com.redhat.spice.0
39201 You'll also need to add the @code{(spice-vdagent-service)} to your
39202 system definition (@pxref{Miscellaneous Services, Spice service}).
39204 @node Defining Services
39205 @section Defining Services
39207 The previous sections show the available services and how one can combine
39208 them in an @code{operating-system} declaration. But how do we define
39209 them in the first place? And what is a service anyway?
39212 * Service Composition:: The model for composing services.
39213 * Service Types and Services:: Types and services.
39214 * Service Reference:: API reference.
39215 * Shepherd Services:: A particular type of service.
39216 * Complex Configurations:: Defining bindings for complex configurations.
39219 @node Service Composition
39220 @subsection Service Composition
39224 Here we define a @dfn{service} as, broadly, something that extends the
39225 functionality of the operating system. Often a service is a process---a
39226 @dfn{daemon}---started when the system boots: a secure shell server, a
39227 Web server, the Guix build daemon, etc. Sometimes a service is a daemon
39228 whose execution can be triggered by another daemon---e.g., an FTP server
39229 started by @command{inetd} or a D-Bus service activated by
39230 @command{dbus-daemon}. Occasionally, a service does not map to a
39231 daemon. For instance, the ``account'' service collects user accounts
39232 and makes sure they exist when the system runs; the ``udev'' service
39233 collects device management rules and makes them available to the eudev
39234 daemon; the @file{/etc} service populates the @file{/etc} directory
39237 @cindex service extensions
39238 Guix system services are connected by @dfn{extensions}. For instance, the
39239 secure shell service @emph{extends} the Shepherd---the
39240 initialization system, running as PID@tie{}1---by giving it the command
39241 lines to start and stop the secure shell daemon (@pxref{Networking
39242 Services, @code{openssh-service-type}}); the UPower service extends the D-Bus
39243 service by passing it its @file{.service} specification, and extends the
39244 udev service by passing it device management rules (@pxref{Desktop
39245 Services, @code{upower-service}}); the Guix daemon service extends the
39246 Shepherd by passing it the command lines to start and stop the daemon,
39247 and extends the account service by passing it a list of required build
39248 user accounts (@pxref{Base Services}).
39250 All in all, services and their ``extends'' relations form a directed
39251 acyclic graph (DAG). If we represent services as boxes and extensions
39252 as arrows, a typical system might provide something like this:
39254 @image{images/service-graph,,5in,Typical service extension graph.}
39256 @cindex system service
39257 At the bottom, we see the @dfn{system service}, which produces the
39258 directory containing everything to run and boot the system, as returned
39259 by the @command{guix system build} command. @xref{Service Reference},
39260 to learn about the other service types shown here.
39261 @xref{system-extension-graph, the @command{guix system extension-graph}
39262 command}, for information on how to generate this representation for a
39263 particular operating system definition.
39265 @cindex service types
39266 Technically, developers can define @dfn{service types} to express these
39267 relations. There can be any number of services of a given type on the
39268 system---for instance, a system running two instances of the GNU secure
39269 shell server (lsh) has two instances of @code{lsh-service-type}, with
39270 different parameters.
39272 The following section describes the programming interface for service
39273 types and services.
39275 @node Service Types and Services
39276 @subsection Service Types and Services
39278 A @dfn{service type} is a node in the DAG described above. Let us start
39279 with a simple example, the service type for the Guix build daemon
39280 (@pxref{Invoking guix-daemon}):
39283 (define guix-service-type
39287 (list (service-extension shepherd-root-service-type guix-shepherd-service)
39288 (service-extension account-service-type guix-accounts)
39289 (service-extension activation-service-type guix-activation)))
39290 (default-value (guix-configuration))))
39294 It defines three things:
39298 A name, whose sole purpose is to make inspection and debugging easier.
39301 A list of @dfn{service extensions}, where each extension designates the
39302 target service type and a procedure that, given the parameters of the
39303 service, returns a list of objects to extend the service of that type.
39305 Every service type has at least one service extension. The only
39306 exception is the @dfn{boot service type}, which is the ultimate service.
39309 Optionally, a default value for instances of this type.
39312 In this example, @code{guix-service-type} extends three services:
39315 @item shepherd-root-service-type
39316 The @code{guix-shepherd-service} procedure defines how the Shepherd
39317 service is extended. Namely, it returns a @code{<shepherd-service>}
39318 object that defines how @command{guix-daemon} is started and stopped
39319 (@pxref{Shepherd Services}).
39321 @item account-service-type
39322 This extension for this service is computed by @code{guix-accounts},
39323 which returns a list of @code{user-group} and @code{user-account}
39324 objects representing the build user accounts (@pxref{Invoking
39327 @item activation-service-type
39328 Here @code{guix-activation} is a procedure that returns a gexp, which is
39329 a code snippet to run at ``activation time''---e.g., when the service is
39333 A service of this type is instantiated like this:
39336 (service guix-service-type
39337 (guix-configuration
39339 (extra-options '("--gc-keep-derivations"))))
39342 The second argument to the @code{service} form is a value representing
39343 the parameters of this specific service instance.
39344 @xref{guix-configuration-type, @code{guix-configuration}}, for
39345 information about the @code{guix-configuration} data type. When the
39346 value is omitted, the default value specified by
39347 @code{guix-service-type} is used:
39350 (service guix-service-type)
39353 @code{guix-service-type} is quite simple because it extends other
39354 services but is not extensible itself.
39356 @c @subsubsubsection Extensible Service Types
39358 The service type for an @emph{extensible} service looks like this:
39361 (define udev-service-type
39362 (service-type (name 'udev)
39364 (list (service-extension shepherd-root-service-type
39365 udev-shepherd-service)))
39367 (compose concatenate) ;concatenate the list of rules
39368 (extend (lambda (config rules)
39370 (($ <udev-configuration> udev initial-rules)
39371 (udev-configuration
39372 (udev udev) ;the udev package to use
39373 (rules (append initial-rules rules)))))))))
39376 This is the service type for the
39377 @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device
39378 management daemon}. Compared to the previous example, in addition to an
39379 extension of @code{shepherd-root-service-type}, we see two new fields:
39383 This is the procedure to @dfn{compose} the list of extensions to
39384 services of this type.
39386 Services can extend the udev service by passing it lists of rules; we
39387 compose those extensions simply by concatenating them.
39390 This procedure defines how the value of the service is @dfn{extended} with
39391 the composition of the extensions.
39393 Udev extensions are composed into a list of rules, but the udev service
39394 value is itself a @code{<udev-configuration>} record. So here, we
39395 extend that record by appending the list of rules it contains to the
39396 list of contributed rules.
39399 This is a string giving an overview of the service type. The string can
39400 contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}). The
39401 @command{guix system search} command searches these strings and displays
39402 them (@pxref{Invoking guix system}).
39405 There can be only one instance of an extensible service type such as
39406 @code{udev-service-type}. If there were more, the
39407 @code{service-extension} specifications would be ambiguous.
39409 Still here? The next section provides a reference of the programming
39410 interface for services.
39412 @node Service Reference
39413 @subsection Service Reference
39415 We have seen an overview of service types (@pxref{Service Types and
39416 Services}). This section provides a reference on how to manipulate
39417 services and service types. This interface is provided by the
39418 @code{(gnu services)} module.
39420 @deffn {Scheme Procedure} service @var{type} [@var{value}]
39421 Return a new service of @var{type}, a @code{<service-type>} object (see
39422 below). @var{value} can be any object; it represents the parameters of
39423 this particular service instance.
39425 When @var{value} is omitted, the default value specified by @var{type}
39426 is used; if @var{type} does not specify a default value, an error is
39429 For instance, this:
39432 (service openssh-service-type)
39436 is equivalent to this:
39439 (service openssh-service-type
39440 (openssh-configuration))
39443 In both cases the result is an instance of @code{openssh-service-type}
39444 with the default configuration.
39447 @deffn {Scheme Procedure} service? @var{obj}
39448 Return true if @var{obj} is a service.
39451 @deffn {Scheme Procedure} service-kind @var{service}
39452 Return the type of @var{service}---i.e., a @code{<service-type>} object.
39455 @deffn {Scheme Procedure} service-value @var{service}
39456 Return the value associated with @var{service}. It represents its
39460 Here is an example of how a service is created and manipulated:
39464 (service nginx-service-type
39465 (nginx-configuration
39467 (log-directory log-directory)
39468 (run-directory run-directory)
39469 (file config-file))))
39474 (eq? (service-kind s) nginx-service-type)
39478 The @code{modify-services} form provides a handy way to change the
39479 parameters of some of the services of a list such as
39480 @code{%base-services} (@pxref{Base Services, @code{%base-services}}). It
39481 evaluates to a list of services. Of course, you could always use
39482 standard list combinators such as @code{map} and @code{fold} to do that
39483 (@pxref{SRFI-1, List Library,, guile, GNU Guile Reference Manual});
39484 @code{modify-services} simply provides a more concise form for this
39487 @deffn {Scheme Syntax} modify-services @var{services} @
39488 (@var{type} @var{variable} => @var{body}) @dots{}
39490 Modify the services listed in @var{services} according to the given
39491 clauses. Each clause has the form:
39494 (@var{type} @var{variable} => @var{body})
39497 where @var{type} is a service type---e.g.,
39498 @code{guix-service-type}---and @var{variable} is an identifier that is
39499 bound within the @var{body} to the service parameters---e.g., a
39500 @code{guix-configuration} instance---of the original service of that
39503 The @var{body} should evaluate to the new service parameters, which will
39504 be used to configure the new service. This new service will replace the
39505 original in the resulting list. Because a service's service parameters
39506 are created using @code{define-record-type*}, you can write a succinct
39507 @var{body} that evaluates to the new service parameters by using the
39508 @code{inherit} feature that @code{define-record-type*} provides.
39510 Clauses can also have the following form:
39513 (delete @var{type})
39516 Such a clause removes all services of the given @var{type} from
39519 @xref{Using the Configuration System}, for example usage.
39523 Next comes the programming interface for service types. This is
39524 something you want to know when writing new service definitions, but not
39525 necessarily when simply looking for ways to customize your
39526 @code{operating-system} declaration.
39528 @deftp {Data Type} service-type
39529 @cindex service type
39530 This is the representation of a @dfn{service type} (@pxref{Service Types
39535 This is a symbol, used only to simplify inspection and debugging.
39537 @item @code{extensions}
39538 A non-empty list of @code{<service-extension>} objects (see below).
39540 @item @code{compose} (default: @code{#f})
39541 If this is @code{#f}, then the service type denotes services that cannot
39542 be extended---i.e., services that do not receive ``values'' from other
39545 Otherwise, it must be a one-argument procedure. The procedure is called
39546 by @code{fold-services} and is passed a list of values collected from
39547 extensions. It may return any single value.
39549 @item @code{extend} (default: @code{#f})
39550 If this is @code{#f}, services of this type cannot be extended.
39552 Otherwise, it must be a two-argument procedure: @code{fold-services}
39553 calls it, passing it the initial value of the service as the first
39554 argument and the result of applying @code{compose} to the extension
39555 values as the second argument. It must return a value that is a valid
39556 parameter value for the service instance.
39558 @item @code{description}
39559 This is a string, possibly using Texinfo markup, describing in a couple
39560 of sentences what the service is about. This string allows users to
39561 find about the service through @command{guix system search}
39562 (@pxref{Invoking guix system}).
39564 @item @code{default-value} (default: @code{&no-default-value})
39565 The default value associated for instances of this service type. This
39566 allows users to use the @code{service} form without its second argument:
39569 (service @var{type})
39572 The returned service in this case has the default value specified by
39576 @xref{Service Types and Services}, for examples.
39579 @deffn {Scheme Procedure} service-extension @var{target-type} @
39581 Return a new extension for services of type @var{target-type}.
39582 @var{compute} must be a one-argument procedure: @code{fold-services}
39583 calls it, passing it the value associated with the service that provides
39584 the extension; it must return a valid value for the target service.
39587 @deffn {Scheme Procedure} service-extension? @var{obj}
39588 Return true if @var{obj} is a service extension.
39591 Occasionally, you might want to simply extend an existing service. This
39592 involves creating a new service type and specifying the extension of
39593 interest, which can be verbose; the @code{simple-service} procedure
39594 provides a shorthand for this.
39596 @deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
39597 Return a service that extends @var{target} with @var{value}. This works
39598 by creating a singleton service type @var{name}, of which the returned
39599 service is an instance.
39601 For example, this extends mcron (@pxref{Scheduled Job Execution}) with
39605 (simple-service 'my-mcron-job mcron-service-type
39606 #~(job '(next-hour (3)) "guix gc -F 2G"))
39610 At the core of the service abstraction lies the @code{fold-services}
39611 procedure, which is responsible for ``compiling'' a list of services
39612 down to a single directory that contains everything needed to boot and
39613 run the system---the directory shown by the @command{guix system build}
39614 command (@pxref{Invoking guix system}). In essence, it propagates
39615 service extensions down the service graph, updating each node parameters
39616 on the way, until it reaches the root node.
39618 @deffn {Scheme Procedure} fold-services @var{services} @
39619 [#:target-type @var{system-service-type}]
39620 Fold @var{services} by propagating their extensions down to the root of
39621 type @var{target-type}; return the root service adjusted accordingly.
39624 Lastly, the @code{(gnu services)} module also defines several essential
39625 service types, some of which are listed below.
39627 @defvr {Scheme Variable} system-service-type
39628 This is the root of the service graph. It produces the system directory
39629 as returned by the @command{guix system build} command.
39632 @defvr {Scheme Variable} boot-service-type
39633 The type of the ``boot service'', which produces the @dfn{boot script}.
39634 The boot script is what the initial RAM disk runs when booting.
39637 @defvr {Scheme Variable} etc-service-type
39638 The type of the @file{/etc} service. This service is used to create
39639 files under @file{/etc} and can be extended by
39640 passing it name/file tuples such as:
39643 (list `("issue" ,(plain-file "issue" "Welcome!\n")))
39646 In this example, the effect would be to add an @file{/etc/issue} file
39647 pointing to the given file.
39650 @defvr {Scheme Variable} setuid-program-service-type
39651 Type for the ``setuid-program service''. This service collects lists of
39652 executable file names, passed as gexps, and adds them to the set of
39653 setuid and setgid programs on the system (@pxref{Setuid Programs}).
39656 @defvr {Scheme Variable} profile-service-type
39657 Type of the service that populates the @dfn{system profile}---i.e., the
39658 programs under @file{/run/current-system/profile}. Other services can
39659 extend it by passing it lists of packages to add to the system profile.
39662 @cindex provenance tracking, of the operating system
39663 @anchor{provenance-service-type}
39664 @defvr {Scheme Variable} provenance-service-type
39665 This is the type of the service that records @dfn{provenance meta-data}
39666 in the system itself. It creates several files under
39667 @file{/run/current-system}:
39671 This is a ``channel file'' that can be passed to @command{guix pull -C}
39672 or @command{guix time-machine -C}, and which describes the channels used
39673 to build the system, if that information was available
39674 (@pxref{Channels}).
39676 @item configuration.scm
39677 This is the file that was passed as the value for this
39678 @code{provenance-service-type} service. By default, @command{guix
39679 system reconfigure} automatically passes the OS configuration file it
39680 received on the command line.
39683 This contains the same information as the two other files but in a
39684 format that is more readily processable.
39687 In general, these two pieces of information (channels and configuration
39688 file) are enough to reproduce the operating system ``from source''.
39691 This information is necessary to rebuild your operating system, but it
39692 is not always sufficient. In particular, @file{configuration.scm}
39693 itself is insufficient if it is not self-contained---if it refers to
39694 external Guile modules or to extra files. If you want
39695 @file{configuration.scm} to be self-contained, we recommend that modules
39696 or files it refers to be part of a channel.
39698 Besides, provenance meta-data is ``silent'' in the sense that it does
39699 not change the bits contained in your system, @emph{except for the
39700 meta-data bits themselves}. Two different OS configurations or sets of
39701 channels can lead to the same system, bit-for-bit; when
39702 @code{provenance-service-type} is used, these two systems will have
39703 different meta-data and thus different store file names, which makes
39704 comparison less trivial.
39707 This service is automatically added to your operating system
39708 configuration when you use @command{guix system reconfigure},
39709 @command{guix system init}, or @command{guix deploy}.
39712 @defvr {Scheme Variable} linux-loadable-module-service-type
39713 Type of the service that collects lists of packages containing
39714 kernel-loadable modules, and adds them to the set of kernel-loadable
39717 This service type is intended to be extended by other service types,
39721 (simple-service 'installing-module
39722 linux-loadable-module-service-type
39723 (list module-to-install-1
39724 module-to-install-2))
39727 This does not actually load modules at bootup, only adds it to the
39728 kernel profile so that it @emph{can} be loaded by other means.
39731 @node Shepherd Services
39732 @subsection Shepherd Services
39734 @cindex shepherd services
39736 @cindex init system
39737 The @code{(gnu services shepherd)} module provides a way to define
39738 services managed by the GNU@tie{}Shepherd, which is the
39739 initialization system---the first process that is started when the
39740 system boots, also known as PID@tie{}1
39741 (@pxref{Introduction,,, shepherd, The GNU Shepherd Manual}).
39743 Services in the Shepherd can depend on each other. For instance, the
39744 SSH daemon may need to be started after the syslog daemon has been
39745 started, which in turn can only happen once all the file systems have
39746 been mounted. The simple operating system defined earlier (@pxref{Using
39747 the Configuration System}) results in a service graph like this:
39749 @image{images/shepherd-graph,,5in,Typical shepherd service graph.}
39751 You can actually generate such a graph for any operating system
39752 definition using the @command{guix system shepherd-graph} command
39753 (@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).
39755 The @code{%shepherd-root-service} is a service object representing
39756 PID@tie{}1, of type @code{shepherd-root-service-type}; it can be extended
39757 by passing it lists of @code{<shepherd-service>} objects.
39759 @deftp {Data Type} shepherd-service
39760 The data type representing a service managed by the Shepherd.
39763 @item @code{provision}
39764 This is a list of symbols denoting what the service provides.
39766 These are the names that may be passed to @command{herd start},
39767 @command{herd status}, and similar commands (@pxref{Invoking herd,,,
39768 shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the
39769 @code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.
39771 @item @code{requirement} (default: @code{'()})
39772 List of symbols denoting the Shepherd services this one depends on.
39774 @cindex one-shot services, for the Shepherd
39775 @item @code{one-shot?} (default: @code{#f})
39776 Whether this service is @dfn{one-shot}. One-shot services stop immediately
39777 after their @code{start} action has completed. @xref{Slots of services,,,
39778 shepherd, The GNU Shepherd Manual}, for more info.
39780 @item @code{respawn?} (default: @code{#t})
39781 Whether to restart the service when it stops, for instance when the
39782 underlying process dies.
39785 @itemx @code{stop} (default: @code{#~(const #f)})
39786 The @code{start} and @code{stop} fields refer to the Shepherd's
39787 facilities to start and stop processes (@pxref{Service De- and
39788 Constructors,,, shepherd, The GNU Shepherd Manual}). They are given as
39789 G-expressions that get expanded in the Shepherd configuration file
39790 (@pxref{G-Expressions}).
39792 @item @code{actions} (default: @code{'()})
39793 @cindex actions, of Shepherd services
39794 This is a list of @code{shepherd-action} objects (see below) defining
39795 @dfn{actions} supported by the service, in addition to the standard
39796 @code{start} and @code{stop} actions. Actions listed here become available as
39797 @command{herd} sub-commands:
39800 herd @var{action} @var{service} [@var{arguments}@dots{}]
39803 @item @code{auto-start?} (default: @code{#t})
39804 Whether this service should be started automatically by the Shepherd. If it
39805 is @code{#f} the service has to be started manually with @code{herd start}.
39807 @item @code{documentation}
39808 A documentation string, as shown when running:
39811 herd doc @var{service-name}
39814 where @var{service-name} is one of the symbols in @code{provision}
39815 (@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).
39817 @item @code{modules} (default: @code{%default-modules})
39818 This is the list of modules that must be in scope when @code{start} and
39819 @code{stop} are evaluated.
39824 The example below defines a Shepherd service that spawns
39825 @command{syslogd}, the system logger from the GNU Networking Utilities
39826 (@pxref{syslogd invocation, @command{syslogd},, inetutils, GNU
39830 (let ((config (plain-file "syslogd.conf" "@dots{}")))
39832 (documentation "Run the syslog daemon (syslogd).")
39833 (provision '(syslogd))
39834 (requirement '(user-processes))
39835 (start #~(make-forkexec-constructor
39836 (list #$(file-append inetutils "/libexec/syslogd")
39837 "--rcfile" #$config)
39838 #:pid-file "/var/run/syslog.pid"))
39839 (stop #~(make-kill-destructor))))
39842 Key elements in this example are the @code{start} and @code{stop}
39843 fields: they are @dfn{staged} code snippets that use the
39844 @code{make-forkexec-constructor} procedure provided by the Shepherd and
39845 its dual, @code{make-kill-destructor} (@pxref{Service De- and
39846 Constructors,,, shepherd, The GNU Shepherd Manual}). The @code{start}
39847 field will have @command{shepherd} spawn @command{syslogd} with the
39848 given option; note that we pass @code{config} after @option{--rcfile},
39849 which is a configuration file declared above (contents of this file are
39850 omitted). Likewise, the @code{stop} field tells how this service is to
39851 be stopped; in this case, it is stopped by making the @code{kill} system
39852 call on its PID@. Code staging is achieved using G-expressions:
39853 @code{#~} stages code, while @code{#$} ``escapes'' back to host code
39854 (@pxref{G-Expressions}).
39856 @deftp {Data Type} shepherd-action
39857 This is the data type that defines additional actions implemented by a
39858 Shepherd service (see above).
39862 Symbol naming the action.
39864 @item documentation
39865 This is a documentation string for the action. It can be viewed by running:
39868 herd doc @var{service} action @var{action}
39872 This should be a gexp that evaluates to a procedure of at least one argument,
39873 which is the ``running value'' of the service (@pxref{Slots of services,,,
39874 shepherd, The GNU Shepherd Manual}).
39877 The following example defines an action called @code{say-hello} that kindly
39883 (documentation "Say hi!")
39884 (procedure #~(lambda (running . args)
39885 (format #t "Hello, friend! arguments: ~s\n"
39890 Assuming this action is added to the @code{example} service, then you can do:
39893 # herd say-hello example
39894 Hello, friend! arguments: ()
39895 # herd say-hello example a b c
39896 Hello, friend! arguments: ("a" "b" "c")
39899 This, as you can see, is a fairly sophisticated way to say hello.
39900 @xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more
39904 @defvr {Scheme Variable} shepherd-root-service-type
39905 The service type for the Shepherd ``root service''---i.e., PID@tie{}1.
39907 This is the service type that extensions target when they want to create
39908 shepherd services (@pxref{Service Types and Services}, for an example).
39909 Each extension must pass a list of @code{<shepherd-service>}. Its
39910 value must be a @code{shepherd-configuration}, as described below.
39913 @deftp {Data Type} shepherd-configuration
39914 This data type represents the Shepherd's configuration.
39917 @item shepherd (default: @code{shepherd})
39918 The Shepherd package to use.
39920 @item services (default: @code{'()})
39921 A list of @code{<shepherd-service>} to start.
39922 You should probably use the service extension
39923 mechanism instead (@pxref{Shepherd Services}).
39927 The following example specifies the Shepherd package for the operating
39933 (services (append (list openssh-service-type))
39937 ;; Use own Shepherd package.
39938 (essential-services
39939 (modify-services (operating-system-default-essential-services
39940 this-operating-system)
39941 (shepherd-root-service-type config => (shepherd-configuration
39943 (shepherd my-shepherd))))))
39946 @defvr {Scheme Variable} %shepherd-root-service
39947 This service represents PID@tie{}1.
39950 @node Complex Configurations
39951 @subsection Complex Configurations
39952 @cindex complex configurations
39953 Some programs might have rather complex configuration files or formats,
39954 and to make it easier to create Scheme bindings for these configuration
39955 files, you can use the utilities defined in the @code{(gnu services
39956 configuration)} module.
39958 The main utility is the @code{define-configuration} macro, which you
39959 will use to define a Scheme record type (@pxref{Record Overview,,,
39960 guile, GNU Guile Reference Manual}). The Scheme record will be
39961 serialized to a configuration file by using @dfn{serializers}, which are
39962 procedures that take some kind of Scheme value and returns a
39963 G-expression (@pxref{G-Expressions}), which should, once serialized to
39964 the disk, return a string. More details are listed below.
39966 @deffn {Scheme Syntax} define-configuration @var{name} @var{clause1} @
39968 Create a record type named @code{@var{name}} that contains the
39969 fields found in the clauses.
39971 A clause can have one of the following forms:
39975 (@var{type} @var{default-value})
39976 @var{documentation})
39979 (@var{type} @var{default-value})
39980 @var{documentation}
39985 @var{documentation})
39989 @var{documentation}
39993 @var{field-name} is an identifier that denotes the name of the field in
39994 the generated record.
39996 @var{type} is the type of the value corresponding to @var{field-name};
39997 since Guile is untyped, a predicate
39998 procedure---@code{@var{type}?}---will be called on the value
39999 corresponding to the field to ensure that the value is of the correct
40000 type. This means that if say, @var{type} is @code{package}, then a
40001 procedure named @code{package?} will be applied on the value to make
40002 sure that it is indeed a @code{<package>} object.
40004 @var{default-value} is the default value corresponding to the field; if
40005 none is specified, the user is forced to provide a value when creating
40006 an object of the record type.
40008 @c XXX: Should these be full sentences or are they allow to be very
40009 @c short like package synopses?
40010 @var{documentation} is a string formatted with Texinfo syntax which
40011 should provide a description of what setting this field does.
40013 @var{serializer} is the name of a procedure which takes two arguments,
40014 the first is the name of the field, and the second is the value
40015 corresponding to the field. The procedure should return a string or
40016 G-expression (@pxref{G-Expressions}) that represents the content that
40017 will be serialized to the configuration file. If none is specified, a
40018 procedure of the name @code{serialize-@var{type}} will be used.
40020 A simple serializer procedure could look like this:
40023 (define (serialize-boolean field-name value)
40024 (let ((value (if value "true" "false")))
40025 #~(string-append #$field-name #$value)))
40028 In some cases multiple different configuration records might be defined
40029 in the same file, but their serializers for the same type might have to
40030 be different, because they have different configuration formats. For
40031 example, the @code{serialize-boolean} procedure for the Getmail service
40032 would have to be different from the one for the Transmission service. To
40033 make it easier to deal with this situation, one can specify a serializer
40034 prefix by using the @code{prefix} literal in the
40035 @code{define-configuration} form. This means that one doesn't have to
40036 manually specify a custom @var{serializer} for every field.
40039 (define (foo-serialize-string field-name value)
40042 (define (bar-serialize-string field-name value)
40045 (define-configuration foo-configuration
40048 "The name of label.")
40051 (define-configuration bar-configuration
40054 "The IPv4 address for this device.")
40058 However, in some cases you might not want to serialize any of the values
40059 of the record, to do this, you can use the @code{no-serialization}
40060 literal. There is also the @code{define-configuration/no-serialization}
40061 macro which is a shorthand of this.
40064 ;; Nothing will be serialized to disk.
40065 (define-configuration foo-configuration
40068 "Some documentation.")
40069 (no-serialization))
40071 ;; The same thing as above.
40072 (define-configuration/no-serialization bar-configuration
40075 "Some documentation."))
40079 @deffn {Scheme Syntax} define-maybe @var{type}
40080 Sometimes a field should not be serialized if the user doesn’t specify a
40081 value. To achieve this, you can use the @code{define-maybe} macro to
40082 define a ``maybe type''; if the value of a maybe type is left unset, or
40083 is set to the @code{%unset-value} value, then it will not be serialized.
40085 When defining a ``maybe type'', the corresponding serializer for the
40086 regular type will be used by default. For example, a field of type
40087 @code{maybe-string} will be serialized using the @code{serialize-string}
40088 procedure by default, you can of course change this by specifying a
40089 custom serializer procedure. Likewise, the type of the value would have
40090 to be a string, or left unspecified.
40093 (define-maybe string)
40095 (define (serialize-string field-name value)
40098 (define-configuration baz-configuration
40100 ;; If set to a string, the `serialize-string' procedure will be used
40101 ;; to serialize the string. Otherwise this field is not serialized.
40103 "The name of this module."))
40106 Like with @code{define-configuration}, one can set a prefix for the
40107 serializer name by using the @code{prefix} literal.
40110 (define-maybe integer
40113 (define (baz-serialize-integer field-name value)
40117 There is also the @code{no-serialization} literal, which when set means
40118 that no serializer will be defined for the ``maybe type'', regardless of
40119 whether its value is set or not.
40120 @code{define-maybe/no-serialization} is a shorthand for specifying the
40121 @code{no-serialization} literal.
40124 (define-maybe/no-serialization symbol)
40126 (define-configuration/no-serialization test-configuration
40133 @deffn (Scheme Procedure) maybe-value-set? @var{value}
40134 Predicate to check whether a user explicitly specified the value of a
40138 @deffn {Scheme Procedure} serialize-configuration @var{configuration} @
40140 Return a G-expression that contains the values corresponding to the
40141 @var{fields} of @var{configuration}, a record that has been generated by
40142 @code{define-configuration}. The G-expression can then be serialized to
40143 disk by using something like @code{mixed-text-file}.
40146 @deffn {Scheme Procedure} empty-serializer @var{field-name} @var{value}
40147 A serializer that just returns an empty string. The
40148 @code{serialize-package} procedure is an alias for this.
40151 Once you have defined a configuration record, you will most likely also
40152 want to document it so that other people know to use it. To help with
40153 that, there are two procedures, both of which are documented below.
40155 @deffn {Scheme Procedure} generate-documentation @var{documentation} @
40156 @var{documentation-name}
40157 Generate a Texinfo fragment from the docstrings in @var{documentation},
40158 a list of @code{(@var{label} @var{fields} @var{sub-documentation} ...)}.
40159 @var{label} should be a symbol and should be the name of the
40160 configuration record. @var{fields} should be a list of all the fields
40161 available for the configuration record.
40163 @var{sub-documentation} is a @code{(@var{field-name}
40164 @var{configuration-name})} tuple. @var{field-name} is the name of the
40165 field which takes another configuration record as its value, and
40166 @var{configuration-name} is the name of that configuration record.
40168 @var{sub-documentation} is only needed if there are nested configuration
40169 records. For example, the @code{getmail-configuration} record
40170 (@pxref{Mail Services}) accepts a @code{getmail-configuration-file}
40171 record in one of its @code{rcfile} field, therefore documentation for
40172 @code{getmail-configuration-file} is nested in
40173 @code{getmail-configuration}.
40176 (generate-documentation
40177 `((getmail-configuration ,getmail-configuration-fields
40178 (rcfile getmail-configuration-file))
40180 'getmail-configuration)
40183 @var{documentation-name} should be a symbol and should be the name of
40184 the configuration record.
40188 @deffn {Scheme Procedure} configuration->documentation
40189 @var{configuration-symbol}
40190 Take @var{configuration-symbol}, the symbol corresponding to the name
40191 used when defining a configuration record with
40192 @code{define-configuration}, and print the Texinfo documentation of its
40193 fields. This is useful if there aren’t any nested configuration records
40194 since it only prints the documentation for the top-level fields.
40197 As of right now, there is no automated way to generate documentation for
40198 configuration records and put them in the manual. Instead, every
40199 time you make a change to the docstrings of a configuration record, you
40200 have to manually call @code{generate-documentation} or
40201 @code{configuration->documentation}, and paste the output into the
40202 @file{doc/guix.texi} file.
40204 @c TODO: Actually test this
40205 Below is an example of a record type created using
40206 @code{define-configuration} and friends.
40209 (use-modules (gnu services)
40211 (gnu services configuration)
40215 ;; Turn field names, which are Scheme symbols into strings
40216 (define (uglify-field-name field-name)
40217 (let ((str (symbol->string field-name)))
40218 ;; field? -> is-field
40219 (if (string-suffix? "?" str)
40220 (string-append "is-" (string-drop-right str 1))
40223 (define (serialize-string field-name value)
40224 #~(string-append #$(uglify-field-name field-name) " = " #$value "\n"))
40226 (define (serialize-integer field-name value)
40227 (serialize-string field-name (number->string value)))
40229 (define (serialize-boolean field-name value)
40230 (serialize-string field-name (if value "true" "false")))
40232 (define (serialize-contact-name field-name value)
40233 #~(string-append "\n[" #$value "]\n"))
40235 (define (list-of-contact-configurations? lst)
40236 (every contact-configuration? lst))
40238 (define (serialize-list-of-contact-configurations field-name value)
40239 #~(string-append #$@@(map (cut serialize-configuration <>
40240 contact-configuration-fields)
40243 (define (serialize-contacts-list-configuration configuration)
40246 #~(string-append "[Owner]\n"
40247 #$(serialize-configuration
40248 configuration contacts-list-configuration-fields))))
40250 (define-maybe integer)
40251 (define-maybe string)
40253 (define-configuration contact-configuration
40256 "The name of the contact."
40257 serialize-contact-name)
40260 "The person's phone number.")
40263 "The person's email address.")
40266 "Whether the person is married."))
40268 (define-configuration contacts-list-configuration
40271 "The name of the owner of this contact list.")
40274 "The owner's email address.")
40276 (list-of-contact-configurations '())
40277 "A list of @@code@{contact-configuation@} records which contain
40278 information about all your contacts."))
40281 A contacts list configuration could then be created like this:
40284 (define my-contacts
40285 (contacts-list-configuration
40287 (email "alice@@example.org")
40289 (list (contact-configuration
40291 (phone-number 1234)
40292 (email "bob@@gnu.org")
40294 (contact-configuration
40296 (phone-number 0000)
40300 After serializing the configuration to disk, the resulting file would
40306 email = alice@@example.org
40309 phone-number = 1234
40310 email = bob@@gnu.org
40319 @node Home Configuration
40320 @chapter Home Configuration
40321 @cindex home configuration
40322 Guix supports declarative configuration of @dfn{home environments} by
40323 utilizing the configuration mechanism described in the previous chapter
40324 (@pxref{Defining Services}), but for user's dotfiles and packages. It
40325 works both on Guix System and foreign distros and allows users to
40326 declare all the packages and services that should be installed and
40327 configured for the user. Once a user has written a file containing
40328 @code{home-environment} record, such a configuration can be
40329 @dfn{instantiated} by an unprivileged user with the @command{guix home}
40330 command (@pxref{Invoking guix home}).
40331 @c Maybe later, it will be possible to make home configuration a part of
40332 @c system configuration to make everything managed by guix system.
40335 The functionality described in this section is still under development
40336 and is subject to change. Get in touch with us on
40337 @email{guix-devel@@gnu.org}!
40340 The user's home environment usually consists of three basic parts:
40341 software, configuration, and state. Software in mainstream distros are
40342 usually installed system-wide, but with GNU Guix most software packages
40343 can be installed on a per-user basis without needing root privileges,
40344 and are thus considered part of the user’s @dfn{home environment}.
40345 Packages on their own are not very useful in many cases, because often they
40346 require some additional configuration, usually config files that reside
40347 in @env{XDG_CONFIG_HOME} (@file{~/.config} by default) or other
40348 directories. Everything else can be considered state, like media files,
40349 application databases, and logs.
40351 Using Guix for managing home environments provides a number of
40356 @item All software can be configured in one language (Guile Scheme),
40357 this gives users the ability to share values between configurations of
40358 different programs.
40360 @item A well-defined home environment is self-contained and can be
40361 created in a declarative and reproducible way---there is no need to grab
40362 external binaries or manually edit some configuration file.
40364 @item After every @command{guix home reconfigure} invocation, a new home
40365 environment generation will be created. This means that users can
40366 rollback to a previous home environment generation so they don’t have to
40367 worry about breaking their configuration.
40369 @item It is possible to manage stateful data with Guix Home, this
40370 includes the ability to automatically clone Git repositories on the
40371 initial setup of the machine, and periodically running commands like
40372 @command{rsync} to sync data with another host. This functionality is
40373 still in an experimental stage, though.
40378 * Declaring the Home Environment:: Customizing your Home.
40379 * Configuring the Shell:: Enabling home environment.
40380 * Home Services:: Specifying home services.
40381 * Invoking guix home:: Instantiating a home configuration.
40384 @node Declaring the Home Environment
40385 @section Declaring the Home Environment
40386 The home environment is configured by providing a
40387 @code{home-environment} declaration in a file that can be passed to the
40388 @command{guix home} command (@pxref{Invoking guix home}). The easiest
40389 way to get started is by generating an initial configuration with
40390 @command{guix home import}:
40393 guix home import ~/src/guix-config
40396 The @command{guix home import} command reads some of the ``dot files''
40397 such as @file{~/.bashrc} found in your home directory and copies them to
40398 the given directory, @file{~/src/guix-config} in this case; it also
40399 reads the contents of your profile, @file{~/.guix-profile}, and, based
40400 on that, it populates @file{~/src/guix-config/home-configuration.scm}
40401 with a Home configuration that resembles your current configuration.
40403 A simple setup can include Bash and a custom text configuration, like in
40404 the example below. Don't be afraid to declare home environment parts,
40405 which overlaps with your current dot files: before installing any
40406 configuration files, Guix Home will back up existing config files to a
40407 separate place in the home directory.
40410 It is highly recommended that you manage your shell or shells with Guix
40411 Home, because it will make sure that all the necessary scripts are
40412 sourced by the shell configuration file. Otherwise you will need to do
40413 it manually. (@pxref{Configuring the Shell}).
40416 @findex home-environment
40418 @include he-config-bare-bones.scm
40421 The @code{packages} field should be self-explanatory, it will install
40422 the list of packages into the user's profile. The most important field
40423 is @code{services}, it contains a list of @dfn{home services}, which are
40424 the basic building blocks of a home environment.
40426 There is no daemon (at least not necessarily) related to a home service,
40427 a home service is just an element that is used to declare part of home
40428 environment and extend other parts of it. The extension mechanism
40429 discussed in the previous chapter (@pxref{Defining Services}) should not
40430 be confused with Shepherd services (@pxref{Shepherd Services}). Using this extension
40431 mechanism and some Scheme code that glues things together gives the user
40432 the freedom to declare their own, very custom, home environments.
40434 @cindex container, for @command{guix home}
40435 Once the configuration looks good, you can first test it in a throw-away
40439 guix home container config.scm
40442 The command above spawns a shell where your home environment is running.
40443 The shell runs in a container, meaning it's isolated from the rest of
40444 the system, so it's a good way to try out your configuration---you can
40445 see if configuration bits are missing or misbehaving, if daemons get
40446 started, and so on. Once you exit that shell, you're back to the prompt
40447 of your original shell ``in the real world''.
40449 Once you have a configuration file that suits your needs, you can
40450 reconfigure your home by running:
40453 guix home reconfigure config.scm
40456 This ``builds'' your home environment and creates @file{~/.guix-home}
40457 pointing to it. Voilà!
40460 Make sure the operating system has elogind, systemd, or a similar
40461 mechanism to create the XDG run-time directory and has the
40462 @env{XDG_RUNTIME_DIR} variable set. Failing that, the
40463 @file{on-first-login} script will not execute anything, and processes
40464 like user Shepherd and its descendants will not start.
40467 @node Configuring the Shell
40468 @section Configuring the Shell
40469 This section is safe to skip if your shell or shells are managed by
40470 Guix Home. Otherwise, read it carefully.
40472 There are a few scripts that must be evaluated by a login shell to
40473 activate the home environment. The shell startup files only read by
40474 login shells often have @code{profile} suffix. For more information
40475 about login shells see @ref{Invoking Bash,,, bash, The GNU Bash
40476 Reference Manual} and see @ref{Bash Startup Files,,, bash, The GNU Bash
40479 The first script that needs to be sourced is @file{setup-environment},
40480 which sets all the necessary environment variables (including variables
40481 declared by the user) and the second one is @file{on-first-login}, which
40482 starts Shepherd for the current user and performs actions declared by
40483 other home services that extends
40484 @code{home-run-on-first-login-service-type}.
40486 Guix Home will always create @file{~/.profile}, which contains the
40490 HOME_ENVIRONMENT=$HOME/.guix-home
40491 . $HOME_ENVIRONMENT/setup-environment
40492 $HOME_ENVIRONMENT/on-first-login
40495 This makes POSIX compliant login shells activate the home environment.
40496 However, in most cases this file won't be read by most modern shells,
40497 because they are run in non POSIX mode by default and have their own
40498 @file{*profile} startup files. For example Bash will prefer
40499 @file{~/.bash_profile} in case it exists and only if it doesn't will it
40500 fallback to @file{~/.profile}. Zsh (if no additional options are
40501 specified) will ignore @file{~/.profile}, even if @file{~/.zprofile}
40504 To make your shell respect @file{~/.profile}, add @code{. ~/.profile} or
40505 @code{source ~/.profile} to the startup file for the login shell. In
40506 case of Bash, it is @file{~/.bash_profile}, and in case of Zsh, it is
40507 @file{~/.zprofile}.
40510 This step is only required if your shell is @emph{not} managed by Guix Home.
40511 Otherwise, everything will be done automatically.
40514 @node Home Services
40515 @section Home Services
40516 @cindex home services
40518 A @dfn{home service} is not necessarily something that has a daemon and
40519 is managed by Shepherd (@pxref{Jump Start,,, shepherd, The GNU Shepherd
40520 Manual}), in most cases it doesn't. It's a simple building block of the
40521 home environment, often declaring a set of packages to be installed in
40522 the home environment profile, a set of config files to be symlinked into
40523 @env{XDG_CONFIG_HOME} (@file{~/.config} by default), and environment
40524 variables to be set by a login shell.
40526 There is a service extension mechanism (@pxref{Service Composition})
40527 which allows home services to extend other home services and utilize
40528 capabilities they provide; for example: declare mcron jobs
40529 (@pxref{Top,,, mcron, GNU@tie{}Mcron}) by extending @ref{Mcron Home
40530 Service}; declare daemons by extending @ref{Shepherd Home Service}; add
40531 commands, which will be invoked on by the Bash by extending
40532 @ref{Shells Home Services, @code{home-bash-service-type}}.
40534 A good way to discover available home services is using the
40535 @command{guix home search} command (@pxref{Invoking guix home}). After
40536 the required home services are found, include its module with the
40537 @code{use-modules} form (@pxref{use-modules,, Using Guile Modules,
40538 guile, The GNU Guile Reference Manual}), or the @code{#:use-modules}
40539 directive (@pxref{define-module,, Creating Guile Modules, guile, The GNU
40540 Guile Reference Manual}) and declare a home service using the
40541 @code{service} function, or extend a service type by declaring a new
40542 service with the @code{simple-service} procedure from @code{(gnu
40546 * Essential Home Services:: Environment variables, packages, on-* scripts.
40547 * Shells: Shells Home Services. POSIX shells, Bash, Zsh.
40548 * Mcron: Mcron Home Service. Scheduled User's Job Execution.
40549 * Power Management: Power Management Home Services. Services for battery power.
40550 * Shepherd: Shepherd Home Service. Managing User's Daemons.
40551 * SSH: Secure Shell. Setting up the secure shell client.
40552 * Desktop: Desktop Home Services. Services for graphical environments.
40553 * Guix: Guix Home Services. Services for Guix.
40555 @c In addition to that Home Services can provide
40557 @node Essential Home Services
40558 @subsection Essential Home Services
40559 There are a few essential home services defined in
40560 @code{(gnu services)}, they are mostly for internal use and are required
40561 to build a home environment, but some of them will be useful for the end
40564 @cindex environment variables
40566 @defvr {Scheme Variable} home-environment-variables-service-type
40567 The service of this type will be instantiated by every home environment
40568 automatically by default, there is no need to define it, but someone may
40569 want to extend it with a list of pairs to set some environment
40573 (list ("ENV_VAR1" . "value1")
40574 ("ENV_VAR2" . "value2"))
40577 The easiest way to extend a service type, without defining a new service
40578 type is to use the @code{simple-service} helper from @code{(gnu
40582 (simple-service 'some-useful-env-vars-service
40583 home-environment-variables-service-type
40584 `(("LESSHISTFILE" . "$XDG_CACHE_HOME/.lesshst")
40585 ("SHELL" . ,(file-append zsh "/bin/zsh"))
40586 ("USELESS_VAR" . #f)
40587 ("_JAVA_AWT_WM_NONREPARENTING" . #t)))
40590 If you include such a service in you home environment definition, it
40591 will add the following content to the @file{setup-environment} script
40592 (which is expected to be sourced by the login shell):
40595 export LESSHISTFILE=$XDG_CACHE_HOME/.lesshst
40596 export SHELL=/gnu/store/2hsg15n644f0glrcbkb1kqknmmqdar03-zsh-5.8/bin/zsh
40597 export _JAVA_AWT_WM_NONREPARENTING
40601 Make sure that module @code{(gnu packages shells)} is imported with
40602 @code{use-modules} or any other way, this namespace contains the
40603 definition of the @code{zsh} package, which is used in the example
40607 The association list (@pxref{Association Lists, alists, Association
40608 Lists, guile, The GNU Guile Reference manual}) is a data structure
40609 containing key-value pairs, for
40610 @code{home-environment-variables-service-type} the key is always a
40611 string, the value can be a string, string-valued gexp
40612 (@pxref{G-Expressions}), file-like object (@pxref{G-Expressions,
40613 file-like object}) or boolean. For gexps, the variable will be set to
40614 the value of the gexp; for file-like objects, it will be set to the path
40615 of the file in the store (@pxref{The Store}); for @code{#t}, it will
40616 export the variable without any value; and for @code{#f}, it will omit
40621 @defvr {Scheme Variable} home-profile-service-type
40622 The service of this type will be instantiated by every home environment
40623 automatically, there is no need to define it, but you may want to extend
40624 it with a list of packages if you want to install additional packages
40625 into your profile. Other services, which need to make some programs
40626 available to the user will also extend this service type.
40628 The extension value is just a list of packages:
40631 (list htop vim emacs)
40634 The same approach as @code{simple-service} (@pxref{Service Reference,
40635 simple-service}) for @code{home-environment-variables-service-type} can
40636 be used here, too. Make sure that modules containing the specified
40637 packages are imported with @code{use-modules}. To find a package or
40638 information about its module use @command{guix search} (@pxref{Invoking
40639 guix package}). Alternatively, @code{specification->package} can be
40640 used to get the package record from string without importing related
40644 There are few more essential services, but users are not expected to
40647 @defvr {Scheme Variable} home-service-type
40648 The root of home services DAG, it generates a folder, which later will be
40649 symlinked to @file{~/.guix-home}, it contains configurations,
40650 profile with binaries and libraries, and some necessary scripts to glue
40654 @defvr {Scheme Variable} home-run-on-first-login-service-type
40655 The service of this type generates a Guile script, which is expected to
40656 be executed by the login shell. It is only executed if the special flag
40657 file inside @env{XDG_RUNTIME_DIR} hasn't been created, this prevents
40658 redundant executions of the script if multiple login shells are spawned.
40660 It can be extended with a gexp. However, to autostart an application,
40661 users @emph{should not} use this service, in most cases it's better to extend
40662 @code{home-shepherd-service-type} with a Shepherd service
40663 (@pxref{Shepherd Services}), or extend the shell's startup file with
40664 the required command using the appropriate service type.
40667 @defvr {Scheme Variable} home-files-service-type
40668 The service of this type allows to specify a list of files, which will
40669 go to @file{~/.guix-home/files}, usually this directory contains
40670 configuration files (to be more precise it contains symlinks to files in
40671 @file{/gnu/store}), which should be placed in @file{$XDG_CONFIG_DIR} or
40672 in rare cases in @file{$HOME}. It accepts extension values in the
40676 `((".sway/config" ,sway-file-like-object)
40677 (".tmux.conf" ,(local-file "./tmux.conf")))
40680 Each nested list contains two values: a subdirectory and file-like
40681 object. After building a home environment @file{~/.guix-home/files}
40682 will be populated with apropiate content and all nested directories will
40683 be created accordingly, however, those files won't go any further until
40684 some other service will do it. By default a
40685 @code{home-symlink-manager-service-type}, which creates necessary
40686 symlinks in home folder to files from @file{~/.guix-home/files} and
40687 backs up already existing, but clashing configs and other things, is a
40688 part of essential home services (enabled by default), but it's possible
40689 to use alternative services to implement more advanced use cases like
40690 read-only home. Feel free to experiment and share your results.
40693 @defvr {Scheme Variable} home-xdg-configuration-files-service-type
40694 The service is very similiar to @code{home-files-service-type} (and
40695 actually extends it), but used for defining files, which will go to
40696 @file{~/.guix-home/files/.config}, which will be symlinked to
40697 @file{$XDG_CONFIG_DIR} by @code{home-symlink-manager-service-type} (for
40698 example) during activation. It accepts extension values in the
40702 `(("sway/config" ,sway-file-like-object)
40703 ;; -> ~/.guix-home/files/.config/sway/config
40704 ;; -> $XDG_CONFIG_DIR/sway/config (by symlink-manager)
40705 ("tmux/tmux.conf" ,(local-file "./tmux.conf")))
40709 @defvr {Scheme Variable} home-activation-service-type
40710 The service of this type generates a guile script, which runs on every
40711 @command{guix home reconfigure} invocation or any other action, which
40712 leads to the activation of the home environment.
40715 @defvr {Scheme Variable} home-symlink-manager-service-type
40716 The service of this type generates a guile script, which will be
40717 executed during activation of home environment, and do a few following
40722 Reads the content of @file{files/} directory of current and pending home
40726 Cleans up all symlinks created by symlink-manager on previous
40727 activation. Also, sub-directories, which become empty also will be
40731 Creates new symlinks the following way: It looks @file{files/} directory
40732 (usually defined with @code{home-files-service-type},
40733 @code{home-xdg-configuration-files-service-type} and maybe some others),
40734 takes the files from @file{files/.config/} subdirectory and put
40735 respective links in @env{XDG_CONFIG_DIR}. For example symlink for
40736 @file{files/.config/sway/config} will end up in
40737 @file{$XDG_CONFIG_DIR/sway/config}. The rest files in @file{files/}
40738 outside of @file{files/.config/} subdirectory will be treated slightly
40739 different: symlink will just go to @file{$HOME}.
40740 @file{files/.some-program/config} will end up in
40741 @file{$HOME/.some-program/config}.
40744 If some sub-directories are missing, they will be created.
40747 If there is a clashing files on the way, they will be backed up.
40751 symlink-manager is a part of essential home services and is enabled and
40756 @node Shells Home Services
40760 @cindex login shell
40761 @cindex interactive shell
40765 Shells play a quite important role in the environment initialization
40766 process, you can configure them manually as described in section
40767 @ref{Configuring the Shell}, but the recommended way is to use home services
40768 listed below. It's both easier and more reliable.
40770 Each home environment instantiates
40771 @code{home-shell-profile-service-type}, which creates a
40772 @file{~/.profile} startup file for all POSIX-compatible shells. This
40773 file contains all the necessary steps to properly initialize the
40774 environment, but many modern shells like Bash or Zsh prefer their own
40775 startup files, that's why the respective home services
40776 (@code{home-bash-service-type} and @code{home-zsh-service-type}) ensure
40777 that @file{~/.profile} is sourced by @file{~/.bash_profile} and
40778 @file{~/.zprofile}, respectively.
40780 @subsubheading Shell Profile Service
40782 @deftp {Data Type} home-shell-profile-configuration
40783 Available @code{home-shell-profile-configuration} fields are:
40786 @item @code{profile} (default: @code{()}) (type: text-config)
40787 @code{home-shell-profile} is instantiated automatically by
40788 @code{home-environment}, DO NOT create this service manually, it can
40789 only be extended. @code{profile} is a list of file-like objects, which
40790 will go to @file{~/.profile}. By default @file{~/.profile} contains the
40791 initialization code which must be evaluated by the login shell to make
40792 home-environment's profile available to the user, but other commands can
40793 be added to the file if it is really necessary. In most cases shell's
40794 configuration files are preferred places for user's customizations.
40795 Extend home-shell-profile service only if you really know what you do.
40801 @subsubheading Bash Home Service
40803 @anchor{home-bash-configuration}
40804 @deftp {Data Type} home-bash-configuration
40805 Available @code{home-bash-configuration} fields are:
40808 @item @code{package} (default: @code{bash}) (type: package)
40809 The Bash package to use.
40811 @item @code{guix-defaults?} (default: @code{#t}) (type: boolean)
40812 Add sane defaults like reading @file{/etc/bashrc} and coloring the output of
40813 @command{ls} to the top of the @file{.bashrc} file.
40815 @item @code{environment-variables} (default: @code{()}) (type: alist)
40816 Association list of environment variables to set for the Bash session. The
40817 rules for the @code{home-environment-variables-service-type} apply
40818 here (@pxref{Essential Home Services}). The contents of this field will be
40819 added after the contents of the @code{bash-profile} field.
40821 @item @code{aliases} (default: @code{()}) (type: alist)
40822 Association list of aliases to set for the Bash session. The aliases
40823 will be defined after the contents of the @code{bashrc} field has been
40824 put in the @file{.bashrc} file. The alias will automatically be quoted,
40825 so something like this:
40828 '(("ls" . "ls -alF"))
40837 @item @code{bash-profile} (default: @code{()}) (type: text-config)
40838 List of file-like objects, which will be added to @file{.bash_profile}.
40839 Used for executing user's commands at start of login shell (In most
40840 cases the shell started on tty just after login). @file{.bash_login}
40841 won't be ever read, because @file{.bash_profile} always present.
40843 @item @code{bashrc} (default: @code{()}) (type: text-config)
40844 List of file-like objects, which will be added to @file{.bashrc}. Used
40845 for executing user's commands at start of interactive shell (The shell
40846 for interactive usage started by typing @code{bash} or by terminal app
40847 or any other program).
40849 @item @code{bash-logout} (default: @code{()}) (type: text-config)
40850 List of file-like objects, which will be added to @file{.bash_logout}.
40851 Used for executing user's commands at the exit of login shell. It won't
40852 be read in some cases (if the shell terminates by exec'ing another
40853 process for example).
40858 You can extend the Bash service by using the @code{home-bash-extension}
40859 configuration record, whose fields must mirror that of
40860 @code{home-bash-configuration} (@pxref{home-bash-configuration}). The
40861 contents of the extensions will be added to the end of the corresponding
40862 Bash configuration files (@pxref{Bash Startup Files,,, bash, The GNU
40863 Bash Reference Manual}.
40865 For example, here is how you would define a service that extends the
40866 Bash service such that @file{~/.bash_profile} defines an additional
40867 environment variable, @env{PS1}:
40870 (define bash-fancy-prompt-service
40871 (simple-service 'bash-fancy-prompt
40872 home-bash-service-type
40873 (home-bash-extension
40874 (environment-variables
40875 '(("PS1" . "\\u \\wλ "))))))
40878 You would then add @code{bash-fancy-prompt-service} to the list in the
40879 @code{services} field of your @code{home-environment}. The reference of
40880 @code{home-bash-extension} follows.
40882 @deftp {Data Type} home-bash-extension
40883 Available @code{home-bash-extension} fields are:
40886 @item @code{environment-variables} (default: @code{()}) (type: alist)
40887 Additional environment variables to set. These will be combined with the
40888 environment variables from other extensions and the base service to form one
40889 coherent block of environment variables.
40891 @item @code{aliases} (default: @code{()}) (type: alist)
40892 Additional aliases to set. These will be combined with the aliases from
40893 other extensions and the base service.
40895 @item @code{bash-profile} (default: @code{()}) (type: text-config)
40896 Additional text blocks to add to @file{.bash_profile}, which will be combined
40897 with text blocks from other extensions and the base service.
40899 @item @code{bashrc} (default: @code{()}) (type: text-config)
40900 Additional text blocks to add to @file{.bashrc}, which will be combined
40901 with text blocks from other extensions and the base service.
40903 @item @code{bash-logout} (default: @code{()}) (type: text-config)
40904 Additional text blocks to add to @file{.bash_logout}, which will be combined
40905 with text blocks from other extensions and the base service.
40910 @subsubheading Zsh Home Service
40912 @deftp {Data Type} home-zsh-configuration
40913 Available @code{home-zsh-configuration} fields are:
40916 @item @code{package} (default: @code{zsh}) (type: package)
40917 The Zsh package to use.
40919 @item @code{xdg-flavor?} (default: @code{#t}) (type: boolean)
40920 Place all the configs to @file{$XDG_CONFIG_HOME/zsh}. Makes
40921 @file{~/.zshenv} to set @env{ZDOTDIR} to @file{$XDG_CONFIG_HOME/zsh}.
40922 Shell startup process will continue with
40923 @file{$XDG_CONFIG_HOME/zsh/.zshenv}.
40925 @item @code{environment-variables} (default: @code{()}) (type: alist)
40926 Association list of environment variables to set for the Zsh session.
40928 @item @code{zshenv} (default: @code{()}) (type: text-config)
40929 List of file-like objects, which will be added to @file{.zshenv}. Used
40930 for setting user's shell environment variables. Must not contain
40931 commands assuming the presence of tty or producing output. Will be read
40932 always. Will be read before any other file in @env{ZDOTDIR}.
40934 @item @code{zprofile} (default: @code{()}) (type: text-config)
40935 List of file-like objects, which will be added to @file{.zprofile}. Used
40936 for executing user's commands at start of login shell (In most cases the
40937 shell started on tty just after login). Will be read before
40940 @item @code{zshrc} (default: @code{()}) (type: text-config)
40941 List of file-like objects, which will be added to @file{.zshrc}. Used
40942 for executing user's commands at start of interactive shell (The shell
40943 for interactive usage started by typing @code{zsh} or by terminal app or
40944 any other program).
40946 @item @code{zlogin} (default: @code{()}) (type: text-config)
40947 List of file-like objects, which will be added to @file{.zlogin}. Used
40948 for executing user's commands at the end of starting process of login
40951 @item @code{zlogout} (default: @code{()}) (type: text-config)
40952 List of file-like objects, which will be added to @file{.zlogout}. Used
40953 for executing user's commands at the exit of login shell. It won't be
40954 read in some cases (if the shell terminates by exec'ing another process
40961 @node Mcron Home Service
40962 @subsection Scheduled User's Job Execution
40966 @cindex scheduling jobs
40968 The @code{(gnu home services mcron)} module provides an interface to
40969 GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
40970 mcron, GNU@tie{}mcron}). The information about system's mcron is
40971 applicable here (@pxref{Scheduled Job Execution}), the only difference
40972 for home services is that they have to be declared in a
40973 @code{home-environment} record instead of an @code{operating-system}
40976 @defvr {Scheme Variable} home-mcron-service-type
40977 This is the type of the @code{mcron} home service, whose value is an
40978 @code{home-mcron-configuration} object. It allows to manage scheduled
40981 This service type can be the target of a service extension that provides
40982 additional job specifications (@pxref{Service Composition}). In other
40983 words, it is possible to define services that provide additional mcron
40987 @deftp {Data Type} home-mcron-configuration
40988 Data type representing the configuration of mcron.
40991 @item @code{mcron} (default: @var{mcron})
40992 The mcron package to use.
40995 This is a list of gexps (@pxref{G-Expressions}), where each gexp
40996 corresponds to an mcron job specification (@pxref{Syntax, mcron job
40997 specifications,, mcron, GNU@tie{}mcron}).
41001 @node Power Management Home Services
41002 @subsection Power Management Home Services
41004 @cindex power management
41005 The @code{(gnu home services pm)} module provides home services
41006 pertaining to battery power.
41008 @defvr {Scheme Variable} home-batsignal-service-type
41009 Service for @code{batsignal}, a program that monitors battery levels
41010 and warns the user through desktop notifications when their battery
41011 is getting low. You can also configure a command to be run when the
41012 battery level passes a point deemed ``dangerous''. This service is
41013 configured with the @code{home-batsignal-configuration} record.
41016 @deftp {Data Type} home-batsignal-configuration
41017 Data type representing the configuration for batsignal.
41020 @item @code{warning-level} (default: @code{15})
41021 The battery level to send a warning message at.
41023 @item @code{warning-message} (default: @code{#f})
41024 The message to send as a notification when the battery level reaches
41025 the @code{warning-level}. Setting to @code{#f} uses the default
41028 @item @code{critical-level} (default: @code{5})
41029 The battery level to send a critical message at.
41031 @item @code{critical-message} (default: @code{#f})
41032 The message to send as a notification when the battery level reaches
41033 the @code{critical-level}. Setting to @code{#f} uses the default
41036 @item @code{danger-level} (default: @code{2})
41037 The battery level to run the @code{danger-command} at.
41039 @item @code{danger-command} (default: @code{#f})
41040 The command to run when the battery level reaches the @code{danger-level}.
41041 Setting to @code{#f} disables running the command entirely.
41043 @item @code{full-level} (default: @code{#f})
41044 The battery level to send a full message at. Setting to @code{#f}
41045 disables sending the full message entirely.
41047 @item @code{full-message} (default: @code{#f})
41048 The message to send as a notification when the battery level reaches
41049 the @code{full-level}. Setting to @code{#f} uses the default message.
41051 @item @code{batteries} (default: @code{'()})
41052 The batteries to monitor. Setting to @code{'()} tries to find batteries
41055 @item @code{poll-delay} (default: @code{60})
41056 The time in seconds to wait before checking the batteries again.
41058 @item @code{icon} (default: @code{#f})
41059 A file-like object to use as the icon for battery notifications. Setting
41060 to @code{#f} disables notification icons entirely.
41062 @item @code{notifications?} (default: @code{#t})
41063 Whether to send any notifications.
41065 @item @code{notifications-expire?} (default: @code{#f})
41066 Whether notifications sent expire after a time.
41068 @item @code{notification-command} (default: @code{#f})
41069 Command to use to send messages. Setting to @code{#f} sends a notification
41070 through @code{libnotify}.
41072 @item @code{ignore-missing?} (default: @code{#f})
41073 Whether to ignore missing battery errors.
41077 @node Shepherd Home Service
41078 @subsection Managing User Daemons
41080 @cindex shepherd services, for users
41081 The @code{(gnu home services shepherd)} module supports the definitions
41082 of per-user Shepherd services (@pxref{Introduction,,, shepherd, The GNU
41083 Shepherd Manual}). You extend @code{home-shepherd-service-type} with
41084 new services; Guix Home then takes care of starting the @code{shepherd}
41085 daemon for you when you log in, which in turns starts the services you
41088 @defvr {Scheme Variable} home-shepherd-service-type
41089 The service type for the userland Shepherd, which allows one to manage
41090 long-running processes or one-shot tasks. User's Shepherd is not an
41091 init process (PID 1), but almost all other information described in
41092 (@pxref{Shepherd Services}) is applicable here too.
41094 This is the service type that extensions target when they want to create
41095 shepherd services (@pxref{Service Types and Services}, for an example).
41096 Each extension must pass a list of @code{<shepherd-service>}. Its
41097 value must be a @code{home-shepherd-configuration}, as described below.
41100 @deftp {Data Type} home-shepherd-configuration
41101 This data type represents the Shepherd's configuration.
41104 @item shepherd (default: @code{shepherd})
41105 The Shepherd package to use.
41107 @item auto-start? (default: @code{#t})
41108 Whether or not to start Shepherd on first login.
41110 @item services (default: @code{'()})
41111 A list of @code{<shepherd-service>} to start.
41112 You should probably use the service extension
41113 mechanism instead (@pxref{Shepherd Services}).
41118 @subsection Secure Shell
41120 @cindex secure shell client, configuration
41121 @cindex SSH client, configuration
41122 The @uref{https://www.openssh.com, OpenSSH package} includes a client,
41123 the @command{ssh} command, that allows you to connect to remote machines
41124 using the @acronym{SSH, secure shell} protocol. With the @code{(gnu
41125 home services ssh)} module, you can set up OpenSSH so that it works in a
41126 predictable fashion, almost independently of state on the local machine.
41127 To do that, you instantiate @code{home-openssh-service-type} in your
41128 Home configuration, as explained below.
41130 @defvr {Scheme Variable} home-openssh-service-type
41131 This is the type of the service to set up the OpenSSH client. It takes
41132 care of several things:
41136 providing a @file{~/.ssh/config} file based on your configuration so
41137 that @command{ssh} knows about hosts you regularly connect to and their
41138 associated parameters;
41141 providing a @file{~/.ssh/authorized_keys}, which lists public keys that
41142 the local SSH server, @command{sshd}, may accept to connect to this user
41146 optionally providing a @file{~/.ssh/known_hosts} file so that @file{ssh}
41147 can authenticate hosts you connect to.
41150 Here is an example of a service and its configuration that you could add
41151 to the @code{services} field of your @code{home-environment}:
41154 (service home-openssh-service-type
41155 (home-openssh-configuration
41157 (list (openssh-host (name "ci.guix.gnu.org")
41159 (openssh-host (name "chbouib")
41160 (host-name "chbouib.example.org")
41161 (user "supercharlie")
41163 (authorized-keys (list (local-file "alice.pub")))))
41166 The example above lists two hosts and their parameters. For instance,
41167 running @command{ssh chbouib} will automatically connect to
41168 @code{chbouib.example.org} on port 10022, logging in as user
41169 @samp{supercharlie}. Further, it marks the public key in
41170 @file{alice.pub} as authorized for incoming connections.
41172 The value associated with a @code{home-openssh-service-type} instance
41173 must be a @code{home-openssh-configuration} record, as describe below.
41176 @deftp {Data Type} home-openssh-configuration
41177 This is the datatype representing the OpenSSH client and server
41178 configuration in one's home environment. It contains the following
41182 @item @code{hosts} (default: @code{'()})
41183 A list of @code{openssh-host} records specifying host names and
41184 associated connection parameters (see below). This host list goes into
41185 @file{~/.ssh/config}, which @command{ssh} reads at startup.
41187 @item @code{known-hosts} (default: @code{*unspecified*})
41188 This must be either:
41192 @code{*unspecified*}, in which case @code{home-openssh-service-type}
41193 leaves it up to @command{ssh} and to the user to maintain the list of
41194 known hosts at @file{~/.ssh/known_hosts}, or
41197 a list of file-like objects, in which case those are concatenated and
41198 emitted as @file{~/.ssh/known_hosts}.
41201 The @file{~/.ssh/known_hosts} contains a list of host name/host key
41202 pairs that allow @command{ssh} to authenticate hosts you connect to and
41203 to detect possible impersonation attacks. By default, @command{ssh}
41204 updates it in a @dfn{TOFU, trust-on-first-use} fashion, meaning that it
41205 records the host's key in that file the first time you connect to it.
41206 This behavior is preserved when @code{known-hosts} is set to
41207 @code{*unspecified*}.
41209 If you instead provide a list of host keys upfront in the
41210 @code{known-hosts} field, your configuration becomes self-contained and
41211 stateless: it can be replicated elsewhere or at another point in time.
41212 Preparing this list can be relatively tedious though, which is why
41213 @code{*unspecified*} is kept as a default.
41215 @item @code{authorized-keys} (default: @code{'()})
41216 This must be a list of file-like objects, each of which containing an
41217 SSH public key that should be authorized to connect to this machine.
41219 Concretely, these files are concatenated and made available as
41220 @file{~/.ssh/authorized_keys}. If an OpenSSH server, @command{sshd}, is
41221 running on this machine, then it @emph{may} take this file into account:
41222 this is what @command{sshd} does by default, but be aware that it can
41223 also be configured to ignore it.
41227 @c %start of fragment
41229 @deftp {Data Type} openssh-host
41230 Available @code{openssh-host} fields are:
41233 @item @code{name} (type: string)
41234 Name of this host declaration.
41236 @item @code{host-name} (type: maybe-string)
41237 Host name---e.g., @code{"foo.example.org"} or @code{"192.168.1.2"}.
41239 @item @code{address-family} (type: address-family)
41240 Address family to use when connecting to this host: one of
41241 @code{AF_INET} (for IPv4 only), @code{AF_INET6} (for IPv6 only), or
41242 @code{*unspecified*} (allowing any address family).
41244 @item @code{identity-file} (type: maybe-string)
41245 The identity file to use---e.g., @code{"/home/charlie/.ssh/id_ed25519"}.
41247 @item @code{port} (type: maybe-natural-number)
41248 TCP port number to connect to.
41250 @item @code{user} (type: maybe-string)
41251 User name on the remote host.
41253 @item @code{forward-x11?} (default: @code{#f}) (type: boolean)
41254 Whether to forward remote client connections to the local X11 graphical
41257 @item @code{forward-x11-trusted?} (default: @code{#f}) (type: boolean)
41258 Whether remote X11 clients have full access to the original X11
41261 @item @code{forward-agent?} (default: @code{#f}) (type: boolean)
41262 Whether the authentication agent (if any) is forwarded to the remote
41265 @item @code{compression?} (default: @code{#f}) (type: boolean)
41266 Whether to compress data in transit.
41268 @item @code{proxy-command} (type: maybe-string)
41269 The command to use to connect to the server. As an example, a command
41270 to connect via an HTTP proxy at 192.0.2.0 would be: @code{"nc -X connect
41271 -x 192.0.2.0:8080 %h %p"}.
41273 @item @code{host-key-algorithms} (type: maybe-string-list)
41274 The list of accepted host key algorithms---e.g.,
41275 @code{'("ssh-ed25519")}.
41277 @item @code{accepted-key-types} (type: maybe-string-list)
41278 The list of accepted user public key types.
41280 @item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
41281 Extra content appended as-is to this @code{Host} block in
41282 @file{~/.ssh/config}.
41289 @c %end of fragment
41292 @node Desktop Home Services
41293 @subsection Desktop Home Services
41295 The @code{(gnu home services desktop)} module provides services that you
41296 may find useful on ``desktop'' systems running a graphical user
41297 environment such as Xorg.
41299 @defvr {Scheme Variable} home-redshift-service-type
41300 This is the service type for @uref{https://github.com/jonls/redshift,
41301 Redshift}, a program that adjusts the display color temperature
41302 according to the time of day. Its associated value must be a
41303 @code{home-redshift-configuration} record, as shown below.
41305 A typical configuration, where we manually specify the latitude and
41306 longitude, might look like this:
41309 (service home-redshift-service-type
41310 (home-redshift-configuration
41311 (location-provider 'manual)
41312 (latitude 35.81) ;northern hemisphere
41313 (longitude -0.80))) ;west of Greenwich
41317 @deftp {Data Type} home-redshift-configuration
41318 Available @code{home-redshift-configuration} fields are:
41321 @item @code{redshift} (default: @code{redshift}) (type: file-like)
41322 Redshift package to use.
41324 @item @code{location-provider} (default: @code{geoclue2}) (type: symbol)
41325 Geolocation provider---@code{'manual} or @code{'geoclue2}. In the
41326 former case, you must also specify the @code{latitude} and
41327 @code{longitude} fields so Redshift can determine daytime at your place.
41328 In the latter case, the Geoclue system service must be running; it will
41329 be queried for location information.
41331 @item @code{adjustment-method} (default: @code{randr}) (type: symbol)
41332 Color adjustment method.
41334 @item @code{daytime-temperature} (default: @code{6500}) (type: integer)
41335 Daytime color temperature (kelvins).
41337 @item @code{nighttime-temperature} (default: @code{4500}) (type: integer)
41338 Nighttime color temperature (kelvins).
41340 @item @code{daytime-brightness} (type: maybe-inexact-number)
41341 Daytime screen brightness, between 0.1 and 1.0, or left unspecified.
41343 @item @code{nighttime-brightness} (type: maybe-inexact-number)
41344 Nighttime screen brightness, between 0.1 and 1.0, or left unspecified.
41346 @item @code{latitude} (type: maybe-inexact-number)
41347 Latitude, when @code{location-provider} is @code{'manual}.
41349 @item @code{longitude} (type: maybe-inexact-number)
41350 Longitude, when @code{location-provider} is @code{'manual}.
41352 @item @code{dawn-time} (type: maybe-string)
41353 Custom time for the transition from night to day in the
41354 morning---@code{"HH:MM"} format. When specified, solar elevation is not
41355 used to determine the daytime/nighttime period.
41357 @item @code{dusk-time} (type: maybe-string)
41358 Likewise, custom time for the transition from day to night in the
41361 @item @code{extra-content} (default: @code{""}) (type: raw-configuration-string)
41362 Extra content appended as-is to the Redshift configuration file. Run
41363 @command{man redshift} for more information about the configuration file
41370 @defvr {Scheme Variable} home-dbus-service-type
41371 This is the service type for running a session-specific D-Bus, for
41372 unprivileged applications that require D-Bus to be running.
41375 @deftp {Data Type} home-dbus-configuration
41376 The configuration record for @code{home-dbus-service-type}.
41379 @item @code{dbus} (default: @code{dbus})
41380 The package providing the @code{/bin/dbus-daemon} command.
41384 @node Guix Home Services
41385 @subsection Guix Home Services
41387 The @code{(gnu home services guix)} module provides services for
41388 user-specific Guix configuration.
41390 @defvr {Scheme Variable} home-channels-service-type
41391 This is the service type for managing
41392 @file{$XDG_CONFIG_HOME/guix/channels.scm}, the file that controls the
41393 channels received on @command{guix pull} (@pxref{Channels}). Its
41394 associated value is a list of @code{channel} records, defined in the
41395 @code{(guix channels)} module.
41397 Generally, it is better to extend this service than to directly
41398 configure it, as its default value is the default guix channel(s)
41399 defined by @code{%default-channels}. If you configure this service
41400 directly, be sure to include a guix channel. @xref{Specifying
41401 Additional Channels} and @ref{Using a Custom Guix Channel} for more
41404 A typical extension for adding a channel might look like this:
41407 (simple-service 'variant-packages-service
41408 home-channels-service-type
41411 (name 'variant-packages)
41412 (url "https://example.org/variant-packages.git")))
41416 @node Invoking guix home
41417 @section Invoking @command{guix home}
41419 @cindex @command{guix home}
41421 Once you have written a home environment declaration (@pxref{Declaring
41422 the Home Environment,,,,}, it can be @dfn{instantiated} using the
41423 @command{guix home} command. The synopsis is:
41426 guix home @var{options}@dots{} @var{action} @var{file}
41429 @var{file} must be the name of a file containing a
41430 @code{home-environment} declaration. @var{action} specifies how the
41431 home environment is instantiated, but there are few auxiliary actions
41432 which don't instantiate it. Currently the following values are
41437 Display available home service type definitions that match the given
41438 regular expressions, sorted by relevance:
41441 @cindex shell-profile
41445 $ guix home search shell
41446 name: home-shell-profile
41447 location: gnu/home/services/shells.scm:100:2
41448 extends: home-files
41449 description: Create `~/.profile', which is used for environment initialization of POSIX compliant login shells.
41450 + This service type can be extended with a list of file-like objects.
41454 location: gnu/home/services/shells.scm:640:2
41455 extends: home-files home-profile
41456 description: Install and configure Fish, the friendly interactive shell.
41460 location: gnu/home/services/shells.scm:290:2
41461 extends: home-files home-profile
41462 description: Install and configure Zsh.
41466 location: gnu/home/services/shells.scm:508:2
41467 extends: home-files home-profile
41468 description: Install and configure GNU Bash.
41474 As for @command{guix search}, the result is written in
41475 @code{recutils} format, which makes it easy to filter the output
41476 (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
41478 @cindex container, for @command{guix home}
41480 Spawn a shell in an isolated environment---a
41481 @dfn{container}---containing your home as specified by @var{file}.
41483 For example, this is how you would start an interactive shell in a
41484 container with your home:
41487 guix home container config.scm
41490 This is a throw-away container where you can lightheartedly fiddle with
41491 files; any changes made within the container, any process started---all
41492 this disappears as soon as you exit that shell.
41494 As with @command{guix shell}, several options control that container:
41499 Enable networking within the container (it is disabled by default).
41501 @item --expose=@var{source}[=@var{target}]
41502 @itemx --share=@var{source}[=@var{target}]
41503 As with @command{guix shell}, make directory @var{source} of the host
41504 system available as @var{target} inside the container---read-only if you
41505 pass @option{--expose}, and writable if you pass @option{--share}
41506 (@pxref{Invoking guix shell, @option{--expose} and @option{--share}}).
41509 Additionally, you can run a command in that container, instead of
41510 spawning an interactive shell. For instance, here is how you would
41511 check which Shepherd services are started in a throw-away home
41515 guix home container config.scm -- herd status
41518 The command to run in the container must come after @code{--} (double
41521 @cindex service type definition, editing
41522 @cindex editing, service type definition
41524 Edit or view the definition of the given Home service types.
41526 For example, the command below opens your editor, as specified by the
41527 @env{EDITOR} environment variable, on the definition of the
41528 @code{home-mcron} service type:
41531 guix home edit home-mcron
41535 Build the home environment described in @var{file}, and switch to it.
41536 Switching means that the activation script will be evaluated and (in
41537 basic scenario) symlinks to configuration files generated from
41538 @code{home-environment} declaration will be created in @file{~}. If the
41539 file with the same path already exists in home folder it will be moved
41540 to @file{~/@var{timestamp}-guix-home-legacy-configs-backup}, where @var{timestamp}
41541 is a current UNIX epoch time.
41544 It is highly recommended to run @command{guix pull} once before you run
41545 @command{guix home reconfigure} for the first time (@pxref{Invoking guix
41549 This effects all the configuration specified in @var{file}. The command
41550 starts Shepherd services specified in @var{file} that are not currently
41551 running; if a service is currently running, this command will arrange
41552 for it to be upgraded the next time it is stopped (e.g.@: by @code{herd
41553 stop @var{service}} or @code{herd restart @var{service}}).
41555 This command creates a new generation whose number is one greater than
41556 the current generation (as reported by @command{guix home
41557 list-generations}). If that generation already exists, it will be
41558 overwritten. This behavior mirrors that of @command{guix package}
41559 (@pxref{Invoking guix package}).
41561 @cindex provenance tracking, of the home environment
41562 Upon completion, the new home is deployed under @file{~/.guix-home}.
41563 This directory contains @dfn{provenance meta-data}: the list of channels
41564 in use (@pxref{Channels}) and @var{file} itself, when available. You
41565 can view the provenance information by running:
41571 This information is useful should you later want to inspect how this
41572 particular generation was built. In fact, assuming @var{file} is
41573 self-contained, you can later rebuild generation @var{n} of your
41574 home environment with:
41577 guix time-machine \
41578 -C /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/channels.scm -- \
41580 /var/guix/profiles/per-user/@var{USER}/guix-home-@var{n}-link/configuration.scm
41584 You can think of it as some sort of built-in version control! Your
41585 home is not just a binary artifact: @emph{it carries its own source}.
41586 @c @xref{Service Reference, @code{provenance-service-type}}, for more
41587 @c information on provenance tracking.
41589 @c @footnote{This action (and the related actions
41590 @c @code{switch-generation} and @code{roll-back}) are usable after the
41591 @c home environment is initialized.}.
41593 @item switch-generation
41594 @cindex home generations
41595 Switch to an existing home generation. This action atomically switches
41596 the home profile to the specified home generation.
41598 The target generation can be specified explicitly by its generation
41599 number. For example, the following invocation would switch to home
41603 guix home switch-generation 7
41606 The target generation can also be specified relative to the current
41607 generation with the form @code{+N} or @code{-N}, where @code{+3} means
41608 ``3 generations ahead of the current generation,'' and @code{-1} means
41609 ``1 generation prior to the current generation.'' When specifying a
41610 negative value such as @code{-1}, you must precede it with @code{--} to
41611 prevent it from being parsed as an option. For example:
41614 guix home switch-generation -- -1
41617 This action will fail if the specified generation does not exist.
41620 @cindex rolling back
41621 Switch to the preceding home generation. This is the inverse
41622 of @command{reconfigure}, and it is exactly the same as invoking
41623 @command{switch-generation} with an argument of @code{-1}.
41625 @item delete-generations
41626 @cindex deleting home generations
41627 @cindex saving space
41628 Delete home generations, making them candidates for garbage collection
41629 (@pxref{Invoking guix gc}, for information on how to run the ``garbage
41632 This works in the same way as @samp{guix package --delete-generations}
41633 (@pxref{Invoking guix package, @option{--delete-generations}}). With no
41634 arguments, all home generations but the current one are deleted:
41637 guix home delete-generations
41640 You can also select the generations you want to delete. The example below
41641 deletes all the home generations that are more than two months old:
41644 guix home delete-generations 2m
41648 Build the derivation of the home environment, which includes all the
41649 configuration files and programs needed. This action does not actually
41653 Describe the current home generation: its file name, as well as
41654 provenance information when available.
41656 To show installed packages in the current home generation's profile, the
41657 @code{--list-installed} flag is provided, with the same syntax that is
41658 used in @command{guix package --list-installed} (@pxref{Invoking guix
41659 package}). For instance, the following command shows a table of all the
41660 packages with ``emacs'' in their name that are installed in the current
41661 home generation's profile:
41664 guix home describe --list-installed=emacs
41667 @item list-generations
41668 List a summary of each generation of the home environment available on
41669 disk, in a human-readable way. This is similar to the
41670 @option{--list-generations} option of @command{guix package}
41671 (@pxref{Invoking guix package}).
41673 Optionally, one can specify a pattern, with the same syntax that is used
41674 in @command{guix package --list-generations}, to restrict the list of
41675 generations displayed. For instance, the following command displays
41676 generations that are up to 10 days old:
41679 guix home list-generations 10d
41682 The @code{--list-installed} flag may also be specified, with the same
41683 syntax that is used in @command{guix home describe}. This may be
41684 helpful if trying to determine when a package was added to the home
41688 Generate a @dfn{home environment} from the packages in the default
41689 profile and configuration files found in the user's home directory. The
41690 configuration files will be copied to the specified directory, and a
41691 @file{home-configuration.scm} will be populated with the home
41692 environment. Note that not every home service that exists is supported
41693 (@pxref{Home Services}).
41696 $ guix home import ~/guix-config
41697 guix home: '/home/alice/guix-config' populated with all the Home configuration files
41701 And there's more! @command{guix home} also provides the following
41702 sub-commands to visualize how the services of your home environment
41703 relate to one another:
41706 @cindex service extension graph, of a home environment
41707 @item extension-graph
41708 Emit to standard output the @dfn{service extension graph} of the home
41709 environment defined in @var{file} (@pxref{Service Composition}, for more
41710 information on service extensions). By default the output is in
41711 Dot/Graphviz format, but you can choose a different format with
41712 @option{--graph-backend}, as with @command{guix graph} (@pxref{Invoking
41713 guix graph, @option{--backend}}):
41718 guix home extension-graph @var{file} | xdot -
41721 shows the extension relations among services.
41723 @cindex Shepherd dependency graph, for a home environment
41724 @item shepherd-graph
41725 Emit to standard output the @dfn{dependency graph} of shepherd services
41726 of the home environment defined in @var{file}. @xref{Shepherd
41727 Services}, for more information and for an example graph.
41729 Again, the default output format is Dot/Graphviz, but you can pass
41730 @option{--graph-backend} to select a different one.
41733 @var{options} can contain any of the common build options (@pxref{Common
41734 Build Options}). In addition, @var{options} can contain one of the
41739 @item --expression=@var{expr}
41740 @itemx -e @var{expr}
41741 Consider the home-environment @var{expr} evaluates to.
41742 This is an alternative to specifying a file which evaluates to a home
41745 @item --allow-downgrades
41746 Instruct @command{guix home reconfigure} to allow system downgrades.
41748 Just like @command{guix system}, @command{guix home reconfigure}, by
41749 default, prevents you from downgrading your home to older or unrelated
41750 revisions compared to the channel revisions that were used to deploy
41751 it---those shown by @command{guix home describe}. Using
41752 @option{--allow-downgrades} allows you to bypass that check, at the risk
41753 of downgrading your home---be careful!
41757 @node Documentation
41758 @chapter Documentation
41760 @cindex documentation, searching for
41761 @cindex searching for documentation
41762 @cindex Info, documentation format
41764 @cindex manual pages
41765 In most cases packages installed with Guix come with documentation.
41766 There are two main documentation formats: ``Info'', a browsable
41767 hypertext format used for GNU software, and ``manual pages'' (or ``man
41768 pages''), the linear documentation format traditionally found on Unix.
41769 Info manuals are accessed with the @command{info} command or with Emacs,
41770 and man pages are accessed using @command{man}.
41772 You can look for documentation of software installed on your system by
41773 keyword. For example, the following command searches for information
41774 about ``TLS'' in Info manuals:
41778 "(emacs)Network Security" -- STARTTLS
41779 "(emacs)Network Security" -- TLS
41780 "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
41781 "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
41786 The command below searches for the same keyword in man
41787 pages@footnote{The database searched by @command{man -k} is only created
41788 in profiles that contain the @code{man-db} package.}:
41792 SSL (7) - OpenSSL SSL/TLS library
41793 certtool (1) - GnuTLS certificate tool
41797 These searches are purely local to your computer so you have the
41798 guarantee that documentation you find corresponds to what you have
41799 actually installed, you can access it off-line, and your privacy is
41802 Once you have these results, you can view the relevant documentation by
41806 $ info "(gnutls)Core TLS API"
41816 Info manuals contain sections and indices as well as hyperlinks like
41817 those found in Web pages. The @command{info} reader (@pxref{Top, Info
41818 reader,, info-stnd, Stand-alone GNU Info}) and its Emacs counterpart
41819 (@pxref{Misc Help,,, emacs, The GNU Emacs Manual}) provide intuitive key
41820 bindings to navigate manuals. @xref{Getting Started,,, info, Info: An
41821 Introduction}, for an introduction to Info navigation.
41826 The packages and systems built by Guix are intended, like most computer
41827 programs, to run on a CPU with a specific instruction set, and under a
41828 specific operating system. Those programs are often also targeting a
41829 specific kernel and system library. Those constraints are captured by
41830 Guix in @code{platform} records.
41833 * platform Reference:: Detail of platform declarations.
41834 * Supported Platforms:: Description of the supported platforms.
41837 @node platform Reference
41838 @section @code{platform} Reference
41840 The @code{platform} data type describes a @dfn{platform}: an
41841 @acronym{ISA, instruction set architecture}, combined with an operating
41842 system and possibly additional system-wide settings such as the
41843 @acronym{ABI, application binary interface}.
41845 @deftp {Data Type} platform
41846 This is the data type representing a platform.
41849 @item @code{target}
41850 This field specifies the platform's GNU triplet as a string
41851 (@pxref{Specifying Target Triplets, GNU configuration triplets,,
41852 autoconf, Autoconf}).
41854 @item @code{system}
41855 This string is the system type as it is known to Guix and passed,
41856 for instance, to the @option{--system} option of most commands.
41858 It usually has the form @code{"@var{cpu}-@var{kernel}"}, where
41859 @var{cpu} is the target CPU and @var{kernel} the target operating
41862 It can be for instance @code{"aarch64-linux"} or @code{"armhf-linux"}.
41863 You will encounter system types when you perform native builds
41864 (@pxref{Native Builds}).
41866 @item @code{linux-architecture} (default: @code{#false})
41867 This optional string field is only relevant if the kernel is Linux. In
41868 that case, it corresponds to the ARCH variable used when building Linux,
41869 @code{"mips"} for instance.
41871 @item @code{glibc-dynamic-linker}
41872 This field is the name of the GNU C Library dynamic linker for the
41873 corresponding system, as a string. It can be
41874 @code{"/lib/ld-linux-armhf.so.3"}.
41879 @node Supported Platforms
41880 @section Supported Platforms
41882 The @code{(guix platforms @dots{})} modules export the following
41883 variables, each of which is bound to a @code{platform} record.
41885 @defvr {Scheme Variable} armv7-linux
41886 Platform targeting ARM v7 CPU running GNU/Linux.
41889 @defvr {Scheme Variable} aarch64-linux
41890 Platform targeting ARM v8 CPU running GNU/Linux.
41893 @defvr {Scheme Variable} mips64-linux
41894 Platform targeting MIPS little-endian 64-bit CPU running GNU/Linux.
41897 @defvr {Scheme Variable} powerpc-linux
41898 Platform targeting PowerPC big-endian 32-bit CPU running GNU/Linux.
41901 @defvr {Scheme Variable} powerpc64le-linux
41902 Platform targeting PowerPC little-endian 64-bit CPU running GNU/Linux.
41905 @defvr {Scheme Variable} riscv64-linux
41906 Platform targeting RISC-V 64-bit CPU running GNU/Linux.
41909 @defvr {Scheme Variable} i686-linux
41910 Platform targeting x86 CPU running GNU/Linux.
41913 @defvr {Scheme Variable} x86_64-linux
41914 Platform targeting x86 64-bit CPU running GNU/Linux.
41917 @defvr {Scheme Variable} i686-mingw
41918 Platform targeting x86 CPU running Windows, with run-time support from
41922 @defvr {Scheme Variable} x86_64-mingw
41923 Platform targeting x86 64-bit CPU running Windows, with run-time support
41927 @defvr {Scheme Variable} i586-gnu
41928 Platform targeting x86 CPU running GNU/Hurd (also referred to as
41932 @node System Images
41933 @chapter Creating System Images
41935 @cindex system images
41936 When it comes to installing Guix System for the first time on a new
41937 machine, you can basically proceed in three different ways. The first
41938 one is to use an existing operating system on the machine to run the
41939 @command{guix system init} command (@pxref{Invoking guix system}). The
41940 second one, is to produce an installation image (@pxref{Building the
41941 Installation Image}). This is a bootable system which role is to
41942 eventually run @command{guix system init}. Finally, the third option
41943 would be to produce an image that is a direct instantiation of the
41944 system you wish to run. That image can then be copied on a bootable
41945 device such as an USB drive or a memory card. The target machine would
41946 then directly boot from it, without any kind of installation procedure.
41948 The @command{guix system image} command is able to turn an operating
41949 system definition into a bootable image. This command supports
41950 different image types, such as @code{efi-raw}, @code{iso9660} and
41951 @code{docker}. Any modern @code{x86_64} machine will probably be able
41952 to boot from an @code{iso9660} image. However, there are a few machines
41953 out there that require specific image types. Those machines, in general
41954 using @code{ARM} processors, may expect specific partitions at specific
41957 This chapter explains how to define customized system images and how to
41958 turn them into actual bootable images.
41961 * image Reference:: Detail of image declarations.
41962 * Instantiate an Image:: How to instantiate an image record.
41963 * image-type Reference:: Detail of image types declaration.
41964 * Image Modules:: Definition of image modules.
41967 @node image Reference
41968 @section @code{image} Reference
41970 The @code{image} record, described right after, allows you to define a
41971 customized bootable system image.
41973 @deftp {Data Type} image
41974 This is the data type representing a system image.
41977 @item @code{name} (default: @code{#false})
41978 The image name as a symbol, @code{'my-iso9660} for instance. The name
41979 is optional and it defaults to @code{#false}.
41981 @item @code{format}
41982 The image format as a symbol. The following formats are supported:
41985 @item @code{disk-image}, a raw disk image composed of one or multiple
41988 @item @code{compressed-qcow2}, a compressed qcow2 image composed of
41989 one or multiple partitions.
41991 @item @code{docker}, a Docker image.
41993 @item @code{iso9660}, an ISO-9660 image.
41995 @item @code{tarball}, a tar.gz image archive.
41997 @item @code{wsl2}, a WSL2 image.
42001 @item @code{platform} (default: @code{#false})
42002 The @code{platform} record the image is targeting (@pxref{Platforms}),
42003 @code{aarch64-linux} for instance. By default, this field is set to
42004 @code{#false} and the image will target the host platform.
42006 @item @code{size} (default: @code{'guess})
42007 The image size in bytes or @code{'guess}. The @code{'guess} symbol,
42008 which is the default, means that the image size will be inferred based
42009 on the image content.
42011 @item @code{operating-system}
42012 The image's @code{operating-system} record that is instanciated.
42014 @item @code{partition-table-type} (default: @code{'mbr})
42015 The image partition table type as a symbol. Possible values are
42016 @code{'mbr} and @code{'gpt}. It default to @code{'mbr}.
42018 @item @code{partitions} (default: @code{'()})
42019 The image partitions as a list of @code{partition} records
42020 (@pxref{partition Reference}).
42022 @item @code{compression?} (default: @code{#true})
42023 Whether the image content should be compressed, as a boolean. It
42024 defaults to @code{#true} and only applies to @code{'iso9660} image
42027 @item @code{volatile-root?} (default: @code{#true})
42028 Whether the image root partition should be made volatile, as a boolean.
42030 This is achieved by using a RAM backed file system (overlayfs) that is
42031 mounted on top of the root partition by the initrd. It defaults to
42032 @code{#true}. When set to @code{#false}, the image root partition is
42033 mounted as read-write partition by the initrd.
42035 @item @code{shared-store?} (default: @code{#false})
42036 Whether the image's store should be shared with the host system, as a
42037 boolean. This can be useful when creating images dedicated to virtual
42038 machines. When set to @code{#false}, which is the default, the image's
42039 @code{operating-system} closure is copied to the image. Otherwise, when
42040 set to @code{#true}, it is assumed that the host store will be made
42041 available at boot, using a @code{9p} mount for instance.
42043 @item @code{shared-network?} (default: @code{#false})
42044 Whether to use the host network interfaces within the image, as a
42045 boolean. This is only used for the @code{'docker} image format. It
42046 defaults to @code{#false}.
42048 @item @code{substitutable?} (default: @code{#true})
42049 Whether the image derivation should be substitutable, as a boolean. It
42050 defaults to @code{true}.
42055 @node partition Reference
42056 @subsection @code{partition} Reference
42058 In @code{image} record may contain some partitions.
42060 @deftp {Data Type} partition
42061 This is the data type representing an image partition.
42064 @item @code{size} (default: @code{'guess})
42065 The partition size in bytes or @code{'guess}. The @code{'guess} symbol,
42066 which is the default, means that the partition size will be inferred
42067 based on the partition content.
42069 @item @code{offset} (default: @code{0})
42070 The partition's start offset in bytes, relative to the image start or
42071 the previous partition end. It defaults to @code{0} which means that
42072 there is no offset applied.
42074 @item @code{file-system} (default: @code{"ext4"})
42075 The partition file system as a string, defaulting to @code{"ext4"}. The
42076 supported values are @code{"vfat"}, @code{"fat16"}, @code{"fat32"} and
42079 @item @code{file-system-options} (default: @code{'()})
42080 The partition file system creation options that should be passed to the
42081 partition creation tool, as a list of strings. This is only supported
42082 when creating @code{"ext4"} partitions.
42084 See the @code{"extended-options"} man page section of the
42085 @code{"mke2fs"} tool for a more complete reference.
42088 The partition label as a mandatory string, @code{"my-root"} for
42091 @item @code{uuid} (default: @code{#false})
42092 The partition UUID as an @code{uuid} record (@pxref{File Systems}). By
42093 default it is @code{#false}, which means that the partition creation
42094 tool will attribute a random UUID to the partition.
42096 @item @code{flags} (default: @code{'()})
42097 The partition flags as a list of symbols. Possible values are
42098 @code{'boot} and @code{'esp}. The @code{'boot} flags should be set if
42099 you want to boot from this partition. Exactly one partition should have
42100 this flag set, usually the root one. The @code{'esp} flag identifies a
42101 UEFI System Partition.
42103 @item @code{initializer} (default: @code{#false})
42104 The partition initializer procedure as a gexp. This procedure is called
42105 to populate a partition. If no initializer is passed, the
42106 @code{initialize-root-partition} procedure from the @code{(gnu build
42107 image)} module is used.
42112 @node Instantiate an Image
42113 @section Instantiate an Image
42115 Let's say you would like to create an MBR image with three distinct
42119 @item The @acronym{ESP, EFI System Partition}, a partition of
42120 40@tie{}MiB at offset 1024@tie{}KiB with a vfat file system.
42122 @item an ext4 partition of 50@tie{}MiB data file, and labeled ``data''.
42124 @item an ext4 bootable partition containing the @code{%simple-os}
42128 You would then write the following image definition in a
42129 @code{my-image.scm} file for instance.
42138 (define MiB (expt 2 20))
42141 (format 'disk-image)
42142 (operating-system %simple-os)
42147 (offset (* 1024 1024))
42149 (file-system "vfat")
42151 (initializer (gexp initialize-efi-partition)))
42155 (file-system "ext4")
42156 (initializer #~(lambda* (root . rest)
42158 (call-with-output-file
42159 (string-append root "/data")
42161 (format port "my-data"))))))
42165 (file-system "ext4")
42167 (initializer (gexp initialize-root-partition))))))
42170 Note that the first and third partitions use generic initializers
42171 procedures, initialize-efi-partition and initialize-root-partition
42172 respectively. The initialize-efi-partition installs a GRUB EFI loader
42173 that is loading the GRUB bootloader located in the root partition. The
42174 initialize-root-partition instantiates a complete system as defined by
42175 the @code{%simple-os} operating-system.
42180 guix system image my-image.scm
42183 to instantiate the @code{image} definition. That produces a disk image
42184 which has the expected structure:
42187 $ parted $(guix system image my-image.scm) print
42190 Disk /gnu/store/yhylv1bp5b2ypb97pd3bbhz6jk5nbhxw-disk-image: 1714MB
42191 Sector size (logical/physical): 512B/512B
42192 Partition Table: msdos
42195 Number Start End Size Type File system Flags
42196 1 1049kB 43.0MB 41.9MB primary fat16 esp
42197 2 43.0MB 95.4MB 52.4MB primary ext4
42198 3 95.4MB 1714MB 1619MB primary ext4 boot
42201 The size of the @code{boot} partition has been inferred to @code{1619MB}
42202 so that it is large enough to host the @code{%simple-os}
42205 You can also use existing @code{image} record definitions and inherit
42206 from them to simplify the @code{image} definition. The @code{(gnu
42207 system image)} module provides the following @code{image} definition
42210 @defvr {Scheme Variable} efi-disk-image
42211 A MBR disk-image composed of two partitions: a 64 bits ESP partition and
42212 a ROOT boot partition. This image can be used on most @code{x86_64} and
42213 @code{i686} machines, supporting BIOS or UEFI booting.
42216 @defvr {Scheme Variable} efi32-disk-image
42217 Same as @code{efi-disk-image} but with a 32 bits EFI partition.
42220 @defvr {Scheme Variable} iso9660-image
42221 An ISO-9660 image composed of a single bootable partition. This image
42222 can also be used on most @code{x86_64} and @code{i686} machines.
42225 @defvr {Scheme Variable} docker-image
42226 A Docker image that can be used to spawn a Docker container.
42229 Using the @code{efi-disk-image} we can simplify our previous
42230 @code{image} declaration this way:
42240 (define MiB (expt 2 20))
42246 (file-system "ext4")
42247 (initializer #~(lambda* (root . rest)
42249 (call-with-output-file
42250 (string-append root "/data")
42252 (format port "my-data")))))))
42255 (inherit efi-disk-image)
42256 (operating-system %simple-os)
42258 (match (image-partitions efi-disk-image)
42260 (list esp data root)))))
42263 This will give the exact same @code{image} instantiation but the
42264 @code{image} declaration is simpler.
42266 @node image-type Reference
42267 @section image-type Reference
42269 The @command{guix system image} command can, as we saw above, take a
42270 file containing an @code{image} declaration as argument and produce an
42271 actual disk image from it. The same command can also handle a file
42272 containing an @code{operating-system} declaration as argument. In that
42273 case, how is the @code{operating-system} turned into an image?
42275 That's where the @code{image-type} record intervenes. This record
42276 defines how to transform an @code{operating-system} record into an
42277 @code{image} record.
42279 @deftp {Data Type} image-type
42280 This is the data type representing an image-type.
42284 The image-type name as a mandatory symbol, @code{'efi32-raw} for
42287 @item @code{constructor}
42288 The image-type constructor, as a mandatory procedure that takes an
42289 @code{operating-system} record as argument and returns an @code{image}
42295 There are several @code{image-type} records provided by the @code{(gnu
42296 system image)} and the @code{(gnu system images @dots{})} modules.
42298 @defvr {Scheme Variable} efi-raw-image-type
42299 Build an image based on the @code{efi-disk-image} image.
42302 @defvr {Scheme Variable} efi32-raw-image-type
42303 Build an image based on the @code{efi32-disk-image} image.
42306 @defvr {Scheme Variable} qcow2-image-type
42307 Build an image based on the @code{efi-disk-image} image but with the
42308 @code{compressed-qcow2} image format.
42311 @defvr {Scheme Variable} iso-image-type
42312 Build a compressed image based on the @code{iso9660-image} image.
42315 @defvr {Scheme Variable} uncompressed-iso-image-type
42316 Build an image based on the @code{iso9660-image} image but with the
42317 @code{compression?} field set to @code{#false}.
42320 @defvr {Scheme Variable} docker-image-type
42321 Build an image based on the @code{docker-image} image.
42324 @defvr {Scheme Variable} raw-with-offset-image-type
42325 Build an MBR image with a single partition starting at a @code{1024KiB}
42326 offset. This is useful to leave some room to install a bootloader in
42330 @defvr {Scheme Variable} pinebook-pro-image-type
42331 Build an image that is targeting the Pinebook Pro machine. The MBR
42332 image contains a single partition starting at a @code{9MiB} offset. The
42333 @code{u-boot-pinebook-pro-rk3399-bootloader} bootloader will be
42334 installed in this gap.
42337 @defvr {Scheme Variable} rock64-image-type
42338 Build an image that is targeting the Rock64 machine. The MBR image
42339 contains a single partition starting at a @code{16MiB} offset. The
42340 @code{u-boot-rock64-rk3328-bootloader} bootloader will be installed in
42344 @defvr {Scheme Variable} novena-image-type
42345 Build an image that is targeting the Novena machine. It has the same
42346 characteristics as @code{raw-with-offset-image-type}.
42349 @defvr {Scheme Variable} pine64-image-type
42350 Build an image that is targeting the Pine64 machine. It has the same
42351 characteristics as @code{raw-with-offset-image-type}.
42354 @defvr {Scheme Variable} hurd-image-type
42355 Build an image that is targeting a @code{i386} machine running the Hurd
42356 kernel. The MBR image contains a single ext2 partitions with specific
42357 @code{file-system-options} flags.
42360 @defvr {Scheme Variable} hurd-qcow2-image-type
42361 Build an image similar to the one built by the @code{hurd-image-type}
42362 but with the @code{format} set to @code{'compressed-qcow2}.
42365 @defvr {Scheme Variable} wsl2-image-type
42366 Build an image for the @acronym{WSL2, Windows Subsystem for Linux 2}.
42367 It can be imported by running:
42370 wsl --import Guix ./guix ./wsl2-image.tar.gz
42376 So, if we get back to the @code{guix system image} command taking an
42377 @code{operating-system} declaration as argument. By default, the
42378 @code{efi-raw-image-type} is used to turn the provided
42379 @code{operating-system} into an actual bootable image.
42381 To use a different @code{image-type}, the @code{--image-type} option can
42382 be used. The @code{--list-image-types} option will list all the
42383 supported image types. It turns out to be a textual listing of all the
42384 @code{image-types} variables described just above (@pxref{Invoking guix
42387 @node Image Modules
42388 @section Image Modules
42390 Let's take the example of the Pine64, an ARM based machine. To be able
42391 to produce an image targeting this board, we need the following
42395 @item An @code{operating-system} record containing at least
42396 an appropriate kernel (@code{linux-libre-arm64-generic}) and bootloader
42397 @code{u-boot-pine64-lts-bootloader}) for the Pine64.
42399 @item Possibly, an @code{image-type} record providing a way to
42400 turn an @code{operating-system} record to an @code{image} record
42401 suitable for the Pine64.
42403 @item An actual @code{image} that can be instantiated with the
42404 @command{guix system image} command.
42408 The @code{(gnu system images pine64)} module provides all those
42409 elements: @code{pine64-barebones-os}, @code{pine64-image-type} and
42410 @code{pine64-barebones-raw-image} respectively.
42412 The module returns the @code{pine64-barebones-raw-image} in order for
42413 users to be able to run:
42416 guix system image gnu/system/images/pine64.scm
42419 Now, thanks to the @code{pine64-image-type} record declaring the
42420 @code{'pine64-raw} @code{image-type}, one could also prepare a
42421 @code{my-pine.scm} file with the following content:
42424 (use-modules (gnu system images pine64))
42426 (inherit pine64-barebones-os)
42427 (timezone "Europe/Athens"))
42430 to customize the @code{pine64-barebones-os}, and run:
42433 $ guix system image --image-type=pine64-raw my-pine.scm
42436 Note that there are other modules in the @code{gnu/system/images}
42437 directory targeting @code{Novena}, @code{Pine64}, @code{PinebookPro} and
42438 @code{Rock64} machines.
42440 @node Installing Debugging Files
42441 @chapter Installing Debugging Files
42443 @cindex debugging files
42444 Program binaries, as produced by the GCC compilers for instance, are
42445 typically written in the ELF format, with a section containing
42446 @dfn{debugging information}. Debugging information is what allows the
42447 debugger, GDB, to map binary code to source code; it is required to
42448 debug a compiled program in good conditions.
42450 This chapter explains how to use separate debug info when packages
42451 provide it, and how to rebuild packages with debug info when it's
42455 * Separate Debug Info:: Installing 'debug' outputs.
42456 * Rebuilding Debug Info:: Building missing debug info.
42459 @node Separate Debug Info
42460 @section Separate Debug Info
42462 The problem with debugging information is that is takes up a fair amount
42463 of disk space. For example, debugging information for the GNU C Library
42464 weighs in at more than 60 MiB@. Thus, as a user, keeping all the
42465 debugging info of all the installed programs is usually not an option.
42466 Yet, space savings should not come at the cost of an impediment to
42467 debugging---especially in the GNU system, which should make it easier
42468 for users to exert their computing freedom (@pxref{GNU Distribution}).
42470 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a
42471 mechanism that allows users to get the best of both worlds: debugging
42472 information can be stripped from the binaries and stored in separate
42473 files. GDB is then able to load debugging information from those files,
42474 when they are available (@pxref{Separate Debug Files,,, gdb, Debugging
42477 The GNU distribution takes advantage of this by storing debugging
42478 information in the @code{lib/debug} sub-directory of a separate package
42479 output unimaginatively called @code{debug} (@pxref{Packages with
42480 Multiple Outputs}). Users can choose to install the @code{debug} output
42481 of a package when they need it. For instance, the following command
42482 installs the debugging information for the GNU C Library and for GNU
42486 guix install glibc:debug guile:debug
42489 GDB must then be told to look for debug files in the user's profile, by
42490 setting the @code{debug-file-directory} variable (consider setting it
42491 from the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with
42495 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
42498 From there on, GDB will pick up debugging information from the
42499 @file{.debug} files under @file{~/.guix-profile/lib/debug}.
42501 Below is an alternative GDB script which is useful when working with
42502 other profiles. It takes advantage of the optional Guile integration in
42503 GDB. This snippet is included by default on Guix System in the
42504 @file{~/.gdbinit} file.
42508 (use-modules (gdb))
42509 (execute (string-append "set debug-file-directory "
42510 (or (getenv "GDB_DEBUG_FILE_DIRECTORY")
42511 "~/.guix-profile/lib/debug")))
42515 In addition, you will most likely want GDB to be able to show the source
42516 code being debugged. To do that, you will have to unpack the source
42517 code of the package of interest (obtained with @code{guix build
42518 --source}, @pxref{Invoking guix build}), and to point GDB to that source
42519 directory using the @code{directory} command (@pxref{Source Path,
42520 @code{directory},, gdb, Debugging with GDB}).
42522 @c XXX: keep me up-to-date
42523 The @code{debug} output mechanism in Guix is implemented by the
42524 @code{gnu-build-system} (@pxref{Build Systems}). Currently, it is
42525 opt-in---debugging information is available only for the packages with
42526 definitions explicitly declaring a @code{debug} output. To check
42527 whether a package has a @code{debug} output, use @command{guix package
42528 --list-available} (@pxref{Invoking guix package}).
42530 Read on for how to deal with packages lacking a @code{debug} output.
42532 @node Rebuilding Debug Info
42533 @section Rebuilding Debug Info
42535 @cindex debugging info, rebuilding
42536 As we saw above, some packages, but not all, provide debugging info in a
42537 @code{debug} output. What can you do when debugging info is missing?
42538 The @option{--with-debug-info} option provides a solution to that: it
42539 allows you to rebuild the package(s) for which debugging info is
42540 missing---and only those---and to graft those onto the application
42541 you're debugging. Thus, while it's not as fast as installing a
42542 @code{debug} output, it is relatively inexpensive.
42544 Let's illustrate that. Suppose you're experiencing a bug in Inkscape
42545 and would like to see what's going on in GLib, a library that's deep
42546 down in its dependency graph. As it turns out, GLib does not have a
42547 @code{debug} output and the backtrace GDB shows is all sadness:
42551 #0 0x00007ffff5f92190 in g_getenv ()
42552 from /gnu/store/@dots{}-glib-2.62.6/lib/libglib-2.0.so.0
42553 #1 0x00007ffff608a7d6 in gobject_init_ctor ()
42554 from /gnu/store/@dots{}-glib-2.62.6/lib/libgobject-2.0.so.0
42555 #2 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=1, argv=argv@@entry=0x7fffffffcfd8,
42556 env=env@@entry=0x7fffffffcfe8) at dl-init.c:72
42557 #3 0x00007ffff7fe2866 in call_init (env=0x7fffffffcfe8, argv=0x7fffffffcfd8, argc=1, l=<optimized out>)
42561 To address that, you install Inkscape linked against a variant GLib that
42562 contains debug info:
42565 guix install inkscape --with-debug-info=glib
42568 This time, debugging will be a whole lot nicer:
42571 $ gdb --args sh -c 'exec inkscape'
42574 Function "g_getenv" not defined.
42575 Make breakpoint pending on future shared library load? (y or [n]) y
42576 Breakpoint 1 (g_getenv) pending.
42578 Starting program: /gnu/store/@dots{}-profile/bin/sh -c exec\ inkscape
42581 #0 g_getenv (variable=variable@@entry=0x7ffff60c7a2e "GOBJECT_DEBUG") at ../glib-2.62.6/glib/genviron.c:252
42582 #1 0x00007ffff608a7d6 in gobject_init () at ../glib-2.62.6/gobject/gtype.c:4380
42583 #2 gobject_init_ctor () at ../glib-2.62.6/gobject/gtype.c:4493
42584 #3 0x00007ffff7fe275a in call_init (l=<optimized out>, argc=argc@@entry=3, argv=argv@@entry=0x7fffffffd088,
42585 env=env@@entry=0x7fffffffd0a8) at dl-init.c:72
42591 Note that there can be packages for which @option{--with-debug-info}
42592 will not have the desired effect. @xref{Package Transformation Options,
42593 @option{--with-debug-info}}, for more information.
42595 @node Using TeX and LaTeX
42596 @chapter Using @TeX{} and @LaTeX{}
42598 @cindex @TeX{} packages
42599 @cindex @LaTeX{} packages
42600 Guix provides packages for the @TeX{}, @LaTeX{}, ConTeXt, LuaTeX, and
42601 related typesetting systems, taken from the
42602 @uref{https://www.tug.org/texlive/, @TeX{} Live distribution}. However,
42603 because @TeX{} Live is so huge and because finding your way in this maze
42604 is tricky, we thought that you, dear user, would welcome guidance on how
42605 to deploy the relevant packages so you can compile your @TeX{} and
42606 @LaTeX{} documents.
42608 @TeX{} Live currently comes in two flavors in Guix:
42612 The ``monolithic'' @code{texlive} package: it comes with @emph{every
42613 single @TeX{} Live package} (more than 7,000 of them), but it is huge
42614 (more than 4@tie{}GiB for a single package!).
42617 The ``modular'' @code{texlive-} packages: you install
42618 @code{texlive-base}, which provides core functionality and the main
42619 commands---@command{pdflatex}, @command{dvips}, @command{luatex},
42620 @command{mf}, etc.---together with individual packages that provide just
42621 the features you need---@code{texlive-listings} for the
42622 @code{listings} package, @code{texlive-hyperref} for @code{hyperref},
42623 @code{texlive-beamer} for Beamer, @code{texlive-pgf} for PGF/TikZ,
42627 We recommend using the modular package set because it is much less
42628 resource-hungry. To build your documents, you would use commands such
42632 guix shell texlive-base texlive-wrapfig \
42633 texlive-hyperref texlive-cm-super -- pdflatex doc.tex
42636 You can quickly end up with unreasonably long command lines though. The
42637 solution is to instead write a manifest, for example like this one:
42640 (specifications->manifest
42646 "texlive-microtype"
42647 "texlive-listings" "texlive-hyperref"
42652 ;; Additional fonts.
42653 "texlive-cm-super" "texlive-amsfonts"
42654 "texlive-times" "texlive-helvetic" "texlive-courier"))
42657 You can then pass it to any command with the @option{-m} option:
42660 guix shell -m manifest.scm -- pdflatex doc.tex
42663 @xref{Writing Manifests}, for more on
42664 manifests. In the future, we plan to provide packages for @TeX{} Live
42665 @dfn{collections}---``meta-packages'' such as @code{fontsrecommended},
42666 @code{humanities}, or @code{langarabic} that provide the set of packages
42667 needed in this particular domain. That will allow you to list fewer
42670 The main difficulty here is that using the modular package set forces
42671 you to select precisely the packages that you need. You can use
42672 @command{guix search}, but finding the right package can prove to be
42673 tedious. When a package is missing, @command{pdflatex} and similar
42674 commands fail with an obscure message along the lines of:
42677 doc.tex: File `tikz.sty' not found.
42678 doc.tex:7: Emergency stop.
42682 or, for a missing font:
42685 kpathsea: Running mktexmf phvr7t
42686 ! I can't find file `phvr7t'.
42689 How do you determine what the missing package is? In the first case,
42690 you'll find the answer by running:
42693 $ guix search texlive tikz
42699 In the second case, @command{guix search} turns up nothing. Instead,
42700 you can search the @TeX{} Live package database using the @command{tlmgr}
42704 $ guix shell texlive-base -- tlmgr info phvr7t
42705 tlmgr: cannot find package phvr7t, searching for other matches:
42707 Packages containing `phvr7t' in their title/description:
42709 Packages containing files matching `phvr7t':
42711 texmf-dist/fonts/tfm/adobe/helvetic/phvr7t.tfm
42712 texmf-dist/fonts/tfm/adobe/helvetic/phvr7tn.tfm
42713 texmf-dist/fonts/vf/adobe/helvetic/phvr7t.vf
42714 texmf-dist/fonts/vf/adobe/helvetic/phvr7tn.vf
42716 texmf-dist/tex4ht/ht-fonts/alias/adobe/helvetic/phvr7t.htf
42719 The file is available in the @TeX{} Live @code{helvetic} package, which is
42720 known in Guix as @code{texlive-helvetic}. Quite a ride, but we found
42723 There is one important limitation though: Guix currently provides a
42724 subset of the @TeX{} Live packages. If you stumble upon a missing
42725 package, you can try and import it (@pxref{Invoking guix import}):
42728 guix import texlive @var{package}
42731 Additional options include:
42736 Traverse the dependency graph of the given upstream package recursively
42737 and generate package expressions for all those packages that are not yet
42742 @TeX{} Live packaging is still very much work in progress, but you can
42743 help! @xref{Contributing}, for more information.
42746 @node Security Updates
42747 @chapter Security Updates
42749 @cindex security updates
42750 @cindex security vulnerabilities
42751 Occasionally, important security vulnerabilities are discovered in software
42752 packages and must be patched. Guix developers try hard to keep track of
42753 known vulnerabilities and to apply fixes as soon as possible in the
42754 @code{master} branch of Guix (we do not yet provide a ``stable'' branch
42755 containing only security updates). The @command{guix lint} tool helps
42756 developers find out about vulnerable versions of software packages in the
42761 gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
42762 gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276
42763 gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
42767 @xref{Invoking guix lint}, for more information.
42769 Guix follows a functional
42770 package management discipline (@pxref{Introduction}), which implies
42771 that, when a package is changed, @emph{every package that depends on it}
42772 must be rebuilt. This can significantly slow down the deployment of
42773 fixes in core packages such as libc or Bash, since basically the whole
42774 distribution would need to be rebuilt. Using pre-built binaries helps
42775 (@pxref{Substitutes}), but deployment may still take more time than
42779 To address this, Guix implements @dfn{grafts}, a mechanism that allows
42780 for fast deployment of critical updates without the costs associated
42781 with a whole-distribution rebuild. The idea is to rebuild only the
42782 package that needs to be patched, and then to ``graft'' it onto packages
42783 explicitly installed by the user and that were previously referring to
42784 the original package. The cost of grafting is typically very low, and
42785 order of magnitudes lower than a full rebuild of the dependency chain.
42787 @cindex replacements of packages, for grafts
42788 For instance, suppose a security update needs to be applied to Bash.
42789 Guix developers will provide a package definition for the ``fixed''
42790 Bash, say @code{bash-fixed}, in the usual way (@pxref{Defining
42791 Packages}). Then, the original package definition is augmented with a
42792 @code{replacement} field pointing to the package containing the bug fix:
42799 (replacement bash-fixed)))
42802 From there on, any package depending directly or indirectly on Bash---as
42803 reported by @command{guix gc --requisites} (@pxref{Invoking guix
42804 gc})---that is installed is automatically ``rewritten'' to refer to
42805 @code{bash-fixed} instead of @code{bash}. This grafting process takes
42806 time proportional to the size of the package, usually less than a
42807 minute for an ``average'' package on a recent machine. Grafting is
42808 recursive: when an indirect dependency requires grafting, then grafting
42809 ``propagates'' up to the package that the user is installing.
42811 Currently, the length of the name and version of the graft and that of
42812 the package it replaces (@code{bash-fixed} and @code{bash} in the example
42813 above) must be equal. This restriction mostly comes from the fact that
42814 grafting works by patching files, including binary files, directly.
42815 Other restrictions may apply: for instance, when adding a graft to a
42816 package providing a shared library, the original shared library and its
42817 replacement must have the same @code{SONAME} and be binary-compatible.
42819 The @option{--no-grafts} command-line option allows you to forcefully
42820 avoid grafting (@pxref{Common Build Options, @option{--no-grafts}}).
42824 guix build bash --no-grafts
42828 returns the store file name of the original Bash, whereas:
42835 returns the store file name of the ``fixed'', replacement Bash. This
42836 allows you to distinguish between the two variants of Bash.
42838 To verify which Bash your whole profile refers to, you can run
42839 (@pxref{Invoking guix gc}):
42842 guix gc -R $(readlink -f ~/.guix-profile) | grep bash
42846 @dots{} and compare the store file names that you get with those above.
42847 Likewise for a complete Guix system generation:
42850 guix gc -R $(guix system build my-config.scm) | grep bash
42853 Lastly, to check which Bash running processes are using, you can use the
42854 @command{lsof} command:
42857 lsof | grep /gnu/store/.*bash
42861 @node Bootstrapping
42862 @chapter Bootstrapping
42864 @c Adapted from the ELS 2013 paper.
42866 @cindex bootstrapping
42868 Bootstrapping in our context refers to how the distribution gets built
42869 ``from nothing''. Remember that the build environment of a derivation
42870 contains nothing but its declared inputs (@pxref{Introduction}). So
42871 there's an obvious chicken-and-egg problem: how does the first package
42872 get built? How does the first compiler get compiled?
42874 It is tempting to think of this question as one that only die-hard
42875 hackers may care about. However, while the answer to that question is
42876 technical in nature, its implications are wide-ranging. How the
42877 distribution is bootstrapped defines the extent to which we, as
42878 individuals and as a collective of users and hackers, can trust the
42879 software we run. It is a central concern from the standpoint of
42880 @emph{security} and from a @emph{user freedom} viewpoint.
42882 @cindex bootstrap binaries
42883 The GNU system is primarily made of C code, with libc at its core. The
42884 GNU build system itself assumes the availability of a Bourne shell and
42885 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
42886 `grep'. Furthermore, build programs---programs that run
42887 @code{./configure}, @code{make}, etc.---are written in Guile Scheme
42888 (@pxref{Derivations}). Consequently, to be able to build anything at
42889 all, from scratch, Guix relies on pre-built binaries of Guile, GCC,
42890 Binutils, libc, and the other packages mentioned above---the
42891 @dfn{bootstrap binaries}.
42893 These bootstrap binaries are ``taken for granted'', though we can also
42894 re-create them if needed (@pxref{Preparing to Use the Bootstrap
42898 * Reduced Binary Seed Bootstrap:: A Bootstrap worthy of GNU.
42899 * Preparing to Use the Bootstrap Binaries:: Building that what matters most.
42902 @node Reduced Binary Seed Bootstrap
42903 @section The Reduced Binary Seed Bootstrap
42905 Guix---like other GNU/Linux distributions---is traditionally bootstrapped from
42906 a set of bootstrap binaries: Bourne shell, command-line tools provided by GNU
42907 Coreutils, Awk, Findutils, `sed', and `grep' and Guile, GCC, Binutils, and the
42908 GNU C Library (@pxref{Bootstrapping}). Usually, these bootstrap binaries are
42909 ``taken for granted.''
42911 Taking the bootstrap binaries for granted means that we consider them to
42912 be a correct and trustworthy ``seed'' for building the complete system.
42913 Therein lies a problem: the combined size of these bootstrap binaries is
42914 about 250MB (@pxref{Bootstrappable Builds,,, mes, GNU Mes}). Auditing
42915 or even inspecting these is next to impossible.
42917 For @code{i686-linux} and @code{x86_64-linux}, Guix now features a
42918 ``Reduced Binary Seed'' bootstrap @footnote{We would like to say: ``Full
42919 Source Bootstrap'' and while we are working towards that goal it would
42920 be hyperbole to use that term for what we do now.}.
42922 The Reduced Binary Seed bootstrap removes the most critical tools---from a
42923 trust perspective---from the bootstrap binaries: GCC, Binutils and the GNU C
42924 Library are replaced by: @code{bootstrap-mescc-tools} (a tiny assembler and
42925 linker) and @code{bootstrap-mes} (a small Scheme Interpreter and a C compiler
42926 written in Scheme and the Mes C Library, built for TinyCC and for GCC).
42928 Using these new binary seeds the ``missing'' Binutils, GCC, and the GNU
42929 C Library are built from source. From here on the more traditional
42930 bootstrap process resumes. This approach has reduced the bootstrap
42931 binaries in size to about 145MB in Guix v1.1.
42933 The next step that Guix has taken is to replace the shell and all its
42934 utilities with implementations in Guile Scheme, the @emph{Scheme-only
42935 bootstrap}. Gash (@pxref{Gash,,, gash, The Gash manual}) is a
42936 POSIX-compatible shell that replaces Bash, and it comes with Gash Utils
42937 which has minimalist replacements for Awk, the GNU Core Utilities, Grep,
42938 Gzip, Sed, and Tar. The rest of the bootstrap binary seeds that were
42939 removed are now built from source.
42941 Building the GNU System from source is currently only possible by adding
42942 some historical GNU packages as intermediate steps@footnote{Packages
42943 such as @code{gcc-2.95.3}, @code{binutils-2.14}, @code{glibc-2.2.5},
42944 @code{gzip-1.2.4}, @code{tar-1.22}, and some others. For details, see
42945 @file{gnu/packages/commencement.scm}.}. As Gash and Gash Utils mature,
42946 and GNU packages become more bootstrappable again (e.g., new releases of
42947 GNU Sed will also ship as gzipped tarballs again, as alternative to the
42948 hard to bootstrap @code{xz}-compression), this set of added packages can
42949 hopefully be reduced again.
42951 The graph below shows the resulting dependency graph for
42952 @code{gcc-core-mesboot0}, the bootstrap compiler used for the
42953 traditional bootstrap of the rest of the Guix System.
42955 @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
42956 @image{images/gcc-core-mesboot0-graph,6in,,Dependency graph of gcc-core-mesboot0}
42958 The only significant binary bootstrap seeds that remain@footnote{
42959 Ignoring the 68KB @code{mescc-tools}; that will be removed later,
42960 together with @code{mes}.} are a Scheme interpreter and a Scheme
42961 compiler: GNU Mes and GNU Guile@footnote{Not shown in this graph are the
42962 static binaries for @file{bash}, @code{tar}, and @code{xz} that are used
42963 to get Guile running.}.
42965 This further reduction has brought down the size of the binary seed to
42966 about 60MB for @code{i686-linux} and @code{x86_64-linux}.
42968 Work is ongoing to remove all binary blobs from our free software
42969 bootstrap stack, working towards a Full Source Bootstrap. Also ongoing
42970 is work to bring these bootstraps to the @code{arm-linux} and
42971 @code{aarch64-linux} architectures and to the Hurd.
42973 If you are interested, join us on @samp{#bootstrappable} on the Freenode
42974 IRC network or discuss on @email{bug-mes@@gnu.org} or
42975 @email{gash-devel@@nongnu.org}.
42977 @node Preparing to Use the Bootstrap Binaries
42978 @section Preparing to Use the Bootstrap Binaries
42980 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
42981 @c large image, it's hard to scroll. Oh well.
42982 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap derivations}
42984 The figure above shows the very beginning of the dependency graph of the
42985 distribution, corresponding to the package definitions of the @code{(gnu
42986 packages bootstrap)} module. A similar figure can be generated with
42987 @command{guix graph} (@pxref{Invoking guix graph}), along the lines of:
42990 guix graph -t derivation \
42991 -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
42992 | dot -Tps > gcc.ps
42995 or, for the further Reduced Binary Seed bootstrap
42998 guix graph -t derivation \
42999 -e '(@@@@ (gnu packages bootstrap) %bootstrap-mes)' \
43000 | dot -Tps > mes.ps
43003 At this level of detail, things are
43004 slightly complex. First, Guile itself consists of an ELF executable,
43005 along with many source and compiled Scheme files that are dynamically
43006 loaded when it runs. This gets stored in the @file{guile-2.0.7.tar.xz}
43007 tarball shown in this graph. This tarball is part of Guix's ``source''
43008 distribution, and gets inserted into the store with @code{add-to-store}
43009 (@pxref{The Store}).
43011 But how do we write a derivation that unpacks this tarball and adds it
43012 to the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
43013 derivation---the first one that gets built---uses @code{bash} as its
43014 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
43015 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar},
43016 @file{xz}, and @file{mkdir} are statically-linked binaries, also part of
43017 the Guix source distribution, whose sole purpose is to allow the Guile
43018 tarball to be unpacked.
43020 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning
43021 Guile that can be used to run subsequent build programs. Its first task
43022 is to download tarballs containing the other pre-built binaries---this
43023 is what the @file{.tar.xz.drv} derivations do. Guix modules such as
43024 @code{ftp-client.scm} are used for this purpose. The
43025 @code{module-import.drv} derivations import those modules in a directory
43026 in the store, using the original layout. The
43027 @code{module-import-compiled.drv} derivations compile those modules, and
43028 write them in an output directory with the right layout. This
43029 corresponds to the @code{#:modules} argument of
43030 @code{build-expression->derivation} (@pxref{Derivations}).
43032 Finally, the various tarballs are unpacked by the derivations
43033 @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, or
43034 @code{bootstrap-mes-0.drv} and @code{bootstrap-mescc-tools-0.drv}, at which
43035 point we have a working C tool chain.
43037 @unnumberedsec Building the Build Tools
43039 Bootstrapping is complete when we have a full tool chain that does not
43040 depend on the pre-built bootstrap tools discussed above. This
43041 no-dependency requirement is verified by checking whether the files of
43042 the final tool chain contain references to the @file{/gnu/store}
43043 directories of the bootstrap inputs. The process that leads to this
43044 ``final'' tool chain is described by the package definitions found in
43045 the @code{(gnu packages commencement)} module.
43047 The @command{guix graph} command allows us to ``zoom out'' compared to
43048 the graph above, by looking at the level of package objects instead of
43049 individual derivations---remember that a package may translate to
43050 several derivations, typically one derivation to download its source,
43051 one to build the Guile modules it needs, and one to actually build the
43052 package from source. The command:
43055 guix graph -t bag \
43056 -e '(@@@@ (gnu packages commencement)
43057 glibc-final-with-bootstrap-bash)' | xdot -
43061 displays the dependency graph leading to the ``final'' C
43062 library@footnote{You may notice the @code{glibc-intermediate} label,
43063 suggesting that it is not @emph{quite} final, but as a good
43064 approximation, we will consider it final.}, depicted below.
43066 @image{images/bootstrap-packages,6in,,Dependency graph of the early packages}
43068 @c See <https://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
43069 The first tool that gets built with the bootstrap binaries is
43070 GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite
43071 for all the following packages. From there Findutils and Diffutils get
43074 Then come the first-stage Binutils and GCC, built as pseudo cross
43075 tools---i.e., with @option{--target} equal to @option{--host}. They are
43076 used to build libc. Thanks to this cross-build trick, this libc is
43077 guaranteed not to hold any reference to the initial tool chain.
43079 From there the final Binutils and GCC (not shown above) are built. GCC
43080 uses @command{ld} from the final Binutils, and links programs against
43081 the just-built libc. This tool chain is used to build the other
43082 packages used by Guix and by the GNU Build System: Guile, Bash,
43085 And voilà! At this point we have the complete set of build tools that
43086 the GNU Build System expects. These are in the @code{%final-inputs}
43087 variable of the @code{(gnu packages commencement)} module, and are
43088 implicitly used by any package that uses @code{gnu-build-system}
43089 (@pxref{Build Systems, @code{gnu-build-system}}).
43092 @unnumberedsec Building the Bootstrap Binaries
43094 @cindex bootstrap binaries
43095 Because the final tool chain does not depend on the bootstrap binaries,
43096 those rarely need to be updated. Nevertheless, it is useful to have an
43097 automated way to produce them, should an update occur, and this is what
43098 the @code{(gnu packages make-bootstrap)} module provides.
43100 The following command builds the tarballs containing the bootstrap binaries
43101 (Binutils, GCC, glibc, for the traditional bootstrap and linux-libre-headers,
43102 bootstrap-mescc-tools, bootstrap-mes for the Reduced Binary Seed bootstrap,
43103 and Guile, and a tarball containing a mixture of Coreutils and other basic
43104 command-line tools):
43107 guix build bootstrap-tarballs
43110 The generated tarballs are those that should be referred to in the
43111 @code{(gnu packages bootstrap)} module mentioned at the beginning of
43114 Still here? Then perhaps by now you've started to wonder: when do we
43115 reach a fixed point? That is an interesting question! The answer is
43116 unknown, but if you would like to investigate further (and have
43117 significant computational and storage resources to do so), then let us
43120 @unnumberedsec Reducing the Set of Bootstrap Binaries
43122 Our traditional bootstrap includes GCC, GNU Libc, Guile, etc. That's a lot of
43123 binary code! Why is that a problem? It's a problem because these big chunks
43124 of binary code are practically non-auditable, which makes it hard to establish
43125 what source code produced them. Every unauditable binary also leaves us
43126 vulnerable to compiler backdoors as described by Ken Thompson in the 1984
43127 paper @emph{Reflections on Trusting Trust}.
43129 This is mitigated by the fact that our bootstrap binaries were generated
43130 from an earlier Guix revision. Nevertheless it lacks the level of
43131 transparency that we get in the rest of the package dependency graph,
43132 where Guix always gives us a source-to-binary mapping. Thus, our goal
43133 is to reduce the set of bootstrap binaries to the bare minimum.
43135 The @uref{https://bootstrappable.org, Bootstrappable.org web site} lists
43136 on-going projects to do that. One of these is about replacing the
43137 bootstrap GCC with a sequence of assemblers, interpreters, and compilers
43138 of increasing complexity, which could be built from source starting from
43139 a simple and auditable assembler.
43141 Our first major achievement is the replacement of of GCC, the GNU C Library
43142 and Binutils by MesCC-Tools (a simple hex linker and macro assembler) and Mes
43143 (@pxref{Top, GNU Mes Reference Manual,, mes, GNU Mes}, a Scheme interpreter
43144 and C compiler in Scheme). Neither MesCC-Tools nor Mes can be fully
43145 bootstrapped yet and thus we inject them as binary seeds. We call this the
43146 Reduced Binary Seed bootstrap, as it has halved the size of our bootstrap
43147 binaries! Also, it has eliminated the C compiler binary; i686-linux and
43148 x86_64-linux Guix packages are now bootstrapped without any binary C compiler.
43150 Work is ongoing to make MesCC-Tools and Mes fully bootstrappable and we are
43151 also looking at any other bootstrap binaries. Your help is welcome!
43154 @chapter Porting to a New Platform
43156 As discussed above, the GNU distribution is self-contained, and
43157 self-containment is achieved by relying on pre-built ``bootstrap
43158 binaries'' (@pxref{Bootstrapping}). These binaries are specific to an
43159 operating system kernel, CPU architecture, and application binary
43160 interface (ABI). Thus, to port the distribution to a platform that is
43161 not yet supported, one must build those bootstrap binaries, and update
43162 the @code{(gnu packages bootstrap)} module to use them on that platform.
43164 Fortunately, Guix can @emph{cross compile} those bootstrap binaries.
43165 When everything goes well, and assuming the GNU tool chain supports the
43166 target platform, this can be as simple as running a command like this
43170 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
43173 For this to work, it is first required to register a new platform as
43174 defined in the @code{(guix platform)} module. A platform is making the
43175 connection between a GNU triplet (@pxref{Specifying Target Triplets, GNU
43176 configuration triplets,, autoconf, Autoconf}), the equivalent
43177 @var{system} in Nix notation, the name of the
43178 @var{glibc-dynamic-linker}, and the corresponding Linux architecture
43179 name if applicable (@pxref{Platforms}).
43181 Once the bootstrap tarball are built, the @code{(gnu packages
43182 bootstrap)} module needs to be updated to refer to these binaries on the
43183 target platform. That is, the hashes and URLs of the bootstrap tarballs
43184 for the new platform must be added alongside those of the currently
43185 supported platforms. The bootstrap Guile tarball is treated specially:
43186 it is expected to be available locally, and @file{gnu/local.mk} has
43187 rules to download it for the supported architectures; a rule for the new
43188 platform must be added as well.
43190 In practice, there may be some complications. First, it may be that the
43191 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
43192 above) is not recognized by all the GNU tools. Typically, glibc
43193 recognizes some of these, whereas GCC uses an extra @option{--with-abi}
43194 configure flag (see @code{gcc.scm} for examples of how to handle this).
43195 Second, some of the required packages could fail to build for that
43196 platform. Lastly, the generated binaries could be broken for some
43199 @c *********************************************************************
43200 @include contributing.texi
43202 @c *********************************************************************
43203 @node Acknowledgments
43204 @chapter Acknowledgments
43206 Guix is based on the @uref{https://nixos.org/nix/, Nix package manager},
43207 which was designed and
43208 implemented by Eelco Dolstra, with contributions from other people (see
43209 the @file{nix/AUTHORS} file in Guix). Nix pioneered functional package
43210 management, and promoted unprecedented features, such as transactional
43211 package upgrades and rollbacks, per-user profiles, and referentially
43212 transparent build processes. Without this work, Guix would not exist.
43214 The Nix-based software distributions, Nixpkgs and NixOS, have also been
43215 an inspiration for Guix.
43217 GNU@tie{}Guix itself is a collective work with contributions from a
43218 number of people. See the @file{AUTHORS} file in Guix for more
43219 information on these fine people. The @file{THANKS} file lists people
43220 who have helped by reporting bugs, taking care of the infrastructure,
43221 providing artwork and themes, making suggestions, and more---thank you!
43224 @c *********************************************************************
43225 @node GNU Free Documentation License
43226 @appendix GNU Free Documentation License
43227 @cindex license, GNU Free Documentation License
43228 @include fdl-1.3.texi
43230 @c *********************************************************************
43231 @node Concept Index
43232 @unnumbered Concept Index
43235 @node Programming Index
43236 @unnumbered Programming Index
43237 @syncodeindex tp fn
43238 @syncodeindex vr fn
43243 @c Local Variables:
43244 @c ispell-local-dictionary: "american";