2 @c ===========================================================================
4 @c This file was generated with po4a. Translate the source file.
6 @c ===========================================================================
10 @setfilename guix.de.info
11 @documentencoding UTF-8
14 @settitle Referenzhandbuch zu GNU Guix
17 @include version-de.texi
19 @c Identifier of the OpenPGP key used to sign tarballs and such.
20 @set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
21 @set KEY-SERVER pool.sks-keyservers.net
24 Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018 Ludovic
25 Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* Copyright
26 @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, 2015,
27 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@*
28 Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{}
29 2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017
30 Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018 Ricardo
31 Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{}
32 2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018
33 Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright
34 @copyright{} 2016, 2017 Nils Gillmann@* Copyright @copyright{} 2016, 2017,
35 2018 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@*
36 Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2017,
37 2018 Clément Lassieur@* Copyright @copyright{} 2017, 2018 Mathieu Othacehe@*
38 Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017,
39 2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@*
40 Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017
41 Christopher Allan Webber@* Copyright @copyright{} 2017, 2018 Marius Bakke@*
42 Copyright @copyright{} 2017 Hartmut Goebel@* Copyright @copyright{} 2017
43 Maxim Cournoyer@* Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@*
44 Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017
45 Andy Wingo@* Copyright @copyright{} 2017, 2018 Arun Isaac@* Copyright
46 @copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@*
47 Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike
48 Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright
49 @copyright{} 2018 Gábor Boskovits@* Copyright @copyright{} 2018 Florian
50 Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @copyright{}
53 Es ist Ihnen gestattet, dieses Dokument zu vervielfältigen, weiterzugeben
54 und/oder zu verändern, unter den Bedingungen der GNU Free Documentation
55 License, entweder gemäß Version 1.3 der Lizenz oder (nach Ihrer Option)
56 einer späteren Version, die von der Free Software Foundation veröffentlicht
57 wurde, ohne unveränderliche Abschnitte, ohne vorderen Umschlagtext und ohne
58 hinteren Umschlagtext. Eine Kopie der Lizenz finden Sie im Abschnitt mit dem
59 Titel »GNU Free Documentation License«.
62 @dircategory Systemadministration
64 * Guix: (guix.de). Installierte Software und Systemkonfigurationen
66 * guix package: (guix.de)guix package aufrufen. Pakete installieren,
69 * guix gc: (guix.de)guix gc aufrufen. Unbenutzten Plattenspeicher wieder
71 * guix pull: (guix.de)guix pull aufrufen. Die Liste verfügbarer Pakete
73 * guix system: (guix.de)guix system aufrufen. Die
74 Betriebssystemkonfiguration
78 @dircategory Softwareentwicklung
80 * guix environment: (guix.de)guix environment aufrufen. Umgebungen für
83 * guix build: (guix.de)guix build aufrufen. Erstellen von Paketen.
84 * guix pack: (guix.de)guix pack aufrufen. Bündel aus Binärdateien
89 @title Referenzhandbuch zu GNU Guix
90 @subtitle Den funktionalen Paketmanager GNU Guix benutzen
91 @author Die GNU-Guix-Entwickler
94 @vskip 0pt plus 1filll
95 Edition @value{EDITION} @* @value{UPDATED} @*
102 @c *********************************************************************
106 Dieses Dokument beschreibt GNU Guix, Version @value{VERSION}, ein
107 funktionales Paketverwaltungswerkzeug, das für das GNU-System geschrieben
110 @c TRANSLATORS: You can replace the following paragraph with information on
111 @c how to join your own translation team and how to report issues with the
113 This manual is also available in French (@pxref{Top,,, guix.fr, Manuel de
114 référence de GNU Guix}) and German (@pxref{Top,,, guix.de, Referenzhandbuch
115 zu GNU Guix}). If you would like to translate it in your native language,
117 @uref{https://translationproject.org/domain/guix-manual.html, Translation
121 * Einführung:: Was ist Guix überhaupt?
122 * Installation:: Guix installieren.
123 * Paketverwaltung:: Pakete installieren, aktualisieren usw.
124 * Programmierschnittstelle:: Guix in Scheme verwenden.
125 * Zubehör:: Befehle zur Paketverwaltung.
126 * GNU-Distribution:: Software für Ihr freundliches GNU-System.
127 * Mitwirken:: Ihre Hilfe ist nötig!
129 * Danksagungen:: Danke!
130 * GNU-Lizenz für freie Dokumentation:: Die Lizenz dieses Handbuchs.
131 * Konzeptverzeichnis:: Konzepte.
132 * Programmierverzeichnis:: Datentypen, Funktionen und Variable.
135 --- Detaillierte Liste der Knoten ---
143 * Aus Binärdatei installieren:: Guix installieren, ohne Zeit zu verlieren!
144 * Voraussetzungen:: Zum Erstellen und Benutzen von Guix nötige
146 * Die Testsuite laufen lassen:: Guix testen.
147 * Den Daemon einrichten:: Wie man die Umgebung des Erstellungs-Daemons
149 * Aufruf des guix-daemon:: Den Erstellungs-Daemon laufen lassen.
150 * Anwendungen einrichten:: Anwendungsspezifische Einstellungen.
152 Den Daemon einrichten
156 * Einrichten der Erstellungsumgebung:: Die isolierte Umgebung zum Erstellen
158 * Auslagern des Daemons einrichten:: Erstellungen auf entfernte Maschinen
160 * SELinux-Unterstützung:: Wie man eine SELinux-Richtlinie für den Daemon
167 * Funktionalitäten:: Wie Guix Ihr Leben schöner machen wird.
168 * Aufruf von guix package:: Pakete installieren, entfernen usw.
169 * Substitute:: Vorerstelle Binärdateien herunterladen.
170 * Pakete mit mehreren Ausgaben.:: Ein Quellpaket, mehrere Ausgaben.
171 * Aufruf von guix gc:: Den Müllsammler laufen lassen.
172 * Aufruf von guix pull:: Das neueste Guix samt Distribution laden.
173 * Channels:: Customizing the package collection.
174 * Inferiors:: Interacting with another revision of Guix.
175 * Invoking guix describe:: Display information about your Guix revision.
176 * Aufruf von guix pack:: Software-Bündel erstellen.
177 * Aufruf von guix archive:: Import und Export von Store-Dateien.
183 * Offizieller Substitut-Server:: Eine besondere Quelle von Substituten.
184 * Substitut-Server autorisieren:: Wie man Substitute an- und abschaltet.
185 * Substitutauthentifizierung:: Wie Guix Substitute verifiziert.
186 * Proxy-Einstellungen:: Wie Sie Substitute über einen Proxy beziehen.
187 * Fehler bei der Substitution:: Was passiert, wenn die Substitution
189 * Vom Vertrauen gegenüber Binärdateien:: Wie können Sie diesem binären
192 Programmierschnittstelle
196 * Pakete definieren:: Wie Sie neue Pakete definieren.
197 * Erstellungssysteme:: Angeben, wie Pakete erstellt werden.
198 * Der Store:: Den Paket-Store verändern.
199 * Ableitungen:: Systemnahe Schnittstelle für Paketableitungen.
200 * Die Store-Monade:: Rein funktionale Schnittstelle zum Store.
201 * G-Ausdrücke:: Erstellungsausdrücke verarbeiten.
202 * Invoking guix repl:: Fiddling with Guix interactively.
208 * „package“-Referenz:: Der Datentyp für Pakete.
209 * „origin“-Referenz:: Datentyp für Paketursprünge.
215 * Aufruf von guix build:: Pakete aus der Befehlszeile heraus erstellen.
216 * Aufruf von guix edit:: Paketdefinitionen bearbeiten.
217 * Aufruf von guix download:: Herunterladen einer Datei und Ausgabe ihres
219 * Aufruf von guix hash:: Den kryptographischen Hash einer Datei
221 * Aufruf von guix import:: Paketdefinitionen importieren.
222 * Aufruf von guix refresh:: Paketdefinitionen aktualisieren.
223 * Aufruf von guix lint:: Fehler in Paketdefinitionen finden.
224 * Aufruf von guix size:: Plattenverbrauch profilieren.
225 * Aufruf von guix graph:: Den Paketgraphen visualisieren.
226 * Aufruf von guix environment:: Entwicklungsumgebungen einrichten.
227 * Aufruf von guix publish:: Substitute teilen.
228 * Aufruf von guix challenge:: Die Substitut-Server anfechten.
229 * Aufruf von guix copy:: Mit einem entfernten Store Dateien austauschen.
230 * Aufruf von guix container:: Prozesse isolieren.
231 * Aufruf von guix weather:: Die Verfügbarkeit von Substituten
233 * Invoking guix processes:: Listing client processes.
235 Aufruf von @command{guix build}
239 * Gemeinsame Erstellungsoptionen:: Erstellungsoptionen für die meisten
241 * Paketumwandlungsoptionen:: Varianten von Paketen erzeugen.
242 * Zusätzliche Erstellungsoptionen:: Optionen spezifisch für »guix
244 * Fehlschläge beim Erstellen untersuchen:: Praxiserfahrung bei der
251 * Systeminstallation:: Das ganze Betriebssystem installieren.
252 * Systemkonfiguration:: Das Betriebssystem konfigurieren.
253 * Dokumentation:: Wie man Nutzerhandbücher von Software liest.
254 * Dateien zur Fehlersuche installieren:: Womit man seinen Debugger
256 * Sicherheitsaktualisierungen:: Sicherheits-Patches schnell einspielen.
257 * Paketmodule:: Pakete aus Sicht des Programmierers.
258 * Paketrichtlinien:: Die Distribution wachsen lassen.
259 * Bootstrapping:: GNU/Linux von Grund auf selbst erstellen.
260 * Portierung:: Guix auf andere Plattformen und Kernels
267 * Einschränkungen:: Was Sie erwarten dürfen.
268 * Hardware-Überlegungen:: Unterstützte Hardware.
269 * Installation von USB-Stick oder DVD:: Das Installationsmedium
271 * Vor der Installation:: Netzwerkanbindung, Partitionierung etc.
272 * Fortfahren mit der Installation:: Die Hauptsache.
273 * GuixSD in einer VM installieren:: Ein GuixSD-Spielplatz.
274 * Ein Abbild zur Installation erstellen:: Wie ein solches entsteht.
280 * Das Konfigurationssystem nutzen:: Ihr GNU-System anpassen.
281 * „operating-system“-Referenz:: Details der
282 Betriebssystem-Deklarationen.
283 * Dateisysteme:: Die Dateisystemeinbindungen konfigurieren.
284 * Abgebildete Geräte:: Näheres zu blockorientierten Speichermedien.
285 * Benutzerkonten:: Benutzerkonten festlegen.
286 * Locales:: Sprache und kulturelle Konventionen.
287 * Dienste:: Systemdienste festlegen.
288 * Setuid-Programme:: Mit Administratorrechten startende Programme.
289 * X.509-Zertifikate:: HTTPS-Server authentifizieren.
290 * Name Service Switch:: Den Name Service Switch von libc konfigurieren.
291 * Initiale RAM-Disk:: Linux-libre hochfahren.
292 * Bootloader-Konfiguration:: Den Bootloader konfigurieren.
293 * Aufruf von guix system:: Instanzierung einer Systemkonfiguration.
294 * GuixSD in einer VM starten:: Wie man GuixSD in einer virtuellen Maschine
296 * Dienste definieren:: Neue Dienstdefinitionen hinzufügen.
302 * Basisdienste:: Essenzielle Systemdienste.
303 * Geplante Auftragsausführung:: Der mcron-Dienst.
304 * Log-Rotation:: Der rottlog-Dienst.
305 * Netzwerkdienste:: Netzwerkeinrichtung, SSH-Daemon etc.
306 * X Window:: Graphische Anzeige.
307 * Druckdienste:: Unterstützung für lokale und entfernte
309 * Desktop-Dienste:: D-Bus- und Desktop-Dienste.
310 * Sound Services:: ALSA and Pulseaudio services.
311 * Datenbankdienste:: SQL-Datenbanken, Schlüssel-Wert-Speicher etc.
312 * Mail-Dienste:: IMAP, POP3, SMTP und so weiter.
313 * Kurznachrichtendienste:: Dienste für Kurznachrichten.
314 * Telefondienste:: Telefoniedienste.
315 * Überwachungsdienste:: Dienste zur Systemüberwachung.
316 * Kerberos-Dienste:: Kerberos-Dienste.
317 * Web-Dienste:: Web-Server.
318 * Zertifikatsdienste:: TLS-Zertifikate via Let’s Encrypt.
319 * DNS-Dienste:: DNS-Daemons.
320 * VPN-Dienste:: VPN-Daemons.
321 * Network File System:: Dienste mit Bezug zum Netzwerkdateisystem.
322 * Kontinuierliche Integration:: Der Cuirass-Dienst.
323 * Power Management Services:: Extending battery life.
324 * Audio-Dienste:: Der MPD.
325 * Virtualisierungsdienste:: Dienste für virtuelle Maschinen.
326 * Versionskontrolldienste:: Entfernten Zugang zu Git-Repositorys bieten.
327 * Spieldienste:: Spielserver.
328 * Verschiedene Dienste:: Andere Dienste.
334 * Dienstkompositionen:: Wie Dienste zusammengestellt werden.
335 * Diensttypen und Dienste:: Typen und Dienste.
336 * Service-Referenz:: Referenz zur Programmierschnittstelle.
337 * Shepherd-Dienste:: Eine spezielle Art von Dienst.
343 * Software-Freiheit:: Was in die Distribution aufgenommen werden
345 * Paketbenennung:: Was macht einen Namen aus?
346 * Versionsnummern:: Wenn der Name noch nicht genug ist.
347 * Zusammenfassungen und Beschreibungen:: Den Nutzern helfen, das richtige
349 * Python-Module:: Ein Touch britischer Comedy.
350 * Perl-Module:: Kleine Perlen.
351 * Java-Pakete:: Kaffeepause.
352 * Schriftarten:: Schriften verschriftlicht.
358 * Erstellung aus dem Git:: Das Neueste und Beste.
359 * Guix vor der Installation ausführen:: Hacker-Tricks.
360 * Perfekt eingerichtet:: Die richtigen Werkzeuge.
361 * Code-Stil:: Wie Mitwirkende hygienisch arbeiten.
362 * Einreichen von Patches:: Teilen Sie Ihre Arbeit.
368 * Programmierparadigmen:: Wie Sie Ihre Elemente zusammenstellen.
369 * Module:: Wo Sie Ihren Code unterbringen.
370 * Datentypen und Mustervergleich:: Implementierung von Datenstrukturen.
371 * Formatierung von Code:: Schreibkonventionen.
376 @c *********************************************************************
381 GNU Guix@footnote{»Guix« wird wie »geeks« ausgesprochen, also als »ɡiːks« in
382 der Notation des Internationalen Phonetischen Alphabets (IPA).} ist ein
383 Werkzeug zur Paketverwaltung für das GNU-System. Guix macht es
384 unprivilegierten Nutzern leicht, Pakete zu installieren, zu aktualisieren
385 oder zu entfernen, zu einem vorherigen Satz von Paketen zurückzuwechseln,
386 Pakete aus ihrem Quellcode heraus zu erstellen und hilft allgemein bei der
387 Schöpfung und Wartung von Software-Umgebungen.
389 @cindex Benutzeroberflächen
390 Guix bietet eine befehlszeilenbasierte Paketverwaltungsschnittstelle
391 (@pxref{Aufruf von guix package}), einen Satz Befehlszeilenwerkzeuge
392 (@pxref{Zubehör}) sowie Schnittstellen zur Programmierung in Scheme
393 (@pxref{Programmierschnittstelle}).
394 @cindex Erstellungs-Daemon
395 Der @dfn{Erstellungs-Daemon} ist für das Erstellen von Paketen im Auftrag
396 von Nutzern verantwortlich (@pxref{Den Daemon einrichten}) und für das
397 Herunterladen vorerstellter Binärdateien aus autorisierten Quellen
398 (@pxref{Substitute}).
400 @cindex Erweiterbarkeit der Distribution
401 @cindex Anpassung, von Paketen
402 Guix enthält Paketdefinitionen für viele Pakete, von GNU und nicht von GNU,
403 die alle @uref{https://www.gnu.org/philosophy/free-sw.html, die Freiheit des
404 Computernutzers respektieren}. Es ist @emph{erweiterbar}: Nutzer können ihre
405 eigenen Paketdefinitionen schreiben (@pxref{Pakete definieren}) und sie als
406 unabhängige Paketmodule verfügbar machen (@pxref{Paketmodule}). Es ist
407 auch @emph{anpassbar}: Nutzer können spezialisierte Paketdefinitionen aus
408 bestehenden @emph{ableiten}, auch von der Befehlszeile (@pxref{Paketumwandlungsoptionen}).
410 @cindex Guix System Distribution
412 Sie können GNU@tie{}Guix auf ein bestehendes GNU/Linux-System aufsetzen, wo
413 es die bereits verfügbaren Werkzeuge ergänzt, ohne zu stören
414 (@pxref{Installation}), oder Sie können es eigenständig als Teil der
415 @dfn{Guix System Distribution}, kurz GuixSD (@pxref{GNU-Distribution}),
416 verwenden. Mit GNU@tie{}GuixSD @emph{deklarieren} Sie alle Aspekte der
417 Betriebssystemkonfiguration und Guix kümmert sich darum, die Konfiguration
418 auf transaktionsbasierte, reproduzierbare und zustandslose Weise zu
419 instanzieren (@pxref{Systemkonfiguration}).
421 @cindex funktionale Paketverwaltung
423 Intern implementiert Guix die Disziplin der @dfn{funktionalen
424 Paketverwaltung}, zu der Nix schon die Pionierarbeit geleistet hat
425 (@pxref{Danksagungen}). In Guix wird der Prozess, ein Paket zu erstellen
426 und zu installieren, als eine @emph{Funktion} im mathematischen Sinn
427 aufgefasst. Diese Funktion hat Eingaben, wie zum Beispiel
428 Erstellungs-Skripts, einen Compiler und Bibliotheken, und liefert ein
429 installiertes Paket. Als eine reine Funktion hängt sein Ergebnis allein von
430 seinen Eingaben ab — zum Beispiel kann er nicht auf Software oder Skripts
431 Bezug nehmen, die nicht ausdrücklich als Eingaben übergeben wurden. Eine
432 Erstellungsfunktion führt immer zum selben Ergebnis, wenn ihr die gleiche
433 Menge an Eingaben übergeben wurde. Sie kann die Umgebung des laufenden
434 Systems auf keine Weise beeinflussen, zum Beispiel kann sie keine Dateien
435 außerhalb ihrer Erstellungs- und Installationsverzeichnisse verändern. Um
436 dies zu erreichen, laufen Erstellungsprozesse in isolieren Umgebungen
437 (sogenannte @dfn{Container}), wo nur ausdrückliche Eingaben sichtbar sind.
440 Das Ergebnis von Paketerstellungsfunktionen wird im Dateisystem
441 @dfn{zwischengespeichert} in einem besonderen Verzeichnis, was als @dfn{der
442 Store} bezeichnet wird (@pxref{Der Store}). Jedes Paket wird in sein eigenes
443 Verzeichnis im Store installiert — standardmäßig ist er unter
444 @file{/gnu/store} zu finden. Der Verzeichnisname enthält einen Hash aller
445 Eingaben, anhand derer das Paket erzeugt wurde, somit hat das Ändern einer
446 Eingabe einen völlig anderen Verzeichnisnamen zur Folge.
448 Dieses Vorgehen ist die Grundlage für die Guix auszeichnenden
449 Funktionalitäten: Unterstützung transaktionsbasierter Paketaktualisierungen
450 und -rückstufungen, Installation von Paketen als einfacher Nutzer sowie
451 Garbage Collection für Pakete (@pxref{Funktionalitäten}).
454 @c *********************************************************************
456 @chapter Installation
458 @cindex Guix installieren
459 @cindex official website
460 GNU Guix kann von seiner Webseite unter
461 @url{http://www.gnu.org/software/guix/} heruntergeladen werden. Dieser
462 Abschnitt beschreibt die Software-Voraussetzungen von Guix und wie man es
463 installiert, so dass man es benutzen kann.
465 Beachten Sie, dass es in diesem Abschnitt um die Installation des
466 Paketverwaltungswerkzeugs geht, welche auf einem laufenden GNU/Linux-System
467 vollzogen werden kann. Falls Sie stattdessen das vollständige
468 GNU-Betriebssystem installieren möchten, werfen Sie einen Blick in den
469 Abschnitt @pxref{Systeminstallation}.
471 @cindex Fremddistribution
472 @cindex directories related to foreign distro
474 Wenn es auf ein bestehendes GNU/Linux-System installiert wird — im Folgenden
475 als @dfn{Fremddistribution} bezeichnet —, ergänzt GNU@tie{}Guix die
476 verfügbaren Werkzeuge, ohne dass sie sich gegenseitig stören. Guix’ Daten
477 befinden sich ausschließlich in zwei Verzeichnissen, üblicherweise
478 @file{/gnu/store} und @file{/var/guix}; andere Dateien auf Ihrem System wie
479 @file{/etc} bleiben unberührt.
481 Sobald es installiert ist, kann Guix durch Ausführen von @command{guix pull}
482 aktualisiert werden (@pxref{Aufruf von guix pull}).
485 * Aus Binärdatei installieren:: Guix installieren, ohne Zeit zu verlieren!
486 * Voraussetzungen:: Zum Erstellen und Benutzen von Guix nötige
488 * Die Testsuite laufen lassen:: Guix testen.
489 * Den Daemon einrichten:: Wie man die Umgebung des Erstellungs-Daemons
491 * Aufruf des guix-daemon:: Den Erstellungs-Daemon laufen lassen.
492 * Anwendungen einrichten:: Anwendungsspezifische Einstellungen.
495 @node Aus Binärdatei installieren
496 @section Aus Binärdatei installieren
498 @cindex Guix aus Binärdateien installieren
499 @cindex installer script
500 Dieser Abschnitt beschreibt, wie sich Guix auf einem beliebigen System aus
501 einem alle Komponenten umfassenden Tarball installieren lässt, der
502 Binärdateien für Guix und all seine Abhängigkeiten liefert. Dies geht in der
503 Regel schneller, als Guix aus seinen Quelldateien zu installieren, was in
504 den nächsten Abschnitten beschrieben wird. Vorausgesetzt wird hier
505 lediglich, dass GNU@tie{}tar und Xz verfügbar sind.
508 @uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh,
509 Installations-Skript für die Shell}, welches Guix automatisch herunterlädt,
510 installiert und eine erste Konfiguration von Guix mit sich bringt. Es sollte
511 als der Administratornutzer (als »root«) ausgeführt werden.
513 Die Installation läuft so ab:
517 @cindex Guix-Binärdatei herunterladen
518 Download the binary tarball from
519 @indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz},
520 where @var{system} is @code{x86_64-linux} for an @code{x86_64} machine
521 already running the kernel Linux, and so on.
523 @c The following is somewhat duplicated in ``System Installation''.
524 Achten Sie darauf, auch die zugehörige @file{.sig}-Datei herunterzuladen und
525 verifizieren Sie damit die Authentizität des Tarballs, ungefähr so:
528 $ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
529 $ gpg --verify guix-binary-@value{VERSION}.@var{system}.tar.xz.sig
532 Falls dieser Befehl fehlschlägt, weil Sie nicht über den nötigen
533 öffentlichen Schlüssel verfügen, können Sie ihn mit diesem Befehl
537 $ gpg --keyserver @value{KEY-SERVER} \
538 --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
542 @c end authentication part
543 und den Befehl @code{gpg --verify} erneut ausführen.
546 Nun müssen Sie zum Administratornutzer @code{root} wechseln. Abhängig von
547 Ihrer Distribution müssen Sie dazu etwa @code{su -} oder @code{sudo -i}
548 ausführen. Danach führen Sie als @code{root}-Nutzer aus:
552 # tar --warning=no-timestamp -xf \
553 guix-binary-@value{VERSION}.@var{system}.tar.xz
554 # mv var/guix /var/ && mv gnu /
557 Dadurch wird @file{/gnu/store} (@pxref{Der Store}) und @file{/var/guix}
558 erzeugt. Letzteres enthält ein fertiges Guix-Profil für den
559 Administratornutzer @code{root} (wie im nächsten Schritt beschrieben).
561 Entpacken Sie den Tarball @emph{nicht} auf einem schon funktionierenden
562 Guix-System, denn es würde seine eigenen essenziellen Dateien überschreiben.
564 Die Befehlszeilenoption @code{--warning=no-timestamp} stellt sicher, dass
565 GNU@tie{}tar nicht vor »unplausibel alten Zeitstempeln« warnt (solche
566 Warnungen traten bei GNU@tie{}tar 1.26 und älter auf, neue Versionen machen
567 keine Probleme). Sie treten auf, weil alle Dateien im Archiv als
568 Änderungszeitpunkt null eingetragen bekommen haben (das bezeichnet den
569 1. Januar 1970). Das ist Absicht, damit der Inhalt des Archivs nicht davon
570 abhängt, wann es erstellt wurde, und es somit reproduzierbar wird.
573 Make the profile available under @file{~root/.config/guix/current}, which is
574 where @command{guix pull} will install updates (@pxref{Aufruf von guix pull}):
577 # mkdir -p ~root/.config/guix
578 # ln -sf /var/guix/profiles/per-user/root/current-guix \
579 ~root/.config/guix/current
582 »Sourcen« Sie @file{etc/profile}, um @code{PATH} und andere relevante
583 Umgebungsvariable zu ergänzen:
586 # GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
587 source $GUIX_PROFILE/etc/profile
591 Erzeugen Sie Nutzergruppe und Nutzerkonten für die Erstellungs-Benutzer wie
592 folgt (@pxref{Einrichten der Erstellungsumgebung}).
595 Führen Sie den Daemon aus, und lassen Sie ihn automatisch bei jedem
598 Wenn Ihre Wirts-Distribution systemd als »init«-System verwendet, können Sie
599 das mit folgenden Befehlen veranlassen:
601 @c Versions of systemd that supported symlinked service files are not
602 @c yet widely deployed, so we should suggest that users copy the service
605 @c See this thread for more information:
606 @c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html
609 # cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
611 # systemctl start guix-daemon && systemctl enable guix-daemon
614 Wenn Ihre Wirts-Distribution als »init«-System Upstart verwendet:
617 # initctl reload-configuration
618 # cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
623 Andernfalls können Sie den Daemon immer noch manuell starten, mit:
626 # ~root/.config/guix/current/bin/guix-daemon \
627 --build-users-group=guixbuild
631 Stellen Sie den @command{guix}-Befehl auch anderen Nutzern Ihrer Maschine
632 zur Verfügung, zum Beispiel so:
635 # mkdir -p /usr/local/bin
637 # ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix
640 Es ist auch eine gute Idee, die Info-Version dieses Handbuchs ebenso
644 # mkdir -p /usr/local/share/info
645 # cd /usr/local/share/info
646 # for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
650 Auf diese Art wird, unter der Annahme, dass bei Ihnen
651 @file{/usr/local/share/info} im Suchpfad eingetragen ist, das Ausführen von
652 @command{info guix} dieses Handbuch öffnen (@pxref{Other Info Directories,,,
653 texinfo, GNU Texinfo} hat weitere Details, wie Sie den Info-Suchpfad ändern
657 @cindex Substitute, deren Autorisierung
658 Um Substitute von @code{hydra.gnu.org} oder einem Spiegelserver davon zu
659 benutzen (@pxref{Substitute}), müssen sie erst autorisiert werden:
662 # guix archive --authorize < \
663 ~root/.config/guix/current/share/guix/hydra.gnu.org.pub
667 Alle Nutzer müssen womöglich ein paar zusätzliche Schritte ausführen, damit
668 ihre Guix-Umgebung genutzt werden kann, siehe @pxref{Anwendungen einrichten}.
671 Voilà, die Installation ist fertig!
673 Sie können nachprüfen, dass Guix funktioniert, indem Sie ein Beispielpaket
674 in das root-Profil installieren:
677 # guix package -i hello
680 The @code{guix} package must remain available in @code{root}'s profile, or
681 it would become subject to garbage collection---in which case you would find
682 yourself badly handicapped by the lack of the @command{guix} command. In
683 other words, do not remove @code{guix} by running @code{guix package -r
686 Der Tarball zur Installation aus einer Binärdatei kann einfach durch
687 Ausführung des folgenden Befehls im Guix-Quellbaum (re-)produziert und
691 make guix-binary.@var{system}.tar.xz
695 ...@: which, in turn, runs:
698 guix pack -s @var{system} --localstatedir \
699 --profile-name=current-guix guix
702 Siehe @xref{Aufruf von guix pack} für weitere Informationen zu diesem
703 praktischen Werkzeug.
705 @node Voraussetzungen
706 @section Voraussetzungen
708 Dieser Abschnitt listet Voraussetzungen auf, um Guix aus seinem Quellcode zu
709 erstellen. Der Erstellungsprozess für Guix ist derselbe wie für andere
710 GNU-Software und wird hier nicht beschrieben. Bitte lesen Sie die Dateien
711 @file{README} und @file{INSTALL} im Guix-Quellbaum, um weitere Details zu
714 GNU Guix hat folgende Pakete als Abhängigkeiten:
717 @item @url{http://gnu.org/software/guile/, GNU Guile}, Version 2.0.13 oder
718 neuer, einschließlich 2.2.x,
719 @item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, version
722 @uref{http://gnutls.org/, GnuTLS}, im Speziellen dessen Bindungen für Guile
723 (@pxref{Guile Preparations, how to install the GnuTLS bindings for Guile,,
724 gnutls-guile, GnuTLS-Guile}),
726 @uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3},
727 version 0.1.0 or later;
729 @c FIXME: Specify a version number once a release has been made.
730 @uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, vom August 2017
732 @item @url{http://zlib.net, zlib},
733 @item @url{http://www.gnu.org/software/make/, GNU Make}.
736 Folgende Abhängigkeiten sind optional:
740 Wenn Sie @url{http://savannah.nongnu.org/projects/guile-json/, Guile-JSON}
741 installieren, können Sie den Befehl @command{guix import pypi} benutzen
742 (@pxref{Aufruf von guix import}). Das spielt hauptsächlich für Entwickler und
743 nicht für Gelegenheitsnutzer eine Rolle.
746 @c Note: We need at least 0.10.2 for 'channel-send-eof'.
747 Unterstützung für das Auslagern von Erstellungen (@pxref{Auslagern des Daemons einrichten}) und @command{guix copy} (@pxref{Aufruf von guix copy}) hängt von
748 @uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, Version
749 0.10.2 oder neuer, ab.
752 Wenn @url{http://www.bzip.org, libbz2} verfügbar ist, kann
753 @command{guix-daemon} damit Erstellungsprotokolle komprimieren.
756 Sofern nicht @code{--disable-daemon} beim Aufruf von @command{configure}
757 übergeben wurde, benötigen Sie auch folgende Pakete:
760 @item @url{http://gnupg.org/, GNU libgcrypt},
761 @item @url{http://sqlite.org, SQLite 3},
762 @item @url{http://gcc.gnu.org, GCC's g++} mit Unterstützung für den
766 @cindex Zustandsverzeichnis
767 Sollten Sie Guix auf einem System konfigurieren, auf dem Guix bereits
768 installiert ist, dann stellen Sie sicher, dasselbe Zustandsverzeichnis wie
769 für die bestehende Installation zu verwenden. Benutzen Sie dazu die
770 Befehlszeilenoption @code{--localstatedir} des @command{configure}-Skripts
771 (@pxref{Directory Variables, @code{localstatedir},, standards, GNU Coding
772 Standards}). Das @command{configure}-Skript schützt vor ungewollter
773 Fehlkonfiguration der @var{localstatedir}, damit sie nicht versehentlich
774 Ihren Store verfälschen (@pxref{Der Store}).
776 @cindex Nix, Kompatibilität
777 Wenn eine funktionierende Installation of @url{http://nixos.org/nix/, the
778 Nix package manager} verfügbar ist, können Sie Guix stattdessen mit
779 @code{--disable-daemon} konfigurieren. In diesem Fall ersetzt Nix die drei
780 oben genannten Abhängigkeiten.
782 Guix ist mit Nix kompatibel, daher ist es möglich, denselben Store für beide
783 zu verwenden. Dazu müssen Sie an @command{configure} nicht nur denselben
784 Wert für @code{--with-store-dir} übergeben, sondern auch denselben Wert für
785 @code{--localstatedir}. Letzterer ist deswegen essenziell, weil er unter
786 Anderem angibt, wo die Datenbank liegt, in der sich die Metainformationen
787 über den Store befinden. Für Nix sind die Werte standardmäßig
788 @code{--with-store-dir=/nix/store} und
789 @code{--localstatedir=/nix/var}. Beachten Sie, dass @code{--disable-daemon}
790 nicht erforderlich ist, wenn Sie die Absicht haben, den Store mit Nix zu
793 @node Die Testsuite laufen lassen
794 @section Die Testsuite laufen lassen
797 Nachdem @command{configure} und @code{make} erfolgreich durchgelaufen sind,
798 ist es ratsam, den Testkatalog auszuführen. Er kann dabei helfen, Probleme
799 mit der Einrichtung oder Systemumgebung zu finden, oder auch Probleme in
800 Guix selbst — und Testfehler zu melden ist eine wirklich gute Art und Weise,
801 bei der Verbesserung von Guix mitzuhelfen. Um den Testkatalog auszuführen,
802 geben Sie Folgendes ein:
808 Testfälle können parallel ausgeführt werden. Sie können die
809 Befehlszeiltenoption @code{-j} von GNU@tie{}make benutzen, damit es
810 schneller geht. Der erste Durchlauf kann auf neuen Maschinen ein paar
811 Minuten dauern, nachfolgende Ausführungen werden schneller sein, weil der
812 für die Tests erstellte Store schon einige Dinge zwischengespeichert haben
815 Es ist auch möglich, eine Teilmenge der Tests laufen zu lassen, indem Sie
816 die @code{TESTS}-Variable des Makefiles ähnlich wie in diesem Beispiel
820 make check TESTS="tests/store.scm tests/cpio.scm"
823 Standardmäßig werden Testergebnisse pro Datei angezeigt. Um die Details
824 jedes einzelnen Testfalls zu sehen, können Sie wie in diesem Beispiel die
825 @code{SCM_LOG_DRIVER_FLAGS}-Variable des Makefiles definieren:
828 make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"
831 Kommt es zum Fehlschlag, senden Sie bitte eine E-Mail an
832 @email{bug-guix@@gnu.org} und fügen Sie die Datei @file{test-suite.log} als
833 Anhang bei. Bitte geben Sie dabei in Ihrer Nachricht die benutzte Version
834 von Guix an sowie die Versionsnummern der Abhängigkeiten
835 (@pxref{Voraussetzungen}).
837 Guix wird auch mit einem Testkatalog für das ganze System ausgeliefert, der
838 vollständige Instanzen des GuixSD-Betriebssystems testet. Er kann nur auf
839 Systemen benutzt werden, auf denen Guix bereits installiert ist, mit
847 Oder, auch hier, indem Sie @code{TESTS} definieren, um eine Teilmenge der
848 auszuführenden Tests anzugeben:
851 make check-system TESTS="basic mcron"
854 Diese Systemtests sind in den @code{(gnu tests @dots{})}-Modulen
855 definiert. Sie funktionieren, indem Sie das getestete Betriebssystem mitsamt
856 schlichter Instrumentierung in einer virtuellen Maschine (VM) ausführen. Die
857 Tests können aufwendige Berechnungen durchführen oder sie günstig umgehen,
858 je nachdem, ob für ihre Abhängigkeiten Substitute zur Verfügung stehen
859 (@pxref{Substitute}). Manche von ihnen nehmen viel Speicherplatz in
860 Anspruch, um die VM-Abbilder zu speichern.
862 Auch hier gilt: Falls Testfehler auftreten, senden Sie bitte alle Details an
863 @email{bug-guix@@gnu.org}.
865 @node Den Daemon einrichten
866 @section Den Daemon einrichten
869 Operationen wie das Erstellen eines Pakets oder Laufenlassen des
870 Müllsammlers werden alle durch einen spezialisierten Prozess durchgeführt,
871 den @dfn{Erstellungs-Daemon}, im Auftrag seiner Kunden (den Clients). Nur
872 der Daemon darf auf den Store und seine zugehörige Datenbank
873 zugreifen. Daher wird jede den Store verändernde Operation durch den Daemon
874 durchgeführt. Zum Beispiel kommunizieren Befehlszeilenwerkzeuge wie
875 @command{guix package} und @command{guix build} mit dem Daemon (mittels
876 entfernter Prozeduraufrufe), um ihm Anweisungen zu geben, was er tun soll.
878 Folgende Abschnitte beschreiben, wie Sie die Umgebung des
879 Erstellungs-Daemons ausstatten sollten. Siehe auch @ref{Substitute} für
880 Informationen darüber, wie Sie es dem Daemon ermöglichen, vorerstellte
881 Binärdateien herunterzuladen.
884 * Einrichten der Erstellungsumgebung:: Die isolierte Umgebung zum Erstellen
886 * Auslagern des Daemons einrichten:: Erstellungen auf entfernte Maschinen
888 * SELinux-Unterstützung:: Wie man eine SELinux-Richtlinie für den Daemon
892 @node Einrichten der Erstellungsumgebung
893 @subsection Einrichten der Erstellungsumgebung
895 @cindex Erstellungsumgebung
896 In einem normalen Mehrbenutzersystem werden Guix und sein Daemon — das
897 Programm @command{guix-daemon} — vom Systemadministrator installiert;
898 @file{/gnu/store} gehört @code{root} und @command{guix-daemon} läuft als
899 @code{root}. Nicht mit erweiterten Rechten ausgestattete Nutzer können
900 Guix-Werkzeuge benutzen, um Pakete zu erstellen oder anderweitig auf den
901 Store zuzugreifen, und der Daemon wird dies für sie erledigen und dabei
902 sicherstellen, dass der Store in einem konsistenten Zustand verbleibt und
903 sich die Nutzer erstellte Pakete teilen.
905 @cindex Erstellungsbenutzer
906 Wenn @command{guix-daemon} als Administratornutzer @code{root} läuft, wollen
907 Sie aber vielleicht dennoch nicht, dass Paketerstellungsprozesse auch als
908 @code{root} ablaufen, aus offensichtlichen Sicherheitsgründen. Um dies zu
909 vermeiden, sollte ein besonderer Pool aus @dfn{Erstellungsbenutzern}
910 geschaffen werden, damit vom Daemon gestartete Erstellungsprozesse ihn
911 benutzen. Diese Erstellungsbenutzer müssen weder eine Shell noch einen
912 Persönlichen Ordner zugewiesen bekommen, sie werden lediglich benutzt, wenn
913 der Daemon @code{root}-Rechte in Erstellungsprozessen ablegt. Mehrere solche
914 Benutzer zu haben, ermöglicht es dem Daemon, verschiedene
915 Erstellungsprozessen unter verschiedenen Benutzeridentifikatoren (UIDs) zu
916 starten, was garantiert, dass sie einander nicht stören — eine essenzielle
917 Funktionalität, da Erstellungen als reine Funktionen angesehen werden
918 (@pxref{Einführung}).
920 Auf einem GNU/Linux-System kann ein Pool von Erstellungsbenutzern wie folgt
921 erzeugt werden (mit Bash-Syntax und den Befehlen von @code{shadow}):
923 @c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html
924 @c for why `-G' is needed.
926 # groupadd --system guixbuild
927 # for i in `seq -w 1 10`;
929 useradd -g guixbuild -G guixbuild \
930 -d /var/empty -s `which nologin` \
931 -c "Guix-Erstellungsbenutzer $i" --system \
937 Die Anzahl der Erstellungsbenutzer entscheidet, wieviele Erstellungsaufträge
938 parallel ausgeführt werden können, wie es mit der Befehlszeilenoption
939 @option{--max-jobs} vorgegeben werden kann (@pxref{Aufruf des guix-daemon,
940 @option{--max-jobs}}). Um @command{guix system vm} und ähnliche Befehle
941 nutzen zu können, müssen Sie die Erstellungsbenutzer unter Umständen zur
942 @code{kvm}-Benutzergruppe hinzufügen, damit sie Zugriff auf @file{/dev/kvm}
943 haben, mit @code{-G guixbuild,kvm} statt @code{-G guixbuild}
944 (@pxref{Aufruf von guix system}).
946 Das Programm @code{guix-daemon} kann mit dem folgenden Befehl als
947 @code{root} gestartet werden@footnote{Wenn Ihre Maschine systemd als
948 »init«-System verwendet, genügt es, die Datei
949 @file{@var{prefix}/lib/systemd/system/guix-daemon.service} in
950 @file{/etc/systemd/system} zu platzieren, damit @command{guix-daemon}
951 automatisch gestartet wird. Ebenso können Sie, wenn Ihre Maschine Upstart
952 als »init«-System benutzt, die Datei
953 @file{@var{prefix}/lib/upstart/system/guix-daemon.conf} in @file{/etc/init}
957 # guix-daemon --build-users-group=guixbuild
962 Auf diese Weise startet der Daemon Erstellungsprozesse in einem chroot als
963 einer der @code{guixbuilder}-Benutzer. Auf GNU/Linux enthält die
964 chroot-Umgebung standardmäßig nichts außer:
966 @c Keep this list in sync with libstore/build.cc! -----------------------
969 einem minimalen @code{/dev}-Verzeichnis, was größtenteils vom @code{/dev}
970 des Wirtssystems unabhängig erstellt wurde@footnote{»Größtenteils«, denn
971 obwohl die Menge an Dateien, die im @code{/dev} des chroots vorkommen, fest
972 ist, können die meisten dieser Dateien nur dann erstellt werden, wenn das
973 Wirtssystem sie auch hat.},
976 dem @code{/proc}-Verzeichnis, es zeigt nur die Prozesse des Containers, weil
977 ein separater Namensraum für Prozess-IDs (PIDs) benutzt wird,
980 @file{/etc/passwd} mit einem Eintrag für den aktuellen Benutzer und einem
981 Eintrag für den Benutzer @file{nobody},
984 @file{/etc/group} mit einem Eintrag für die Gruppe des Benutzers,
987 @file{/etc/hosts} mit einem Eintrag, der @code{localhost} auf
988 @code{127.0.0.1} abbildet,
991 einem @file{/tmp}-Verzeichnis mit Schreibrechten.
994 Sie können beeinflussen, in welchem Verzeichnis der Daemon Erstellungsbäume
995 unterbringt, indem sie den Wert der Umgebungsvariablen @code{TMPDIR}
996 ändern. Allerdings heißt innerhalb des chroots der Erstellungsbaum immer
997 @file{/tmp/guix-build-@var{name}.drv-0}, wobei @var{name} der Ableitungsname
998 ist — z.B. @code{coreutils-8.24}. Dadurch hat der Wert von @code{TMPDIR}
999 keinen Einfluss auf die Erstellungsumgebung, wodurch Unterschiede vermieden
1000 werden, falls Erstellungsprozesse den Namen ihres Erstellungsbaumes
1004 Der Daemon befolgt außerdem den Wert der Umgebungsvariablen
1005 @code{http_proxy} für von ihm durchgeführte HTTP-Downloads, sei es für
1006 Ableitungen mit fester Ausgabe (@pxref{Ableitungen}) oder für Substitute
1007 (@pxref{Substitute}).
1009 Wenn Sie Guix als ein Benutzer ohne erweiterte Rechte installieren, ist es
1010 dennoch möglich, @command{guix-daemon} auszuführen, sofern Sie
1011 @code{--disable-chroot} übergeben. Allerdings können Erstellungsprozesse
1012 dann nicht voneinander und vom Rest des Systems isoliert werden. Daher
1013 können sich Erstellungsprozesse gegenseitig stören und auf Programme,
1014 Bibliotheken und andere Dateien zugreifen, die dem restlichen System zur
1015 Verfügung stehen — was es deutlich schwerer macht, sie als @emph{reine}
1016 Funktionen aufzufassen.
1019 @node Auslagern des Daemons einrichten
1020 @subsection Nutzung der Auslagerungsfunktionalität
1024 Wenn erwünscht kann der Erstellungs-Daemon Ableitungserstellungen
1025 @dfn{auslagern} auf andere Maschinen, auf denen Guix läuft, mit Hilfe des
1026 @code{offload}-»@dfn{Build-Hooks}«@footnote{Diese Funktionalität ist nur
1027 verfügbar, wenn @uref{https://github.com/artyom-poptsov/guile-ssh,
1028 Guile-SSH} vorhanden ist.}. Wenn diese Funktionalität aktiviert ist, wird
1029 eine nutzerspezifizierte Liste von Erstellungsmaschinen aus
1030 @file{/etc/guix/machines.scm} gelesen. Wann immer eine Erstellung angefragt
1031 wird, zum Beispiel durch @code{guix build}, versucht der Daemon, sie an eine
1032 der Erstellungsmaschinen auszulagern, die die Einschränkungen der Ableitung
1033 erfüllen, insbesondere ihren Systemtyp — z.B. @file{x86_64-linux}. Fehlende
1034 Voraussetzungen für die Erstellung werden über SSH auf die Zielmaschine
1035 kopiert, welche dann mit der Erstellung weitermacht. Hat sie Erfolg damit,
1036 so werden die Ausgabe oder Ausgaben der Erstellung zurück auf die
1037 ursprüngliche Maschine kopiert.
1039 Die Datei @file{/etc/guix/machines.scm} sieht normalerweise so aus:
1042 (list (build-machine
1043 (name "eightysix.example.org")
1044 (system "x86_64-linux")
1045 (host-key "ssh-ed25519 AAAAC3Nza@dots{}")
1047 (speed 2.)) ;unglaublich schnell!
1050 (name "meeps.example.org")
1051 (system "mips64el-linux")
1052 (host-key "ssh-rsa AAAAB3Nza@dots{}")
1055 (string-append (getenv "HOME")
1056 "/.ssh/identität-für-guix"))))
1060 Im obigen Beispiel geben wir eine Liste mit zwei Erstellungsmaschinen vor,
1061 eine für die @code{x86_64}-Architektur und eine für die
1062 @code{mips64el}-Architektur.
1064 Tatsächlich ist diese Datei — wenig überraschend! — eine Scheme-Datei, die
1065 ausgewertet wird, wenn der @code{offload}-Hook gestartet wird. Der Wert, den
1066 sie zurückliefert, muss eine Liste von @code{build-machine}-Objekten
1067 sein. Obwohl dieses Beispiel eine feste Liste von Erstellungsmaschinen
1068 zeigt, könnte man auch auf die Idee kommen, etwa mit DNS-SD eine Liste
1069 möglicher im lokalen Netzwerk entdeckter Erstellungsmaschinen zu liefern
1070 (@pxref{Einführung, Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme
1071 Programs}). Der Datentyp @code{build-machine} wird im Folgenden weiter
1074 @deftp {Datentyp} build-machine
1075 Dieser Datentyp repräsentiert Erstellungsmaschinen, an die der Daemon
1076 Erstellungen auslagern darf. Die wichtigen Felder sind:
1081 Der Hostname der entfernten Maschine.
1084 Der Systemtyp der entfernten Maschine — z.B. @code{"x86_64-linux"}.
1087 Das Benutzerkonto, mit dem eine Verbindung zur entfernten Maschine über SSH
1088 aufgebaut werden soll. Beachten Sie, dass das SSH-Schlüsselpaar @emph{nicht}
1089 durch eine Passphrase geschützt sein darf, damit nicht-interaktive
1090 Anmeldungen möglich sind.
1093 Dies muss der @dfn{öffentliche SSH-Host-Schlüssel} der Maschine im
1094 OpenSSH-Format sein. Er wird benutzt, um die Identität der Maschine zu
1095 prüfen, wenn wir uns mit ihr verbinden. Er ist eine lange Zeichenkette, die
1096 ungefähr so aussieht:
1099 ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org
1102 Wenn auf der Maschine der OpenSSH-Daemon, @command{sshd}, läuft, ist der
1103 Host-Schlüssel in einer Datei wie @file{/etc/ssh/ssh_host_ed25519_key.pub}
1106 Wenn auf der Maschine der SSH-Daemon von GNU@tie{}lsh, nämlich
1107 @command{lshd}, läuft, befindet sich der Host-Schlüssel in
1108 @file{/etc/lsh/host-key.pub} oder einer ähnlichen Datei. Er kann ins
1109 OpenSSH-Format umgewandelt werden durch @command{lsh-export-key}
1110 (@pxref{Converting keys,,, lsh, LSH Manual}):
1113 $ lsh-export-key --openssh < /etc/lsh/host-key.pub
1114 ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{}
1119 Eine Reihe optionaler Felder kann festgelegt werden:
1123 @item @code{port} (Vorgabe: @code{22})
1124 Portnummer des SSH-Servers auf der Maschine.
1126 @item @code{private-key} (Vorgabe: @file{~root/.ssh/id_rsa})
1127 The SSH private key file to use when connecting to the machine, in OpenSSH
1128 format. This key must not be protected with a passphrase.
1130 Beachten Sie, dass als Vorgabewert der private Schlüssel @emph{des
1131 root-Benutzers} genommen wird. Vergewissern Sie sich, dass er existiert,
1132 wenn Sie die Standardeinstellung verwenden.
1134 @item @code{compression} (Vorgabe: @code{"zlib@@openssh.com,zlib"})
1135 @itemx @code{compression-level} (Vorgabe: @code{3})
1136 Die Kompressionsmethoden auf SSH-Ebene und das angefragte
1139 Beachten Sie, dass Auslagerungen SSH-Kompression benötigen, um beim
1140 Übertragen von Dateien an Erstellungsmaschinen und zurück weniger Bandbreite
1143 @item @code{daemon-socket} (Vorgabe: @code{"/var/guix/daemon-socket/socket"})
1144 Dateiname des Unix-Sockets, auf dem @command{guix-daemon} auf der Maschine
1147 @item @code{parallel-builds} (Vorgabe: @code{1})
1148 Die Anzahl der Erstellungen, die auf der Maschine parallel ausgeführt werden
1151 @item @code{speed} (Vorgabe: @code{1.0})
1152 Ein »relativer Geschwindigkeitsfaktor«. Der Auslagerungsplaner gibt
1153 tendenziell Maschinen mit höherem Geschwindigkeitsfaktor den Vorrang.
1155 @item @code{features} (Vorgabe: @code{'()})
1156 Eine Liste von Zeichenketten, die besondere von der Maschine unterstützte
1157 Funktionalitäten bezeichnen. Ein Beispiel ist @code{"kvm"} für Maschinen,
1158 die über die KVM-Linux-Module zusammen mit entsprechender
1159 Hardware-Unterstützung verfügen. Ableitungen können Funktionalitäten dem
1160 Namen nach anfragen und werden dann auf passenden Erstellungsmaschinen
1166 Der Befehl @code{guile} muss sich im Suchpfad der Erstellungsmaschinen
1167 befinden. Zusätzlich müssen die Guix-Module im @code{$GUILE_LOAD_PATH} auf
1168 den Erstellungsmaschinen zu finden sein — um dies nachzuprüfen, können Sie
1169 Folgendes ausführen:
1172 ssh build-machine guile -c "'(use-modules (guix config))'"
1175 Es gibt noch eine weitere Sache zu tun, sobald @file{machines.scm}
1176 eingerichtet ist. Wie zuvor erklärt, werden beim Auslagern Dateien zwischen
1177 den Stores der Maschinen hin- und hergeschickt. Damit das funktioniert,
1178 müssen Sie als Erstes ein Schlüsselpaar auf jeder Maschine erzeugen, damit
1179 der Daemon signierte Archive mit den Dateien aus dem Store versenden kann
1180 (@pxref{Aufruf von guix archive}):
1183 # guix archive --generate-key
1187 Jede Erstellungsmaschine muss den Schlüssel der Hauptmaschine autorisieren,
1188 damit diese Store-Objekte von der Hauptmaschine empfangen kann:
1191 # guix archive --authorize < öffentlicher-schlüssel-hauptmaschine.txt
1195 Andersherum muss auch die Hauptmaschine den jeweiligen Schlüssel jeder
1196 Erstellungsmaschine autorisieren.
1198 Der ganze Umstand mit den Schlüsseln soll ausdrücken, dass sich Haupt- und
1199 Erstellungsmaschinen paarweise gegenseitig vertrauen. Konkret kann der
1200 Erstellungs-Daemon auf der Hauptmaschine die Echtheit von den
1201 Erstellungsmaschinen empfangener Dateien gewährleisten (und umgekehrt), und
1202 auch dass sie nicht sabotiert wurden und mit einem autorisierten Schlüssel
1205 @cindex Auslagerung testen
1206 Um zu testen, ob Ihr System funktioniert, führen Sie diesen Befehl auf der
1213 Dadurch wird versucht, zu jeder Erstellungsmaschine eine Verbindung
1214 herzustellen, die in @file{/etc/guix/machines.scm} angegeben wurde,
1215 sichergestellt, dass auf jeder Guile und die Guix-Module nutzbar sind, und
1216 jeweils versucht, etwas auf die Erstellungsmaschine zu exportieren und von
1217 dort zu imporieren. Dabei auftretende Fehler werden gemeldet.
1219 Wenn Sie stattdessen eine andere Maschinendatei verwenden möchten, geben Sie
1220 diese einfach auf der Befehlszeile an:
1223 # guix offload test maschinen-qualif.scm
1226 Letztendlich können Sie hiermit nur die Teilmenge der Maschinen testen,
1227 deren Name zu einem regulären Ausdruck passt:
1230 # guix offload test maschinen.scm '\.gnu\.org$'
1233 @cindex Auslagerungs-Lagebericht
1234 Um die momentane Auslastung aller Erstellungs-Hosts anzuzeigen, führen Sie
1235 diesen Befehl auf dem Hauptknoten aus:
1238 # guix offload status
1242 @node SELinux-Unterstützung
1243 @subsection SELinux-Unterstützung
1245 @cindex SELinux, Policy für den Daemon
1246 @cindex Mandatory Access Control, SELinux
1247 @cindex Sicherheit, des guix-daemon
1248 Guix enthält eine SELinux-Richtliniendatei (»Policy«) unter
1249 @file{etc/guix-daemon.cil}, die auf einem System installiert werden
1250 kann, auf dem SELinux aktiviert ist, damit Guix-Dateien gekennzeichnet
1251 sind, und um das erwartete Verhalten des Daemons anzugeben. Da GuixSD
1252 keine Grundrichtlinie (»Base Policy«) für SELinux bietet, kann diese
1253 Richtlinie für den Daemon auf GuixSD nicht benutzt werden.
1255 @subsubsection Installieren der SELinux-Policy
1256 @cindex SELinux, Policy installieren
1257 Um die Richtlinie (Policy) zu installieren, führen Sie folgenden Befehl mit
1258 Administratorrechten aus:
1261 semodule -i etc/guix-daemon.cil
1264 Kennzeichnen Sie dann das Dateisystem neu mit @code{restorecon} oder einem
1265 anderen, von Ihrem System angebotenen Mechanismus.
1267 Sobald die Richtlinie installiert ist, das Dateisystem neu gekennzeichnet
1268 wurde und der Daemon neugestartet wurde, sollte er im Kontext
1269 @code{guix_daemon_t} laufen. Sie können dies mit dem folgenden Befehl
1273 ps -Zax | grep guix-daemon
1276 Beobachten Sie die Protokolldateien von SELinux, wenn Sie einen Befehl wie
1277 @code{guix build hello} ausführen, um sich zu überzeugen, dass SELinux alle
1278 notwendigen Operationen gestattet.
1280 @subsubsection Einschränkungen
1281 @cindex SELinux, Einschränkungen
1283 Diese Richtlinie ist nicht perfekt. Im Folgenden finden Sie eine Liste von
1284 Einschränkungen oder merkwürdigen Verhaltensweisen, die bedacht werden
1285 sollten, wenn man die mitgelieferte SELinux-Richtlinie für den Guix-Daemon
1290 @code{guix_daemon_socket_t} wird nicht wirklich benutzt. Keine der
1291 Socket-Operationen benutzt Kontexte, die irgendetwas mit
1292 @code{guix_daemon_socket_t} zu tun haben. Es schadet nicht, diese ungenutzte
1293 Kennzeichnung zu haben, aber es wäre besser, für die Kennzeichnung auch
1294 Socket-Regeln festzulegen.
1297 @code{guix gc} kann nicht auf beliebige Verknüpfungen zu Profilen
1298 zugreifen. Die Kennzeichnung des Ziels einer symbolischen Verknüpfung ist
1299 notwendigerweise unabhängig von der Dateikennzeichnung der
1300 Verknüpfung. Obwohl alle Profile unter $localstatedir gekennzeichnet sind,
1301 erben die Verknüpfungen auf diese Profile die Kennzeichnung desjenigen
1302 Verzeichnisses, in dem sie sich befinden. Für Verknüpfungen im Persönlichen
1303 Ordner des Benutzers ist das @code{user_home_t}, aber Verknüpfungen aus dem
1304 Persönlichen Ordner des Administratornutzers, oder @file{/tmp}, oder das
1305 Arbeitsverzeichnis des HTTP-Servers, etc., funktioniert das
1306 nicht. @code{guix gc} würde es nicht gestattet, diese Verknüpfungen
1307 auszulesen oder zu verfolgen.
1310 Die vom Daemon gebotene Funktionalität, auf TCP-Verbindungen zu lauschen,
1311 könnte nicht mehr funktionieren. Dies könnte zusätzliche Regeln brauchen,
1312 weil SELinux Netzwerk-Sockets anders behandelt als Dateien.
1315 Derzeit wird allen Dateien mit einem Namen, der zum regulären Ausdruck
1316 @code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} passt, die
1317 Kennzeichnung @code{guix_daemon_exec_t} zugewiesen, wodurch @emph{jede
1318 beliebige} Datei mit diesem Namen in irgendeinem Profil gestattet wäre, in
1319 der Domäne @code{guix_daemon_t} ausgeführt zu werden. Das ist nicht
1320 ideal. Ein Angreifer könnte ein Paket erstellen, dass solch eine ausführbare
1321 Datei enthält, und den Nutzer überzeugen, es zu installieren und
1322 auszuführen. Dadurch käme es in die Domäne @code{guix_daemon_t}. Ab diesem
1323 Punkt könnte SELinux nicht mehr verhindern, dass es auf Dateien zugreift,
1324 auf die Prozesse in dieser Domäne zugreifen dürfen.
1326 Wir könnten zum Zeitpunkt der Installation eine wesentlich restriktivere
1327 Richtlinie generieren, für die nur @emph{genau derselbe} Dateiname des
1328 gerade installierten @code{guix-daemon}-Programms als
1329 @code{guix_daemon_exec_t} gekennzeichnet würde, statt einen vieles
1330 umfassenden regulären Ausdruck zu benutzen. Aber dann müsste der
1331 Administratornutzer zum Zeitpunkt der Installation jedes Mal die Richtlinie
1332 installieren oder aktualisieren müssen, sobald das Guix-Paket aktualisiert
1333 wird, dass das tatsächlich in Benutzung befindliche
1334 @code{guix-daemon}-Programm enthält.
1337 @node Aufruf des guix-daemon
1338 @section Aufruf von @command{guix-daemon}
1340 Das Programm @command{guix-daemon} implementiert alle Funktionalitäten, um
1341 auf den Store zuzugreifen. Dazu gehört das Starten von Erstellungsprozessen,
1342 das Ausführen des Müllsammlers, das Abfragen, ob ein Erstellungsergebnis
1343 verfügbar ist, etc. Normalerweise wird er so als Administratornutzer
1344 (@code{root}) gestartet:
1347 # guix-daemon --build-users-group=guixbuild
1351 Details, wie Sie ihn einrichten, finden Sie im Abschnitt @pxref{Den Daemon einrichten}.
1354 @cindex Container, Erstellungsumgebung
1355 @cindex Erstellungsumgebung
1356 @cindex Reproduzierbare Erstellungen
1357 Standardmäßig führt @command{guix-daemon} Erstellungsprozesse mit
1358 unterschiedlichen UIDs aus, die aus der Erstellungsgruppe stammen, deren
1359 Name mit @code{--build-users-group} übergeben wurde. Außerdem läuft jeder
1360 Erstellungsprozess in einer chroot-Umgebung, die nur die Teilmenge des
1361 Stores enthält, von der der Erstellungsprozess abhängt, entsprechend seiner
1362 Ableitung (@pxref{Programmierschnittstelle, derivation}), und ein paar
1363 bestimmte Systemverzeichnisse, darunter standardmäßig auch @file{/dev} und
1364 @file{/dev/pts}. Zudem ist die Erstellungsumgebung auf GNU/Linux ein
1365 @dfn{Container}: Nicht nur hat er seinen eigenen Dateisystembaum, er hat
1366 auch einen separaten Namensraum zum Einhängen von Dateisystemen, seinen
1367 eigenen Namensraum für PIDs, für Netzwerke, etc. Dies hilft dabei,
1368 reproduzierbare Erstellungen zu garantieren (@pxref{Funktionalitäten}).
1370 When the daemon performs a build on behalf of the user, it creates a build
1371 directory under @file{/tmp} or under the directory specified by its
1372 @code{TMPDIR} environment variable. This directory is shared with the
1373 container for the duration of the build, though within the container, the
1374 build tree is always called @file{/tmp/guix-build-@var{name}.drv-0}.
1376 Nach Abschluss der Erstellung wird das Erstellungsverzeichnis automatisch
1377 entfernt, außer wenn die Erstellung fehlgeschlagen ist und der Client
1378 @option{--keep-failed} angegeben hat (@pxref{Aufruf von guix build,
1379 @option{--keep-failed}}).
1381 The daemon listens for connections and spawns one sub-process for each
1382 session started by a client (one of the @command{guix} sub-commands.) The
1383 @command{guix processes} command allows you to get an overview of the
1384 activity on your system by viewing each of the active sessions and clients.
1385 @xref{Invoking guix processes}, for more information.
1387 Die folgenden Befehlszeilenoptionen werden unterstützt:
1390 @item --build-users-group=@var{Gruppe}
1391 Verwende die Benutzerkonten aus der @var{Gruppe}, um Erstellungsprozesse
1392 auszuführen (@pxref{Den Daemon einrichten, build users}).
1394 @item --no-substitutes
1396 Benutze keine Substitute für Erstellungsergebnisse. Das heißt, dass alle
1397 Objekte lokal erstellt werden müssen, und kein Herunterladen von vorab
1398 erstellten Binärdateien erlaubt ist (@pxref{Substitute}).
1400 Wenn der Daemon mit @code{--no-substitutes} ausgeführt wird, können Clients
1401 trotzdem Substitute explizit aktivieren über den entfernten Prozeduraufruf
1402 @code{set-build-options} (@pxref{Der Store}).
1404 @item --substitute-urls=@var{URLs}
1405 @anchor{daemon-substitute-urls}
1406 Benutze @var{URLs} als standardmäßige, leerzeichengetrennte Liste der
1407 Quell-URLs für Substitute. Wenn diese Befehlszeilenoption nicht angegeben
1408 wird, wird @indicateurl{https://mirror.hydra.gnu.org https://hydra.gnu.org}
1409 verwendet (@code{mirror.hydra.gnu.org} ist ein Spiegelserver für
1410 @code{hydra.gnu.org}).
1412 Das hat zur Folge, dass Substitute von den @var{URLs} heruntergeladen werden
1413 können, solange sie mit einer Signatur versehen sind, der vertraut wird
1414 (@pxref{Substitute}).
1417 @item --no-build-hook
1418 Den »@dfn{Build-Hook}« nicht benutzen.
1420 »Build-Hook« ist der Name eines Hilfsprogramms, das der Daemon starten kann
1421 und an das er Erstellungsanfragen übermittelt. Durch diesen Mechanismus
1422 können Erstellungen an andere Maschinen ausgelagert werden (@pxref{Auslagern des Daemons einrichten}).
1424 @item --cache-failures
1425 Fehler bei der Erstellung zwischenspeichern. Normalerweise werden nur
1426 erfolgreiche Erstellungen gespeichert.
1428 Wenn diese Befehlszeilenoption benutzt wird, kann @command{guix gc
1429 --list-failures} benutzt werden, um die Menge an Store-Objekten abzufragen,
1430 die als Fehlschläge markiert sind; @command{guix gc --clear-failures}
1431 entfernt Store-Objekte aus der Menge zwischengespeicherter
1432 Fehlschläge. @xref{Aufruf von guix gc}.
1434 @item --cores=@var{n}
1436 @var{n} CPU-Kerne zum Erstellen jeder Ableitung benutzen; @code{0} heißt, so
1437 viele wie verfügbar sind.
1439 Der Vorgabewert ist @code{0}, jeder Client kann jedoch eine abweichende
1440 Anzahl vorgeben, zum Beispiel mit der Befehlszeilenoption @code{--cores} von
1441 @command{guix build} (@pxref{Aufruf von guix build}).
1443 Dadurch wird die Umgebungsvariable @code{NIX_BUILD_CORES} im
1444 Erstellungsprozess definiert, welcher sie benutzen kann, um intern parallele
1445 Ausführungen zuzulassen — zum Beispiel durch Nutzung von @code{make
1446 -j$NIX_BUILD_CORES}.
1448 @item --max-jobs=@var{n}
1450 Höchstenss @var{n} Erstellungsaufträge parallel bearbeiten. Der Vorgabewert
1451 liegt bei @code{1}. Wird er auf @code{0} gesetzt, werden keine Erstellungen
1452 lokal durchgeführt, stattdessen lagert der Daemon sie nur aus (@pxref{Auslagern des Daemons einrichten}) oder sie schlagen einfach fehl.
1454 @item --max-silent-time=@var{Sekunden}
1455 Wenn der Erstellungs- oder Substitutionsprozess länger als
1456 @var{Sekunden}-lang keine Ausgabe erzeugt, wird er abgebrochen und ein
1457 Fehler beim Erstellen gemeldet.
1459 Der Vorgabewert ist @code{0}, was bedeutet, dass es keine Zeitbeschränkung
1462 Clients können einen anderen Wert als den hier angegebenen verwenden lassen
1463 (@pxref{Gemeinsame Erstellungsoptionen, @code{--max-silent-time}}).
1465 @item --timeout=@var{Sekunden}
1466 Entsprechend wird hier der Erstellungs- oder Substitutionsprozess
1467 abgebrochen und als Fehlschlag gemeldet, wenn er mehr als
1468 @var{Sekunden}-lang dauert.
1470 Der Vorgabewert ist @code{0}, was bedeutet, dass es keine Zeitbeschränkung
1473 Clients können einen anderen Wert verwenden lassen (@pxref{Gemeinsame Erstellungsoptionen, @code{--timeout}}).
1475 @item --rounds=@var{N}
1476 Jede Ableitung @var{n}-mal hintereinander erstellen und einen Fehler melden,
1477 wenn nacheinander ausgewertete Erstellungsergebnisse nicht Bit für Bit
1478 identisch sind. Beachten Sie, dass Clients wie @command{guix build} einen
1479 anderen Wert verwenden lassen können (@pxref{Aufruf von guix build}).
1481 Wenn dies zusammen mit @option{--keep-failed} benutzt wird, bleiben die sich
1482 unterscheidenden Ausgaben im Store unter dem Namen
1483 @file{/gnu/store/@dots{}-check}. Dadurch können Unterschiede zwischen den
1484 beiden Ergebnissen leicht erkannt werden.
1487 Informationen zur Fehlersuche ausgeben.
1489 Dies ist nützlich, um Probleme beim Starten des Daemons nachzuvollziehen;
1490 Clients könn aber auch ein abweichenden Wert verwenden lassen, zum Beispiel
1491 mit der Befehlszeilenoption @code{--verbosity} von @command{guix build}
1492 (@pxref{Aufruf von guix build}).
1494 @item --chroot-directory=@var{Verzeichnis}
1495 Füge das @var{Verzeichnis} zum chroot von Erstellungen hinzu.
1497 Dadurch kann sich das Ergebnis von Erstellungsprozessen ändern — zum
1498 Beispiel, wenn diese optionale Abhängigkeiten aus dem @var{Verzeichnis}
1499 verwenden, wenn sie verfügbar sind, und nicht, wenn es fehlt. Deshalb ist es
1500 nicht empfohlen, dass Sie diese Befehlszeilenoption verwenden, besser
1501 sollten Sie dafür sorgen, dass jede Ableitung alle von ihr benötigten
1502 Eingabgen deklariert.
1504 @item --disable-chroot
1505 Erstellungen ohne chroot durchführen.
1507 Diese Befehlszeilenoption zu benutzen, wird nicht empfohlen, denn auch
1508 dadurch bekämen Erstellungsprozesse Zugriff auf nicht deklarierte
1509 Abhängigkeiten. Sie ist allerdings unvermeidlich, wenn @command{guix-daemon}
1510 auf einem Benutzerkonto ohne ausreichende Berechtigungen ausgeführt wird.
1512 @item --log-compression=@var{Typ}
1513 Erstellungsprotokolle werden entsprechend dem @var{Typ} komprimiert, der
1514 entweder @code{gzip}, @code{bzip2} oder @code{none} (für keine Kompression)
1517 Sofern nicht @code{--lose-logs} angegeben wurde, werden alle
1518 Erstellungsprotokolle in der @var{localstatedir} gespeichert. Um Platz zu
1519 sparen, komprimiert sie der Daemon standardmäßig automatisch mit bzip2.
1521 @item --disable-deduplication
1522 @cindex Deduplizieren
1523 Automatische Dateien-»Deduplizierung« im Store ausschalten.
1525 Standardmäßig werden zum Store hinzugefügte Objekte automatisch
1526 »dedupliziert«: Wenn eine neue Datei mit einer anderen im Store
1527 übereinstimmt, wird die neue Datei stattdessen als harte Verknüpfung auf die
1528 andere Datei angelegt. Dies reduziert den Speicherverbrauch auf der Platte
1529 merklich, jedoch steigt andererseits die Auslastung bei der Ein-/Ausgabe im
1530 Erstellungsprozess geringfügig. Durch diese Option wird keine solche
1531 Optimierung durchgeführt.
1533 @item --gc-keep-outputs[=yes|no]
1534 Gibt an, ob der Müllsammler (Garbage Collector, GC) die Ausgaben lebendiger
1535 Ableitungen behalten muss (»yes«) oder nicht (»no«).
1538 @cindex Müllsammlerwurzeln
1539 When set to ``yes'', the GC will keep the outputs of any live derivation
1540 available in the store---the @code{.drv} files. The default is ``no'',
1541 meaning that derivation outputs are kept only if they are reachable from a
1542 GC root. @xref{Aufruf von guix gc}, for more on GC roots.
1544 @item --gc-keep-derivations[=yes|no]
1545 Gibt an, ob der Müllsammler (GC) Ableitungen behalten muss (»yes«), wenn sie
1546 lebendige Ausgaben haben, oder nicht (»no«).
1548 Für »yes«, den Vorgabewert, behält der Müllsammler Ableitungen —
1549 z.B. @code{.drv}-Dateien —, solange zumindest eine ihrer Ausgaben lebendig
1550 ist. Dadurch können Nutzer den Ursprung der Dateien in ihrem Store
1551 nachvollziehen. Setzt man den Wert auf »no«, wird ein bisschen weniger
1552 Speicher auf der Platte verbraucht.
1554 In this way, setting @code{--gc-keep-derivations} to ``yes'' causes liveness
1555 to flow from outputs to derivations, and setting @code{--gc-keep-outputs} to
1556 ``yes'' causes liveness to flow from derivations to outputs. When both are
1557 set to ``yes'', the effect is to keep all the build prerequisites (the
1558 sources, compiler, libraries, and other build-time tools) of live objects in
1559 the store, regardless of whether these prerequisites are reachable from a GC
1560 root. This is convenient for developers since it saves rebuilds or
1563 @item --impersonate-linux-2.6
1564 Auf Linux-basierten Systemen wird hiermit vorgetäuscht, dass es sich um
1565 Linux 2.6 handeln würde, indem der Kernel für einen
1566 @code{uname}-Systemaufruf als Version der Veröffentlichung mit 2.6
1569 Dies kann hilfreich sein, um Programme zu erstellen, die (normalerweise zu
1570 Unrecht) von der Kernel-Versionsnummer abhängen.
1573 Keine Protokolle der Erstellungen vorhalten. Normalerweise würden solche in
1574 @code{@var{localstatedir}/guix/log} gespeichert.
1576 @item --system=@var{System}
1577 Verwende @var{System} als aktuellen Systemtyp. Standardmäßig ist dies das
1578 Paar aus Befehlssatz und Kernel, welches beim Aufruf von @code{configure}
1579 erkannt wurde, wie zum Beispiel @code{x86_64-linux}.
1581 @item --listen=@var{Endpunkt}
1582 Lausche am @var{Endpunkt} auf Verbindungen. Dabei wird der @var{Endpunkt}
1583 als Dateiname eines Unix-Sockets verstanden, wenn er mit einem @code{/}
1584 (Schrägstrich) beginnt. Andernfalls wird der @var{Endpunkt} als Hostname
1585 oder als Hostname-Port-Paar verstanden, auf dem gelauscht wird. Hier sind
1589 @item --listen=/gnu/var/daemon
1590 Lausche auf Verbindungen am Unix-Socket @file{/gnu/var/daemon}, falls nötig
1591 wird er dazu erstellt.
1593 @item --listen=localhost
1594 @cindex Daemon, Fernzugriff
1595 @cindex Fernzugriff auf den Daemon
1596 @cindex Daemon, Einrichten auf Clustern
1597 @cindex Cluster, Einrichtung des Daemons
1598 Lausche auf TCP-Verbindungen an der Netzwerkschnittstelle, die
1599 @code{localhost} entspricht, auf Port 44146.
1601 @item --listen=128.0.0.42:1234
1602 Lausche auf TCP-Verbindungen an der Netzwerkschnittstelle, die
1603 @code{128.0.0.42} entspricht, auf Port 1234.
1606 Diese Befehlszeilenoption kann mehrmals wiederholt werden. In diesem Fall
1607 akzeptiert @command{guix-daemon} Verbindungen auf allen angegebenen
1608 Endpunkten. Benutzer können bei Client-Befehlen angeben, mit welchem
1609 Endpunkt sie sich verbinden möchten, indem sie die Umgebungsvariable
1610 @code{GUIX_DAEMON_SOCKET} festlegen (@pxref{Der Store,
1611 @code{GUIX_DAEMON_SOCKET}}).
1613 @quotation Anmerkung
1614 Das Daemon-Protokoll ist @emph{weder authentifiziert noch
1615 verschlüsselt}. Die Benutzung von @code{--listen=@var{Host}} eignet sich für
1616 lokale Netzwerke, wie z.B. in Rechen-Clustern, wo sich nur solche Knoten mit
1617 dem Daemon verbinden, denen man vertraut. In Situationen, wo ein Fernzugriff
1618 auf den Daemon durchgeführt wird, empfehlen wir, über Unix-Sockets in
1619 Verbindung mit SSH zuzugreifen.
1622 Wird @code{--listen} nicht angegeben, lauscht @command{guix-daemon} auf
1623 Verbindungen auf dem Unix-Socket, der sich unter
1624 @file{@var{localstatedir}/guix/daemon-socket/socket} befindet.
1628 @node Anwendungen einrichten
1629 @section Anwendungen einrichten
1631 @cindex Fremddistribution
1632 Läuft Guix aufgesetzt auf einer GNU/Linux-Distribution außer GuixSD — einer
1633 sogenannten @dfn{Fremddistribution} —, so sind ein paar zusätzliche Schritte
1634 bei der Einrichtung nötig. Hier finden Sie manche davon.
1638 @anchor{locales-and-locpath}
1639 @cindex Locales, nicht auf GuixSD
1641 @vindex GUIX_LOCPATH
1642 Über Guix installierte Pakete benutzen nicht die Daten zu Regions- und
1643 Spracheinstellungen (Locales) des Wirtssystems. Stattdessen müssen Sie erst
1644 eines der Locale-Pakete installieren, die für Guix verfügbar sind, und dann
1645 den Wert Ihrer Umgebungsvariablen @code{GUIX_LOCPATH} passend festlegen:
1648 $ guix package -i glibc-locales
1649 $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale
1652 Beachten Sie, dass das Paket @code{glibc-locales} Daten für alle von
1653 GNU@tie{}libc unterstützten Locales enthält und deswegen um die 110@tie{}MiB
1654 wiegt. Alternativ gibt es auch @code{glibc-utf8-locales}, was kleiner, aber
1655 auf ein paar UTF-8-Locales beschränkt ist.
1657 Die Variable @code{GUIX_LOCPATH} spielt eine ähnliche Rolle wie
1658 @code{LOCPATH} (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C
1659 Library Reference Manual}). Es gibt jedoch zwei wichtige Unterschiede:
1663 @code{GUIX_LOCPATH} wird nur von der libc in Guix beachtet und nicht der von
1664 Fremddistributionen bereitgestellten libc. Mit @code{GUIX_LOCPATH} können
1665 Sie daher sicherstellen, dass die Programme der Fremddistribution keine
1666 inkompatiblen Locale-Daten von Guix laden.
1669 libc hängt an jeden @code{GUIX_LOCPATH}-Eintrag @code{/X.Y} an, wobei
1670 @code{X.Y} die Version von libc ist — z.B. @code{2.22}. Sollte Ihr
1671 Guix-Profil eine Mischung aus Programmen enthalten, die an verschiedene
1672 libc-Versionen gebunden sind, wird jede nur die Locale-Daten im richtigen
1673 Format zu laden versuchen.
1676 Das ist wichtig, weil das Locale-Datenformat verschiedener libc-Versionen
1677 inkompatibel sein könnte.
1679 @subsection Name Service Switch
1681 @cindex Name Service Switch, glibc
1682 @cindex NSS (Name Service Switch), glibc
1683 @cindex nscd (Name Service Caching Daemon)
1684 @cindex Name Service Caching Daemon (nscd)
1685 Wenn Sie Guix auf einer Fremddistribution verwenden, @emph{empfehlen wir
1686 stärkstens}, dass Sie den @dfn{Name Service Cache Daemon} der
1687 GNU-C-Bibliothek, @command{nscd}, laufen lassen, welcher auf dem Socket
1688 @file{/var/run/nscd/socket} lauschen sollte. Wenn Sie das nicht tun, könnten
1689 mit Guix installierte Anwendungen Probleme beim Auflösen von Hostnamen oder
1690 Benutzerkonten haben, oder sogar abstürzen. Die nächsten Absätze erklären
1693 @cindex @file{nsswitch.conf}
1694 Die GNU-C-Bibliothek implementiert einen @dfn{Name Service Switch} (NSS),
1695 welcher einen erweiterbaren Mechanismus zur allgemeinen »Namensauflösung«
1696 darstellt: Hostnamensauflösung, Benutzerkonten und weiteres (@pxref{Name Service Switch,,, libc, The GNU C Library Reference Manual}).
1698 @cindex Network Information Service (NIS)
1699 @cindex NIS (Network Information Service)
1700 Für die Erweiterbarkeit unterstützt der NSS @dfn{Plugins}, welche neue
1701 Implementierungen zur Namensauflösung bieten: Zum Beispiel ermöglicht das
1702 Plugin @code{nss-mdns} die Namensauflösung für @code{.local}-Hostnamen, das
1703 Plugin @code{nis} gestattet die Auflösung von Benutzerkonten über den
1704 Network Information Service (NIS) und so weiter. Diese zusätzlichen
1705 »Auflösungsdienste« werden systemweit konfiguriert in
1706 @file{/etc/nsswitch.conf} und alle auf dem System laufenden Programme halten
1707 sich an diese Einstellungen (@pxref{NSS Configuration File,,, libc, The GNU
1708 C Reference Manual}).
1710 Wenn sie eine Namensauflösung durchführen — zum Beispiel, indem sie die
1711 @code{getaddrinfo}-Funktion in C aufrufen — versuchen die Anwendungen als
1712 Erstes, sich mit dem nscd zu verbinden; ist dies erfolgreich, führt nscd für
1713 sie die weiteren Namensauflösungen durch. Falls nscd nicht läuft, führen sie
1714 selbst die Namensauflösungen durch, indem sie die Namensauflösungsdienste in
1715 ihren eigenen Adressraum laden und ausführen. Diese Namensauflösungsdienste
1716 — die @file{libnss_*.so}-Dateien — werden mit @code{dlopen} geladen, aber
1717 sie kommen von der C-Bibliothek des Wirtssystems und nicht von der
1718 C-Bibliothek, mit der die Anwendung gebunden wurde (also der C-Bibliothek
1721 Und hier kommt es zum Problem: Wenn die Anwendung mit der C-Bibliothek von
1722 Guix (etwa glibc 2.24) gebunden wurde und die NSS-Plugins von einer anderen
1723 C-Bibliothek (etwa @code{libnss_mdns.so} für glibc 2.22) zu laden versucht,
1724 wird sie vermutlich abstürzen oder die Namensauflösungen werden unerwartet
1727 Durch das Ausführen von @command{nscd} auf dem System wird, neben anderen
1728 Vorteilen, dieses Problem der binären Inkompatibilität vermieden, weil diese
1729 @code{libnss_*.so}-Dateien vom @command{nscd}-Prozess geladen werden, nicht
1730 in den Anwendungen selbst.
1732 @subsection X11-Schriftarten
1734 @cindex Schriftarten
1735 Die Mehrheit der graphischen Anwendungen benutzen Fontconfig zum Finden und
1736 Laden von Schriftarten und für die Darstellung im X11-Client. Im Paket
1737 @code{fontconfig} in Guix werden Schriftarten standardmäßig in
1738 @file{$HOME/.guix-profile} gesucht. Um es graphischen Anwendungen, die mit
1739 Guix installiert wurden, zu ermöglichen, Schriftarten anzuzeigen, müssen Sie
1740 die Schriftarten auch mit Guix installieren. Essenzielle Pakete für
1741 Schriftarten sind unter Anderem @code{gs-fonts}, @code{font-dejavu} und
1742 @code{font-gnu-freefont-ttf}.
1744 Um auf Chinesisch, Japanisch oder Koreanisch verfassten Text in graphischen
1745 Anwendungen anzeigen zu können, möchten Sie vielleicht
1746 @code{font-adobe-source-han-sans} oder @code{font-wqy-zenhei}
1747 installieren. Ersteres hat mehrere Ausgaben, für jede Sprachfamilie eine
1748 (@pxref{Pakete mit mehreren Ausgaben.}). Zum Beispiel installiert folgender
1749 Befehl Schriftarten für chinesische Sprachen:
1752 guix package -i font-adobe-source-han-sans:cn
1755 @cindex @code{xterm}
1756 Ältere Programme wie @command{xterm} benutzen kein Fontconfig, sondern
1757 X-Server-seitige Schriftartendarstellung. Solche Programme setzen voraus,
1758 dass der volle Name einer Schriftart mit XLFD (X Logical Font Description)
1759 angegeben wird, z.B. so:
1762 -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1
1765 Um solche vollen Namen für die in Ihrem Guix-Profil installierten
1766 TrueType-Schriftarten zu verwenden, müssen Sie den Pfad für Schriftarten
1767 (Font Path) des X-Servers anpassen:
1769 @c Note: 'xset' does not accept symlinks so the trick below arranges to
1770 @c get at the real directory. See <https://bugs.gnu.org/30655>.
1772 xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))
1775 @cindex @code{xlsfonts}
1776 Danach können Sie den Befehl @code{xlsfonts} ausführen (aus dem Paket
1777 @code{xlsfonts}), um sicherzustellen, dass dort Ihre TrueType-Schriftarten
1780 @cindex @code{fc-cache}
1782 Nach der Installation der Schriftarten müssen Sie unter Umständen den
1783 Schriftarten-Zwischenspeicher (Font-Cache) erneuern, um diese in Anwendungen
1784 benutzen zu können. Gleiches gilt, wenn mit Guix installierte Anwendungen
1785 anscheinend keine Schriftarten finden können. Um das Erneuern des
1786 Font-Caches zu erzwingen, führen Sie @code{fc-cache -f} aus. Der Befehl
1787 @code{fc-cache} wird vom Paket @code{fontconfig} angeboten.
1789 @subsection X.509-Zertifikate
1791 @cindex @code{nss-certs}
1792 Das Paket @code{nss-certs} bietet X.509-Zertifikate, womit Programme die
1793 Identität von Web-Servern authentifizieren können, auf die über HTTPS
1796 Wenn Sie Guix auf einer Fremddistribution verwenden, können Sie dieses Paket
1797 installieren und die relevanten Umgebungsvariablen festlegen, damit Pakete
1798 wissen, wo sie Zertifikate finden. In @xref{X.509-Zertifikate} stehen
1799 genaue Informationen.
1801 @subsection Emacs-Pakete
1803 @cindex @code{emacs}
1804 Wenn Sie mit Guix Pakete für Emacs installieren, werden deren elisp-Dateien
1805 entweder in @file{$HOME/.guix-profile/share/emacs/site-lisp/} oder in
1806 Unterverzeichnissen von
1807 @file{$HOME/.guix-profile/share/emacs/site-lisp/guix.d/}
1808 gespeichert. Letzteres Verzeichnis gibt es, weil es Tausende von
1809 Emacs-Paketen gibt und sie alle im selben Verzeichnis zu speichern
1810 vielleicht nicht verlässlich funktioniert (wegen Namenskonflikten). Daher
1811 halten wir es für richtig, für jedes Paket ein anderes Verzeichnis zu
1812 benutzen. Das Emacs-Paketsystem organisiert die Dateistruktur ähnlich
1813 (@pxref{Package Files,,, emacs, The GNU Emacs Manual}).
1815 Standardmäßig »weiß« Emacs (wenn er mit Guix installiert wurde), wo diese
1816 Pakete liegen, Sie müssen also nichts selbst konfigurieren. Wenn Sie aber
1817 aus irgendeinem Grund mit Guix installierte Pakete nicht automatisch laden
1818 lassen möchten, können Sie Emacs mit der Befehlszeilenoption
1819 @code{--no-site-file} starten (@pxref{Init File,,, emacs, The GNU Emacs
1822 @subsection GCC-Toolchain
1827 Guix bietet individuelle Compiler-Pakete wie etwa @code{gcc}, aber wenn Sie
1828 einen vollständigen Satz an Werkzeugen zum Kompilieren und Binden von
1829 Quellcode brauchen, werden Sie eigentlich das Paket @code{gcc-toolchain}
1830 haben wollen. Das Paket bietet eine vollständige GCC-Toolchain für die
1831 Entwicklung mit C/C++, einschließlich GCC selbst, der GNU-C-Bibliothek
1832 (Header-Dateien und Binärdateien samt Symbolen zur Fehlersuche/Debugging in
1833 der @code{debug}-Ausgabe), Binutils und einen Wrapper für den Binder/Linker.
1835 @cindex Versuch, unreine Bibliothek zu benutzen, Fehlermeldung
1837 Der Zweck des Wrappers ist, die an den Binder übergebenen
1838 Befehlszeilenoptionen mit @code{-L} und @code{-l} zu überprüfen und jeweils
1839 passende Argumente mit @code{-rpath} anzufügen, womit dann der echte Binder
1840 aufgerufen wird. Standardmäßig weigert sich der Binder-Wrapper, mit
1841 Bibliotheken außerhalb des Stores zu binden, um »Reinheit« zu
1842 gewährleisten. Das kann aber stören, wenn man die Toolchain benutzt, um mit
1843 lokalen Bibliotheken zu binden. Um Referenzen auf Bibliotheken außerhalb des
1844 Stores zu erlauben, müssen Sie die Umgebungsvariable
1845 @code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} setzen.
1849 @c *********************************************************************
1850 @node Paketverwaltung
1851 @chapter Paketverwaltung
1854 Der Zweck von GNU Guix ist, Benutzern die leichte Installation,
1855 Aktualisierung und Entfernung von Software-Paketen zu ermöglichen, ohne dass
1856 sie ihre Erstellungsprozeduren oder Abhängigkeiten kennen müssen. Guix kann
1857 natürlich noch mehr als diese offensichtlichen Funktionalitäten.
1859 Dieses Kapitel beschreibt die Hauptfunktionalitäten von Guix, sowie die von
1860 Guix angebotenen Paketverwaltungswerkzeuge. Zusätzlich von den im Folgenden
1861 beschriebenen Befehlszeilen-Benutzerschnittstellen (@pxref{Aufruf von guix package, @code{guix package}}) können Sie auch mit der
1862 Emacs-Guix-Schnittstelle (@pxref{Top,,, emacs-guix, The Emacs-Guix Reference
1863 Manual}) arbeiten, nachdem Sie das Paket @code{emacs-guix} installiert haben
1864 (führen Sie zum Einstieg in Emacs-Guix den Emacs-Befehl @kbd{M-x guix-help}
1868 guix package -i emacs-guix
1872 * Funktionalitäten:: Wie Guix Ihr Leben schöner machen wird.
1873 * Aufruf von guix package:: Pakete installieren, entfernen usw.
1874 * Substitute:: Vorerstelle Binärdateien herunterladen.
1875 * Pakete mit mehreren Ausgaben.:: Ein Quellpaket, mehrere Ausgaben.
1876 * Aufruf von guix gc:: Den Müllsammler laufen lassen.
1877 * Aufruf von guix pull:: Das neueste Guix samt Distribution laden.
1878 * Channels:: Customizing the package collection.
1879 * Inferiors:: Interacting with another revision of Guix.
1880 * Invoking guix describe:: Display information about your Guix revision.
1881 * Aufruf von guix pack:: Software-Bündel erstellen.
1882 * Aufruf von guix archive:: Import und Export von Store-Dateien.
1885 @node Funktionalitäten
1886 @section Funktionalitäten
1888 Wenn Sie Guix benutzen, landet jedes Paket schließlich im @dfn{Paket-Store}
1889 in seinem eigenen Verzeichnis — der Name ist ähnlich wie
1890 @file{/gnu/store/xxx-package-1.2}, wobei @code{xxx} eine Zeichenkette in
1891 Base32-Darstellung ist.
1893 Statt diese Verzeichnisse direkt anzugeben, haben Nutzer ihr eigenes
1894 @dfn{Profil}, welches auf diejenigen Pakete zeigt, die sie tatsächlich
1895 benutzen wollen. Diese Profile sind im Persönlichen Ordner des jeweiligen
1896 Nutzers gespeichert als @code{$HOME/.guix-profile}.
1898 Zum Beispiel installiert @code{alice} GCC 4.7.2. Dadurch zeigt dann
1899 @file{/home/alice/.guix-profile/bin/gcc} auf
1900 @file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Auf demselben Rechner hat
1901 @code{bob} bereits GCC 4.8.0 installiert. Das Profil von @code{bob} zeigt
1902 dann einfach weiterhin auf @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc} —
1903 d.h. beide Versionen von GCC koexistieren auf demselben System, ohne sich zu
1906 Der Befehl @command{guix package} ist das zentrale Werkzeug, um Pakete zu
1907 verwalten (@pxref{Aufruf von guix package}). Es arbeitet auf dem eigenen
1908 Profil jedes Nutzers und kann @emph{mit normalen Benutzerrechten} ausgeführt
1911 @cindex Transaktionen
1912 Der Befehl stellt die offensichtlichen Installations-, Entfernungs- und
1913 Aktualisierungsoperationen zur Verfügung. Jeder Aufruf ist tatsächlich eine
1914 eigene @emph{Transaktion}: Entweder die angegebene Operation wird
1915 erfolgreich durchgeführt, oder gar nichts passiert. Wenn also der Prozess
1916 von @command{guix package} während der Transaktion beendet wird, oder es zum
1917 Stromausfall während der Transaktion kommt, dann bleibt der alte, nutzbare
1918 Zustands des Nutzerprofils erhalten.
1920 Zudem kann jede Pakettransaktion @emph{zurückgesetzt} werden
1921 (Rollback). Wird also zum Beispiel durch eine Aktualisierung eine neue
1922 Version eines Pakets installiert, die einen schwerwiegenden Fehler zur Folge
1923 hat, können Nutzer ihr Profil einfach auf die vorherige Profilinstanz
1924 zurücksetzen, von der sie wissen, dass sie gut lief. Ebenso unterliegt auf
1925 GuixSD auch die globale Systemkonfiguration transaktionellen
1926 Aktualisierungen und Rücksetzungen (@pxref{Das Konfigurationssystem nutzen}).
1928 Alle Pakete im Paket-Store können vom @emph{Müllsammler} (Garbage Collector)
1929 gelöscht werden. Guix ist in der Lage, festzustellen, welche Pakete noch
1930 durch Benutzerprofile referenziert werden, und entfernt nur diese, die
1931 nachweislich nicht mehr referenziert werden (@pxref{Aufruf von guix gc}). Benutzer können auch ausdrücklich alte Generationen ihres Profils
1932 löschen, damit die zugehörigen Pakete vom Müllsammler gelöscht werden
1935 @cindex Reproduzierbarkeit
1936 @cindex Reproduzierbare Erstellungen
1937 Guix takes a @dfn{purely functional} approach to package management, as
1938 described in the introduction (@pxref{Einführung}). Each
1939 @file{/gnu/store} package directory name contains a hash of all the inputs
1940 that were used to build that package---compiler, libraries, build scripts,
1941 etc. This direct correspondence allows users to make sure a given package
1942 installation matches the current state of their distribution. It also helps
1943 maximize @dfn{build reproducibility}: thanks to the isolated build
1944 environments that are used, a given build is likely to yield bit-identical
1945 files when performed on different machines (@pxref{Aufruf des guix-daemon,
1949 Auf dieser Grundlage kann Guix @dfn{transparent Binär- oder Quelldateien
1950 ausliefern}. Wenn eine vorerstellte Binärdatei für ein
1951 @file{/gnu/store}-Objekt von einer externen Quelle verfügbar ist — ein
1952 @dfn{Substitut} —, lädt Guix sie einfach herunter und entpackt sie,
1953 andernfalls erstellt Guix das Paket lokal aus seinem Quellcode
1954 (@pxref{Substitute}). Weil Erstellungsergebnisse normalerweise Bit für Bit
1955 reproduzierbar sind, müssen die Nutzer den Servern, die Substitute anbieten,
1956 nicht blind vertrauen; sie können eine lokale Erstellung erzwingen und
1957 Substitute @emph{anfechten} (@pxref{Aufruf von guix challenge}).
1959 Kontrolle über die Erstellungsumgebung ist eine auch für Entwickler
1960 nützliche Funktionalität. Der Befehl @command{guix environment} ermöglicht
1961 es Entwicklern eines Pakets, schnell die richtige Entwicklungsumgebung für
1962 ihr Paket einzurichten, ohne manuell die Abhängigkeiten des Pakets in ihr
1963 Profil installieren zu müssen (@pxref{Aufruf von guix environment}).
1965 @cindex replication, of software environments
1966 @cindex provenance tracking, of software artifacts
1967 All of Guix and its package definitions is version-controlled, and
1968 @command{guix pull} allows you to ``travel in time'' on the history of Guix
1969 itself (@pxref{Aufruf von guix pull}). This makes it possible to replicate a
1970 Guix instance on a different machine or at a later point in time, which in
1971 turn allows you to @emph{replicate complete software environments}, while
1972 retaining precise @dfn{provenance tracking} of the software.
1974 @node Aufruf von guix package
1975 @section Invoking @command{guix package}
1977 @cindex Installieren von Paketen
1978 @cindex Entfernen von Paketen
1979 @cindex Paketinstallation
1980 @cindex Paketentfernung
1981 Der Befehl @command{guix package} ist ein Werkzeug, womit Nutzer Pakete
1982 installieren, aktualisieren, entfernen und auf vorherige Konfigurationen
1983 zurücksetzen können. Dabei wird nur das eigene Profil des Nutzers verwendet,
1984 und es funktioniert mit normalen Benutzerrechten, ohne Administratorrechte
1985 (@pxref{Funktionalitäten}). Die Syntax ist:
1988 guix package @var{Optionen}
1990 @cindex Transaktionen
1991 In erster Linie geben die @var{Optionen} an, welche Operationen in der
1992 Transaktion durchgeführt werden sollen. Nach Abschluss wird ein neues Profil
1993 erzeugt, aber vorherige @dfn{Generationen} des Profils bleiben verfügbar,
1994 falls der Benutzer auf sie zurückwechseln will.
1996 Um zum Beispiel @code{lua} zu entfernen und @code{guile} und
1997 @code{guile-cairo} in einer einzigen Transaktion zu installieren:
2000 guix package -r lua -i guile guile-cairo
2003 @command{guix package} unterstützt auch ein @dfn{deklaratives Vorgehen},
2004 wobei der Nutzer die genaue Menge an Paketen, die verfügbar sein sollen,
2005 festlegt und über die Befehlszeilenoption @option{--manifest} übergibt
2006 (@pxref{profile-manifest, @option{--manifest}}).
2009 Für jeden Benutzer wird automatisch eine symbolische Verknüpfung zu seinem
2010 Standardprofil angelegt als @file{$HOME/.guix-profile}. Diese symbolische
2011 Verknüpfung zeigt immer auf die aktuelle Generation des Standardprofils des
2012 Benutzers. Somit können Nutzer @file{$HOME/.guix-profile/bin} z.B. zu ihrer
2013 Umgebungsvariablen @code{PATH} hinzufügen.
2015 Wenn Sie nicht die Guix System Distribution benutzen, sollten Sie in
2016 Betracht ziehen, folgende Zeilen zu Ihrem @file{~/.bash_profile}
2017 hinzuzufügen (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference
2018 Manual}), damit in neu erzeugten Shells alle Umgebungsvariablen richtig
2022 GUIX_PROFILE="$HOME/.guix-profile" ; \
2023 source "$HOME/.guix-profile/etc/profile"
2026 Ist Ihr System für mehrere Nutzer eingerichtet, werden Nutzerprofile an
2027 einem Ort gespeichert, der als @dfn{Müllsammlerwurzel} registriert ist, auf
2028 die @file{$HOME/.guix-profile} zeigt (@pxref{Aufruf von guix gc}). Dieses
2029 Verzeichnis ist normalerweise
2030 @code{@var{localstatedir}/guix/profiles/per-user/@var{Benutzer}}, wobei
2031 @var{localstatedir} der an @code{configure} als @code{--localstatedir}
2032 übergebene Wert ist und @var{Benutzer} für den jeweiligen Benutzernamen
2033 steht. Das @file{per-user}-Verzeichnis wird erstellt, wenn
2034 @command{guix-daemon} gestartet wird, und das Unterverzeichnis
2035 @var{Benutzer} wird durch @command{guix package} erstellt.
2037 Als @var{Optionen} kann vorkommen:
2041 @item --install=@var{Paket} @dots{}
2042 @itemx -i @var{Paket} @dots{}
2043 Die angegebenen @var{Paket}e installieren.
2045 Jedes @var{Paket} kann entweder einfach durch seinen Paketnamen aufgeführt
2046 werden, wie @code{guile}, oder als Paketname gefolgt von einem At-Zeichen @@
2047 und einer Versionsnummer, wie @code{guile@@1.8.8} oder auch nur
2048 @code{guile@@1.8} (in letzterem Fall wird die neueste Version mit Präfix
2049 @code{1.8} ausgewählt.)
2051 Wird keine Versionsnummer angegeben, wird die neueste verfügbare Version
2052 ausgewählt. Zudem kann im @var{Paket} ein Doppelpunkt auftauchen, gefolgt
2053 vom Namen einer der Ausgaben des Pakets, wie @code{gcc:doc} oder
2054 @code{binutils@@2.22:lib} (@pxref{Pakete mit mehreren Ausgaben.}). Pakete
2055 mit zugehörigem Namen (und optional der Version) werden unter den Modulen
2056 der GNU-Distribution gesucht (@pxref{Paketmodule}).
2058 @cindex propagierte Eingaben
2059 Manchmal haben Pakete @dfn{propagierte Eingaben}: Als solche werden
2060 Abhängigkeiten bezeichnet, die automatisch zusammen mit dem angeforderten
2061 Paket installiert werden (im Abschnitt @pxref{package-propagated-inputs,
2062 @code{propagated-inputs} in @code{package} objects} sind weitere
2063 Informationen über propagierte Eingaben in Paketdefinitionen zu finden).
2065 @anchor{package-cmd-propagated-inputs}
2066 Ein Beispiel ist die GNU-MPC-Bibliothek: Ihre C-Headerdateien verweisen auf
2067 die der GNU-MPFR-Bibliothek, welche wiederum auf die der GMP-Bibliothek
2068 verweisen. Wenn also MPC installiert wird, werden auch die MPFR- und
2069 GMP-Bibliotheken in das Profil installiert; entfernt man MPC, werden auch
2070 MPFR und GMP entfernt — außer sie wurden noch auf andere Art ausdrücklich
2071 vom Nutzer installiert.
2073 Abgesehen davon setzen Pakete manchmal die Definition von Umgebungsvariablen
2074 für ihre Suchpfade voraus (siehe die Erklärung von @code{--search-paths}
2075 weiter unten). Alle fehlenden oder womöglich falschen Definitionen von
2076 Umgebungsvariablen werden hierbei gemeldet.
2078 @item --install-from-expression=@var{Ausdruck}
2079 @itemx -e @var{Ausdruck}
2080 Das Paket installieren, zu dem der @var{Ausdruck} ausgewertet wird.
2082 Beim @var{Ausdruck} muss es sich um einen Scheme-Ausdruck handeln, der zu
2083 einem @code{<package>}-Objekt ausgewertet wird. Diese Option ist besonders
2084 nützlich, um zwischen gleichnamigen Varianten eines Pakets zu unterscheiden,
2085 durch Ausdrücke wie @code{(@@ (gnu packages base) guile-final)}.
2087 Beachten Sie, dass mit dieser Option die erste Ausgabe des angegebenen
2088 Pakets installiert wird, was unzureichend sein kann, wenn eine bestimmte
2089 Ausgabe eines Pakets mit mehreren Ausgaben gewünscht ist.
2091 @item --install-from-file=@var{Datei}
2092 @itemx -f @var{Datei}
2093 Das Paket installieren, zu dem der Code in der @var{Datei} ausgewertet wird.
2095 Zum Beispiel könnte die @var{Datei} eine Definition wie diese enthalten
2096 (@pxref{Pakete definieren}):
2099 @verbatiminclude package-hello.scm
2102 Entwickler könnten es für nützlich erachten, eine solche
2103 @file{guix.scm}-Datei im Quellbaum ihres Projekts abzulegen, mit der
2104 Zwischenstände der Entwicklung getestet und reproduzierbare
2105 Erstellungsumgebungen aufgebaut werden können (@pxref{Aufruf von guix environment}).
2107 @item --remove=@var{Paket} @dots{}
2108 @itemx -r @var{Paket} @dots{}
2109 Die angegebenen @var{Paket}e entfernen.
2111 Wie auch bei @code{--install} kann jedes @var{Paket} neben dem Paketnamen
2112 auch eine Versionsnummer und/oder eine Ausgabe benennen. Zum Beispiel würde
2113 @code{-r glibc:debug} die @code{debug}-Ausgabe von @code{glibc} aus dem
2116 @item --upgrade[=@var{Regexp} @dots{}]
2117 @itemx -u [@var{Regexp} @dots{}]
2118 @cindex Pakete aktualisieren
2119 Alle installierten Pakete aktualisieren. Wenn einer oder mehr reguläre
2120 Ausdrücke (Regexps) angegeben wurden, werden nur diejenigen installierten
2121 Pakete aktualisiert, deren Name zu einer der @var{Regexp}s passt. Siehe auch
2122 weiter unten die Befehlszeilenoption @code{--do-not-upgrade}.
2124 Beachten Sie, dass das Paket so auf die neueste Version unter den Paketen
2125 gebracht wird, die in der aktuell installierten Distribution vorliegen. Um
2126 jedoch Ihre Distribution zu aktualisieren, sollten Sie regelmäßig
2127 @command{guix pull} ausführen (@pxref{Aufruf von guix pull}).
2129 @item --do-not-upgrade[=@var{Regexp} @dots{}]
2130 In Verbindung mit der Befehlszeilenoption @code{--upgrade}, führe
2131 @emph{keine} Aktualisierung von Paketen durch, deren Name zum regulären
2132 Ausdruck @var{Regexp} passt. Um zum Beispiel alle Pakete im aktuellen Profil
2133 zu aktualisieren mit Ausnahme derer, die »emacs« im Namen haben:
2136 $ guix package --upgrade . --do-not-upgrade emacs
2139 @item @anchor{profile-manifest}--manifest=@var{Datei}
2140 @itemx -m @var{Datei}
2141 @cindex Profildeklaration
2142 @cindex Profilmanifest
2143 Erstellt eine neue Generation des Profils aus dem vom Scheme-Code in
2144 @var{Datei} gelieferten Manifest-Objekt.
2146 Dadurch könnrn Sie den Inhalt des Profils @emph{deklarieren}, statt ihn
2147 durch eine Folge von Befehlen wie @code{--install} u.Ä. zu generieren. Der
2148 Vorteil ist, dass die @var{Datei} unter Versionskontrolle gestellt werden
2149 kann, auf andere Maschinen zum Reproduzieren desselben Profils kopiert
2150 werden kann und Ähnliches.
2152 @c FIXME: Add reference to (guix profile) documentation when available.
2153 Der Code in der @var{Datei} muss ein @dfn{Manifest}-Objekt liefern, was
2154 ungefähr einer Liste von Paketen entspricht:
2156 @findex packages->manifest
2158 (use-package-modules guile emacs)
2163 ;; Eine bestimmte Paketausgabe nutzen.
2164 (list guile-2.0 "debug")))
2167 @findex specifications->manifest
2168 In diesem Beispiel müssen wir wissen, welche Module die Variablen
2169 @code{emacs} und @code{guile-2.0} definieren, um die richtige Angabe mit
2170 @code{use-package-modules} machen zu können, was umständlich sein kann. Wir
2171 können auch normale Paketnamen angeben und sie durch
2172 @code{specifications->manifest} zu den entsprechenden Paketobjekten
2173 auflösen, zum Beispiel so:
2176 (specifications->manifest
2177 '("emacs" "guile@@2.2" "guile@@2.2:debug"))
2182 @cindex Zurücksetzen von Transaktionen
2183 @cindex Transaktionen, zurücksetzen
2184 Wechselt zur vorherigen @dfn{Generation} des Profils zurück — d.h. macht die
2185 letzte Transaktion rückgängig.
2187 In Verbindung mit Befehlszeilenoptionen wie @code{--install} wird zuerst
2188 zurückgesetzt, bevor andere Aktionen durchgeführt werden.
2190 Ein Rücksetzen der ersten Generation, die installierte Pakete enthält,
2191 wechselt das Profil zur @dfn{nullten Generation}, die keinerlei Dateien
2192 enthält, abgesehen von Metadaten über sich selbst.
2194 Nach dem Zurücksetzen überschreibt das Installieren, Entfernen oder
2195 Aktualisieren von Paketen vormals zukünftige Generationen, d.h. der Verlauf
2196 der Generationen eines Profils ist immer linear.
2198 @item --switch-generation=@var{Muster}
2199 @itemx -S @var{Muster}
2200 @cindex Generationen
2201 Wechselt zu der bestimmten Generation, die durch das @var{Muster} bezeichnet
2204 Als @var{Muster} kann entweder die Nummer einer Generation oder eine Nummer
2205 mit vorangestelltem »+« oder »-« dienen. Letzteres springt die angegebene
2206 Anzahl an Generationen vor oder zurück. Zum Beispiel kehrt
2207 @code{--switch-generation=+1} nach einem Zurücksetzen wieder zur neueren
2210 Der Unterschied zwischen @code{--roll-back} und
2211 @code{--switch-generation=-1} ist, dass @code{--switch-generation} keine
2212 nullte Generation erzeugen wird; existiert die angegebene Generation nicht,
2213 bleibt schlicht die aktuelle Generation erhalten.
2215 @item --search-paths[=@var{Art}]
2217 Führe die Definitionen von Umgebungsvariablen auf, in Bash-Syntax, die nötig
2218 sein könnten, um alle installierten Pakete nutzen zu können. Diese
2219 Umgebungsvariablen werden benutzt, um die @dfn{Suchpfade} für Dateien
2220 festzulegen, die von einigen installierten Paketen benutzt werden.
2222 Zum Beispiel braucht GCC die Umgebungsvariablen @code{CPATH} und
2223 @code{LIBRARY_PATH}, um zu wissen, wo sich im Benutzerprofil Header und
2224 Bibliotheken befinden (@pxref{Environment Variables,,, gcc, Using the GNU
2225 Compiler Collection (GCC)}). Wenn GCC und, sagen wir, die C-Bibliothek im
2226 Profil installiert sind, schlägt @code{--search-paths} also vor, diese
2227 Variablen jeweils auf @code{@var{profile}/include} und
2228 @code{@var{profile}/lib} verweisen zu lassen.
2230 Die typische Nutzung ist, in der Shell diese Variablen zu definieren:
2233 $ eval `guix package --search-paths`
2236 Als @var{Art} kann entweder @code{exact}, @code{prefix} oder @code{suffix}
2237 gewählt werden, wodurch die gelieferten Definitionen der Umgebungsvariablen
2238 entweder exakt die Einstellungen für Guix meldet, oder sie als Präfix oder
2239 Suffix an den aktuellen Wert dieser Variablen anhängt. Gibt man keine
2240 @var{Art} an, wird der Vorgabewert @code{exact} verwendet.
2242 Diese Befehlszeilenoption kann auch benutzt werden, um die
2243 @emph{kombinierten} Suchpfade mehrerer Profile zu berechnen. Betrachten Sie
2247 $ guix package -p foo -i guile
2248 $ guix package -p bar -i guile-json
2249 $ guix package -p foo -p bar --search-paths
2252 Der letzte Befehl oben meldet auch die Definition der Umgebungsvariablen
2253 @code{GUILE_LOAD_PATH}, obwohl für sich genommen weder @file{foo} noch
2254 @file{bar} zu dieser Empfehlung führen würden.
2257 @item --profile=@var{Profil}
2258 @itemx -p @var{Profil}
2259 Auf @var{Profil} anstelle des Standardprofils des Benutzers arbeiten.
2261 @cindex Kollisionen, in einem Profil
2262 @cindex Paketkollisionen in Profilen
2263 @cindex Profilkollisionen
2264 @item --allow-collisions
2265 Kollidierende Pakete im neuen Profil zulassen. Benutzung auf eigene Gefahr!
2267 Standardmäßig wird @command{guix package} @dfn{Kollisionen} als Fehler
2268 auffassen und melden. Zu Kollisionen kommt es, wenn zwei oder mehr
2269 verschiedene Versionen oder Varianten desselben Pakets im Profil landen.
2272 Erzeugt ausführliche Textausgaben. Insbesondere wird auch das
2273 Erstellungsprotokoll der Umgebung auf dem Standard-Fehler-Port (stderr)
2277 Erstellt das Profil mit dem Bootstrap-Guile. Diese Option ist nur für
2278 Entwickler der Distribution nützlich.
2282 Zusätzlich zu diesen Aktionen unterstützt @command{guix package} folgende
2283 Befehlszeilenoptionen, um den momentanen Zustand eines Profils oder die
2284 Verfügbarkeit von Paketen nachzulesen:
2288 @item --search=@var{Regexp}
2289 @itemx -s @var{Regexp}
2290 @cindex Suche nach Paketen
2291 Führt alle verfügbaren Pakete auf, deren Name, Zusammenfassung oder
2292 Beschreibung zum regulären Ausdruck @var{Regexp} passt, sortiert nach ihrer
2293 Relevanz. Alle Metadaten passender Pakete werden im @code{recutils}-Format
2294 geliefert (@pxref{Top, GNU recutils databases,, recutils, GNU recutils
2297 So können bestimmte Felder mit dem Befehl @command{recsel} extrahiert
2298 werden, zum Beispiel:
2301 $ guix package -s malloc | recsel -p name,version,relevance
2315 Ebenso kann der Name aller zu den Bedingungen der GNU@tie{}LGPL, Version 3,
2316 verfügbaren Pakete ermittelt werden:
2319 $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
2326 Es ist auch möglich, Suchergebnisse näher einzuschränken, indem Sie
2327 @code{-s} mehrmals übergeben. Zum Beispiel liefert folgender Befehl eines
2328 Liste von Brettspielen:
2331 $ guix package -s '\<board\>' -s game | recsel -p name
2336 Würden wir @code{-s game} weglassen, bekämen wir auch Software-Pakete
2337 aufgelistet, die mit »printed circuit boards« (elektronischen Leiterplatten)
2338 zu tun haben; ohne die spitzen Klammern um @code{board} bekämen wir auch
2339 Pakete, die mit »keyboards« (Tastaturen, oder musikalischen Keyboard) zu tun
2342 Es ist Zeit für ein komplexeres Beispiel. Folgender Befehl sucht
2343 kryptographische Bibliotheken, filtert Haskell-, Perl-, Python- und
2344 Ruby-Bibliotheken heraus und gibt Namen und Zusammenfassung passender Pakete
2348 $ guix package -s crypto -s library | \
2349 recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis
2353 @xref{Selection Expressions,,, recutils, GNU recutils manual} enthält
2354 weitere Informationen über @dfn{Auswahlausdrücke} mit @code{recsel -e}.
2356 @item --show=@var{Paket}
2357 Zeigt Details über das @var{Paket} aus der Liste verfügbarer Pakete, im
2358 @code{recutils}-Format (@pxref{Top, GNU recutils databases,, recutils, GNU
2362 $ guix package --show=python | recsel -p name,version
2370 Sie können auch den vollständigen Namen eines Pakets angeben, um Details nur
2371 über diese Version angezeigt zu bekommen:
2373 $ guix package --show=python@@3.4 | recsel -p name,version
2380 @item --list-installed[=@var{Regexp}]
2381 @itemx -I [@var{Regexp}]
2382 Listet die derzeit installierten Pakete im angegebenen Profil auf, die
2383 zuletzt installierten Pakete zuletzt. Wenn ein regulärer Ausdruck
2384 @var{Regexp} angegeben wird, werden nur installierte Pakete aufgeführt,
2385 deren Name zu @var{Regexp} passt.
2387 Zu jedem installierten Paket werden folgende Informationen angezeigt, durch
2388 Tabulatorzeichen getrennt: der Paketname, die Version als Zeichenkette,
2389 welche Teile des Pakets installiert sind (zum Beispiel @code{out}, wenn die
2390 Standard-Paketausgabe installiert ist, @code{include}, wenn seine Header
2391 installiert sind, usw.) und an welchem Pfad das Paket im Store zu finden
2394 @item --list-available[=@var{Regexp}]
2395 @itemx -A [@var{Regexp}]
2396 Listet Pakete auf, die in der aktuell installierten Distribution dieses
2397 Systems verfügbar sind (@pxref{GNU-Distribution}). Wenn ein regulärer
2398 Ausdruck @var{Regexp} angegeben wird, werden nur Pakete aufgeführt, deren
2399 Name zum regulären Ausdruck @var{Regexp} passt.
2401 Zu jedem Paket werden folgende Informationen getrennt durch Tabulatorzeichen
2402 ausgegeben: der Name, die Version als Zeichenkette, die Teile des Programms
2403 (@pxref{Pakete mit mehreren Ausgaben.}) und die Stelle im Quellcode, an der
2404 das Paket definiert ist.
2406 @item --list-generations[=@var{Muster}]
2407 @itemx -l [@var{Muster}]
2408 @cindex Generationen
2409 Liefert eine Liste der Generationen zusammen mit dem Datum, an dem sie
2410 erzeugt wurden; zu jeder Generation werden zudem die installierten Pakete
2411 angezeigt, zuletzt installierte Pakete zuletzt. Beachten Sie, dass die
2412 nullte Generation niemals angezeigt wird.
2414 Zu jedem installierten Paket werden folgende Informationen durch
2415 Tabulatorzeichen getrennt angezeigt: der Name des Pakets, die Version als
2416 Zeichenkette, welcher Teil des Pakets installiert ist (@pxref{Pakete mit mehreren Ausgaben.}) und an welcher Stelle sich das Paket im Store befindet.
2418 Wenn ein @var{Muster} angegeben wird, liefert der Befehl nur dazu passende
2419 Generationen. Gültige Muster sind zum Beispiel:
2422 @item @emph{Ganze Zahlen und kommagetrennte ganze Zahlen}. Beide Muster bezeichnen
2423 Generationsnummern. Zum Beispiel liefert @code{--list-generations=1} die
2426 Durch @code{--list-generations=1,8,2} werden drei Generationen in der
2427 angegebenen Reihenfolge angezeigt. Weder Leerzeichen noch ein Komma am
2428 Schluss der Liste ist erlaubt.
2430 @item @emph{Bereiche}. @code{--list-generations=2..9} gibt die
2431 angegebenen Generationen und alles dazwischen aus. Beachten Sie, dass der
2432 Bereichsanfang eine kleinere Zahl als das Bereichsende sein muss.
2434 Sie können auch kein Bereichsende angeben, zum Beispiel liefert
2435 @code{--list-generations=2..} alle Generationen ab der zweiten.
2437 @item @emph{Zeitdauern}. Sie können auch die letzten @emph{N}@tie{}Tage, Wochen
2438 or months by passing an integer along with the first letter of the
2439 duration. For example, @code{--list-generations=20d} lists generations that
2440 are up to 20 days old.
2443 @item --delete-generations[=@var{Muster}]
2444 @itemx -d [@var{Muster}]
2445 Wird kein @var{Muster} angegeben, werden alle Generationen außer der
2448 Dieser Befehl akzeptiert dieselben Muster wie
2449 @option{--list-generations}. Wenn ein @var{Muster} angegeben wird, werden
2450 die passenden Generationen gelöscht. Wenn das @var{Muster} für eine
2451 Zeitdauer steht, werden diejenigen Generationen gelöscht, die @emph{älter}
2452 als die angegebene Dauer sind. Zum Beispiel löscht
2453 @code{--delete-generations=1m} die Generationen, die mehr als einen Monat
2456 Falls die aktuelle Generation zum Muster passt, wird sie @emph{nicht}
2457 gelöscht. Auch die nullte Generation wird niemals gelöscht.
2459 Beachten Sie, dass Sie auf gelöschte Generationen nicht zurückwechseln
2460 können. Dieser Befehl sollte also nur mit Vorsicht benutzt werden.
2464 Zu guter Letzt können Sie, da @command{guix package} Erstellungsprozesse zu
2465 starten vermag, auch alle gemeinsamen Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}) verwenden. Auch Paketumwandlungsoptionen wie
2466 @option{--with-source} sind möglich (@pxref{Paketumwandlungsoptionen}). Beachten Sie jedoch, dass die verwendeten
2467 Paketumwandlungsoptionen verloren gehen, nachdem Sie die Pakete aktualisiert
2468 haben. Damit Paketumwandlungen über Aktualisierungen hinweg erhalten
2469 bleiben, sollten Sie Ihre eigene Paketvariante in einem Guile-Modul
2470 definieren und zur Umgebungsvariablen @code{GUIX_PACKAGE_PATH} hinzufügen
2471 (@pxref{Pakete definieren}).
2477 @cindex vorerstellte Binärdateien
2478 Guix kann transparent Binär- oder Quelldateien ausliefern. Das heißt, Dinge
2479 können sowohl lokal erstellt, als auch als vorerstellte Objekte von einem
2480 Server heruntergeladen werden, oder beides gemischt. Wir bezeichnen diese
2481 vorerstellten Objekte als @dfn{Substitute} — sie substituieren lokale
2482 Erstellungsergebnisse. In vielen Fällen geht das Herunterladen eines
2483 Substituts wesentlich schneller, als Dinge lokal zu erstellen.
2485 Substitute können alles sein, was das Ergebnis einer Ableitungserstellung
2486 ist (@pxref{Ableitungen}). Natürlich sind sie üblicherweise vorerstellte
2487 Paket-Binärdateien, aber wenn zum Beispiel ein Quell-Tarball das Ergebnis
2488 einer Ableitungserstellung ist, kann auch er als Substitut verfügbar sein.
2491 * Offizieller Substitut-Server:: Eine besondere Quelle von Substituten.
2492 * Substitut-Server autorisieren:: Wie man Substitute an- und abschaltet.
2493 * Substitutauthentifizierung:: Wie Guix Substitute verifiziert.
2494 * Proxy-Einstellungen:: Wie Sie Substitute über einen Proxy beziehen.
2495 * Fehler bei der Substitution:: Was passiert, wenn die Substitution
2497 * Vom Vertrauen gegenüber Binärdateien:: Wie können Sie diesem binären
2501 @node Offizieller Substitut-Server
2502 @subsection Offizieller Substitut-Server
2506 Der Server @code{mirror.hydra.gnu.org} ist die Façade für eine offizielle
2507 »Build-Farm«, ein Erstellungswerk, das kontinuierlich Guix-Pakete für einige
2508 Prozessorarchitekturen erstellt und sie als Substitute zur Verfügung
2509 stellt. Dies ist die standardmäßige Quelle von Substituten; durch Übergeben
2510 der Befehlszeilenoption @option{--substitute-urls} an entweder den
2511 @command{guix-daemon} (@pxref{daemon-substitute-urls,, @code{guix-daemon
2512 --substitute-urls}}) oder Client-Werkzeuge wie @command{guix package}
2513 (@pxref{client-substitute-urls,, client @option{--substitute-urls} option})
2514 kann eine abweichende Einstellung benutzt werden.
2516 Substitut-URLs können entweder HTTP oder HTTPS sein. HTTPS wird empfohlen,
2517 weil die Kommunikation verschlüsselt ist; umgekehrt kann bei HTTP die
2518 Kommunikation belauscht werden, wodurch der Angreifer zum Beispiel erfahren
2519 könnte, ob Ihr System über noch nicht behobene Sicherheitsschwachstellen
2522 Substitute von der offiziellen Build-Farm sind standardmäßig erlaubt, wenn
2523 Sie die Guix-System-Distribution verwenden (@pxref{GNU-Distribution}). Auf
2524 Fremddistributionen sind sie allerdings standardmäßig ausgeschaltet, solange
2525 Sie sie nicht ausdrücklich in einem der empfohlenen Installationsschritte
2526 erlaubt haben (@pxref{Installation}). Die folgenden Absätze beschreiben, wie
2527 Sie Substitute für die offizielle Build-Farm an- oder ausschalten; dieselbe
2528 Prozedur kann auch benutzt werden, um Substitute für einen beliebigen
2529 anderen Substitutsserver zu erlauben.
2531 @node Substitut-Server autorisieren
2532 @subsection Substitut-Server autorisieren
2535 @cindex Substitute, deren Autorisierung
2536 @cindex Access Control List (ACL), für Substitute
2537 @cindex ACL (Access Control List), für Substitute
2538 Um es Guix zu gestatten, Substitute von @code{hydra.gnu.org} oder einem
2539 Spiegelserver davon herunterzuladen, müssen Sie den zugehörigen öffentlichen
2540 Schlüssel zur Access Control List (ACL, Zugriffssteuerungsliste) für
2541 Archivimporte hinzufügen, mit Hilfe des Befehls @command{guix archive}
2542 (@pxref{Aufruf von guix archive}). Dies impliziert, dass Sie darauf vertrauen,
2543 dass @code{hydra.gnu.org} nicht kompromittiert wurde und echte Substitute
2546 Der öffentliche Schlüssel für @code{hydra.gnu.org} wird zusammen mit Guix
2547 installiert, in das Verzeichnis
2548 @code{@var{prefix}/share/guix/hydra.gnu.org.pub}, wobei @var{prefix} das
2549 Installationspräfix von Guix ist. Wenn Sie Guix aus seinem Quellcode heraus
2550 installieren, stellen Sie sicher, dass Sie die GPG-Signatur von
2551 @file{guix-@value{VERSION}.tar.gz} prüfen, worin sich dieser öffentliche
2552 Schlüssel befindet. Dann können Sie so etwas wie hier ausführen:
2555 # guix archive --authorize < @var{prefix}/share/guix/hydra.gnu.org.pub
2558 @quotation Anmerkung
2559 Genauso enthält die Datei @file{berlin.guixsd.org.pub} den öffentlichen
2560 Schlüssel für die neue Build-Farm des Guix-Projekts, die unter
2561 @indicateurl{https://berlin.guixsd.org} erreichbar ist.
2563 Derzeit, als dieser Text geschrieben wurde, wird @code{berlin.guixsd.org}
2564 ausgebaut, um besser skalieren zu können, aber Sie könnten es
2565 ausprobieren. Dahinter stecken 20 x86_64-/i686-Erstellungsknoten, die
2566 Substitute früher anbieten könnten als @code{mirror.hydra.gnu.org}.
2569 Sobald es eingerichtet wurde, sollte sich die Ausgabe eines Befehls wie
2570 @code{guix build} von so etwas:
2573 $ guix build emacs --dry-run
2574 Folgende Ableitungen würden erstellt:
2575 /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
2576 /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
2577 /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
2578 /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
2583 in so etwas verwandeln:
2586 $ guix build emacs --dry-run
2587 112.3 MB würden heruntergeladen:
2588 /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
2589 /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
2590 /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
2591 /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
2596 Das zeigt an, dass Substitute von @code{hydra.gnu.org} nutzbar sind und für
2597 zukünftige Erstellungen heruntergeladen werden, wann immer es möglich ist.
2599 @cindex Substitute, wie man sie ausschaltet
2600 Der Substitutsmechanismus kann global ausgeschaltet werden, indem Sie dem
2601 @code{guix-daemon} beim Starten die Befehlszeilenoption
2602 @code{--no-substitutes} übergeben (@pxref{Aufruf des guix-daemon}). Er kann
2603 auch temporär ausgeschaltet werden, indem Sie @code{--no-substitutes} an
2604 @command{guix package}, @command{guix build} und andere
2605 Befehlszeilenwerkzeuge übergeben.
2607 @node Substitutauthentifizierung
2608 @subsection Substitutauthentifizierung
2610 @cindex digitale Signaturen
2611 Guix erkennt, wenn ein verfälschtes Substitut benutzt würde, und meldet
2612 einen Fehler. Ebenso werden Substitute ignoriert, die nich signiert sind,
2613 oder nicht mit einem in der ACL aufgelisteten Schlüssel signiert sind.
2615 Es gibt nur eine Ausnahme: Wenn ein unautorisierter Server Substitute
2616 anbietet, die @emph{Bit für Bit identisch} mit denen von einem autorisierten
2617 Server sind, können sie auch vom unautorisierten Server heruntergeladen
2618 werden. Zum Beispiel, angenommen wir haben zwei Substitutserver mit dieser
2619 Befehlszeilenoption ausgewählt:
2622 --substitute-urls="https://a.example.org https://b.example.org"
2626 @cindex Reproduzierbare Erstellungen
2627 Wenn in der ACL nur der Schlüssel für @code{b.example.org} aufgeführt wurde,
2628 aber @code{a.example.org} @emph{exakt dieselben} Substitute anbietet, wird
2629 Guix auch Substitute von @code{a.example.org} herunterladen, weil es in der
2630 Liste zuerst kommt und als Spiegelserver für @code{b.example.org} aufgefasst
2631 werden kann. In der Praxis haben unabhängige Maschinen bei der Erstellung
2632 normalerweise dieselben Binärdateien als Ergebnis, dank bit-reproduzierbarer
2633 Erstellungen (siehe unten).
2635 Wenn Sie HTTPS benutzen, wird das X.509-Zertifikat des Servers @emph{nicht}
2636 validiert (mit anderen Worten, die Identität des Servers wird nicht
2637 authentifiziert), entgegen dem, was HTTPS-Clients wie Web-Browser
2638 normalerweise tun. Da Guix Substitutinformationen selbst überprüft, wie oben
2639 erklärt, wäre es unnötig (wohingegen mit X.509-Zertifikaten geprüft wird, ob
2640 ein Domain-Name zu öffentlichen Schlüsseln passt).
2642 @node Proxy-Einstellungen
2643 @subsection Proxy-Einstellungen
2646 Substitute werden über HTTP oder HTTPS heruntergeladen. Die
2647 Umgebungsvariable @code{http_proxy} kann in der Umgebung von
2648 @command{guix-daemon} definiert werden und wirkt sich dann auf das
2649 Herunterladen von Substituten aus. Beachten Sie, dass der Wert von
2650 @code{http_proxy} in der Umgebung, in der @command{guix build},
2651 @command{guix package} und andere Client-Befehle ausgeführt werden,
2652 @emph{keine Rolle spielt}.
2654 @node Fehler bei der Substitution
2655 @subsection Fehler bei der Substitution
2657 Selbst wenn ein Substitut für eine Ableitung verfügbar ist, schlägt die
2658 versuchte Substitution manchmal fehl. Das kann aus vielen Gründen geschehen:
2659 die Substitutsserver könnten offline sein, das Substitut könnte kürzlich
2660 gelöscht worden sein, die Netzwerkverbindunge könnte unterbrochen worden
2663 Wenn Substitute aktiviert sind und ein Substitut für eine Ableitung zwar
2664 verfügbar ist, aber die versuchte Substitution fehlschlägt, kann Guix
2665 versuchen, die Ableitung lokal zu erstellen, je nachdem, ob
2666 @code{--fallback} übergeben wurde (@pxref{fallback-option,, common build
2667 option @code{--fallback}}). Genauer gesagt, wird keine lokale Erstellung
2668 durchgeführt, solange kein @code{--fallback} angegeben wurde, und die
2669 Ableitung wird als Fehlschlag angesehen. Wenn @code{--fallback} übergeben
2670 wurde, wird Guix versuchen, die Ableitung lokal zu erstellen, und ob die
2671 Ableitung erfolgreich ist oder nicht, hängt davon ab, ob die lokale
2672 Erstellung erfolgreich ist oder nicht. Beachten Sie, dass, falls Substitute
2673 ausgeschaltet oder erst gar kein Substitut verfügbar ist, @emph{immer} eine
2674 lokale Erstellung durchgeführt wird, egal ob @code{--fallback} übergeben
2677 Um eine Vorstellung zu bekommen, wieviele Substitute gerade verfügbar sind,
2678 können Sie den Befehl @command{guix weather} benutzen (@pxref{Aufruf von guix weather}). Dieser Befehl zeigt Statistiken darüber an, wie es um die von
2679 einem Server verfügbaren Substitute steht.
2681 @node Vom Vertrauen gegenüber Binärdateien
2682 @subsection Vom Vertrauen gegenüber Binärdateien
2684 @cindex Vertrauen, gegenüber vorerstellten Binärdateien
2685 Derzeit hängt die Kontrolle jedes Individuums über seine Rechner von
2686 Institutionen, Unternehmen und solchen Gruppierungen ab, die über genug
2687 Macht und Entschlusskraft verfügen, die Rechnerinfrastruktur zu sabotieren
2688 und ihre Schwachstellen auszunutzen. Auch wenn es bequem ist, Substitute von
2689 @code{hydra.gnu.org} zu benutzen, ermuntern wir Nutzer, auch selbst
2690 Erstellungen durchzuführen oder gar ihre eigene Build-Farm zu betreiben,
2691 damit @code{hydra.gnu.org} ein weniger interessantes Ziel wird. Eine Art,
2692 uns zu helfen, ist, die von Ihnen erstellte Software mit dem Befehl
2693 @command{guix publish} zu veröffentlichen, damit andere eine größere Auswahl
2694 haben, von welchem Server sie Substitute beziehen möchten (@pxref{Aufruf von guix publish}).
2696 Guix hat die richtigen Grundlagen, um die Reproduzierbarkeit von
2697 Erstellungen zu maximieren (@pxref{Funktionalitäten}). In den meisten Fällen sollten
2698 unabhängige Erstellungen eines bestimmten Pakets zu bitweise identischen
2699 Ergebnissen führen. Wir können also mit Hilfe einer vielschichtigen Menge an
2700 unabhängigen Paketerstellungen die Integrität unseres Systems besser
2701 gewährleisten. Der Befehl @command{guix challenge} hat das Ziel, Nutzern zu
2702 ermöglichen, Substitutserver zu beurteilen, und Entwickler dabei zu
2703 unterstützen, nichtdeterministische Paketerstellungen zu finden
2704 (@pxref{Aufruf von guix challenge}). Ebenso ermöglicht es die
2705 Befehlszeilenoption @option{--check} von @command{guix build}, dass Nutzer
2706 bereits installierte Substitute auf Echtheit zu prüfen, indem sie lokal
2707 nachgebaut werden (@pxref{build-check, @command{guix build --check}}).
2709 In Zukunft wollen wir, dass Guix Binärdateien an und von Nutzern
2710 peer-to-peer veröffentlichen kann. Wenn Sie mit uns dieses Projekt
2711 diskuttieren möchten, kommen Sie auf unsere Mailing-Liste
2712 @email{guix-devel@@gnu.org}.
2714 @node Pakete mit mehreren Ausgaben.
2715 @section Pakete mit mehreren Ausgaben.
2717 @cindex mehrere Ausgaben, bei Paketen
2718 @cindex Paketausgaben
2721 Oft haben in Guix definierte Pakete eine einzige @dfn{Ausgabe} — d.h. aus
2722 dem Quellpaket entsteht genau ein Verzeichnis im Store. Wenn Sie
2723 @command{guix package -i glibc} ausführen, wird die Standard-Paketausgabe
2724 des GNU-libc-Pakets installiert; die Standardausgabe wird @code{out}
2725 genannt, aber ihr Name kann weggelassen werden, wie sie an obigem Befehl
2726 sehen. In diesem speziellen Fall enthält die Standard-Paketausgabe von
2727 @code{glibc} alle C-Headerdateien, gemeinsamen Bibliotheken (»Shared
2728 Libraries«), statische Bibliotheken (»Static Libraries«), Dokumentation für
2729 Info sowie andere zusätzliche Dateien.
2731 Manchmal ist es besser, die verschiedenen Arten von Dateien, die aus einem
2732 einzelnen Quellpaket hervorgehen, in getrennte Ausgaben zu unterteilen. Zum
2733 Beispiel installiert die GLib-C-Bibliothek (die von GTK+ und damit
2734 zusammenhängenden Paketen benutzt wird) mehr als 20 MiB an HTML-Seiten mit
2735 Referenzdokumentation. Um den Nutzern, die das nicht brauchen, Platz zu
2736 sparen, wird die Dokumentation in einer separaten Ausgabe abgelegt, genannt
2737 @code{doc}. Um also die Hauptausgabe von GLib zu installieren, zu der alles
2738 außer der Dokumentation gehört, ist der Befehl:
2741 guix package -i glib
2744 @cindex Dokumentation
2745 Der Befehl, um die Dokumentation zu installieren, ist:
2748 guix package -i glib:doc
2751 Manche Pakete installieren Programme mit unterschiedlich großem
2752 »Abhängigkeiten-Fußabdruck«. Zum Beispiel installiert das Paket WordNet
2753 sowohl Befehlszeilenwerkzeuge als auch grafische Benutzerschnittstellen
2754 (GUIs). Erstere hängen nur von der C-Bibliothek ab, während Letztere auch
2755 von Tcl/Tk und den zu Grunde liegenden X-Bibliotheken abhängen. Jedenfalls
2756 belassen wir deshalb die Befehlszeilenwerkzeuge in der
2757 Standard-Paketausgabe, während sich die GUIs in einer separaten Ausgabe
2758 befinden. So können Benutzer, die die GUIs nicht brauchen, Platz sparen. Der
2759 Befehl @command{guix size} kann dabei helfen, solche Situationen zu erkennen
2760 (@pxref{Aufruf von guix size}). @command{guix graph} kann auch helfen
2761 (@pxref{Aufruf von guix graph}).
2763 In der GNU-Distribution gibt es viele solche Pakete mit mehreren
2764 Ausgaben. Andere Konventionen für Ausgabenamen sind zum Beispiel @code{lib}
2765 für Bibliotheken und eventuell auch ihre Header-Dateien,, @code{bin} für
2766 eigenständige Programme und @code{debug} für Informationen zur
2767 Fehlerbehandlung (@pxref{Dateien zur Fehlersuche installieren}). Die Ausgaben eines
2768 Pakets stehen in der dritten Spalte der Anzeige von @command{guix package
2769 --list-available} (@pxref{Aufruf von guix package}).
2772 @node Aufruf von guix gc
2773 @section @command{guix gc} aufrufen
2776 @cindex Plattenspeicher
2777 Pakete, die zwar installiert sind, aber nicht benutzt werden, können vom
2778 @dfn{Müllsammler} entfernt werden. Mit dem Befehl @command{guix gc} können
2779 Benutzer den Müllsammler ausdrücklich aufrufen, um Speicher im Verzeichnis
2780 @file{/gnu/store} freizugeben. Dies ist der @emph{einzige} Weg, Dateien aus
2781 @file{/gnu/store} zu entfernen — das manuelle Entfernen von Dateien kann den
2782 Store irreparabel beschädigen!
2785 @cindex Müllsammlerwurzeln
2786 Der Müllsammler kennt eine Reihe von @dfn{Wurzeln}: Jede Datei in
2787 @file{/gnu/store}, die von einer Wurzel aus erreichbar ist, gilt als
2788 @dfn{lebendig} und kann nicht entfernt werden; jede andere Datei gilt als
2789 @dfn{tot} und ist ein Kandidat, gelöscht zu werden. Die Menge der
2790 Müllsammlerwurzeln (kurz auch »GC-Wurzeln«, von englisch »Garbage
2791 Collector«) umfasst Standard-Benutzerprofile; standardmäßig werden diese
2792 Müllsammlerwurzeln durch symbolische Verknüpfungen in
2793 @file{/var/guix/gcroots} dargestellt. Neue Müllsammlerwurzeln können zum
2794 Beispiel mit @command{guix build --root} festgelegt werden (@pxref{Aufruf von guix build}).
2796 Bevor Sie mit @code{guix gc --collect-garbage} Speicher freimachen, wollen
2797 Sie vielleicht alte Generationen von Benutzerprofilen löschen, damit alte
2798 Paketerstellungen von diesen Generationen entfernt werden können. Führen Sie
2799 dazu @code{guix package --delete-generations} aus (@pxref{Aufruf von guix package}).
2801 Unsere Empfehlung ist, dass Sie den Müllsammler regelmäßig laufen lassen und
2802 wenn Sie wenig freien Speicherplatz zur Verfügung haben. Um zum Beispiel
2803 sicherzustellen, dass Sie mindestens 5@tie{}GB auf Ihrer Platte zur
2804 Verfügung haben, benutzen Sie einfach:
2810 Es ist völlig sicher, dafür eine nicht interaktive, regelmäßige
2811 Auftragsausführung vorzugeben (@pxref{Geplante Auftragsausführung}, für eine
2812 Erklärung, wie man das in GuixSD tun kann). @command{guix gc} ohne
2813 Befehlszeilenargumente auszuführen, lässt so viel Müll wie möglich sammeln,
2814 aber das ist oft nicht, was man will, denn so muss man unter Umständen
2815 Software erneut erstellen oder erneut herunterladen, weil der Müllsammler
2816 sie als »tot« ansieht, sie aber zur Erstellung anderer Software wieder
2817 gebraucht wird — das trifft zum Beispiel auf die Compiler-Toolchain zu.
2819 Der Befehl @command{guix gc} hat drei Arbeitsmodi: Er kann benutzt werden,
2820 um als Müllsammler tote Dateien zu entfernen (das Standardverhalten), um
2821 ganz bestimmte, angegebene Datein zu löschen (mit der Befehlszeilenoption
2822 @code{--delete}), um Müllsammlerinformationen auszugeben oder
2823 fortgeschrittenere Anfragen zu verarbeiten. Die
2824 Müllsammler-Befehlszeilenoptionen sind wie folgt:
2827 @item --collect-garbage[=@var{Minimum}]
2828 @itemx -C [@var{Minimum}]
2829 Lässt Müll sammeln — z.B. nicht erreichbare Dateien in @file{/gnu/store} und
2830 seinen Unterverzeichnissen. Wird keine andere Befehlszeilenoption angegeben,
2831 wird standardmäßig diese durchgeführt.
2833 Wenn ein @var{Minimum} angegeben wurde, hört der Müllsammler auf, sobald
2834 @var{Minimum} Bytes gesammelt wurden. Das @var{Minimum} kann die Anzahl der
2835 Bytes bezeichnen oder mit einer Einheit als Suffix versehen sein, wie etwa
2836 @code{MiB} für Mebibytes und @code{GB} für Gigabytes (@pxref{Block size,
2837 size specifications,, coreutils, GNU Coreutils}).
2839 Wird kein @var{Minimum} angegeben, sammelt der Müllsammler allen Müll.
2841 @item --free-space=@var{Menge}
2842 @itemx -F @var{Menge}
2843 Sammelt Müll, bis die angegebene @var{Menge} an freiem Speicher in
2844 @file{/gnu/store} zur Verfügung steht, falls möglich; die @var{Menge} ist
2845 eine Speichergröße wie @code{500MiB}, wie oben beschrieben.
2847 Wenn die angegebene @var{Menge} oder mehr bereits in @file{/gnu/store} frei
2848 verfügbar ist, passiert nichts.
2852 Versucht, alle als Argumente angegebenen Dateien oder Verzeichnisse im Store
2853 zu löschen. Dies schlägt fehl, wenn manche der Dateien oder Verzeichnisse
2854 nicht im Store oder noch immer lebendig sind.
2856 @item --list-failures
2857 Store-Objekte auflisten, die zwischengespeicherten Erstellungsfehlern
2860 Hierbei wird nichts ausgegeben, sofern der Daemon nicht mit
2861 @option{--cache-failures} gestartet wurde (@pxref{Aufruf des guix-daemon,
2862 @option{--cache-failures}}).
2864 @item --clear-failures
2865 Die angegebenen Store-Objekte aus dem Zwischenspeicher für fehlgeschlagene
2866 Erstellungen entfernen.
2868 Auch diese Option macht nur Sinn, wenn der Daemon mit
2869 @option{--cache-failures} gestartet wurde. Andernfalls passiert nichts.
2872 Zeigt die Liste toter Dateien und Verzeichnisse an, die sich noch im Store
2873 befinden — das heißt, Dateien, die von keiner Wurzel mehr erreichbar sind.
2876 Zeige die Liste lebendiger Store-Dateien und -Verzeichnisse.
2880 Außerdem können Referenzen unter bestehenden Store-Dateien gefunden werden:
2886 @cindex Paketabhängigkeiten
2887 Listet die referenzierten bzw. sie referenzierenden Objekte der angegebenen
2893 Listet alle Voraussetzungen der als Argumente übergebenen Store-Dateien
2894 auf. Voraussetzungen sind die Store-Dateien selbst, ihre Referenzen sowie
2895 die Referenzen davon, rekursiv. Mit anderen Worten, die zurückgelieferte
2896 Liste ist der @dfn{transitive Abschluss} dieser Store-Dateien.
2898 Der Abschnitt @xref{Aufruf von guix size} erklärt ein Werkzeug, um den
2899 Speicherbedarf des Abschlusses eines Elements zu ermitteln. Siehe
2900 @xref{Aufruf von guix graph} für ein Werkzeug, um den Referenzgraphen zu
2905 Liefert die Ableitung(en), die zu den angegebenen Store-Objekten führen
2906 (@pxref{Ableitungen}).
2908 Zum Beispiel liefert dieser Befehl:
2911 guix gc --derivers `guix package -I ^emacs$ | cut -f4`
2915 die @file{.drv}-Datei(en), die zum in Ihrem Profil installierten
2916 @code{emacs}-Paket führen.
2918 Beachten Sie, dass es auch sein kann, dass keine passenden
2919 @file{.drv}-Dateien existieren, zum Beispiel wenn diese Dateien bereits dem
2920 Müllsammler zum Opfer gefallen sind. Es kann auch passieren, dass es mehr
2921 als eine passende @file{.drv} gibt, bei Ableitungen mit fester Ausgabe.
2924 Zuletzt können Sie mit folgenden Befehlszeilenoptionen die Integrität des
2925 Stores prüfen und den Plattenspeicherverbrauch im Zaum halten.
2929 @item --verify[=@var{Optionen}]
2930 @cindex Integrität, des Stores
2931 @cindex Integritätsprüfung
2932 Die Integrität des Stores verifizieren
2934 Standardmäßig wird sichergestellt, dass alle Store-Objekte, die in der
2935 Datenbank des Daemons als gültig markiert wurden, auch tatsächlich in
2936 @file{/gnu/store} existieren.
2938 Wenn angegeben, müssen die @var{Optionen} eine kommagetrennte Liste aus
2939 mindestens einem der Worte @code{contents} und @code{repair} sein.
2941 Wenn Sie @option{--verify=contents} übergeben, berechnet der Daemon den Hash
2942 des Inhalts jedes Store-Objekts und vergleicht ihn mit dem Hash in der
2943 Datenbank. Sind die Hashes ungleich, wird eine Datenbeschädigung
2944 gemeldet. Weil dabei @emph{alle Dateien im Store} durchlaufen werden, kann
2945 der Befehl viel Zeit brauchen, besonders auf Systemen mit langsamer Platte.
2947 @cindex Store, reparieren
2948 @cindex Datenbeschädigung, Behebung
2949 Mit @option{--verify=repair} oder @option{--verify=contents,repair} versucht
2950 der Daemon, beschädigte Store-Objekte zu reparieren, indem er Substitute für
2951 selbige herunterlädt (@pxref{Substitute}). Weil die Reparatur nicht atomar
2952 und daher womöglich riskant ist, kann nur der Systemadministrator den Befehl
2953 benutzen. Eine weniger aufwendige Alternative, wenn Sie wissen, welches
2954 Objekt beschädigt ist, ist, @command{guix build --repair} zu benutzen
2955 (@pxref{Aufruf von guix build}).
2958 @cindex Deduplizieren
2959 Den Store durch Nutzung harter Verknüpfungen für identische Dateien
2960 optimieren — mit anderen Worten wird der Store @dfn{dedupliziert}.
2962 Der Daemon führt Deduplizierung automatisch nach jeder erfolgreichen
2963 Erstellung und jedem Importieren eines Archivs durch, sofern er nicht mit
2964 @code{--disable-deduplication} (@pxref{Aufruf des guix-daemon,
2965 @code{--disable-deduplication}}) gestartet wurde. Diese Befehlszeilenoption
2966 brauchen Sie also in erster Linie dann, wenn der Daemon zuvor mit
2967 @code{--disable-deduplication} gestartet worden ist.
2971 @node Aufruf von guix pull
2972 @section @command{guix pull} aufrufen
2974 @cindex Aktualisieren von Guix
2975 @cindex Updaten von Guix
2976 @cindex @command{guix pull}
2978 Packages are installed or upgraded to the latest version available in the
2979 distribution currently available on your local machine. To update that
2980 distribution, along with the Guix tools, you must run @command{guix pull}:
2981 the command downloads the latest Guix source code and package descriptions,
2982 and deploys it. Source code is downloaded from a @uref{https://git-scm.com,
2983 Git} repository, by default the official GNU@tie{}Guix repository, though
2984 this can be customized.
2986 Danach wird @command{guix package} Pakete und ihre Versionen entsprechend
2987 der gerade heruntergeladenen Kopie von Guix benutzen. Nicht nur das, auch
2988 alle Guix-Befehle und Scheme-Module werden aus der neuesten Version von Guix
2989 kommen. Neue @command{guix}-Unterbefehle, die durch die Aktualisierung
2990 hinzugekommen sind, werden also auch verfügbar.
2992 Any user can update their Guix copy using @command{guix pull}, and the
2993 effect is limited to the user who run @command{guix pull}. For instance,
2994 when user @code{root} runs @command{guix pull}, this has no effect on the
2995 version of Guix that user @code{alice} sees, and vice versa.
2997 The result of running @command{guix pull} is a @dfn{profile} available under
2998 @file{~/.config/guix/current} containing the latest Guix. Thus, make sure
2999 to add it to the beginning of your search path so that you use the latest
3000 version, and similarly for the Info manual (@pxref{Dokumentation}):
3003 export PATH="$HOME/.config/guix/current/bin:$PATH"
3004 export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"
3007 The @code{--list-generations} or @code{-l} option lists past generations
3008 produced by @command{guix pull}, along with details about their provenance:
3012 Generation 1 Jun 10 2018 00:18:18
3014 repository URL: https://git.savannah.gnu.org/git/guix.git
3015 branch: origin/master
3016 commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe
3018 Generation 2 Jun 11 2018 11:02:49
3020 repository URL: https://git.savannah.gnu.org/git/guix.git
3021 branch: origin/master
3022 commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
3023 2 new packages: keepalived, libnfnetlink
3024 6 packages upgraded: emacs-nix-mode@@2.0.4,
3025 guile2.0-guix@@0.14.0-12.77a1aac, guix@@0.14.0-12.77a1aac,
3026 heimdal@@7.5.0, milkytracker@@1.02.00, nix@@2.0.4
3028 Generation 3 Jun 13 2018 23:31:07 (current)
3030 repository URL: https://git.savannah.gnu.org/git/guix.git
3031 branch: origin/master
3032 commit: 844cc1c8f394f03b404c5bb3aee086922373490c
3033 28 new packages: emacs-helm-ls-git, emacs-helm-mu, @dots{}
3034 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{}
3037 @ref{Invoking guix describe, @command{guix describe}}, for other ways to
3038 describe the current status of Guix.
3040 This @code{~/.config/guix/current} profile works like any other profile
3041 created by @command{guix package} (@pxref{Aufruf von guix package}). That is,
3042 you can list generations, roll back to the previous generation---i.e., the
3043 previous Guix---and so on:
3046 $ guix package -p ~/.config/guix/current --roll-back
3047 switched from generation 3 to 2
3048 $ guix package -p ~/.config/guix/current --delete-generations=1
3049 deleting /var/guix/profiles/per-user/charlie/current-guix-1-link
3052 Der Befehl @command{guix pull} wird in der Regel ohne Befehlszeilenargumente
3053 aufgerufen, aber er versteht auch folgende Befehlszeilenoptionen:
3056 @item --url=@var{URL}
3057 @itemx --commit=@var{Commit}
3058 @itemx --branch=@var{Branch}
3059 Download code from the specified @var{url}, at the given @var{commit} (a
3060 valid Git commit ID represented as a hexadecimal string), or @var{branch}.
3062 @cindex @file{channels.scm}, configuration file
3063 @cindex configuration file for channels
3064 These options are provided for convenience, but you can also specify your
3065 configuration in the @file{~/.config/guix/channels.scm} file or using the
3066 @option{--channels} option (see below).
3068 @item --channels=@var{file}
3069 @itemx -C @var{file}
3070 Read the list of channels from @var{file} instead of
3071 @file{~/.config/guix/channels.scm}. @var{file} must contain Scheme code
3072 that evaluates to a list of channel objects. @xref{Channels}, for more
3075 @item --list-generations[=@var{Muster}]
3076 @itemx -l [@var{Muster}]
3077 List all the generations of @file{~/.config/guix/current} or, if
3078 @var{pattern} is provided, the subset of generations that match
3079 @var{pattern}. The syntax of @var{pattern} is the same as with @code{guix
3080 package --list-generations} (@pxref{Aufruf von guix package}).
3082 @ref{Invoking guix describe}, for a way to display information about the
3083 current generation only.
3085 @item --profile=@var{Profil}
3086 @itemx -p @var{Profil}
3087 Use @var{profile} instead of @file{~/.config/guix/current}.
3091 Show which channel commit(s) would be used and what would be built or
3092 substituted but do not actually do it.
3095 Ausführliche Informationen ausgeben und Erstellungsprotokolle auf der
3096 Standardfehlerausgabe ausgeben.
3099 Use the bootstrap Guile to build the latest Guix. This option is only
3100 useful to Guix developers.
3103 The @dfn{channel} mechanism allows you to instruct @command{guix pull} which
3104 repository and branch to pull from, as well as @emph{additional}
3105 repositories containing package modules that should be deployed.
3106 @xref{Channels}, for more information.
3108 In addition, @command{guix pull} supports all the common build options
3109 (@pxref{Gemeinsame Erstellungsoptionen}).
3115 @cindex @file{channels.scm}, configuration file
3116 @cindex configuration file for channels
3117 @cindex @command{guix pull}, configuration file
3118 @cindex configuration of @command{guix pull}
3119 Guix and its package collection are updated by running @command{guix pull}
3120 (@pxref{Aufruf von guix pull}). By default @command{guix pull} downloads and
3121 deploys Guix itself from the official GNU@tie{}Guix repository. This can be
3122 customized by defining @dfn{channels} in the
3123 @file{~/.config/guix/channels.scm} file. A channel specifies a URL and
3124 branch of a Git repository to be deployed, and @command{guix pull} can be
3125 instructed to pull from one or more channels. In other words, channels can
3126 be used to @emph{customize} and to @emph{extend} Guix, as we will see below.
3128 @subsection Using a Custom Guix Channel
3130 The channel called @code{guix} specifies where Guix itself---its
3131 command-line tools as well as its package collection---should be
3132 downloaded. For instance, suppose you want to update from your own copy of
3133 the Guix repository at @code{example.org}, and specifically the
3134 @code{super-hacks} branch, you can write in
3135 @code{~/.config/guix/channels.scm} this specification:
3138 ;; Tell 'guix pull' to use my own repo.
3141 (url "https://example.org/my-guix.git")
3142 (branch "super-hacks")))
3146 From there on, @command{guix pull} will fetch code from the
3147 @code{super-hacks} branch of the repository at @code{example.org}.
3149 @subsection Specifying Additional Channels
3151 @cindex extending the package collection (channels)
3152 @cindex personal packages (channels)
3153 @cindex channels, for personal packages
3154 You can also specify @emph{additional channels} to pull from. Let's say you
3155 have a bunch of custom package variants or personal packages that you think
3156 would make little sense to contribute to the Guix project, but would like to
3157 have these packages transparently available to you at the command line. You
3158 would first write modules containing those package definitions
3159 (@pxref{Paketmodule}), maintain them in a Git repository, and then you
3160 and anyone else can use it as an additional channel to get packages from.
3163 @c What follows stems from discussions at
3164 @c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as
3165 @c earlier discussions on guix-devel@gnu.org.
3167 Before you, dear user, shout---``woow this is @emph{soooo coool}!''---and
3168 publish your personal channel to the world, we would like to share a few
3173 Before publishing a channel, please consider contributing your package
3174 definitions to Guix proper (@pxref{Mitwirken}). Guix as a project is
3175 open to free software of all sorts, and packages in Guix proper are readily
3176 available to all Guix users and benefit from the project's quality assurance
3180 When you maintain package definitions outside Guix, we, Guix developers,
3181 consider that @emph{the compatibility burden is on you}. Remember that
3182 package modules and package definitions are just Scheme code that uses
3183 various programming interfaces (APIs). We want to remain free to change
3184 these APIs to keep improving Guix, possibly in ways that break your
3185 channel. We never change APIs gratuitously, but we will @emph{not} commit
3186 to freezing APIs either.
3189 Corollary: if you're using an external channel and that channel breaks,
3190 please @emph{report the issue to the channel authors}, not to the Guix
3194 You've been warned! Having said this, we believe external channels are a
3195 practical way to exert your freedom to augment Guix' package collection and
3196 to share your improvements, which are basic tenets of
3197 @uref{https://www.gnu.org/philosophy/free-sw.html, free software}. Please
3198 email us at @email{guix-devel@@gnu.org} if you'd like to discuss this.
3201 Once you have a Git repository containing your own package modules, you can
3202 write @code{~/.config/guix/channels.scm} to instruct @command{guix pull} to
3203 pull from your personal channel @emph{in addition} to the default Guix
3206 @vindex %default-channels
3208 ;; Add my personal packages to those Guix provides.
3210 (name 'my-personal-packages)
3211 (url "https://example.org/personal-packages.git"))
3216 Note that the snippet above is (as always!)@: Scheme code; we use
3217 @code{cons} to add a channel the list of channels that the variable
3218 @code{%default-channels} is bound to (@pxref{Pairs, @code{cons} and lists,,
3219 guile, GNU Guile Reference Manual}). With this file in place, @command{guix
3220 pull} builds not only Guix but also the package modules from your own
3221 repository. The result in @file{~/.config/guix/current} is the union of
3222 Guix with your own package modules:
3225 $ guix pull --list-generations
3227 Generation 19 Aug 27 2018 16:20:48
3229 repository URL: https://git.savannah.gnu.org/git/guix.git
3231 commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
3232 my-personal-packages dd3df5e
3233 repository URL: https://example.org/personal-packages.git
3235 commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
3236 11 new packages: my-gimp, my-emacs-with-cool-features, @dots{}
3237 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{}
3241 The output of @command{guix pull} above shows that Generation@tie{}19
3242 includes both Guix and packages from the @code{my-personal-packages}
3243 channel. Among the new and upgraded packages that are listed, some like
3244 @code{my-gimp} and @code{my-emacs-with-cool-features} might come from
3245 @code{my-personal-packages}, while others come from the Guix default
3248 @subsection Replicating Guix
3250 @cindex pinning, channels
3251 @cindex replicating Guix
3252 @cindex reproducibility, of Guix
3253 The @command{guix pull --list-generations} output above shows precisely
3254 which commits were used to build this instance of Guix. We can thus
3255 replicate it, say, on another machine, by providing a channel specification
3256 in @file{~/.config/guix/channels.scm} that is ``pinned'' to these commits:
3259 ;; Deploy specific commits of my channels of interest.
3262 (url "https://git.savannah.gnu.org/git/guix.git")
3263 (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
3265 (name 'my-personal-packages)
3266 (url "https://example.org/personal-packages.git")
3267 (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))
3270 The @command{guix describe --format=channels} command can even generate this
3271 list of channels directly (@pxref{Invoking guix describe}).
3273 At this point the two machines run the @emph{exact same Guix}, with access
3274 to the @emph{exact same packages}. The output of @command{guix build gimp}
3275 on one machine will be exactly the same, bit for bit, as the output of the
3276 same command on the other machine. It also means both machines have access
3277 to all the source code of Guix and, transitively, to all the source code of
3278 every package it defines.
3280 This gives you super powers, allowing you to track the provenance of binary
3281 artifacts with very fine grain, and to reproduce software environments at
3282 will---some sort of ``meta reproducibility'' capabilities, if you will.
3283 @xref{Inferiors}, for another way to take advantage of these super powers.
3288 @c TODO: Remove this once we're more confident about API stability.
3289 @quotation Anmerkung
3290 The functionality described here is a ``technology preview'' as of version
3291 @value{VERSION}. As such, the interface is subject to change.
3295 @cindex composition of Guix revisions
3296 Sometimes you might need to mix packages from the revision of Guix you're
3297 currently running with packages available in a different revision of Guix.
3298 Guix @dfn{inferiors} allow you to achieve that by composing different Guix
3299 revisions in arbitrary ways.
3301 @cindex inferior packages
3302 Technically, an ``inferior'' is essentially a separate Guix process
3303 connected to your main Guix process through a REPL (@pxref{Invoking guix
3304 repl}). The @code{(guix inferior)} module allows you to create inferiors
3305 and to communicate with them. It also provides a high-level interface to
3306 browse and manipulate the packages that an inferior provides---@dfn{inferior
3309 When combined with channels (@pxref{Channels}), inferiors provide a simple
3310 way to interact with a separate revision of Guix. For example, let's assume
3311 you want to install in your profile the current @code{guile} package, along
3312 with the @code{guile-json} as it existed in an older revision of
3313 Guix---perhaps because the newer @code{guile-json} has an incompatible API
3314 and you want to run your code against the old API@. To do that, you could
3315 write a manifest for use by @code{guix package --manifest} (@pxref{Aufruf von guix package}); in that manifest, you would create an inferior for that old
3316 Guix revision you care about, and you would look up the @code{guile-json}
3317 package in the inferior:
3320 (use-modules (guix inferior) (guix channels)
3321 (srfi srfi-1)) ;for 'first'
3324 ;; This is the old revision from which we want to
3325 ;; extract guile-json.
3328 (url "https://git.savannah.gnu.org/git/guix.git")
3330 "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))
3333 ;; An inferior representing the above revision.
3334 (inferior-for-channels channels))
3336 ;; Now create a manifest with the current "guile" package
3337 ;; and the old "guile-json" package.
3339 (list (first (lookup-inferior-packages inferior "guile-json"))
3340 (specification->package "guile")))
3343 On its first run, @command{guix package --manifest} might have to build the
3344 channel you specified before it can create the inferior; subsequent runs
3345 will be much faster because the Guix revision will be cached.
3347 The @code{(guix inferior)} module provides the following procedures to open
3350 @deffn {Scheme Procedure} inferior-for-channels @var{channels} @
3351 [#:cache-directory] [#:ttl] Return an inferior for @var{channels}, a list of
3352 channels. Use the cache at @var{cache-directory}, where entries can be
3353 reclaimed after @var{ttl} seconds. This procedure opens a new connection to
3356 As a side effect, this procedure may build or substitute binaries for
3357 @var{channels}, which can take time.
3360 @deffn {Scheme Procedure} open-inferior @var{directory} @
3361 [#:command "bin/guix"] Open the inferior Guix in @var{directory}, running
3362 @code{@var{directory}/@var{command} repl} or equivalent. Return @code{#f}
3363 if the inferior could not be launched.
3366 @cindex inferior packages
3367 The procedures listed below allow you to obtain and manipulate inferior
3370 @deffn {Scheme Procedure} inferior-packages @var{inferior}
3371 Return the list of packages known to @var{inferior}.
3374 @deffn {Scheme Procedure} lookup-inferior-packages @var{inferior} @var{name} @
3375 [@var{version}] Return the sorted list of inferior packages matching
3376 @var{name} in @var{inferior}, with highest version numbers first. If
3377 @var{version} is true, return only packages with a version number prefixed
3381 @deffn {Scheme Procedure} inferior-package? @var{obj}
3382 Return true if @var{obj} is an inferior package.
3385 @deffn {Scheme Procedure} inferior-package-name @var{package}
3386 @deffnx {Scheme Procedure} inferior-package-version @var{package}
3387 @deffnx {Scheme Procedure} inferior-package-synopsis @var{package}
3388 @deffnx {Scheme Procedure} inferior-package-description @var{package}
3389 @deffnx {Scheme Procedure} inferior-package-home-page @var{package}
3390 @deffnx {Scheme Procedure} inferior-package-location @var{package}
3391 @deffnx {Scheme Procedure} inferior-package-inputs @var{package}
3392 @deffnx {Scheme Procedure} inferior-package-native-inputs @var{package}
3393 @deffnx {Scheme Procedure} inferior-package-propagated-inputs @var{package}
3394 @deffnx {Scheme Procedure} inferior-package-transitive-propagated-inputs @var{package}
3395 @deffnx {Scheme Procedure} inferior-package-native-search-paths @var{package}
3396 @deffnx {Scheme Procedure} inferior-package-transitive-native-search-paths @var{package}
3397 @deffnx {Scheme Procedure} inferior-package-search-paths @var{package}
3398 These procedures are the counterpart of package record accessors
3399 (@pxref{„package“-Referenz}). Most of them work by querying the inferior
3400 @var{package} comes from, so the inferior must still be live when you call
3404 Inferior packages can be used transparently like any other package or
3405 file-like object in G-expressions (@pxref{G-Ausdrücke}). They are also
3406 transparently handled by the @code{packages->manifest} procedure, which is
3407 commonly use in manifests (@pxref{Aufruf von guix package, the
3408 @option{--manifest} option of @command{guix package}}). Thus you can insert
3409 an inferior package pretty much anywhere you would insert a regular package:
3410 in manifests, in the @code{packages} field of your @code{operating-system}
3411 declaration, and so on.
3413 @node Invoking guix describe
3414 @section Invoking @command{guix describe}
3416 @cindex Reproduzierbarkeit
3417 @cindex replicating Guix
3418 Often you may want to answer questions like: ``Which revision of Guix am I
3419 using?'' or ``Which channels am I using?'' This is useful information in
3420 many situations: if you want to @emph{replicate} an environment on a
3421 different machine or user account, if you want to report a bug or to
3422 determine what change in the channels you are using caused it, or if you
3423 want to record your system state for reproducibility purposes. The
3424 @command{guix describe} command answers these questions.
3426 When run from a @command{guix pull}ed @command{guix}, @command{guix
3427 describe} displays the channel(s) that it was built from, including their
3428 repository URL and commit IDs (@pxref{Channels}):
3432 Generation 10 Sep 03 2018 17:32:44 (current)
3434 repository URL: https://git.savannah.gnu.org/git/guix.git
3436 commit: e0fa68c7718fffd33d81af415279d6ddb518f727
3439 If you're familiar with the Git version control system, this is similar in
3440 spirit to @command{git describe}; the output is also similar to that of
3441 @command{guix pull --list-generations}, but limited to the current
3442 generation (@pxref{Aufruf von guix pull, the @option{--list-generations}
3443 option}). Because the Git commit ID shown above unambiguously refers to a
3444 snapshot of Guix, this information is all it takes to describe the revision
3445 of Guix you're using, and also to replicate it.
3447 To make it easier to replicate Guix, @command{guix describe} can also be
3448 asked to return a list of channels instead of the human-readable description
3452 $ guix describe -f channels
3455 (url "https://git.savannah.gnu.org/git/guix.git")
3457 "e0fa68c7718fffd33d81af415279d6ddb518f727")))
3461 You can save this to a file and feed it to @command{guix pull -C} on some
3462 other machine or at a later point in time, which will instantiate @emph{this
3463 exact Guix revision} (@pxref{Aufruf von guix pull, the @option{-C} option}).
3464 From there on, since you're able to deploy the same revision of Guix, you
3465 can just as well @emph{replicate a complete software environment}. We
3466 humbly think that this is @emph{awesome}, and we hope you'll like it too!
3468 The details of the options supported by @command{guix describe} are as
3472 @item --format=@var{format}
3473 @itemx -f @var{format}
3474 Produce output in the specified @var{format}, one of:
3478 produce human-readable output;
3480 produce a list of channel specifications that can be passed to @command{guix
3481 pull -C} or installed as @file{~/.config/guix/channels.scm} (@pxref{Aufruf von guix pull});
3484 produce a list of channel specifications in JSON format;
3486 produce a list of channel specifications in Recutils format.
3489 @item --profile=@var{Profil}
3490 @itemx -p @var{Profil}
3491 Display information about @var{profile}.
3494 @node Aufruf von guix pack
3495 @section Invoking @command{guix pack}
3497 Occasionally you want to pass software to people who are not (yet!) lucky
3498 enough to be using Guix. You'd tell them to run @command{guix package -i
3499 @var{something}}, but that's not possible in this case. This is where
3500 @command{guix pack} comes in.
3502 @quotation Anmerkung
3503 If you are looking for ways to exchange binaries among machines that already
3504 run Guix, @pxref{Aufruf von guix copy}, @ref{Aufruf von guix publish}, and
3505 @ref{Aufruf von guix archive}.
3510 @cindex application bundle
3511 @cindex software bundle
3512 The @command{guix pack} command creates a shrink-wrapped @dfn{pack} or
3513 @dfn{software bundle}: it creates a tarball or some other archive containing
3514 the binaries of the software you're interested in, and all its
3515 dependencies. The resulting archive can be used on any machine that does
3516 not have Guix, and people can run the exact same binaries as those you have
3517 with Guix. The pack itself is created in a bit-reproducible fashion, so
3518 anyone can verify that it really contains the build results that you pretend
3521 For example, to create a bundle containing Guile, Emacs, Geiser, and all
3522 their dependencies, you can run:
3525 $ guix pack guile emacs geiser
3527 /gnu/store/@dots{}-pack.tar.gz
3530 The result here is a tarball containing a @file{/gnu/store} directory with
3531 all the relevant packages. The resulting tarball contains a @dfn{profile}
3532 with the three packages of interest; the profile is the same as would be
3533 created by @command{guix package -i}. It is this mechanism that is used to
3534 create Guix's own standalone binary tarball (@pxref{Aus Binärdatei installieren}).
3536 Users of this pack would have to run
3537 @file{/gnu/store/@dots{}-profile/bin/guile} to run Guile, which you may find
3538 inconvenient. To work around it, you can create, say, a @file{/opt/gnu/bin}
3539 symlink to the profile:
3542 guix pack -S /opt/gnu/bin=bin guile emacs geiser
3546 That way, users can happily type @file{/opt/gnu/bin/guile} and enjoy.
3548 @cindex relocatable binaries, with @command{guix pack}
3549 What if the recipient of your pack does not have root privileges on their
3550 machine, and thus cannot unpack it in the root file system? In that case,
3551 you will want to use the @code{--relocatable} option (see below). This
3552 option produces @dfn{relocatable binaries}, meaning they they can be placed
3553 anywhere in the file system hierarchy: in the example above, users can
3554 unpack your tarball in their home directory and directly run
3555 @file{./opt/gnu/bin/guile}.
3557 @cindex Docker, build an image with guix pack
3558 Alternatively, you can produce a pack in the Docker image format using the
3562 guix pack -f docker guile emacs geiser
3566 The result is a tarball that can be passed to the @command{docker load}
3568 @uref{https://docs.docker.com/engine/reference/commandline/load/, Docker
3569 documentation} for more information.
3571 @cindex Singularity, build an image with guix pack
3572 @cindex SquashFS, build an image with guix pack
3573 Yet another option is to produce a SquashFS image with the following
3577 guix pack -f squashfs guile emacs geiser
3581 The result is a SquashFS file system image that can either be mounted or
3582 directly be used as a file system container image with the
3583 @uref{http://singularity.lbl.gov, Singularity container execution
3584 environment}, using commands like @command{singularity shell} or
3585 @command{singularity exec}.
3587 Several command-line options allow you to customize your pack:
3590 @item --format=@var{format}
3591 @itemx -f @var{format}
3592 Produce a pack in the given @var{format}.
3594 The available formats are:
3598 This is the default format. It produces a tarball containing all the
3599 specified binaries and symlinks.
3602 This produces a tarball that follows the
3603 @uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md,
3604 Docker Image Specification}.
3607 This produces a SquashFS image containing all the specified binaries and
3608 symlinks, as well as empty mount points for virtual file systems like
3614 Produce @dfn{relocatable binaries}---i.e., binaries that can be placed
3615 anywhere in the file system hierarchy and run from there. For example, if
3616 you create a pack containing Bash with:
3619 guix pack -R -S /mybin=bin bash
3623 ...@: you can copy that pack to a machine that lacks Guix, and from your
3624 home directory as a normal user, run:
3632 In that shell, if you type @code{ls /gnu/store}, you'll notice that
3633 @file{/gnu/store} shows up and contains all the dependencies of @code{bash},
3634 even though the machine actually lacks @file{/gnu/store} altogether! That is
3635 probably the simplest way to deploy Guix-built software on a non-Guix
3638 There's a gotcha though: this technique relies on the @dfn{user namespace}
3639 feature of the kernel Linux, which allows unprivileged users to mount or
3640 change root. Old versions of Linux did not support it, and some GNU/Linux
3641 distributions turn it off; on these systems, programs from the pack
3642 @emph{will fail to run}, unless they are unpacked in the root file system.
3644 @item --expression=@var{expr}
3645 @itemx -e @var{expr}
3646 Consider the package @var{expr} evaluates to.
3648 This has the same purpose as the same-named option in @command{guix build}
3649 (@pxref{Zusätzliche Erstellungsoptionen, @code{--expression} in @command{guix
3652 @item --manifest=@var{Datei}
3653 @itemx -m @var{Datei}
3654 Use the packages contained in the manifest object returned by the Scheme
3657 This has a similar purpose as the same-named option in @command{guix
3658 package} (@pxref{profile-manifest, @option{--manifest}}) and uses the same
3659 manifest files. It allows you to define a collection of packages once and
3660 use it both for creating profiles and for creating archives for use on
3661 machines that do not have Guix installed. Note that you can specify
3662 @emph{either} a manifest file @emph{or} a list of packages, but not both.
3664 @item --system=@var{System}
3665 @itemx -s @var{system}
3666 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the
3667 system type of the build host.
3669 @item --target=@var{triplet}
3670 @cindex cross-compilation
3671 Cross-build for @var{triplet}, which must be a valid GNU triplet, such as
3672 @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
3673 configuration triplets,, autoconf, Autoconf}).
3675 @item --compression=@var{tool}
3676 @itemx -C @var{tool}
3677 Compress the resulting tarball using @var{tool}---one of @code{gzip},
3678 @code{bzip2}, @code{xz}, @code{lzip}, or @code{none} for no compression.
3680 @item --symlink=@var{spec}
3681 @itemx -S @var{spec}
3682 Add the symlinks specified by @var{spec} to the pack. This option can
3683 appear several times.
3685 @var{spec} has the form @code{@var{source}=@var{target}}, where @var{source}
3686 is the symlink that will be created and @var{target} is the symlink target.
3688 For instance, @code{-S /opt/gnu/bin=bin} creates a @file{/opt/gnu/bin}
3689 symlink pointing to the @file{bin} sub-directory of the profile.
3691 @item --localstatedir
3692 @itemx --profile-name=@var{name}
3693 Include the ``local state directory'', @file{/var/guix}, in the resulting
3694 pack, and notably the @file{/var/guix/profiles/per-user/root/@var{name}}
3695 profile---by default @var{name} is @code{guix-profile}, which corresponds to
3696 @file{~root/.guix-profile}.
3698 @file{/var/guix} contains the store database (@pxref{Der Store}) as well as
3699 garbage-collector roots (@pxref{Aufruf von guix gc}). Providing it in the
3700 pack means that the store is ``complete'' and manageable by Guix; not
3701 providing it pack means that the store is ``dead'': items cannot be added to
3702 it or removed from it after extraction of the pack.
3704 One use case for this is the Guix self-contained binary tarball
3705 (@pxref{Aus Binärdatei installieren}).
3708 Use the bootstrap binaries to build the pack. This option is only useful to
3712 In addition, @command{guix pack} supports all the common build options
3713 (@pxref{Gemeinsame Erstellungsoptionen}) and all the package transformation options
3714 (@pxref{Paketumwandlungsoptionen}).
3717 @node Aufruf von guix archive
3718 @section Invoking @command{guix archive}
3720 @cindex @command{guix archive}
3722 The @command{guix archive} command allows users to @dfn{export} files from
3723 the store into a single archive, and to later @dfn{import} them on a machine
3724 that runs Guix. In particular, it allows store files to be transferred from
3725 one machine to the store on another machine.
3727 @quotation Anmerkung
3728 If you're looking for a way to produce archives in a format suitable for
3729 tools other than Guix, @pxref{Aufruf von guix pack}.
3732 @cindex exporting store items
3733 To export store files as an archive to standard output, run:
3736 guix archive --export @var{options} @var{specifications}...
3739 @var{specifications} may be either store file names or package
3740 specifications, as for @command{guix package} (@pxref{Aufruf von guix package}). For instance, the following command creates an archive
3741 containing the @code{gui} output of the @code{git} package and the main
3742 output of @code{emacs}:
3745 guix archive --export git:gui /gnu/store/...-emacs-24.3 > great.nar
3748 If the specified packages are not built yet, @command{guix archive}
3749 automatically builds them. The build process may be controlled with the
3750 common build options (@pxref{Gemeinsame Erstellungsoptionen}).
3752 To transfer the @code{emacs} package to a machine connected over SSH, one
3756 guix archive --export -r emacs | ssh the-machine guix archive --import
3760 Similarly, a complete user profile may be transferred from one machine to
3764 guix archive --export -r $(readlink -f ~/.guix-profile) | \
3765 ssh the-machine guix-archive --import
3769 However, note that, in both examples, all of @code{emacs} and the profile as
3770 well as all of their dependencies are transferred (due to @code{-r}),
3771 regardless of what is already available in the store on the target machine.
3772 The @code{--missing} option can help figure out which items are missing from
3773 the target store. The @command{guix copy} command simplifies and optimizes
3774 this whole process, so this is probably what you should use in this case
3775 (@pxref{Aufruf von guix copy}).
3777 @cindex nar, archive format
3778 @cindex normalized archive (nar)
3779 Archives are stored in the ``normalized archive'' or ``nar'' format, which
3780 is comparable in spirit to `tar', but with differences that make it more
3781 appropriate for our purposes. First, rather than recording all Unix
3782 metadata for each file, the nar format only mentions the file type (regular,
3783 directory, or symbolic link); Unix permissions and owner/group are
3784 dismissed. Second, the order in which directory entries are stored always
3785 follows the order of file names according to the C locale collation order.
3786 This makes archive production fully deterministic.
3788 @c FIXME: Add xref to daemon doc about signatures.
3789 When exporting, the daemon digitally signs the contents of the archive, and
3790 that digital signature is appended. When importing, the daemon verifies the
3791 signature and rejects the import in case of an invalid signature or if the
3792 signing key is not authorized.
3794 The main options are:
3798 Export the specified store files or packages (see below.) Write the
3799 resulting archive to the standard output.
3801 Dependencies are @emph{not} included in the output, unless
3802 @code{--recursive} is passed.
3806 When combined with @code{--export}, this instructs @command{guix archive} to
3807 include dependencies of the given items in the archive. Thus, the resulting
3808 archive is self-contained: it contains the closure of the exported store
3812 Read an archive from the standard input, and import the files listed therein
3813 into the store. Abort if the archive has an invalid digital signature, or
3814 if it is signed by a public key not among the authorized keys (see
3815 @code{--authorize} below.)
3818 Read a list of store file names from the standard input, one per line, and
3819 write on the standard output the subset of these files missing from the
3822 @item --generate-key[=@var{parameters}]
3823 @cindex signing, archives
3824 Generate a new key pair for the daemon. This is a prerequisite before
3825 archives can be exported with @code{--export}. Note that this operation
3826 usually takes time, because it needs to gather enough entropy to generate
3829 The generated key pair is typically stored under @file{/etc/guix}, in
3830 @file{signing-key.pub} (public key) and @file{signing-key.sec} (private key,
3831 which must be kept secret.) When @var{parameters} is omitted, an ECDSA key
3832 using the Ed25519 curve is generated, or, for Libgcrypt versions before
3833 1.6.0, it is a 4096-bit RSA key. Alternatively, @var{parameters} can
3834 specify @code{genkey} parameters suitable for Libgcrypt (@pxref{General
3835 public-key related Functions, @code{gcry_pk_genkey},, gcrypt, The Libgcrypt
3839 @cindex authorizing, archives
3840 Authorize imports signed by the public key passed on standard input. The
3841 public key must be in ``s-expression advanced format''---i.e., the same
3842 format as the @file{signing-key.pub} file.
3844 The list of authorized keys is kept in the human-editable file
3845 @file{/etc/guix/acl}. The file contains
3846 @url{http://people.csail.mit.edu/rivest/Sexp.txt, ``advanced-format
3847 s-expressions''} and is structured as an access-control list in the
3848 @url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure
3851 @item --extract=@var{directory}
3852 @itemx -x @var{directory}
3853 Read a single-item archive as served by substitute servers
3854 (@pxref{Substitute}) and extract it to @var{directory}. This is a
3855 low-level operation needed in only very narrow use cases; see below.
3857 For example, the following command extracts the substitute for Emacs served
3858 by @code{hydra.gnu.org} to @file{/tmp/emacs}:
3862 https://hydra.gnu.org/nar/@dots{}-emacs-24.5 \
3863 | bunzip2 | guix archive -x /tmp/emacs
3866 Single-item archives are different from multiple-item archives produced by
3867 @command{guix archive --export}; they contain a single store item, and they
3868 do @emph{not} embed a signature. Thus this operation does @emph{no}
3869 signature verification and its output should be considered unsafe.
3871 The primary purpose of this operation is to facilitate inspection of archive
3872 contents coming from possibly untrusted substitute servers.
3876 @c *********************************************************************
3877 @node Programmierschnittstelle
3878 @chapter Programmierschnittstelle
3880 GNU Guix provides several Scheme programming interfaces (APIs) to define,
3881 build, and query packages. The first interface allows users to write
3882 high-level package definitions. These definitions refer to familiar
3883 packaging concepts, such as the name and version of a package, its build
3884 system, and its dependencies. These definitions can then be turned into
3885 concrete build actions.
3887 Build actions are performed by the Guix daemon, on behalf of users. In a
3888 standard setup, the daemon has write access to the store---the
3889 @file{/gnu/store} directory---whereas users do not. The recommended setup
3890 also has the daemon perform builds in chroots, under a specific build users,
3891 to minimize interference with the rest of the system.
3894 Lower-level APIs are available to interact with the daemon and the store.
3895 To instruct the daemon to perform a build action, users actually provide it
3896 with a @dfn{derivation}. A derivation is a low-level representation of the
3897 build actions to be taken, and the environment in which they should
3898 occur---derivations are to package definitions what assembly is to C
3899 programs. The term ``derivation'' comes from the fact that build results
3900 @emph{derive} from them.
3902 This chapter describes all these APIs in turn, starting from high-level
3903 package definitions.
3906 * Pakete definieren:: Wie Sie neue Pakete definieren.
3907 * Erstellungssysteme:: Angeben, wie Pakete erstellt werden.
3908 * Der Store:: Den Paket-Store verändern.
3909 * Ableitungen:: Systemnahe Schnittstelle für Paketableitungen.
3910 * Die Store-Monade:: Rein funktionale Schnittstelle zum Store.
3911 * G-Ausdrücke:: Erstellungsausdrücke verarbeiten.
3912 * Invoking guix repl:: Fiddling with Guix interactively.
3915 @node Pakete definieren
3916 @section Pakete definieren
3918 The high-level interface to package definitions is implemented in the
3919 @code{(guix packages)} and @code{(guix build-system)} modules. As an
3920 example, the package definition, or @dfn{recipe}, for the GNU Hello package
3924 (define-module (gnu packages hello)
3925 #:use-module (guix packages)
3926 #:use-module (guix download)
3927 #:use-module (guix build-system gnu)
3928 #:use-module (guix licenses)
3929 #:use-module (gnu packages gawk))
3931 (define-public hello
3937 (uri (string-append "mirror://gnu/hello/hello-" version
3941 "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
3942 (build-system gnu-build-system)
3943 (arguments '(#:configure-flags '("--enable-silent-rules")))
3944 (inputs `(("gawk" ,gawk)))
3945 (synopsis "Hello, GNU world: An example GNU package")
3946 (description "Guess what GNU Hello prints!")
3947 (home-page "http://www.gnu.org/software/hello/")
3952 Without being a Scheme expert, the reader may have guessed the meaning of
3953 the various fields here. This expression binds the variable @code{hello} to
3954 a @code{<package>} object, which is essentially a record (@pxref{SRFI-9,
3955 Scheme records,, guile, GNU Guile Reference Manual}). This package object
3956 can be inspected using procedures found in the @code{(guix packages)}
3957 module; for instance, @code{(package-name hello)}
3958 returns---surprise!---@code{"hello"}.
3960 With luck, you may be able to import part or all of the definition of the
3961 package you are interested in from another repository, using the @code{guix
3962 import} command (@pxref{Aufruf von guix import}).
3964 In the example above, @var{hello} is defined in a module of its own,
3965 @code{(gnu packages hello)}. Technically, this is not strictly necessary,
3966 but it is convenient to do so: all the packages defined in modules under
3967 @code{(gnu packages @dots{})} are automatically known to the command-line
3968 tools (@pxref{Paketmodule}).
3970 There are a few points worth noting in the above package definition:
3974 The @code{source} field of the package is an @code{<origin>} object
3975 (@pxref{„origin“-Referenz}, for the complete reference). Here, the
3976 @code{url-fetch} method from @code{(guix download)} is used, meaning that
3977 the source is a file to be downloaded over FTP or HTTP.
3979 The @code{mirror://gnu} prefix instructs @code{url-fetch} to use one of the
3980 GNU mirrors defined in @code{(guix download)}.
3982 The @code{sha256} field specifies the expected SHA256 hash of the file being
3983 downloaded. It is mandatory, and allows Guix to check the integrity of the
3984 file. The @code{(base32 @dots{})} form introduces the base32 representation
3985 of the hash. You can obtain this information with @code{guix download}
3986 (@pxref{Aufruf von guix download}) and @code{guix hash} (@pxref{Aufruf von guix hash}).
3989 When needed, the @code{origin} form can also have a @code{patches} field
3990 listing patches to be applied, and a @code{snippet} field giving a Scheme
3991 expression to modify the source code.
3994 @cindex GNU-Erstellungssystem
3995 The @code{build-system} field specifies the procedure to build the package
3996 (@pxref{Erstellungssysteme}). Here, @var{gnu-build-system} represents the
3997 familiar GNU Build System, where packages may be configured, built, and
3998 installed with the usual @code{./configure && make && make check && make
3999 install} command sequence.
4002 The @code{arguments} field specifies options for the build system
4003 (@pxref{Erstellungssysteme}). Here it is interpreted by @var{gnu-build-system}
4004 as a request run @file{configure} with the @code{--enable-silent-rules}
4011 What about these quote (@code{'}) characters? They are Scheme syntax to
4012 introduce a literal list; @code{'} is synonymous with @code{quote}.
4013 @xref{Expression Syntax, quoting,, guile, GNU Guile Reference Manual}, for
4014 details. Here the value of the @code{arguments} field is a list of
4015 arguments passed to the build system down the road, as with @code{apply}
4016 (@pxref{Fly Evaluation, @code{apply},, guile, GNU Guile Reference Manual}).
4018 The hash-colon (@code{#:}) sequence defines a Scheme @dfn{keyword}
4019 (@pxref{Keywords,,, guile, GNU Guile Reference Manual}), and
4020 @code{#:configure-flags} is a keyword used to pass a keyword argument to the
4021 build system (@pxref{Coding With Keywords,,, guile, GNU Guile Reference
4025 The @code{inputs} field specifies inputs to the build process---i.e.,
4026 build-time or run-time dependencies of the package. Here, we define an
4027 input called @code{"gawk"} whose value is that of the @var{gawk} variable;
4028 @var{gawk} is itself bound to a @code{<package>} object.
4030 @cindex backquote (quasiquote)
4033 @cindex comma (unquote)
4037 @findex unquote-splicing
4038 Again, @code{`} (a backquote, synonymous with @code{quasiquote}) allows us
4039 to introduce a literal list in the @code{inputs} field, while @code{,} (a
4040 comma, synonymous with @code{unquote}) allows us to insert a value in that
4041 list (@pxref{Expression Syntax, unquote,, guile, GNU Guile Reference
4044 Note that GCC, Coreutils, Bash, and other essential tools do not need to be
4045 specified as inputs here. Instead, @var{gnu-build-system} takes care of
4046 ensuring that they are present (@pxref{Erstellungssysteme}).
4048 However, any other dependencies need to be specified in the @code{inputs}
4049 field. Any dependency not specified here will simply be unavailable to the
4050 build process, possibly leading to a build failure.
4053 @xref{„package“-Referenz}, for a full description of possible fields.
4055 Once a package definition is in place, the package may actually be built
4056 using the @code{guix build} command-line tool (@pxref{Aufruf von guix build}),
4057 troubleshooting any build failures you encounter (@pxref{Fehlschläge beim Erstellen untersuchen}). You can easily jump back to the package definition using the
4058 @command{guix edit} command (@pxref{Aufruf von guix edit}). @xref{Paketrichtlinien}, for more information on how to test package definitions, and
4059 @ref{Aufruf von guix lint}, for information on how to check a definition for
4061 @vindex GUIX_PACKAGE_PATH
4062 Lastly, @pxref{Channels}, for information on how to extend the distribution
4063 by adding your own package definitions in a ``channel''.
4065 Finally, updating the package definition to a new upstream version can be
4066 partly automated by the @command{guix refresh} command (@pxref{Aufruf von guix refresh}).
4068 Behind the scenes, a derivation corresponding to the @code{<package>} object
4069 is first computed by the @code{package-derivation} procedure. That
4070 derivation is stored in a @code{.drv} file under @file{/gnu/store}. The
4071 build actions it prescribes may then be realized by using the
4072 @code{build-derivations} procedure (@pxref{Der Store}).
4074 @deffn {Scheme Procedure} package-derivation @var{store} @var{package} [@var{system}]
4075 Return the @code{<derivation>} object of @var{package} for @var{system}
4076 (@pxref{Ableitungen}).
4078 @var{package} must be a valid @code{<package>} object, and @var{system} must
4079 be a string denoting the target system type---e.g., @code{"x86_64-linux"}
4080 for an x86_64 Linux-based GNU system. @var{store} must be a connection to
4081 the daemon, which operates on the store (@pxref{Der Store}).
4085 @cindex cross-compilation
4086 Similarly, it is possible to compute a derivation that cross-builds a
4087 package for some other system:
4089 @deffn {Scheme Procedure} package-cross-derivation @var{store} @
4090 @var{package} @var{target} [@var{system}] Return the @code{<derivation>}
4091 object of @var{package} cross-built from @var{system} to @var{target}.
4093 @var{target} must be a valid GNU triplet denoting the target hardware and
4094 operating system, such as @code{"mips64el-linux-gnu"} (@pxref{Configuration
4095 Names, GNU configuration triplets,, configure, GNU Configure and Build
4099 @cindex package transformations
4100 @cindex input rewriting
4101 @cindex dependency tree rewriting
4102 Packages can be manipulated in arbitrary ways. An example of a useful
4103 transformation is @dfn{input rewriting}, whereby the dependency tree of a
4104 package is rewritten by replacing specific inputs by others:
4106 @deffn {Scheme Procedure} package-input-rewriting @var{replacements} @
4107 [@var{rewrite-name}] Return a procedure that, when passed a package,
4108 replaces its direct and indirect dependencies (but not its implicit inputs)
4109 according to @var{replacements}. @var{replacements} is a list of package
4110 pairs; the first element of each pair is the package to replace, and the
4111 second one is the replacement.
4113 Optionally, @var{rewrite-name} is a one-argument procedure that takes the
4114 name of a package and returns its new name after rewrite.
4118 Consider this example:
4121 (define libressl-instead-of-openssl
4122 ;; This is a procedure to replace OPENSSL by LIBRESSL,
4124 (package-input-rewriting `((,openssl . ,libressl))))
4126 (define git-with-libressl
4127 (libressl-instead-of-openssl git))
4131 Here we first define a rewriting procedure that replaces @var{openssl} with
4132 @var{libressl}. Then we use it to define a @dfn{variant} of the @var{git}
4133 package that uses @var{libressl} instead of @var{openssl}. This is exactly
4134 what the @option{--with-input} command-line option does (@pxref{Paketumwandlungsoptionen, @option{--with-input}}).
4136 A more generic procedure to rewrite a package dependency graph is
4137 @code{package-mapping}: it supports arbitrary changes to nodes in the graph.
4139 @deffn {Scheme Procedure} package-mapping @var{proc} [@var{cut?}]
4140 Return a procedure that, given a package, applies @var{proc} to all the
4141 packages depended on and returns the resulting package. The procedure stops
4142 recursion when @var{cut?} returns true for a given package.
4146 * „package“-Referenz:: Der Datentyp für Pakete.
4147 * „origin“-Referenz:: Datentyp für Paketursprünge.
4151 @node „package“-Referenz
4152 @subsection @code{package} Reference
4154 This section summarizes all the options available in @code{package}
4155 declarations (@pxref{Pakete definieren}).
4157 @deftp {Data Type} package
4158 This is the data type representing a package recipe.
4162 The name of the package, as a string.
4164 @item @code{version}
4165 The version of the package, as a string.
4168 An object telling how the source code for the package should be acquired.
4169 Most of the time, this is an @code{origin} object, which denotes a file
4170 fetched from the Internet (@pxref{„origin“-Referenz}). It can also be any
4171 other ``file-like'' object such as a @code{local-file}, which denotes a file
4172 from the local file system (@pxref{G-Ausdrücke, @code{local-file}}).
4174 @item @code{build-system}
4175 The build system that should be used to build the package (@pxref{Erstellungssysteme}).
4177 @item @code{arguments} (default: @code{'()})
4178 The arguments that should be passed to the build system. This is a list,
4179 typically containing sequential keyword-value pairs.
4181 @item @code{inputs} (default: @code{'()})
4182 @itemx @code{native-inputs} (default: @code{'()})
4183 @itemx @code{propagated-inputs} (default: @code{'()})
4184 @cindex inputs, of packages
4185 These fields list dependencies of the package. Each one is a list of
4186 tuples, where each tuple has a label for the input (a string) as its first
4187 element, a package, origin, or derivation as its second element, and
4188 optionally the name of the output thereof that should be used, which
4189 defaults to @code{"out"} (@pxref{Pakete mit mehreren Ausgaben.}, for more
4190 on package outputs). For example, the list below specifies three inputs:
4193 `(("libffi" ,libffi)
4194 ("libunistring" ,libunistring)
4195 ("glib:bin" ,glib "bin")) ;the "bin" output of Glib
4198 @cindex cross compilation, package dependencies
4199 The distinction between @code{native-inputs} and @code{inputs} is necessary
4200 when considering cross-compilation. When cross-compiling, dependencies
4201 listed in @code{inputs} are built for the @emph{target} architecture;
4202 conversely, dependencies listed in @code{native-inputs} are built for the
4203 architecture of the @emph{build} machine.
4205 @code{native-inputs} is typically used to list tools needed at build time,
4206 but not at run time, such as Autoconf, Automake, pkg-config, Gettext, or
4207 Bison. @command{guix lint} can report likely mistakes in this area
4208 (@pxref{Aufruf von guix lint}).
4210 @anchor{package-propagated-inputs}
4211 Lastly, @code{propagated-inputs} is similar to @code{inputs}, but the
4212 specified packages will be automatically installed alongside the package
4213 they belong to (@pxref{package-cmd-propagated-inputs, @command{guix
4214 package}}, for information on how @command{guix package} deals with
4217 For example this is necessary when a C/C++ library needs headers of another
4218 library to compile, or when a pkg-config file refers to another one @i{via}
4219 its @code{Requires} field.
4221 Another example where @code{propagated-inputs} is useful is for languages
4222 that lack a facility to record the run-time search path akin to the
4223 @code{RUNPATH} of ELF files; this includes Guile, Python, Perl, and more.
4224 To ensure that libraries written in those languages can find library code
4225 they depend on at run time, run-time dependencies must be listed in
4226 @code{propagated-inputs} rather than @code{inputs}.
4228 @item @code{self-native-input?} (default: @code{#f})
4229 This is a Boolean field telling whether the package should use itself as a
4230 native input when cross-compiling.
4232 @item @code{outputs} (default: @code{'("out")})
4233 The list of output names of the package. @xref{Pakete mit mehreren Ausgaben.}, for typical uses of additional outputs.
4235 @item @code{native-search-paths} (default: @code{'()})
4236 @itemx @code{search-paths} (default: @code{'()})
4237 A list of @code{search-path-specification} objects describing search-path
4238 environment variables honored by the package.
4240 @item @code{replacement} (default: @code{#f})
4241 This must be either @code{#f} or a package object that will be used as a
4242 @dfn{replacement} for this package. @xref{Sicherheitsaktualisierungen, grafts}, for
4245 @item @code{synopsis}
4246 Eine einzeilige Beschreibung des Pakets.
4248 @item @code{description}
4249 Eine ausführlichere Beschreibung des Pakets.
4251 @item @code{license}
4252 @cindex license, of packages
4253 The license of the package; a value from @code{(guix licenses)}, or a list
4256 @item @code{home-page}
4257 The URL to the home-page of the package, as a string.
4259 @item @code{supported-systems} (default: @var{%supported-systems})
4260 The list of systems supported by the package, as strings of the form
4261 @code{architecture-kernel}, for example @code{"x86_64-linux"}.
4263 @item @code{maintainers} (default: @code{'()})
4264 The list of maintainers of the package, as @code{maintainer} objects.
4266 @item @code{location} (default: source location of the @code{package} form)
4267 The source location of the package. It is useful to override this when
4268 inheriting from another package, in which case this field is not
4269 automatically corrected.
4274 @node „origin“-Referenz
4275 @subsection @code{origin} Reference
4277 This section summarizes all the options available in @code{origin}
4278 declarations (@pxref{Pakete definieren}).
4280 @deftp {Data Type} origin
4281 This is the data type representing a source code origin.
4285 An object containing the URI of the source. The object type depends on the
4286 @code{method} (see below). For example, when using the @var{url-fetch}
4287 method of @code{(guix download)}, the valid @code{uri} values are: a URL
4288 represented as a string, or a list thereof.
4291 A procedure that handles the URI.
4296 @item @var{url-fetch} from @code{(guix download)}
4297 download a file from the HTTP, HTTPS, or FTP URL specified in the @code{uri}
4301 @item @var{git-fetch} from @code{(guix git-download)}
4302 clone the Git version control repository, and check out the revision
4303 specified in the @code{uri} field as a @code{git-reference} object; a
4304 @code{git-reference} looks like this:
4308 (url "git://git.debian.org/git/pkg-shadow/shadow")
4309 (commit "v4.1.5.1"))
4314 A bytevector containing the SHA-256 hash of the source. Typically the
4315 @code{base32} form is used here to generate the bytevector from a base-32
4318 You can obtain this information using @code{guix download} (@pxref{Aufruf von guix download}) or @code{guix hash} (@pxref{Aufruf von guix hash}).
4320 @item @code{file-name} (default: @code{#f})
4321 The file name under which the source code should be saved. When this is
4322 @code{#f}, a sensible default value will be used in most cases. In case the
4323 source is fetched from a URL, the file name from the URL will be used. For
4324 version control checkouts, it is recommended to provide the file name
4325 explicitly because the default is not very descriptive.
4327 @item @code{patches} (default: @code{'()})
4328 A list of file names, origins, or file-like objects (@pxref{G-Ausdrücke,
4329 file-like objects}) pointing to patches to be applied to the source.
4331 This list of patches must be unconditional. In particular, it cannot depend
4332 on the value of @code{%current-system} or @code{%current-target-system}.
4334 @item @code{snippet} (default: @code{#f})
4335 A G-expression (@pxref{G-Ausdrücke}) or S-expression that will be run in
4336 the source directory. This is a convenient way to modify the source,
4337 sometimes more convenient than a patch.
4339 @item @code{patch-flags} (default: @code{'("-p1")})
4340 A list of command-line flags that should be passed to the @code{patch}
4343 @item @code{patch-inputs} (default: @code{#f})
4344 Input packages or derivations to the patching process. When this is
4345 @code{#f}, the usual set of inputs necessary for patching are provided, such
4348 @item @code{modules} (default: @code{'()})
4349 A list of Guile modules that should be loaded during the patching process
4350 and while running the code in the @code{snippet} field.
4352 @item @code{patch-guile} (default: @code{#f})
4353 The Guile package that should be used in the patching process. When this is
4354 @code{#f}, a sensible default is used.
4359 @node Erstellungssysteme
4360 @section Erstellungssysteme
4362 @cindex build system
4363 Each package definition specifies a @dfn{build system} and arguments for
4364 that build system (@pxref{Pakete definieren}). This @code{build-system}
4365 field represents the build procedure of the package, as well as implicit
4366 dependencies of that build procedure.
4368 Build systems are @code{<build-system>} objects. The interface to create
4369 and manipulate them is provided by the @code{(guix build-system)} module,
4370 and actual build systems are exported by specific modules.
4372 @cindex bag (low-level package representation)
4373 Under the hood, build systems first compile package objects to @dfn{bags}.
4374 A @dfn{bag} is like a package, but with less ornamentation---in other words,
4375 a bag is a lower-level representation of a package, which includes all the
4376 inputs of that package, including some that were implicitly added by the
4377 build system. This intermediate representation is then compiled to a
4378 derivation (@pxref{Ableitungen}).
4380 Build systems accept an optional list of @dfn{arguments}. In package
4381 definitions, these are passed @i{via} the @code{arguments} field
4382 (@pxref{Pakete definieren}). They are typically keyword arguments
4383 (@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU Guile
4384 Reference Manual}). The value of these arguments is usually evaluated in
4385 the @dfn{build stratum}---i.e., by a Guile process launched by the daemon
4386 (@pxref{Ableitungen}).
4388 The main build system is @var{gnu-build-system}, which implements the
4389 standard build procedure for GNU and many other packages. It is provided by
4390 the @code{(guix build-system gnu)} module.
4392 @defvr {Scheme Variable} gnu-build-system
4393 @var{gnu-build-system} represents the GNU Build System, and variants thereof
4394 (@pxref{Configuration, configuration and makefile conventions,, standards,
4395 GNU Coding Standards}).
4397 @cindex build phases
4398 In a nutshell, packages using it are configured, built, and installed with
4399 the usual @code{./configure && make && make check && make install} command
4400 sequence. In practice, a few additional steps are often needed. All these
4401 steps are split up in separate @dfn{phases}, notably@footnote{Please see the
4402 @code{(guix build gnu-build-system)} modules for more details about the
4407 Unpack the source tarball, and change the current directory to the extracted
4408 source tree. If the source is actually a directory, copy it to the build
4409 tree, and enter that directory.
4411 @item patch-source-shebangs
4412 Patch shebangs encountered in source files so they refer to the right store
4413 file names. For instance, this changes @code{#!/bin/sh} to
4414 @code{#!/gnu/store/@dots{}-bash-4.3/bin/sh}.
4417 Run the @file{configure} script with a number of default options, such as
4418 @code{--prefix=/gnu/store/@dots{}}, as well as the options specified by the
4419 @code{#:configure-flags} argument.
4422 Run @code{make} with the list of flags specified with @code{#:make-flags}.
4423 If the @code{#:parallel-build?} argument is true (the default), build with
4427 Run @code{make check}, or some other target specified with
4428 @code{#:test-target}, unless @code{#:tests? #f} is passed. If the
4429 @code{#:parallel-tests?} argument is true (the default), run @code{make
4433 Run @code{make install} with the flags listed in @code{#:make-flags}.
4435 @item patch-shebangs
4436 Patch shebangs on the installed executable files.
4439 Strip debugging symbols from ELF files (unless @code{#:strip-binaries?} is
4440 false), copying them to the @code{debug} output when available
4441 (@pxref{Dateien zur Fehlersuche installieren}).
4444 @vindex %standard-phases
4445 The build-side module @code{(guix build gnu-build-system)} defines
4446 @var{%standard-phases} as the default list of build phases.
4447 @var{%standard-phases} is a list of symbol/procedure pairs, where the
4448 procedure implements the actual phase.
4450 The list of phases used for a particular package can be changed with the
4451 @code{#:phases} parameter. For instance, passing:
4454 #:phases (modify-phases %standard-phases (delete 'configure))
4457 means that all the phases described above will be used, except the
4458 @code{configure} phase.
4460 In addition, this build system ensures that the ``standard'' environment for
4461 GNU packages is available. This includes tools such as GCC, libc,
4462 Coreutils, Bash, Make, Diffutils, grep, and sed (see the @code{(guix
4463 build-system gnu)} module for a complete list). We call these the
4464 @dfn{implicit inputs} of a package, because package definitions do not have
4468 Other @code{<build-system>} objects are defined to support other conventions
4469 and tools used by free software packages. They inherit most of
4470 @var{gnu-build-system}, and differ mainly in the set of inputs implicitly
4471 added to the build process, and in the list of phases executed. Some of
4472 these build systems are listed below.
4474 @defvr {Scheme Variable} ant-build-system
4475 This variable is exported by @code{(guix build-system ant)}. It implements
4476 the build procedure for Java packages that can be built with
4477 @url{http://ant.apache.org/, Ant build tool}.
4479 It adds both @code{ant} and the @dfn{Java Development Kit} (JDK) as provided
4480 by the @code{icedtea} package to the set of inputs. Different packages can
4481 be specified with the @code{#:ant} and @code{#:jdk} parameters,
4484 When the original package does not provide a suitable Ant build file, the
4485 parameter @code{#:jar-name} can be used to generate a minimal Ant build file
4486 @file{build.xml} with tasks to build the specified jar archive. In this
4487 case the parameter @code{#:source-dir} can be used to specify the source
4488 sub-directory, defaulting to ``src''.
4490 The @code{#:main-class} parameter can be used with the minimal ant buildfile
4491 to specify the main class of the resulting jar. This makes the jar file
4492 executable. The @code{#:test-include} parameter can be used to specify the
4493 list of junit tests to run. It defaults to @code{(list "**/*Test.java")}.
4494 The @code{#:test-exclude} can be used to disable some tests. It defaults to
4495 @code{(list "**/Abstract*.java")}, because abstract classes cannot be run as
4498 The parameter @code{#:build-target} can be used to specify the Ant task that
4499 should be run during the @code{build} phase. By default the ``jar'' task
4504 @defvr {Scheme Variable} android-ndk-build-system
4505 @cindex Android distribution
4506 @cindex Android NDK build system
4507 This variable is exported by @code{(guix build-system android-ndk)}. It
4508 implements a build procedure for Android NDK (native development kit)
4509 packages using a Guix-specific build process.
4511 The build system assumes that packages install their public interface
4512 (header) files to the subdirectory "include" of the "out" output and their
4513 libraries to the subdirectory "lib" of the "out" output.
4515 It's also assumed that the union of all the dependencies of a package has no
4518 For the time being, cross-compilation is not supported - so right now the
4519 libraries and header files are assumed to be host tools.
4523 @defvr {Scheme Variable} asdf-build-system/source
4524 @defvrx {Scheme Variable} asdf-build-system/sbcl
4525 @defvrx {Scheme Variable} asdf-build-system/ecl
4527 These variables, exported by @code{(guix build-system asdf)}, implement
4528 build procedures for Common Lisp packages using
4529 @url{https://common-lisp.net/project/asdf/, ``ASDF''}. ASDF is a system
4530 definition facility for Common Lisp programs and libraries.
4532 The @code{asdf-build-system/source} system installs the packages in source
4533 form, and can be loaded using any common lisp implementation, via ASDF. The
4534 others, such as @code{asdf-build-system/sbcl}, install binary systems in the
4535 format which a particular implementation understands. These build systems
4536 can also be used to produce executable programs, or lisp images which
4537 contain a set of packages pre-loaded.
4539 The build system uses naming conventions. For binary packages, the package
4540 name should be prefixed with the lisp implementation, such as @code{sbcl-}
4541 for @code{asdf-build-system/sbcl}.
4543 Additionally, the corresponding source package should be labeled using the
4544 same convention as python packages (see @ref{Python-Module}), using the
4547 For binary packages, each system should be defined as a Guix package. If
4548 one package @code{origin} contains several systems, package variants can be
4549 created in order to build all the systems. Source packages, which use
4550 @code{asdf-build-system/source}, may contain several systems.
4552 In order to create executable programs and images, the build-side procedures
4553 @code{build-program} and @code{build-image} can be used. They should be
4554 called in a build phase after the @code{create-symlinks} phase, so that the
4555 system which was just built can be used within the resulting image.
4556 @code{build-program} requires a list of Common Lisp expressions to be passed
4557 as the @code{#:entry-program} argument.
4559 If the system is not defined within its own @code{.asd} file of the same
4560 name, then the @code{#:asd-file} parameter should be used to specify which
4561 file the system is defined in. Furthermore, if the package defines a system
4562 for its tests in a separate file, it will be loaded before the tests are run
4563 if it is specified by the @code{#:test-asd-file} parameter. If it is not
4564 set, the files @code{<system>-tests.asd}, @code{<system>-test.asd},
4565 @code{tests.asd}, and @code{test.asd} will be tried if they exist.
4567 If for some reason the package must be named in a different way than the
4568 naming conventions suggest, the @code{#:asd-system-name} parameter can be
4569 used to specify the name of the system.
4573 @defvr {Scheme Variable} cargo-build-system
4574 @cindex Rust programming language
4575 @cindex Cargo (Rust build system)
4576 This variable is exported by @code{(guix build-system cargo)}. It supports
4577 builds of packages using Cargo, the build tool of the
4578 @uref{https://www.rust-lang.org, Rust programming language}.
4580 In its @code{configure} phase, this build system replaces dependencies
4581 specified in the @file{Carto.toml} file with inputs to the Guix package.
4582 The @code{install} phase installs the binaries, and it also installs the
4583 source code and @file{Cargo.toml} file.
4586 @cindex Clojure (programming language)
4587 @cindex simple Clojure build system
4588 @defvr {Scheme Variable} clojure-build-system
4589 This variable is exported by @code{(guix build-system clojure)}. It
4590 implements a simple build procedure for @uref{https://clojure.org/, Clojure}
4591 packages using plain old @code{compile} in Clojure. Cross-compilation is
4594 It adds @code{clojure}, @code{icedtea} and @code{zip} to the set of inputs.
4595 Different packages can be specified with the @code{#:clojure}, @code{#:jdk}
4596 and @code{#:zip} parameters, respectively.
4598 A list of source directories, test directories and jar names can be
4599 specified with the @code{#:source-dirs}, @code{#:test-dirs} and
4600 @code{#:jar-names} parameters, respectively. Compile directory and main
4601 class can be specified with the @code{#:compile-dir} and @code{#:main-class}
4602 parameters, respectively. Other parameters are documented below.
4604 This build system is an extension of @var{ant-build-system}, but with the
4605 following phases changed:
4610 This phase calls @code{compile} in Clojure to compile source files and runs
4611 @command{jar} to create jars from both source files and compiled files
4612 according to the include list and exclude list specified in
4613 @code{#:aot-include} and @code{#:aot-exclude}, respectively. The exclude
4614 list has priority over the include list. These lists consist of symbols
4615 representing Clojure libraries or the special keyword @code{#:all}
4616 representing all Clojure libraries found under the source directories. The
4617 parameter @code{#:omit-source?} decides if source should be included into
4621 This phase runs tests according to the include list and exclude list
4622 specified in @code{#:test-include} and @code{#:test-exclude}, respectively.
4623 Their meanings are analogous to that of @code{#:aot-include} and
4624 @code{#:aot-exclude}, except that the special keyword @code{#:all} now
4625 stands for all Clojure libraries found under the test directories. The
4626 parameter @code{#:tests?} decides if tests should be run.
4629 This phase installs all jars built previously.
4632 Apart from the above, this build system also contains an additional phase:
4637 This phase installs all top-level files with base name matching
4638 @var{%doc-regex}. A different regex can be specified with the
4639 @code{#:doc-regex} parameter. All files (recursively) inside the
4640 documentation directories specified in @code{#:doc-dirs} are installed as
4645 @defvr {Scheme Variable} cmake-build-system
4646 This variable is exported by @code{(guix build-system cmake)}. It
4647 implements the build procedure for packages using the
4648 @url{http://www.cmake.org, CMake build tool}.
4650 It automatically adds the @code{cmake} package to the set of inputs. Which
4651 package is used can be specified with the @code{#:cmake} parameter.
4653 The @code{#:configure-flags} parameter is taken as a list of flags passed to
4654 the @command{cmake} command. The @code{#:build-type} parameter specifies in
4655 abstract terms the flags passed to the compiler; it defaults to
4656 @code{"RelWithDebInfo"} (short for ``release mode with debugging
4657 information''), which roughly means that code is compiled with @code{-O2
4658 -g}, as is the case for Autoconf-based packages by default.
4661 @defvr {Scheme Variable} go-build-system
4662 This variable is exported by @code{(guix build-system go)}. It implements a
4663 build procedure for Go packages using the standard
4664 @url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, Go
4667 The user is expected to provide a value for the key @code{#:import-path}
4668 and, in some cases, @code{#:unpack-path}. The
4669 @url{https://golang.org/doc/code.html#ImportPaths, import path} corresponds
4670 to the file system path expected by the package's build scripts and any
4671 referring packages, and provides a unique way to refer to a Go package. It
4672 is typically based on a combination of the package source code's remote URI
4673 and file system hierarchy structure. In some cases, you will need to unpack
4674 the package's source code to a different directory structure than the one
4675 indicated by the import path, and @code{#:unpack-path} should be used in
4678 Packages that provide Go libraries should be installed along with their
4679 source code. The key @code{#:install-source?}, which defaults to @code{#t},
4680 controls whether or not the source code is installed. It can be set to
4681 @code{#f} for packages that only provide executable files.
4684 @defvr {Scheme Variable} glib-or-gtk-build-system
4685 This variable is exported by @code{(guix build-system glib-or-gtk)}. It is
4686 intended for use with packages making use of GLib or GTK+.
4688 This build system adds the following two phases to the ones defined by
4689 @var{gnu-build-system}:
4692 @item glib-or-gtk-wrap
4693 The phase @code{glib-or-gtk-wrap} ensures that programs in @file{bin/} are
4694 able to find GLib ``schemas'' and
4695 @uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK+
4696 modules}. This is achieved by wrapping the programs in launch scripts that
4697 appropriately set the @code{XDG_DATA_DIRS} and @code{GTK_PATH} environment
4700 It is possible to exclude specific package outputs from that wrapping
4701 process by listing their names in the
4702 @code{#:glib-or-gtk-wrap-excluded-outputs} parameter. This is useful when
4703 an output is known not to contain any GLib or GTK+ binaries, and where
4704 wrapping would gratuitously add a dependency of that output on GLib and
4707 @item glib-or-gtk-compile-schemas
4708 The phase @code{glib-or-gtk-compile-schemas} makes sure that all
4709 @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html,
4710 GSettings schemas} of GLib are compiled. Compilation is performed by the
4711 @command{glib-compile-schemas} program. It is provided by the package
4712 @code{glib:bin} which is automatically imported by the build system. The
4713 @code{glib} package providing @command{glib-compile-schemas} can be
4714 specified with the @code{#:glib} parameter.
4717 Both phases are executed after the @code{install} phase.
4720 @defvr {Scheme Variable} guile-build-system
4721 This build system is for Guile packages that consist exclusively of Scheme
4722 code and that are so lean that they don't even have a makefile, let alone a
4723 @file{configure} script. It compiles Scheme code using @command{guild
4724 compile} (@pxref{Compilation,,, guile, GNU Guile Reference Manual}) and
4725 installs the @file{.scm} and @file{.go} files in the right place. It also
4726 installs documentation.
4728 This build system supports cross-compilation by using the @code{--target}
4729 option of @command{guild compile}.
4731 Packages built with @code{guile-build-system} must provide a Guile package
4732 in their @code{native-inputs} field.
4735 @defvr {Scheme Variable} minify-build-system
4736 This variable is exported by @code{(guix build-system minify)}. It
4737 implements a minification procedure for simple JavaScript packages.
4739 It adds @code{uglify-js} to the set of inputs and uses it to compress all
4740 JavaScript files in the @file{src} directory. A different minifier package
4741 can be specified with the @code{#:uglify-js} parameter, but it is expected
4742 that the package writes the minified code to the standard output.
4744 When the input JavaScript files are not all located in the @file{src}
4745 directory, the parameter @code{#:javascript-files} can be used to specify a
4746 list of file names to feed to the minifier.
4749 @defvr {Scheme Variable} ocaml-build-system
4750 This variable is exported by @code{(guix build-system ocaml)}. It
4751 implements a build procedure for @uref{https://ocaml.org, OCaml} packages,
4752 which consists of choosing the correct set of commands to run for each
4753 package. OCaml packages can expect many different commands to be run. This
4754 build system will try some of them.
4756 When the package has a @file{setup.ml} file present at the top-level, it
4757 will run @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} and
4758 @code{ocaml setup.ml -install}. The build system will assume that this file
4759 was generated by @uref{http://oasis.forge.ocamlcore.org/, OASIS} and will
4760 take care of setting the prefix and enabling tests if they are not
4761 disabled. You can pass configure and build flags with the
4762 @code{#:configure-flags} and @code{#:build-flags}. The @code{#:test-flags}
4763 key can be passed to change the set of flags used to enable tests. The
4764 @code{#:use-make?} key can be used to bypass this system in the build and
4767 When the package has a @file{configure} file, it is assumed that it is a
4768 hand-made configure script that requires a different argument format than in
4769 the @code{gnu-build-system}. You can add more flags with the
4770 @code{#:configure-flags} key.
4772 When the package has a @file{Makefile} file (or @code{#:use-make?} is
4773 @code{#t}), it will be used and more flags can be passed to the build and
4774 install phases with the @code{#:make-flags} key.
4776 Finally, some packages do not have these files and use a somewhat standard
4777 location for its build system. In that case, the build system will run
4778 @code{ocaml pkg/pkg.ml} or @code{ocaml pkg/build.ml} and take care of
4779 providing the path to the required findlib module. Additional flags can be
4780 passed via the @code{#:build-flags} key. Install is taken care of by
4781 @command{opam-installer}. In this case, the @code{opam} package must be
4782 added to the @code{native-inputs} field of the package definition.
4784 Note that most OCaml packages assume they will be installed in the same
4785 directory as OCaml, which is not what we want in guix. In particular, they
4786 will install @file{.so} files in their module's directory, which is usually
4787 fine because it is in the OCaml compiler directory. In guix though, these
4788 libraries cannot be found and we use @code{CAML_LD_LIBRARY_PATH}. This
4789 variable points to @file{lib/ocaml/site-lib/stubslibs} and this is where
4790 @file{.so} libraries should be installed.
4793 @defvr {Scheme Variable} python-build-system
4794 This variable is exported by @code{(guix build-system python)}. It
4795 implements the more or less standard build procedure used by Python
4796 packages, which consists in running @code{python setup.py build} and then
4797 @code{python setup.py install --prefix=/gnu/store/@dots{}}.
4799 For packages that install stand-alone Python programs under @code{bin/}, it
4800 takes care of wrapping these programs so that their @code{PYTHONPATH}
4801 environment variable points to all the Python libraries they depend on.
4803 Which Python package is used to perform the build can be specified with the
4804 @code{#:python} parameter. This is a useful way to force a package to be
4805 built for a specific version of the Python interpreter, which might be
4806 necessary if the package is only compatible with a single interpreter
4809 By default guix calls @code{setup.py} under control of @code{setuptools},
4810 much like @command{pip} does. Some packages are not compatible with
4811 setuptools (and pip), thus you can disable this by setting the
4812 @code{#:use-setuptools} parameter to @code{#f}.
4815 @defvr {Scheme Variable} perl-build-system
4816 This variable is exported by @code{(guix build-system perl)}. It implements
4817 the standard build procedure for Perl packages, which either consists in
4818 running @code{perl Build.PL --prefix=/gnu/store/@dots{}}, followed by
4819 @code{Build} and @code{Build install}; or in running @code{perl Makefile.PL
4820 PREFIX=/gnu/store/@dots{}}, followed by @code{make} and @code{make install},
4821 depending on which of @code{Build.PL} or @code{Makefile.PL} is present in
4822 the package distribution. Preference is given to the former if both
4823 @code{Build.PL} and @code{Makefile.PL} exist in the package distribution.
4824 This preference can be reversed by specifying @code{#t} for the
4825 @code{#:make-maker?} parameter.
4827 The initial @code{perl Makefile.PL} or @code{perl Build.PL} invocation
4828 passes flags specified by the @code{#:make-maker-flags} or
4829 @code{#:module-build-flags} parameter, respectively.
4831 Which Perl package is used can be specified with @code{#:perl}.
4834 @defvr {Scheme Variable} r-build-system
4835 This variable is exported by @code{(guix build-system r)}. It implements
4836 the build procedure used by @uref{http://r-project.org, R} packages, which
4837 essentially is little more than running @code{R CMD INSTALL
4838 --library=/gnu/store/@dots{}} in an environment where @code{R_LIBS_SITE}
4839 contains the paths to all R package inputs. Tests are run after
4840 installation using the R function @code{tools::testInstalledPackage}.
4843 @defvr {Scheme Variable} texlive-build-system
4844 This variable is exported by @code{(guix build-system texlive)}. It is used
4845 to build TeX packages in batch mode with a specified engine. The build
4846 system sets the @code{TEXINPUTS} variable to find all TeX source files in
4849 By default it runs @code{luatex} on all files ending on @code{ins}. A
4850 different engine and format can be specified with the @code{#:tex-format}
4851 argument. Different build targets can be specified with the
4852 @code{#:build-targets} argument, which expects a list of file names. The
4853 build system adds only @code{texlive-bin} and @code{texlive-latex-base}
4854 (both from @code{(gnu packages tex}) to the inputs. Both can be overridden
4855 with the arguments @code{#:texlive-bin} and @code{#:texlive-latex-base},
4858 The @code{#:tex-directory} parameter tells the build system where to install
4859 the built files under the texmf tree.
4862 @defvr {Scheme Variable} ruby-build-system
4863 This variable is exported by @code{(guix build-system ruby)}. It implements
4864 the RubyGems build procedure used by Ruby packages, which involves running
4865 @code{gem build} followed by @code{gem install}.
4867 The @code{source} field of a package that uses this build system typically
4868 references a gem archive, since this is the format that Ruby developers use
4869 when releasing their software. The build system unpacks the gem archive,
4870 potentially patches the source, runs the test suite, repackages the gem, and
4871 installs it. Additionally, directories and tarballs may be referenced to
4872 allow building unreleased gems from Git or a traditional source release
4875 Which Ruby package is used can be specified with the @code{#:ruby}
4876 parameter. A list of additional flags to be passed to the @command{gem}
4877 command can be specified with the @code{#:gem-flags} parameter.
4880 @defvr {Scheme Variable} waf-build-system
4881 This variable is exported by @code{(guix build-system waf)}. It implements
4882 a build procedure around the @code{waf} script. The common
4883 phases---@code{configure}, @code{build}, and @code{install}---are
4884 implemented by passing their names as arguments to the @code{waf} script.
4886 The @code{waf} script is executed by the Python interpreter. Which Python
4887 package is used to run the script can be specified with the @code{#:python}
4891 @defvr {Scheme Variable} scons-build-system
4892 This variable is exported by @code{(guix build-system scons)}. It
4893 implements the build procedure used by the SCons software construction
4894 tool. This build system runs @code{scons} to build the package, @code{scons
4895 test} to run tests, and then @code{scons install} to install the package.
4897 Additional flags to be passed to @code{scons} can be specified with the
4898 @code{#:scons-flags} parameter. The version of Python used to run SCons can
4899 be specified by selecting the appropriate SCons package with the
4900 @code{#:scons} parameter.
4903 @defvr {Scheme Variable} haskell-build-system
4904 This variable is exported by @code{(guix build-system haskell)}. It
4905 implements the Cabal build procedure used by Haskell packages, which
4906 involves running @code{runhaskell Setup.hs configure
4907 --prefix=/gnu/store/@dots{}} and @code{runhaskell Setup.hs build}. Instead
4908 of installing the package by running @code{runhaskell Setup.hs install}, to
4909 avoid trying to register libraries in the read-only compiler store
4910 directory, the build system uses @code{runhaskell Setup.hs copy}, followed
4911 by @code{runhaskell Setup.hs register}. In addition, the build system
4912 generates the package documentation by running @code{runhaskell Setup.hs
4913 haddock}, unless @code{#:haddock? #f} is passed. Optional Haddock
4914 parameters can be passed with the help of the @code{#:haddock-flags}
4915 parameter. If the file @code{Setup.hs} is not found, the build system looks
4916 for @code{Setup.lhs} instead.
4918 Which Haskell compiler is used can be specified with the @code{#:haskell}
4919 parameter which defaults to @code{ghc}.
4922 @defvr {Scheme Variable} dub-build-system
4923 This variable is exported by @code{(guix build-system dub)}. It implements
4924 the Dub build procedure used by D packages, which involves running @code{dub
4925 build} and @code{dub run}. Installation is done by copying the files
4928 Which D compiler is used can be specified with the @code{#:ldc} parameter
4929 which defaults to @code{ldc}.
4932 @defvr {Scheme Variable} emacs-build-system
4933 This variable is exported by @code{(guix build-system emacs)}. It
4934 implements an installation procedure similar to the packaging system of
4935 Emacs itself (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
4937 It first creates the @code{@var{package}-autoloads.el} file, then it byte
4938 compiles all Emacs Lisp files. Differently from the Emacs packaging system,
4939 the Info documentation files are moved to the standard documentation
4940 directory and the @file{dir} file is deleted. Each package is installed in
4941 its own directory under @file{share/emacs/site-lisp/guix.d}.
4944 @defvr {Scheme Variable} font-build-system
4945 This variable is exported by @code{(guix build-system font)}. It implements
4946 an installation procedure for font packages where upstream provides
4947 pre-compiled TrueType, OpenType, etc.@: font files that merely need to be
4948 copied into place. It copies font files to standard locations in the output
4952 @defvr {Scheme Variable} meson-build-system
4953 This variable is exported by @code{(guix build-system meson)}. It
4954 implements the build procedure for packages that use
4955 @url{http://mesonbuild.com, Meson} as their build system.
4957 It adds both Meson and @uref{https://ninja-build.org/, Ninja} to the set of
4958 inputs, and they can be changed with the parameters @code{#:meson} and
4959 @code{#:ninja} if needed. The default Meson is @code{meson-for-build},
4960 which is special because it doesn't clear the @code{RUNPATH} of binaries and
4961 libraries when they are installed.
4963 This build system is an extension of @var{gnu-build-system}, but with the
4964 following phases changed to some specific for Meson:
4969 The phase runs @code{meson} with the flags specified in
4970 @code{#:configure-flags}. The flag @code{--build-type} is always set to
4971 @code{plain} unless something else is specified in @code{#:build-type}.
4974 The phase runs @code{ninja} to build the package in parallel by default, but
4975 this can be changed with @code{#:parallel-build?}.
4978 The phase runs @code{ninja} with the target specified in
4979 @code{#:test-target}, which is @code{"test"} by default.
4982 The phase runs @code{ninja install} and can not be changed.
4985 Apart from that, the build system also adds the following phases:
4990 This phase ensures that all binaries can find the libraries they need. It
4991 searches for required libraries in subdirectories of the package being
4992 built, and adds those to @code{RUNPATH} where needed. It also removes
4993 references to libraries left over from the build phase by
4994 @code{meson-for-build}, such as test dependencies, that aren't actually
4995 required for the program to run.
4997 @item glib-or-gtk-wrap
4998 This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
4999 is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
5001 @item glib-or-gtk-compile-schemas
5002 This phase is the phase provided by @code{glib-or-gtk-build-system}, and it
5003 is not enabled by default. It can be enabled with @code{#:glib-or-gtk?}.
5007 Lastly, for packages that do not need anything as sophisticated, a
5008 ``trivial'' build system is provided. It is trivial in the sense that it
5009 provides basically no support: it does not pull any implicit inputs, and
5010 does not have a notion of build phases.
5012 @defvr {Scheme Variable} trivial-build-system
5013 This variable is exported by @code{(guix build-system trivial)}.
5015 This build system requires a @code{#:builder} argument. This argument must
5016 be a Scheme expression that builds the package output(s)---as with
5017 @code{build-expression->derivation} (@pxref{Ableitungen,
5018 @code{build-expression->derivation}}).
5028 Conceptually, the @dfn{store} is the place where derivations that have been
5029 built successfully are stored---by default, @file{/gnu/store}.
5030 Sub-directories in the store are referred to as @dfn{store items} or
5031 sometimes @dfn{store paths}. The store has an associated database that
5032 contains information such as the store paths referred to by each store path,
5033 and the list of @emph{valid} store items---results of successful builds.
5034 This database resides in @file{@var{localstatedir}/guix/db}, where
5035 @var{localstatedir} is the state directory specified @i{via}
5036 @option{--localstatedir} at configure time, usually @file{/var}.
5038 The store is @emph{always} accessed by the daemon on behalf of its clients
5039 (@pxref{Aufruf des guix-daemon}). To manipulate the store, clients connect to
5040 the daemon over a Unix-domain socket, send requests to it, and read the
5041 result---these are remote procedure calls, or RPCs.
5043 @quotation Anmerkung
5044 Users must @emph{never} modify files under @file{/gnu/store} directly. This
5045 would lead to inconsistencies and break the immutability assumptions of
5046 Guix's functional model (@pxref{Einführung}).
5048 @xref{Aufruf von guix gc, @command{guix gc --verify}}, for information on how
5049 to check the integrity of the store and attempt recovery from accidental
5053 The @code{(guix store)} module provides procedures to connect to the daemon,
5054 and to perform RPCs. These are described below. By default,
5055 @code{open-connection}, and thus all the @command{guix} commands, connect to
5056 the local daemon or to the URI specified by the @code{GUIX_DAEMON_SOCKET}
5057 environment variable.
5059 @defvr {Environment Variable} GUIX_DAEMON_SOCKET
5060 When set, the value of this variable should be a file name or a URI
5061 designating the daemon endpoint. When it is a file name, it denotes a
5062 Unix-domain socket to connect to. In addition to file names, the supported
5068 These are for Unix-domain sockets.
5069 @code{file:///var/guix/daemon-socket/socket} is equivalent to
5070 @file{/var/guix/daemon-socket/socket}.
5073 @cindex Daemon, Fernzugriff
5074 @cindex Fernzugriff auf den Daemon
5075 @cindex Daemon, Einrichten auf Clustern
5076 @cindex Cluster, Einrichtung des Daemons
5077 These URIs denote connections over TCP/IP, without encryption nor
5078 authentication of the remote host. The URI must specify the host name and
5079 optionally a port number (by default port 44146 is used):
5082 guix://master.guix.example.org:1234
5085 This setup is suitable on local networks, such as clusters, where only
5086 trusted nodes may connect to the build daemon at
5087 @code{master.guix.example.org}.
5089 The @code{--listen} option of @command{guix-daemon} can be used to instruct
5090 it to listen for TCP connections (@pxref{Aufruf des guix-daemon,
5094 @cindex SSH access to build daemons
5095 These URIs allow you to connect to a remote daemon over SSH@footnote{This
5096 feature requires Guile-SSH (@pxref{Voraussetzungen}).}. A typical URL might
5100 ssh://charlie@@guix.example.org:22
5103 As for @command{guix copy}, the usual OpenSSH client configuration files are
5104 honored (@pxref{Aufruf von guix copy}).
5107 Additional URI schemes may be supported in the future.
5109 @c XXX: Remove this note when the protocol incurs fewer round trips
5110 @c and when (guix derivations) no longer relies on file system access.
5111 @quotation Anmerkung
5112 The ability to connect to remote build daemons is considered experimental as
5113 of @value{VERSION}. Please get in touch with us to share any problems or
5114 suggestions you may have (@pxref{Mitwirken}).
5118 @deffn {Scheme Procedure} open-connection [@var{uri}] [#:reserve-space? #t]
5119 Connect to the daemon over the Unix-domain socket at @var{uri} (a string).
5120 When @var{reserve-space?} is true, instruct it to reserve a little bit of
5121 extra space on the file system so that the garbage collector can still
5122 operate should the disk become full. Return a server object.
5124 @var{file} defaults to @var{%default-socket-path}, which is the normal
5125 location given the options that were passed to @command{configure}.
5128 @deffn {Scheme Procedure} close-connection @var{server}
5129 Close the connection to @var{server}.
5132 @defvr {Scheme Variable} current-build-output-port
5133 This variable is bound to a SRFI-39 parameter, which refers to the port
5134 where build and error logs sent by the daemon should be written.
5137 Procedures that make RPCs all take a server object as their first argument.
5139 @deffn {Scheme Procedure} valid-path? @var{server} @var{path}
5140 @cindex invalid store items
5141 Return @code{#t} when @var{path} designates a valid store item and @code{#f}
5142 otherwise (an invalid item may exist on disk but still be invalid, for
5143 instance because it is the result of an aborted or failed build.)
5145 A @code{&nix-protocol-error} condition is raised if @var{path} is not
5146 prefixed by the store directory (@file{/gnu/store}).
5149 @deffn {Scheme Procedure} add-text-to-store @var{server} @var{name} @var{text} [@var{references}]
5150 Add @var{text} under file @var{name} in the store, and return its store
5151 path. @var{references} is the list of store paths referred to by the
5152 resulting store path.
5155 @deffn {Scheme Procedure} build-derivations @var{server} @var{derivations}
5156 Build @var{derivations} (a list of @code{<derivation>} objects or derivation
5157 paths), and return when the worker is done building them. Return @code{#t}
5161 Note that the @code{(guix monads)} module provides a monad as well as
5162 monadic versions of the above procedures, with the goal of making it more
5163 convenient to work with code that accesses the store (@pxref{Die Store-Monade}).
5166 @i{This section is currently incomplete.}
5169 @section Ableitungen
5172 Low-level build actions and the environment in which they are performed are
5173 represented by @dfn{derivations}. A derivation contains the following
5174 pieces of information:
5178 The outputs of the derivation---derivations produce at least one file or
5179 directory in the store, but may produce more.
5182 The inputs of the derivations, which may be other derivations or plain files
5183 in the store (patches, build scripts, etc.)
5186 The system type targeted by the derivation---e.g., @code{x86_64-linux}.
5189 The file name of a build script in the store, along with the arguments to be
5193 A list of environment variables to be defined.
5197 @cindex derivation path
5198 Derivations allow clients of the daemon to communicate build actions to the
5199 store. They exist in two forms: as an in-memory representation, both on the
5200 client- and daemon-side, and as files in the store whose name end in
5201 @code{.drv}---these files are referred to as @dfn{derivation paths}.
5202 Derivations paths can be passed to the @code{build-derivations} procedure to
5203 perform the build actions they prescribe (@pxref{Der Store}).
5205 @cindex fixed-output derivations
5206 Operations such as file downloads and version-control checkouts for which
5207 the expected content hash is known in advance are modeled as
5208 @dfn{fixed-output derivations}. Unlike regular derivations, the outputs of
5209 a fixed-output derivation are independent of its inputs---e.g., a source
5210 code download produces the same result regardless of the download method and
5213 The @code{(guix derivations)} module provides a representation of
5214 derivations as Scheme objects, along with procedures to create and otherwise
5215 manipulate derivations. The lowest-level primitive to create a derivation
5216 is the @code{derivation} procedure:
5218 @deffn {Scheme Procedure} derivation @var{store} @var{name} @var{builder} @
5219 @var{args} [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive?
5220 #f] [#:inputs '()] [#:env-vars '()] @ [#:system (%current-system)]
5221 [#:references-graphs #f] @ [#:allowed-references #f]
5222 [#:disallowed-references #f] @ [#:leaked-env-vars #f] [#:local-build? #f] @
5223 [#:substitutable? #t] [#:properties '()] Build a derivation with the given
5224 arguments, and return the resulting @code{<derivation>} object.
5226 When @var{hash} and @var{hash-algo} are given, a @dfn{fixed-output
5227 derivation} is created---i.e., one whose result is known in advance, such as
5228 a file download. If, in addition, @var{recursive?} is true, then that fixed
5229 output may be an executable file or a directory and @var{hash} must be the
5230 hash of an archive containing this output.
5232 When @var{references-graphs} is true, it must be a list of file name/store
5233 path pairs. In that case, the reference graph of each store path is
5234 exported in the build environment in the corresponding file, in a simple
5237 When @var{allowed-references} is true, it must be a list of store items or
5238 outputs that the derivation's output may refer to. Likewise,
5239 @var{disallowed-references}, if true, must be a list of things the outputs
5240 may @emph{not} refer to.
5242 When @var{leaked-env-vars} is true, it must be a list of strings denoting
5243 environment variables that are allowed to ``leak'' from the daemon's
5244 environment to the build environment. This is only applicable to
5245 fixed-output derivations---i.e., when @var{hash} is true. The main use is
5246 to allow variables such as @code{http_proxy} to be passed to derivations
5247 that download files.
5249 When @var{local-build?} is true, declare that the derivation is not a good
5250 candidate for offloading and should rather be built locally (@pxref{Auslagern des Daemons einrichten}). This is the case for small derivations where the costs of
5251 data transfers would outweigh the benefits.
5253 When @var{substitutable?} is false, declare that substitutes of the
5254 derivation's output should not be used (@pxref{Substitute}). This is
5255 useful, for instance, when building packages that capture details of the
5256 host CPU instruction set.
5258 @var{properties} must be an association list describing ``properties'' of
5259 the derivation. It is kept as-is, uninterpreted, in the derivation.
5263 Here's an example with a shell script as its builder, assuming @var{store}
5264 is an open connection to the daemon, and @var{bash} points to a Bash
5265 executable in the store:
5268 (use-modules (guix utils)
5272 (let ((builder ; add the Bash script to the store
5273 (add-text-to-store store "my-builder.sh"
5274 "echo hello world > $out\n" '())))
5275 (derivation store "foo"
5276 bash `("-e" ,builder)
5277 #:inputs `((,bash) (,builder))
5278 #:env-vars '(("HOME" . "/homeless"))))
5279 @result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo>
5282 As can be guessed, this primitive is cumbersome to use directly. A better
5283 approach is to write build scripts in Scheme, of course! The best course of
5284 action for that is to write the build code as a ``G-expression'', and to
5285 pass it to @code{gexp->derivation}. For more information,
5286 @pxref{G-Ausdrücke}.
5288 Once upon a time, @code{gexp->derivation} did not exist and constructing
5289 derivations with build code written in Scheme was achieved with
5290 @code{build-expression->derivation}, documented below. This procedure is
5291 now deprecated in favor of the much nicer @code{gexp->derivation}.
5293 @deffn {Scheme Procedure} build-expression->derivation @var{store} @
5294 @var{name} @var{exp} @ [#:system (%current-system)] [#:inputs '()] @
5295 [#:outputs '("out")] [#:hash #f] [#:hash-algo #f] @ [#:recursive? #f]
5296 [#:env-vars '()] [#:modules '()] @ [#:references-graphs #f]
5297 [#:allowed-references #f] @ [#:disallowed-references #f] @ [#:local-build?
5298 #f] [#:substitutable? #t] [#:guile-for-build #f] Return a derivation that
5299 executes Scheme expression @var{exp} as a builder for derivation
5300 @var{name}. @var{inputs} must be a list of @code{(name drv-path sub-drv)}
5301 tuples; when @var{sub-drv} is omitted, @code{"out"} is assumed.
5302 @var{modules} is a list of names of Guile modules from the current search
5303 path to be copied in the store, compiled, and made available in the load
5304 path during the execution of @var{exp}---e.g., @code{((guix build utils)
5305 (guix build gnu-build-system))}.
5307 @var{exp} is evaluated in an environment where @code{%outputs} is bound to a
5308 list of output/path pairs, and where @code{%build-inputs} is bound to a list
5309 of string/output-path pairs made from @var{inputs}. Optionally,
5310 @var{env-vars} is a list of string pairs specifying the name and value of
5311 environment variables visible to the builder. The builder terminates by
5312 passing the result of @var{exp} to @code{exit}; thus, when @var{exp} returns
5313 @code{#f}, the build is considered to have failed.
5315 @var{exp} is built using @var{guile-for-build} (a derivation). When
5316 @var{guile-for-build} is omitted or is @code{#f}, the value of the
5317 @code{%guile-for-build} fluid is used instead.
5319 See the @code{derivation} procedure for the meaning of
5320 @var{references-graphs}, @var{allowed-references},
5321 @var{disallowed-references}, @var{local-build?}, and @var{substitutable?}.
5325 Here's an example of a single-output derivation that creates a directory
5326 containing one file:
5329 (let ((builder '(let ((out (assoc-ref %outputs "out")))
5330 (mkdir out) ; create /gnu/store/@dots{}-goo
5331 (call-with-output-file (string-append out "/test")
5333 (display '(hello guix) p))))))
5334 (build-expression->derivation store "goo" builder))
5336 @result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}>
5340 @node Die Store-Monade
5341 @section Die Store-Monade
5345 The procedures that operate on the store described in the previous sections
5346 all take an open connection to the build daemon as their first argument.
5347 Although the underlying model is functional, they either have side effects
5348 or depend on the current state of the store.
5350 The former is inconvenient: the connection to the build daemon has to be
5351 carried around in all those functions, making it impossible to compose
5352 functions that do not take that parameter with functions that do. The
5353 latter can be problematic: since store operations have side effects and/or
5354 depend on external state, they have to be properly sequenced.
5356 @cindex monadic values
5357 @cindex monadic functions
5358 This is where the @code{(guix monads)} module comes in. This module
5359 provides a framework for working with @dfn{monads}, and a particularly
5360 useful monad for our uses, the @dfn{store monad}. Monads are a construct
5361 that allows two things: associating ``context'' with values (in our case,
5362 the context is the store), and building sequences of computations (here
5363 computations include accesses to the store). Values in a monad---values
5364 that carry this additional context---are called @dfn{monadic values};
5365 procedures that return such values are called @dfn{monadic procedures}.
5367 Consider this ``normal'' procedure:
5370 (define (sh-symlink store)
5371 ;; Return a derivation that symlinks the 'bash' executable.
5372 (let* ((drv (package-derivation store bash))
5373 (out (derivation->output-path drv))
5374 (sh (string-append out "/bin/bash")))
5375 (build-expression->derivation store "sh"
5376 `(symlink ,sh %output))))
5379 Using @code{(guix monads)} and @code{(guix gexp)}, it may be rewritten as a
5383 (define (sh-symlink)
5384 ;; Same, but return a monadic value.
5385 (mlet %store-monad ((drv (package->derivation bash)))
5386 (gexp->derivation "sh"
5387 #~(symlink (string-append #$drv "/bin/bash")
5391 There are several things to note in the second version: the @code{store}
5392 parameter is now implicit and is ``threaded'' in the calls to the
5393 @code{package->derivation} and @code{gexp->derivation} monadic procedures,
5394 and the monadic value returned by @code{package->derivation} is @dfn{bound}
5395 using @code{mlet} instead of plain @code{let}.
5397 As it turns out, the call to @code{package->derivation} can even be omitted
5398 since it will take place implicitly, as we will see later
5399 (@pxref{G-Ausdrücke}):
5402 (define (sh-symlink)
5403 (gexp->derivation "sh"
5404 #~(symlink (string-append #$bash "/bin/bash")
5409 @c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/>
5410 @c for the funny quote.
5411 Calling the monadic @code{sh-symlink} has no effect. As someone once said,
5412 ``you exit a monad like you exit a building on fire: by running''. So, to
5413 exit the monad and get the desired effect, one must use
5414 @code{run-with-store}:
5417 (run-with-store (open-connection) (sh-symlink))
5418 @result{} /gnu/store/...-sh-symlink
5421 Note that the @code{(guix monad-repl)} module extends the Guile REPL with
5422 new ``meta-commands'' to make it easier to deal with monadic procedures:
5423 @code{run-in-store}, and @code{enter-store-monad}. The former is used to
5424 ``run'' a single monadic value through the store:
5427 scheme@@(guile-user)> ,run-in-store (package->derivation hello)
5428 $1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
5431 The latter enters a recursive REPL, where all the return values are
5432 automatically run through the store:
5435 scheme@@(guile-user)> ,enter-store-monad
5436 store-monad@@(guile-user) [1]> (package->derivation hello)
5437 $2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}>
5438 store-monad@@(guile-user) [1]> (text-file "foo" "Hello!")
5439 $3 = "/gnu/store/@dots{}-foo"
5440 store-monad@@(guile-user) [1]> ,q
5441 scheme@@(guile-user)>
5445 Note that non-monadic values cannot be returned in the @code{store-monad}
5448 The main syntactic forms to deal with monads in general are provided by the
5449 @code{(guix monads)} module and are described below.
5451 @deffn {Scheme Syntax} with-monad @var{monad} @var{body} ...
5452 Evaluate any @code{>>=} or @code{return} forms in @var{body} as being in
5456 @deffn {Scheme Syntax} return @var{val}
5457 Return a monadic value that encapsulates @var{val}.
5460 @deffn {Scheme Syntax} >>= @var{mval} @var{mproc} ...
5461 @dfn{Bind} monadic value @var{mval}, passing its ``contents'' to monadic
5462 procedures @var{mproc}@dots{}@footnote{This operation is commonly referred
5463 to as ``bind'', but that name denotes an unrelated procedure in Guile. Thus
5464 we use this somewhat cryptic symbol inherited from the Haskell language.}.
5465 There can be one @var{mproc} or several of them, as in this example:
5469 (with-monad %state-monad
5471 (lambda (x) (return (+ 1 x)))
5472 (lambda (x) (return (* 2 x)))))
5476 @result{} some-state
5480 @deffn {Scheme Syntax} mlet @var{monad} ((@var{var} @var{mval}) ...) @
5482 @deffnx {Scheme Syntax} mlet* @var{monad} ((@var{var} @var{mval}) ...) @
5483 @var{body} ... Bind the variables @var{var} to the monadic values
5484 @var{mval} in @var{body}, which is a sequence of expressions. As with the
5485 bind operator, this can be thought of as ``unpacking'' the raw, non-monadic
5486 value ``contained'' in @var{mval} and making @var{var} refer to that raw,
5487 non-monadic value within the scope of the @var{body}. The form (@var{var}
5488 -> @var{val}) binds @var{var} to the ``normal'' value @var{val}, as per
5489 @code{let}. The binding operations occur in sequence from left to right.
5490 The last expression of @var{body} must be a monadic expression, and its
5491 result will become the result of the @code{mlet} or @code{mlet*} when run in
5494 @code{mlet*} is to @code{mlet} what @code{let*} is to @code{let}
5495 (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}).
5498 @deffn {Scheme System} mbegin @var{monad} @var{mexp} ...
5499 Bind @var{mexp} and the following monadic expressions in sequence, returning
5500 the result of the last expression. Every expression in the sequence must be
5501 a monadic expression.
5503 This is akin to @code{mlet}, except that the return values of the monadic
5504 expressions are ignored. In that sense, it is analogous to @code{begin},
5505 but applied to monadic expressions.
5508 @deffn {Scheme System} mwhen @var{condition} @var{mexp0} @var{mexp*} ...
5509 When @var{condition} is true, evaluate the sequence of monadic expressions
5510 @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When @var{condition} is
5511 false, return @code{*unspecified*} in the current monad. Every expression
5512 in the sequence must be a monadic expression.
5515 @deffn {Scheme System} munless @var{condition} @var{mexp0} @var{mexp*} ...
5516 When @var{condition} is false, evaluate the sequence of monadic expressions
5517 @var{mexp0}..@var{mexp*} as in an @code{mbegin}. When @var{condition} is
5518 true, return @code{*unspecified*} in the current monad. Every expression in
5519 the sequence must be a monadic expression.
5523 The @code{(guix monads)} module provides the @dfn{state monad}, which allows
5524 an additional value---the state---to be @emph{threaded} through monadic
5527 @defvr {Scheme Variable} %state-monad
5528 The state monad. Procedures in the state monad can access and change the
5529 state that is threaded.
5531 Consider the example below. The @code{square} procedure returns a value in
5532 the state monad. It returns the square of its argument, but also increments
5533 the current state value:
5537 (mlet %state-monad ((count (current-state)))
5538 (mbegin %state-monad
5539 (set-current-state (+ 1 count))
5542 (run-with-state (sequence %state-monad (map square (iota 3))) 0)
5547 When ``run'' through @var{%state-monad}, we obtain that additional state
5548 value, which is the number of @code{square} calls.
5551 @deffn {Monadic Procedure} current-state
5552 Return the current state as a monadic value.
5555 @deffn {Monadic Procedure} set-current-state @var{value}
5556 Set the current state to @var{value} and return the previous state as a
5560 @deffn {Monadic Procedure} state-push @var{value}
5561 Push @var{value} to the current state, which is assumed to be a list, and
5562 return the previous state as a monadic value.
5565 @deffn {Monadic Procedure} state-pop
5566 Pop a value from the current state and return it as a monadic value. The
5567 state is assumed to be a list.
5570 @deffn {Scheme Procedure} run-with-state @var{mval} [@var{state}]
5571 Run monadic value @var{mval} starting with @var{state} as the initial
5572 state. Return two values: the resulting value, and the resulting state.
5575 The main interface to the store monad, provided by the @code{(guix store)}
5576 module, is as follows.
5578 @defvr {Scheme Variable} %store-monad
5579 The store monad---an alias for @var{%state-monad}.
5581 Values in the store monad encapsulate accesses to the store. When its
5582 effect is needed, a value of the store monad must be ``evaluated'' by
5583 passing it to the @code{run-with-store} procedure (see below.)
5586 @deffn {Scheme Procedure} run-with-store @var{store} @var{mval} [#:guile-for-build] [#:system (%current-system)]
5587 Run @var{mval}, a monadic value in the store monad, in @var{store}, an open
5591 @deffn {Monadic Procedure} text-file @var{name} @var{text} [@var{references}]
5592 Return as a monadic value the absolute file name in the store of the file
5593 containing @var{text}, a string. @var{references} is a list of store items
5594 that the resulting text file refers to; it defaults to the empty list.
5597 @deffn {Monadic Procedure} binary-file @var{name} @var{data} [@var{references}]
5598 Return as a monadic value the absolute file name in the store of the file
5599 containing @var{data}, a bytevector. @var{references} is a list of store
5600 items that the resulting binary file refers to; it defaults to the empty
5604 @deffn {Monadic Procedure} interned-file @var{file} [@var{name}] @
5605 [#:recursive? #t] [#:select? (const #t)] Return the name of @var{file} once
5606 interned in the store. Use @var{name} as its store name, or the basename of
5607 @var{file} if @var{name} is omitted.
5609 When @var{recursive?} is true, the contents of @var{file} are added
5610 recursively; if @var{file} designates a flat file and @var{recursive?} is
5611 true, its contents are added, and its permission bits are kept.
5613 When @var{recursive?} is true, call @code{(@var{select?} @var{file}
5614 @var{stat})} for each directory entry, where @var{file} is the entry's
5615 absolute file name and @var{stat} is the result of @code{lstat}; exclude
5616 entries for which @var{select?} does not return true.
5618 The example below adds a file to the store, under two different names:
5621 (run-with-store (open-connection)
5622 (mlet %store-monad ((a (interned-file "README"))
5623 (b (interned-file "README" "LEGU-MIN")))
5624 (return (list a b))))
5626 @result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN")
5631 The @code{(guix packages)} module exports the following package-related
5634 @deffn {Monadic Procedure} package-file @var{package} [@var{file}] @
5635 [#:system (%current-system)] [#:target #f] @ [#:output "out"] Return as a
5636 monadic value in the absolute file name of @var{file} within the
5637 @var{output} directory of @var{package}. When @var{file} is omitted, return
5638 the name of the @var{output} directory of @var{package}. When @var{target}
5639 is true, use it as a cross-compilation target triplet.
5642 @deffn {Monadic Procedure} package->derivation @var{package} [@var{system}]
5643 @deffnx {Monadic Procedure} package->cross-derivation @var{package} @
5644 @var{target} [@var{system}] Monadic version of @code{package-derivation} and
5645 @code{package-cross-derivation} (@pxref{Pakete definieren}).
5650 @section G-Ausdrücke
5652 @cindex G-expression
5653 @cindex build code quoting
5654 So we have ``derivations'', which represent a sequence of build actions to
5655 be performed to produce an item in the store (@pxref{Ableitungen}). These
5656 build actions are performed when asking the daemon to actually build the
5657 derivations; they are run by the daemon in a container (@pxref{Aufruf des guix-daemon}).
5659 @cindex strata of code
5660 It should come as no surprise that we like to write these build actions in
5661 Scheme. When we do that, we end up with two @dfn{strata} of Scheme
5662 code@footnote{The term @dfn{stratum} in this context was coined by Manuel
5663 Serrano et al.@: in the context of their work on Hop. Oleg Kiselyov, who
5664 has written insightful
5665 @url{http://okmij.org/ftp/meta-programming/#meta-scheme, essays and code on
5666 this topic}, refers to this kind of code generation as @dfn{staging}.}: the
5667 ``host code''---code that defines packages, talks to the daemon, etc.---and
5668 the ``build code''---code that actually performs build actions, such as
5669 making directories, invoking @command{make}, etc.
5671 To describe a derivation and its build actions, one typically needs to embed
5672 build code inside host code. It boils down to manipulating build code as
5673 data, and the homoiconicity of Scheme---code has a direct representation as
5674 data---comes in handy for that. But we need more than the normal
5675 @code{quasiquote} mechanism in Scheme to construct build expressions.
5677 The @code{(guix gexp)} module implements @dfn{G-expressions}, a form of
5678 S-expressions adapted to build expressions. G-expressions, or @dfn{gexps},
5679 consist essentially of three syntactic forms: @code{gexp}, @code{ungexp},
5680 and @code{ungexp-splicing} (or simply: @code{#~}, @code{#$}, and
5681 @code{#$@@}), which are comparable to @code{quasiquote}, @code{unquote}, and
5682 @code{unquote-splicing}, respectively (@pxref{Expression Syntax,
5683 @code{quasiquote},, guile, GNU Guile Reference Manual}). However, there are
5688 Gexps are meant to be written to a file and run or manipulated by other
5692 When a high-level object such as a package or derivation is unquoted inside
5693 a gexp, the result is as if its output file name had been introduced.
5696 Gexps carry information about the packages or derivations they refer to, and
5697 these dependencies are automatically added as inputs to the build processes
5701 @cindex lowering, of high-level objects in gexps
5702 This mechanism is not limited to package and derivation objects:
5703 @dfn{compilers} able to ``lower'' other high-level objects to derivations or
5704 files in the store can be defined, such that these objects can also be
5705 inserted into gexps. For example, a useful type of high-level objects that
5706 can be inserted in a gexp is ``file-like objects'', which make it easy to
5707 add files to the store and to refer to them in derivations and such (see
5708 @code{local-file} and @code{plain-file} below.)
5710 To illustrate the idea, here is an example of a gexp:
5717 (symlink (string-append #$coreutils "/bin/ls")
5721 This gexp can be passed to @code{gexp->derivation}; we obtain a derivation
5722 that builds a directory containing exactly one symlink to
5723 @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls}:
5726 (gexp->derivation "the-thing" build-exp)
5729 As one would expect, the @code{"/gnu/store/@dots{}-coreutils-8.22"} string
5730 is substituted to the reference to the @var{coreutils} package in the actual
5731 build code, and @var{coreutils} is automatically made an input to the
5732 derivation. Likewise, @code{#$output} (equivalent to @code{(ungexp
5733 output)}) is replaced by a string containing the directory name of the
5734 output of the derivation.
5736 @cindex cross compilation
5737 In a cross-compilation context, it is useful to distinguish between
5738 references to the @emph{native} build of a package---that can run on the
5739 host---versus references to cross builds of a package. To that end, the
5740 @code{#+} plays the same role as @code{#$}, but is a reference to a native
5744 (gexp->derivation "vi"
5747 (system* (string-append #+coreutils "/bin/ln")
5749 (string-append #$emacs "/bin/emacs")
5750 (string-append #$output "/bin/vi")))
5751 #:target "mips64el-linux-gnu")
5755 In the example above, the native build of @var{coreutils} is used, so that
5756 @command{ln} can actually run on the host; but then the cross-compiled build
5757 of @var{emacs} is referenced.
5759 @cindex imported modules, for gexps
5760 @findex with-imported-modules
5761 Another gexp feature is @dfn{imported modules}: sometimes you want to be
5762 able to use certain Guile modules from the ``host environment'' in the gexp,
5763 so those modules should be imported in the ``build environment''. The
5764 @code{with-imported-modules} form allows you to express that:
5767 (let ((build (with-imported-modules '((guix build utils))
5769 (use-modules (guix build utils))
5770 (mkdir-p (string-append #$output "/bin"))))))
5771 (gexp->derivation "empty-dir"
5774 (display "success!\n")
5779 In this example, the @code{(guix build utils)} module is automatically
5780 pulled into the isolated build environment of our gexp, such that
5781 @code{(use-modules (guix build utils))} works as expected.
5783 @cindex module closure
5784 @findex source-module-closure
5785 Usually you want the @emph{closure} of the module to be imported---i.e., the
5786 module itself and all the modules it depends on---rather than just the
5787 module; failing to do that, attempts to use the module will fail because of
5788 missing dependent modules. The @code{source-module-closure} procedure
5789 computes the closure of a module by looking at its source file headers,
5790 which comes in handy in this case:
5793 (use-modules (guix modules)) ;for 'source-module-closure'
5795 (with-imported-modules (source-module-closure
5796 '((guix build utils)
5798 (gexp->derivation "something-with-vms"
5800 (use-modules (guix build utils)
5805 @cindex extensions, for gexps
5806 @findex with-extensions
5807 In the same vein, sometimes you want to import not just pure-Scheme modules,
5808 but also ``extensions'' such as Guile bindings to C libraries or other
5809 ``full-blown'' packages. Say you need the @code{guile-json} package
5810 available on the build side, here's how you would do it:
5813 (use-modules (gnu packages guile)) ;for 'guile-json'
5815 (with-extensions (list guile-json)
5816 (gexp->derivation "something-with-json"
5818 (use-modules (json))
5822 The syntactic form to construct gexps is summarized below.
5824 @deffn {Scheme Syntax} #~@var{exp}
5825 @deffnx {Scheme Syntax} (gexp @var{exp})
5826 Return a G-expression containing @var{exp}. @var{exp} may contain one or
5827 more of the following forms:
5831 @itemx (ungexp @var{obj})
5832 Introduce a reference to @var{obj}. @var{obj} may have one of the supported
5833 types, for example a package or a derivation, in which case the
5834 @code{ungexp} form is replaced by its output file name---e.g.,
5835 @code{"/gnu/store/@dots{}-coreutils-8.22}.
5837 If @var{obj} is a list, it is traversed and references to supported objects
5838 are substituted similarly.
5840 If @var{obj} is another gexp, its contents are inserted and its dependencies
5841 are added to those of the containing gexp.
5843 If @var{obj} is another kind of object, it is inserted as is.
5845 @item #$@var{obj}:@var{output}
5846 @itemx (ungexp @var{obj} @var{output})
5847 This is like the form above, but referring explicitly to the @var{output} of
5848 @var{obj}---this is useful when @var{obj} produces multiple outputs
5849 (@pxref{Pakete mit mehreren Ausgaben.}).
5852 @itemx #+@var{obj}:output
5853 @itemx (ungexp-native @var{obj})
5854 @itemx (ungexp-native @var{obj} @var{output})
5855 Same as @code{ungexp}, but produces a reference to the @emph{native} build
5856 of @var{obj} when used in a cross compilation context.
5858 @item #$output[:@var{output}]
5859 @itemx (ungexp output [@var{output}])
5860 Insert a reference to derivation output @var{output}, or to the main output
5861 when @var{output} is omitted.
5863 This only makes sense for gexps passed to @code{gexp->derivation}.
5866 @itemx (ungexp-splicing @var{lst})
5867 Like the above, but splices the contents of @var{lst} inside the containing
5871 @itemx (ungexp-native-splicing @var{lst})
5872 Like the above, but refers to native builds of the objects listed in
5877 G-expressions created by @code{gexp} or @code{#~} are run-time objects of
5878 the @code{gexp?} type (see below.)
5881 @deffn {Scheme Syntax} with-imported-modules @var{modules} @var{body}@dots{}
5882 Mark the gexps defined in @var{body}@dots{} as requiring @var{modules} in
5883 their execution environment.
5885 Each item in @var{modules} can be the name of a module, such as @code{(guix
5886 build utils)}, or it can be a module name, followed by an arrow, followed by
5890 `((guix build utils)
5892 ((guix config) => ,(scheme-file "config.scm"
5893 #~(define-module @dots{}))))
5897 In the example above, the first two modules are taken from the search path,
5898 and the last one is created from the given file-like object.
5900 This form has @emph{lexical} scope: it has an effect on the gexps directly
5901 defined in @var{body}@dots{}, but not on those defined, say, in procedures
5902 called from @var{body}@dots{}.
5905 @deffn {Scheme Syntax} with-extensions @var{extensions} @var{body}@dots{}
5906 Mark the gexps defined in @var{body}@dots{} as requiring @var{extensions} in
5907 their build and execution environment. @var{extensions} is typically a list
5908 of package objects such as those defined in the @code{(gnu packages guile)}
5911 Concretely, the packages listed in @var{extensions} are added to the load
5912 path while compiling imported modules in @var{body}@dots{}; they are also
5913 added to the load path of the gexp returned by @var{body}@dots{}.
5916 @deffn {Scheme Procedure} gexp? @var{obj}
5917 Return @code{#t} if @var{obj} is a G-expression.
5920 G-expressions are meant to be written to disk, either as code building some
5921 derivation, or as plain files in the store. The monadic procedures below
5922 allow you to do that (@pxref{Die Store-Monade}, for more information about
5925 @deffn {Monadic Procedure} gexp->derivation @var{name} @var{exp} @
5926 [#:system (%current-system)] [#:target #f] [#:graft? #t] @ [#:hash #f]
5927 [#:hash-algo #f] @ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @
5928 [#:module-path @var{%load-path}] @ [#:effective-version "2.2"] @
5929 [#:references-graphs #f] [#:allowed-references #f] @
5930 [#:disallowed-references #f] @ [#:leaked-env-vars #f] @ [#:script-name
5931 (string-append @var{name} "-builder")] @ [#:deprecation-warnings #f] @
5932 [#:local-build? #f] [#:substitutable? #t] @ [#:properties '()]
5933 [#:guile-for-build #f] Return a derivation @var{name} that runs @var{exp} (a
5934 gexp) with @var{guile-for-build} (a derivation) on @var{system}; @var{exp}
5935 is stored in a file called @var{script-name}. When @var{target} is true, it
5936 is used as the cross-compilation target triplet for packages referred to by
5939 @var{modules} is deprecated in favor of @code{with-imported-modules}. Its
5940 meaning is to make @var{modules} available in the evaluation context of
5941 @var{exp}; @var{modules} is a list of names of Guile modules searched in
5942 @var{module-path} to be copied in the store, compiled, and made available in
5943 the load path during the execution of @var{exp}---e.g., @code{((guix build
5944 utils) (guix build gnu-build-system))}.
5946 @var{effective-version} determines the string to use when adding extensions
5947 of @var{exp} (see @code{with-extensions}) to the search path---e.g.,
5950 @var{graft?} determines whether packages referred to by @var{exp} should be
5951 grafted when applicable.
5953 When @var{references-graphs} is true, it must be a list of tuples of one of
5954 the following forms:
5957 (@var{file-name} @var{package})
5958 (@var{file-name} @var{package} @var{output})
5959 (@var{file-name} @var{derivation})
5960 (@var{file-name} @var{derivation} @var{output})
5961 (@var{file-name} @var{store-item})
5964 The right-hand-side of each element of @var{references-graphs} is
5965 automatically made an input of the build process of @var{exp}. In the build
5966 environment, each @var{file-name} contains the reference graph of the
5967 corresponding item, in a simple text format.
5969 @var{allowed-references} must be either @code{#f} or a list of output names
5970 and packages. In the latter case, the list denotes store items that the
5971 result is allowed to refer to. Any reference to another store item will
5972 lead to a build error. Similarly for @var{disallowed-references}, which can
5973 list items that must not be referenced by the outputs.
5975 @var{deprecation-warnings} determines whether to show deprecation warnings
5976 while compiling modules. It can be @code{#f}, @code{#t}, or
5979 The other arguments are as for @code{derivation} (@pxref{Ableitungen}).
5982 @cindex file-like objects
5983 The @code{local-file}, @code{plain-file}, @code{computed-file},
5984 @code{program-file}, and @code{scheme-file} procedures below return
5985 @dfn{file-like objects}. That is, when unquoted in a G-expression, these
5986 objects lead to a file in the store. Consider this G-expression:
5989 #~(system* #$(file-append glibc "/sbin/nscd") "-f"
5990 #$(local-file "/tmp/my-nscd.conf"))
5993 The effect here is to ``intern'' @file{/tmp/my-nscd.conf} by copying it to
5994 the store. Once expanded, for instance @i{via} @code{gexp->derivation}, the
5995 G-expression refers to that copy under @file{/gnu/store}; thus, modifying or
5996 removing the file in @file{/tmp} does not have any effect on what the
5997 G-expression does. @code{plain-file} can be used similarly; it differs in
5998 that the file content is directly passed as a string.
6000 @deffn {Scheme Procedure} local-file @var{file} [@var{name}] @
6001 [#:recursive? #f] [#:select? (const #t)] Return an object representing local
6002 file @var{file} to add to the store; this object can be used in a gexp. If
6003 @var{file} is a relative file name, it is looked up relative to the source
6004 file where this form appears. @var{file} will be added to the store under
6005 @var{name}--by default the base name of @var{file}.
6007 When @var{recursive?} is true, the contents of @var{file} are added
6008 recursively; if @var{file} designates a flat file and @var{recursive?} is
6009 true, its contents are added, and its permission bits are kept.
6011 When @var{recursive?} is true, call @code{(@var{select?} @var{file}
6012 @var{stat})} for each directory entry, where @var{file} is the entry's
6013 absolute file name and @var{stat} is the result of @code{lstat}; exclude
6014 entries for which @var{select?} does not return true.
6016 This is the declarative counterpart of the @code{interned-file} monadic
6017 procedure (@pxref{Die Store-Monade, @code{interned-file}}).
6020 @deffn {Scheme Procedure} plain-file @var{name} @var{content}
6021 Return an object representing a text file called @var{name} with the given
6022 @var{content} (a string or a bytevector) to be added to the store.
6024 This is the declarative counterpart of @code{text-file}.
6027 @deffn {Scheme Procedure} computed-file @var{name} @var{gexp} @
6028 [#:options '(#:local-build? #t)] Return an object representing the store
6029 item @var{name}, a file or directory computed by @var{gexp}. @var{options}
6030 is a list of additional arguments to pass to @code{gexp->derivation}.
6032 This is the declarative counterpart of @code{gexp->derivation}.
6035 @deffn {Monadic Procedure} gexp->script @var{name} @var{exp} @
6036 [#:guile (default-guile)] [#:module-path %load-path] Return an executable
6037 script @var{name} that runs @var{exp} using @var{guile}, with @var{exp}'s
6038 imported modules in its search path. Look up @var{exp}'s modules in
6041 The example below builds a script that simply invokes the @command{ls}
6045 (use-modules (guix gexp) (gnu packages base))
6047 (gexp->script "list-files"
6048 #~(execl #$(file-append coreutils "/bin/ls")
6052 When ``running'' it through the store (@pxref{Die Store-Monade,
6053 @code{run-with-store}}), we obtain a derivation that produces an executable
6054 file @file{/gnu/store/@dots{}-list-files} along these lines:
6057 #!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds
6059 (execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls")
6063 @deffn {Scheme Procedure} program-file @var{name} @var{exp} @
6064 [#:guile #f] [#:module-path %load-path] Return an object representing the
6065 executable store item @var{name} that runs @var{gexp}. @var{guile} is the
6066 Guile package used to execute that script. Imported modules of @var{gexp}
6067 are looked up in @var{module-path}.
6069 This is the declarative counterpart of @code{gexp->script}.
6072 @deffn {Monadic Procedure} gexp->file @var{name} @var{exp} @
6073 [#:set-load-path? #t] [#:module-path %load-path] @ [#:splice? #f] @ [#:guile
6074 (default-guile)] Return a derivation that builds a file @var{name}
6075 containing @var{exp}. When @var{splice?} is true, @var{exp} is considered
6076 to be a list of expressions that will be spliced in the resulting file.
6078 When @var{set-load-path?} is true, emit code in the resulting file to set
6079 @code{%load-path} and @code{%load-compiled-path} to honor @var{exp}'s
6080 imported modules. Look up @var{exp}'s modules in @var{module-path}.
6082 The resulting file holds references to all the dependencies of @var{exp} or
6086 @deffn {Scheme Procedure} scheme-file @var{name} @var{exp} [#:splice? #f]
6087 Return an object representing the Scheme file @var{name} that contains
6090 This is the declarative counterpart of @code{gexp->file}.
6093 @deffn {Monadic Procedure} text-file* @var{name} @var{text} @dots{}
6094 Return as a monadic value a derivation that builds a text file containing
6095 all of @var{text}. @var{text} may list, in addition to strings, objects of
6096 any type that can be used in a gexp: packages, derivations, local file
6097 objects, etc. The resulting store file holds references to all these.
6099 This variant should be preferred over @code{text-file} anytime the file to
6100 create will reference items from the store. This is typically the case when
6101 building a configuration file that embeds store file names, like this:
6104 (define (profile.sh)
6105 ;; Return the name of a shell script in the store that
6106 ;; initializes the 'PATH' environment variable.
6107 (text-file* "profile.sh"
6108 "export PATH=" coreutils "/bin:"
6109 grep "/bin:" sed "/bin\n"))
6112 In this example, the resulting @file{/gnu/store/@dots{}-profile.sh} file
6113 will reference @var{coreutils}, @var{grep}, and @var{sed}, thereby
6114 preventing them from being garbage-collected during its lifetime.
6117 @deffn {Scheme Procedure} mixed-text-file @var{name} @var{text} @dots{}
6118 Return an object representing store file @var{name} containing @var{text}.
6119 @var{text} is a sequence of strings and file-like objects, as in:
6122 (mixed-text-file "profile"
6123 "export PATH=" coreutils "/bin:" grep "/bin")
6126 This is the declarative counterpart of @code{text-file*}.
6129 @deffn {Scheme Procedure} file-union @var{name} @var{files}
6130 Return a @code{<computed-file>} that builds a directory containing all of
6131 @var{files}. Each item in @var{files} must be a two-element list where the
6132 first element is the file name to use in the new directory, and the second
6133 element is a gexp denoting the target file. Here's an example:
6137 `(("hosts" ,(plain-file "hosts"
6138 "127.0.0.1 localhost"))
6139 ("bashrc" ,(plain-file "bashrc"
6140 "alias ls='ls --color=auto'"))))
6143 This yields an @code{etc} directory containing these two files.
6146 @deffn {Scheme Procedure} directory-union @var{name} @var{things}
6147 Return a directory that is the union of @var{things}, where @var{things} is
6148 a list of file-like objects denoting directories. For example:
6151 (directory-union "guile+emacs" (list guile emacs))
6154 yields a directory that is the union of the @code{guile} and @code{emacs}
6158 @deffn {Scheme Procedure} file-append @var{obj} @var{suffix} @dots{}
6159 Return a file-like object that expands to the concatenation of @var{obj} and
6160 @var{suffix}, where @var{obj} is a lowerable object and each @var{suffix} is
6163 As an example, consider this gexp:
6166 (gexp->script "run-uname"
6167 #~(system* #$(file-append coreutils
6171 The same effect could be achieved with:
6174 (gexp->script "run-uname"
6175 #~(system* (string-append #$coreutils
6179 There is one difference though: in the @code{file-append} case, the
6180 resulting script contains the absolute file name as a string, whereas in the
6181 second case, the resulting script contains a @code{(string-append @dots{})}
6182 expression to construct the file name @emph{at run time}.
6186 Of course, in addition to gexps embedded in ``host'' code, there are also
6187 modules containing build tools. To make it clear that they are meant to be
6188 used in the build stratum, these modules are kept in the @code{(guix build
6189 @dots{})} name space.
6191 @cindex lowering, of high-level objects in gexps
6192 Internally, high-level objects are @dfn{lowered}, using their compiler, to
6193 either derivations or store items. For instance, lowering a package yields
6194 a derivation, and lowering a @code{plain-file} yields a store item. This is
6195 achieved using the @code{lower-object} monadic procedure.
6197 @deffn {Monadic Procedure} lower-object @var{obj} [@var{system}] @
6198 [#:target #f] Return as a value in @var{%store-monad} the derivation or
6199 store item corresponding to @var{obj} for @var{system}, cross-compiling for
6200 @var{target} if @var{target} is true. @var{obj} must be an object that has
6201 an associated gexp compiler, such as a @code{<package>}.
6204 @node Invoking guix repl
6205 @section Invoking @command{guix repl}
6207 @cindex REPL, read-eval-print loop
6208 The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop}
6209 (REPL) for interactive programming (@pxref{Using Guile Interactively,,,
6210 guile, GNU Guile Reference Manual}). Compared to just launching the
6211 @command{guile} command, @command{guix repl} guarantees that all the Guix
6212 modules and all its dependencies are available in the search path. You can
6217 scheme@@(guile-user)> ,use (gnu packages base)
6218 scheme@@(guile-user)> coreutils
6219 $1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300>
6223 In addition, @command{guix repl} implements a simple machine-readable REPL
6224 protocol for use by @code{(guix inferior)}, a facility to interact with
6225 @dfn{inferiors}, separate processes running a potentially different revision
6228 The available options are as follows:
6231 @item --type=@var{type}
6232 @itemx -t @var{type}
6233 Start a REPL of the given @var{TYPE}, which can be one of the following:
6237 This is default, and it spawns a standard full-featured Guile REPL.
6239 Spawn a REPL that uses the machine-readable protocol. This is the protocol
6240 that the @code{(guix inferior)} module speaks.
6243 @item --listen=@var{Endpunkt}
6244 By default, @command{guix repl} reads from standard input and writes to
6245 standard output. When this option is passed, it will instead listen for
6246 connections on @var{endpoint}. Here are examples of valid options:
6249 @item --listen=tcp:37146
6250 Accept connections on localhost on port 37146.
6252 @item --listen=unix:/tmp/socket
6253 Accept connections on the Unix-domain socket @file{/tmp/socket}.
6257 @c *********************************************************************
6261 This section describes Guix command-line utilities. Some of them are
6262 primarily targeted at developers and users who write new package
6263 definitions, while others are more generally useful. They complement the
6264 Scheme programming interface of Guix in a convenient way.
6267 * Aufruf von guix build:: Pakete aus der Befehlszeile heraus erstellen.
6268 * Aufruf von guix edit:: Paketdefinitionen bearbeiten.
6269 * Aufruf von guix download:: Herunterladen einer Datei und Ausgabe ihres
6271 * Aufruf von guix hash:: Den kryptographischen Hash einer Datei
6273 * Aufruf von guix import:: Paketdefinitionen importieren.
6274 * Aufruf von guix refresh:: Paketdefinitionen aktualisieren.
6275 * Aufruf von guix lint:: Fehler in Paketdefinitionen finden.
6276 * Aufruf von guix size:: Plattenverbrauch profilieren.
6277 * Aufruf von guix graph:: Den Paketgraphen visualisieren.
6278 * Aufruf von guix environment:: Entwicklungsumgebungen einrichten.
6279 * Aufruf von guix publish:: Substitute teilen.
6280 * Aufruf von guix challenge:: Die Substitut-Server anfechten.
6281 * Aufruf von guix copy:: Mit einem entfernten Store Dateien austauschen.
6282 * Aufruf von guix container:: Prozesse isolieren.
6283 * Aufruf von guix weather:: Die Verfügbarkeit von Substituten
6285 * Invoking guix processes:: Listing client processes.
6288 @node Aufruf von guix build
6289 @section Aufruf von @command{guix build}
6291 @cindex package building
6292 @cindex @command{guix build}
6293 The @command{guix build} command builds packages or derivations and their
6294 dependencies, and prints the resulting store paths. Note that it does not
6295 modify the user's profile---this is the job of the @command{guix package}
6296 command (@pxref{Aufruf von guix package}). Thus, it is mainly useful for
6297 distribution developers.
6299 The general syntax is:
6302 guix build @var{options} @var{package-or-derivation}@dots{}
6305 As an example, the following command builds the latest versions of Emacs and
6306 of Guile, displays their build logs, and finally displays the resulting
6310 guix build emacs guile
6313 Similarly, the following command builds all the available packages:
6316 guix build --quiet --keep-going \
6317 `guix package -A | cut -f1,2 --output-delimiter=@@`
6320 @var{package-or-derivation} may be either the name of a package found in the
6321 software distribution such as @code{coreutils} or @code{coreutils@@8.20}, or
6322 a derivation such as @file{/gnu/store/@dots{}-coreutils-8.19.drv}. In the
6323 former case, a package with the corresponding name (and optionally version)
6324 is searched for among the GNU distribution modules (@pxref{Paketmodule}).
6326 Alternatively, the @code{--expression} option may be used to specify a
6327 Scheme expression that evaluates to a package; this is useful when
6328 disambiguating among several same-named packages or package variants is
6331 There may be zero or more @var{options}. The available options are
6332 described in the subsections below.
6335 * Gemeinsame Erstellungsoptionen:: Erstellungsoptionen für die meisten
6337 * Paketumwandlungsoptionen:: Varianten von Paketen erzeugen.
6338 * Zusätzliche Erstellungsoptionen:: Optionen spezifisch für »guix
6340 * Fehlschläge beim Erstellen untersuchen:: Praxiserfahrung bei der
6344 @node Gemeinsame Erstellungsoptionen
6345 @subsection Gemeinsame Erstellungsoptionen
6347 A number of options that control the build process are common to
6348 @command{guix build} and other commands that can spawn builds, such as
6349 @command{guix package} or @command{guix archive}. These are the following:
6353 @item --load-path=@var{directory}
6354 @itemx -L @var{directory}
6355 Add @var{directory} to the front of the package module search path
6356 (@pxref{Paketmodule}).
6358 This allows users to define their own packages and make them visible to the
6363 Keep the build tree of failed builds. Thus, if a build fails, its build
6364 tree is kept under @file{/tmp}, in a directory whose name is shown at the
6365 end of the build log. This is useful when debugging build issues.
6366 @xref{Fehlschläge beim Erstellen untersuchen}, for tips and tricks on how to debug build
6369 This option has no effect when connecting to a remote daemon with a
6370 @code{guix://} URI (@pxref{Der Store, the @code{GUIX_DAEMON_SOCKET}
6375 Keep going when some of the derivations fail to build; return only once all
6376 the builds have either completed or failed.
6378 The default behavior is to stop as soon as one of the specified derivations
6383 Do not build the derivations.
6385 @anchor{fallback-option}
6387 When substituting a pre-built binary fails, fall back to building packages
6388 locally (@pxref{Fehler bei der Substitution}).
6390 @item --substitute-urls=@var{URLs}
6391 @anchor{client-substitute-urls}
6392 Consider @var{urls} the whitespace-separated list of substitute source URLs,
6393 overriding the default list of URLs of @command{guix-daemon}
6394 (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}).
6396 This means that substitutes may be downloaded from @var{urls}, provided they
6397 are signed by a key authorized by the system administrator
6398 (@pxref{Substitute}).
6400 When @var{urls} is the empty string, substitutes are effectively disabled.
6402 @item --no-substitutes
6403 Benutze keine Substitute für Erstellungsergebnisse. Das heißt, dass alle
6404 Objekte lokal erstellt werden müssen, und kein Herunterladen von vorab
6405 erstellten Binärdateien erlaubt ist (@pxref{Substitute}).
6408 Do not ``graft'' packages. In practice, this means that package updates
6409 available as grafts are not applied. @xref{Sicherheitsaktualisierungen}, for more
6410 information on grafts.
6412 @item --rounds=@var{n}
6413 Build each derivation @var{n} times in a row, and raise an error if
6414 consecutive build results are not bit-for-bit identical.
6416 This is a useful way to detect non-deterministic builds processes.
6417 Non-deterministic build processes are a problem because they make it
6418 practically impossible for users to @emph{verify} whether third-party
6419 binaries are genuine. @xref{Aufruf von guix challenge}, for more.
6421 Note that, currently, the differing build results are not kept around, so
6422 you will have to manually investigate in case of an error---e.g., by
6423 stashing one of the build results with @code{guix archive --export}
6424 (@pxref{Aufruf von guix archive}), then rebuilding, and finally comparing the
6427 @item --no-build-hook
6428 Nicht versuchen, Erstellungen über den »Build-Hook« des Daemons auszulagern
6429 (@pxref{Auslagern des Daemons einrichten}). Somit wird lokal erstellt, statt
6430 Erstellungen auf entfernte Maschinen auszulagern.
6432 @item --max-silent-time=@var{Sekunden}
6433 Wenn der Erstellungs- oder Substitutionsprozess länger als
6434 @var{Sekunden}-lang keine Ausgabe erzeugt, wird er abgebrochen und ein
6435 Fehler beim Erstellen gemeldet.
6437 By default, the daemon's setting is honored (@pxref{Aufruf des guix-daemon,
6438 @code{--max-silent-time}}).
6440 @item --timeout=@var{Sekunden}
6441 Entsprechend wird hier der Erstellungs- oder Substitutionsprozess
6442 abgebrochen und als Fehlschlag gemeldet, wenn er mehr als
6443 @var{Sekunden}-lang dauert.
6445 By default, the daemon's setting is honored (@pxref{Aufruf des guix-daemon,
6448 @item --verbosity=@var{level}
6449 Use the given verbosity level. @var{level} must be an integer between 0 and
6450 5; higher means more verbose output. Setting a level of 4 or more may be
6451 helpful when debugging setup issues with the build daemon.
6453 @item --cores=@var{n}
6455 Allow the use of up to @var{n} CPU cores for the build. The special value
6456 @code{0} means to use as many CPU cores as available.
6458 @item --max-jobs=@var{n}
6460 Allow at most @var{n} build jobs in parallel. @xref{Aufruf des guix-daemon,
6461 @code{--max-jobs}}, for details about this option and the equivalent
6462 @command{guix-daemon} option.
6466 Behind the scenes, @command{guix build} is essentially an interface to the
6467 @code{package-derivation} procedure of the @code{(guix packages)} module,
6468 and to the @code{build-derivations} procedure of the @code{(guix
6469 derivations)} module.
6471 In addition to options explicitly passed on the command line, @command{guix
6472 build} and other @command{guix} commands that support building honor the
6473 @code{GUIX_BUILD_OPTIONS} environment variable.
6475 @defvr {Environment Variable} GUIX_BUILD_OPTIONS
6476 Users can define this variable to a list of command line options that will
6477 automatically be used by @command{guix build} and other @command{guix}
6478 commands that can perform builds, as in the example below:
6481 $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"
6484 These options are parsed independently, and the result is appended to the
6485 parsed command-line options.
6489 @node Paketumwandlungsoptionen
6490 @subsection Paketumwandlungsoptionen
6492 @cindex package variants
6493 Another set of command-line options supported by @command{guix build} and
6494 also @command{guix package} are @dfn{package transformation options}. These
6495 are options that make it possible to define @dfn{package variants}---for
6496 instance, packages built from different source code. This is a convenient
6497 way to create customized packages on the fly without having to type in the
6498 definitions of package variants (@pxref{Pakete definieren}).
6502 @item --with-source=@var{source}
6503 @itemx --with-source=@var{package}=@var{source}
6504 @itemx --with-source=@var{package}@@@var{version}=@var{source}
6505 Use @var{source} as the source of @var{package}, and @var{version} as its
6506 version number. @var{source} must be a file name or a URL, as for
6507 @command{guix download} (@pxref{Aufruf von guix download}).
6509 When @var{package} is omitted, it is taken to be the package name specified
6510 on the command line that matches the base of @var{source}---e.g., if
6511 @var{source} is @code{/src/guile-2.0.10.tar.gz}, the corresponding package
6514 Likewise, when @var{version} is omitted, the version string is inferred from
6515 @var{source}; in the previous example, it is @code{2.0.10}.
6517 This option allows users to try out versions of packages other than the one
6518 provided by the distribution. The example below downloads
6519 @file{ed-1.7.tar.gz} from a GNU mirror and uses that as the source for the
6523 guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz
6526 As a developer, @code{--with-source} makes it easy to test release
6530 guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz
6533 @dots{} or to build from a checkout in a pristine environment:
6536 $ git clone git://git.sv.gnu.org/guix.git
6537 $ guix build guix --with-source=guix@@1.0=./guix
6540 @item --with-input=@var{package}=@var{replacement}
6541 Replace dependency on @var{package} by a dependency on @var{replacement}.
6542 @var{package} must be a package name, and @var{replacement} must be a
6543 package specification such as @code{guile} or @code{guile@@1.8}.
6545 For instance, the following command builds Guix, but replaces its dependency
6546 on the current stable version of Guile with a dependency on the legacy
6547 version of Guile, @code{guile@@2.0}:
6550 guix build --with-input=guile=guile@@2.0 guix
6553 This is a recursive, deep replacement. So in this example, both @code{guix}
6554 and its dependency @code{guile-json} (which also depends on @code{guile})
6555 get rebuilt against @code{guile@@2.0}.
6557 This is implemented using the @code{package-input-rewriting} Scheme
6558 procedure (@pxref{Pakete definieren, @code{package-input-rewriting}}).
6560 @item --with-graft=@var{package}=@var{replacement}
6561 This is similar to @code{--with-input} but with an important difference:
6562 instead of rebuilding the whole dependency chain, @var{replacement} is built
6563 and then @dfn{grafted} onto the binaries that were initially referring to
6564 @var{package}. @xref{Sicherheitsaktualisierungen}, for more information on grafts.
6566 For example, the command below grafts version 3.5.4 of GnuTLS onto Wget and
6567 all its dependencies, replacing references to the version of GnuTLS they
6571 guix build --with-graft=gnutls=gnutls@@3.5.4 wget
6574 This has the advantage of being much faster than rebuilding everything. But
6575 there is a caveat: it works if and only if @var{package} and
6576 @var{replacement} are strictly compatible---for example, if they provide a
6577 library, the application binary interface (ABI) of those libraries must be
6578 compatible. If @var{replacement} is somehow incompatible with
6579 @var{package}, then the resulting package may be unusable. Use with care!
6581 @item --with-branch=@var{package}=@var{branch}
6582 @cindex Git, using the latest commit
6583 @cindex latest commit, building
6584 Build @var{package} from the latest commit of @var{branch}. The
6585 @code{source} field of @var{package} must be an origin with the
6586 @code{git-fetch} method (@pxref{„origin“-Referenz}) or a @code{git-checkout}
6587 object; the repository URL is taken from that @code{source}.
6589 For instance, the following command builds @code{guile-sqlite3} from the
6590 latest commit of its @code{master} branch, and then builds @code{guix}
6591 (which depends on it) and @code{cuirass} (which depends on @code{guix})
6592 against this specific @code{guile-sqlite3} build:
6595 guix build --with-branch=guile-sqlite3=master cuirass
6598 @cindex continuous integration
6599 Obviously, since it uses the latest commit of the given branch, the result
6600 of such a command varies over time. Nevertheless it is a convenient way to
6601 rebuild entire software stacks against the latest commit of one or more
6602 packages. This is particularly useful in the context of continuous
6605 Checkouts are kept in a cache under @file{~/.cache/guix/checkouts} to speed
6606 up consecutive accesses to the same repository. You may want to clean it up
6607 once in a while to save disk space.
6609 @item --with-commit=@var{package}=@var{commit}
6610 This is similar to @code{--with-branch}, except that it builds from
6611 @var{commit} rather than the tip of a branch. @var{commit} must be a valid
6612 Git commit SHA1 identifier.
6615 @node Zusätzliche Erstellungsoptionen
6616 @subsection Zusätzliche Erstellungsoptionen
6618 The command-line options presented below are specific to @command{guix
6625 Build quietly, without displaying the build log. Upon completion, the build
6626 log is kept in @file{/var} (or similar) and can always be retrieved using
6627 the @option{--log-file} option.
6629 @item --file=@var{file}
6630 @itemx -f @var{Datei}
6631 Build the package, derivation, or other file-like object that the code
6632 within @var{file} evaluates to (@pxref{G-Ausdrücke, file-like objects}).
6634 As an example, @var{file} might contain a package definition like this
6635 (@pxref{Pakete definieren}):
6638 @verbatiminclude package-hello.scm
6641 @item --expression=@var{expr}
6642 @itemx -e @var{expr}
6643 Build the package or derivation @var{expr} evaluates to.
6645 For example, @var{expr} may be @code{(@@ (gnu packages guile) guile-1.8)},
6646 which unambiguously designates this specific variant of version 1.8 of
6649 Alternatively, @var{expr} may be a G-expression, in which case it is used as
6650 a build program passed to @code{gexp->derivation} (@pxref{G-Ausdrücke}).
6652 Lastly, @var{expr} may refer to a zero-argument monadic procedure
6653 (@pxref{Die Store-Monade}). The procedure must return a derivation as a
6654 monadic value, which is then passed through @code{run-with-store}.
6658 Build the source derivations of the packages, rather than the packages
6661 For instance, @code{guix build -S gcc} returns something like
6662 @file{/gnu/store/@dots{}-gcc-4.7.2.tar.bz2}, which is the GCC source
6665 The returned source tarball is the result of applying any patches and code
6666 snippets specified in the package @code{origin} (@pxref{Pakete definieren}).
6669 Fetch and return the source of @var{package-or-derivation} and all their
6670 dependencies, recursively. This is a handy way to obtain a local copy of
6671 all the source code needed to build @var{packages}, allowing you to
6672 eventually build them even without network access. It is an extension of
6673 the @code{--source} option and can accept one of the following optional
6678 This value causes the @code{--sources} option to behave in the same way as
6679 the @code{--source} option.
6682 Build the source derivations of all packages, including any source that
6683 might be listed as @code{inputs}. This is the default value.
6686 $ guix build --sources tzdata
6687 The following derivations will be built:
6688 /gnu/store/@dots{}-tzdata2015b.tar.gz.drv
6689 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
6693 Build the source derivations of all packages, as well of all transitive
6694 inputs to the packages. This can be used e.g.@: to prefetch package source
6695 for later offline building.
6698 $ guix build --sources=transitive tzdata
6699 The following derivations will be built:
6700 /gnu/store/@dots{}-tzcode2015b.tar.gz.drv
6701 /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv
6702 /gnu/store/@dots{}-grep-2.21.tar.xz.drv
6703 /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv
6704 /gnu/store/@dots{}-make-4.1.tar.xz.drv
6705 /gnu/store/@dots{}-bash-4.3.tar.xz.drv
6711 @item --system=@var{System}
6712 @itemx -s @var{system}
6713 Attempt to build for @var{system}---e.g., @code{i686-linux}---instead of the
6714 system type of the build host.
6716 @quotation Anmerkung
6717 The @code{--system} flag is for @emph{native} compilation and must not be
6718 confused with cross-compilation. See @code{--target} below for information
6719 on cross-compilation.
6722 An example use of this is on Linux-based systems, which can emulate
6723 different personalities. For instance, passing @code{--system=i686-linux}
6724 on an @code{x86_64-linux} system or @code{--system=armhf-linux} on an
6725 @code{aarch64-linux} system allows you to build packages in a complete
6728 @quotation Anmerkung
6729 Building for an @code{armhf-linux} system is unconditionally enabled on
6730 @code{aarch64-linux} machines, although certain aarch64 chipsets do not
6731 allow for this functionality, notably the ThunderX.
6734 Similarly, when transparent emulation with QEMU and @code{binfmt_misc} is
6735 enabled (@pxref{Virtualisierungsdienste, @code{qemu-binfmt-service-type}}),
6736 you can build for any system for which a QEMU @code{binfmt_misc} handler is
6739 Builds for a system other than that of the machine you are using can also be
6740 offloaded to a remote machine of the right architecture. @xref{Auslagern des Daemons einrichten}, for more information on offloading.
6742 @item --target=@var{triplet}
6743 @cindex cross-compilation
6744 Cross-build for @var{triplet}, which must be a valid GNU triplet, such as
6745 @code{"mips64el-linux-gnu"} (@pxref{Specifying target triplets, GNU
6746 configuration triplets,, autoconf, Autoconf}).
6748 @anchor{build-check}
6750 @cindex determinism, checking
6751 @cindex reproducibility, checking
6752 Rebuild @var{package-or-derivation}, which are already available in the
6753 store, and raise an error if the build results are not bit-for-bit
6756 This mechanism allows you to check whether previously installed substitutes
6757 are genuine (@pxref{Substitute}), or whether the build result of a package
6758 is deterministic. @xref{Aufruf von guix challenge}, for more background
6759 information and tools.
6761 Wenn dies zusammen mit @option{--keep-failed} benutzt wird, bleiben die sich
6762 unterscheidenden Ausgaben im Store unter dem Namen
6763 @file{/gnu/store/@dots{}-check}. Dadurch können Unterschiede zwischen den
6764 beiden Ergebnissen leicht erkannt werden.
6767 @cindex repairing store items
6768 @cindex Datenbeschädigung, Behebung
6769 Attempt to repair the specified store items, if they are corrupt, by
6770 re-downloading or rebuilding them.
6772 This operation is not atomic and thus restricted to @code{root}.
6776 Return the derivation paths, not the output paths, of the given packages.
6778 @item --root=@var{file}
6779 @itemx -r @var{file}
6780 @cindex GC roots, adding
6781 @cindex garbage collector roots, adding
6782 Make @var{file} a symlink to the result, and register it as a garbage
6785 Consequently, the results of this @command{guix build} invocation are
6786 protected from garbage collection until @var{file} is removed. When that
6787 option is omitted, build results are eligible for garbage collection as soon
6788 as the build completes. @xref{Aufruf von guix gc}, for more on GC roots.
6791 @cindex build logs, access
6792 Return the build log file names or URLs for the given
6793 @var{package-or-derivation}, or raise an error if build logs are missing.
6795 This works regardless of how packages or derivations are specified. For
6796 instance, the following invocations are equivalent:
6799 guix build --log-file `guix build -d guile`
6800 guix build --log-file `guix build guile`
6801 guix build --log-file guile
6802 guix build --log-file -e '(@@ (gnu packages guile) guile-2.0)'
6805 If a log is unavailable locally, and unless @code{--no-substitutes} is
6806 passed, the command looks for a corresponding log on one of the substitute
6807 servers (as specified with @code{--substitute-urls}.)
6809 So for instance, imagine you want to see the build log of GDB on MIPS, but
6810 you are actually on an @code{x86_64} machine:
6813 $ guix build --log-file gdb -s mips64el-linux
6814 https://hydra.gnu.org/log/@dots{}-gdb-7.10
6817 You can freely access a huge library of build logs!
6820 @node Fehlschläge beim Erstellen untersuchen
6821 @subsection Fehlschläge beim Erstellen untersuchen
6823 @cindex build failures, debugging
6824 When defining a new package (@pxref{Pakete definieren}), you will probably
6825 find yourself spending some time debugging and tweaking the build until it
6826 succeeds. To do that, you need to operate the build commands yourself in an
6827 environment as close as possible to the one the build daemon uses.
6829 To that end, the first thing to do is to use the @option{--keep-failed} or
6830 @option{-K} option of @command{guix build}, which will keep the failed build
6831 tree in @file{/tmp} or whatever directory you specified as @code{TMPDIR}
6832 (@pxref{Aufruf von guix build, @code{--keep-failed}}).
6834 From there on, you can @command{cd} to the failed build tree and source the
6835 @file{environment-variables} file, which contains all the environment
6836 variable definitions that were in place when the build failed. So let's say
6837 you're debugging a build failure in package @code{foo}; a typical session
6838 would look like this:
6842 @dots{} @i{build fails}
6843 $ cd /tmp/guix-build-foo.drv-0
6844 $ source ./environment-variables
6848 Now, you can invoke commands as if you were the daemon (almost) and
6849 troubleshoot your build process.
6851 Sometimes it happens that, for example, a package's tests pass when you run
6852 them manually but they fail when the daemon runs them. This can happen
6853 because the daemon runs builds in containers where, unlike in our
6854 environment above, network access is missing, @file{/bin/sh} does not exist,
6855 etc. (@pxref{Einrichten der Erstellungsumgebung}).
6857 In such cases, you may need to run inspect the build process from within a
6858 container similar to the one the build daemon creates:
6863 $ cd /tmp/guix-build-foo.drv-0
6864 $ guix environment --no-grafts -C foo --ad-hoc strace gdb
6865 [env]# source ./environment-variables
6869 Here, @command{guix environment -C} creates a container and spawns a new
6870 shell in it (@pxref{Aufruf von guix environment}). The @command{--ad-hoc
6871 strace gdb} part adds the @command{strace} and @command{gdb} commands to the
6872 container, which would may find handy while debugging. The
6873 @option{--no-grafts} option makes sure we get the exact same environment,
6874 with ungrafted packages (@pxref{Sicherheitsaktualisierungen}, for more info on grafts).
6876 To get closer to a container like that used by the build daemon, we can
6877 remove @file{/bin/sh}:
6883 (Don't worry, this is harmless: this is all happening in the throw-away
6884 container created by @command{guix environment}.)
6886 The @command{strace} command is probably not in the search path, but we can
6890 [env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check
6893 In this way, not only you will have reproduced the environment variables the
6894 daemon uses, you will also be running the build process in a container
6895 similar to the one the daemon uses.
6898 @node Aufruf von guix edit
6899 @section Invoking @command{guix edit}
6901 @cindex @command{guix edit}
6902 @cindex package definition, editing
6903 So many packages, so many source files! The @command{guix edit} command
6904 facilitates the life of users and packagers by pointing their editor at the
6905 source file containing the definition of the specified packages. For
6909 guix edit gcc@@4.9 vim
6913 launches the program specified in the @code{VISUAL} or in the @code{EDITOR}
6914 environment variable to view the recipe of GCC@tie{}4.9.3 and that of Vim.
6916 If you are using a Guix Git checkout (@pxref{Erstellung aus dem Git}), or have
6917 created your own packages on @code{GUIX_PACKAGE_PATH} (@pxref{Paketmodule}), you will be able to edit the package recipes. In other cases,
6918 you will be able to examine the read-only recipes for packages currently in
6922 @node Aufruf von guix download
6923 @section Invoking @command{guix download}
6925 @cindex @command{guix download}
6926 @cindex downloading package sources
6927 When writing a package definition, developers typically need to download a
6928 source tarball, compute its SHA256 hash, and write that hash in the package
6929 definition (@pxref{Pakete definieren}). The @command{guix download} tool
6930 helps with this task: it downloads a file from the given URI, adds it to the
6931 store, and prints both its file name in the store and its SHA256 hash.
6933 The fact that the downloaded file is added to the store saves bandwidth:
6934 when the developer eventually tries to build the newly defined package with
6935 @command{guix build}, the source tarball will not have to be downloaded
6936 again because it is already in the store. It is also a convenient way to
6937 temporarily stash files, which may be deleted eventually (@pxref{Aufruf von guix gc}).
6939 The @command{guix download} command supports the same URIs as used in
6940 package definitions. In particular, it supports @code{mirror://} URIs.
6941 @code{https} URIs (HTTP over TLS) are supported @emph{provided} the Guile
6942 bindings for GnuTLS are available in the user's environment; when they are
6943 not available, an error is raised. @xref{Guile Preparations, how to install
6944 the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, for more
6947 @command{guix download} verifies HTTPS server certificates by loading the
6948 certificates of X.509 authorities from the directory pointed to by the
6949 @code{SSL_CERT_DIR} environment variable (@pxref{X.509-Zertifikate}),
6950 unless @option{--no-check-certificate} is used.
6952 The following options are available:
6955 @item --format=@var{fmt}
6957 Write the hash in the format specified by @var{fmt}. For more information
6958 on the valid values for @var{fmt}, @pxref{Aufruf von guix hash}.
6960 @item --no-check-certificate
6961 Do not validate the X.509 certificates of HTTPS servers.
6963 When using this option, you have @emph{absolutely no guarantee} that you are
6964 communicating with the authentic server responsible for the given URL, which
6965 makes you vulnerable to ``man-in-the-middle'' attacks.
6967 @item --output=@var{file}
6968 @itemx -o @var{file}
6969 Save the downloaded file to @var{file} instead of adding it to the store.
6972 @node Aufruf von guix hash
6973 @section Invoking @command{guix hash}
6975 @cindex @command{guix hash}
6976 The @command{guix hash} command computes the SHA256 hash of a file. It is
6977 primarily a convenience tool for anyone contributing to the distribution: it
6978 computes the cryptographic hash of a file, which can be used in the
6979 definition of a package (@pxref{Pakete definieren}).
6981 The general syntax is:
6984 guix hash @var{option} @var{file}
6987 When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the
6988 hash of data read from standard input. @command{guix hash} has the
6993 @item --format=@var{fmt}
6995 Write the hash in the format specified by @var{fmt}.
6997 Supported formats: @code{nix-base32}, @code{base32}, @code{base16}
6998 (@code{hex} and @code{hexadecimal} can be used as well).
7000 If the @option{--format} option is not specified, @command{guix hash} will
7001 output the hash in @code{nix-base32}. This representation is used in the
7002 definitions of packages.
7006 Compute the hash on @var{file} recursively.
7008 @c FIXME: Replace xref above with xref to an ``Archive'' section when
7010 In this case, the hash is computed on an archive containing @var{file},
7011 including its children if it is a directory. Some of the metadata of
7012 @var{file} is part of the archive; for instance, when @var{file} is a
7013 regular file, the hash is different depending on whether @var{file} is
7014 executable or not. Metadata such as time stamps has no impact on the hash
7015 (@pxref{Aufruf von guix archive}).
7019 When combined with @option{--recursive}, exclude version control system
7020 directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.)
7023 As an example, here is how you would compute the hash of a Git checkout,
7024 which is useful when using the @code{git-fetch} method (@pxref{„origin“-Referenz}):
7027 $ git clone http://example.org/foo.git
7033 @node Aufruf von guix import
7034 @section Invoking @command{guix import}
7036 @cindex importing packages
7037 @cindex package import
7038 @cindex package conversion
7039 @cindex Invoking @command{guix import}
7040 The @command{guix import} command is useful for people who would like to add
7041 a package to the distribution with as little work as possible---a legitimate
7042 demand. The command knows of a few repositories from which it can
7043 ``import'' package metadata. The result is a package definition, or a
7044 template thereof, in the format we know (@pxref{Pakete definieren}).
7046 The general syntax is:
7049 guix import @var{importer} @var{options}@dots{}
7052 @var{importer} specifies the source from which to import package metadata,
7053 and @var{options} specifies a package identifier and other options specific
7054 to @var{importer}. Currently, the available ``importers'' are:
7058 Import metadata for the given GNU package. This provides a template for the
7059 latest version of that GNU package, including the hash of its source
7060 tarball, and its canonical synopsis and description.
7062 Additional information such as the package dependencies and its license
7063 needs to be figured out manually.
7065 For example, the following command returns a package definition for
7069 guix import gnu hello
7072 Specific command-line options are:
7075 @item --key-download=@var{policy}
7076 As for @code{guix refresh}, specify the policy to handle missing OpenPGP
7077 keys when verifying the package signature. @xref{Aufruf von guix refresh,
7078 @code{--key-download}}.
7083 Import metadata from the @uref{https://pypi.python.org/, Python Package
7084 Index}@footnote{This functionality requires Guile-JSON to be installed.
7085 @xref{Voraussetzungen}.}. Information is taken from the JSON-formatted
7086 description available at @code{pypi.python.org} and usually includes all the
7087 relevant information, including package dependencies. For maximum
7088 efficiency, it is recommended to install the @command{unzip} utility, so
7089 that the importer can unzip Python wheels and gather data from them.
7091 The command below imports metadata for the @code{itsdangerous} Python
7095 guix import pypi itsdangerous
7101 Traverse the dependency graph of the given upstream package recursively and
7102 generate package expressions for all those packages that are not yet in
7108 Import metadata from @uref{https://rubygems.org/, RubyGems}@footnote{This
7109 functionality requires Guile-JSON to be installed. @xref{Voraussetzungen}.}.
7110 Information is taken from the JSON-formatted description available at
7111 @code{rubygems.org} and includes most relevant information, including
7112 runtime dependencies. There are some caveats, however. The metadata
7113 doesn't distinguish between synopses and descriptions, so the same string is
7114 used for both fields. Additionally, the details of non-Ruby dependencies
7115 required to build native extensions is unavailable and left as an exercise
7118 The command below imports metadata for the @code{rails} Ruby package:
7121 guix import gem rails
7127 Traverse the dependency graph of the given upstream package recursively and
7128 generate package expressions for all those packages that are not yet in
7134 Import metadata from @uref{https://www.metacpan.org/,
7135 MetaCPAN}@footnote{This functionality requires Guile-JSON to be installed.
7136 @xref{Voraussetzungen}.}. Information is taken from the JSON-formatted
7137 metadata provided through @uref{https://fastapi.metacpan.org/, MetaCPAN's
7138 API} and includes most relevant information, such as module dependencies.
7139 License information should be checked closely. If Perl is available in the
7140 store, then the @code{corelist} utility will be used to filter core modules
7141 out of the list of dependencies.
7143 The command command below imports metadata for the @code{Acme::Boolean} Perl
7147 guix import cpan Acme::Boolean
7152 @cindex Bioconductor
7153 Import metadata from @uref{https://cran.r-project.org/, CRAN}, the central
7154 repository for the @uref{http://r-project.org, GNU@tie{}R statistical and
7155 graphical environment}.
7157 Information is extracted from the @code{DESCRIPTION} file of the package.
7159 The command command below imports metadata for the @code{Cairo} R package:
7162 guix import cran Cairo
7165 When @code{--recursive} is added, the importer will traverse the dependency
7166 graph of the given upstream package recursively and generate package
7167 expressions for all those packages that are not yet in Guix.
7169 When @code{--archive=bioconductor} is added, metadata is imported from
7170 @uref{https://www.bioconductor.org/, Bioconductor}, a repository of R
7171 packages for for the analysis and comprehension of high-throughput genomic
7172 data in bioinformatics.
7174 Information is extracted from the @code{DESCRIPTION} file of a package
7175 published on the web interface of the Bioconductor SVN repository.
7177 The command below imports metadata for the @code{GenomicRanges} R package:
7180 guix import cran --archive=bioconductor GenomicRanges
7186 Import metadata from @uref{http://www.ctan.org/, CTAN}, the comprehensive
7187 TeX archive network for TeX packages that are part of the
7188 @uref{https://www.tug.org/texlive/, TeX Live distribution}.
7190 Information about the package is obtained through the XML API provided by
7191 CTAN, while the source code is downloaded from the SVN repository of the Tex
7192 Live project. This is done because the CTAN does not keep versioned
7195 The command command below imports metadata for the @code{fontspec} TeX
7199 guix import texlive fontspec
7202 When @code{--archive=DIRECTORY} is added, the source code is downloaded not
7203 from the @file{latex} sub-directory of the @file{texmf-dist/source} tree in
7204 the TeX Live SVN repository, but from the specified sibling directory under
7207 The command below imports metadata for the @code{ifxetex} package from CTAN
7208 while fetching the sources from the directory @file{texmf/source/generic}:
7211 guix import texlive --archive=generic ifxetex
7215 @cindex JSON, import
7216 Import package metadata from a local JSON file@footnote{This functionality
7217 requires Guile-JSON to be installed. @xref{Voraussetzungen}.}. Consider the
7218 following example package definition in JSON format:
7224 "source": "mirror://gnu/hello/hello-2.10.tar.gz",
7225 "build-system": "gnu",
7226 "home-page": "https://www.gnu.org/software/hello/",
7227 "synopsis": "Hello, GNU world: An example GNU package",
7228 "description": "GNU Hello prints a greeting.",
7229 "license": "GPL-3.0+",
7230 "native-inputs": ["gcc@@6"]
7234 The field names are the same as for the @code{<package>} record
7235 (@xref{Pakete definieren}). References to other packages are provided as
7236 JSON lists of quoted package specification strings such as @code{guile} or
7239 The importer also supports a more explicit source definition using the
7240 common fields for @code{<origin>} records:
7246 "method": "url-fetch",
7247 "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
7249 "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
7256 The command below reads metadata from the JSON file @code{hello.json} and
7257 outputs a package expression:
7260 guix import json hello.json
7264 Import metadata from a local copy of the source of the
7265 @uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This relies
7266 on the @command{nix-instantiate} command of @uref{http://nixos.org/nix/,
7267 Nix}.}. Package definitions in Nixpkgs are typically written in a mixture
7268 of Nix-language and Bash code. This command only imports the high-level
7269 package structure that is written in the Nix language. It normally includes
7270 all the basic fields of a package definition.
7272 When importing a GNU package, the synopsis and descriptions are replaced by
7273 their canonical upstream variant.
7275 Usually, you will first need to do:
7278 export NIX_REMOTE=daemon
7282 so that @command{nix-instantiate} does not try to open the Nix database.
7284 As an example, the command below imports the package definition of
7285 LibreOffice (more precisely, it imports the definition of the package bound
7286 to the @code{libreoffice} top-level attribute):
7289 guix import nix ~/path/to/nixpkgs libreoffice
7294 Import metadata from the Haskell community's central package archive
7295 @uref{https://hackage.haskell.org/, Hackage}. Information is taken from
7296 Cabal files and includes all the relevant information, including package
7299 Specific command-line options are:
7304 Read a Cabal file from standard input.
7305 @item --no-test-dependencies
7307 Do not include dependencies required only by the test suites.
7308 @item --cabal-environment=@var{alist}
7309 @itemx -e @var{alist}
7310 @var{alist} is a Scheme alist defining the environment in which the Cabal
7311 conditionals are evaluated. The accepted keys are: @code{os}, @code{arch},
7312 @code{impl} and a string representing the name of a flag. The value
7313 associated with a flag has to be either the symbol @code{true} or
7314 @code{false}. The value associated with other keys has to conform to the
7315 Cabal file format definition. The default value associated with the keys
7316 @code{os}, @code{arch} and @code{impl} is @samp{linux}, @samp{x86_64} and
7317 @samp{ghc}, respectively.
7320 Traverse the dependency graph of the given upstream package recursively and
7321 generate package expressions for all those packages that are not yet in
7325 The command below imports metadata for the latest version of the @code{HTTP}
7326 Haskell package without including test dependencies and specifying the value
7327 of the flag @samp{network-uri} as @code{false}:
7330 guix import hackage -t -e "'((\"network-uri\" . false))" HTTP
7333 A specific package version may optionally be specified by following the
7334 package name by an at-sign and a version number as in the following example:
7337 guix import hackage mtl@@2.1.3.1
7342 The @code{stackage} importer is a wrapper around the @code{hackage} one. It
7343 takes a package name, looks up the package version included in a long-term
7344 support (LTS) @uref{https://www.stackage.org, Stackage} release and uses the
7345 @code{hackage} importer to retrieve its metadata. Note that it is up to you
7346 to select an LTS release compatible with the GHC compiler used by Guix.
7348 Specific command-line options are:
7351 @item --no-test-dependencies
7353 Do not include dependencies required only by the test suites.
7354 @item --lts-version=@var{version}
7355 @itemx -l @var{version}
7356 @var{version} is the desired LTS release version. If omitted the latest
7360 Traverse the dependency graph of the given upstream package recursively and
7361 generate package expressions for all those packages that are not yet in
7365 The command below imports metadata for the @code{HTTP} Haskell package
7366 included in the LTS Stackage release version 7.18:
7369 guix import stackage --lts-version=7.18 HTTP
7374 Import metadata from an Emacs Lisp Package Archive (ELPA) package repository
7375 (@pxref{Packages,,, emacs, The GNU Emacs Manual}).
7377 Specific command-line options are:
7380 @item --archive=@var{repo}
7381 @itemx -a @var{repo}
7382 @var{repo} identifies the archive repository from which to retrieve the
7383 information. Currently the supported repositories and their identifiers
7387 @uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu}
7388 identifier. This is the default.
7390 Packages from @code{elpa.gnu.org} are signed with one of the keys contained
7391 in the GnuPG keyring at @file{share/emacs/25.1/etc/package-keyring.gpg} (or
7392 similar) in the @code{emacs} package (@pxref{Package Installation, ELPA
7393 package signatures,, emacs, The GNU Emacs Manual}).
7396 @uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the
7397 @code{melpa-stable} identifier.
7400 @uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa}
7406 Traverse the dependency graph of the given upstream package recursively and
7407 generate package expressions for all those packages that are not yet in
7413 Import metadata from the crates.io Rust package repository
7414 @uref{https://crates.io, crates.io}.
7419 Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package
7420 repository used by the OCaml community.
7423 The structure of the @command{guix import} code is modular. It would be
7424 useful to have more importers for other package formats, and your help is
7425 welcome here (@pxref{Mitwirken}).
7427 @node Aufruf von guix refresh
7428 @section Invoking @command{guix refresh}
7430 @cindex @command{guix refresh}
7431 The primary audience of the @command{guix refresh} command is developers of
7432 the GNU software distribution. By default, it reports any packages provided
7433 by the distribution that are outdated compared to the latest upstream
7438 gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
7439 gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0
7442 Alternately, one can specify packages to consider, in which case a warning
7443 is emitted for packages that lack an updater:
7446 $ guix refresh coreutils guile guile-ssh
7447 gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
7448 gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13
7451 @command{guix refresh} browses the upstream repository of each package and
7452 determines the highest version number of the releases therein. The command
7453 knows how to update specific types of packages: GNU packages, ELPA packages,
7454 etc.---see the documentation for @option{--type} below. There are many
7455 packages, though, for which it lacks a method to determine whether a new
7456 upstream release is available. However, the mechanism is extensible, so
7457 feel free to get in touch with us to add a new method!
7459 Sometimes the upstream name differs from the package name used in Guix, and
7460 @command{guix refresh} needs a little help. Most updaters honor the
7461 @code{upstream-name} property in package definitions, which can be used to
7465 (define-public network-manager
7467 (name "network-manager")
7469 (properties '((upstream-name . "NetworkManager")))))
7472 When passed @code{--update}, it modifies distribution source files to update
7473 the version numbers and source tarball hashes of those package recipes
7474 (@pxref{Pakete definieren}). This is achieved by downloading each package's
7475 latest source tarball and its associated OpenPGP signature, authenticating
7476 the downloaded tarball against its signature using @command{gpg}, and
7477 finally computing its hash. When the public key used to sign the tarball is
7478 missing from the user's keyring, an attempt is made to automatically
7479 retrieve it from a public key server; when this is successful, the key is
7480 added to the user's keyring; otherwise, @command{guix refresh} reports an
7483 The following options are supported:
7487 @item --expression=@var{expr}
7488 @itemx -e @var{expr}
7489 Consider the package @var{expr} evaluates to.
7491 This is useful to precisely refer to a package, as in this example:
7494 guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)'
7497 This command lists the dependents of the ``final'' libc (essentially all the
7502 Update distribution source files (package recipes) in place. This is
7503 usually run from a checkout of the Guix source tree (@pxref{Guix vor der Installation ausführen}):
7506 $ ./pre-inst-env guix refresh -s non-core -u
7509 @xref{Pakete definieren}, for more information on package definitions.
7511 @item --select=[@var{subset}]
7512 @itemx -s @var{subset}
7513 Select all the packages in @var{subset}, one of @code{core} or
7516 The @code{core} subset refers to all the packages at the core of the
7517 distribution---i.e., packages that are used to build ``everything else''.
7518 This includes GCC, libc, Binutils, Bash, etc. Usually, changing one of
7519 these packages in the distribution entails a rebuild of all the others.
7520 Thus, such updates are an inconvenience to users in terms of build time or
7521 bandwidth used to achieve the upgrade.
7523 The @code{non-core} subset refers to the remaining packages. It is
7524 typically useful in cases where an update of the core packages would be
7527 @item --manifest=@var{Datei}
7528 @itemx -m @var{Datei}
7529 Select all the packages from the manifest in @var{file}. This is useful to
7530 check if any packages of the user manifest can be updated.
7532 @item --type=@var{updater}
7533 @itemx -t @var{updater}
7534 Select only packages handled by @var{updater} (may be a comma-separated list
7535 of updaters). Currently, @var{updater} may be one of:
7539 the updater for GNU packages;
7541 the updater for GNOME packages;
7543 the updater for KDE packages;
7545 the updater for X.org packages;
7547 the updater for packages hosted on kernel.org;
7549 the updater for @uref{http://elpa.gnu.org/, ELPA} packages;
7551 the updater for @uref{https://cran.r-project.org/, CRAN} packages;
7553 the updater for @uref{https://www.bioconductor.org/, Bioconductor} R
7556 the updater for @uref{http://www.cpan.org/, CPAN} packages;
7558 the updater for @uref{https://pypi.python.org, PyPI} packages.
7560 the updater for @uref{https://rubygems.org, RubyGems} packages.
7562 the updater for @uref{https://github.com, GitHub} packages.
7564 the updater for @uref{https://hackage.haskell.org, Hackage} packages.
7566 the updater for @uref{https://www.stackage.org, Stackage} packages.
7568 the updater for @uref{https://crates.io, Crates} packages.
7571 For instance, the following command only checks for updates of Emacs
7572 packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages:
7575 $ guix refresh --type=elpa,cran
7576 gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
7577 gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9
7582 In addition, @command{guix refresh} can be passed one or more package names,
7586 $ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8
7590 The command above specifically updates the @code{emacs} and @code{idutils}
7591 packages. The @code{--select} option would have no effect in this case.
7593 When considering whether to upgrade a package, it is sometimes convenient to
7594 know which packages would be affected by the upgrade and should be checked
7595 for compatibility. For this the following option may be used when passing
7596 @command{guix refresh} one or more package names:
7600 @item --list-updaters
7602 List available updaters and exit (see @option{--type} above.)
7604 For each updater, display the fraction of packages it covers; at the end,
7605 display the fraction of packages covered by all these updaters.
7607 @item --list-dependent
7609 List top-level dependent packages that would need to be rebuilt as a result
7610 of upgrading one or more packages.
7612 @xref{Aufruf von guix graph, the @code{reverse-package} type of @command{guix
7613 graph}}, for information on how to visualize the list of dependents of a
7618 Be aware that the @code{--list-dependent} option only @emph{approximates}
7619 the rebuilds that would be required as a result of an upgrade. More
7620 rebuilds might be required under some circumstances.
7623 $ guix refresh --list-dependent flex
7624 Building the following 120 packages would ensure 213 dependent packages are rebuilt:
7625 hop@@2.4.0 geiser@@0.4 notmuch@@0.18 mu@@0.9.9.5 cflow@@1.4 idutils@@4.6 @dots{}
7628 The command above lists a set of packages that could be built to check for
7629 compatibility with an upgraded @code{flex} package.
7631 The following options can be used to customize GnuPG operation:
7635 @item --gpg=@var{command}
7636 Use @var{command} as the GnuPG 2.x command. @var{command} is searched for
7639 @item --keyring=@var{file}
7640 Use @var{file} as the keyring for upstream keys. @var{file} must be in the
7641 @dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx}
7642 and the GNU@tie{}Privacy Guard (GPG) can manipulate these files
7643 (@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard},
7644 for information on a tool to manipulate keybox files).
7646 When this option is omitted, @command{guix refresh} uses
7647 @file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream
7648 signing keys. OpenPGP signatures are checked against keys from this
7649 keyring; missing keys are downloaded to this keyring as well (see
7650 @option{--key-download} below.)
7652 You can export keys from your default GPG keyring into a keybox file using
7653 commands like this one:
7656 gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx
7659 Likewise, you can fetch keys to a specific keybox file like this:
7662 gpg --no-default-keyring --keyring mykeyring.kbx \
7663 --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
7666 @ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU
7667 Privacy Guard}, for more information on GPG's @option{--keyring} option.
7669 @item --key-download=@var{policy}
7670 Handle missing OpenPGP keys according to @var{policy}, which may be one of:
7674 Always download missing OpenPGP keys from the key server, and add them to
7675 the user's GnuPG keyring.
7678 Never try to download missing OpenPGP keys. Instead just bail out.
7681 When a package signed with an unknown OpenPGP key is encountered, ask the
7682 user whether to download it or not. This is the default behavior.
7685 @item --key-server=@var{host}
7686 Use @var{host} as the OpenPGP key server when importing a public key.
7690 The @code{github} updater uses the @uref{https://developer.github.com/v3/,
7691 GitHub API} to query for new releases. When used repeatedly e.g.@: when
7692 refreshing all packages, GitHub will eventually refuse to answer any further
7693 API requests. By default 60 API requests per hour are allowed, and a full
7694 refresh on all GitHub packages in Guix requires more than this.
7695 Authentication with GitHub through the use of an API token alleviates these
7696 limits. To use an API token, set the environment variable
7697 @code{GUIX_GITHUB_TOKEN} to a token procured from
7698 @uref{https://github.com/settings/tokens} or otherwise.
7701 @node Aufruf von guix lint
7702 @section Invoking @command{guix lint}
7704 @cindex @command{guix lint}
7705 @cindex package, checking for errors
7706 The @command{guix lint} command is meant to help package developers avoid
7707 common errors and use a consistent style. It runs a number of checks on a
7708 given set of packages in order to find common mistakes in their
7709 definitions. Available @dfn{checkers} include (see @code{--list-checkers}
7710 for a complete list):
7715 Validate certain typographical and stylistic rules about package
7716 descriptions and synopses.
7718 @item inputs-should-be-native
7719 Identify inputs that should most likely be native inputs.
7724 @itemx source-file-name
7725 Probe @code{home-page} and @code{source} URLs and report those that are
7726 invalid. Suggest a @code{mirror://} URL when applicable. Check that the
7727 source file name is meaningful, e.g.@: is not just a version number or
7728 ``git-checkout'', without a declared @code{file-name} (@pxref{„origin“-Referenz}).
7731 @cindex security vulnerabilities
7732 @cindex CVE, Common Vulnerabilities and Exposures
7733 Report known vulnerabilities found in the Common Vulnerabilities and
7734 Exposures (CVE) databases of the current and past year
7735 @uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US NIST}.
7737 To view information about a particular vulnerability, visit pages such as:
7741 @indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD}
7743 @indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD}
7747 where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g.,
7748 @code{CVE-2015-7554}.
7750 Package developers can specify in package recipes the
7751 @uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)} name
7752 and version of the package when they differ from the name or version that
7753 Guix uses, as in this example:
7759 ;; CPE calls this package "grub2".
7760 (properties '((cpe-name . "grub2")
7761 (cpe-version . "2.3")))
7764 @c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>.
7765 Some entries in the CVE database do not specify which version of a package
7766 they apply to, and would thus ``stick around'' forever. Package developers
7767 who found CVE alerts and verified they can be ignored can declare them as in
7774 ;; These CVEs no longer apply and can be safely ignored.
7775 (properties `((lint-hidden-cve . ("CVE-2011-0433"
7778 "CVE-2011-5244")))))
7782 Warn about obvious source code formatting issues: trailing white space, use
7783 of tabulations, etc.
7786 The general syntax is:
7789 guix lint @var{options} @var{package}@dots{}
7792 If no package is given on the command line, then all packages are checked.
7793 The @var{options} may be zero or more of the following:
7796 @item --list-checkers
7798 List and describe all the available checkers that will be run on packages
7803 Only enable the checkers specified in a comma-separated list using the names
7804 returned by @code{--list-checkers}.
7808 @node Aufruf von guix size
7809 @section Invoking @command{guix size}
7812 @cindex package size
7814 @cindex @command{guix size}
7815 The @command{guix size} command helps package developers profile the disk
7816 usage of packages. It is easy to overlook the impact of an additional
7817 dependency added to a package, or the impact of using a single output for a
7818 package that could easily be split (@pxref{Pakete mit mehreren Ausgaben.}). Such are the typical issues that @command{guix size} can
7821 The command can be passed one or more package specifications such as
7822 @code{gcc@@4.8} or @code{guile:debug}, or a file name in the store.
7823 Consider this example:
7826 $ guix size coreutils
7827 store item total self
7828 /gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1%
7829 /gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6%
7830 /gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0%
7831 /gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4%
7832 /gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9%
7833 /gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5%
7834 /gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3%
7835 /gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2%
7840 The store items listed here constitute the @dfn{transitive closure} of
7841 Coreutils---i.e., Coreutils and all its dependencies, recursively---as would
7845 $ guix gc -R /gnu/store/@dots{}-coreutils-8.23
7848 Here the output shows three columns next to store items. The first column,
7849 labeled ``total'', shows the size in mebibytes (MiB) of the closure of the
7850 store item---that is, its own size plus the size of all its dependencies.
7851 The next column, labeled ``self'', shows the size of the item itself. The
7852 last column shows the ratio of the size of the item itself to the space
7853 occupied by all the items listed here.
7855 In this example, we see that the closure of Coreutils weighs in at
7856 79@tie{}MiB, most of which is taken by libc and GCC's run-time support
7857 libraries. (That libc and GCC's libraries represent a large fraction of the
7858 closure is not a problem @i{per se} because they are always available on the
7861 When the package(s) passed to @command{guix size} are available in the
7862 store@footnote{More precisely, @command{guix size} looks for the
7863 @emph{ungrafted} variant of the given package(s), as returned by @code{guix
7864 build @var{package} --no-grafts}. @xref{Sicherheitsaktualisierungen}, for information
7865 on grafts.}, @command{guix size} queries the daemon to determine its
7866 dependencies, and measures its size in the store, similar to @command{du -ms
7867 --apparent-size} (@pxref{du invocation,,, coreutils, GNU Coreutils}).
7869 When the given packages are @emph{not} in the store, @command{guix size}
7870 reports information based on the available substitutes
7871 (@pxref{Substitute}). This makes it possible it to profile disk usage of
7872 store items that are not even on disk, only available remotely.
7874 You can also specify several package names:
7877 $ guix size coreutils grep sed bash
7878 store item total self
7879 /gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4%
7880 /gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8%
7881 /gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6%
7882 /gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2%
7888 In this example we see that the combination of the four packages takes
7889 102.3@tie{}MiB in total, which is much less than the sum of each closure
7890 since they have a lot of dependencies in common.
7892 The available options are:
7896 @item --substitute-urls=@var{URLs}
7897 Use substitute information from @var{urls}. @xref{client-substitute-urls,
7898 the same option for @code{guix build}}.
7900 @item --sort=@var{key}
7901 Sort lines according to @var{key}, one of the following options:
7905 the size of each item (the default);
7907 the total size of the item's closure.
7910 @item --map-file=@var{file}
7911 Write a graphical map of disk usage in PNG format to @var{file}.
7913 For the example above, the map looks like this:
7915 @image{images/coreutils-size-map,5in,, map of Coreutils disk usage produced
7916 by @command{guix size}}
7918 This option requires that
7919 @uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be
7920 installed and visible in Guile's module search path. When that is not the
7921 case, @command{guix size} fails as it tries to load it.
7923 @item --system=@var{System}
7924 @itemx -s @var{system}
7925 Consider packages for @var{system}---e.g., @code{x86_64-linux}.
7929 @node Aufruf von guix graph
7930 @section Invoking @command{guix graph}
7933 @cindex @command{guix graph}
7934 @cindex Paketabhängigkeiten
7935 Packages and their dependencies form a @dfn{graph}, specifically a directed
7936 acyclic graph (DAG). It can quickly become difficult to have a mental model
7937 of the package DAG, so the @command{guix graph} command provides a visual
7938 representation of the DAG. By default, @command{guix graph} emits a DAG
7939 representation in the input format of @uref{http://www.graphviz.org/,
7940 Graphviz}, so its output can be passed directly to the @command{dot} command
7941 of Graphviz. It can also emit an HTML page with embedded JavaScript code to
7942 display a ``chord diagram'' in a Web browser, using the
7943 @uref{https://d3js.org/, d3.js} library, or emit Cypher queries to construct
7944 a graph in a graph database supporting the @uref{http://www.opencypher.org/,
7945 openCypher} query language. The general syntax is:
7948 guix graph @var{options} @var{package}@dots{}
7951 For example, the following command generates a PDF file representing the
7952 package DAG for the GNU@tie{}Core Utilities, showing its build-time
7956 guix graph coreutils | dot -Tpdf > dag.pdf
7959 The output looks like this:
7961 @image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils}
7963 Nice little graph, no?
7965 But there is more than one graph! The one above is concise: it is the graph
7966 of package objects, omitting implicit inputs such as GCC, libc, grep, etc.
7967 It is often useful to have such a concise graph, but sometimes one may want
7968 to see more details. @command{guix graph} supports several types of graphs,
7969 allowing you to choose the level of detail:
7973 This is the default type used in the example above. It shows the DAG of
7974 package objects, excluding implicit dependencies. It is concise, but
7975 filters out many details.
7977 @item reverse-package
7978 This shows the @emph{reverse} DAG of packages. For example:
7981 guix graph --type=reverse-package ocaml
7984 ...@: yields the graph of packages that depend on OCaml.
7986 Note that for core packages this can yield huge graphs. If all you want is
7987 to know the number of packages that depend on a given package, use
7988 @command{guix refresh --list-dependent} (@pxref{Aufruf von guix refresh,
7989 @option{--list-dependent}}).
7992 This is the package DAG, @emph{including} implicit inputs.
7994 For instance, the following command:
7997 guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf
8000 ...@: yields this bigger graph:
8002 @image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU
8005 At the bottom of the graph, we see all the implicit inputs of
8006 @var{gnu-build-system} (@pxref{Erstellungssysteme, @code{gnu-build-system}}).
8008 Now, note that the dependencies of these implicit inputs---that is, the
8009 @dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown here,
8013 Similar to @code{bag-emerged}, but this time including all the bootstrap
8016 @item bag-with-origins
8017 Similar to @code{bag}, but also showing origins and their dependencies.
8020 This is the most detailed representation: It shows the DAG of derivations
8021 (@pxref{Ableitungen}) and plain store items. Compared to the above
8022 representation, many additional nodes are visible, including build scripts,
8023 patches, Guile modules, etc.
8025 For this type of graph, it is also possible to pass a @file{.drv} file name
8026 instead of a package name, as in:
8029 guix graph -t derivation `guix system build -d my-config.scm`
8033 This is the graph of @dfn{package modules} (@pxref{Paketmodule}). For
8034 example, the following command shows the graph for the package module that
8035 defines the @code{guile} package:
8038 guix graph -t module guile | dot -Tpdf > module-graph.pdf
8042 All the types above correspond to @emph{build-time dependencies}. The
8043 following graph type represents the @emph{run-time dependencies}:
8047 This is the graph of @dfn{references} of a package output, as returned by
8048 @command{guix gc --references} (@pxref{Aufruf von guix gc}).
8050 If the given package output is not available in the store, @command{guix
8051 graph} attempts to obtain dependency information from substitutes.
8053 Here you can also pass a store file name instead of a package name. For
8054 example, the command below produces the reference graph of your profile
8055 (which can be big!):
8058 guix graph -t references `readlink -f ~/.guix-profile`
8062 This is the graph of the @dfn{referrers} of a store item, as returned by
8063 @command{guix gc --referrers} (@pxref{Aufruf von guix gc}).
8065 This relies exclusively on local information from your store. For instance,
8066 let us suppose that the current Inkscape is available in 10 profiles on your
8067 machine; @command{guix graph -t referrers inkscape} will show a graph rooted
8068 at Inkscape and with those 10 profiles linked to it.
8070 It can help determine what is preventing a store item from being garbage
8075 The available options are the following:
8078 @item --type=@var{type}
8079 @itemx -t @var{type}
8080 Produce a graph output of @var{type}, where @var{type} must be one of the
8081 values listed above.
8084 List the supported graph types.
8086 @item --backend=@var{backend}
8087 @itemx -b @var{backend}
8088 Produce a graph using the selected @var{backend}.
8090 @item --list-backends
8091 List the supported graph backends.
8093 Currently, the available backends are Graphviz and d3.js.
8095 @item --expression=@var{expr}
8096 @itemx -e @var{expr}
8097 Consider the package @var{expr} evaluates to.
8099 This is useful to precisely refer to a package, as in this example:
8102 guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)'
8105 @item --system=@var{System}
8106 @itemx -s @var{system}
8107 Display the graph for @var{system}---e.g., @code{i686-linux}.
8109 The package dependency graph is largely architecture-independent, but there
8110 are some architecture-dependent bits that this option allows you to
8115 @node Aufruf von guix environment
8116 @section Invoking @command{guix environment}
8118 @cindex reproducible build environments
8119 @cindex development environments
8120 @cindex @command{guix environment}
8121 @cindex environment, package build environment
8122 The purpose of @command{guix environment} is to assist hackers in creating
8123 reproducible development environments without polluting their package
8124 profile. The @command{guix environment} tool takes one or more packages,
8125 builds all of their inputs, and creates a shell environment to use them.
8127 The general syntax is:
8130 guix environment @var{options} @var{package}@dots{}
8133 The following example spawns a new shell set up for the development of
8137 guix environment guile
8140 If the needed dependencies are not built yet, @command{guix environment}
8141 automatically builds them. The environment of the new shell is an augmented
8142 version of the environment that @command{guix environment} was run in. It
8143 contains the necessary search paths for building the given package added to
8144 the existing environment variables. To create a ``pure'' environment, in
8145 which the original environment variables have been unset, use the
8146 @code{--pure} option@footnote{Users sometimes wrongfully augment environment
8147 variables such as @code{PATH} in their @file{~/.bashrc} file. As a
8148 consequence, when @code{guix environment} launches it, Bash may read
8149 @file{~/.bashrc}, thereby introducing ``impurities'' in these environment
8150 variables. It is an error to define such environment variables in
8151 @file{.bashrc}; instead, they should be defined in @file{.bash_profile},
8152 which is sourced only by log-in shells. @xref{Bash Startup Files,,, bash,
8153 The GNU Bash Reference Manual}, for details on Bash start-up files.}.
8155 @vindex GUIX_ENVIRONMENT
8156 @command{guix environment} defines the @code{GUIX_ENVIRONMENT} variable in
8157 the shell it spawns; its value is the file name of the profile of this
8158 environment. This allows users to, say, define a specific prompt for
8159 development environments in their @file{.bashrc} (@pxref{Bash Startup
8160 Files,,, bash, The GNU Bash Reference Manual}):
8163 if [ -n "$GUIX_ENVIRONMENT" ]
8165 export PS1="\u@@\h \w [dev]\$ "
8170 ...@: or to browse the profile:
8173 $ ls "$GUIX_ENVIRONMENT/bin"
8176 Additionally, more than one package may be specified, in which case the
8177 union of the inputs for the given packages are used. For example, the
8178 command below spawns a shell where all of the dependencies of both Guile and
8179 Emacs are available:
8182 guix environment guile emacs
8185 Sometimes an interactive shell session is not desired. An arbitrary command
8186 may be invoked by placing the @code{--} token to separate the command from
8187 the rest of the arguments:
8190 guix environment guile -- make -j4
8193 In other situations, it is more convenient to specify the list of packages
8194 needed in the environment. For example, the following command runs
8195 @command{python} from an environment containing Python@tie{}2.7 and NumPy:
8198 guix environment --ad-hoc python2-numpy python-2.7 -- python
8201 Furthermore, one might want the dependencies of a package and also some
8202 additional packages that are not build-time or runtime dependencies, but are
8203 useful when developing nonetheless. Because of this, the @code{--ad-hoc}
8204 flag is positional. Packages appearing before @code{--ad-hoc} are
8205 interpreted as packages whose dependencies will be added to the
8206 environment. Packages appearing after are interpreted as packages that will
8207 be added to the environment directly. For example, the following command
8208 creates a Guix development environment that additionally includes Git and
8212 guix environment guix --ad-hoc git strace
8215 Sometimes it is desirable to isolate the environment as much as possible,
8216 for maximal purity and reproducibility. In particular, when using Guix on a
8217 host distro that is not GuixSD, it is desirable to prevent access to
8218 @file{/usr/bin} and other system-wide resources from the development
8219 environment. For example, the following command spawns a Guile REPL in a
8220 ``container'' where only the store and the current working directory are
8224 guix environment --ad-hoc --container guile -- guile
8227 @quotation Anmerkung
8228 The @code{--container} option requires Linux-libre 3.19 or newer.
8231 The available options are summarized below.
8234 @item --root=@var{file}
8235 @itemx -r @var{file}
8236 @cindex persistent environment
8237 @cindex garbage collector root, for environments
8238 Make @var{file} a symlink to the profile for this environment, and register
8239 it as a garbage collector root.
8241 This is useful if you want to protect your environment from garbage
8242 collection, to make it ``persistent''.
8244 When this option is omitted, the environment is protected from garbage
8245 collection only for the duration of the @command{guix environment} session.
8246 This means that next time you recreate the same environment, you could have
8247 to rebuild or re-download packages. @xref{Aufruf von guix gc}, for more on GC
8250 @item --expression=@var{expr}
8251 @itemx -e @var{expr}
8252 Create an environment for the package or list of packages that @var{expr}
8255 For example, running:
8258 guix environment -e '(@@ (gnu packages maths) petsc-openmpi)'
8261 starts a shell with the environment for this specific variant of the PETSc
8267 guix environment --ad-hoc -e '(@@ (gnu) %base-packages)'
8270 starts a shell with all the GuixSD base packages available.
8272 The above commands only use the default output of the given packages. To
8273 select other outputs, two element tuples can be specified:
8276 guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")'
8279 @item --load=@var{file}
8280 @itemx -l @var{file}
8281 Create an environment for the package or list of packages that the code
8282 within @var{file} evaluates to.
8284 Zum Beispiel könnte die @var{Datei} eine Definition wie diese enthalten
8285 (@pxref{Pakete definieren}):
8288 @verbatiminclude environment-gdb.scm
8291 @item --manifest=@var{Datei}
8292 @itemx -m @var{Datei}
8293 Create an environment for the packages contained in the manifest object
8294 returned by the Scheme code in @var{file}.
8296 This is similar to the same-named option in @command{guix package}
8297 (@pxref{profile-manifest, @option{--manifest}}) and uses the same manifest
8301 Include all specified packages in the resulting environment, as if an @i{ad
8302 hoc} package were defined with them as inputs. This option is useful for
8303 quickly creating an environment without having to write a package expression
8304 to contain the desired inputs.
8306 For instance, the command:
8309 guix environment --ad-hoc guile guile-sdl -- guile
8312 runs @command{guile} in an environment where Guile and Guile-SDL are
8315 Note that this example implicitly asks for the default output of
8316 @code{guile} and @code{guile-sdl}, but it is possible to ask for a specific
8317 output---e.g., @code{glib:bin} asks for the @code{bin} output of @code{glib}
8318 (@pxref{Pakete mit mehreren Ausgaben.}).
8320 This option may be composed with the default behavior of @command{guix
8321 environment}. Packages appearing before @code{--ad-hoc} are interpreted as
8322 packages whose dependencies will be added to the environment, the default
8323 behavior. Packages appearing after are interpreted as packages that will be
8324 added to the environment directly.
8327 Unset existing environment variables when building the new environment.
8328 This has the effect of creating an environment in which search paths only
8329 contain package inputs.
8331 @item --search-paths
8332 Display the environment variable definitions that make up the environment.
8334 @item --system=@var{System}
8335 @itemx -s @var{system}
8336 Attempt to build for @var{system}---e.g., @code{i686-linux}.
8341 Run @var{command} within an isolated container. The current working
8342 directory outside the container is mapped inside the container.
8343 Additionally, unless overridden with @code{--user}, a dummy home directory
8344 is created that matches the current user's home directory, and
8345 @file{/etc/passwd} is configured accordingly. The spawned process runs as
8346 the current user outside the container, but has root privileges in the
8347 context of the container.
8351 For containers, share the network namespace with the host system.
8352 Containers created without this flag only have access to the loopback
8355 @item --link-profile
8357 For containers, link the environment profile to @file{~/.guix-profile}
8358 within the container. This is equivalent to running the command @command{ln
8359 -s $GUIX_ENVIRONMENT ~/.guix-profile} within the container. Linking will
8360 fail and abort the environment if the directory already exists, which will
8361 certainly be the case if @command{guix environment} was invoked in the
8362 user's home directory.
8364 Certain packages are configured to look in @code{~/.guix-profile} for
8365 configuration files and data;@footnote{For example, the @code{fontconfig}
8366 package inspects @file{~/.guix-profile/share/fonts} for additional fonts.}
8367 @code{--link-profile} allows these programs to behave as expected within the
8370 @item --user=@var{user}
8371 @itemx -u @var{user}
8372 For containers, use the username @var{user} in place of the current user.
8373 The generated @file{/etc/passwd} entry within the container will contain the
8374 name @var{user}; the home directory will be @file{/home/USER}; and no user
8375 GECOS data will be copied. @var{user} need not exist on the system.
8377 Additionally, any shared or exposed path (see @code{--share} and
8378 @code{--expose} respectively) whose target is within the current user's home
8379 directory will be remapped relative to @file{/home/USER}; this includes the
8380 automatic mapping of the current working directory.
8383 # will expose paths as /home/foo/wd, /home/foo/test, and /home/foo/target
8385 guix environment --container --user=foo \
8386 --expose=$HOME/test \
8387 --expose=/tmp/target=$HOME/target
8390 While this will limit the leaking of user identity through home paths and
8391 each of the user fields, this is only one useful component of a broader
8392 privacy/anonymity solution---not one in and of itself.
8394 @item --expose=@var{source}[=@var{target}]
8395 For containers, expose the file system @var{source} from the host system as
8396 the read-only file system @var{target} within the container. If
8397 @var{target} is not specified, @var{source} is used as the target mount
8398 point in the container.
8400 The example below spawns a Guile REPL in a container in which the user's
8401 home directory is accessible read-only via the @file{/exchange} directory:
8404 guix environment --container --expose=$HOME=/exchange --ad-hoc guile -- guile
8407 @item --share=@var{source}[=@var{target}]
8408 For containers, share the file system @var{source} from the host system as
8409 the writable file system @var{target} within the container. If @var{target}
8410 is not specified, @var{source} is used as the target mount point in the
8413 The example below spawns a Guile REPL in a container in which the user's
8414 home directory is accessible for both reading and writing via the
8415 @file{/exchange} directory:
8418 guix environment --container --share=$HOME=/exchange --ad-hoc guile -- guile
8422 @command{guix environment} also supports all of the common build options
8423 that @command{guix build} supports (@pxref{Gemeinsame Erstellungsoptionen}).
8426 @node Aufruf von guix publish
8427 @section Invoking @command{guix publish}
8429 @cindex @command{guix publish}
8430 The purpose of @command{guix publish} is to enable users to easily share
8431 their store with others, who can then use it as a substitute server
8432 (@pxref{Substitute}).
8434 When @command{guix publish} runs, it spawns an HTTP server which allows
8435 anyone with network access to obtain substitutes from it. This means that
8436 any machine running Guix can also act as if it were a build farm, since the
8437 HTTP interface is compatible with Hydra, the software behind the
8438 @code{hydra.gnu.org} build farm.
8440 For security, each substitute is signed, allowing recipients to check their
8441 authenticity and integrity (@pxref{Substitute}). Because @command{guix
8442 publish} uses the signing key of the system, which is only readable by the
8443 system administrator, it must be started as root; the @code{--user} option
8444 makes it drop root privileges early on.
8446 The signing key pair must be generated before @command{guix publish} is
8447 launched, using @command{guix archive --generate-key} (@pxref{Aufruf von guix archive}).
8449 The general syntax is:
8452 guix publish @var{options}@dots{}
8455 Running @command{guix publish} without any additional arguments will spawn
8456 an HTTP server on port 8080:
8462 Once a publishing server has been authorized (@pxref{Aufruf von guix archive}), the daemon may download substitutes from it:
8465 guix-daemon --substitute-urls=http://example.org:8080
8468 By default, @command{guix publish} compresses archives on the fly as it
8469 serves them. This ``on-the-fly'' mode is convenient in that it requires no
8470 setup and is immediately available. However, when serving lots of clients,
8471 we recommend using the @option{--cache} option, which enables caching of the
8472 archives before they are sent to clients---see below for details. The
8473 @command{guix weather} command provides a handy way to check what a server
8474 provides (@pxref{Aufruf von guix weather}).
8476 As a bonus, @command{guix publish} also serves as a content-addressed mirror
8477 for source files referenced in @code{origin} records (@pxref{„origin“-Referenz}). For instance, assuming @command{guix publish} is running on
8478 @code{example.org}, the following URL returns the raw
8479 @file{hello-2.10.tar.gz} file with the given SHA256 hash (represented in
8480 @code{nix-base32} format, @pxref{Aufruf von guix hash}):
8483 http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i
8486 Obviously, these URLs only work for files that are in the store; in other
8487 cases, they return 404 (``Not Found'').
8489 @cindex build logs, publication
8490 Build logs are available from @code{/log} URLs like:
8493 http://example.org/log/gwspk@dots{}-guile-2.2.3
8497 When @command{guix-daemon} is configured to save compressed build logs, as
8498 is the case by default (@pxref{Aufruf des guix-daemon}), @code{/log} URLs
8499 return the compressed log as-is, with an appropriate @code{Content-Type}
8500 and/or @code{Content-Encoding} header. We recommend running
8501 @command{guix-daemon} with @code{--log-compression=gzip} since Web browsers
8502 can automatically decompress it, which is not the case with bzip2
8505 The following options are available:
8508 @item --port=@var{port}
8509 @itemx -p @var{port}
8510 Listen for HTTP requests on @var{port}.
8512 @item --listen=@var{host}
8513 Listen on the network interface for @var{host}. The default is to accept
8514 connections from any interface.
8516 @item --user=@var{user}
8517 @itemx -u @var{user}
8518 Change privileges to @var{user} as soon as possible---i.e., once the server
8519 socket is open and the signing key has been read.
8521 @item --compression[=@var{level}]
8522 @itemx -C [@var{level}]
8523 Compress data using the given @var{level}. When @var{level} is zero,
8524 disable compression. The range 1 to 9 corresponds to different gzip
8525 compression levels: 1 is the fastest, and 9 is the best (CPU-intensive).
8528 Unless @option{--cache} is used, compression occurs on the fly and the
8529 compressed streams are not cached. Thus, to reduce load on the machine that
8530 runs @command{guix publish}, it may be a good idea to choose a low
8531 compression level, to run @command{guix publish} behind a caching proxy, or
8532 to use @option{--cache}. Using @option{--cache} has the advantage that it
8533 allows @command{guix publish} to add @code{Content-Length} HTTP header to
8536 @item --cache=@var{directory}
8537 @itemx -c @var{directory}
8538 Cache archives and meta-data (@code{.narinfo} URLs) to @var{directory} and
8539 only serve archives that are in cache.
8541 When this option is omitted, archives and meta-data are created on-the-fly.
8542 This can reduce the available bandwidth, especially when compression is
8543 enabled, since this may become CPU-bound. Another drawback of the default
8544 mode is that the length of archives is not known in advance, so
8545 @command{guix publish} does not add a @code{Content-Length} HTTP header to
8546 its responses, which in turn prevents clients from knowing the amount of
8547 data being downloaded.
8549 Conversely, when @option{--cache} is used, the first request for a store
8550 item (@i{via} a @code{.narinfo} URL) returns 404 and triggers a background
8551 process to @dfn{bake} the archive---computing its @code{.narinfo} and
8552 compressing the archive, if needed. Once the archive is cached in
8553 @var{directory}, subsequent requests succeed and are served directly from
8554 the cache, which guarantees that clients get the best possible bandwidth.
8556 The ``baking'' process is performed by worker threads. By default, one
8557 thread per CPU core is created, but this can be customized. See
8558 @option{--workers} below.
8560 When @option{--ttl} is used, cached entries are automatically deleted when
8563 @item --workers=@var{N}
8564 When @option{--cache} is used, request the allocation of @var{N} worker
8565 threads to ``bake'' archives.
8567 @item --ttl=@var{ttl}
8568 Produce @code{Cache-Control} HTTP headers that advertise a time-to-live
8569 (TTL) of @var{ttl}. @var{ttl} must denote a duration: @code{5d} means 5
8570 days, @code{1m} means 1 month, and so on.
8572 This allows the user's Guix to keep substitute information in cache for
8573 @var{ttl}. However, note that @code{guix publish} does not itself guarantee
8574 that the store items it provides will indeed remain available for as long as
8577 Additionally, when @option{--cache} is used, cached entries that have not
8578 been accessed for @var{ttl} and that no longer have a corresponding item in
8579 the store, may be deleted.
8581 @item --nar-path=@var{path}
8582 Use @var{path} as the prefix for the URLs of ``nar'' files (@pxref{Aufruf von guix archive, normalized archives}).
8584 By default, nars are served at a URL such as
8585 @code{/nar/gzip/@dots{}-coreutils-8.25}. This option allows you to change
8586 the @code{/nar} part to @var{path}.
8588 @item --public-key=@var{file}
8589 @itemx --private-key=@var{file}
8590 Use the specific @var{file}s as the public/private key pair used to sign the
8591 store items being published.
8593 The files must correspond to the same key pair (the private key is used for
8594 signing and the public key is merely advertised in the signature metadata).
8595 They must contain keys in the canonical s-expression format as produced by
8596 @command{guix archive --generate-key} (@pxref{Aufruf von guix archive}). By
8597 default, @file{/etc/guix/signing-key.pub} and
8598 @file{/etc/guix/signing-key.sec} are used.
8600 @item --repl[=@var{port}]
8601 @itemx -r [@var{port}]
8602 Spawn a Guile REPL server (@pxref{REPL Servers,,, guile, GNU Guile Reference
8603 Manual}) on @var{port} (37146 by default). This is used primarily for
8604 debugging a running @command{guix publish} server.
8607 Enabling @command{guix publish} on a GuixSD system is a one-liner: just
8608 instantiate a @code{guix-publish-service-type} service in the
8609 @code{services} field of the @code{operating-system} declaration
8610 (@pxref{guix-publish-service-type, @code{guix-publish-service-type}}).
8612 If you are instead running Guix on a ``foreign distro'', follow these
8617 If your host distro uses the systemd init system:
8620 # ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
8621 /etc/systemd/system/
8622 # systemctl start guix-publish && systemctl enable guix-publish
8626 Wenn Ihre Wirts-Distribution als »init«-System Upstart verwendet:
8629 # ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
8630 # start guix-publish
8634 Otherwise, proceed similarly with your distro's init system.
8637 @node Aufruf von guix challenge
8638 @section Invoking @command{guix challenge}
8640 @cindex Reproduzierbare Erstellungen
8641 @cindex verifiable builds
8642 @cindex @command{guix challenge}
8644 Do the binaries provided by this server really correspond to the source code
8645 it claims to build? Is a package build process deterministic? These are the
8646 questions the @command{guix challenge} command attempts to answer.
8648 The former is obviously an important question: Before using a substitute
8649 server (@pxref{Substitute}), one had better @emph{verify} that it provides
8650 the right binaries, and thus @emph{challenge} it. The latter is what
8651 enables the former: If package builds are deterministic, then independent
8652 builds of the package should yield the exact same result, bit for bit; if a
8653 server provides a binary different from the one obtained locally, it may be
8654 either corrupt or malicious.
8656 We know that the hash that shows up in @file{/gnu/store} file names is the
8657 hash of all the inputs of the process that built the file or
8658 directory---compilers, libraries, build scripts,
8659 etc. (@pxref{Einführung}). Assuming deterministic build processes, one
8660 store file name should map to exactly one build output. @command{guix
8661 challenge} checks whether there is, indeed, a single mapping by comparing
8662 the build outputs of several independent builds of any given store item.
8664 The command output looks like this:
8667 $ guix challenge --substitute-urls="https://hydra.gnu.org https://guix.example.org"
8668 updating list of substitutes from 'https://hydra.gnu.org'... 100.0%
8669 updating list of substitutes from 'https://guix.example.org'... 100.0%
8670 /gnu/store/@dots{}-openssl-1.0.2d contents differ:
8671 local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
8672 https://hydra.gnu.org/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
8673 https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
8674 /gnu/store/@dots{}-git-2.5.0 contents differ:
8675 local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
8676 https://hydra.gnu.org/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
8677 https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
8678 /gnu/store/@dots{}-pius-2.1.1 contents differ:
8679 local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
8680 https://hydra.gnu.org/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
8681 https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs
8685 6,406 store items were analyzed:
8686 - 4,749 (74.1%) were identical
8687 - 525 (8.2%) differed
8688 - 1,132 (17.7%) were inconclusive
8692 In this example, @command{guix challenge} first scans the store to determine
8693 the set of locally-built derivations---as opposed to store items that were
8694 downloaded from a substitute server---and then queries all the substitute
8695 servers. It then reports those store items for which the servers obtained a
8696 result different from the local build.
8698 @cindex non-determinism, in package builds
8699 As an example, @code{guix.example.org} always gets a different answer.
8700 Conversely, @code{hydra.gnu.org} agrees with local builds, except in the
8701 case of Git. This might indicate that the build process of Git is
8702 non-deterministic, meaning that its output varies as a function of various
8703 things that Guix does not fully control, in spite of building packages in
8704 isolated environments (@pxref{Funktionalitäten}). Most common sources of
8705 non-determinism include the addition of timestamps in build results, the
8706 inclusion of random numbers, and directory listings sorted by inode number.
8707 See @uref{https://reproducible-builds.org/docs/}, for more information.
8709 To find out what is wrong with this Git binary, we can do something along
8710 these lines (@pxref{Aufruf von guix archive}):
8713 $ wget -q -O - https://hydra.gnu.org/nar/@dots{}-git-2.5.0 \
8714 | guix archive -x /tmp/git
8715 $ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git
8718 This command shows the difference between the files resulting from the local
8719 build, and the files resulting from the build on @code{hydra.gnu.org}
8720 (@pxref{Overview, Comparing and Merging Files,, diffutils, Comparing and
8721 Merging Files}). The @command{diff} command works great for text files.
8722 When binary files differ, a better option is @uref{https://diffoscope.org/,
8723 Diffoscope}, a tool that helps visualize differences for all kinds of files.
8725 Once you have done that work, you can tell whether the differences are due
8726 to a non-deterministic build process or to a malicious server. We try hard
8727 to remove sources of non-determinism in packages to make it easier to verify
8728 substitutes, but of course, this is a process that involves not just Guix,
8729 but a large part of the free software community. In the meantime,
8730 @command{guix challenge} is one tool to help address the problem.
8732 If you are writing packages for Guix, you are encouraged to check whether
8733 @code{hydra.gnu.org} and other substitute servers obtain the same build
8734 result as you did with:
8737 $ guix challenge @var{package}
8741 where @var{package} is a package specification such as @code{guile@@2.0} or
8744 The general syntax is:
8747 guix challenge @var{options} [@var{packages}@dots{}]
8750 When a difference is found between the hash of a locally-built item and that
8751 of a server-provided substitute, or among substitutes provided by different
8752 servers, the command displays it as in the example above and its exit code
8753 is 2 (other non-zero exit codes denote other kinds of errors.)
8755 The one option that matters is:
8759 @item --substitute-urls=@var{URLs}
8760 Consider @var{urls} the whitespace-separated list of substitute source URLs
8765 Show details about matches (identical contents) in addition to information
8770 @node Aufruf von guix copy
8771 @section Invoking @command{guix copy}
8773 @cindex copy, of store items, over SSH
8774 @cindex SSH, copy of store items
8775 @cindex sharing store items across machines
8776 @cindex transferring store items across machines
8777 The @command{guix copy} command copies items from the store of one machine
8778 to that of another machine over a secure shell (SSH)
8779 connection@footnote{This command is available only when Guile-SSH was
8780 found. @xref{Voraussetzungen}, for details.}. For example, the following
8781 command copies the @code{coreutils} package, the user's profile, and all
8782 their dependencies over to @var{host}, logged in as @var{user}:
8785 guix copy --to=@var{user}@@@var{host} \
8786 coreutils `readlink -f ~/.guix-profile`
8789 If some of the items to be copied are already present on @var{host}, they
8790 are not actually sent.
8792 The command below retrieves @code{libreoffice} and @code{gimp} from
8793 @var{host}, assuming they are available there:
8796 guix copy --from=@var{host} libreoffice gimp
8799 The SSH connection is established using the Guile-SSH client, which is
8800 compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and
8801 @file{~/.ssh/config}, and uses the SSH agent for authentication.
8803 The key used to sign items that are sent must be accepted by the remote
8804 machine. Likewise, the key used by the remote machine to sign items you are
8805 retrieving must be in @file{/etc/guix/acl} so it is accepted by your own
8806 daemon. @xref{Aufruf von guix archive}, for more information about store item
8809 The general syntax is:
8812 guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{}
8815 You must always specify one of the following options:
8818 @item --to=@var{spec}
8819 @itemx --from=@var{spec}
8820 Specify the host to send to or receive from. @var{spec} must be an SSH spec
8821 such as @code{example.org}, @code{charlie@@example.org}, or
8822 @code{charlie@@example.org:2222}.
8825 The @var{items} can be either package names, such as @code{gimp}, or store
8826 items, such as @file{/gnu/store/@dots{}-idutils-4.6}.
8828 When specifying the name of a package to send, it is first built if needed,
8829 unless @option{--dry-run} was specified. Common build options are supported
8830 (@pxref{Gemeinsame Erstellungsoptionen}).
8833 @node Aufruf von guix container
8834 @section Invoking @command{guix container}
8836 @cindex @command{guix container}
8837 @quotation Anmerkung
8838 As of version @value{VERSION}, this tool is experimental. The interface is
8839 subject to radical change in the future.
8842 The purpose of @command{guix container} is to manipulate processes running
8843 within an isolated environment, commonly known as a ``container'', typically
8844 created by the @command{guix environment} (@pxref{Aufruf von guix environment}) and @command{guix system container} (@pxref{Aufruf von guix system}) commands.
8846 The general syntax is:
8849 guix container @var{action} @var{options}@dots{}
8852 @var{action} specifies the operation to perform with a container, and
8853 @var{options} specifies the context-specific arguments for the action.
8855 The following actions are available:
8859 Execute a command within the context of a running container.
8864 guix container exec @var{pid} @var{program} @var{arguments}@dots{}
8867 @var{pid} specifies the process ID of the running container. @var{program}
8868 specifies an executable file name within the root file system of the
8869 container. @var{arguments} are the additional options that will be passed
8872 The following command launches an interactive login shell inside a GuixSD
8873 container, started by @command{guix system container}, and whose process ID
8877 guix container exec 9001 /run/current-system/profile/bin/bash --login
8880 Note that the @var{pid} cannot be the parent process of a container. It
8881 must be PID 1 of the container or one of its child processes.
8885 @node Aufruf von guix weather
8886 @section Invoking @command{guix weather}
8888 Occasionally you're grumpy because substitutes are lacking and you end up
8889 building packages by yourself (@pxref{Substitute}). The @command{guix
8890 weather} command reports on substitute availability on the specified servers
8891 so you can have an idea of whether you'll be grumpy today. It can sometimes
8892 be useful info as a user, but it is primarily useful to people running
8893 @command{guix publish} (@pxref{Aufruf von guix publish}).
8895 @cindex statistics, for substitutes
8896 @cindex availability of substitutes
8897 @cindex substitute availability
8898 @cindex weather, substitute availability
8899 Here's a sample run:
8902 $ guix weather --substitute-urls=https://guix.example.org
8903 computing 5,872 package derivations for x86_64-linux...
8904 looking for 6,128 store items on https://guix.example.org..
8905 updating list of substitutes from 'https://guix.example.org'... 100.0%
8906 https://guix.example.org
8907 43.4% substitutes available (2,658 out of 6,128)
8908 7,032.5 MiB of nars (compressed)
8909 19,824.2 MiB on disk (uncompressed)
8910 0.030 seconds per request (182.9 seconds in total)
8911 33.5 requests per second
8913 9.8% (342 out of 3,470) of the missing items are queued
8915 x86_64-linux: 518 (59.7%)
8916 i686-linux: 221 (25.5%)
8917 aarch64-linux: 128 (14.8%)
8918 build rate: 23.41 builds per hour
8919 x86_64-linux: 11.16 builds per hour
8920 i686-linux: 6.03 builds per hour
8921 aarch64-linux: 6.41 builds per hour
8924 @cindex continuous integration, statistics
8925 As you can see, it reports the fraction of all the packages for which
8926 substitutes are available on the server---regardless of whether substitutes
8927 are enabled, and regardless of whether this server's signing key is
8928 authorized. It also reports the size of the compressed archives (``nars'')
8929 provided by the server, the size the corresponding store items occupy in the
8930 store (assuming deduplication is turned off), and the server's throughput.
8931 The second part gives continuous integration (CI) statistics, if the server
8934 To achieve that, @command{guix weather} queries over HTTP(S) meta-data
8935 (@dfn{narinfos}) for all the relevant store items. Like @command{guix
8936 challenge}, it ignores signatures on those substitutes, which is innocuous
8937 since the command only gathers statistics and cannot install those
8940 Among other things, it is possible to query specific system types and
8941 specific package sets. The available options are listed below.
8944 @item --substitute-urls=@var{URLs}
8945 @var{urls} is the space-separated list of substitute server URLs to query.
8946 When this option is omitted, the default set of substitute servers is
8949 @item --system=@var{System}
8950 @itemx -s @var{system}
8951 Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This
8952 option can be repeated, in which case @command{guix weather} will query
8953 substitutes for several system types.
8955 @item --manifest=@var{Datei}
8956 Instead of querying substitutes for all the packages, only ask for those
8957 specified in @var{file}. @var{file} must contain a @dfn{manifest}, as with
8958 the @code{-m} option of @command{guix package} (@pxref{Aufruf von guix package}).
8961 @node Invoking guix processes
8962 @section Invoking @command{guix processes}
8964 The @command{guix processes} command can be useful to developers and system
8965 administrators, especially on multi-user machines and on build farms: it
8966 lists the current sessions (connections to the daemon), as well as
8967 information about the processes involved@footnote{Remote sessions, when
8968 @command{guix-daemon} is started with @option{--listen} specifying a TCP
8969 endpoint, are @emph{not} listed.}. Here's an example of the information it
8973 $ sudo guix processes
8976 ClientCommand: guix environment --ad-hoc python
8980 ClientCommand: guix publish -u guix-publish -p 3000 -C 9 @dots{}
8984 ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
8985 LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock
8986 LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock
8987 LockHeld: /gnu/store/@dots{}-libjpeg-turbo-2.0.0.lock
8988 ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800
8989 ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800
8990 ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800
8993 In this example we see that @command{guix-daemon} has three clients:
8994 @command{guix environment}, @command{guix publish}, and the Cuirass
8995 continuous integration tool; their process identifier (PID) is given by the
8996 @code{ClientPID} field. The @code{SessionPID} field gives the PID of the
8997 @command{guix-daemon} sub-process of this particular session.
8999 The @code{LockHeld} fields show which store items are currently locked by
9000 this session, which corresponds to store items being built or substituted
9001 (the @code{LockHeld} field is not displayed when @command{guix processes} is
9002 not running as root.) Last, by looking at the @code{ChildProcess} field, we
9003 understand that these three builds are being offloaded (@pxref{Auslagern des Daemons einrichten}).
9005 The output is in Recutils format so we can use the handy @command{recsel}
9006 command to select sessions of interest (@pxref{Selection Expressions,,,
9007 recutils, GNU recutils manual}). As an example, the command shows the
9008 command line and PID of the client that triggered the build of a Perl
9012 $ sudo guix processes | \
9013 recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
9015 ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{}
9018 @c *********************************************************************
9019 @node GNU-Distribution
9020 @chapter GNU-Distribution
9022 @cindex Guix System Distribution
9024 Guix comes with a distribution of the GNU system consisting entirely of free
9025 software@footnote{The term ``free'' here refers to the
9026 @url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to users of
9027 that software}.}. The distribution can be installed on its own
9028 (@pxref{Systeminstallation}), but it is also possible to install Guix as a
9029 package manager on top of an installed GNU/Linux system
9030 (@pxref{Installation}). To distinguish between the two, we refer to the
9031 standalone distribution as the Guix System Distribution, or GuixSD.
9033 The distribution provides core GNU packages such as GNU libc, GCC, and
9034 Binutils, as well as many GNU and non-GNU applications. The complete list
9035 of available packages can be browsed
9036 @url{http://www.gnu.org/software/guix/packages,on-line} or by running
9037 @command{guix package} (@pxref{Aufruf von guix package}):
9040 guix package --list-available
9043 Our goal is to provide a practical 100% free software distribution of
9044 Linux-based and other variants of GNU, with a focus on the promotion and
9045 tight integration of GNU components, and an emphasis on programs and tools
9046 that help users exert that freedom.
9048 Packages are currently available on the following platforms:
9053 Intel/AMD @code{x86_64} architecture, Linux-Libre kernel;
9056 Intel 32-bit architecture (IA32), Linux-Libre kernel;
9059 ARMv7-A architecture with hard float, Thumb-2 and NEON, using the EABI
9060 hard-float application binary interface (ABI), and Linux-Libre kernel.
9063 little-endian 64-bit ARMv8-A processors, Linux-Libre kernel. This is
9064 currently in an experimental stage, with limited support.
9065 @xref{Mitwirken}, for how to help!
9067 @item mips64el-linux
9068 little-endian 64-bit MIPS processors, specifically the Loongson series, n32
9069 ABI, and Linux-Libre kernel.
9073 GuixSD itself is currently only available on @code{i686} and @code{x86_64}.
9076 For information on porting to other architectures or kernels,
9080 * Systeminstallation:: Das ganze Betriebssystem installieren.
9081 * Systemkonfiguration:: Das Betriebssystem konfigurieren.
9082 * Dokumentation:: Wie man Nutzerhandbücher von Software liest.
9083 * Dateien zur Fehlersuche installieren:: Womit man seinen Debugger
9085 * Sicherheitsaktualisierungen:: Sicherheits-Patches schnell einspielen.
9086 * Paketmodule:: Pakete aus Sicht des Programmierers.
9087 * Paketrichtlinien:: Die Distribution wachsen lassen.
9088 * Bootstrapping:: GNU/Linux von Grund auf selbst erstellen.
9089 * Portierung:: Guix auf andere Plattformen und Kernels
9093 Building this distribution is a cooperative effort, and you are invited to
9094 join! @xref{Mitwirken}, for information about how you can help.
9096 @node Systeminstallation
9097 @section Systeminstallation
9099 @cindex installing GuixSD
9100 @cindex Guix System Distribution
9101 This section explains how to install the Guix System Distribution (GuixSD)
9102 on a machine. The Guix package manager can also be installed on top of a
9103 running GNU/Linux system, @pxref{Installation}.
9106 @quotation Anmerkung
9107 @c This paragraph is for people reading this from tty2 of the
9108 @c installation image.
9109 You are reading this documentation with an Info reader. For details on how
9110 to use it, hit the @key{RET} key (``return'' or ``enter'') on the link that
9111 follows: @pxref{Top, Info reader,, info-stnd, Stand-alone GNU Info}. Hit
9112 @kbd{l} afterwards to come back here.
9114 Alternately, run @command{info info} in another tty to keep the manual
9120 * Einschränkungen:: Was Sie erwarten dürfen.
9121 * Hardware-Überlegungen:: Unterstützte Hardware.
9122 * Installation von USB-Stick oder DVD:: Das Installationsmedium
9124 * Vor der Installation:: Netzwerkanbindung, Partitionierung etc.
9125 * Fortfahren mit der Installation:: Die Hauptsache.
9126 * GuixSD in einer VM installieren:: Ein GuixSD-Spielplatz.
9127 * Ein Abbild zur Installation erstellen:: Wie ein solches entsteht.
9130 @node Einschränkungen
9131 @subsection Einschränkungen
9133 As of version @value{VERSION}, the Guix System Distribution (GuixSD) is not
9134 production-ready. It may contain bugs and lack important features. Thus,
9135 if you are looking for a stable production system that respects your freedom
9136 as a computer user, a good solution at this point is to consider
9137 @url{http://www.gnu.org/distros/free-distros.html, one of the more
9138 established GNU/Linux distributions}. We hope you can soon switch to the
9139 GuixSD without fear, of course. In the meantime, you can also keep using
9140 your distribution and try out the package manager on top of it
9141 (@pxref{Installation}).
9143 Before you proceed with the installation, be aware of the following
9144 noteworthy limitations applicable to version @value{VERSION}:
9148 The installation process does not include a graphical user interface and
9149 requires familiarity with GNU/Linux (see the following subsections to get a
9150 feel of what that means.)
9153 Support for the Logical Volume Manager (LVM) is missing.
9156 More and more system services are provided (@pxref{Dienste}), but some may
9160 More than 7,500 packages are available, but you might occasionally find that
9161 a useful package is missing.
9164 GNOME, Xfce, LXDE, and Enlightenment are available (@pxref{Desktop-Dienste}), as well as a number of X11 window managers. However, some
9165 graphical applications may be missing, as well as KDE.
9168 You have been warned! But more than a disclaimer, this is an invitation to
9169 report issues (and success stories!), and to join us in improving it.
9170 @xref{Mitwirken}, for more info.
9173 @node Hardware-Überlegungen
9174 @subsection Hardware-Überlegungen
9176 @cindex hardware support on GuixSD
9177 GNU@tie{}GuixSD focuses on respecting the user's computing freedom. It
9178 builds around the kernel Linux-libre, which means that only hardware for
9179 which free software drivers and firmware exist is supported. Nowadays, a
9180 wide range of off-the-shelf hardware is supported on GNU/Linux-libre---from
9181 keyboards to graphics cards to scanners and Ethernet controllers.
9182 Unfortunately, there are still areas where hardware vendors deny users
9183 control over their own computing, and such hardware is not supported on
9186 @cindex WiFi, hardware support
9187 One of the main areas where free drivers or firmware are lacking is WiFi
9188 devices. WiFi devices known to work include those using Atheros chips
9189 (AR9271 and AR7010), which corresponds to the @code{ath9k} Linux-libre
9190 driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core
9191 Revision 5), which corresponds to the @code{b43-open} Linux-libre driver.
9192 Free firmware exists for both and is available out-of-the-box on GuixSD, as
9193 part of @var{%base-firmware} (@pxref{„operating-system“-Referenz,
9196 @cindex RYF, Respects Your Freedom
9197 The @uref{https://www.fsf.org/, Free Software Foundation} runs
9198 @uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (RYF), a
9199 certification program for hardware products that respect your freedom and
9200 your privacy and ensure that you have control over your device. We
9201 encourage you to check the list of RYF-certified devices.
9203 Another useful resource is the @uref{https://www.h-node.org/, H-Node} web
9204 site. It contains a catalog of hardware devices with information about
9205 their support in GNU/Linux.
9208 @node Installation von USB-Stick oder DVD
9209 @subsection Installation von USB-Stick oder DVD
9211 An ISO-9660 installation image that can be written to a USB stick or burnt
9212 to a DVD can be downloaded from
9213 @indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz},
9214 where @var{system} is one of:
9218 for a GNU/Linux system on Intel/AMD-compatible 64-bit CPUs;
9221 for a 32-bit GNU/Linux system on Intel-compatible CPUs.
9224 @c start duplication of authentication part from ``Binary Installation''
9225 Make sure to download the associated @file{.sig} file and to verify the
9226 authenticity of the image against it, along these lines:
9229 $ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig
9230 $ gpg --verify guixsd-install-@value{VERSION}.@var{system}.iso.xz.sig
9233 Falls dieser Befehl fehlschlägt, weil Sie nicht über den nötigen
9234 öffentlichen Schlüssel verfügen, können Sie ihn mit diesem Befehl
9238 $ gpg --keyserver @value{KEY-SERVER} \
9239 --recv-keys @value{OPENPGP-SIGNING-KEY-ID}
9244 und den Befehl @code{gpg --verify} erneut ausführen.
9246 This image contains the tools necessary for an installation. It is meant to
9247 be copied @emph{as is} to a large-enough USB stick or DVD.
9249 @unnumberedsubsubsec Copying to a USB Stick
9251 To copy the image to a USB stick, follow these steps:
9255 Decompress the image using the @command{xz} command:
9258 xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz
9262 Insert a USB stick of 1@tie{}GiB or more into your machine, and determine
9263 its device name. Assuming that the USB stick is known as @file{/dev/sdX},
9264 copy the image with:
9267 dd if=guixsd-install-@value{VERSION}.x86_64-linux.iso of=/dev/sdX
9271 Access to @file{/dev/sdX} usually requires root privileges.
9274 @unnumberedsubsubsec Burning on a DVD
9276 To copy the image to a DVD, follow these steps:
9280 Decompress the image using the @command{xz} command:
9283 xz -d guixsd-install-@value{VERSION}.@var{system}.iso.xz
9287 Insert a blank DVD into your machine, and determine its device name.
9288 Assuming that the DVD drive is known as @file{/dev/srX}, copy the image
9292 growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.x86_64.iso
9295 Access to @file{/dev/srX} usually requires root privileges.
9298 @unnumberedsubsubsec Booting
9300 Once this is done, you should be able to reboot the system and boot from the
9301 USB stick or DVD. The latter usually requires you to get in the BIOS or
9302 UEFI boot menu, where you can choose to boot from the USB stick.
9304 @xref{GuixSD in einer VM installieren}, if, instead, you would like to install
9305 GuixSD in a virtual machine (VM).
9308 @node Vor der Installation
9309 @subsection Vor der Installation
9311 Once you have successfully booted your computer using the installation
9312 medium, you should end up with a root prompt. Several console TTYs are
9313 configured and can be used to run commands as root. TTY2 shows this
9314 documentation, browsable using the Info reader commands (@pxref{Top,,,
9315 info-stnd, Stand-alone GNU Info}). The installation system runs the GPM
9316 mouse daemon, which allows you to select text with the left mouse button and
9317 to paste it with the middle button.
9319 @quotation Anmerkung
9320 Installation requires access to the Internet so that any missing
9321 dependencies of your system configuration can be downloaded. See the
9322 ``Networking'' section below.
9325 The installation system includes many common tools needed for this task.
9326 But it is also a full-blown GuixSD system, which means that you can install
9327 additional packages, should you need it, using @command{guix package}
9328 (@pxref{Aufruf von guix package}).
9330 @subsubsection Keyboard Layout
9332 @cindex keyboard layout
9333 The installation image uses the US qwerty keyboard layout. If you want to
9334 change it, you can use the @command{loadkeys} command. For example, the
9335 following command selects the Dvorak keyboard layout:
9341 See the files under @file{/run/current-system/profile/share/keymaps} for a
9342 list of available keyboard layouts. Run @command{man loadkeys} for more
9345 @subsubsection Networking
9347 Run the following command to see what your network interfaces are called:
9354 @dots{} or, using the GNU/Linux-specific @command{ip} command:
9360 @c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
9361 Wired interfaces have a name starting with @samp{e}; for example, the
9362 interface corresponding to the first on-board Ethernet controller is called
9363 @samp{eno1}. Wireless interfaces have a name starting with @samp{w}, like
9367 @item Wired connection
9368 To configure a wired network run the following command, substituting
9369 @var{interface} with the name of the wired interface you want to use.
9372 ifconfig @var{interface} up
9375 @item Wireless connection
9378 To configure wireless networking, you can create a configuration file for
9379 the @command{wpa_supplicant} configuration tool (its location is not
9380 important) using one of the available text editors such as @command{nano}:
9383 nano wpa_supplicant.conf
9386 As an example, the following stanza can go to this file and will work for
9387 many wireless networks, provided you give the actual SSID and passphrase for
9388 the network you are connecting to:
9392 ssid="@var{my-ssid}"
9394 psk="the network's secret passphrase"
9398 Start the wireless service and run it in the background with the following
9399 command (substitute @var{interface} with the name of the network interface
9403 wpa_supplicant -c wpa_supplicant.conf -i @var{interface} -B
9406 Run @command{man wpa_supplicant} for more information.
9410 At this point, you need to acquire an IP address. On a network where IP
9411 addresses are automatically assigned @i{via} DHCP, you can run:
9414 dhclient -v @var{interface}
9417 Try to ping a server to see if networking is up and running:
9423 Setting up network access is almost always a requirement because the image
9424 does not contain all the software and tools that may be needed.
9426 @cindex installing over SSH
9427 If you want to, you can continue the installation remotely by starting an
9431 herd start ssh-daemon
9434 Make sure to either set a password with @command{passwd}, or configure
9435 OpenSSH public key authentication before logging in.
9437 @subsubsection Disk Partitioning
9439 Unless this has already been done, the next step is to partition, and then
9440 format the target partition(s).
9442 The installation image includes several partitioning tools, including Parted
9443 (@pxref{Overview,,, parted, GNU Parted User Manual}), @command{fdisk}, and
9444 @command{cfdisk}. Run it and set up your disk with the partition layout you
9451 If your disk uses the GUID Partition Table (GPT) format and you plan to
9452 install BIOS-based GRUB (which is the default), make sure a BIOS Boot
9453 Partition is available (@pxref{BIOS installation,,, grub, GNU GRUB manual}).
9455 @cindex EFI, installation
9456 @cindex UEFI, installation
9457 @cindex ESP, EFI system partition
9458 If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System
9459 Partition} (ESP) is required. This partition should be mounted at
9460 @file{/boot/efi} and must have the @code{esp} flag set. E.g., for
9464 parted /dev/sda set 1 esp on
9467 @quotation Anmerkung
9468 @vindex grub-bootloader
9469 @vindex grub-efi-bootloader
9470 Unsure whether to use EFI- or BIOS-based GRUB? If the directory
9471 @file{/sys/firmware/efi} exists in the installation image, then you should
9472 probably perform an EFI installation, using @code{grub-efi-bootloader}.
9473 Otherwise you should use the BIOS-based GRUB, known as
9474 @code{grub-bootloader}. @xref{Bootloader-Konfiguration}, for more info on
9478 Once you are done partitioning the target hard disk drive, you have to
9479 create a file system on the relevant partition(s)@footnote{Currently GuixSD
9480 only supports ext4 and btrfs file systems. In particular, code that reads
9481 file system UUIDs and labels only works for these file system types.}. For
9482 the ESP, if you have one and assuming it is @file{/dev/sda1}, run:
9485 mkfs.fat -F32 /dev/sda1
9488 Preferably, assign file systems a label so that you can easily and reliably
9489 refer to them in @code{file-system} declarations (@pxref{Dateisysteme}).
9490 This is typically done using the @code{-L} option of @command{mkfs.ext4} and
9491 related commands. So, assuming the target root partition lives at
9492 @file{/dev/sda2}, a file system with the label @code{my-root} can be created
9496 mkfs.ext4 -L my-root /dev/sda2
9499 @cindex encrypted disk
9500 If you are instead planning to encrypt the root partition, you can use the
9501 Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
9502 @uref{https://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
9503 @code{man cryptsetup}} for more information.) Assuming you want to store
9504 the root partition on @file{/dev/sda2}, the command sequence would be along
9508 cryptsetup luksFormat /dev/sda2
9509 cryptsetup open --type luks /dev/sda2 my-partition
9510 mkfs.ext4 -L my-root /dev/mapper/my-partition
9513 Once that is done, mount the target file system under @file{/mnt} with a
9514 command like (again, assuming @code{my-root} is the label of the root file
9518 mount LABEL=my-root /mnt
9521 Also mount any other file systems you would like to use on the target system
9522 relative to this path. If you have @file{/boot} on a separate partition for
9523 example, mount it at @file{/mnt/boot} now so it is found by @code{guix
9524 system init} afterwards.
9526 Finally, if you plan to use one or more swap partitions (@pxref{Memory
9527 Concepts, swap space,, libc, The GNU C Library Reference Manual}), make sure
9528 to initialize them with @command{mkswap}. Assuming you have one swap
9529 partition on @file{/dev/sda3}, you would run:
9536 Alternatively, you may use a swap file. For example, assuming that in the
9537 new system you want to use the file @file{/swapfile} as a swap file, you
9538 would run@footnote{This example will work for many types of file systems
9539 (e.g., ext4). However, for copy-on-write file systems (e.g., btrfs), the
9540 required steps may be different. For details, see the manual pages for
9541 @command{mkswap} and @command{swapon}.}:
9544 # This is 10 GiB of swap space. Adjust "count" to change the size.
9545 dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
9546 # For security, make the file readable and writable only by root.
9547 chmod 600 /mnt/swapfile
9548 mkswap /mnt/swapfile
9549 swapon /mnt/swapfile
9552 Note that if you have encrypted the root partition and created a swap file
9553 in its file system as described above, then the encryption also protects the
9554 swap file, just like any other file in that file system.
9556 @node Fortfahren mit der Installation
9557 @subsection Fortfahren mit der Installation
9559 With the target partitions ready and the target root mounted on @file{/mnt},
9560 we're ready to go. First, run:
9563 herd start cow-store /mnt
9566 This makes @file{/gnu/store} copy-on-write, such that packages added to it
9567 during the installation phase are written to the target disk on @file{/mnt}
9568 rather than kept in memory. This is necessary because the first phase of
9569 the @command{guix system init} command (see below) entails downloads or
9570 builds to @file{/gnu/store} which, initially, is an in-memory file system.
9572 Next, you have to edit a file and provide the declaration of the operating
9573 system to be installed. To that end, the installation system comes with
9574 three text editors. We recommend GNU nano (@pxref{Top,,, nano, GNU nano
9575 Manual}), which supports syntax highlighting and parentheses matching; other
9576 editors include GNU Zile (an Emacs clone), and nvi (a clone of the original
9577 BSD @command{vi} editor). We strongly recommend storing that file on the
9578 target root file system, say, as @file{/mnt/etc/config.scm}. Failing to do
9579 that, you will have lost your configuration file once you have rebooted into
9580 the newly-installed system.
9582 @xref{Das Konfigurationssystem nutzen}, for an overview of the configuration
9583 file. The example configurations discussed in that section are available
9584 under @file{/etc/configuration} in the installation image. Thus, to get
9585 started with a system configuration providing a graphical display server (a
9586 ``desktop'' system), you can run something along these lines:
9590 # cp /etc/configuration/desktop.scm /mnt/etc/config.scm
9591 # nano /mnt/etc/config.scm
9594 You should pay attention to what your configuration file contains, and in
9599 Make sure the @code{bootloader-configuration} form refers to the target you
9600 want to install GRUB on. It should mention @code{grub-bootloader} if you
9601 are installing GRUB in the legacy way, or @code{grub-efi-bootloader} for
9602 newer UEFI systems. For legacy systems, the @code{target} field names a
9603 device, like @code{/dev/sda}; for UEFI systems it names a path to a mounted
9604 EFI partition, like @code{/boot/efi}, and do make sure the path is actually
9608 Be sure that your file system labels match the value of their respective
9609 @code{device} fields in your @code{file-system} configuration, assuming your
9610 @code{file-system} configuration uses the @code{file-system-label} procedure
9611 in its @code{device} field.
9614 If there are encrypted or RAID partitions, make sure to add a
9615 @code{mapped-devices} field to describe them (@pxref{Abgebildete Geräte}).
9618 Once you are done preparing the configuration file, the new system must be
9619 initialized (remember that the target root file system is mounted under
9623 guix system init /mnt/etc/config.scm /mnt
9627 This copies all the necessary files and installs GRUB on @file{/dev/sdX},
9628 unless you pass the @option{--no-bootloader} option. For more information,
9629 @pxref{Aufruf von guix system}. This command may trigger downloads or builds
9630 of missing packages, which can take some time.
9632 Once that command has completed---and hopefully succeeded!---you can run
9633 @command{reboot} and boot into the new system. The @code{root} password in
9634 the new system is initially empty; other users' passwords need to be
9635 initialized by running the @command{passwd} command as @code{root}, unless
9636 your configuration specifies otherwise (@pxref{user-account-password, user
9637 account passwords}).
9639 @cindex upgrading GuixSD
9640 From then on, you can update GuixSD whenever you want by running
9641 @command{guix pull} as @code{root} (@pxref{Aufruf von guix pull}), and then
9642 running @command{guix system reconfigure} to build a new system generation
9643 with the latest packages and services (@pxref{Aufruf von guix system}). We
9644 recommend doing that regularly so that your system includes the latest
9645 security updates (@pxref{Sicherheitsaktualisierungen}).
9647 Join us on @code{#guix} on the Freenode IRC network or on
9648 @file{guix-devel@@gnu.org} to share your experience---good or not so good.
9650 @node GuixSD in einer VM installieren
9651 @subsection Installing GuixSD in a Virtual Machine
9653 @cindex virtual machine, GuixSD installation
9654 @cindex virtual private server (VPS)
9655 @cindex VPS (virtual private server)
9656 If you'd like to install GuixSD in a virtual machine (VM) or on a virtual
9657 private server (VPS) rather than on your beloved machine, this section is
9660 To boot a @uref{http://qemu.org/,QEMU} VM for installing GuixSD in a disk
9661 image, follow these steps:
9665 First, retrieve and decompress the GuixSD installation image as described
9666 previously (@pxref{Installation von USB-Stick oder DVD}).
9669 Create a disk image that will hold the installed system. To make a
9670 qcow2-formatted disk image, use the @command{qemu-img} command:
9673 qemu-img create -f qcow2 guixsd.img 50G
9676 The resulting file will be much smaller than 50 GB (typically less than 1
9677 MB), but it will grow as the virtualized storage device is filled up.
9680 Boot the USB installation image in an VM:
9683 qemu-system-x86_64 -m 1024 -smp 1 \
9684 -net user -net nic,model=virtio -boot menu=on \
9685 -drive file=guixsd-install-@value{VERSION}.@var{system}.iso \
9686 -drive file=guixsd.img
9689 The ordering of the drives matters.
9691 In the VM console, quickly press the @kbd{F12} key to enter the boot menu.
9692 Then press the @kbd{2} key and the @kbd{RET} key to validate your selection.
9695 You're now root in the VM, proceed with the installation process.
9696 @xref{Vor der Installation}, and follow the instructions.
9699 Once installation is complete, you can boot the system that's on your
9700 @file{guixsd.img} image. @xref{GuixSD in einer VM starten}, for how to do that.
9702 @node Ein Abbild zur Installation erstellen
9703 @subsection Ein Abbild zur Installation erstellen
9705 @cindex installation image
9706 The installation image described above was built using the @command{guix
9707 system} command, specifically:
9710 guix system disk-image gnu/system/install.scm
9713 Have a look at @file{gnu/system/install.scm} in the source tree, and see
9714 also @ref{Aufruf von guix system} for more information about the installation
9717 @subsection Building the Installation Image for ARM Boards
9719 Many ARM boards require a specific variant of the
9720 @uref{http://www.denx.de/wiki/U-Boot/, U-Boot} bootloader.
9722 If you build a disk image and the bootloader is not available otherwise (on
9723 another boot drive etc), it's advisable to build an image that includes the
9724 bootloader, specifically:
9727 guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'
9730 @code{A20-OLinuXino-Lime2} is the name of the board. If you specify an
9731 invalid board, a list of possible boards will be printed.
9733 @node Systemkonfiguration
9734 @section Systemkonfiguration
9736 @cindex system configuration
9737 The Guix System Distribution supports a consistent whole-system
9738 configuration mechanism. By that we mean that all aspects of the global
9739 system configuration---such as the available system services, timezone and
9740 locale settings, user accounts---are declared in a single place. Such a
9741 @dfn{system configuration} can be @dfn{instantiated}---i.e., effected.
9743 @c Yes, we're talking of Puppet, Chef, & co. here. ↑
9744 One of the advantages of putting all the system configuration under the
9745 control of Guix is that it supports transactional system upgrades, and makes
9746 it possible to roll back to a previous system instantiation, should
9747 something go wrong with the new one (@pxref{Funktionalitäten}). Another advantage
9748 is that it makes it easy to replicate the exact same configuration across
9749 different machines, or at different points in time, without having to resort
9750 to additional administration tools layered on top of the own tools of the
9753 This section describes this mechanism. First we focus on the system
9754 administrator's viewpoint---explaining how the system is configured and
9755 instantiated. Then we show how this mechanism can be extended, for instance
9756 to support new system services.
9759 * Das Konfigurationssystem nutzen:: Ihr GNU-System anpassen.
9760 * „operating-system“-Referenz:: Details der
9761 Betriebssystem-Deklarationen.
9762 * Dateisysteme:: Die Dateisystemeinbindungen konfigurieren.
9763 * Abgebildete Geräte:: Näheres zu blockorientierten Speichermedien.
9764 * Benutzerkonten:: Benutzerkonten festlegen.
9765 * Locales:: Sprache und kulturelle Konventionen.
9766 * Dienste:: Systemdienste festlegen.
9767 * Setuid-Programme:: Mit Administratorrechten startende Programme.
9768 * X.509-Zertifikate:: HTTPS-Server authentifizieren.
9769 * Name Service Switch:: Den Name Service Switch von libc konfigurieren.
9770 * Initiale RAM-Disk:: Linux-libre hochfahren.
9771 * Bootloader-Konfiguration:: Den Bootloader konfigurieren.
9772 * Aufruf von guix system:: Instanzierung einer Systemkonfiguration.
9773 * GuixSD in einer VM starten:: Wie man GuixSD in einer virtuellen Maschine
9775 * Dienste definieren:: Neue Dienstdefinitionen hinzufügen.
9778 @node Das Konfigurationssystem nutzen
9779 @subsection Das Konfigurationssystem nutzen
9781 The operating system is configured by providing an @code{operating-system}
9782 declaration in a file that can then be passed to the @command{guix system}
9783 command (@pxref{Aufruf von guix system}). A simple setup, with the default
9784 system services, the default Linux-Libre kernel, initial RAM disk, and boot
9785 loader looks like this:
9787 @findex operating-system
9789 @include os-config-bare-bones.texi
9792 This example should be self-describing. Some of the fields defined above,
9793 such as @code{host-name} and @code{bootloader}, are mandatory. Others, such
9794 as @code{packages} and @code{services}, can be omitted, in which case they
9795 get a default value.
9797 Below we discuss the effect of some of the most important fields
9798 (@pxref{„operating-system“-Referenz}, for details about all the available
9799 fields), and how to @dfn{instantiate} the operating system using
9800 @command{guix system}.
9802 @unnumberedsubsubsec Bootloader
9804 @cindex legacy boot, on Intel machines
9805 @cindex BIOS boot, on Intel machines
9808 The @code{bootloader} field describes the method that will be used to boot
9809 your system. Machines based on Intel processors can boot in ``legacy'' BIOS
9810 mode, as in the example above. However, more recent machines rely instead
9811 on the @dfn{Unified Extensible Firmware Interface} (UEFI) to boot. In that
9812 case, the @code{bootloader} field should contain something along these
9816 (bootloader-configuration
9817 (bootloader grub-efi-bootloader)
9818 (target "/boot/efi"))
9821 @xref{Bootloader-Konfiguration}, for more information on the available
9822 configuration options.
9824 @unnumberedsubsubsec Globally-Visible Packages
9826 @vindex %base-packages
9827 The @code{packages} field lists packages that will be globally visible on
9828 the system, for all user accounts---i.e., in every user's @code{PATH}
9829 environment variable---in addition to the per-user profiles (@pxref{Aufruf von guix package}). The @var{%base-packages} variable provides all the tools
9830 one would expect for basic user and administrator tasks---including the GNU
9831 Core Utilities, the GNU Networking Utilities, the GNU Zile lightweight text
9832 editor, @command{find}, @command{grep}, etc. The example above adds
9833 GNU@tie{}Screen to those, taken from the @code{(gnu packages screen)} module
9834 (@pxref{Paketmodule}). The @code{(list package output)} syntax can be
9835 used to add a specific output of a package:
9838 (use-modules (gnu packages))
9839 (use-modules (gnu packages dns))
9843 (packages (cons (list bind "utils")
9847 @findex specification->package
9848 Referring to packages by variable name, like @code{bind} above, has the
9849 advantage of being unambiguous; it also allows typos and such to be
9850 diagnosed right away as ``unbound variables''. The downside is that one
9851 needs to know which module defines which package, and to augment the
9852 @code{use-package-modules} line accordingly. To avoid that, one can use the
9853 @code{specification->package} procedure of the @code{(gnu packages)} module,
9854 which returns the best package for a given name or name and version:
9857 (use-modules (gnu packages))
9861 (packages (append (map specification->package
9862 '("tcpdump" "htop" "gnupg@@2.0"))
9866 @unnumberedsubsubsec System Services
9869 @vindex %base-services
9870 The @code{services} field lists @dfn{system services} to be made available
9871 when the system starts (@pxref{Dienste}). The @code{operating-system}
9872 declaration above specifies that, in addition to the basic services, we want
9873 the @command{lshd} secure shell daemon listening on port 2222
9874 (@pxref{Netzwerkdienste, @code{lsh-service}}). Under the hood,
9875 @code{lsh-service} arranges so that @code{lshd} is started with the right
9876 command-line options, possibly with supporting configuration files generated
9877 as needed (@pxref{Dienste definieren}).
9879 @cindex customization, of services
9880 @findex modify-services
9881 Occasionally, instead of using the base services as is, you will want to
9882 customize them. To do this, use @code{modify-services} (@pxref{Service-Referenz, @code{modify-services}}) to modify the list.
9884 For example, suppose you want to modify @code{guix-daemon} and Mingetty (the
9885 console log-in) in the @var{%base-services} list (@pxref{Basisdienste,
9886 @code{%base-services}}). To do that, you can write the following in your
9887 operating system declaration:
9890 (define %my-services
9891 ;; My very own list of services.
9892 (modify-services %base-services
9893 (guix-service-type config =>
9896 (use-substitutes? #f)
9897 (extra-options '("--gc-keep-derivations"))))
9898 (mingetty-service-type config =>
9899 (mingetty-configuration
9900 (inherit config)))))
9904 (services %my-services))
9907 This changes the configuration---i.e., the service parameters---of the
9908 @code{guix-service-type} instance, and that of all the
9909 @code{mingetty-service-type} instances in the @var{%base-services} list.
9910 Observe how this is accomplished: first, we arrange for the original
9911 configuration to be bound to the identifier @code{config} in the @var{body},
9912 and then we write the @var{body} so that it evaluates to the desired
9913 configuration. In particular, notice how we use @code{inherit} to create a
9914 new configuration which has the same values as the old configuration, but
9915 with a few modifications.
9917 @cindex encrypted disk
9918 The configuration for a typical ``desktop'' usage, with an encrypted root
9919 partition, the X11 display server, GNOME and Xfce (users can choose which of
9920 these desktop environments to use at the log-in screen by pressing
9921 @kbd{F1}), network management, power management, and more, would look like
9925 @include os-config-desktop.texi
9928 A graphical system with a choice of lightweight window managers instead of
9929 full-blown desktop environments would look like this:
9932 @include os-config-lightweight-desktop.texi
9935 This example refers to the @file{/boot/efi} file system by its UUID,
9936 @code{1234-ABCD}. Replace this UUID with the right UUID on your system, as
9937 returned by the @command{blkid} command.
9939 @xref{Desktop-Dienste}, for the exact list of services provided by
9940 @var{%desktop-services}. @xref{X.509-Zertifikate}, for background
9941 information about the @code{nss-certs} package that is used here.
9943 Again, @var{%desktop-services} is just a list of service objects. If you
9944 want to remove services from there, you can do so using the procedures for
9945 list filtering (@pxref{SRFI-1 Filtering and Partitioning,,, guile, GNU Guile
9946 Reference Manual}). For instance, the following expression returns a list
9947 that contains all the services in @var{%desktop-services} minus the Avahi
9951 (remove (lambda (service)
9952 (eq? (service-kind service) avahi-service-type))
9956 @unnumberedsubsubsec Instantiating the System
9958 Assuming the @code{operating-system} declaration is stored in the
9959 @file{my-system-config.scm} file, the @command{guix system reconfigure
9960 my-system-config.scm} command instantiates that configuration, and makes it
9961 the default GRUB boot entry (@pxref{Aufruf von guix system}).
9963 The normal way to change the system configuration is by updating this file
9964 and re-running @command{guix system reconfigure}. One should never have to
9965 touch files in @file{/etc} or to run commands that modify the system state
9966 such as @command{useradd} or @command{grub-install}. In fact, you must
9967 avoid that since that would not only void your warranty but also prevent you
9968 from rolling back to previous versions of your system, should you ever need
9971 @cindex roll-back, of the operating system
9972 Speaking of roll-back, each time you run @command{guix system reconfigure},
9973 a new @dfn{generation} of the system is created---without modifying or
9974 deleting previous generations. Old system generations get an entry in the
9975 bootloader boot menu, allowing you to boot them in case something went wrong
9976 with the latest generation. Reassuring, no? The @command{guix system
9977 list-generations} command lists the system generations available on disk.
9978 It is also possible to roll back the system via the commands @command{guix
9979 system roll-back} and @command{guix system switch-generation}.
9981 Although the @command{guix system reconfigure} command will not modify
9982 previous generations, you must take care when the current generation is not
9983 the latest (e.g., after invoking @command{guix system roll-back}), since the
9984 operation might overwrite a later generation (@pxref{Aufruf von guix system}).
9986 @unnumberedsubsubsec The Programming Interface
9988 At the Scheme level, the bulk of an @code{operating-system} declaration is
9989 instantiated with the following monadic procedure (@pxref{Die Store-Monade}):
9991 @deffn {Monadic Procedure} operating-system-derivation os
9992 Return a derivation that builds @var{os}, an @code{operating-system} object
9993 (@pxref{Ableitungen}).
9995 The output of the derivation is a single directory that refers to all the
9996 packages, configuration files, and other supporting files needed to
9997 instantiate @var{os}.
10000 This procedure is provided by the @code{(gnu system)} module. Along with
10001 @code{(gnu services)} (@pxref{Dienste}), this module contains the guts of
10002 GuixSD. Make sure to visit it!
10005 @node „operating-system“-Referenz
10006 @subsection @code{operating-system} Reference
10008 This section summarizes all the options available in @code{operating-system}
10009 declarations (@pxref{Das Konfigurationssystem nutzen}).
10011 @deftp {Data Type} operating-system
10012 This is the data type representing an operating system configuration. By
10013 that, we mean all the global system configuration, not per-user
10014 configuration (@pxref{Das Konfigurationssystem nutzen}).
10017 @item @code{kernel} (default: @var{linux-libre})
10018 The package object of the operating system kernel to use@footnote{Currently
10019 only the Linux-libre kernel is supported. In the future, it will be
10020 possible to use the GNU@tie{}Hurd.}.
10022 @item @code{kernel-arguments} (default: @code{'()})
10023 List of strings or gexps representing additional arguments to pass on the
10024 command-line of the kernel---e.g., @code{("console=ttyS0")}.
10026 @item @code{bootloader}
10027 The system bootloader configuration object. @xref{Bootloader-Konfiguration}.
10029 @item @code{initrd-modules} (default: @code{%base-initrd-modules})
10031 @cindex initial RAM disk
10032 The list of Linux kernel modules that need to be available in the initial
10033 RAM disk. @xref{Initiale RAM-Disk}.
10035 @item @code{initrd} (default: @code{base-initrd})
10036 A procedure that returns an initial RAM disk for the Linux kernel. This
10037 field is provided to support low-level customization and should rarely be
10038 needed for casual use. @xref{Initiale RAM-Disk}.
10040 @item @code{firmware} (default: @var{%base-firmware})
10042 List of firmware packages loadable by the operating system kernel.
10044 The default includes firmware needed for Atheros- and Broadcom-based WiFi
10045 devices (Linux-libre modules @code{ath9k} and @code{b43-open},
10046 respectively). @xref{Hardware-Überlegungen}, for more info on supported
10049 @item @code{host-name}
10052 @item @code{hosts-file}
10054 A file-like object (@pxref{G-Ausdrücke, file-like objects}) for use as
10055 @file{/etc/hosts} (@pxref{Host Names,,, libc, The GNU C Library Reference
10056 Manual}). The default is a file with entries for @code{localhost} and
10059 @item @code{mapped-devices} (default: @code{'()})
10060 A list of mapped devices. @xref{Abgebildete Geräte}.
10062 @item @code{file-systems}
10063 A list of file systems. @xref{Dateisysteme}.
10065 @item @code{swap-devices} (default: @code{'()})
10066 @cindex swap devices
10067 A list of strings identifying devices or files to be used for ``swap space''
10068 (@pxref{Memory Concepts,,, libc, The GNU C Library Reference Manual}). For
10069 example, @code{'("/dev/sda3")} or @code{'("/swapfile")}. It is possible to
10070 specify a swap file in a file system on a mapped device, provided that the
10071 necessary device mapping and file system are also specified. @xref{Abgebildete Geräte} and @ref{Dateisysteme}.
10073 @item @code{users} (default: @code{%base-user-accounts})
10074 @itemx @code{groups} (default: @var{%base-groups})
10075 List of user accounts and groups. @xref{Benutzerkonten}.
10077 If the @code{users} list lacks a user account with UID@tie{}0, a ``root''
10078 account with UID@tie{}0 is automatically added.
10080 @item @code{skeletons} (default: @code{(default-skeletons)})
10081 A list target file name/file-like object tuples (@pxref{G-Ausdrücke,
10082 file-like objects}). These are the skeleton files that will be added to the
10083 home directory of newly-created user accounts.
10085 For instance, a valid value may look like this:
10088 `((".bashrc" ,(plain-file "bashrc" "echo Hello\n"))
10089 (".guile" ,(plain-file "guile"
10090 "(use-modules (ice-9 readline))
10091 (activate-readline)")))
10094 @item @code{issue} (default: @var{%default-issue})
10095 A string denoting the contents of the @file{/etc/issue} file, which is
10096 displayed when users log in on a text console.
10098 @item @code{packages} (default: @var{%base-packages})
10099 The set of packages installed in the global profile, which is accessible at
10100 @file{/run/current-system/profile}.
10102 The default set includes core utilities and it is good practice to install
10103 non-core utilities in user profiles (@pxref{Aufruf von guix package}).
10105 @item @code{timezone}
10106 A timezone identifying string---e.g., @code{"Europe/Paris"}.
10108 You can run the @command{tzselect} command to find out which timezone string
10109 corresponds to your region. Choosing an invalid timezone name causes
10110 @command{guix system} to fail.
10112 @item @code{locale} (default: @code{"en_US.utf8"})
10113 The name of the default locale (@pxref{Locale Names,,, libc, The GNU C
10114 Library Reference Manual}). @xref{Locales}, for more information.
10116 @item @code{locale-definitions} (default: @var{%default-locale-definitions})
10117 The list of locale definitions to be compiled and that may be used at run
10118 time. @xref{Locales}.
10120 @item @code{locale-libcs} (default: @code{(list @var{glibc})})
10121 The list of GNU@tie{}libc packages whose locale data and tools are used to
10122 build the locale definitions. @xref{Locales}, for compatibility
10123 considerations that justify this option.
10125 @item @code{name-service-switch} (default: @var{%default-nss})
10126 Configuration of the libc name service switch (NSS)---a
10127 @code{<name-service-switch>} object. @xref{Name Service Switch}, for
10130 @item @code{services} (default: @var{%base-services})
10131 A list of service objects denoting system services. @xref{Dienste}.
10133 @item @code{pam-services} (default: @code{(base-pam-services)})
10135 @cindex pluggable authentication modules
10136 @c FIXME: Add xref to PAM services section.
10137 Linux @dfn{pluggable authentication module} (PAM) services.
10139 @item @code{setuid-programs} (default: @var{%setuid-programs})
10140 List of string-valued G-expressions denoting setuid programs. @xref{Setuid-Programme}.
10142 @item @code{sudoers-file} (default: @var{%sudoers-specification})
10143 @cindex sudoers file
10144 The contents of the @file{/etc/sudoers} file as a file-like object
10145 (@pxref{G-Ausdrücke, @code{local-file} and @code{plain-file}}).
10147 This file specifies which users can use the @command{sudo} command, what
10148 they are allowed to do, and what privileges they may gain. The default is
10149 that only @code{root} and members of the @code{wheel} group may use
10156 @subsection Dateisysteme
10158 The list of file systems to be mounted is specified in the
10159 @code{file-systems} field of the operating system declaration (@pxref{Das Konfigurationssystem nutzen}). Each file system is declared using the
10160 @code{file-system} form, like this:
10164 (mount-point "/home")
10165 (device "/dev/sda3")
10169 As usual, some of the fields are mandatory---those shown in the example
10170 above---while others can be omitted. These are described below.
10172 @deftp {Data Type} file-system
10173 Objects of this type represent file systems to be mounted. They contain the
10178 This is a string specifying the type of the file system---e.g.,
10181 @item @code{mount-point}
10182 This designates the place where the file system is to be mounted.
10184 @item @code{device}
10185 This names the ``source'' of the file system. It can be one of three
10186 things: a file system label, a file system UUID, or the name of a
10187 @file{/dev} node. Labels and UUIDs offer a way to refer to file systems
10188 without having to hard-code their actual device name@footnote{Note that,
10189 while it is tempting to use @file{/dev/disk/by-uuid} and similar device
10190 names to achieve the same result, this is not recommended: These special
10191 device nodes are created by the udev daemon and may be unavailable at the
10192 time the device is mounted.}.
10194 @findex file-system-label
10195 File system labels are created using the @code{file-system-label} procedure,
10196 UUIDs are created using @code{uuid}, and @file{/dev} node are plain
10197 strings. Here's an example of a file system referred to by its label, as
10198 shown by the @command{e2label} command:
10202 (mount-point "/home")
10204 (device (file-system-label "my-home")))
10208 UUIDs are converted from their string representation (as shown by the
10209 @command{tune2fs -l} command) using the @code{uuid} form@footnote{The
10210 @code{uuid} form expects 16-byte UUIDs as defined in
10211 @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122}. This is the form
10212 of UUID used by the ext2 family of file systems and others, but it is
10213 different from ``UUIDs'' found in FAT file systems, for instance.}, like
10218 (mount-point "/home")
10220 (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))
10223 When the source of a file system is a mapped device (@pxref{Abgebildete Geräte}), its @code{device} field @emph{must} refer to the mapped device
10224 name---e.g., @file{"/dev/mapper/root-partition"}. This is required so that
10225 the system knows that mounting the file system depends on having the
10226 corresponding device mapping established.
10228 @item @code{flags} (default: @code{'()})
10229 This is a list of symbols denoting mount flags. Recognized flags include
10230 @code{read-only}, @code{bind-mount}, @code{no-dev} (disallow access to
10231 special files), @code{no-suid} (ignore setuid and setgid bits), and
10232 @code{no-exec} (disallow program execution.)
10234 @item @code{options} (default: @code{#f})
10235 This is either @code{#f}, or a string denoting mount options.
10237 @item @code{mount?} (default: @code{#t})
10238 This value indicates whether to automatically mount the file system when the
10239 system is brought up. When set to @code{#f}, the file system gets an entry
10240 in @file{/etc/fstab} (read by the @command{mount} command) but is not
10241 automatically mounted.
10243 @item @code{needed-for-boot?} (default: @code{#f})
10244 This Boolean value indicates whether the file system is needed when
10245 booting. If that is true, then the file system is mounted when the initial
10246 RAM disk (initrd) is loaded. This is always the case, for instance, for the
10249 @item @code{check?} (default: @code{#t})
10250 This Boolean indicates whether the file system needs to be checked for
10251 errors before being mounted.
10253 @item @code{create-mount-point?} (default: @code{#f})
10254 When true, the mount point is created if it does not exist yet.
10256 @item @code{dependencies} (default: @code{'()})
10257 This is a list of @code{<file-system>} or @code{<mapped-device>} objects
10258 representing file systems that must be mounted or mapped devices that must
10259 be opened before (and unmounted or closed after) this one.
10261 As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is a
10262 dependency of @file{/sys/fs/cgroup/cpu} and @file{/sys/fs/cgroup/memory}.
10264 Another example is a file system that depends on a mapped device, for
10265 example for an encrypted partition (@pxref{Abgebildete Geräte}).
10269 The @code{(gnu system file-systems)} exports the following useful variables.
10271 @defvr {Scheme Variable} %base-file-systems
10272 These are essential file systems that are required on normal systems, such
10273 as @var{%pseudo-terminal-file-system} and @var{%immutable-store} (see
10274 below.) Operating system declarations should always contain at least these.
10277 @defvr {Scheme Variable} %pseudo-terminal-file-system
10278 This is the file system to be mounted as @file{/dev/pts}. It supports
10279 @dfn{pseudo-terminals} created @i{via} @code{openpty} and similar functions
10280 (@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference Manual}).
10281 Pseudo-terminals are used by terminal emulators such as @command{xterm}.
10284 @defvr {Scheme Variable} %shared-memory-file-system
10285 This file system is mounted as @file{/dev/shm} and is used to support memory
10286 sharing across processes (@pxref{Memory-mapped I/O, @code{shm_open},, libc,
10287 The GNU C Library Reference Manual}).
10290 @defvr {Scheme Variable} %immutable-store
10291 This file system performs a read-only ``bind mount'' of @file{/gnu/store},
10292 making it read-only for all the users including @code{root}. This prevents
10293 against accidental modification by software running as @code{root} or by
10294 system administrators.
10296 The daemon itself is still able to write to the store: it remounts it
10297 read-write in its own ``name space.''
10300 @defvr {Scheme Variable} %binary-format-file-system
10301 The @code{binfmt_misc} file system, which allows handling of arbitrary
10302 executable file types to be delegated to user space. This requires the
10303 @code{binfmt.ko} kernel module to be loaded.
10306 @defvr {Scheme Variable} %fuse-control-file-system
10307 The @code{fusectl} file system, which allows unprivileged users to mount and
10308 unmount user-space FUSE file systems. This requires the @code{fuse.ko}
10309 kernel module to be loaded.
10312 @node Abgebildete Geräte
10313 @subsection Abgebildete Geräte
10315 @cindex device mapping
10316 @cindex mapped devices
10317 The Linux kernel has a notion of @dfn{device mapping}: a block device, such
10318 as a hard disk partition, can be @dfn{mapped} into another device, usually
10319 in @code{/dev/mapper/}, with additional processing over the data that flows
10320 through it@footnote{Note that the GNU@tie{}Hurd makes no difference between
10321 the concept of a ``mapped device'' and that of a file system: both boil down
10322 to @emph{translating} input/output operations made on a file to operations
10323 on its backing store. Thus, the Hurd implements mapped devices, like file
10324 systems, using the generic @dfn{translator} mechanism (@pxref{Translators,,,
10325 hurd, The GNU Hurd Reference Manual}).}. A typical example is encryption
10326 device mapping: all writes to the mapped device are encrypted, and all reads
10327 are deciphered, transparently. Guix extends this notion by considering any
10328 device or set of devices that are @dfn{transformed} in some way to create a
10329 new device; for instance, RAID devices are obtained by @dfn{assembling}
10330 several other devices, such as hard disks or partitions, into a new one that
10331 behaves as one partition. Other examples, not yet implemented, are LVM
10334 Mapped devices are declared using the @code{mapped-device} form, defined as
10335 follows; for examples, see below.
10337 @deftp {Data Type} mapped-device
10338 Objects of this type represent device mappings that will be made when the
10343 This is either a string specifying the name of the block device to be
10344 mapped, such as @code{"/dev/sda3"}, or a list of such strings when several
10345 devices need to be assembled for creating a new one.
10348 This string specifies the name of the resulting mapped device. For kernel
10349 mappers such as encrypted devices of type @code{luks-device-mapping},
10350 specifying @code{"my-partition"} leads to the creation of the
10351 @code{"/dev/mapper/my-partition"} device. For RAID devices of type
10352 @code{raid-device-mapping}, the full device name such as @code{"/dev/md0"}
10356 This must be a @code{mapped-device-kind} object, which specifies how
10357 @var{source} is mapped to @var{target}.
10361 @defvr {Scheme Variable} luks-device-mapping
10362 This defines LUKS block device encryption using the @command{cryptsetup}
10363 command from the package with the same name. It relies on the
10364 @code{dm-crypt} Linux kernel module.
10367 @defvr {Scheme Variable} raid-device-mapping
10368 This defines a RAID device, which is assembled using the @code{mdadm}
10369 command from the package with the same name. It requires a Linux kernel
10370 module for the appropriate RAID level to be loaded, such as @code{raid456}
10371 for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
10374 @cindex disk encryption
10376 The following example specifies a mapping from @file{/dev/sda3} to
10377 @file{/dev/mapper/home} using LUKS---the
10378 @url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, a
10379 standard mechanism for disk encryption. The @file{/dev/mapper/home} device
10380 can then be used as the @code{device} of a @code{file-system} declaration
10381 (@pxref{Dateisysteme}).
10385 (source "/dev/sda3")
10387 (type luks-device-mapping))
10390 Alternatively, to become independent of device numbering, one may obtain the
10391 LUKS UUID (@dfn{unique identifier}) of the source device by a command like:
10394 cryptsetup luksUUID /dev/sda3
10397 and use it as follows:
10401 (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
10403 (type luks-device-mapping))
10406 @cindex swap encryption
10407 It is also desirable to encrypt swap space, since swap space may contain
10408 sensitive data. One way to accomplish that is to use a swap file in a file
10409 system on a device mapped via LUKS encryption. In this way, the swap file
10410 is encrypted because the entire device is encrypted. @xref{Vor der Installation,,Disk Partitioning}, for an example.
10412 A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
10413 may be declared as follows:
10417 (source (list "/dev/sda1" "/dev/sdb1"))
10418 (target "/dev/md0")
10419 (type raid-device-mapping))
10422 The @file{/dev/md0} device can then be used as the @code{device} of a
10423 @code{file-system} declaration (@pxref{Dateisysteme}). Note that the RAID
10424 level need not be given; it is chosen during the initial creation and
10425 formatting of the RAID device and is determined automatically later.
10428 @node Benutzerkonten
10429 @subsection Benutzerkonten
10433 @cindex user accounts
10434 User accounts and groups are entirely managed through the
10435 @code{operating-system} declaration. They are specified with the
10436 @code{user-account} and @code{user-group} forms:
10442 (supplementary-groups '("wheel" ;allow use of sudo, etc.
10443 "audio" ;sound card
10444 "video" ;video devices such as webcams
10445 "cdrom")) ;the good ol' CD-ROM
10446 (comment "Bob's sister")
10447 (home-directory "/home/alice"))
10450 When booting or upon completion of @command{guix system reconfigure}, the
10451 system ensures that only the user accounts and groups specified in the
10452 @code{operating-system} declaration exist, and with the specified
10453 properties. Thus, account or group creations or modifications made by
10454 directly invoking commands such as @command{useradd} are lost upon
10455 reconfiguration or reboot. This ensures that the system remains exactly as
10458 @deftp {Data Type} user-account
10459 Objects of this type represent user accounts. The following members may be
10464 The name of the user account.
10468 This is the name (a string) or identifier (a number) of the user group this
10469 account belongs to.
10471 @item @code{supplementary-groups} (default: @code{'()})
10472 Optionally, this can be defined as a list of group names that this account
10475 @item @code{uid} (default: @code{#f})
10476 This is the user ID for this account (a number), or @code{#f}. In the
10477 latter case, a number is automatically chosen by the system when the account
10480 @item @code{comment} (default: @code{""})
10481 A comment about the account, such as the account owner's full name.
10483 @item @code{home-directory}
10484 This is the name of the home directory for the account.
10486 @item @code{create-home-directory?} (default: @code{#t})
10487 Indicates whether the home directory of this account should be created if it
10488 does not exist yet.
10490 @item @code{shell} (default: Bash)
10491 This is a G-expression denoting the file name of a program to be used as the
10492 shell (@pxref{G-Ausdrücke}).
10494 @item @code{system?} (default: @code{#f})
10495 This Boolean value indicates whether the account is a ``system'' account.
10496 System accounts are sometimes treated specially; for instance, graphical
10497 login managers do not list them.
10499 @anchor{user-account-password}
10500 @item @code{password} (default: @code{#f})
10501 You would normally leave this field to @code{#f}, initialize user passwords
10502 as @code{root} with the @command{passwd} command, and then let users change
10503 it with @command{passwd}. Passwords set with @command{passwd} are of course
10504 preserved across reboot and reconfiguration.
10506 If you @emph{do} want to have a preset password for an account, then this
10507 field must contain the encrypted password, as a string. @xref{crypt,,,
10508 libc, The GNU C Library Reference Manual}, for more information on password
10509 encryption, and @ref{Encryption,,, guile, GNU Guile Reference Manual}, for
10510 information on Guile's @code{crypt} procedure.
10516 User group declarations are even simpler:
10519 (user-group (name "students"))
10522 @deftp {Data Type} user-group
10523 This type is for, well, user groups. There are just a few fields:
10527 The name of the group.
10529 @item @code{id} (default: @code{#f})
10530 The group identifier (a number). If @code{#f}, a new number is
10531 automatically allocated when the group is created.
10533 @item @code{system?} (default: @code{#f})
10534 This Boolean value indicates whether the group is a ``system'' group.
10535 System groups have low numerical IDs.
10537 @item @code{password} (default: @code{#f})
10538 What, user groups can have a password? Well, apparently yes. Unless
10539 @code{#f}, this field specifies the password of the group.
10544 For convenience, a variable lists all the basic user groups one may expect:
10546 @defvr {Scheme Variable} %base-groups
10547 This is the list of basic user groups that users and/or packages expect to
10548 be present on the system. This includes groups such as ``root'', ``wheel'',
10549 and ``users'', as well as groups used to control access to specific devices
10550 such as ``audio'', ``disk'', and ``cdrom''.
10553 @defvr {Scheme Variable} %base-user-accounts
10554 This is the list of basic system accounts that programs may expect to find
10555 on a GNU/Linux system, such as the ``nobody'' account.
10557 Note that the ``root'' account is not included here. It is a special-case
10558 and is automatically added whether or not it is specified.
10562 @subsection Locales
10565 A @dfn{locale} defines cultural conventions for a particular language and
10566 region of the world (@pxref{Locales,,, libc, The GNU C Library Reference
10567 Manual}). Each locale has a name that typically has the form
10568 @code{@var{language}_@var{territory}.@var{codeset}}---e.g.,
10569 @code{fr_LU.utf8} designates the locale for the French language, with
10570 cultural conventions from Luxembourg, and using the UTF-8 encoding.
10572 @cindex locale definition
10573 Usually, you will want to specify the default locale for the machine using
10574 the @code{locale} field of the @code{operating-system} declaration
10575 (@pxref{„operating-system“-Referenz, @code{locale}}).
10577 The selected locale is automatically added to the @dfn{locale definitions}
10578 known to the system if needed, with its codeset inferred from its
10579 name---e.g., @code{bo_CN.utf8} will be assumed to use the @code{UTF-8}
10580 codeset. Additional locale definitions can be specified in the
10581 @code{locale-definitions} slot of @code{operating-system}---this is useful,
10582 for instance, if the codeset could not be inferred from the locale name.
10583 The default set of locale definitions includes some widely used locales, but
10584 not all the available locales, in order to save space.
10586 For instance, to add the North Frisian locale for Germany, the value of that
10590 (cons (locale-definition
10591 (name "fy_DE.utf8") (source "fy_DE"))
10592 %default-locale-definitions)
10595 Likewise, to save space, one might want @code{locale-definitions} to list
10596 only the locales that are actually used, as in:
10599 (list (locale-definition
10600 (name "ja_JP.eucjp") (source "ja_JP")
10601 (charset "EUC-JP")))
10605 The compiled locale definitions are available at
10606 @file{/run/current-system/locale/X.Y}, where @code{X.Y} is the libc version,
10607 which is the default location where the GNU@tie{}libc provided by Guix looks
10608 for locale data. This can be overridden using the @code{LOCPATH}
10609 environment variable (@pxref{locales-and-locpath, @code{LOCPATH} and locale
10612 The @code{locale-definition} form is provided by the @code{(gnu system
10613 locale)} module. Details are given below.
10615 @deftp {Data Type} locale-definition
10616 This is the data type of a locale definition.
10621 The name of the locale. @xref{Locale Names,,, libc, The GNU C Library
10622 Reference Manual}, for more information on locale names.
10624 @item @code{source}
10625 The name of the source for that locale. This is typically the
10626 @code{@var{language}_@var{territory}} part of the locale name.
10628 @item @code{charset} (default: @code{"UTF-8"})
10629 The ``character set'' or ``code set'' for that locale,
10630 @uref{http://www.iana.org/assignments/character-sets, as defined by IANA}.
10635 @defvr {Scheme Variable} %default-locale-definitions
10636 A list of commonly used UTF-8 locales, used as the default value of the
10637 @code{locale-definitions} field of @code{operating-system} declarations.
10639 @cindex locale name
10640 @cindex normalized codeset in locale names
10641 These locale definitions use the @dfn{normalized codeset} for the part that
10642 follows the dot in the name (@pxref{Using gettextized software, normalized
10643 codeset,, libc, The GNU C Library Reference Manual}). So for instance it
10644 has @code{uk_UA.utf8} but @emph{not}, say, @code{uk_UA.UTF-8}.
10647 @subsubsection Locale Data Compatibility Considerations
10649 @cindex incompatibility, of locale data
10650 @code{operating-system} declarations provide a @code{locale-libcs} field to
10651 specify the GNU@tie{}libc packages that are used to compile locale
10652 declarations (@pxref{„operating-system“-Referenz}). ``Why would I care?'',
10653 you may ask. Well, it turns out that the binary format of locale data is
10654 occasionally incompatible from one libc version to another.
10656 @c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html>
10657 @c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>.
10658 For instance, a program linked against libc version 2.21 is unable to read
10659 locale data produced with libc 2.22; worse, that program @emph{aborts}
10660 instead of simply ignoring the incompatible locale data@footnote{Versions
10661 2.23 and later of GNU@tie{}libc will simply skip the incompatible locale
10662 data, which is already an improvement.}. Similarly, a program linked
10663 against libc 2.22 can read most, but not all, of the locale data from libc
10664 2.21 (specifically, @code{LC_COLLATE} data is incompatible); thus calls to
10665 @code{setlocale} may fail, but programs will not abort.
10667 The ``problem'' in GuixSD is that users have a lot of freedom: They can
10668 choose whether and when to upgrade software in their profiles, and might be
10669 using a libc version different from the one the system administrator used to
10670 build the system-wide locale data.
10672 Fortunately, unprivileged users can also install their own locale data and
10673 define @var{GUIX_LOCPATH} accordingly (@pxref{locales-and-locpath,
10674 @code{GUIX_LOCPATH} and locale packages}).
10676 Still, it is best if the system-wide locale data at
10677 @file{/run/current-system/locale} is built for all the libc versions
10678 actually in use on the system, so that all the programs can access it---this
10679 is especially crucial on a multi-user system. To do that, the administrator
10680 can specify several libc packages in the @code{locale-libcs} field of
10681 @code{operating-system}:
10684 (use-package-modules base)
10688 (locale-libcs (list glibc-2.21 (canonical-package glibc))))
10691 This example would lead to a system containing locale definitions for both
10692 libc 2.21 and the current version of libc in
10693 @file{/run/current-system/locale}.
10697 @subsection Dienste
10699 @cindex system services
10700 An important part of preparing an @code{operating-system} declaration is
10701 listing @dfn{system services} and their configuration (@pxref{Das Konfigurationssystem nutzen}). System services are typically daemons launched when
10702 the system boots, or other actions needed at that time---e.g., configuring
10705 GuixSD has a broad definition of ``service'' (@pxref{Dienstkompositionen}),
10706 but many services are managed by the GNU@tie{}Shepherd (@pxref{Shepherd-Dienste}). On a running system, the @command{herd} command allows you to
10707 list the available services, show their status, start and stop them, or do
10708 other specific operations (@pxref{Jump Start,,, shepherd, The GNU Shepherd
10709 Manual}). For example:
10715 The above command, run as @code{root}, lists the currently defined
10716 services. The @command{herd doc} command shows a synopsis of the given
10717 service and its associated actions:
10721 Run libc's name service cache daemon (nscd).
10723 # herd doc nscd action invalidate
10724 invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.
10727 The @command{start}, @command{stop}, and @command{restart} sub-commands have
10728 the effect you would expect. For instance, the commands below stop the nscd
10729 service and restart the Xorg display server:
10733 Service nscd has been stopped.
10734 # herd restart xorg-server
10735 Service xorg-server has been stopped.
10736 Service xorg-server has been started.
10739 The following sections document the available services, starting with the
10740 core services, that may be used in an @code{operating-system} declaration.
10743 * Basisdienste:: Essenzielle Systemdienste.
10744 * Geplante Auftragsausführung:: Der mcron-Dienst.
10745 * Log-Rotation:: Der rottlog-Dienst.
10746 * Netzwerkdienste:: Netzwerkeinrichtung, SSH-Daemon etc.
10747 * X Window:: Graphische Anzeige.
10748 * Druckdienste:: Unterstützung für lokale und entfernte
10750 * Desktop-Dienste:: D-Bus- und Desktop-Dienste.
10751 * Sound Services:: ALSA and Pulseaudio services.
10752 * Datenbankdienste:: SQL-Datenbanken, Schlüssel-Wert-Speicher etc.
10753 * Mail-Dienste:: IMAP, POP3, SMTP und so weiter.
10754 * Kurznachrichtendienste:: Dienste für Kurznachrichten.
10755 * Telefondienste:: Telefoniedienste.
10756 * Überwachungsdienste:: Dienste zur Systemüberwachung.
10757 * Kerberos-Dienste:: Kerberos-Dienste.
10758 * Web-Dienste:: Web-Server.
10759 * Zertifikatsdienste:: TLS-Zertifikate via Let’s Encrypt.
10760 * DNS-Dienste:: DNS-Daemons.
10761 * VPN-Dienste:: VPN-Daemons.
10762 * Network File System:: Dienste mit Bezug zum Netzwerkdateisystem.
10763 * Kontinuierliche Integration:: Der Cuirass-Dienst.
10764 * Power Management Services:: Extending battery life.
10765 * Audio-Dienste:: Der MPD.
10766 * Virtualisierungsdienste:: Dienste für virtuelle Maschinen.
10767 * Versionskontrolldienste:: Entfernten Zugang zu Git-Repositorys bieten.
10768 * Spieldienste:: Spielserver.
10769 * Verschiedene Dienste:: Andere Dienste.
10773 @subsubsection Basisdienste
10775 The @code{(gnu services base)} module provides definitions for the basic
10776 services that one expects from the system. The services exported by this
10777 module are listed below.
10779 @defvr {Scheme Variable} %base-services
10780 This variable contains a list of basic services (@pxref{Diensttypen und Dienste}, for more information on service objects) one would expect from
10781 the system: a login service (mingetty) on each tty, syslogd, the libc name
10782 service cache daemon (nscd), the udev device manager, and more.
10784 This is the default value of the @code{services} field of
10785 @code{operating-system} declarations. Usually, when customizing a system,
10786 you will want to append services to @var{%base-services}, like this:
10789 (cons* (avahi-service) (lsh-service) %base-services)
10793 @defvr {Scheme Variable} special-files-service-type
10794 This is the service that sets up ``special files'' such as @file{/bin/sh};
10795 an instance of it is part of @code{%base-services}.
10797 The value associated with @code{special-files-service-type} services must be
10798 a list of tuples where the first element is the ``special file'' and the
10799 second element is its target. By default it is:
10801 @cindex @file{/bin/sh}
10802 @cindex @file{sh}, in @file{/bin}
10804 `(("/bin/sh" ,(file-append @var{bash} "/bin/sh")))
10807 @cindex @file{/usr/bin/env}
10808 @cindex @file{env}, in @file{/usr/bin}
10809 If you want to add, say, @code{/usr/bin/env} to your system, you can change
10813 `(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))
10814 ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env")))
10817 Since this is part of @code{%base-services}, you can use
10818 @code{modify-services} to customize the set of special files (@pxref{Service-Referenz, @code{modify-services}}). But the simple way to add a special
10819 file is @i{via} the @code{extra-special-file} procedure (see below.)
10822 @deffn {Scheme Procedure} extra-special-file @var{file} @var{target}
10823 Use @var{target} as the ``special file'' @var{file}.
10825 For example, adding the following lines to the @code{services} field of your
10826 operating system declaration leads to a @file{/usr/bin/env} symlink:
10829 (extra-special-file "/usr/bin/env"
10830 (file-append coreutils "/bin/env"))
10834 @deffn {Scheme Procedure} host-name-service @var{name}
10835 Return a service that sets the host name to @var{name}.
10838 @deffn {Scheme Procedure} login-service @var{config}
10839 Return a service to run login according to @var{config}, a
10840 @code{<login-configuration>} object, which specifies the message of the day,
10841 among other things.
10844 @deftp {Data Type} login-configuration
10845 This is the data type representing the configuration of login.
10850 @cindex message of the day
10851 A file-like object containing the ``message of the day''.
10853 @item @code{allow-empty-passwords?} (default: @code{#t})
10854 Allow empty passwords by default so that first-time users can log in when
10855 the 'root' account has just been created.
10860 @deffn {Scheme Procedure} mingetty-service @var{config}
10861 Return a service to run mingetty according to @var{config}, a
10862 @code{<mingetty-configuration>} object, which specifies the tty to run,
10863 among other things.
10866 @deftp {Data Type} mingetty-configuration
10867 This is the data type representing the configuration of Mingetty, which
10868 provides the default implementation of virtual console log-in.
10873 The name of the console this Mingetty runs on---e.g., @code{"tty1"}.
10875 @item @code{auto-login} (default: @code{#f})
10876 When true, this field must be a string denoting the user name under which
10877 the system automatically logs in. When it is @code{#f}, a user name and
10878 password must be entered to log in.
10880 @item @code{login-program} (default: @code{#f})
10881 This must be either @code{#f}, in which case the default log-in program is
10882 used (@command{login} from the Shadow tool suite), or a gexp denoting the
10883 name of the log-in program.
10885 @item @code{login-pause?} (default: @code{#f})
10886 When set to @code{#t} in conjunction with @var{auto-login}, the user will
10887 have to press a key before the log-in shell is launched.
10889 @item @code{mingetty} (default: @var{mingetty})
10890 The Mingetty package to use.
10895 @deffn {Scheme Procedure} agetty-service @var{config}
10896 Return a service to run agetty according to @var{config}, an
10897 @code{<agetty-configuration>} object, which specifies the tty to run, among
10901 @deftp {Data Type} agetty-configuration
10902 This is the data type representing the configuration of agetty, which
10903 implements virtual and serial console log-in. See the @code{agetty(8)} man
10904 page for more information.
10909 The name of the console this agetty runs on, as a string---e.g.,
10910 @code{"ttyS0"}. This argument is optional, it will default to a reasonable
10911 default serial port used by the kernel Linux.
10913 For this, if there is a value for an option @code{agetty.tty} in the kernel
10914 command line, agetty will extract the device name of the serial port from it
10917 If not and if there is a value for an option @code{console} with a tty in
10918 the Linux command line, agetty will extract the device name of the serial
10919 port from it and use that.
10921 In both cases, agetty will leave the other serial device settings (baud rate
10922 etc.)@: alone---in the hope that Linux pinned them to the correct values.
10924 @item @code{baud-rate} (default: @code{#f})
10925 A string containing a comma-separated list of one or more baud rates, in
10928 @item @code{term} (default: @code{#f})
10929 A string containing the value used for the @code{TERM} environment variable.
10931 @item @code{eight-bits?} (default: @code{#f})
10932 When @code{#t}, the tty is assumed to be 8-bit clean, and parity detection
10935 @item @code{auto-login} (default: @code{#f})
10936 When passed a login name, as a string, the specified user will be logged in
10937 automatically without prompting for their login name or password.
10939 @item @code{no-reset?} (default: @code{#f})
10940 When @code{#t}, don't reset terminal cflags (control modes).
10942 @item @code{host} (default: @code{#f})
10943 This accepts a string containing the "login_host", which will be written
10944 into the @file{/var/run/utmpx} file.
10946 @item @code{remote?} (default: @code{#f})
10947 When set to @code{#t} in conjunction with @var{host}, this will add an
10948 @code{-r} fakehost option to the command line of the login program specified
10949 in @var{login-program}.
10951 @item @code{flow-control?} (default: @code{#f})
10952 When set to @code{#t}, enable hardware (RTS/CTS) flow control.
10954 @item @code{no-issue?} (default: @code{#f})
10955 When set to @code{#t}, the contents of the @file{/etc/issue} file will not
10956 be displayed before presenting the login prompt.
10958 @item @code{init-string} (default: @code{#f})
10959 This accepts a string that will be sent to the tty or modem before sending
10960 anything else. It can be used to initialize a modem.
10962 @item @code{no-clear?} (default: @code{#f})
10963 When set to @code{#t}, agetty will not clear the screen before showing the
10966 @item @code{login-program} (default: (file-append shadow "/bin/login"))
10967 This must be either a gexp denoting the name of a log-in program, or unset,
10968 in which case the default value is the @command{login} from the Shadow tool
10971 @item @code{local-line} (default: @code{#f})
10972 Control the CLOCAL line flag. This accepts one of three symbols as
10973 arguments, @code{'auto}, @code{'always}, or @code{'never}. If @code{#f}, the
10974 default value chosen by agetty is @code{'auto}.
10976 @item @code{extract-baud?} (default: @code{#f})
10977 When set to @code{#t}, instruct agetty to try to extract the baud rate from
10978 the status messages produced by certain types of modems.
10980 @item @code{skip-login?} (default: @code{#f})
10981 When set to @code{#t}, do not prompt the user for a login name. This can be
10982 used with @var{login-program} field to use non-standard login systems.
10984 @item @code{no-newline?} (default: @code{#f})
10985 When set to @code{#t}, do not print a newline before printing the
10986 @file{/etc/issue} file.
10988 @c Is this dangerous only when used with login-program, or always?
10989 @item @code{login-options} (default: @code{#f})
10990 This option accepts a string containing options that are passed to the login
10991 program. When used with the @var{login-program}, be aware that a malicious
10992 user could try to enter a login name containing embedded options that could
10993 be parsed by the login program.
10995 @item @code{login-pause} (default: @code{#f})
10996 When set to @code{#t}, wait for any key before showing the login prompt.
10997 This can be used in conjunction with @var{auto-login} to save memory by
10998 lazily spawning shells.
11000 @item @code{chroot} (default: @code{#f})
11001 Change root to the specified directory. This option accepts a directory
11004 @item @code{hangup?} (default: @code{#f})
11005 Use the Linux system call @code{vhangup} to do a virtual hangup of the
11006 specified terminal.
11008 @item @code{keep-baud?} (default: @code{#f})
11009 When set to @code{#t}, try to keep the existing baud rate. The baud rates
11010 from @var{baud-rate} are used when agetty receives a @key{BREAK} character.
11012 @item @code{timeout} (default: @code{#f})
11013 When set to an integer value, terminate if no user name could be read within
11014 @var{timeout} seconds.
11016 @item @code{detect-case?} (default: @code{#f})
11017 When set to @code{#t}, turn on support for detecting an uppercase-only
11018 terminal. This setting will detect a login name containing only uppercase
11019 letters as indicating an uppercase-only terminal and turn on some
11020 upper-to-lower case conversions. Note that this will not support Unicode
11023 @item @code{wait-cr?} (default: @code{#f})
11024 When set to @code{#t}, wait for the user or modem to send a carriage-return
11025 or linefeed character before displaying @file{/etc/issue} or login prompt.
11026 This is typically used with the @var{init-string} option.
11028 @item @code{no-hints?} (default: @code{#f})
11029 When set to @code{#t}, do not print hints about Num, Caps, and Scroll locks.
11031 @item @code{no-hostname?} (default: @code{#f})
11032 By default, the hostname is printed. When this option is set to @code{#t},
11033 no hostname will be shown at all.
11035 @item @code{long-hostname?} (default: @code{#f})
11036 By default, the hostname is only printed until the first dot. When this
11037 option is set to @code{#t}, the fully qualified hostname by
11038 @code{gethostname} or @code{getaddrinfo} is shown.
11040 @item @code{erase-characters} (default: @code{#f})
11041 This option accepts a string of additional characters that should be
11042 interpreted as backspace when the user types their login name.
11044 @item @code{kill-characters} (default: @code{#f})
11045 This option accepts a string that should be interpreted to mean "ignore all
11046 previous characters" (also called a "kill" character) when the types their
11049 @item @code{chdir} (default: @code{#f})
11050 This option accepts, as a string, a directory path that will be changed to
11053 @item @code{delay} (default: @code{#f})
11054 This options accepts, as an integer, the number of seconds to sleep before
11055 opening the tty and displaying the login prompt.
11057 @item @code{nice} (default: @code{#f})
11058 This option accepts, as an integer, the nice value with which to run the
11059 @command{login} program.
11061 @item @code{extra-options} (default: @code{'()})
11062 This option provides an "escape hatch" for the user to provide arbitrary
11063 command-line arguments to @command{agetty} as a list of strings.
11068 @deffn {Scheme Procedure} kmscon-service-type @var{config}
11069 Return a service to run
11070 @uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} according to
11071 @var{config}, a @code{<kmscon-configuration>} object, which specifies the
11072 tty to run, among other things.
11075 @deftp {Data Type} kmscon-configuration
11076 This is the data type representing the configuration of Kmscon, which
11077 implements virtual console log-in.
11081 @item @code{virtual-terminal}
11082 The name of the console this Kmscon runs on---e.g., @code{"tty1"}.
11084 @item @code{login-program} (default: @code{#~(string-append #$shadow "/bin/login")})
11085 A gexp denoting the name of the log-in program. The default log-in program
11086 is @command{login} from the Shadow tool suite.
11088 @item @code{login-arguments} (default: @code{'("-p")})
11089 A list of arguments to pass to @command{login}.
11091 @item @code{auto-login} (default: @code{#f})
11092 When passed a login name, as a string, the specified user will be logged in
11093 automatically without prompting for their login name or password.
11095 @item @code{hardware-acceleration?} (default: #f)
11096 Whether to use hardware acceleration.
11098 @item @code{kmscon} (default: @var{kmscon})
11099 The Kmscon package to use.
11104 @cindex name service cache daemon
11106 @deffn {Scheme Procedure} nscd-service [@var{config}] [#:glibc glibc] @
11107 [#:name-services '()] Return a service that runs the libc name service cache
11108 daemon (nscd) with the given @var{config}---an @code{<nscd-configuration>}
11109 object. @xref{Name Service Switch}, for an example.
11111 For convenience, the Shepherd service for nscd provides the following
11116 @cindex cache invalidation, nscd
11117 @cindex nscd, cache invalidation
11118 This invalidate the given cache. For instance, running:
11121 herd invalidate nscd hosts
11125 invalidates the host name lookup cache of nscd.
11128 Running @command{herd statistics nscd} displays information about nscd usage
11134 @defvr {Scheme Variable} %nscd-default-configuration
11135 This is the default @code{<nscd-configuration>} value (see below) used by
11136 @code{nscd-service}. It uses the caches defined by
11137 @var{%nscd-default-caches}; see below.
11140 @deftp {Data Type} nscd-configuration
11141 This is the data type representing the name service cache daemon (nscd)
11146 @item @code{name-services} (default: @code{'()})
11147 List of packages denoting @dfn{name services} that must be visible to the
11148 nscd---e.g., @code{(list @var{nss-mdns})}.
11150 @item @code{glibc} (default: @var{glibc})
11151 Package object denoting the GNU C Library providing the @command{nscd}
11154 @item @code{log-file} (default: @code{"/var/log/nscd.log"})
11155 Name of the nscd log file. This is where debugging output goes when
11156 @code{debug-level} is strictly positive.
11158 @item @code{debug-level} (default: @code{0})
11159 Integer denoting the debugging levels. Higher numbers mean that more
11160 debugging output is logged.
11162 @item @code{caches} (default: @var{%nscd-default-caches})
11163 List of @code{<nscd-cache>} objects denoting things to be cached; see below.
11168 @deftp {Data Type} nscd-cache
11169 Data type representing a cache database of nscd and its parameters.
11173 @item @code{database}
11174 This is a symbol representing the name of the database to be cached. Valid
11175 values are @code{passwd}, @code{group}, @code{hosts}, and @code{services},
11176 which designate the corresponding NSS database (@pxref{NSS Basics,,, libc,
11177 The GNU C Library Reference Manual}).
11179 @item @code{positive-time-to-live}
11180 @itemx @code{negative-time-to-live} (default: @code{20})
11181 A number representing the number of seconds during which a positive or
11182 negative lookup result remains in cache.
11184 @item @code{check-files?} (default: @code{#t})
11185 Whether to check for updates of the files corresponding to @var{database}.
11187 For instance, when @var{database} is @code{hosts}, setting this flag
11188 instructs nscd to check for updates in @file{/etc/hosts} and to take them
11191 @item @code{persistent?} (default: @code{#t})
11192 Whether the cache should be stored persistently on disk.
11194 @item @code{shared?} (default: @code{#t})
11195 Whether the cache should be shared among users.
11197 @item @code{max-database-size} (default: 32@tie{}MiB)
11198 Maximum size in bytes of the database cache.
11200 @c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert
11201 @c settings, so leave them out.
11206 @defvr {Scheme Variable} %nscd-default-caches
11207 List of @code{<nscd-cache>} objects used by default by
11208 @code{nscd-configuration} (see above).
11210 It enables persistent and aggressive caching of service and host name
11211 lookups. The latter provides better host name lookup performance,
11212 resilience in the face of unreliable name servers, and also better
11213 privacy---often the result of host name lookups is in local cache, so
11214 external name servers do not even need to be queried.
11217 @anchor{syslog-configuration-type}
11220 @deftp {Data Type} syslog-configuration
11221 This data type represents the configuration of the syslog daemon.
11224 @item @code{syslogd} (default: @code{#~(string-append #$inetutils "/libexec/syslogd")})
11225 The syslog daemon to use.
11227 @item @code{config-file} (default: @code{%default-syslog.conf})
11228 The syslog configuration file to use.
11233 @anchor{syslog-service}
11235 @deffn {Scheme Procedure} syslog-service @var{config}
11236 Return a service that runs a syslog daemon according to @var{config}.
11238 @xref{syslogd invocation,,, inetutils, GNU Inetutils}, for more information
11239 on the configuration file syntax.
11242 @defvr {Scheme Variable} guix-service-type
11243 This is the type of the service that runs the build daemon,
11244 @command{guix-daemon} (@pxref{Aufruf des guix-daemon}). Its value must be a
11245 @code{guix-configuration} record as described below.
11248 @anchor{guix-configuration-type}
11249 @deftp {Data Type} guix-configuration
11250 This data type represents the configuration of the Guix build daemon.
11251 @xref{Aufruf des guix-daemon}, for more information.
11254 @item @code{guix} (default: @var{guix})
11255 The Guix package to use.
11257 @item @code{build-group} (default: @code{"guixbuild"})
11258 Name of the group for build user accounts.
11260 @item @code{build-accounts} (default: @code{10})
11261 Number of build user accounts to create.
11263 @item @code{authorize-key?} (default: @code{#t})
11264 @cindex Substitute, deren Autorisierung
11265 Whether to authorize the substitute keys listed in
11266 @code{authorized-keys}---by default that of @code{hydra.gnu.org}
11267 (@pxref{Substitute}).
11269 @vindex %default-authorized-guix-keys
11270 @item @code{authorized-keys} (default: @var{%default-authorized-guix-keys})
11271 The list of authorized key files for archive imports, as a list of
11272 string-valued gexps (@pxref{Aufruf von guix archive}). By default, it
11273 contains that of @code{hydra.gnu.org} (@pxref{Substitute}).
11275 @item @code{use-substitutes?} (default: @code{#t})
11276 Whether to use substitutes.
11278 @item @code{substitute-urls} (default: @var{%default-substitute-urls})
11279 The list of URLs where to look for substitutes by default.
11281 @item @code{max-silent-time} (default: @code{0})
11282 @itemx @code{timeout} (default: @code{0})
11283 The number of seconds of silence and the number of seconds of activity,
11284 respectively, after which a build process times out. A value of zero
11285 disables the timeout.
11287 @item @code{log-compression} (default: @code{'bzip2})
11288 The type of compression used for build logs---one of @code{gzip},
11289 @code{bzip2}, or @code{none}.
11291 @item @code{extra-options} (default: @code{'()})
11292 List of extra command-line options for @command{guix-daemon}.
11294 @item @code{log-file} (default: @code{"/var/log/guix-daemon.log"})
11295 File where @command{guix-daemon}'s standard output and standard error are
11298 @item @code{http-proxy} (default: @code{#f})
11299 The HTTP proxy used for downloading fixed-output derivations and
11302 @item @code{tmpdir} (default: @code{#f})
11303 A directory path where the @command{guix-daemon} will perform builds.
11308 @deffn {Scheme Procedure} udev-service [#:udev @var{eudev} #:rules @code{'()}]
11309 Run @var{udev}, which populates the @file{/dev} directory dynamically. udev
11310 rules can be provided as a list of files through the @var{rules} variable.
11311 The procedures @var{udev-rule} and @var{file->udev-rule} from @code{(gnu
11312 services base)} simplify the creation of such rule files.
11314 @deffn {Scheme Procedure} udev-rule [@var{file-name} @var{contents}]
11315 Return a udev-rule file named @var{file-name} containing the rules defined
11316 by the @var{contents} literal.
11318 In the following example, a rule for a USB device is defined to be stored in
11319 the file @file{90-usb-thing.rules}. The rule runs a script upon detecting a
11320 USB device with a given product identifier.
11323 (define %example-udev-rule
11325 "90-usb-thing.rules"
11326 (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
11327 "ATTR@{product@}==\"Example\", "
11328 "RUN+=\"/path/to/script\"")))
11332 Here we show how the default @var{udev-service} can be extended with it.
11338 (modify-services %desktop-services
11339 (udev-service-type config =>
11340 (udev-configuration (inherit config)
11341 (rules (append (udev-configuration-rules config)
11342 (list %example-udev-rule))))))))
11345 @deffn {Scheme Procedure} file->udev-rule [@var{file-name} @var{file}]
11346 Return a udev file named @var{file-name} containing the rules defined within
11347 @var{file}, a file-like object.
11349 The following example showcases how we can use an existing rule file.
11352 (use-modules (guix download) ;for url-fetch
11353 (guix packages) ;for origin
11356 (define %android-udev-rules
11358 "51-android-udev.rules"
11359 (let ((version "20170910"))
11362 (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
11363 "android-udev-rules/" version "/51-android.rules"))
11365 (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))
11369 Additionally, Guix package definitions can be included in @var{rules} in
11370 order to extend the udev rules with the definitions found under their
11371 @file{lib/udev/rules.d} sub-directory. In lieu of the previous
11372 @var{file->udev-rule} example, we could have used the
11373 @var{android-udev-rules} package which exists in Guix in the @code{(gnu
11374 packages android)} module.
11376 The following example shows how to use the @var{android-udev-rules} package
11377 so that the Android tool @command{adb} can detect devices without root
11378 privileges. It also details how to create the @code{adbusers} group, which
11379 is required for the proper functioning of the rules defined within the
11380 @var{android-udev-rules} package. To create such a group, we must define it
11381 both as part of the @var{supplementary-groups} of our @var{user-account}
11382 declaration, as well as in the @var{groups} field of the
11383 @var{operating-system} record.
11386 (use-modules (gnu packages android) ;for android-udev-rules
11387 (gnu system shadow) ;for user-group
11392 (users (cons (user-acount
11394 (supplementary-groups
11395 '("adbusers" ;for adb
11396 "wheel" "netdev" "audio" "video"))
11399 (groups (cons (user-group (system? #t) (name "adbusers"))
11405 (modify-services %desktop-services
11406 (udev-service-type config =>
11407 (udev-configuration (inherit config)
11408 (rules (cons* android-udev-rules
11409 (udev-configuration-rules config))))))))
11413 @defvr {Scheme Variable} urandom-seed-service-type
11414 Save some entropy in @var{%random-seed-file} to seed @file{/dev/urandom}
11415 when rebooting. It also tries to seed @file{/dev/urandom} from
11416 @file{/dev/hwrng} while booting, if @file{/dev/hwrng} exists and is
11420 @defvr {Scheme Variable} %random-seed-file
11421 This is the name of the file where some random bytes are saved by
11422 @var{urandom-seed-service} to seed @file{/dev/urandom} when rebooting. It
11423 defaults to @file{/var/lib/random-seed}.
11428 @deffn {Scheme Procedure} console-keymap-service @var{files} ...
11429 @cindex keyboard layout
11430 Return a service to load console keymaps from @var{files} using
11431 @command{loadkeys} command. Most likely, you want to load some default
11432 keymap, which can be done like this:
11435 (console-keymap-service "dvorak")
11438 Or, for example, for a Swedish keyboard, you may need to combine the
11441 (console-keymap-service "se-lat6" "se-fi-lat6")
11444 Also you can specify a full file name (or file names) of your keymap(s).
11445 See @code{man loadkeys} for details.
11451 @defvr {Scheme Variable} gpm-service-type
11452 This is the type of the service that runs GPM, the @dfn{general-purpose
11453 mouse daemon}, which provides mouse support to the Linux console. GPM
11454 allows users to use the mouse in the console, notably to select, copy, and
11457 The value for services of this type must be a @code{gpm-configuration} (see
11458 below). This service is not part of @var{%base-services}.
11461 @deftp {Data Type} gpm-configuration
11462 Data type representing the configuration of GPM.
11465 @item @code{options} (default: @code{%default-gpm-options})
11466 Command-line options passed to @command{gpm}. The default set of options
11467 instruct @command{gpm} to listen to mouse events on @file{/dev/input/mice}.
11468 @xref{Command Line,,, gpm, gpm manual}, for more information.
11470 @item @code{gpm} (default: @code{gpm})
11471 The GPM package to use.
11476 @anchor{guix-publish-service-type}
11477 @deffn {Scheme Variable} guix-publish-service-type
11478 This is the service type for @command{guix publish} (@pxref{Aufruf von guix publish}). Its value must be a @code{guix-configuration} object, as
11481 This assumes that @file{/etc/guix} already contains a signing key pair as
11482 created by @command{guix archive --generate-key} (@pxref{Aufruf von guix archive}). If that is not the case, the service will fail to start.
11485 @deftp {Data Type} guix-publish-configuration
11486 Data type representing the configuration of the @code{guix publish} service.
11489 @item @code{guix} (default: @code{guix})
11490 The Guix package to use.
11492 @item @code{port} (default: @code{80})
11493 The TCP port to listen for connections.
11495 @item @code{host} (default: @code{"localhost"})
11496 The host (and thus, network interface) to listen to. Use @code{"0.0.0.0"}
11497 to listen on all the network interfaces.
11499 @item @code{compression-level} (Vorgabe: @code{3})
11500 The gzip compression level at which substitutes are compressed. Use
11501 @code{0} to disable compression altogether, and @code{9} to get the best
11502 compression ratio at the expense of increased CPU usage.
11504 @item @code{nar-path} (default: @code{"nar"})
11505 The URL path at which ``nars'' can be fetched. @xref{Aufruf von guix publish,
11506 @code{--nar-path}}, for details.
11508 @item @code{cache} (default: @code{#f})
11509 When it is @code{#f}, disable caching and instead generate archives on
11510 demand. Otherwise, this should be the name of a directory---e.g.,
11511 @code{"/var/cache/guix/publish"}---where @command{guix publish} caches
11512 archives and meta-data ready to be sent. @xref{Aufruf von guix publish,
11513 @option{--cache}}, for more information on the tradeoffs involved.
11515 @item @code{workers} (default: @code{#f})
11516 When it is an integer, this is the number of worker threads used for
11517 caching; when @code{#f}, the number of processors is used. @xref{Aufruf von guix publish, @option{--workers}}, for more information.
11519 @item @code{ttl} (default: @code{#f})
11520 When it is an integer, this denotes the @dfn{time-to-live} in seconds of the
11521 published archives. @xref{Aufruf von guix publish, @option{--ttl}}, for more
11526 @anchor{rngd-service}
11527 @deffn {Scheme Procedure} rngd-service [#:rng-tools @var{rng-tools}] @
11528 [#:device "/dev/hwrng"] Return a service that runs the @command{rngd}
11529 program from @var{rng-tools} to add @var{device} to the kernel's entropy
11530 pool. The service will fail if @var{device} does not exist.
11533 @anchor{pam-limits-service}
11534 @cindex session limits
11539 @deffn {Scheme Procedure} pam-limits-service [#:limits @code{'()}]
11541 Return a service that installs a configuration file for the
11542 @uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html,
11543 @code{pam_limits} module}. The procedure optionally takes a list of
11544 @code{pam-limits-entry} values, which can be used to specify @code{ulimit}
11545 limits and nice priority limits to user sessions.
11547 The following limits definition sets two hard and soft limits for all login
11548 sessions of users in the @code{realtime} group:
11551 (pam-limits-service
11553 (pam-limits-entry "@@realtime" 'both 'rtprio 99)
11554 (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited)))
11557 The first entry increases the maximum realtime priority for non-privileged
11558 processes; the second entry lifts any restriction of the maximum address
11559 space that can be locked in memory. These settings are commonly used for
11560 real-time audio systems.
11563 @node Geplante Auftragsausführung
11564 @subsubsection Geplante Auftragsausführung
11568 @cindex scheduling jobs
11569 The @code{(gnu services mcron)} module provides an interface to
11570 GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,,
11571 mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional Unix
11572 @command{cron} daemon; the main difference is that it is implemented in
11573 Guile Scheme, which provides a lot of flexibility when specifying the
11574 scheduling of jobs and their actions.
11576 The example below defines an operating system that runs the
11577 @command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files}) and
11578 the @command{guix gc} commands (@pxref{Aufruf von guix gc}) daily, as well as
11579 the @command{mkid} command on behalf of an unprivileged user (@pxref{mkid
11580 invocation,,, idutils, ID Database Utilities}). It uses gexps to introduce
11581 job definitions that are passed to mcron (@pxref{G-Ausdrücke}).
11584 (use-modules (guix) (gnu) (gnu services mcron))
11585 (use-package-modules base idutils)
11587 (define updatedb-job
11588 ;; Run 'updatedb' at 3AM every day. Here we write the
11589 ;; job's action as a Scheme procedure.
11590 #~(job '(next-hour '(3))
11592 (execl (string-append #$findutils "/bin/updatedb")
11594 "--prunepaths=/tmp /var/tmp /gnu/store"))))
11596 (define garbage-collector-job
11597 ;; Collect garbage 5 minutes after midnight every day.
11598 ;; The job's action is a shell command.
11599 #~(job "5 0 * * *" ;Vixie cron syntax
11602 (define idutils-job
11603 ;; Update the index database as user "charlie" at 12:15PM
11604 ;; and 19:15PM. This runs from the user's home directory.
11605 #~(job '(next-minute-from (next-hour '(12 19)) '(15))
11606 (string-append #$idutils "/bin/mkid src")
11611 (services (cons (mcron-service (list garbage-collector-job
11617 @xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron}, for
11618 more information on mcron job specifications. Below is the reference of the
11621 On a running system, you can use the @code{schedule} action of the service
11622 to visualize the mcron jobs that will be executed next:
11625 # herd schedule mcron
11629 The example above lists the next five tasks that will be executed, but you
11630 can also specify the number of tasks to display:
11633 # herd schedule mcron 10
11636 @deffn {Scheme Procedure} mcron-service @var{jobs} [#:mcron @var{mcron}]
11637 Return an mcron service running @var{mcron} that schedules @var{jobs}, a
11638 list of gexps denoting mcron job specifications.
11640 This is a shorthand for:
11642 (service mcron-service-type
11643 (mcron-configuration (mcron mcron) (jobs jobs)))
11647 @defvr {Scheme Variable} mcron-service-type
11648 This is the type of the @code{mcron} service, whose value is an
11649 @code{mcron-configuration} object.
11651 This service type can be the target of a service extension that provides it
11652 additional job specifications (@pxref{Dienstkompositionen}). In other
11653 words, it is possible to define services that provide additional mcron jobs
11657 @deftp {Data Type} mcron-configuration
11658 Data type representing the configuration of mcron.
11661 @item @code{mcron} (default: @var{mcron})
11662 The mcron package to use.
11665 This is a list of gexps (@pxref{G-Ausdrücke}), where each gexp corresponds
11666 to an mcron job specification (@pxref{Syntax, mcron job specifications,,
11667 mcron, GNU@tie{}mcron}).
11673 @subsubsection Log-Rotation
11676 @cindex log rotation
11678 Log files such as those found in @file{/var/log} tend to grow endlessly, so
11679 it's a good idea to @dfn{rotate} them once in a while---i.e., archive their
11680 contents in separate files, possibly compressed. The @code{(gnu services
11681 admin)} module provides an interface to GNU@tie{}Rot[t]log, a log rotation
11682 tool (@pxref{Top,,, rottlog, GNU Rot[t]log Manual}).
11684 The example below defines an operating system that provides log rotation
11685 with the default settings, for commonly encountered log files.
11688 (use-modules (guix) (gnu))
11689 (use-service-modules admin mcron)
11690 (use-package-modules base idutils)
11694 (services (cons (service rottlog-service-type)
11698 @defvr {Scheme Variable} rottlog-service-type
11699 This is the type of the Rottlog service, whose value is a
11700 @code{rottlog-configuration} object.
11702 Other services can extend this one with new @code{log-rotation} objects (see
11703 below), thereby augmenting the set of files to be rotated.
11705 This service type can define mcron jobs (@pxref{Geplante Auftragsausführung}) to
11706 run the rottlog service.
11709 @deftp {Data Type} rottlog-configuration
11710 Data type representing the configuration of rottlog.
11713 @item @code{rottlog} (default: @code{rottlog})
11714 The Rottlog package to use.
11716 @item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")})
11717 The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,,
11718 rottlog, GNU Rot[t]log Manual}).
11720 @item @code{rotations} (default: @code{%default-rotations})
11721 A list of @code{log-rotation} objects as defined below.
11724 This is a list of gexps where each gexp corresponds to an mcron job
11725 specification (@pxref{Geplante Auftragsausführung}).
11729 @deftp {Data Type} log-rotation
11730 Data type representing the rotation of a group of log files.
11732 Taking an example from the Rottlog manual (@pxref{Period Related File
11733 Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be defined
11739 (files '("/var/log/apache/*"))
11740 (options '("storedir apache-archives"
11746 The list of fields is as follows:
11749 @item @code{frequency} (default: @code{'weekly})
11750 The log rotation frequency, a symbol.
11753 The list of files or file glob patterns to rotate.
11755 @item @code{options} (default: @code{'()})
11756 The list of rottlog options for this rotation (@pxref{Configuration
11757 parameters,,, rottlog, GNU Rot[t]lg Manual}).
11759 @item @code{post-rotate} (default: @code{#f})
11760 Either @code{#f} or a gexp to execute once the rotation has completed.
11764 @defvr {Scheme Variable} %default-rotations
11765 Specifies weekly rotation of @var{%rotated-files} and a couple of other
11769 @defvr {Scheme Variable} %rotated-files
11770 The list of syslog-controlled files to be rotated. By default it is:
11771 @code{'("/var/log/messages" "/var/log/secure")}.
11774 @node Netzwerkdienste
11775 @subsubsection Netzwerkdienste
11777 The @code{(gnu services networking)} module provides services to configure
11778 the network interface.
11780 @cindex DHCP, networking service
11781 @defvr {Scheme Variable} dhcp-client-service-type
11782 This is the type of services that run @var{dhcp}, a Dynamic Host
11783 Configuration Protocol (DHCP) client, on all the non-loopback network
11784 interfaces. Its value is the DHCP client package to use, @code{isc-dhcp} by
11788 @deffn {Scheme Procedure} dhcpd-service-type
11789 This type defines a service that runs a DHCP daemon. To create a service of
11790 this type, you must supply a @code{<dhcpd-configuration>}. For example:
11793 (service dhcpd-service-type
11794 (dhcpd-configuration
11795 (config-file (local-file "my-dhcpd.conf"))
11796 (interfaces '("enp0s25"))))
11800 @deftp {Data Type} dhcpd-configuration
11802 @item @code{package} (default: @code{isc-dhcp})
11803 The package that provides the DHCP daemon. This package is expected to
11804 provide the daemon at @file{sbin/dhcpd} relative to its output directory.
11805 The default package is the @uref{http://www.isc.org/products/DHCP, ISC's
11807 @item @code{config-file} (default: @code{#f})
11808 The configuration file to use. This is required. It will be passed to
11809 @code{dhcpd} via its @code{-cf} option. This may be any ``file-like''
11810 object (@pxref{G-Ausdrücke, file-like objects}). See @code{man
11811 dhcpd.conf} for details on the configuration file syntax.
11812 @item @code{version} (default: @code{"4"})
11813 The DHCP version to use. The ISC DHCP server supports the values ``4'',
11814 ``6'', and ``4o6''. These correspond to the @code{dhcpd} program options
11815 @code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for details.
11816 @item @code{run-directory} (default: @code{"/run/dhcpd"})
11817 The run directory to use. At service activation time, this directory will
11818 be created if it does not exist.
11819 @item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"})
11820 The PID file to use. This corresponds to the @code{-pf} option of
11821 @code{dhcpd}. See @code{man dhcpd} for details.
11822 @item @code{interfaces} (default: @code{'()})
11823 The names of the network interfaces on which dhcpd should listen for
11824 broadcasts. If this list is not empty, then its elements (which must be
11825 strings) will be appended to the @code{dhcpd} invocation when starting the
11826 daemon. It may not be necessary to explicitly specify any interfaces here;
11827 see @code{man dhcpd} for details.
11831 @defvr {Scheme Variable} static-networking-service-type
11832 @c TODO Document <static-networking> data structures.
11833 This is the type for statically-configured network interfaces.
11836 @deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @
11837 [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @ [#:requirement
11838 @code{'(udev)}] Return a service that starts @var{interface} with address
11839 @var{ip}. If @var{netmask} is true, use it as the network mask. If
11840 @var{gateway} is true, it must be a string specifying the default network
11841 gateway. @var{requirement} can be used to declare a dependency on another
11842 service before configuring the interface.
11844 This procedure can be called several times, one for each network interface
11845 of interest. Behind the scenes what it does is extend
11846 @code{static-networking-service-type} with additional network interfaces to
11852 (static-networking-service "eno1" "192.168.1.82"
11853 #:gateway "192.168.1.2"
11854 #:name-servers '("192.168.1.2"))
11861 @cindex network management
11862 @deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}]
11863 Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network
11864 management daemon that aims to simplify wired and wireless networking.
11866 This service adds the @var{wicd} package to the global profile, providing
11867 several commands to interact with the daemon and configure networking:
11868 @command{wicd-client}, a graphical user interface, and the
11869 @command{wicd-cli} and @command{wicd-curses} user interfaces.
11872 @cindex ModemManager
11874 @defvr {Scheme Variable} modem-manager-service-type
11875 This is the service type for the
11876 @uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager}
11877 service. The value for this service type is a
11878 @code{modem-manager-configuration} record.
11880 This service is part of @code{%desktop-services} (@pxref{Desktop-Dienste}).
11883 @deftp {Data Type} modem-manager-configuration
11884 Data type representing the configuration of ModemManager.
11887 @item @code{modem-manager} (default: @code{modem-manager})
11888 The ModemManager package to use.
11893 @cindex NetworkManager
11895 @defvr {Scheme Variable} network-manager-service-type
11896 This is the service type for the
11897 @uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager}
11898 service. The value for this service type is a
11899 @code{network-manager-configuration} record.
11901 This service is part of @code{%desktop-services} (@pxref{Desktop-Dienste}).
11904 @deftp {Data Type} network-manager-configuration
11905 Data type representing the configuration of NetworkManager.
11908 @item @code{network-manager} (default: @code{network-manager})
11909 The NetworkManager package to use.
11911 @item @code{dns} (default: @code{"default"})
11912 Processing mode for DNS, which affects how NetworkManager uses the
11913 @code{resolv.conf} configuration file.
11917 NetworkManager will update @code{resolv.conf} to reflect the nameservers
11918 provided by currently active connections.
11921 NetworkManager will run @code{dnsmasq} as a local caching nameserver, using
11922 a "split DNS" configuration if you are connected to a VPN, and then update
11923 @code{resolv.conf} to point to the local nameserver.
11926 NetworkManager will not modify @code{resolv.conf}.
11929 @item @code{vpn-plugins} (default: @code{'()})
11930 This is the list of available plugins for virtual private networks (VPNs).
11931 An example of this is the @code{network-manager-openvpn} package, which
11932 allows NetworkManager to manage VPNs @i{via} OpenVPN.
11938 @deffn {Scheme Variable} connman-service-type
11939 This is the service type to run @url{https://01.org/connman,Connman}, a
11940 network connection manager.
11942 Its value must be an @code{connman-configuration} record as in this example:
11945 (service connman-service-type
11946 (connman-configuration
11947 (disable-vpn? #t)))
11950 See below for details about @code{connman-configuration}.
11953 @deftp {Data Type} connman-configuration
11954 Data Type representing the configuration of connman.
11957 @item @code{connman} (default: @var{connman})
11958 The connman package to use.
11960 @item @code{disable-vpn?} (default: @code{#f})
11961 When true, disable connman's vpn plugin.
11965 @cindex WPA Supplicant
11966 @defvr {Scheme Variable} wpa-supplicant-service-type
11967 This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA
11968 supplicant}, an authentication daemon required to authenticate against
11969 encrypted WiFi or ethernet networks.
11972 @deftp {Data Type} wpa-supplicant-configuration
11973 Data type representing the configuration of WPA Supplicant.
11975 It takes the following parameters:
11978 @item @code{wpa-supplicant} (default: @code{wpa-supplicant})
11979 The WPA Supplicant package to use.
11981 @item @code{dbus?} (default: @code{#t})
11982 Whether to listen for requests on D-Bus.
11984 @item @code{pid-file} (default: @code{"/var/run/wpa_supplicant.pid"})
11985 Where to store the PID file.
11987 @item @code{interface} (default: @code{#f})
11988 If this is set, it must specify the name of a network interface that WPA
11989 supplicant will control.
11991 @item @code{config-file} (default: @code{#f})
11992 Optional configuration file to use.
11994 @item @code{extra-options} (default: @code{'()})
11995 List of additional command-line arguments to pass to the daemon.
12000 @defvr {Scheme Variable} iptables-service-type
12001 This is the service type to set up an iptables configuration. iptables is a
12002 packet filtering framework supported by the Linux kernel. This service
12003 supports configuring iptables for both IPv4 and IPv6. A simple example
12004 configuration rejecting all incoming connections except those to the ssh
12005 port 22 is shown below.
12008 (service iptables-service-type
12009 (iptables-configuration
12010 (ipv4-rules (plain-file "iptables.rules" "*filter
12014 -A INPUT -p tcp --dport 22 -j ACCEPT
12015 -A INPUT -j REJECT --reject-with icmp-port-unreachable
12018 (ipv6-rules (plain-file "ip6tables.rules" "*filter
12022 -A INPUT -p tcp --dport 22 -j ACCEPT
12023 -A INPUT -j REJECT --reject-with icmp6-port-unreachable
12029 @deftp {Data Type} iptables-configuration
12030 The data type representing the configuration of iptables.
12033 @item @code{iptables} (default: @code{iptables})
12034 The iptables package that provides @code{iptables-restore} and
12035 @code{ip6tables-restore}.
12036 @item @code{ipv4-rules} (default: @code{%iptables-accept-all-rules})
12037 The iptables rules to use. It will be passed to @code{iptables-restore}.
12038 This may be any ``file-like'' object (@pxref{G-Ausdrücke, file-like
12040 @item @code{ipv6-rules} (default: @code{%iptables-accept-all-rules})
12041 The ip6tables rules to use. It will be passed to @code{ip6tables-restore}.
12042 This may be any ``file-like'' object (@pxref{G-Ausdrücke, file-like
12047 @cindex NTP (Network Time Protocol), service
12048 @cindex real time clock
12049 @defvr {Scheme Variable} ntp-service-type
12050 This is the type of the service running the @uref{http://www.ntp.org,
12051 Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep
12052 the system clock synchronized with that of the specified NTP servers.
12054 The value of this service is an @code{ntpd-configuration} object, as
12058 @deftp {Data Type} ntp-configuration
12059 This is the data type for the NTP service configuration.
12062 @item @code{servers} (default: @code{%ntp-servers})
12063 This is the list of servers (host names) with which @command{ntpd} will be
12066 @item @code{allow-large-adjustment?} (default: @code{#f})
12067 This determines whether @command{ntpd} is allowed to make an initial
12068 adjustment of more than 1,000 seconds.
12070 @item @code{ntp} (default: @code{ntp})
12071 The NTP package to use.
12075 @defvr {Scheme Variable} %ntp-servers
12076 List of host names used as the default NTP servers. These are servers of
12077 the @uref{https://www.ntppool.org/en/, NTP Pool Project}.
12081 @deffn {Scheme Procedure} openntpd-service-type
12082 Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as
12083 implemented by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will
12084 keep the system clock synchronized with that of the given servers.
12088 openntpd-service-type
12089 (openntpd-configuration
12090 (listen-on '("127.0.0.1" "::1"))
12091 (sensor '("udcf0 correction 70000"))
12092 (constraint-from '("www.gnu.org"))
12093 (constraints-from '("https://www.google.com/"))
12094 (allow-large-adjustment? #t)))
12099 @deftp {Data Type} openntpd-configuration
12101 @item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")})
12102 The openntpd executable to use.
12103 @item @code{listen-on} (default: @code{'("127.0.0.1" "::1")})
12104 A list of local IP addresses or hostnames the ntpd daemon should listen on.
12105 @item @code{query-from} (default: @code{'()})
12106 A list of local IP address the ntpd daemon should use for outgoing queries.
12107 @item @code{sensor} (default: @code{'()})
12108 Specify a list of timedelta sensor devices ntpd should use. @code{ntpd}
12109 will listen to each sensor that acutally exists and ignore non-existant
12110 ones. See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation}
12111 for more information.
12112 @item @code{server} (default: @var{%ntp-servers})
12113 Specify a list of IP addresses or hostnames of NTP servers to synchronize
12115 @item @code{servers} (default: @code{'()})
12116 Specify a list of IP addresses or hostnames of NTP pools to synchronize to.
12117 @item @code{constraint-from} (default: @code{'()})
12118 @code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS servers
12119 via TLS. This time information is not used for precision but acts as an
12120 authenticated constraint, thereby reducing the impact of unauthenticated NTP
12121 man-in-the-middle attacks. Specify a list of URLs, IP addresses or
12122 hostnames of HTTPS servers to provide a constraint.
12123 @item @code{constraints-from} (default: @code{'()})
12124 As with constraint from, specify a list of URLs, IP addresses or hostnames
12125 of HTTPS servers to provide a constraint. Should the hostname resolve to
12126 multiple IP addresses, @code{ntpd} will calculate a median constraint from
12128 @item @code{allow-large-adjustment?} (default: @code{#f})
12129 Determines if @code{ntpd} is allowed to make an initial adjustment of more
12135 @deffn {Scheme variable} inetd-service-type
12136 This service runs the @command{inetd} (@pxref{inetd invocation,,, inetutils,
12137 GNU Inetutils}) daemon. @command{inetd} listens for connections on internet
12138 sockets, and lazily starts the specified server program when a connection is
12139 made on one of these sockets.
12141 The value of this service is an @code{inetd-configuration} object. The
12142 following example configures the @command{inetd} daemon to provide the
12143 built-in @command{echo} service, as well as an smtp service which forwards
12144 smtp traffic over ssh to a server @code{smtp-server} behind a gateway
12150 (inetd-configuration
12154 (socket-type 'stream)
12161 (socket-type 'stream)
12165 (program (file-append openssh "/bin/ssh"))
12167 '("ssh" "-qT" "-i" "/path/to/ssh_key"
12168 "-W" "smtp-server:25" "user@@hostname")))))
12171 See below for more details about @code{inetd-configuration}.
12174 @deftp {Data Type} inetd-configuration
12175 Data type representing the configuration of @command{inetd}.
12178 @item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")})
12179 The @command{inetd} executable to use.
12181 @item @code{entries} (default: @code{'()})
12182 A list of @command{inetd} service entries. Each entry should be created by
12183 the @code{inetd-entry} constructor.
12187 @deftp {Data Type} inetd-entry
12188 Data type representing an entry in the @command{inetd} configuration. Each
12189 entry corresponds to a socket where @command{inetd} will listen for
12193 @item @code{node} (Vorgabe: @code{#f})
12194 Optional string, a comma-separated list of local addresses @command{inetd}
12195 should use when listening for this service. @xref{Configuration file,,,
12196 inetutils, GNU Inetutils} for a complete description of all options.
12198 A string, the name must correspond to an entry in @code{/etc/services}.
12199 @item @code{socket-type}
12200 One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or
12202 @item @code{protocol}
12203 A string, must correspond to an entry in @code{/etc/protocols}.
12204 @item @code{wait?} (Vorgabe: @code{#t})
12205 Whether @command{inetd} should wait for the server to exit before listening
12206 to new service requests.
12208 A string containing the user (and, optionally, group) name of the user as
12209 whom the server should run. The group name can be specified in a suffix,
12210 separated by a colon or period, i.e.@: @code{"user"}, @code{"user:group"} or
12211 @code{"user.group"}.
12212 @item @code{program} (default: @code{"internal"})
12213 The server program which will serve the requests, or @code{"internal"} if
12214 @command{inetd} should use a built-in service.
12215 @item @code{arguments} (default: @code{'()})
12216 A list strings or file-like objects, which are the server program's
12217 arguments, starting with the zeroth argument, i.e.@: the name of the program
12218 itself. For @command{inetd}'s internal services, this entry must be
12219 @code{'()} or @code{'("internal")}.
12222 @xref{Configuration file,,, inetutils, GNU Inetutils} for a more detailed
12223 discussion of each configuration field.
12227 @defvr {Scheme Variable} tor-service-type
12228 This is the type for a service that runs the @uref{https://torproject.org,
12229 Tor} anonymous networking daemon. The service is configured using a
12230 @code{<tor-configuration>} record. By default, the Tor daemon runs as the
12231 @code{tor} unprivileged user, which is a member of the @code{tor} group.
12235 @deffn {Scheme Procedure} tor-service [@var{config-file}] [#:tor @var{tor}]
12236 This procedure is deprecated and will be removed in a future release.
12237 Return a service of the @code{tor-service-type} type. @var{config-file} and
12238 @var{tor} have the same meaning as in @code{<tor-configuration>}.
12241 @deftp {Data Type} tor-configuration
12243 @item @code{tor} (default: @code{tor})
12244 The package that provides the Tor daemon. This package is expected to
12245 provide the daemon at @file{bin/tor} relative to its output directory. The
12246 default package is the @uref{https://www.torproject.org, Tor Project's}
12249 @item @code{config-file} (default: @code{(plain-file "empty" "")})
12250 The configuration file to use. It will be appended to a default
12251 configuration file, and the final configuration file will be passed to
12252 @code{tor} via its @code{-f} option. This may be any ``file-like'' object
12253 (@pxref{G-Ausdrücke, file-like objects}). See @code{man tor} for details
12254 on the configuration file syntax.
12256 @item @code{hidden-services} (default: @code{'()})
12257 The list of @code{<hidden-service>} records to use. For any hidden service
12258 you include in this list, appropriate configuration to enable the hidden
12259 service will be automatically added to the default configuration file. You
12260 may conveniently create @code{<hidden-service>} records using the
12261 @code{tor-hidden-service} procedure described below.
12263 @item @code{socks-socket-type} (default: @code{'tcp})
12264 The default socket type that Tor should use for its SOCKS socket. This must
12265 be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by
12266 default Tor will listen on TCP port 9050 on the loopback interface (i.e.,
12267 localhost). If it is @code{'unix}, then Tor will listen on the UNIX domain
12268 socket @file{/var/run/tor/socks-sock}, which will be made writable by
12269 members of the @code{tor} group.
12271 If you want to customize the SOCKS socket in more detail, leave
12272 @code{socks-socket-type} at its default value of @code{'tcp} and use
12273 @code{config-file} to override the default by providing your own
12274 @code{SocksPort} option.
12278 @cindex hidden service
12279 @deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping}
12280 Define a new Tor @dfn{hidden service} called @var{name} and implementing
12281 @var{mapping}. @var{mapping} is a list of port/host tuples, such as:
12284 '((22 "127.0.0.1:22")
12285 (80 "127.0.0.1:8080"))
12288 In this example, port 22 of the hidden service is mapped to local port 22,
12289 and port 80 is mapped to local port 8080.
12291 This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory,
12292 where the @file{hostname} file contains the @code{.onion} host name for the
12295 See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the
12296 Tor project's documentation} for more information.
12299 The @code{(gnu services rsync)} module provides the following services:
12301 You might want an rsync daemon if you have files that you want available so
12302 anyone (or just yourself) can download existing files or upload new files.
12304 @deffn {Scheme Variable} rsync-service-type
12305 This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon,
12306 @command{rsync-configuration} record as in this example:
12309 (service rsync-service-type)
12312 See below for details about @code{rsync-configuration}.
12315 @deftp {Data Type} rsync-configuration
12316 Data type representing the configuration for @code{rsync-service}.
12319 @item @code{package} (default: @var{rsync})
12320 @code{rsync} package to use.
12322 @item @code{port-number} (default: @code{873})
12323 TCP port on which @command{rsync} listens for incoming connections. If port
12324 is less than @code{1024} @command{rsync} needs to be started as the
12325 @code{root} user and group.
12327 @item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"})
12328 Name of the file where @command{rsync} writes its PID.
12330 @item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"})
12331 Name of the file where @command{rsync} writes its lock file.
12333 @item @code{log-file} (default: @code{"/var/log/rsyncd.log"})
12334 Name of the file where @command{rsync} writes its log file.
12336 @item @code{use-chroot?} (default: @var{#t})
12337 Whether to use chroot for @command{rsync} shared directory.
12339 @item @code{share-path} (default: @file{/srv/rsync})
12340 Location of the @command{rsync} shared directory.
12342 @item @code{share-comment} (default: @code{"Rsync share"})
12343 Comment of the @command{rsync} shared directory.
12345 @item @code{read-only?} (default: @var{#f})
12346 Read-write permissions to shared directory.
12348 @item @code{timeout} (default: @code{300})
12349 I/O timeout in seconds.
12351 @item @code{user} (default: @var{"root"})
12352 Owner of the @code{rsync} process.
12354 @item @code{group} (default: @var{"root"})
12355 Group of the @code{rsync} process.
12357 @item @code{uid} (default: @var{"rsyncd"})
12358 User name or user ID that file transfers to and from that module should take
12359 place as when the daemon was run as @code{root}.
12361 @item @code{gid} (default: @var{"rsyncd"})
12362 Group name or group ID that will be used when accessing the module.
12367 Furthermore, @code{(gnu services ssh)} provides the following services.
12371 @deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @
12372 [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @
12373 [#:allow-empty-passwords? #f] [#:root-login? #f] @ [#:syslog-output? #t]
12374 [#:x11-forwarding? #t] @ [#:tcp/ip-forwarding? #t]
12375 [#:password-authentication? #t] @ [#:public-key-authentication? #t]
12376 [#:initialize? #t] Run the @command{lshd} program from @var{lsh} to listen
12377 on port @var{port-number}. @var{host-key} must designate a file containing
12378 the host key, and readable only by root.
12380 When @var{daemonic?} is true, @command{lshd} will detach from the
12381 controlling terminal and log its output to syslogd, unless one sets
12382 @var{syslog-output?} to false. Obviously, it also makes lsh-service depend
12383 on existence of syslogd service. When @var{pid-file?} is true,
12384 @command{lshd} writes its PID to the file called @var{pid-file}.
12386 When @var{initialize?} is true, automatically create the seed and host key
12387 upon service activation if they do not exist yet. This may take long and
12388 require interaction.
12390 When @var{initialize?} is false, it is up to the user to initialize the
12391 randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to
12392 create a key pair with the private key stored in file @var{host-key}
12393 (@pxref{lshd basics,,, lsh, LSH Manual}).
12395 When @var{interfaces} is empty, lshd listens for connections on all the
12396 network interfaces; otherwise, @var{interfaces} must be a list of host names
12399 @var{allow-empty-passwords?} specifies whether to accept log-ins with empty
12400 passwords, and @var{root-login?} specifies whether to accept log-ins as
12403 The other options should be self-descriptive.
12408 @deffn {Scheme Variable} openssh-service-type
12409 This is the type for the @uref{http://www.openssh.org, OpenSSH} secure shell
12410 daemon, @command{sshd}. Its value must be an @code{openssh-configuration}
12411 record as in this example:
12414 (service openssh-service-type
12415 (openssh-configuration
12416 (x11-forwarding? #t)
12417 (permit-root-login 'without-password)
12419 `(("alice" ,(local-file "alice.pub"))
12420 ("bob" ,(local-file "bob.pub"))))))
12423 See below for details about @code{openssh-configuration}.
12425 This service can be extended with extra authorized keys, as in this example:
12428 (service-extension openssh-service-type
12429 (const `(("charlie"
12430 ,(local-file "charlie.pub")))))
12434 @deftp {Data Type} openssh-configuration
12435 This is the configuration record for OpenSSH's @command{sshd}.
12438 @item @code{pid-file} (default: @code{"/var/run/sshd.pid"})
12439 Name of the file where @command{sshd} writes its PID.
12441 @item @code{port-number} (default: @code{22})
12442 TCP port on which @command{sshd} listens for incoming connections.
12444 @item @code{permit-root-login} (default: @code{#f})
12445 This field determines whether and when to allow logins as root. If
12446 @code{#f}, root logins are disallowed; if @code{#t}, they are allowed. If
12447 it's the symbol @code{'without-password}, then root logins are permitted but
12448 not with password-based authentication.
12450 @item @code{allow-empty-passwords?} (default: @code{#f})
12451 When true, users with empty passwords may log in. When false, they may not.
12453 @item @code{password-authentication?} (default: @code{#t})
12454 When true, users may log in with their password. When false, they have
12455 other authentication methods.
12457 @item @code{public-key-authentication?} (default: @code{#t})
12458 When true, users may log in using public key authentication. When false,
12459 users have to use other authentication method.
12461 Authorized public keys are stored in @file{~/.ssh/authorized_keys}. This is
12462 used only by protocol version 2.
12464 @item @code{x11-forwarding?} (default: @code{#f})
12465 When true, forwarding of X11 graphical client connections is enabled---in
12466 other words, @command{ssh} options @option{-X} and @option{-Y} will work.
12468 @item @code{allow-agent-forwarding?} (default: @code{#t})
12469 Whether to allow agent forwarding.
12471 @item @code{allow-tcp-forwarding?} (default: @code{#t})
12472 Whether to allow TCP forwarding.
12474 @item @code{gateway-ports?} (default: @code{#f})
12475 Whether to allow gateway ports.
12477 @item @code{challenge-response-authentication?} (default: @code{#f})
12478 Specifies whether challenge response authentication is allowed (e.g.@: via
12481 @item @code{use-pam?} (default: @code{#t})
12482 Enables the Pluggable Authentication Module interface. If set to @code{#t},
12483 this will enable PAM authentication using
12484 @code{challenge-response-authentication?} and
12485 @code{password-authentication?}, in addition to PAM account and session
12486 module processing for all authentication types.
12488 Because PAM challenge response authentication usually serves an equivalent
12489 role to password authentication, you should disable either
12490 @code{challenge-response-authentication?} or
12491 @code{password-authentication?}.
12493 @item @code{print-last-log?} (default: @code{#t})
12494 Specifies whether @command{sshd} should print the date and time of the last
12495 user login when a user logs in interactively.
12497 @item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))})
12498 Configures external subsystems (e.g.@: file transfer daemon).
12500 This is a list of two-element lists, each of which containing the subsystem
12501 name and a command (with optional arguments) to execute upon subsystem
12504 The command @command{internal-sftp} implements an in-process SFTP server.
12505 Alternately, one can specify the @command{sftp-server} command:
12507 (service openssh-service-type
12508 (openssh-configuration
12510 `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))
12513 @item @code{accepted-environment} (default: @code{'()})
12514 List of strings describing which environment variables may be exported.
12516 Each string gets on its own line. See the @code{AcceptEnv} option in
12517 @code{man sshd_config}.
12519 This example allows ssh-clients to export the @code{COLORTERM} variable. It
12520 is set by terminal emulators, which support colors. You can use it in your
12521 shell's ressource file to enable colors for the prompt and commands if this
12525 (service openssh-service-type
12526 (openssh-configuration
12527 (accepted-environment '("COLORTERM"))))
12530 @item @code{authorized-keys} (default: @code{'()})
12531 @cindex authorized keys, SSH
12532 @cindex SSH authorized keys
12533 This is the list of authorized keys. Each element of the list is a user
12534 name followed by one or more file-like objects that represent SSH public
12538 (openssh-configuration
12540 `(("rekado" ,(local-file "rekado.pub"))
12541 ("chris" ,(local-file "chris.pub"))
12542 ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))
12546 registers the specified public keys for user accounts @code{rekado},
12547 @code{chris}, and @code{root}.
12549 Additional authorized keys can be specified @i{via}
12550 @code{service-extension}.
12552 Note that this does @emph{not} interfere with the use of
12553 @file{~/.ssh/authorized_keys}.
12555 @item @code{log-level} (default: @code{'info})
12556 This is a symbol specifying the logging level: @code{quiet}, @code{fatal},
12557 @code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man
12558 page for @file{sshd_config} for the full list of level names.
12563 @deffn {Scheme Procedure} dropbear-service [@var{config}]
12564 Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH
12565 daemon} with the given @var{config}, a @code{<dropbear-configuration>}
12568 For example, to specify a Dropbear service listening on port 1234, add this
12569 call to the operating system's @code{services} field:
12572 (dropbear-service (dropbear-configuration
12573 (port-number 1234)))
12577 @deftp {Data Type} dropbear-configuration
12578 This data type represents the configuration of a Dropbear SSH daemon.
12581 @item @code{dropbear} (default: @var{dropbear})
12582 The Dropbear package to use.
12584 @item @code{port-number} (default: 22)
12585 The TCP port where the daemon waits for incoming connections.
12587 @item @code{syslog-output?} (default: @code{#t})
12588 Whether to enable syslog output.
12590 @item @code{pid-file} (default: @code{"/var/run/dropbear.pid"})
12591 File name of the daemon's PID file.
12593 @item @code{root-login?} (default: @code{#f})
12594 Whether to allow @code{root} logins.
12596 @item @code{allow-empty-passwords?} (default: @code{#f})
12597 Whether to allow empty passwords.
12599 @item @code{password-authentication?} (default: @code{#t})
12600 Whether to enable password-based authentication.
12604 @defvr {Scheme Variable} %facebook-host-aliases
12605 This variable contains a string for use in @file{/etc/hosts} (@pxref{Host
12606 Names,,, libc, The GNU C Library Reference Manual}). Each line contains a
12607 entry that maps a known server name of the Facebook on-line service---e.g.,
12608 @code{www.facebook.com}---to the local host---@code{127.0.0.1} or its IPv6
12609 equivalent, @code{::1}.
12611 This variable is typically used in the @code{hosts-file} field of an
12612 @code{operating-system} declaration (@pxref{„operating-system“-Referenz,
12613 @file{/etc/hosts}}):
12616 (use-modules (gnu) (guix))
12619 (host-name "mymachine")
12622 ;; Create a /etc/hosts file with aliases for "localhost"
12623 ;; and "mymachine", as well as for Facebook servers.
12624 (plain-file "hosts"
12625 (string-append (local-host-aliases host-name)
12626 %facebook-host-aliases))))
12629 This mechanism can prevent programs running locally, such as Web browsers,
12630 from accessing Facebook.
12633 The @code{(gnu services avahi)} provides the following definition.
12635 @deffn {Scheme Procedure} avahi-service [#:avahi @var{avahi}] @
12636 [#:host-name #f] [#:publish? #t] [#:ipv4? #t] @ [#:ipv6? #t] [#:wide-area?
12637 #f] @ [#:domains-to-browse '()] [#:debug? #f] Return a service that runs
12638 @command{avahi-daemon}, a system-wide mDNS/DNS-SD responder that allows for
12639 service discovery and "zero-configuration" host name lookups (see
12640 @uref{http://avahi.org/}), and extends the name service cache daemon (nscd)
12641 so that it can resolve @code{.local} host names using
12642 @uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}.
12643 Additionally, add the @var{avahi} package to the system profile so that
12644 commands such as @command{avahi-browse} are directly usable.
12646 If @var{host-name} is different from @code{#f}, use that as the host name to
12647 publish for this machine; otherwise, use the machine's actual host name.
12649 When @var{publish?} is true, publishing of host names and services is
12650 allowed; in particular, avahi-daemon will publish the machine's host name
12651 and IP address via mDNS on the local network.
12653 When @var{wide-area?} is true, DNS-SD over unicast DNS is enabled.
12655 Boolean values @var{ipv4?} and @var{ipv6?} determine whether to use
12659 @deffn {Scheme Variable} openvswitch-service-type
12660 This is the type of the @uref{http://www.openvswitch.org, Open vSwitch}
12661 service, whose value should be an @code{openvswitch-configuration} object.
12664 @deftp {Data Type} openvswitch-configuration
12665 Data type representing the configuration of Open vSwitch, a multilayer
12666 virtual switch which is designed to enable massive network automation
12667 through programmatic extension.
12670 @item @code{package} (default: @var{openvswitch})
12671 Package object of the Open vSwitch.
12677 @subsubsection X Window
12680 @cindex X Window System
12681 @cindex login manager
12682 Support for the X Window graphical display system---specifically Xorg---is
12683 provided by the @code{(gnu services xorg)} module. Note that there is no
12684 @code{xorg-service} procedure. Instead, the X server is started by the
12685 @dfn{login manager}, by default SLiM.
12687 @cindex window manager
12688 To use X11, you must install at least one @dfn{window manager}---for example
12689 the @code{windowmaker} or @code{openbox} packages---preferably by adding it
12690 to the @code{packages} field of your operating system definition
12691 (@pxref{„operating-system“-Referenz, system-wide packages}).
12693 @defvr {Scheme Variable} slim-service-type
12694 This is the type for the SLiM graphical login manager for X11.
12696 @cindex session types (X11)
12697 @cindex X11 session types
12698 SLiM looks for @dfn{session types} described by the @file{.desktop} files in
12699 @file{/run/current-system/profile/share/xsessions} and allows users to
12700 choose a session from the log-in screen using @kbd{F1}. Packages such as
12701 @code{xfce}, @code{sawfish}, and @code{ratpoison} provide @file{.desktop}
12702 files; adding them to the system-wide set of packages automatically makes
12703 them available at the log-in screen.
12705 In addition, @file{~/.xsession} files are honored. When available,
12706 @file{~/.xsession} must be an executable that starts a window manager and/or
12710 @deftp {Data Type} slim-configuration
12711 Data type representing the configuration of @code{slim-service-type}.
12714 @item @code{allow-empty-passwords?} (default: @code{#t})
12715 Whether to allow logins with empty passwords.
12717 @item @code{auto-login?} (default: @code{#f})
12718 @itemx @code{default-user} (default: @code{""})
12719 When @code{auto-login?} is false, SLiM presents a log-in screen.
12721 When @code{auto-login?} is true, SLiM logs in directly as
12722 @code{default-user}.
12724 @item @code{theme} (default: @code{%default-slim-theme})
12725 @itemx @code{theme-name} (default: @code{%default-slim-theme-name})
12726 The graphical theme to use and its name.
12728 @item @code{auto-login-session} (default: @code{#f})
12729 If true, this must be the name of the executable to start as the default
12730 session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}.
12732 If false, a session described by one of the available @file{.desktop} files
12733 in @code{/run/current-system/profile} and @code{~/.guix-profile} will be
12736 @quotation Anmerkung
12737 You must install at least one window manager in the system profile or in
12738 your user profile. Failing to do that, if @code{auto-login-session} is
12739 false, you will be unable to log in.
12742 @item @code{startx} (default: @code{(xorg-start-command)})
12743 The command used to start the X11 graphical server.
12745 @item @code{xauth} (default: @code{xauth})
12746 The XAuth package to use.
12748 @item @code{shepherd} (default: @code{shepherd})
12749 The Shepherd package used when invoking @command{halt} and @command{reboot}.
12751 @item @code{sessreg} (default: @code{sessreg})
12752 The sessreg package used in order to register the session.
12754 @item @code{slim} (default: @code{slim})
12755 The SLiM package to use.
12759 @defvr {Scheme Variable} %default-theme
12760 @defvrx {Scheme Variable} %default-theme-name
12761 The default SLiM theme and its name.
12765 @deftp {Data Type} sddm-configuration
12766 This is the data type representing the sddm service configuration.
12769 @item @code{display-server} (default: "x11")
12770 Select display server to use for the greeter. Valid values are "x11" or
12773 @item @code{numlock} (default: "on")
12774 Valid values are "on", "off" or "none".
12776 @item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")})
12777 Command to run when halting.
12779 @item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")})
12780 Command to run when rebooting.
12782 @item @code{theme} (default "maldives")
12783 Theme to use. Default themes provided by SDDM are "elarun" or "maldives".
12785 @item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes")
12786 Directory to look for themes.
12788 @item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces")
12789 Directory to look for faces.
12791 @item @code{default-path} (default "/run/current-system/profile/bin")
12792 Default PATH to use.
12794 @item @code{minimum-uid} (default 1000)
12795 Minimum UID to display in SDDM.
12797 @item @code{maximum-uid} (default 2000)
12798 Maximum UID to display in SDDM
12800 @item @code{remember-last-user?} (default #t)
12801 Remember last user.
12803 @item @code{remember-last-session?} (default #t)
12804 Remember last session.
12806 @item @code{hide-users} (default "")
12807 Usernames to hide from SDDM greeter.
12809 @item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")})
12810 Users with shells listed will be hidden from the SDDM greeter.
12812 @item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")})
12813 Script to run before starting a wayland session.
12815 @item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions")
12816 Directory to look for desktop files starting wayland sessions.
12818 @item @code{xorg-server-path} (default @code{xorg-start-command})
12819 Path to xorg-server.
12821 @item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")})
12824 @item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")})
12827 @item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")})
12828 Script to run after starting xorg-server.
12830 @item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")})
12831 Script to run before stopping xorg-server.
12833 @item @code{xsession-command} (default: @code{xinitrc})
12834 Script to run before starting a X session.
12836 @item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions")
12837 Directory to look for desktop files starting X sessions.
12839 @item @code{minimum-vt} (default: 7)
12842 @item @code{xserver-arguments} (default "-nolisten tcp")
12843 Arguments to pass to xorg-server.
12845 @item @code{auto-login-user} (default "")
12846 User to use for auto-login.
12848 @item @code{auto-login-session} (default "")
12849 Desktop file to use for auto-login.
12851 @item @code{relogin?} (default #f)
12852 Relogin after logout.
12857 @cindex login manager
12859 @deffn {Scheme Procedure} sddm-service config
12860 Return a service that spawns the SDDM graphical login manager for config of
12861 type @code{<sddm-configuration>}.
12864 (sddm-service (sddm-configuration
12865 (auto-login-user "Alice")
12866 (auto-login-session "xfce.desktop")))
12870 @deffn {Scheme Procedure} xorg-start-command [#:guile] @
12871 [#:modules %default-xorg-modules] @ [#:fonts %default-xorg-fonts] @
12872 [#:configuration-file (xorg-configuration-file @dots{})] @ [#:xorg-server
12873 @var{xorg-server}] Return a @code{startx} script in which @var{modules}, a
12874 list of X module packages, and @var{fonts}, a list of X font directories,
12875 are available. See @code{xorg-wrapper} for more details on the arguments.
12876 The result should be used in place of @code{startx}.
12878 Usually the X server is started by a login manager.
12881 @deffn {Scheme Procedure} xorg-configuration-file @
12882 [#:modules %default-xorg-modules] @ [#:fonts %default-xorg-fonts] @
12883 [#:drivers '()] [#:resolutions '()] [#:extra-config '()] Return a
12884 configuration file for the Xorg server containing search paths for all the
12887 @var{modules} must be a list of @dfn{module packages} loaded by the Xorg
12888 server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so
12889 on. @var{fonts} must be a list of font directories to add to the server's
12892 @var{drivers} must be either the empty list, in which case Xorg chooses a
12893 graphics driver automatically, or a list of driver names that will be tried
12894 in this order---e.g., @code{("modesetting" "vesa")}.
12896 Likewise, when @var{resolutions} is the empty list, Xorg chooses an
12897 appropriate screen resolution; otherwise, it must be a list of
12898 resolutions---e.g., @code{((1024 768) (640 480))}.
12900 Last, @var{extra-config} is a list of strings or objects appended to the
12901 configuration file. It is used to pass extra text to be added verbatim to
12902 the configuration file.
12905 @cindex keyboard layout
12906 This procedure is especially useful to configure a different keyboard layout
12907 than the default US keymap. For instance, to use the ``bépo'' keymap by
12908 default on the display manager:
12912 "Section \"InputClass\"
12913 Identifier \"evdev keyboard catchall\"
12915 MatchIsKeyboard \"on\"
12916 Option \"xkb_layout\" \"fr\"
12917 Option \"xkb_variant\" \"bepo\"
12923 (modify-services %desktop-services
12924 (slim-service-type config =>
12925 (slim-configuration
12927 (startx (xorg-start-command
12928 #:configuration-file
12929 (xorg-configuration-file
12931 (list bepo-evdev)))))))))
12934 The @code{MatchIsKeyboard} line specifies that we only apply the
12935 configuration to keyboards. Without this line, other devices such as
12936 touchpad may not work correctly because they will be attached to the wrong
12937 driver. In this example, the user typically used @code{setxkbmap fr bepo}
12938 to set their favorite keymap once logged in. The first argument corresponds
12939 to the layout, while the second argument corresponds to the variant. The
12940 @code{xkb_variant} line can be omitted to select the default variant.
12943 @deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}]
12944 Add @var{package}, a package for a screen locker or screen saver whose
12945 command is @var{program}, to the set of setuid programs and add a PAM entry
12946 for it. For example:
12949 (screen-locker-service xlockmore "xlock")
12952 makes the good ol' XlockMore usable.
12957 @subsubsection Druckdienste
12959 @cindex printer support with CUPS
12960 The @code{(gnu services cups)} module provides a Guix service definition for
12961 the CUPS printing service. To add printer support to a GuixSD system, add a
12962 @code{cups-service} to the operating system definition:
12964 @deffn {Scheme Variable} cups-service-type
12965 The service type for the CUPS print server. Its value should be a valid
12966 CUPS configuration (see below). To use the default settings, simply write:
12968 (service cups-service-type)
12972 The CUPS configuration controls the basic things about your CUPS
12973 installation: what interfaces it listens on, what to do if a print job
12974 fails, how much logging to do, and so on. To actually add a printer, you
12975 have to visit the @url{http://localhost:631} URL, or use a tool such as
12976 GNOME's printer configuration services. By default, configuring a CUPS
12977 service will generate a self-signed certificate if needed, for secure
12978 connections to the print server.
12980 Suppose you want to enable the Web interface of CUPS and also add support
12981 for Epson printers @i{via} the @code{escpr} package and for HP printers
12982 @i{via} the @code{hplip-minimal} package. You can do that directly, like
12983 this (you need to use the @code{(gnu packages cups)} module):
12986 (service cups-service-type
12987 (cups-configuration
12988 (web-interface? #t)
12990 (list cups-filters escpr hplip-minimal))))
12993 Note: If you wish to use the Qt5 based GUI which comes with the hplip
12994 package then it is suggested that you install the @code{hplip} package,
12995 either in your OS configuration file or as your user.
12997 The available configuration parameters follow. Each parameter definition is
12998 preceded by its type; for example, @samp{string-list foo} indicates that the
12999 @code{foo} parameter should be specified as a list of strings. There is
13000 also a way to specify the configuration as a string, if you have an old
13001 @code{cupsd.conf} file that you want to port over from some other system;
13002 see the end for more details.
13004 @c The following documentation was initially generated by
13005 @c (generate-documentation) in (gnu services cups). Manually maintained
13006 @c documentation is better, so we shouldn't hesitate to edit below as
13007 @c needed. However if the change you want to make to this documentation
13008 @c can be done in an automated way, it's probably easier to change
13009 @c (generate-documentation) than to make it below and have to deal with
13010 @c the churn as CUPS updates.
13013 Available @code{cups-configuration} fields are:
13015 @deftypevr {@code{cups-configuration} parameter} package cups
13019 @deftypevr {@code{cups-configuration} parameter} package-list extensions
13020 Drivers and other extensions to the CUPS package.
13023 @deftypevr {@code{cups-configuration} parameter} files-configuration files-configuration
13024 Configuration of where to write logs, what directories to use for print
13025 spools, and related privileged configuration parameters.
13027 Available @code{files-configuration} fields are:
13029 @deftypevr {@code{files-configuration} parameter} log-location access-log
13030 Defines the access log filename. Specifying a blank filename disables
13031 access log generation. The value @code{stderr} causes log entries to be
13032 sent to the standard error file when the scheduler is running in the
13033 foreground, or to the system log daemon when run in the background. The
13034 value @code{syslog} causes log entries to be sent to the system log daemon.
13035 The server name may be included in filenames using the string @code{%s}, as
13036 in @code{/var/log/cups/%s-access_log}.
13038 Defaults to @samp{"/var/log/cups/access_log"}.
13041 @deftypevr {@code{files-configuration} parameter} file-name cache-dir
13042 Where CUPS should cache data.
13044 Defaults to @samp{"/var/cache/cups"}.
13047 @deftypevr {@code{files-configuration} parameter} string config-file-perm
13048 Specifies the permissions for all configuration files that the scheduler
13051 Note that the permissions for the printers.conf file are currently masked to
13052 only allow access from the scheduler user (typically root). This is done
13053 because printer device URIs sometimes contain sensitive authentication
13054 information that should not be generally known on the system. There is no
13055 way to disable this security feature.
13057 Defaults to @samp{"0640"}.
13060 @deftypevr {@code{files-configuration} parameter} log-location error-log
13061 Defines the error log filename. Specifying a blank filename disables access
13062 log generation. The value @code{stderr} causes log entries to be sent to
13063 the standard error file when the scheduler is running in the foreground, or
13064 to the system log daemon when run in the background. The value
13065 @code{syslog} causes log entries to be sent to the system log daemon. The
13066 server name may be included in filenames using the string @code{%s}, as in
13067 @code{/var/log/cups/%s-error_log}.
13069 Defaults to @samp{"/var/log/cups/error_log"}.
13072 @deftypevr {@code{files-configuration} parameter} string fatal-errors
13073 Specifies which errors are fatal, causing the scheduler to exit. The kind
13078 No errors are fatal.
13081 All of the errors below are fatal.
13084 Browsing initialization errors are fatal, for example failed connections to
13088 Configuration file syntax errors are fatal.
13091 Listen or Port errors are fatal, except for IPv6 failures on the loopback or
13092 @code{any} addresses.
13095 Log file creation or write errors are fatal.
13098 Bad startup file permissions are fatal, for example shared TLS certificate
13099 and key files with world-read permissions.
13102 Defaults to @samp{"all -browse"}.
13105 @deftypevr {@code{files-configuration} parameter} boolean file-device?
13106 Specifies whether the file pseudo-device can be used for new printer
13107 queues. The URI @uref{file:///dev/null} is always allowed.
13109 Defaults to @samp{#f}.
13112 @deftypevr {@code{files-configuration} parameter} string group
13113 Specifies the group name or ID that will be used when executing external
13116 Defaults to @samp{"lp"}.
13119 @deftypevr {@code{files-configuration} parameter} string log-file-perm
13120 Specifies the permissions for all log files that the scheduler writes.
13122 Defaults to @samp{"0644"}.
13125 @deftypevr {@code{files-configuration} parameter} log-location page-log
13126 Defines the page log filename. Specifying a blank filename disables access
13127 log generation. The value @code{stderr} causes log entries to be sent to
13128 the standard error file when the scheduler is running in the foreground, or
13129 to the system log daemon when run in the background. The value
13130 @code{syslog} causes log entries to be sent to the system log daemon. The
13131 server name may be included in filenames using the string @code{%s}, as in
13132 @code{/var/log/cups/%s-page_log}.
13134 Defaults to @samp{"/var/log/cups/page_log"}.
13137 @deftypevr {@code{files-configuration} parameter} string remote-root
13138 Specifies the username that is associated with unauthenticated accesses by
13139 clients claiming to be the root user. The default is @code{remroot}.
13141 Defaults to @samp{"remroot"}.
13144 @deftypevr {@code{files-configuration} parameter} file-name request-root
13145 Specifies the directory that contains print jobs and other HTTP request
13148 Defaults to @samp{"/var/spool/cups"}.
13151 @deftypevr {@code{files-configuration} parameter} sandboxing sandboxing
13152 Specifies the level of security sandboxing that is applied to print filters,
13153 backends, and other child processes of the scheduler; either @code{relaxed}
13154 or @code{strict}. This directive is currently only used/supported on macOS.
13156 Defaults to @samp{strict}.
13159 @deftypevr {@code{files-configuration} parameter} file-name server-keychain
13160 Specifies the location of TLS certificates and private keys. CUPS will look
13161 for public and private keys in this directory: a @code{.crt} files for
13162 PEM-encoded certificates and corresponding @code{.key} files for PEM-encoded
13165 Defaults to @samp{"/etc/cups/ssl"}.
13168 @deftypevr {@code{files-configuration} parameter} file-name server-root
13169 Specifies the directory containing the server configuration files.
13171 Defaults to @samp{"/etc/cups"}.
13174 @deftypevr {@code{files-configuration} parameter} boolean sync-on-close?
13175 Specifies whether the scheduler calls fsync(2) after writing configuration
13178 Defaults to @samp{#f}.
13181 @deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group
13182 Specifies the group(s) to use for @code{@@SYSTEM} group authentication.
13185 @deftypevr {@code{files-configuration} parameter} file-name temp-dir
13186 Specifies the directory where temporary files are stored.
13188 Defaults to @samp{"/var/spool/cups/tmp"}.
13191 @deftypevr {@code{files-configuration} parameter} string user
13192 Specifies the user name or ID that is used when running external programs.
13194 Defaults to @samp{"lp"}.
13198 @deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level
13199 Specifies the logging level for the AccessLog file. The @code{config} level
13200 logs when printers and classes are added, deleted, or modified and when
13201 configuration files are accessed or updated. The @code{actions} level logs
13202 when print jobs are submitted, held, released, modified, or canceled, and
13203 any of the conditions for @code{config}. The @code{all} level logs all
13206 Defaults to @samp{actions}.
13209 @deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs?
13210 Specifies whether to purge job history data automatically when it is no
13211 longer required for quotas.
13213 Defaults to @samp{#f}.
13216 @deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols
13217 Specifies which protocols to use for local printer sharing.
13219 Defaults to @samp{dnssd}.
13222 @deftypevr {@code{cups-configuration} parameter} boolean browse-web-if?
13223 Specifies whether the CUPS web interface is advertised.
13225 Defaults to @samp{#f}.
13228 @deftypevr {@code{cups-configuration} parameter} boolean browsing?
13229 Specifies whether shared printers are advertised.
13231 Defaults to @samp{#f}.
13234 @deftypevr {@code{cups-configuration} parameter} string classification
13235 Specifies the security classification of the server. Any valid banner name
13236 can be used, including "classified", "confidential", "secret", "topsecret",
13237 and "unclassified", or the banner can be omitted to disable secure printing
13240 Defaults to @samp{""}.
13243 @deftypevr {@code{cups-configuration} parameter} boolean classify-override?
13244 Specifies whether users may override the classification (cover page) of
13245 individual print jobs using the @code{job-sheets} option.
13247 Defaults to @samp{#f}.
13250 @deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type
13251 Specifies the default type of authentication to use.
13253 Defaults to @samp{Basic}.
13256 @deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption
13257 Specifies whether encryption will be used for authenticated requests.
13259 Defaults to @samp{Required}.
13262 @deftypevr {@code{cups-configuration} parameter} string default-language
13263 Specifies the default language to use for text and web content.
13265 Defaults to @samp{"en"}.
13268 @deftypevr {@code{cups-configuration} parameter} string default-paper-size
13269 Specifies the default paper size for new print queues. @samp{"Auto"} uses a
13270 locale-specific default, while @samp{"None"} specifies there is no default
13271 paper size. Specific size names are typically @samp{"Letter"} or
13274 Defaults to @samp{"Auto"}.
13277 @deftypevr {@code{cups-configuration} parameter} string default-policy
13278 Specifies the default access policy to use.
13280 Defaults to @samp{"default"}.
13283 @deftypevr {@code{cups-configuration} parameter} boolean default-shared?
13284 Specifies whether local printers are shared by default.
13286 Defaults to @samp{#t}.
13289 @deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-interval
13290 Specifies the delay for updating of configuration and state files, in
13291 seconds. A value of 0 causes the update to happen as soon as possible,
13292 typically within a few milliseconds.
13294 Defaults to @samp{30}.
13297 @deftypevr {@code{cups-configuration} parameter} error-policy error-policy
13298 Specifies what to do when an error occurs. Possible values are
13299 @code{abort-job}, which will discard the failed print job; @code{retry-job},
13300 which will retry the job at a later time; @code{retry-this-job}, which
13301 retries the failed job immediately; and @code{stop-printer}, which stops the
13304 Defaults to @samp{stop-printer}.
13307 @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-limit
13308 Specifies the maximum cost of filters that are run concurrently, which can
13309 be used to minimize disk, memory, and CPU resource problems. A limit of 0
13310 disables filter limiting. An average print to a non-PostScript printer
13311 needs a filter limit of about 200. A PostScript printer needs about half
13312 that (100). Setting the limit below these thresholds will effectively limit
13313 the scheduler to printing a single job at any time.
13315 Defaults to @samp{0}.
13318 @deftypevr {@code{cups-configuration} parameter} non-negative-integer filter-nice
13319 Specifies the scheduling priority of filters that are run to print a job.
13320 The nice value ranges from 0, the highest priority, to 19, the lowest
13323 Defaults to @samp{0}.
13326 @deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups
13327 Specifies whether to do reverse lookups on connecting clients. The
13328 @code{double} setting causes @code{cupsd} to verify that the hostname
13329 resolved from the address matches one of the addresses returned for that
13330 hostname. Double lookups also prevent clients with unregistered addresses
13331 from connecting to your server. Only set this option to @code{#t} or
13332 @code{double} if absolutely required.
13334 Defaults to @samp{#f}.
13337 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-kill-delay
13338 Specifies the number of seconds to wait before killing the filters and
13339 backend associated with a canceled or held job.
13341 Defaults to @samp{30}.
13344 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-interval
13345 Specifies the interval between retries of jobs in seconds. This is
13346 typically used for fax queues but can also be used with normal print queues
13347 whose error policy is @code{retry-job} or @code{retry-current-job}.
13349 Defaults to @samp{30}.
13352 @deftypevr {@code{cups-configuration} parameter} non-negative-integer job-retry-limit
13353 Specifies the number of retries that are done for jobs. This is typically
13354 used for fax queues but can also be used with normal print queues whose
13355 error policy is @code{retry-job} or @code{retry-current-job}.
13357 Defaults to @samp{5}.
13360 @deftypevr {@code{cups-configuration} parameter} boolean keep-alive?
13361 Specifies whether to support HTTP keep-alive connections.
13363 Defaults to @samp{#t}.
13366 @deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout
13367 Specifies how long an idle client connection remains open, in seconds.
13369 Defaults to @samp{30}.
13372 @deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body
13373 Specifies the maximum size of print files, IPP requests, and HTML form
13374 data. A limit of 0 disables the limit check.
13376 Defaults to @samp{0}.
13379 @deftypevr {@code{cups-configuration} parameter} multiline-string-list listen
13380 Listens on the specified interfaces for connections. Valid values are of
13381 the form @var{address}:@var{port}, where @var{address} is either an IPv6
13382 address enclosed in brackets, an IPv4 address, or @code{*} to indicate all
13383 addresses. Values can also be file names of local UNIX domain sockets. The
13384 Listen directive is similar to the Port directive but allows you to restrict
13385 access to specific interfaces or networks.
13388 @deftypevr {@code{cups-configuration} parameter} non-negative-integer listen-back-log
13389 Specifies the number of pending connections that will be allowed. This
13390 normally only affects very busy servers that have reached the MaxClients
13391 limit, but can also be triggered by large numbers of simultaneous
13392 connections. When the limit is reached, the operating system will refuse
13393 additional connections until the scheduler can accept the pending ones.
13395 Defaults to @samp{128}.
13398 @deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls
13399 Specifies a set of additional access controls.
13401 Available @code{location-access-controls} fields are:
13403 @deftypevr {@code{location-access-controls} parameter} file-name path
13404 Specifies the URI path to which the access control applies.
13407 @deftypevr {@code{location-access-controls} parameter} access-control-list access-controls
13408 Access controls for all access to this path, in the same format as the
13409 @code{access-controls} of @code{operation-access-control}.
13411 Defaults to @samp{()}.
13414 @deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls
13415 Access controls for method-specific access to this path.
13417 Defaults to @samp{()}.
13419 Available @code{method-access-controls} fields are:
13421 @deftypevr {@code{method-access-controls} parameter} boolean reverse?
13422 If @code{#t}, apply access controls to all methods except the listed
13423 methods. Otherwise apply to only the listed methods.
13425 Defaults to @samp{#f}.
13428 @deftypevr {@code{method-access-controls} parameter} method-list methods
13429 Methods to which this access control applies.
13431 Defaults to @samp{()}.
13434 @deftypevr {@code{method-access-controls} parameter} access-control-list access-controls
13435 Access control directives, as a list of strings. Each string should be one
13436 directive, such as "Order allow,deny".
13438 Defaults to @samp{()}.
13443 @deftypevr {@code{cups-configuration} parameter} non-negative-integer log-debug-history
13444 Specifies the number of debugging messages that are retained for logging if
13445 an error occurs in a print job. Debug messages are logged regardless of the
13448 Defaults to @samp{100}.
13451 @deftypevr {@code{cups-configuration} parameter} log-level log-level
13452 Specifies the level of logging for the ErrorLog file. The value @code{none}
13453 stops all logging while @code{debug2} logs everything.
13455 Defaults to @samp{info}.
13458 @deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format
13459 Specifies the format of the date and time in the log files. The value
13460 @code{standard} logs whole seconds while @code{usecs} logs microseconds.
13462 Defaults to @samp{standard}.
13465 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients
13466 Specifies the maximum number of simultaneous clients that are allowed by the
13469 Defaults to @samp{100}.
13472 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients-per-host
13473 Specifies the maximum number of simultaneous clients that are allowed from a
13476 Defaults to @samp{100}.
13479 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies
13480 Specifies the maximum number of copies that a user can print of each job.
13482 Defaults to @samp{9999}.
13485 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time
13486 Specifies the maximum time a job may remain in the @code{indefinite} hold
13487 state before it is canceled. A value of 0 disables cancellation of held
13490 Defaults to @samp{0}.
13493 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs
13494 Specifies the maximum number of simultaneous jobs that are allowed. Set to
13495 0 to allow an unlimited number of jobs.
13497 Defaults to @samp{500}.
13500 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-printer
13501 Specifies the maximum number of simultaneous jobs that are allowed per
13502 printer. A value of 0 allows up to MaxJobs jobs per printer.
13504 Defaults to @samp{0}.
13507 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-jobs-per-user
13508 Specifies the maximum number of simultaneous jobs that are allowed per
13509 user. A value of 0 allows up to MaxJobs jobs per user.
13511 Defaults to @samp{0}.
13514 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-job-time
13515 Specifies the maximum time a job may take to print before it is canceled, in
13516 seconds. Set to 0 to disable cancellation of "stuck" jobs.
13518 Defaults to @samp{10800}.
13521 @deftypevr {@code{cups-configuration} parameter} non-negative-integer max-log-size
13522 Specifies the maximum size of the log files before they are rotated, in
13523 bytes. The value 0 disables log rotation.
13525 Defaults to @samp{1048576}.
13528 @deftypevr {@code{cups-configuration} parameter} non-negative-integer multiple-operation-timeout
13529 Specifies the maximum amount of time to allow between files in a multiple
13530 file print job, in seconds.
13532 Defaults to @samp{300}.
13535 @deftypevr {@code{cups-configuration} parameter} string page-log-format
13536 Specifies the format of PageLog lines. Sequences beginning with percent
13537 (@samp{%}) characters are replaced with the corresponding information, while
13538 all other characters are copied literally. The following percent sequences
13543 insert a single percent character
13546 insert the value of the specified IPP attribute
13549 insert the number of copies for the current page
13552 insert the current page number
13555 insert the current date and time in common log format
13561 insert the printer name
13564 insert the username
13567 A value of the empty string disables page logging. The string @code{%p %u
13568 %j %T %P %C %@{job-billing@} %@{job-originating-host-name@} %@{job-name@}
13569 %@{media@} %@{sides@}} creates a page log with the standard items.
13571 Defaults to @samp{""}.
13574 @deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables
13575 Passes the specified environment variable(s) to child processes; a list of
13578 Defaults to @samp{()}.
13581 @deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies
13582 Specifies named access control policies.
13584 Available @code{policy-configuration} fields are:
13586 @deftypevr {@code{policy-configuration} parameter} string name
13587 Name of the policy.
13590 @deftypevr {@code{policy-configuration} parameter} string job-private-access
13591 Specifies an access list for a job's private values. @code{@@ACL} maps to
13592 the printer's requesting-user-name-allowed or requesting-user-name-denied
13593 values. @code{@@OWNER} maps to the job's owner. @code{@@SYSTEM} maps to
13594 the groups listed for the @code{system-group} field of the
13595 @code{files-config} configuration, which is reified into the
13596 @code{cups-files.conf(5)} file. Other possible elements of the access list
13597 include specific user names, and @code{@@@var{group}} to indicate members of
13598 a specific group. The access list may also be simply @code{all} or
13601 Defaults to @samp{"@@OWNER @@SYSTEM"}.
13604 @deftypevr {@code{policy-configuration} parameter} string job-private-values
13605 Specifies the list of job values to make private, or @code{all},
13606 @code{default}, or @code{none}.
13608 Defaults to @samp{"job-name job-originating-host-name
13609 job-originating-user-name phone"}.
13612 @deftypevr {@code{policy-configuration} parameter} string subscription-private-access
13613 Specifies an access list for a subscription's private values. @code{@@ACL}
13614 maps to the printer's requesting-user-name-allowed or
13615 requesting-user-name-denied values. @code{@@OWNER} maps to the job's
13616 owner. @code{@@SYSTEM} maps to the groups listed for the
13617 @code{system-group} field of the @code{files-config} configuration, which is
13618 reified into the @code{cups-files.conf(5)} file. Other possible elements of
13619 the access list include specific user names, and @code{@@@var{group}} to
13620 indicate members of a specific group. The access list may also be simply
13621 @code{all} or @code{default}.
13623 Defaults to @samp{"@@OWNER @@SYSTEM"}.
13626 @deftypevr {@code{policy-configuration} parameter} string subscription-private-values
13627 Specifies the list of job values to make private, or @code{all},
13628 @code{default}, or @code{none}.
13630 Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri
13631 notify-subscriber-user-name notify-user-data"}.
13634 @deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls
13635 Access control by IPP operation.
13637 Defaults to @samp{()}.
13641 @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-files
13642 Specifies whether job files (documents) are preserved after a job is
13643 printed. If a numeric value is specified, job files are preserved for the
13644 indicated number of seconds after printing. Otherwise a boolean value
13645 applies indefinitely.
13647 Defaults to @samp{86400}.
13650 @deftypevr {@code{cups-configuration} parameter} boolean-or-non-negative-integer preserve-job-history
13651 Specifies whether the job history is preserved after a job is printed. If a
13652 numeric value is specified, the job history is preserved for the indicated
13653 number of seconds after printing. If @code{#t}, the job history is
13654 preserved until the MaxJobs limit is reached.
13656 Defaults to @samp{#t}.
13659 @deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout
13660 Specifies the amount of time to wait for job completion before restarting
13663 Defaults to @samp{30}.
13666 @deftypevr {@code{cups-configuration} parameter} string rip-cache
13667 Specifies the maximum amount of memory to use when converting documents into
13668 bitmaps for a printer.
13670 Defaults to @samp{"128m"}.
13673 @deftypevr {@code{cups-configuration} parameter} string server-admin
13674 Specifies the email address of the server administrator.
13676 Defaults to @samp{"root@@localhost.localdomain"}.
13679 @deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias
13680 The ServerAlias directive is used for HTTP Host header validation when
13681 clients connect to the scheduler from external interfaces. Using the
13682 special name @code{*} can expose your system to known browser-based DNS
13683 rebinding attacks, even when accessing sites through a firewall. If the
13684 auto-discovery of alternate names does not work, we recommend listing each
13685 alternate name with a ServerAlias directive instead of using @code{*}.
13687 Defaults to @samp{*}.
13690 @deftypevr {@code{cups-configuration} parameter} string server-name
13691 Specifies the fully-qualified host name of the server.
13693 Defaults to @samp{"localhost"}.
13696 @deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens
13697 Specifies what information is included in the Server header of HTTP
13698 responses. @code{None} disables the Server header. @code{ProductOnly}
13699 reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor}
13700 reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}.
13701 @code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is the
13702 output of the @code{uname} command. @code{Full} reports @code{CUPS 2.0.0
13703 (@var{uname}) IPP/2.0}.
13705 Defaults to @samp{Minimal}.
13708 @deftypevr {@code{cups-configuration} parameter} string set-env
13709 Set the specified environment variable to be passed to child processes.
13711 Defaults to @samp{"variable value"}.
13714 @deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen
13715 Listens on the specified interfaces for encrypted connections. Valid values
13716 are of the form @var{address}:@var{port}, where @var{address} is either an
13717 IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to indicate
13720 Defaults to @samp{()}.
13723 @deftypevr {@code{cups-configuration} parameter} ssl-options ssl-options
13724 Sets encryption options. By default, CUPS only supports encryption using
13725 TLS v1.0 or higher using known secure cipher suites. The @code{AllowRC4}
13726 option enables the 128-bit RC4 cipher suites, which are required for some
13727 older clients that do not implement newer ones. The @code{AllowSSL3} option
13728 enables SSL v3.0, which is required for some older clients that do not
13731 Defaults to @samp{()}.
13734 @deftypevr {@code{cups-configuration} parameter} boolean strict-conformance?
13735 Specifies whether the scheduler requires clients to strictly adhere to the
13736 IPP specifications.
13738 Defaults to @samp{#f}.
13741 @deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout
13742 Specifies the HTTP request timeout, in seconds.
13744 Defaults to @samp{300}.
13748 @deftypevr {@code{cups-configuration} parameter} boolean web-interface?
13749 Specifies whether the web interface is enabled.
13751 Defaults to @samp{#f}.
13754 At this point you're probably thinking ``oh dear, Guix manual, I like you
13755 but you can stop already with the configuration options''. Indeed.
13756 However, one more point: it could be that you have an existing
13757 @code{cupsd.conf} that you want to use. In that case, you can pass an
13758 @code{opaque-cups-configuration} as the configuration of a
13759 @code{cups-service-type}.
13761 Available @code{opaque-cups-configuration} fields are:
13763 @deftypevr {@code{opaque-cups-configuration} parameter} package cups
13767 @deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf
13768 The contents of the @code{cupsd.conf}, as a string.
13771 @deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf
13772 The contents of the @code{cups-files.conf} file, as a string.
13775 For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in
13776 strings of the same name, you could instantiate a CUPS service like this:
13779 (service cups-service-type
13780 (opaque-cups-configuration
13781 (cupsd.conf cupsd.conf)
13782 (cups-files.conf cups-files.conf)))
13786 @node Desktop-Dienste
13787 @subsubsection Desktop-Dienste
13789 The @code{(gnu services desktop)} module provides services that are usually
13790 useful in the context of a ``desktop'' setup---that is, on a machine running
13791 a graphical display server, possibly with graphical user interfaces, etc.
13792 It also defines services that provide specific desktop environments like
13793 GNOME, XFCE or MATE.
13795 To simplify things, the module defines a variable containing the set of
13796 services that users typically expect on a machine with a graphical
13797 environment and networking:
13799 @defvr {Scheme Variable} %desktop-services
13800 This is a list of services that builds upon @var{%base-services} and adds or
13801 adjusts services for a typical ``desktop'' setup.
13803 In particular, it adds a graphical login manager (@pxref{X Window,
13804 @code{slim-service}}), screen lockers, a network management tool
13805 (@pxref{Netzwerkdienste, @code{network-manager-service-type}}), energy
13806 and color management services, the @code{elogind} login and seat manager,
13807 the Polkit privilege service, the GeoClue location service, the
13808 AccountsService daemon that allows authorized users change system passwords,
13809 an NTP client (@pxref{Netzwerkdienste}), the Avahi daemon, and has the
13810 name service switch service configured to be able to use @code{nss-mdns}
13811 (@pxref{Name Service Switch, mDNS}).
13814 The @var{%desktop-services} variable can be used as the @code{services}
13815 field of an @code{operating-system} declaration (@pxref{„operating-system“-Referenz, @code{services}}).
13817 Additionally, the @code{gnome-desktop-service}, @code{xfce-desktop-service},
13818 @code{mate-desktop-service} and @code{enlightenment-desktop-service-type}
13819 procedures can add GNOME, XFCE, MATE and/or Enlightenment to a system. To
13820 ``add GNOME'' means that system-level services like the backlight adjustment
13821 helpers and the power management utilities are added to the system,
13822 extending @code{polkit} and @code{dbus} appropriately, allowing GNOME to
13823 operate with elevated privileges on a limited number of special-purpose
13824 system interfaces. Additionally, adding a service made by
13825 @code{gnome-desktop-service} adds the GNOME metapackage to the system
13826 profile. Likewise, adding the XFCE service not only adds the @code{xfce}
13827 metapackage to the system profile, but it also gives the Thunar file manager
13828 the ability to open a ``root-mode'' file management window, if the user
13829 authenticates using the administrator's password via the standard polkit
13830 graphical interface. To ``add MATE'' means that @code{polkit} and
13831 @code{dbus} are extended appropriately, allowing MATE to operate with
13832 elevated privileges on a limited number of special-purpose system
13833 interfaces. Additionally, adding a service made by
13834 @code{mate-desktop-service} adds the MATE metapackage to the system
13835 profile. ``Adding ENLIGHTENMENT'' means that @code{dbus} is extended
13836 appropriately, and several of Enlightenment's binaries are set as setuid,
13837 allowing Enlightenment's screen locker and other functionality to work as
13840 The desktop environments in Guix use the Xorg display server by default. If
13841 you'd like to use the newer display server protocol called Wayland, you need
13842 to use the @code{sddm-service} instead of the @code{slim-service} for the
13843 graphical login manager. You should then select the ``GNOME (Wayland)''
13844 session in SDDM. Alternatively you can also try starting GNOME on Wayland
13845 manually from a TTY with the command ``XDG_SESSION_TYPE=wayland exec
13846 dbus-run-session gnome-session``. Currently only GNOME has support for
13849 @deffn {Scheme Procedure} gnome-desktop-service
13850 Return a service that adds the @code{gnome} package to the system profile,
13851 and extends polkit with the actions from @code{gnome-settings-daemon}.
13854 @deffn {Scheme Procedure} xfce-desktop-service
13855 Return a service that adds the @code{xfce} package to the system profile,
13856 and extends polkit with the ability for @code{thunar} to manipulate the file
13857 system as root from within a user session, after the user has authenticated
13858 with the administrator's password.
13861 @deffn {Scheme Procedure} mate-desktop-service
13862 Return a service that adds the @code{mate} package to the system profile,
13863 and extends polkit with the actions from @code{mate-settings-daemon}.
13866 @deffn {Scheme Procedure} enlightenment-desktop-service-type
13867 Return a service that adds the @code{enlightenment} package to the system
13868 profile, and extends dbus with actions from @code{efl}.
13871 @deftp {Data Type} enlightenment-desktop-service-configuration
13873 @item @code{enlightenment} (default @code{enlightenment})
13874 The enlightenment package to use.
13878 Because the GNOME, XFCE and MATE desktop services pull in so many packages,
13879 the default @code{%desktop-services} variable doesn't include any of them by
13880 default. To add GNOME, XFCE or MATE, just @code{cons} them onto
13881 @code{%desktop-services} in the @code{services} field of your
13882 @code{operating-system}:
13885 (use-modules (gnu))
13886 (use-service-modules desktop)
13889 ;; cons* adds items to the list given as its last argument.
13890 (services (cons* (gnome-desktop-service)
13891 (xfce-desktop-service)
13892 %desktop-services))
13896 These desktop environments will then be available as options in the
13897 graphical login window.
13899 The actual service definitions included in @code{%desktop-services} and
13900 provided by @code{(gnu services dbus)} and @code{(gnu services desktop)} are
13903 @deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()]
13904 Return a service that runs the ``system bus'', using @var{dbus}, with
13905 support for @var{services}.
13907 @uref{http://dbus.freedesktop.org/, D-Bus} is an inter-process communication
13908 facility. Its system bus is used to allow system services to communicate
13909 and to be notified of system-wide events.
13911 @var{services} must be a list of packages that provide an
13912 @file{etc/dbus-1/system.d} directory containing additional D-Bus
13913 configuration and policy files. For example, to allow avahi-daemon to use
13914 the system bus, @var{services} must be equal to @code{(list avahi)}.
13917 @deffn {Scheme Procedure} elogind-service [#:config @var{config}]
13918 Return a service that runs the @code{elogind} login and seat management
13919 daemon. @uref{https://github.com/elogind/elogind, Elogind} exposes a D-Bus
13920 interface that can be used to know which users are logged in, know what kind
13921 of sessions they have open, suspend the system, inhibit system suspend,
13922 reboot the system, and other tasks.
13924 Elogind handles most system-level power events for a computer, for example
13925 suspending the system when a lid is closed, or shutting it down when the
13926 power button is pressed.
13928 The @var{config} keyword argument specifies the configuration for elogind,
13929 and should be the result of an @code{(elogind-configuration (@var{parameter}
13930 @var{value})...)} invocation. Available parameters and their default values
13934 @item kill-user-processes?
13936 @item kill-only-users
13938 @item kill-exclude-users
13940 @item inhibit-delay-max-seconds
13942 @item handle-power-key
13944 @item handle-suspend-key
13946 @item handle-hibernate-key
13948 @item handle-lid-switch
13950 @item handle-lid-switch-docked
13952 @item power-key-ignore-inhibited?
13954 @item suspend-key-ignore-inhibited?
13956 @item hibernate-key-ignore-inhibited?
13958 @item lid-switch-ignore-inhibited?
13960 @item holdoff-timeout-seconds
13964 @item idle-action-seconds
13966 @item runtime-directory-size-percent
13968 @item runtime-directory-size
13972 @item suspend-state
13973 @code{("mem" "standby" "freeze")}
13976 @item hibernate-state
13978 @item hibernate-mode
13979 @code{("platform" "shutdown")}
13980 @item hybrid-sleep-state
13982 @item hybrid-sleep-mode
13983 @code{("suspend" "platform" "shutdown")}
13987 @deffn {Scheme Procedure} accountsservice-service @
13988 [#:accountsservice @var{accountsservice}] Return a service that runs
13989 AccountsService, a system service that can list available accounts, change
13990 their passwords, and so on. AccountsService integrates with PolicyKit to
13991 enable unprivileged users to acquire the capability to modify their system
13993 @uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the
13994 accountsservice web site} for more information.
13996 The @var{accountsservice} keyword argument is the @code{accountsservice}
13997 package to expose as a service.
14000 @deffn {Scheme Procedure} polkit-service @
14001 [#:polkit @var{polkit}] Return a service that runs the
14002 @uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege
14003 management service}, which allows system administrators to grant access to
14004 privileged operations in a structured way. By querying the Polkit service,
14005 a privileged system component can know when it should grant additional
14006 capabilities to ordinary users. For example, an ordinary user can be
14007 granted the capability to suspend the system if the user is logged in
14011 @deffn {Scheme Procedure} upower-service [#:upower @var{upower}] @
14012 [#:watts-up-pro? #f] @ [#:poll-batteries? #t] @ [#:ignore-lid? #f] @
14013 [#:use-percentage-for-policy? #f] @ [#:percentage-low 10] @
14014 [#:percentage-critical 3] @ [#:percentage-action 2] @ [#:time-low 1200] @
14015 [#:time-critical 300] @ [#:time-action 120] @ [#:critical-power-action
14016 'hybrid-sleep] Return a service that runs
14017 @uref{http://upower.freedesktop.org/, @command{upowerd}}, a system-wide
14018 monitor for power consumption and battery levels, with the given
14019 configuration settings. It implements the @code{org.freedesktop.UPower}
14020 D-Bus interface, and is notably used by GNOME.
14023 @deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}]
14024 Return a service for @uref{http://udisks.freedesktop.org/docs/latest/,
14025 UDisks}, a @dfn{disk management} daemon that provides user interfaces with
14026 notifications and ways to mount/unmount disks. Programs that talk to UDisks
14027 include the @command{udisksctl} command, part of UDisks, and GNOME Disks.
14030 @deffn {Scheme Procedure} colord-service [#:colord @var{colord}]
14031 Return a service that runs @command{colord}, a system service with a D-Bus
14032 interface to manage the color profiles of input and output devices such as
14033 screens and scanners. It is notably used by the GNOME Color Manager
14034 graphical tool. See @uref{http://www.freedesktop.org/software/colord/, the
14035 colord web site} for more information.
14038 @deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
14039 Return a configuration allowing an application to access GeoClue location
14040 data. @var{name} is the Desktop ID of the application, without the
14041 @code{.desktop} part. If @var{allowed?} is true, the application will have
14042 access to location information by default. The boolean @var{system?} value
14043 indicates whether an application is a system component or not. Finally
14044 @var{users} is a list of UIDs of all users for which this application is
14045 allowed location info access. An empty users list means that all users are
14049 @defvr {Scheme Variable} %standard-geoclue-applications
14050 The standard list of well-known GeoClue application configurations, granting
14051 authority to the GNOME date-and-time utility to ask for the current location
14052 in order to set the time zone, and allowing the IceCat and Epiphany web
14053 browsers to request location information. IceCat and Epiphany both query
14054 the user before allowing a web page to know the user's location.
14057 @deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @
14058 [#:whitelist '()] @ [#:wifi-geolocation-url
14059 "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @
14060 [#:submit-data? #f] [#:wifi-submission-url
14061 "https://location.services.mozilla.com/v1/submit?key=geoclue"] @
14062 [#:submission-nick "geoclue"] @ [#:applications
14063 %standard-geoclue-applications] Return a service that runs the GeoClue
14064 location service. This service provides a D-Bus interface to allow
14065 applications to request access to a user's physical location, and optionally
14066 to add information to online location databases. See
14067 @uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue web
14068 site} for more information.
14071 @deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @
14072 [@w{#:auto-enable? #f}] Return a service that runs the @command{bluetoothd}
14073 daemon, which manages all the Bluetooth devices and provides a number of
14074 D-Bus interfaces. When AUTO-ENABLE? is true, the bluetooth controller is
14075 powered automatically at boot, which can be useful when using a bluetooth
14078 Users need to be in the @code{lp} group to access the D-Bus service.
14081 @node Sound Services
14082 @subsubsection Sound Services
14084 @cindex sound support
14086 @cindex PulseAudio, sound support
14088 The @code{(gnu services sound)} module provides a service to configure the
14089 Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the
14090 preferred ALSA output driver.
14092 @deffn {Scheme Variable} alsa-service-type
14093 This is the type for the @uref{https://alsa-project.org/, Advanced Linux
14094 Sound Architecture} (ALSA) system, which generates the
14095 @file{/etc/asound.conf} configuration file. The value for this type is a
14096 @command{alsa-configuration} record as in this example:
14099 (service alsa-service-type)
14102 See below for details about @code{alsa-configuration}.
14105 @deftp {Data Type} alsa-configuration
14106 Data type representing the configuration for @code{alsa-service}.
14109 @item @code{alsa-plugins} (default: @var{alsa-plugins})
14110 @code{alsa-plugins} package to use.
14112 @item @code{pulseaudio?} (default: @var{#t})
14113 Whether ALSA applications should transparently be made to use the
14114 @uref{http://www.pulseaudio.org/, PulseAudio} sound server.
14116 Using PulseAudio allows you to run several sound-producing applications at
14117 the same time and to individual control them @i{via} @command{pavucontrol},
14118 among other things.
14120 @item @code{extra-options} (default: @var{""})
14121 String to append to the @file{/etc/asound.conf} file.
14126 Individual users who want to override the system configuration of ALSA can
14127 do it with the @file{~/.asoundrc} file:
14130 # In guix, we have to specify the absolute path for plugins.
14132 lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
14135 # Routing ALSA to jack:
14136 # <http://jackaudio.org/faq/routing_alsa.html>.
14140 0 system:playback_1
14141 1 system:playback_2
14158 See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the
14162 @node Datenbankdienste
14163 @subsubsection Datenbankdienste
14167 The @code{(gnu services databases)} module provides the following services.
14169 @deffn {Scheme Procedure} postgresql-service [#:postgresql postgresql] @
14170 [#:config-file] [#:data-directory ``/var/lib/postgresql/data''] @ [#:port
14171 5432] [#:locale ``en_US.utf8''] Return a service that runs @var{postgresql},
14172 the PostgreSQL database server.
14174 The PostgreSQL daemon loads its runtime configuration from
14175 @var{config-file}, creates a database cluster with @var{locale} as the
14176 default locale, stored in @var{data-directory}. It then listens on
14180 @deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)]
14181 Return a service that runs @command{mysqld}, the MySQL or MariaDB database
14184 The optional @var{config} argument specifies the configuration for
14185 @command{mysqld}, which should be a @code{<mysql-configuration>} object.
14188 @deftp {Data Type} mysql-configuration
14189 Data type representing the configuration of @var{mysql-service}.
14192 @item @code{mysql} (default: @var{mariadb})
14193 Package object of the MySQL database server, can be either @var{mariadb} or
14196 For MySQL, a temporary root password will be displayed at activation time.
14197 For MariaDB, the root password is empty.
14199 @item @code{port} (default: @code{3306})
14200 TCP port on which the database server listens for incoming connections.
14204 @defvr {Scheme Variable} memcached-service-type
14205 This is the service type for the @uref{https://memcached.org/, Memcached}
14206 service, which provides a distributed in memory cache. The value for the
14207 service type is a @code{memcached-configuration} object.
14211 (service memcached-service-type)
14214 @deftp {Data Type} memcached-configuration
14215 Data type representing the configuration of memcached.
14218 @item @code{memcached} (default: @code{memcached})
14219 The Memcached package to use.
14221 @item @code{interfaces} (default: @code{'("0.0.0.0")})
14222 Network interfaces on which to listen.
14224 @item @code{tcp-port} (default: @code{11211})
14225 Port on which to accept connections on,
14227 @item @code{udp-port} (default: @code{11211})
14228 Port on which to accept UDP connections on, a value of 0 will disable
14229 listening on a UDP socket.
14231 @item @code{additional-options} (default: @code{'()})
14232 Additional command line options to pass to @code{memcached}.
14236 @defvr {Scheme Variable} mongodb-service-type
14237 This is the service type for @uref{https://www.mongodb.com/, MongoDB}. The
14238 value for the service type is a @code{mongodb-configuration} object.
14242 (service mongodb-service-type)
14245 @deftp {Data Type} mongodb-configuration
14246 Data type representing the configuration of mongodb.
14249 @item @code{mongodb} (default: @code{mongodb})
14250 The MongoDB package to use.
14252 @item @code{config-file} (default: @code{%default-mongodb-configuration-file})
14253 The configuration file for MongoDB.
14255 @item @code{data-directory} (default: @code{"/var/lib/mongodb"})
14256 This value is used to create the directory, so that it exists and is owned
14257 by the mongodb user. It should match the data-directory which MongoDB is
14258 configured to use through the configuration file.
14262 @defvr {Scheme Variable} redis-service-type
14263 This is the service type for the @uref{https://redis.io/, Redis} key/value
14264 store, whose value is a @code{redis-configuration} object.
14267 @deftp {Data Type} redis-configuration
14268 Data type representing the configuration of redis.
14271 @item @code{redis} (default: @code{redis})
14272 The Redis package to use.
14274 @item @code{bind} (default: @code{"127.0.0.1"})
14275 Network interface on which to listen.
14277 @item @code{port} (default: @code{6379})
14278 Port on which to accept connections on, a value of 0 will disable listening
14281 @item @code{working-directory} (default: @code{"/var/lib/redis"})
14282 Directory in which to store the database and related files.
14287 @subsubsection Mail-Dienste
14291 The @code{(gnu services mail)} module provides Guix service definitions for
14292 email services: IMAP, POP3, and LMTP servers, as well as mail transport
14293 agents (MTAs). Lots of acronyms! These services are detailed in the
14296 @subsubheading Dovecot Service
14298 @deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)]
14299 Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.
14302 By default, Dovecot does not need much configuration; the default
14303 configuration object created by @code{(dovecot-configuration)} will suffice
14304 if your mail is delivered to @code{~/Maildir}. A self-signed certificate
14305 will be generated for TLS-protected connections, though Dovecot will also
14306 listen on cleartext ports by default. There are a number of options,
14307 though, which mail administrators might need to change, and as is the case
14308 with other services, Guix allows the system administrator to specify these
14309 parameters via a uniform Scheme interface.
14311 For example, to specify that mail is located at @code{maildir~/.mail}, one
14312 would instantiate the Dovecot service like this:
14315 (dovecot-service #:config
14316 (dovecot-configuration
14317 (mail-location "maildir:~/.mail")))
14320 The available configuration parameters follow. Each parameter definition is
14321 preceded by its type; for example, @samp{string-list foo} indicates that the
14322 @code{foo} parameter should be specified as a list of strings. There is
14323 also a way to specify the configuration as a string, if you have an old
14324 @code{dovecot.conf} file that you want to port over from some other system;
14325 see the end for more details.
14327 @c The following documentation was initially generated by
14328 @c (generate-documentation) in (gnu services mail). Manually maintained
14329 @c documentation is better, so we shouldn't hesitate to edit below as
14330 @c needed. However if the change you want to make to this documentation
14331 @c can be done in an automated way, it's probably easier to change
14332 @c (generate-documentation) than to make it below and have to deal with
14333 @c the churn as dovecot updates.
14335 Available @code{dovecot-configuration} fields are:
14337 @deftypevr {@code{dovecot-configuration} parameter} package dovecot
14338 The dovecot package.
14341 @deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen
14342 A list of IPs or hosts where to listen for connections. @samp{*} listens on
14343 all IPv4 interfaces, @samp{::} listens on all IPv6 interfaces. If you want
14344 to specify non-default ports or anything more complex, customize the address
14345 and port fields of the @samp{inet-listener} of the specific services you are
14349 @deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols
14350 List of protocols we want to serve. Available protocols include
14351 @samp{imap}, @samp{pop3}, and @samp{lmtp}.
14353 Available @code{protocol-configuration} fields are:
14355 @deftypevr {@code{protocol-configuration} parameter} string name
14356 The name of the protocol.
14359 @deftypevr {@code{protocol-configuration} parameter} string auth-socket-path
14360 UNIX socket path to the master authentication server to find users. This is
14361 used by imap (for shared users) and lda. It defaults to
14362 @samp{"/var/run/dovecot/auth-userdb"}.
14365 @deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins
14366 Space separated list of plugins to load.
14369 @deftypevr {@code{protocol-configuration} parameter} non-negative-integer mail-max-userip-connections
14370 Maximum number of IMAP connections allowed for a user from each IP address.
14371 NOTE: The username is compared case-sensitively. Defaults to @samp{10}.
14376 @deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services
14377 List of services to enable. Available services include @samp{imap},
14378 @samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and
14381 Available @code{service-configuration} fields are:
14383 @deftypevr {@code{service-configuration} parameter} string kind
14384 The service kind. Valid values include @code{director}, @code{imap-login},
14385 @code{pop3-login}, @code{lmtp}, @code{imap}, @code{pop3}, @code{auth},
14386 @code{auth-worker}, @code{dict}, @code{tcpwrap}, @code{quota-warning}, or
14390 @deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners
14391 Listeners for the service. A listener is either a
14392 @code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or
14393 an @code{inet-listener-configuration}. Defaults to @samp{()}.
14395 Available @code{unix-listener-configuration} fields are:
14397 @deftypevr {@code{unix-listener-configuration} parameter} string path
14398 Path to the file, relative to @code{base-dir} field. This is also used as
14402 @deftypevr {@code{unix-listener-configuration} parameter} string mode
14403 The access mode for the socket. Defaults to @samp{"0600"}.
14406 @deftypevr {@code{unix-listener-configuration} parameter} string user
14407 The user to own the socket. Defaults to @samp{""}.
14410 @deftypevr {@code{unix-listener-configuration} parameter} string group
14411 The group to own the socket. Defaults to @samp{""}.
14415 Available @code{fifo-listener-configuration} fields are:
14417 @deftypevr {@code{fifo-listener-configuration} parameter} string path
14418 Path to the file, relative to @code{base-dir} field. This is also used as
14422 @deftypevr {@code{fifo-listener-configuration} parameter} string mode
14423 The access mode for the socket. Defaults to @samp{"0600"}.
14426 @deftypevr {@code{fifo-listener-configuration} parameter} string user
14427 The user to own the socket. Defaults to @samp{""}.
14430 @deftypevr {@code{fifo-listener-configuration} parameter} string group
14431 The group to own the socket. Defaults to @samp{""}.
14435 Available @code{inet-listener-configuration} fields are:
14437 @deftypevr {@code{inet-listener-configuration} parameter} string protocol
14438 The protocol to listen for.
14441 @deftypevr {@code{inet-listener-configuration} parameter} string address
14442 The address on which to listen, or empty for all addresses. Defaults to
14446 @deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port
14447 The port on which to listen.
14450 @deftypevr {@code{inet-listener-configuration} parameter} boolean ssl?
14451 Whether to use SSL for this service; @samp{yes}, @samp{no}, or
14452 @samp{required}. Defaults to @samp{#t}.
14457 @deftypevr {@code{service-configuration} parameter} non-negative-integer client-limit
14458 Maximum number of simultaneous client connections per process. Once this
14459 number of connections is received, the next incoming connection will prompt
14460 Dovecot to spawn another process. If set to 0, @code{default-client-limit}
14463 Defaults to @samp{0}.
14467 @deftypevr {@code{service-configuration} parameter} non-negative-integer service-count
14468 Number of connections to handle before starting a new process. Typically
14469 the only useful values are 0 (unlimited) or 1. 1 is more secure, but 0 is
14470 faster. <doc/wiki/LoginProcess.txt>. Defaults to @samp{1}.
14474 @deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit
14475 Maximum number of processes that can exist for this service. If set to 0,
14476 @code{default-process-limit} is used instead.
14478 Defaults to @samp{0}.
14482 @deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail
14483 Number of processes to always keep waiting for more connections. Defaults
14487 @deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit
14488 If you set @samp{service-count 0}, you probably need to grow this. Defaults
14489 to @samp{256000000}.
14494 @deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict
14495 Dict configuration, as created by the @code{dict-configuration} constructor.
14497 Available @code{dict-configuration} fields are:
14499 @deftypevr {@code{dict-configuration} parameter} free-form-fields entries
14500 A list of key-value pairs that this dict should hold. Defaults to
14506 @deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs
14507 A list of passdb configurations, each one created by the
14508 @code{passdb-configuration} constructor.
14510 Available @code{passdb-configuration} fields are:
14512 @deftypevr {@code{passdb-configuration} parameter} string driver
14513 The driver that the passdb should use. Valid values include @samp{pam},
14514 @samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}. Defaults
14518 @deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args
14519 Space separated list of arguments to the passdb driver. Defaults to
14525 @deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs
14526 List of userdb configurations, each one created by the
14527 @code{userdb-configuration} constructor.
14529 Available @code{userdb-configuration} fields are:
14531 @deftypevr {@code{userdb-configuration} parameter} string driver
14532 The driver that the userdb should use. Valid values include @samp{passwd}
14533 and @samp{static}. Defaults to @samp{"passwd"}.
14536 @deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args
14537 Space separated list of arguments to the userdb driver. Defaults to
14541 @deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields
14542 Override fields from passwd. Defaults to @samp{()}.
14547 @deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration
14548 Plug-in configuration, created by the @code{plugin-configuration}
14552 @deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces
14553 List of namespaces. Each item in the list is created by the
14554 @code{namespace-configuration} constructor.
14556 Available @code{namespace-configuration} fields are:
14558 @deftypevr {@code{namespace-configuration} parameter} string name
14559 Name for this namespace.
14562 @deftypevr {@code{namespace-configuration} parameter} string type
14563 Namespace type: @samp{private}, @samp{shared} or @samp{public}. Defaults to
14567 @deftypevr {@code{namespace-configuration} parameter} string separator
14568 Hierarchy separator to use. You should use the same separator for all
14569 namespaces or some clients get confused. @samp{/} is usually a good one.
14570 The default however depends on the underlying mail storage format. Defaults
14574 @deftypevr {@code{namespace-configuration} parameter} string prefix
14575 Prefix required to access this namespace. This needs to be different for
14576 all namespaces. For example @samp{Public/}. Defaults to @samp{""}.
14579 @deftypevr {@code{namespace-configuration} parameter} string location
14580 Physical location of the mailbox. This is in the same format as
14581 mail_location, which is also the default for it. Defaults to @samp{""}.
14584 @deftypevr {@code{namespace-configuration} parameter} boolean inbox?
14585 There can be only one INBOX, and this setting defines which namespace has
14586 it. Defaults to @samp{#f}.
14589 @deftypevr {@code{namespace-configuration} parameter} boolean hidden?
14590 If namespace is hidden, it's not advertised to clients via NAMESPACE
14591 extension. You'll most likely also want to set @samp{list? #f}. This is
14592 mostly useful when converting from another server with different namespaces
14593 which you want to deprecate but still keep working. For example you can
14594 create hidden namespaces with prefixes @samp{~/mail/}, @samp{~%u/mail/} and
14595 @samp{mail/}. Defaults to @samp{#f}.
14598 @deftypevr {@code{namespace-configuration} parameter} boolean list?
14599 Show the mailboxes under this namespace with the LIST command. This makes
14600 the namespace visible for clients that do not support the NAMESPACE
14601 extension. The special @code{children} value lists child mailboxes, but
14602 hides the namespace prefix. Defaults to @samp{#t}.
14605 @deftypevr {@code{namespace-configuration} parameter} boolean subscriptions?
14606 Namespace handles its own subscriptions. If set to @code{#f}, the parent
14607 namespace handles them. The empty prefix should always have this as
14608 @code{#t}). Defaults to @samp{#t}.
14611 @deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes
14612 List of predefined mailboxes in this namespace. Defaults to @samp{()}.
14614 Available @code{mailbox-configuration} fields are:
14616 @deftypevr {@code{mailbox-configuration} parameter} string name
14617 Name for this mailbox.
14620 @deftypevr {@code{mailbox-configuration} parameter} string auto
14621 @samp{create} will automatically create this mailbox. @samp{subscribe} will
14622 both create and subscribe to the mailbox. Defaults to @samp{"no"}.
14625 @deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use
14626 List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154. Valid
14627 values are @code{\All}, @code{\Archive}, @code{\Drafts}, @code{\Flagged},
14628 @code{\Junk}, @code{\Sent}, and @code{\Trash}. Defaults to @samp{()}.
14635 @deftypevr {@code{dovecot-configuration} parameter} file-name base-dir
14636 Base directory where to store runtime data. Defaults to
14637 @samp{"/var/run/dovecot/"}.
14640 @deftypevr {@code{dovecot-configuration} parameter} string login-greeting
14641 Greeting message for clients. Defaults to @samp{"Dovecot ready."}.
14644 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-trusted-networks
14645 List of trusted network ranges. Connections from these IPs are allowed to
14646 override their IP addresses and ports (for logging and for authentication
14647 checks). @samp{disable-plaintext-auth} is also ignored for these networks.
14648 Typically you would specify your IMAP proxy servers here. Defaults to
14652 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets
14653 List of login access check sockets (e.g.@: tcpwrap). Defaults to @samp{()}.
14656 @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle?
14657 Show more verbose process titles (in ps). Currently shows user name and IP
14658 address. Useful for seeing who is actually using the IMAP processes (e.g.@:
14659 shared mailboxes or if the same uid is used for multiple accounts).
14660 Defaults to @samp{#f}.
14663 @deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients?
14664 Should all processes be killed when Dovecot master process shuts down.
14665 Setting this to @code{#f} means that Dovecot can be upgraded without forcing
14666 existing client connections to close (although that could also be a problem
14667 if the upgrade is e.g.@: due to a security fix). Defaults to @samp{#t}.
14670 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer doveadm-worker-count
14671 If non-zero, run mail commands via this many connections to doveadm server,
14672 instead of running them directly in the same process. Defaults to @samp{0}.
14675 @deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path
14676 UNIX socket or host:port used for connecting to doveadm server. Defaults to
14677 @samp{"doveadm-server"}.
14680 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-environment
14681 List of environment variables that are preserved on Dovecot startup and
14682 passed down to all of its child processes. You can also give key=value
14683 pairs to always set specific settings.
14686 @deftypevr {@code{dovecot-configuration} parameter} boolean disable-plaintext-auth?
14687 Disable LOGIN command and all other plaintext authentications unless SSL/TLS
14688 is used (LOGINDISABLED capability). Note that if the remote IP matches the
14689 local IP (i.e.@: you're connecting from the same computer), the connection
14690 is considered secure and plaintext authentication is allowed. See also
14691 ssl=required setting. Defaults to @samp{#t}.
14694 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size
14695 Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled.
14696 Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set for
14697 caching to be used. Defaults to @samp{0}.
14700 @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-ttl
14701 Time to live for cached data. After TTL expires the cached record is no
14702 longer used, *except* if the main database lookup returns internal failure.
14703 We also try to handle password changes automatically: If user's previous
14704 authentication was successful, but this one wasn't, the cache isn't used.
14705 For now this works only with plaintext authentication. Defaults to @samp{"1
14709 @deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl
14710 TTL for negative hits (user not found, password mismatch). 0 disables
14711 caching them completely. Defaults to @samp{"1 hour"}.
14714 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-realms
14715 List of realms for SASL authentication mechanisms that need them. You can
14716 leave it empty if you don't want to support multiple realms. Many clients
14717 simply use the first one listed here, so keep the default realm first.
14718 Defaults to @samp{()}.
14721 @deftypevr {@code{dovecot-configuration} parameter} string auth-default-realm
14722 Default realm/domain to use if none was specified. This is used for both
14723 SASL realms and appending @@domain to username in plaintext logins.
14724 Defaults to @samp{""}.
14727 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-chars
14728 List of allowed characters in username. If the user-given username contains
14729 a character not listed in here, the login automatically fails. This is just
14730 an extra check to make sure user can't exploit any potential quote escaping
14731 vulnerabilities with SQL/LDAP databases. If you want to allow all
14732 characters, set this value to empty. Defaults to
14733 @samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}.
14736 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-translation
14737 Username character translations before it's looked up from databases. The
14738 value contains series of from -> to characters. For example @samp{#@@/@@}
14739 means that @samp{#} and @samp{/} characters are translated to @samp{@@}.
14740 Defaults to @samp{""}.
14743 @deftypevr {@code{dovecot-configuration} parameter} string auth-username-format
14744 Username formatting before it's looked up from databases. You can use the
14745 standard variables here, e.g.@: %Lu would lowercase the username, %n would
14746 drop away the domain if it was given, or @samp{%n-AT-%d} would change the
14747 @samp{@@} into @samp{-AT-}. This translation is done after
14748 @samp{auth-username-translation} changes. Defaults to @samp{"%Lu"}.
14751 @deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-separator
14752 If you want to allow master users to log in by specifying the master
14753 username within the normal username string (i.e.@: not using SASL
14754 mechanism's support for it), you can specify the separator character here.
14755 The format is then <username><separator><master username>. UW-IMAP uses
14756 @samp{*} as the separator, so that could be a good choice. Defaults to
14760 @deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username
14761 Username to use for users logging in with ANONYMOUS SASL mechanism.
14762 Defaults to @samp{"anonymous"}.
14765 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-count
14766 Maximum number of dovecot-auth worker processes. They're used to execute
14767 blocking passdb and userdb queries (e.g.@: MySQL and PAM). They're
14768 automatically created and destroyed as needed. Defaults to @samp{30}.
14771 @deftypevr {@code{dovecot-configuration} parameter} string auth-gssapi-hostname
14772 Host name to use in GSSAPI principal names. The default is to use the name
14773 returned by gethostname(). Use @samp{$ALL} (with quotes) to allow all
14774 keytab entries. Defaults to @samp{""}.
14777 @deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab
14778 Kerberos keytab to use for the GSSAPI mechanism. Will use the system
14779 default (usually @file{/etc/krb5.keytab}) if not specified. You may need to
14780 change the auth service to run as root to be able to read this file.
14781 Defaults to @samp{""}.
14784 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind?
14785 Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon and
14786 @samp{ntlm-auth} helper. <doc/wiki/Authentication/Mechanisms/Winbind.txt>.
14787 Defaults to @samp{#f}.
14790 @deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path
14791 Path for Samba's @samp{ntlm-auth} helper binary. Defaults to
14792 @samp{"/usr/bin/ntlm_auth"}.
14795 @deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay
14796 Time to delay before replying to failed authentications. Defaults to
14800 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert?
14801 Require a valid SSL client certificate or the authentication fails.
14802 Defaults to @samp{#f}.
14805 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert?
14806 Take the username from client's SSL certificate, using
14807 @code{X509_NAME_get_text_by_NID()} which returns the subject's DN's
14808 CommonName. Defaults to @samp{#f}.
14811 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms
14812 List of wanted authentication mechanisms. Supported mechanisms are:
14813 @samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5}, @samp{ntlm},
14814 @samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi}, @samp{otp},
14815 @samp{skey}, and @samp{gss-spnego}. NOTE: See also
14816 @samp{disable-plaintext-auth} setting.
14819 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-servers
14820 List of IPs or hostnames to all director servers, including ourself. Ports
14821 can be specified as ip:port. The default port is the same as what director
14822 service's @samp{inet-listener} is using. Defaults to @samp{()}.
14825 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-mail-servers
14826 List of IPs or hostnames to all backend mail servers. Ranges are allowed
14827 too, like 10.0.0.10-10.0.0.30. Defaults to @samp{()}.
14830 @deftypevr {@code{dovecot-configuration} parameter} string director-user-expire
14831 How long to redirect users to a specific server after it no longer has any
14832 connections. Defaults to @samp{"15 min"}.
14835 @deftypevr {@code{dovecot-configuration} parameter} string director-username-hash
14836 How the username is translated before being hashed. Useful values include
14837 %Ln if user can log in with or without @@domain, %Ld if mailboxes are shared
14838 within domain. Defaults to @samp{"%Lu"}.
14841 @deftypevr {@code{dovecot-configuration} parameter} string log-path
14842 Log file to use for error messages. @samp{syslog} logs to syslog,
14843 @samp{/dev/stderr} logs to stderr. Defaults to @samp{"syslog"}.
14846 @deftypevr {@code{dovecot-configuration} parameter} string info-log-path
14847 Log file to use for informational messages. Defaults to @samp{log-path}.
14848 Defaults to @samp{""}.
14851 @deftypevr {@code{dovecot-configuration} parameter} string debug-log-path
14852 Log file to use for debug messages. Defaults to @samp{info-log-path}.
14853 Defaults to @samp{""}.
14856 @deftypevr {@code{dovecot-configuration} parameter} string syslog-facility
14857 Syslog facility to use if you're logging to syslog. Usually if you don't
14858 want to use @samp{mail}, you'll use local0..local7. Also other standard
14859 facilities are supported. Defaults to @samp{"mail"}.
14862 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose?
14863 Log unsuccessful authentication attempts and the reasons why they failed.
14864 Defaults to @samp{#f}.
14867 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords?
14868 In case of password mismatches, log the attempted password. Valid values
14869 are no, plain and sha1. sha1 can be useful for detecting brute force
14870 password attempts vs. user simply trying the same password over and over
14871 again. You can also truncate the value to n chars by appending ":n" (e.g.@:
14872 sha1:6). Defaults to @samp{#f}.
14875 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug?
14876 Even more verbose logging for debugging purposes. Shows for example SQL
14877 queries. Defaults to @samp{#f}.
14880 @deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords?
14881 In case of password mismatches, log the passwords and used scheme so the
14882 problem can be debugged. Enabling this also enables @samp{auth-debug}.
14883 Defaults to @samp{#f}.
14886 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug?
14887 Enable mail process debugging. This can help you figure out why Dovecot
14888 isn't finding your mails. Defaults to @samp{#f}.
14891 @deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl?
14892 Show protocol level SSL errors. Defaults to @samp{#f}.
14895 @deftypevr {@code{dovecot-configuration} parameter} string log-timestamp
14896 Prefix for each line written to log file. % codes are in strftime(3)
14897 format. Defaults to @samp{"\"%b %d %H:%M:%S \""}.
14900 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-elements
14901 List of elements we want to log. The elements which have a non-empty
14902 variable value are joined together to form a comma-separated string.
14905 @deftypevr {@code{dovecot-configuration} parameter} string login-log-format
14906 Login log format. %s contains @samp{login-log-format-elements} string, %$
14907 contains the data we want to log. Defaults to @samp{"%$: %s"}.
14910 @deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix
14911 Log prefix for mail processes. See doc/wiki/Variables.txt for list of
14912 possible variables you can use. Defaults to
14913 @samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}.
14916 @deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format
14917 Format to use for logging mail deliveries. You can use variables:
14920 Delivery status message (e.g.@: @samp{saved to INBOX})
14932 Defaults to @samp{"msgid=%m: %$"}.
14935 @deftypevr {@code{dovecot-configuration} parameter} string mail-location
14936 Location for users' mailboxes. The default is empty, which means that
14937 Dovecot tries to find the mailboxes automatically. This won't work if the
14938 user doesn't yet have any mail, so you should explicitly tell Dovecot the
14941 If you're using mbox, giving a path to the INBOX file (e.g.@: /var/mail/%u)
14942 isn't enough. You'll also need to tell Dovecot where the other mailboxes
14943 are kept. This is called the "root mail directory", and it must be the
14944 first path given in the @samp{mail-location} setting.
14946 There are a few special variables you can use, eg.:
14952 user part in user@@domain, same as %u if there's no domain
14954 domain part in user@@domain, empty if there's no domain
14959 See doc/wiki/Variables.txt for full list. Some examples:
14961 @item maildir:~/Maildir
14962 @item mbox:~/mail:INBOX=/var/mail/%u
14963 @item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%
14965 Defaults to @samp{""}.
14968 @deftypevr {@code{dovecot-configuration} parameter} string mail-uid
14969 System user and group used to access mails. If you use multiple, userdb can
14970 override these by returning uid or gid fields. You can use either numbers
14971 or names. <doc/wiki/UserIds.txt>. Defaults to @samp{""}.
14974 @deftypevr {@code{dovecot-configuration} parameter} string mail-gid
14976 Defaults to @samp{""}.
14979 @deftypevr {@code{dovecot-configuration} parameter} string mail-privileged-group
14980 Group to enable temporarily for privileged operations. Currently this is
14981 used only with INBOX when either its initial creation or dotlocking fails.
14982 Typically this is set to "mail" to give access to /var/mail. Defaults to
14986 @deftypevr {@code{dovecot-configuration} parameter} string mail-access-groups
14987 Grant access to these supplementary groups for mail processes. Typically
14988 these are used to set up access to shared mailboxes. Note that it may be
14989 dangerous to set these if users can create symlinks (e.g.@: if "mail" group
14990 is set here, ln -s /var/mail ~/mail/var could allow a user to delete others'
14991 mailboxes, or ln -s /secret/shared/box ~/mail/mybox would allow reading
14992 it). Defaults to @samp{""}.
14995 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access?
14996 Allow full file system access to clients. There's no access checks other
14997 than what the operating system does for the active UID/GID. It works with
14998 both maildir and mboxes, allowing you to prefix mailboxes names with e.g.@:
14999 /path/ or ~user/. Defaults to @samp{#f}.
15002 @deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable?
15003 Don't use mmap() at all. This is required if you store indexes to shared
15004 file systems (NFS or clustered file system). Defaults to @samp{#f}.
15007 @deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl?
15008 Rely on @samp{O_EXCL} to work when creating dotlock files. NFS supports
15009 @samp{O_EXCL} since version 3, so this should be safe to use nowadays by
15010 default. Defaults to @samp{#t}.
15013 @deftypevr {@code{dovecot-configuration} parameter} string mail-fsync
15014 When to use fsync() or fdatasync() calls:
15017 Whenever necessary to avoid losing important data
15019 Useful with e.g.@: NFS when write()s are delayed
15021 Never use it (best performance, but crashes can lose data).
15023 Defaults to @samp{"optimized"}.
15026 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage?
15027 Mail storage exists in NFS. Set this to yes to make Dovecot flush NFS
15028 caches whenever needed. If you're using only a single mail server this
15029 isn't needed. Defaults to @samp{#f}.
15032 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index?
15033 Mail index files also exist in NFS. Setting this to yes requires
15034 @samp{mmap-disable? #t} and @samp{fsync-disable? #f}. Defaults to
15038 @deftypevr {@code{dovecot-configuration} parameter} string lock-method
15039 Locking method for index files. Alternatives are fcntl, flock and dotlock.
15040 Dotlocking uses some tricks which may create more disk I/O than other
15041 locking methods. NFS users: flock doesn't work, remember to change
15042 @samp{mmap-disable}. Defaults to @samp{"fcntl"}.
15045 @deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir
15046 Directory in which LDA/LMTP temporarily stores incoming mails >128 kB.
15047 Defaults to @samp{"/tmp"}.
15050 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-uid
15051 Valid UID range for users. This is mostly to make sure that users can't log
15052 in as daemons or other system users. Note that denying root logins is
15053 hardcoded to dovecot binary and can't be done even if @samp{first-valid-uid}
15054 is set to 0. Defaults to @samp{500}.
15057 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid
15059 Defaults to @samp{0}.
15062 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-gid
15063 Valid GID range for users. Users having non-valid GID as primary group ID
15064 aren't allowed to log in. If user belongs to supplementary groups with
15065 non-valid GIDs, those groups are not set. Defaults to @samp{1}.
15068 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid
15070 Defaults to @samp{0}.
15073 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length
15074 Maximum allowed length for mail keyword name. It's only forced when trying
15075 to create new keywords. Defaults to @samp{50}.
15078 @deftypevr {@code{dovecot-configuration} parameter} colon-separated-file-name-list valid-chroot-dirs
15079 List of directories under which chrooting is allowed for mail processes
15080 (i.e.@: /var/mail will allow chrooting to /var/mail/foo/bar too). This
15081 setting doesn't affect @samp{login-chroot} @samp{mail-chroot} or auth chroot
15082 settings. If this setting is empty, "/./" in home dirs are ignored.
15083 WARNING: Never add directories here which local users can modify, that may
15084 lead to root exploit. Usually this should be done only if you don't allow
15085 shell access for users. <doc/wiki/Chrooting.txt>. Defaults to @samp{()}.
15088 @deftypevr {@code{dovecot-configuration} parameter} string mail-chroot
15089 Default chroot directory for mail processes. This can be overridden for
15090 specific users in user database by giving /./ in user's home directory
15091 (e.g.@: /home/./user chroots into /home). Note that usually there is no
15092 real need to do chrooting, Dovecot doesn't allow users to access files
15093 outside their mail directory anyway. If your home directories are prefixed
15094 with the chroot directory, append "/."@: to @samp{mail-chroot}.
15095 <doc/wiki/Chrooting.txt>. Defaults to @samp{""}.
15098 @deftypevr {@code{dovecot-configuration} parameter} file-name auth-socket-path
15099 UNIX socket path to master authentication server to find users. This is
15100 used by imap (for shared users) and lda. Defaults to
15101 @samp{"/var/run/dovecot/auth-userdb"}.
15104 @deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir
15105 Directory where to look up mail plugins. Defaults to
15106 @samp{"/usr/lib/dovecot"}.
15109 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mail-plugins
15110 List of plugins to load for all services. Plugins specific to IMAP, LDA,
15111 etc.@: are added to this list in their own .conf files. Defaults to
15115 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-cache-min-mail-count
15116 The minimum number of mails in a mailbox before updates are done to cache
15117 file. This allows optimizing Dovecot's behavior to do less disk writes at
15118 the cost of more disk reads. Defaults to @samp{0}.
15121 @deftypevr {@code{dovecot-configuration} parameter} string mailbox-idle-check-interval
15122 When IDLE command is running, mailbox is checked once in a while to see if
15123 there are any new mails or other changes. This setting defines the minimum
15124 time to wait between those checks. Dovecot can also use dnotify, inotify
15125 and kqueue to find out immediately when changes occur. Defaults to
15129 @deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf?
15130 Save mails with CR+LF instead of plain LF. This makes sending those mails
15131 take less CPU, especially with sendfile() syscall with Linux and FreeBSD.
15132 But it also creates a bit more disk I/O which may just make it slower. Also
15133 note that if other software reads the mboxes/maildirs, they may handle the
15134 extra CRs wrong and cause problems. Defaults to @samp{#f}.
15137 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-stat-dirs?
15138 By default LIST command returns all entries in maildir beginning with a
15139 dot. Enabling this option makes Dovecot return only entries which are
15140 directories. This is done by stat()ing each entry, so it causes more disk
15141 I/O. (For systems setting struct @samp{dirent->d_type} this check is free
15142 and it's done always regardless of this setting). Defaults to @samp{#f}.
15145 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks?
15146 When copying a message, do it with hard links whenever possible. This makes
15147 the performance much better, and it's unlikely to have any side effects.
15148 Defaults to @samp{#t}.
15151 @deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs?
15152 Assume Dovecot is the only MUA accessing Maildir: Scan cur/ directory only
15153 when its mtime changes unexpectedly or when we can't find the mail
15154 otherwise. Defaults to @samp{#f}.
15157 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks
15158 Which locking methods to use for locking mbox. There are four available:
15162 Create <mailbox>.lock file. This is the oldest and most NFS-safe solution.
15163 If you want to use /var/mail/ like directory, the users will need write
15164 access to that directory.
15166 Same as dotlock, but if it fails because of permissions or because there
15167 isn't enough disk space, just skip it.
15169 Use this if possible. Works with NFS too if lockd is used.
15171 May not exist in all systems. Doesn't work with NFS.
15173 May not exist in all systems. Doesn't work with NFS.
15176 You can use multiple locking methods; if you do the order they're declared
15177 in is important to avoid deadlocks if other MTAs/MUAs are using multiple
15178 locking methods as well. Some operating systems don't allow using some of
15179 them simultaneously.
15182 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks
15186 @deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout
15187 Maximum time to wait for lock (all of them) before aborting. Defaults to
15191 @deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout
15192 If dotlock exists but the mailbox isn't modified in any way, override the
15193 lock file after this much time. Defaults to @samp{"2 mins"}.
15196 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs?
15197 When mbox changes unexpectedly we have to fully read it to find out what
15198 changed. If the mbox is large this can take a long time. Since the change
15199 is usually just a newly appended mail, it'd be faster to simply read the new
15200 mails. If this setting is enabled, Dovecot does this but still safely
15201 fallbacks to re-reading the whole mbox file whenever something in mbox isn't
15202 how it's expected to be. The only real downside to this setting is that if
15203 some other MUA changes message flags, Dovecot doesn't notice it
15204 immediately. Note that a full sync is done with SELECT, EXAMINE, EXPUNGE
15205 and CHECK commands. Defaults to @samp{#t}.
15208 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs?
15209 Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT,
15210 EXAMINE, EXPUNGE or CHECK commands. If this is set, @samp{mbox-dirty-syncs}
15211 is ignored. Defaults to @samp{#f}.
15214 @deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes?
15215 Delay writing mbox headers until doing a full write sync (EXPUNGE and CHECK
15216 commands and when closing the mailbox). This is especially useful for POP3
15217 where clients often delete all mails. The downside is that our changes
15218 aren't immediately visible to other MUAs. Defaults to @samp{#t}.
15221 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mbox-min-index-size
15222 If mbox size is smaller than this (e.g.@: 100k), don't write index files.
15223 If an index file already exists it's still read, just not updated. Defaults
15227 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size
15228 Maximum dbox file size until it's rotated. Defaults to @samp{10000000}.
15231 @deftypevr {@code{dovecot-configuration} parameter} string mdbox-rotate-interval
15232 Maximum dbox file age until it's rotated. Typically in days. Day begins
15233 from midnight, so 1d = today, 2d = yesterday, etc. 0 = check disabled.
15234 Defaults to @samp{"1d"}.
15237 @deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space?
15238 When creating new mdbox files, immediately preallocate their size to
15239 @samp{mdbox-rotate-size}. This setting currently works only in Linux with
15240 some file systems (ext4, xfs). Defaults to @samp{#f}.
15243 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-dir
15244 sdbox and mdbox support saving mail attachments to external files, which
15245 also allows single instance storage for them. Other backends don't support
15248 WARNING: This feature hasn't been tested much yet. Use at your own risk.
15250 Directory root where to store mail attachments. Disabled, if empty.
15251 Defaults to @samp{""}.
15254 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-attachment-min-size
15255 Attachments smaller than this aren't saved externally. It's also possible
15256 to write a plugin to disable saving specific attachments externally.
15257 Defaults to @samp{128000}.
15260 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs
15261 File system backend to use for saving attachments:
15264 No SiS done by Dovecot (but this might help FS's own deduplication)
15266 SiS with immediate byte-by-byte comparison during saving
15267 @item sis-queue posix
15268 SiS with delayed comparison and deduplication.
15270 Defaults to @samp{"sis posix"}.
15273 @deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash
15274 Hash format to use in attachment filenames. You can add any text and
15275 variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}},
15276 @code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be
15277 truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits.
15278 Defaults to @samp{"%@{sha1@}"}.
15281 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit
15283 Defaults to @samp{100}.
15286 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit
15288 Defaults to @samp{1000}.
15291 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-limit
15292 Default VSZ (virtual memory size) limit for service processes. This is
15293 mainly intended to catch and kill processes that leak memory before they eat
15294 up everything. Defaults to @samp{256000000}.
15297 @deftypevr {@code{dovecot-configuration} parameter} string default-login-user
15298 Login user is internally used by login processes. This is the most
15299 untrusted user in Dovecot system. It shouldn't have access to anything at
15300 all. Defaults to @samp{"dovenull"}.
15303 @deftypevr {@code{dovecot-configuration} parameter} string default-internal-user
15304 Internal user is used by unprivileged processes. It should be separate from
15305 login user, so that login processes can't disturb other processes. Defaults
15306 to @samp{"dovecot"}.
15309 @deftypevr {@code{dovecot-configuration} parameter} string ssl?
15310 SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>. Defaults to
15314 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert
15315 PEM encoded X.509 SSL/TLS certificate (public key). Defaults to
15316 @samp{"</etc/dovecot/default.pem"}.
15319 @deftypevr {@code{dovecot-configuration} parameter} string ssl-key
15320 PEM encoded SSL/TLS private key. The key is opened before dropping root
15321 privileges, so keep the key file unreadable by anyone but root. Defaults to
15322 @samp{"</etc/dovecot/private/default.pem"}.
15325 @deftypevr {@code{dovecot-configuration} parameter} string ssl-key-password
15326 If key file is password protected, give the password here. Alternatively
15327 give it when starting dovecot with -p parameter. Since this file is often
15328 world-readable, you may want to place this setting instead to a different.
15329 Defaults to @samp{""}.
15332 @deftypevr {@code{dovecot-configuration} parameter} string ssl-ca
15333 PEM encoded trusted certificate authority. Set this only if you intend to
15334 use @samp{ssl-verify-client-cert? #t}. The file should contain the CA
15335 certificate(s) followed by the matching CRL(s). (e.g.@: @samp{ssl-ca
15336 </etc/ssl/certs/ca.pem}). Defaults to @samp{""}.
15339 @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl?
15340 Require that CRL check succeeds for client certificates. Defaults to
15344 @deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert?
15345 Request client to send a certificate. If you also want to require it, set
15346 @samp{auth-ssl-require-client-cert? #t} in auth section. Defaults to
15350 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field
15351 Which field from certificate to use for username. commonName and
15352 x500UniqueIdentifier are the usual choices. You'll also need to set
15353 @samp{auth-ssl-username-from-cert? #t}. Defaults to @samp{"commonName"}.
15356 @deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol
15357 Minimum SSL protocol version to accept. Defaults to @samp{"TLSv1"}.
15360 @deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list
15361 SSL ciphers to use. Defaults to
15362 @samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}.
15365 @deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device
15366 SSL crypto device to use, for valid values run "openssl engine". Defaults
15370 @deftypevr {@code{dovecot-configuration} parameter} string postmaster-address
15371 Address to use when sending rejection mails. %d expands to recipient
15372 domain. Defaults to @samp{"postmaster@@%d"}.
15375 @deftypevr {@code{dovecot-configuration} parameter} string hostname
15376 Hostname to use in various parts of sent mails (e.g.@: in Message-Id) and
15377 in LMTP replies. Default is the system's real hostname@@domain. Defaults
15381 @deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail?
15382 If user is over quota, return with temporary failure instead of bouncing the
15383 mail. Defaults to @samp{#f}.
15386 @deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path
15387 Binary to use for sending mails. Defaults to @samp{"/usr/sbin/sendmail"}.
15390 @deftypevr {@code{dovecot-configuration} parameter} string submission-host
15391 If non-empty, send mails via this SMTP host[:port] instead of sendmail.
15392 Defaults to @samp{""}.
15395 @deftypevr {@code{dovecot-configuration} parameter} string rejection-subject
15396 Subject: header to use for rejection mails. You can use the same variables
15397 as for @samp{rejection-reason} below. Defaults to @samp{"Rejected: %s"}.
15400 @deftypevr {@code{dovecot-configuration} parameter} string rejection-reason
15401 Human readable error message for rejection mails. You can use variables:
15413 Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}.
15416 @deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter
15417 Delimiter character between local-part and detail in email address.
15418 Defaults to @samp{"+"}.
15421 @deftypevr {@code{dovecot-configuration} parameter} string lda-original-recipient-header
15422 Header where the original recipient address (SMTP's RCPT TO: address) is
15423 taken from if not available elsewhere. With dovecot-lda -a parameter
15424 overrides this. A commonly used header for this is X-Original-To. Defaults
15428 @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate?
15429 Should saving a mail to a nonexistent mailbox automatically create it?.
15430 Defaults to @samp{#f}.
15433 @deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe?
15434 Should automatically created mailboxes be also automatically subscribed?.
15435 Defaults to @samp{#f}.
15438 @deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-length
15439 Maximum IMAP command line length. Some clients generate very long command
15440 lines with huge mailboxes, so you may need to raise this if you get "Too
15441 long argument" or "IMAP command line too large" errors often. Defaults to
15445 @deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format
15446 IMAP logout format string:
15449 total number of bytes read from client
15451 total number of bytes sent to client.
15453 See @file{doc/wiki/Variables.txt} for a list of all the variables you can
15454 use. Defaults to @samp{"in=%i out=%o deleted=%@{deleted@}
15455 expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@}
15456 hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@}
15457 body_bytes=%@{fetch_body_bytes@}"}.
15460 @deftypevr {@code{dovecot-configuration} parameter} string imap-capability
15461 Override the IMAP CAPABILITY response. If the value begins with '+', add
15462 the given capabilities on top of the defaults (e.g.@: +XFOO XBAR). Defaults
15466 @deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval
15467 How long to wait between "OK Still here" notifications when client is
15468 IDLEing. Defaults to @samp{"2 mins"}.
15471 @deftypevr {@code{dovecot-configuration} parameter} string imap-id-send
15472 ID field names and values to send to clients. Using * as the value makes
15473 Dovecot use the default value. The following fields have default values
15474 currently: name, version, os, os-version, support-url, support-email.
15475 Defaults to @samp{""}.
15478 @deftypevr {@code{dovecot-configuration} parameter} string imap-id-log
15479 ID fields sent by client to log. * means everything. Defaults to
15483 @deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds
15484 Workarounds for various client bugs:
15487 @item delay-newmail
15488 Send EXISTS/RECENT new mail notifications only when replying to NOOP and
15489 CHECK commands. Some clients ignore them otherwise, for example OSX Mail
15490 (<v2.1). Outlook Express breaks more badly though, without this it may show
15491 user "Message no longer in server" errors. Note that OE6 still breaks even
15492 with this workaround if synchronization is set to "Headers Only".
15494 @item tb-extra-mailbox-sep
15495 Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and adds
15496 extra @samp{/} suffixes to mailbox names. This option causes Dovecot to
15497 ignore the extra @samp{/} instead of treating it as invalid mailbox name.
15499 @item tb-lsub-flags
15500 Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g.@: mbox). This
15501 makes Thunderbird realize they aren't selectable and show them greyed out,
15502 instead of only later giving "not selectable" popup error.
15504 Defaults to @samp{()}.
15507 @deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host
15508 Host allowed in URLAUTH URLs sent by client. "*" allows all. Defaults to
15513 Whew! Lots of configuration options. The nice thing about it though is that
15514 GuixSD has a complete interface to Dovecot's configuration language. This
15515 allows not only a nice way to declare configurations, but also offers
15516 reflective capabilities as well: users can write code to inspect and
15517 transform configurations from within Scheme.
15519 However, it could be that you just want to get a @code{dovecot.conf} up and
15520 running. In that case, you can pass an @code{opaque-dovecot-configuration}
15521 as the @code{#:config} parameter to @code{dovecot-service}. As its name
15522 indicates, an opaque configuration does not have easy reflective
15525 Available @code{opaque-dovecot-configuration} fields are:
15527 @deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot
15528 The dovecot package.
15531 @deftypevr {@code{opaque-dovecot-configuration} parameter} string string
15532 The contents of the @code{dovecot.conf}, as a string.
15535 For example, if your @code{dovecot.conf} is just the empty string, you could
15536 instantiate a dovecot service like this:
15539 (dovecot-service #:config
15540 (opaque-dovecot-configuration
15544 @subsubheading OpenSMTPD Service
15546 @deffn {Scheme Variable} opensmtpd-service-type
15547 This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD} service,
15548 whose value should be an @code{opensmtpd-configuration} object as in this
15552 (service opensmtpd-service-type
15553 (opensmtpd-configuration
15554 (config-file (local-file "./my-smtpd.conf"))))
15558 @deftp {Data Type} opensmtpd-configuration
15559 Data type representing the configuration of opensmtpd.
15562 @item @code{package} (default: @var{opensmtpd})
15563 Package object of the OpenSMTPD SMTP server.
15565 @item @code{config-file} (default: @var{%default-opensmtpd-file})
15566 File-like object of the OpenSMTPD configuration file to use. By default it
15567 listens on the loopback network interface, and allows for mail from users
15568 and daemons on the local machine, as well as permitting email to remote
15569 servers. Run @command{man smtpd.conf} for more information.
15574 @subsubheading Exim Service
15576 @cindex mail transfer agent (MTA)
15577 @cindex MTA (mail transfer agent)
15580 @deffn {Scheme Variable} exim-service-type
15581 This is the type of the @uref{https://exim.org, Exim} mail transfer agent
15582 (MTA), whose value should be an @code{exim-configuration} object as in this
15586 (service exim-service-type
15587 (exim-configuration
15588 (config-file (local-file "./my-exim.conf"))))
15592 In order to use an @code{exim-service-type} service you must also have a
15593 @code{mail-aliases-service-type} service present in your
15594 @code{operating-system} (even if it has no aliases).
15596 @deftp {Data Type} exim-configuration
15597 Data type representing the configuration of exim.
15600 @item @code{package} (default: @var{exim})
15601 Package object of the Exim server.
15603 @item @code{config-file} (default: @code{#f})
15604 File-like object of the Exim configuration file to use. If its value is
15605 @code{#f} then use the default configuration file from the package provided
15606 in @code{package}. The resulting configuration file is loaded after setting
15607 the @code{exim_user} and @code{exim_group} configuration variables.
15612 @subsubheading Mail Aliases Service
15614 @cindex email aliases
15615 @cindex aliases, for email addresses
15617 @deffn {Scheme Variable} mail-aliases-service-type
15618 This is the type of the service which provides @code{/etc/aliases},
15619 specifying how to deliver mail to users on this system.
15622 (service mail-aliases-service-type
15623 '(("postmaster" "bob")
15624 ("bob" "bob@@example.com" "bob@@example2.com")))
15628 The configuration for a @code{mail-aliases-service-type} service is an
15629 association list denoting how to deliver mail that comes to this
15630 system. Each entry is of the form @code{(alias addresses ...)}, with
15631 @code{alias} specifying the local alias and @code{addresses} specifying
15632 where to deliver this user's mail.
15634 The aliases aren't required to exist as users on the local system. In the
15635 above example, there doesn't need to be a @code{postmaster} entry in the
15636 @code{operating-system}'s @code{user-accounts} in order to deliver the
15637 @code{postmaster} mail to @code{bob} (which subsequently would deliver mail
15638 to @code{bob@@example.com} and @code{bob@@example2.com}).
15640 @node Kurznachrichtendienste
15641 @subsubsection Kurznachrichtendienste
15646 The @code{(gnu services messaging)} module provides Guix service definitions
15647 for messaging services: currently only Prosody is supported.
15649 @subsubheading Prosody Service
15651 @deffn {Scheme Variable} prosody-service-type
15652 This is the type for the @uref{https://prosody.im, Prosody XMPP
15653 communication server}. Its value must be a @code{prosody-configuration}
15654 record as in this example:
15657 (service prosody-service-type
15658 (prosody-configuration
15659 (modules-enabled (cons "groups" "mam" %default-modules-enabled))
15662 (int-component-configuration
15663 (hostname "conference.example.net")
15665 (mod-muc (mod-muc-configuration)))))
15668 (virtualhost-configuration
15669 (domain "example.net"))))))
15672 See below for details about @code{prosody-configuration}.
15676 By default, Prosody does not need much configuration. Only one
15677 @code{virtualhosts} field is needed: it specifies the domain you wish
15680 You can perform various sanity checks on the generated configuration with
15681 the @code{prosodyctl check} command.
15683 Prosodyctl will also help you to import certificates from the
15684 @code{letsencrypt} directory so that the @code{prosody} user can access
15685 them. See @url{https://prosody.im/doc/letsencrypt}.
15688 prosodyctl --root cert import /etc/letsencrypt/live
15691 The available configuration parameters follow. Each parameter definition is
15692 preceded by its type; for example, @samp{string-list foo} indicates that the
15693 @code{foo} parameter should be specified as a list of strings. Types
15694 starting with @code{maybe-} denote parameters that won't show up in
15695 @code{prosody.cfg.lua} when their value is @code{'disabled}.
15697 There is also a way to specify the configuration as a string, if you have an
15698 old @code{prosody.cfg.lua} file that you want to port over from some other
15699 system; see the end for more details.
15701 The @code{file-object} type designates either a file-like object
15702 (@pxref{G-Ausdrücke, file-like objects}) or a file name.
15704 @c The following documentation was initially generated by
15705 @c (generate-documentation) in (gnu services messaging). Manually maintained
15706 @c documentation is better, so we shouldn't hesitate to edit below as
15707 @c needed. However if the change you want to make to this documentation
15708 @c can be done in an automated way, it's probably easier to change
15709 @c (generate-documentation) than to make it below and have to deal with
15710 @c the churn as Prosody updates.
15712 Available @code{prosody-configuration} fields are:
15714 @deftypevr {@code{prosody-configuration} parameter} package prosody
15715 The Prosody package.
15718 @deftypevr {@code{prosody-configuration} parameter} file-name data-path
15719 Location of the Prosody data storage directory. See
15720 @url{https://prosody.im/doc/configure}. Defaults to
15721 @samp{"/var/lib/prosody"}.
15724 @deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths
15725 Additional plugin directories. They are searched in all the specified paths
15726 in order. See @url{https://prosody.im/doc/plugins_directory}. Defaults to
15730 @deftypevr {@code{prosody-configuration} parameter} file-name certificates
15731 Every virtual host and component needs a certificate so that clients and
15732 servers can securely verify its identity. Prosody will automatically load
15733 certificates/keys from the directory specified here. Defaults to
15734 @samp{"/etc/prosody/certs"}.
15737 @deftypevr {@code{prosody-configuration} parameter} string-list admins
15738 This is a list of accounts that are admins for the server. Note that you
15739 must create the accounts separately. See
15740 @url{https://prosody.im/doc/admins} and
15741 @url{https://prosody.im/doc/creating_accounts}. Example: @code{(admins
15742 '("user1@@example.com" "user2@@example.net"))} Defaults to @samp{()}.
15745 @deftypevr {@code{prosody-configuration} parameter} boolean use-libevent?
15746 Enable use of libevent for better performance under high load. See
15747 @url{https://prosody.im/doc/libevent}. Defaults to @samp{#f}.
15750 @deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled
15751 This is the list of modules Prosody will load on startup. It looks for
15752 @code{mod_modulename.lua} in the plugins folder, so make sure that exists
15753 too. Documentation on modules can be found at:
15754 @url{https://prosody.im/doc/modules}. Defaults to @samp{("roster"
15755 "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard"
15756 "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}.
15759 @deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled
15760 @samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but should
15761 you want to disable them then add them to this list. Defaults to @samp{()}.
15764 @deftypevr {@code{prosody-configuration} parameter} file-object groups-file
15765 Path to a text file where the shared groups are defined. If this path is
15766 empty then @samp{mod_groups} does nothing. See
15767 @url{https://prosody.im/doc/modules/mod_groups}. Defaults to
15768 @samp{"/var/lib/prosody/sharedgroups.txt"}.
15771 @deftypevr {@code{prosody-configuration} parameter} boolean allow-registration?
15772 Disable account creation by default, for security. See
15773 @url{https://prosody.im/doc/creating_accounts}. Defaults to @samp{#f}.
15776 @deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration ssl
15777 These are the SSL/TLS-related settings. Most of them are disabled so to use
15778 Prosody's defaults. If you do not completely understand these options, do
15779 not add them to your config, it is easy to lower the security of your server
15780 using them. See @url{https://prosody.im/doc/advanced_ssl_config}.
15782 Available @code{ssl-configuration} fields are:
15784 @deftypevr {@code{ssl-configuration} parameter} maybe-string protocol
15785 This determines what handshake to use.
15788 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name key
15789 Path to your private key file.
15792 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate
15793 Path to your certificate file.
15796 @deftypevr {@code{ssl-configuration} parameter} file-object capath
15797 Path to directory containing root certificates that you wish Prosody to
15798 trust when verifying the certificates of remote servers. Defaults to
15799 @samp{"/etc/ssl/certs"}.
15802 @deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile
15803 Path to a file containing root certificates that you wish Prosody to trust.
15804 Similar to @code{capath} but with all certificates concatenated together.
15807 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify
15808 A list of verification options (these mostly map to OpenSSL's
15809 @code{set_verify()} flags).
15812 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list options
15813 A list of general options relating to SSL/TLS. These map to OpenSSL's
15814 @code{set_options()}. For a full list of options available in LuaSec, see
15818 @deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth
15819 How long a chain of certificate authorities to check when looking for a
15820 trusted root certificate.
15823 @deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers
15824 An OpenSSL cipher string. This selects what ciphers Prosody will offer to
15825 clients, and in what order.
15828 @deftypevr {@code{ssl-configuration} parameter} maybe-file-name dhparam
15829 A path to a file containing parameters for Diffie-Hellman key exchange. You
15830 can create such a file with: @code{openssl dhparam -out
15831 /etc/prosody/certs/dh-2048.pem 2048}
15834 @deftypevr {@code{ssl-configuration} parameter} maybe-string curve
15835 Curve for Elliptic curve Diffie-Hellman. Prosody's default is
15836 @samp{"secp384r1"}.
15839 @deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext
15840 A list of "extra" verification options.
15843 @deftypevr {@code{ssl-configuration} parameter} maybe-string password
15844 Password for encrypted private keys.
15849 @deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption?
15850 Whether to force all client-to-server connections to be encrypted or not.
15851 See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}.
15854 @deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms
15855 Set of mechanisms that will never be offered. See
15856 @url{https://prosody.im/doc/modules/mod_saslauth}. Defaults to
15857 @samp{("DIGEST-MD5")}.
15860 @deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption?
15861 Whether to force all server-to-server connections to be encrypted or not.
15862 See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}.
15865 @deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth?
15866 Whether to require encryption and certificate authentication. This provides
15867 ideal security, but requires servers you communicate with to support
15868 encryption AND present valid, trusted certificates. See
15869 @url{https://prosody.im/doc/s2s#security}. Defaults to @samp{#f}.
15872 @deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-domains
15873 Many servers don't support encryption or have invalid or self-signed
15874 certificates. You can list domains here that will not be required to
15875 authenticate using certificates. They will be authenticated using DNS. See
15876 @url{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}.
15879 @deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains
15880 Even if you leave @code{s2s-secure-auth?} disabled, you can still require
15881 valid certificates for some domains by specifying a list here. See
15882 @url{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}.
15885 @deftypevr {@code{prosody-configuration} parameter} string authentication
15886 Select the authentication backend to use. The default provider stores
15887 passwords in plaintext and uses Prosody's configured data storage to store
15888 the authentication data. If you do not trust your server please see
15889 @url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for
15890 information about using the hashed backend. See also
15891 @url{https://prosody.im/doc/authentication} Defaults to
15892 @samp{"internal_plain"}.
15895 @deftypevr {@code{prosody-configuration} parameter} maybe-string log
15896 Set logging options. Advanced logging configuration is not yet supported by
15897 the GuixSD Prosody Service. See @url{https://prosody.im/doc/logging}.
15898 Defaults to @samp{"*syslog"}.
15901 @deftypevr {@code{prosody-configuration} parameter} file-name pidfile
15902 File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}.
15903 Defaults to @samp{"/var/run/prosody/prosody.pid"}.
15906 @deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size
15907 Maximum allowed size of the HTTP body (in bytes).
15910 @deftypevr {@code{prosody-configuration} parameter} maybe-string http-external-url
15911 Some modules expose their own URL in various ways. This URL is built from
15912 the protocol, host and port used. If Prosody sits behind a proxy, the
15913 public URL will be @code{http-external-url} instead. See
15914 @url{https://prosody.im/doc/http#external_url}.
15917 @deftypevr {@code{prosody-configuration} parameter} virtualhost-configuration-list virtualhosts
15918 A host in Prosody is a domain on which user accounts can be created. For
15919 example if you want your users to have addresses like
15920 @samp{"john.smith@@example.com"} then you need to add a host
15921 @samp{"example.com"}. All options in this list will apply only to this
15924 Note: the name "virtual" host is used in configuration to avoid confusion
15925 with the actual physical host that Prosody is installed on. A single
15926 Prosody instance can serve many domains, each one defined as a VirtualHost
15927 entry in Prosody's configuration. Conversely a server that hosts a single
15928 domain would have just one VirtualHost entry.
15930 See @url{https://prosody.im/doc/configure#virtual_host_settings}.
15932 Available @code{virtualhost-configuration} fields are:
15934 all these @code{prosody-configuration} fields: @code{admins},
15935 @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled},
15936 @code{groups-file}, @code{allow-registration?}, @code{ssl},
15937 @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms},
15938 @code{s2s-require-encryption?}, @code{s2s-secure-auth?},
15939 @code{s2s-insecure-domains}, @code{s2s-secure-domains},
15940 @code{authentication}, @code{log}, @code{http-max-content-size},
15941 @code{http-external-url}, @code{raw-content}, plus:
15942 @deftypevr {@code{virtualhost-configuration} parameter} string domain
15943 Domain you wish Prosody to serve.
15948 @deftypevr {@code{prosody-configuration} parameter} int-component-configuration-list int-components
15949 Components are extra services on a server which are available to clients,
15950 usually on a subdomain of the main server (such as
15951 @samp{"mycomponent.example.com"}). Example components might be chatroom
15952 servers, user directories, or gateways to other protocols.
15954 Internal components are implemented with Prosody-specific plugins. To add
15955 an internal component, you simply fill the hostname field, and the plugin
15956 you wish to use for the component.
15958 See @url{https://prosody.im/doc/components}. Defaults to @samp{()}.
15960 Available @code{int-component-configuration} fields are:
15962 all these @code{prosody-configuration} fields: @code{admins},
15963 @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled},
15964 @code{groups-file}, @code{allow-registration?}, @code{ssl},
15965 @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms},
15966 @code{s2s-require-encryption?}, @code{s2s-secure-auth?},
15967 @code{s2s-insecure-domains}, @code{s2s-secure-domains},
15968 @code{authentication}, @code{log}, @code{http-max-content-size},
15969 @code{http-external-url}, @code{raw-content}, plus:
15970 @deftypevr {@code{int-component-configuration} parameter} string hostname
15971 Hostname of the component.
15974 @deftypevr {@code{int-component-configuration} parameter} string plugin
15975 Plugin you wish to use for the component.
15978 @deftypevr {@code{int-component-configuration} parameter} maybe-mod-muc-configuration mod-muc
15979 Multi-user chat (MUC) is Prosody's module for allowing you to create hosted
15980 chatrooms/conferences for XMPP users.
15982 General information on setting up and using multi-user chatrooms can be
15983 found in the "Chatrooms" documentation
15984 (@url{https://prosody.im/doc/chatrooms}), which you should read if you are
15985 new to XMPP chatrooms.
15987 See also @url{https://prosody.im/doc/modules/mod_muc}.
15989 Available @code{mod-muc-configuration} fields are:
15991 @deftypevr {@code{mod-muc-configuration} parameter} string name
15992 The name to return in service discovery responses. Defaults to
15993 @samp{"Prosody Chatrooms"}.
15996 @deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation
15997 If @samp{#t}, this will only allow admins to create new chatrooms.
15998 Otherwise anyone can create a room. The value @samp{"local"} restricts room
15999 creation to users on the service's parent domain. E.g.@:
16000 @samp{user@@example.com} can create rooms on @samp{rooms.example.com}. The
16001 value @samp{"admin"} restricts to service administrators only. Defaults to
16005 @deftypevr {@code{mod-muc-configuration} parameter} non-negative-integer max-history-messages
16006 Maximum number of history messages that will be sent to the member that has
16007 just joined the room. Defaults to @samp{20}.
16014 @deftypevr {@code{prosody-configuration} parameter} ext-component-configuration-list ext-components
16015 External components use XEP-0114, which most standalone components support.
16016 To add an external component, you simply fill the hostname field. See
16017 @url{https://prosody.im/doc/components}. Defaults to @samp{()}.
16019 Available @code{ext-component-configuration} fields are:
16021 all these @code{prosody-configuration} fields: @code{admins},
16022 @code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled},
16023 @code{groups-file}, @code{allow-registration?}, @code{ssl},
16024 @code{c2s-require-encryption?}, @code{disable-sasl-mechanisms},
16025 @code{s2s-require-encryption?}, @code{s2s-secure-auth?},
16026 @code{s2s-insecure-domains}, @code{s2s-secure-domains},
16027 @code{authentication}, @code{log}, @code{http-max-content-size},
16028 @code{http-external-url}, @code{raw-content}, plus:
16029 @deftypevr {@code{ext-component-configuration} parameter} string component-secret
16030 Password which the component will use to log in.
16033 @deftypevr {@code{ext-component-configuration} parameter} string hostname
16034 Hostname of the component.
16039 @deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports
16040 Port(s) Prosody listens on for component connections. Defaults to
16044 @deftypevr {@code{prosody-configuration} parameter} string component-interface
16045 Interface Prosody listens on for component connections. Defaults to
16046 @samp{"127.0.0.1"}.
16049 @deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content
16050 Raw content that will be added to the configuration file.
16053 It could be that you just want to get a @code{prosody.cfg.lua} up and
16054 running. In that case, you can pass an @code{opaque-prosody-configuration}
16055 record as the value of @code{prosody-service-type}. As its name indicates,
16056 an opaque configuration does not have easy reflective capabilities.
16057 Available @code{opaque-prosody-configuration} fields are:
16059 @deftypevr {@code{opaque-prosody-configuration} parameter} package prosody
16060 The prosody package.
16063 @deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua
16064 The contents of the @code{prosody.cfg.lua} to use.
16067 For example, if your @code{prosody.cfg.lua} is just the empty string, you
16068 could instantiate a prosody service like this:
16071 (service prosody-service-type
16072 (opaque-prosody-configuration
16073 (prosody.cfg.lua "")))
16076 @c end of Prosody auto-generated documentation
16078 @subsubheading BitlBee Service
16080 @cindex IRC (Internet Relay Chat)
16081 @cindex IRC gateway
16082 @url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC interface
16083 to a variety of messaging protocols such as XMPP.
16085 @defvr {Scheme Variable} bitlbee-service-type
16086 This is the service type for the @url{http://bitlbee.org,BitlBee} IRC
16087 gateway daemon. Its value is a @code{bitlbee-configuration} (see below).
16089 To have BitlBee listen on port 6667 on localhost, add this line to your
16093 (service bitlbee-service-type)
16097 @deftp {Data Type} bitlbee-configuration
16098 This is the configuration for BitlBee, with the following fields:
16101 @item @code{interface} (default: @code{"127.0.0.1"})
16102 @itemx @code{port} (default: @code{6667})
16103 Listen on the network interface corresponding to the IP address specified in
16104 @var{interface}, on @var{port}.
16106 When @var{interface} is @code{127.0.0.1}, only local clients can connect;
16107 when it is @code{0.0.0.0}, connections can come from any networking
16110 @item @code{package} (default: @code{bitlbee})
16111 The BitlBee package to use.
16113 @item @code{plugins} (default: @code{'()})
16114 List of plugin packages to use---e.g., @code{bitlbee-discord}.
16116 @item @code{extra-settings} (default: @code{""})
16117 Configuration snippet added as-is to the BitlBee configuration file.
16122 @node Telefondienste
16123 @subsubsection Telefondienste
16125 @cindex Murmur (VoIP server)
16126 @cindex VoIP server
16127 This section describes how to set up and run a Murmur server. Murmur is the
16128 server of the @uref{https://mumble.info, Mumble} voice-over-IP (VoIP) suite.
16130 @deftp {Data Type} murmur-configuration
16131 The service type for the Murmur server. An example configuration can look
16135 (service murmur-service-type
16136 (murmur-configuration
16138 "Welcome to this Mumble server running on GuixSD!")
16139 (cert-required? #t) ;disallow text password logins
16140 (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
16141 (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))
16144 After reconfiguring your system, you can manually set the murmur
16145 @code{SuperUser} password with the command that is printed during the
16148 It is recommended to register a normal Mumble user account and grant it
16149 admin or moderator rights. You can use the @code{mumble} client to login as
16150 new normal user, register yourself, and log out. For the next step login
16151 with the name @code{SuperUser} use the @code{SuperUser} password that you
16152 set previously, and grant your newly registered mumble user administrator or
16153 moderator rights and create some channels.
16155 Available @code{murmur-configuration} fields are:
16158 @item @code{package} (default: @code{mumble})
16159 Package that contains @code{bin/murmurd}.
16161 @item @code{user} (default: @code{"murmur"})
16162 User who will run the Murmur server.
16164 @item @code{group} (default: @code{"murmur"})
16165 Group of the user who will run the murmur server.
16167 @item @code{port} (default: @code{64738})
16168 Port on which the server will listen.
16170 @item @code{welcome-text} (default: @code{""})
16171 Welcome text sent to clients when they connect.
16173 @item @code{server-password} (default: @code{""})
16174 Password the clients have to enter in order to connect.
16176 @item @code{max-users} (default: @code{100})
16177 Maximum of users that can be connected to the server at once.
16179 @item @code{max-user-bandwidth} (default: @code{#f})
16180 Maximum voice traffic a user can send per second.
16182 @item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"})
16183 File name of the sqlite database. The service's user will become the owner
16186 @item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"})
16187 File name of the log file. The service's user will become the owner of the
16190 @item @code{autoban-attempts} (default: @code{10})
16191 Maximum number of logins a user can make in @code{autoban-timeframe} without
16192 getting auto banned for @code{autoban-time}.
16194 @item @code{autoban-timeframe} (default: @code{120})
16195 Timeframe for autoban in seconds.
16197 @item @code{autoban-time} (default: @code{300})
16198 Amount of time in seconds for which a client gets banned when violating the
16201 @item @code{opus-threshold} (default: @code{100})
16202 Percentage of clients that need to support opus before switching over to
16205 @item @code{channel-nesting-limit} (default: @code{10})
16206 How deep channels can be nested at maximum.
16208 @item @code{channelname-regex} (default: @code{#f})
16209 A string in form of a Qt regular expression that channel names must conform
16212 @item @code{username-regex} (default: @code{#f})
16213 A string in form of a Qt regular expression that user names must conform to.
16215 @item @code{text-message-length} (default: @code{5000})
16216 Maximum size in bytes that a user can send in one text chat message.
16218 @item @code{image-message-length} (default: @code{(* 128 1024)})
16219 Maximum size in bytes that a user can send in one image message.
16221 @item @code{cert-required?} (default: @code{#f})
16222 If it is set to @code{#t} clients that use weak password authentification
16223 will not be accepted. Users must have completed the certificate wizard to
16226 @item @code{remember-channel?} (default: @code{#f})
16227 Should murmur remember the last channel each user was in when they
16228 disconnected and put them into the remembered channel when they rejoin.
16230 @item @code{allow-html?} (default: @code{#f})
16231 Should html be allowed in text messages, user comments, and channel
16234 @item @code{allow-ping?} (default: @code{#f})
16235 Setting to true exposes the current user count, the maximum user count, and
16236 the server's maximum bandwidth per client to unauthenticated users. In the
16237 Mumble client, this information is shown in the Connect dialog.
16239 Disabling this setting will prevent public listing of the server.
16241 @item @code{bonjour?} (default: @code{#f})
16242 Should the server advertise itself in the local network through the bonjour
16245 @item @code{send-version?} (default: @code{#f})
16246 Should the murmur server version be exposed in ping requests.
16248 @item @code{log-days} (default: @code{31})
16249 Murmur also stores logs in the database, which are accessible via RPC. The
16250 default is 31 days of months, but you can set this setting to 0 to keep logs
16251 forever, or -1 to disable logging to the database.
16253 @item @code{obfuscate-ips?} (default: @code{#t})
16254 Should logged ips be obfuscated to protect the privacy of users.
16256 @item @code{ssl-cert} (default: @code{#f})
16257 File name of the SSL/TLS certificate used for encrypted connections.
16260 (ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")
16262 @item @code{ssl-key} (default: @code{#f})
16263 Filepath to the ssl private key used for encrypted connections.
16265 (ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")
16268 @item @code{ssl-dh-params} (default: @code{#f})
16269 File name of a PEM-encoded file with Diffie-Hellman parameters for the
16270 SSL/TLS encryption. Alternatively you set it to @code{"@@ffdhe2048"},
16271 @code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"} or
16272 @code{"@@ffdhe8192"} to use bundled parameters from RFC 7919.
16274 @item @code{ssl-ciphers} (default: @code{#f})
16275 The @code{ssl-ciphers} option chooses the cipher suites to make available
16276 for use in SSL/TLS.
16278 This option is specified using
16279 @uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT,
16280 OpenSSL cipher list notation}.
16282 It is recommended that you try your cipher string using 'openssl ciphers
16283 <string>' before setting it here, to get a feel for which cipher suites you
16284 will get. After setting this option, it is recommend that you inspect your
16285 Murmur log to ensure that Murmur is using the cipher suites that you
16288 Note: Changing this option may impact the backwards compatibility of your
16289 Murmur server, and can remove the ability for older Mumble clients to be
16290 able to connect to it.
16292 @item @code{public-registration} (default: @code{#f})
16293 Must be a @code{<murmur-public-registration-configuration>} record or
16296 You can optionally register your server in the public server list that the
16297 @code{mumble} client shows on startup. You cannot register your server if
16298 you have set a @code{server-password}, or set @code{allow-ping} to
16301 It might take a few hours until it shows up in the public list.
16303 @item @code{file} (default: @code{#f})
16304 Optional alternative override for this configuration.
16308 @deftp {Data Type} murmur-public-registration-configuration
16309 Configuration for public registration of a murmur service.
16313 This is a display name for your server. Not to be confused with the
16316 @item @code{password}
16317 A password to identify your registration. Subsequent updates will need the
16318 same password. Don't lose your password.
16321 This should be a @code{http://} or @code{https://} link to your web site.
16323 @item @code{hostname} (default: @code{#f})
16324 By default your server will be listed by its IP address. If it is set your
16325 server will be linked by this host name instead.
16331 @node Überwachungsdienste
16332 @subsubsection Überwachungsdienste
16334 @subsubheading Tailon Service
16336 @uref{https://tailon.readthedocs.io/, Tailon} is a web application for
16337 viewing and searching log files.
16339 The following example will configure the service with default values. By
16340 default, Tailon can be accessed on port 8080 (@code{http://localhost:8080}).
16343 (service tailon-service-type)
16346 The following example customises more of the Tailon configuration, adding
16347 @command{sed} to the list of allowed commands.
16350 (service tailon-service-type
16351 (tailon-configuration
16353 (tailon-configuration-file
16354 (allowed-commands '("tail" "grep" "awk" "sed"))))))
16358 @deftp {Data Type} tailon-configuration
16359 Data type representing the configuration of Tailon. This type has the
16360 following parameters:
16363 @item @code{config-file} (default: @code{(tailon-configuration-file)})
16364 The configuration file to use for Tailon. This can be set to a
16365 @dfn{tailon-configuration-file} record value, or any gexp
16366 (@pxref{G-Ausdrücke}).
16368 For example, to instead use a local file, the @code{local-file} function can
16372 (service tailon-service-type
16373 (tailon-configuration
16374 (config-file (local-file "./my-tailon.conf"))))
16377 @item @code{package} (default: @code{tailon})
16378 The tailon package to use.
16383 @deftp {Data Type} tailon-configuration-file
16384 Data type representing the configuration options for Tailon. This type has
16385 the following parameters:
16388 @item @code{files} (default: @code{(list "/var/log")})
16389 List of files to display. The list can include strings for a single file or
16390 directory, or a list, where the first item is the name of a subsection, and
16391 the remaining items are the files or directories in that subsection.
16393 @item @code{bind} (default: @code{"localhost:8080"})
16394 Address and port to which Tailon should bind on.
16396 @item @code{relative-root} (default: @code{#f})
16397 URL path to use for Tailon, set to @code{#f} to not use a path.
16399 @item @code{allow-transfers?} (default: @code{#t})
16400 Allow downloading the log files in the web interface.
16402 @item @code{follow-names?} (default: @code{#t})
16403 Allow tailing of not-yet existent files.
16405 @item @code{tail-lines} (default: @code{200})
16406 Number of lines to read initially from each file.
16408 @item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")})
16409 Commands to allow running. By default, @code{sed} is disabled.
16411 @item @code{debug?} (default: @code{#f})
16412 Set @code{debug?} to @code{#t} to show debug messages.
16414 @item @code{wrap-lines} (default: @code{#t})
16415 Initial line wrapping state in the web interface. Set to @code{#t} to
16416 initially wrap lines (the default), or to @code{#f} to initially not wrap
16419 @item @code{http-auth} (default: @code{#f})
16420 HTTP authentication type to use. Set to @code{#f} to disable authentication
16421 (the default). Supported values are @code{"digest"} or @code{"basic"}.
16423 @item @code{users} (default: @code{#f})
16424 If HTTP authentication is enabled (see @code{http-auth}), access will be
16425 restricted to the credentials provided here. To configure users, use a list
16426 of pairs, where the first element of the pair is the username, and the 2nd
16427 element of the pair is the password.
16430 (tailon-configuration-file
16431 (http-auth "basic")
16432 (users '(("user1" . "password1")
16433 ("user2" . "password2"))))
16440 @subsubheading Darkstat Service
16442 Darkstat is a packet sniffer that captures network traffic, calculates
16443 statistics about usage, and serves reports over HTTP.
16445 @defvar {Scheme Variable} darkstat-service-type
16446 This is the service type for the @uref{https://unix4lyfe.org/darkstat/,
16447 darkstat} service, its value must be a @code{darkstat-configuration} record
16448 as in this example:
16451 (service darkstat-service-type
16452 (darkstat-configuration
16453 (interface "eno1")))
16457 @deftp {Data Type} darkstat-configuration
16458 Data type representing the configuration of @command{darkstat}.
16461 @item @code{package} (default: @code{darkstat})
16462 The darkstat package to use.
16464 @item @code{interface}
16465 Capture traffic on the specified network interface.
16467 @item @code{port} (default: @code{"667"})
16468 Bind the web interface to the specified port.
16470 @item @code{bind-address} (default: @code{"127.0.0.1"})
16471 Bind the web interface to the specified address.
16473 @item @code{base} (default: @code{"/"})
16474 Specify the path of the base URL. This can be useful if @command{darkstat}
16475 is accessed via a reverse proxy.
16480 @subsubheading Prometheus Node Exporter Service
16482 @cindex prometheus-node-exporter
16483 The Prometheus ``node exporter'' makes hardware and operating system
16484 statistics provided by the Linux kernel available for the Prometheus
16485 monitoring system. This service should be deployed on all physical nodes
16486 and virtual machines, where monitoring these statistics is desirable.
16488 @defvar {Scheme variable} prometheus-node-exporter-service-type
16489 This is the service type for the
16490 @uref{https://github.com/prometheus/node_exporter/,
16491 prometheus-node-exporter} service, its value must be a
16492 @code{prometheus-node-exporter-configuration} record as in this example:
16495 (service prometheus-node-exporter-service-type
16496 (prometheus-node-exporter-configuration
16497 (web-listen-address ":9100")))
16501 @deftp {Data Type} prometheus-node-exporter-configuration
16502 Data type representing the configuration of @command{node_exporter}.
16505 @item @code{package} (default: @code{go-github-com-prometheus-node-exporter})
16506 The prometheus-node-exporter package to use.
16508 @item @code{web-listen-address} (default: @code{":9100"})
16509 Bind the web interface to the specified address.
16514 @node Kerberos-Dienste
16515 @subsubsection Kerberos-Dienste
16518 The @code{(gnu services kerberos)} module provides services relating to the
16519 authentication protocol @dfn{Kerberos}.
16521 @subsubheading Krb5 Service
16523 Programs using a Kerberos client library normally expect a configuration
16524 file in @file{/etc/krb5.conf}. This service generates such a file from a
16525 definition provided in the operating system declaration. It does not cause
16526 any daemon to be started.
16528 No ``keytab'' files are provided by this service---you must explicitly
16529 create them. This service is known to work with the MIT client library,
16530 @code{mit-krb5}. Other implementations have not been tested.
16532 @defvr {Scheme Variable} krb5-service-type
16533 A service type for Kerberos 5 clients.
16537 Here is an example of its use:
16539 (service krb5-service-type
16540 (krb5-configuration
16541 (default-realm "EXAMPLE.COM")
16542 (allow-weak-crypto? #t)
16545 (name "EXAMPLE.COM")
16546 (admin-server "groucho.example.com")
16547 (kdc "karl.example.com"))
16550 (admin-server "kerb-admin.argrx.edu")
16551 (kdc "keys.argrx.edu"))))))
16555 This example provides a Kerberos@tie{}5 client configuration which:
16557 @item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both
16558 of which have distinct administration servers and key distribution centers;
16559 @item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly
16560 specified by clients;
16561 @item Accepts services which only support encryption types known to be weak.
16564 The @code{krb5-realm} and @code{krb5-configuration} types have many fields.
16565 Only the most commonly used ones are described here. For a full list, and
16566 more detailed explanation of each, see the MIT
16567 @uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf}
16571 @deftp {Data Type} krb5-realm
16572 @cindex realm, kerberos
16575 This field is a string identifying the name of the realm. A common
16576 convention is to use the fully qualified DNS name of your organization,
16577 converted to upper case.
16579 @item @code{admin-server}
16580 This field is a string identifying the host where the administration server
16584 This field is a string identifying the key distribution center for the
16589 @deftp {Data Type} krb5-configuration
16592 @item @code{allow-weak-crypto?} (default: @code{#f})
16593 If this flag is @code{#t} then services which only offer encryption
16594 algorithms known to be weak will be accepted.
16596 @item @code{default-realm} (default: @code{#f})
16597 This field should be a string identifying the default Kerberos realm for the
16598 client. You should set this field to the name of your Kerberos realm. If
16599 this value is @code{#f} then a realm must be specified with every Kerberos
16600 principal when invoking programs such as @command{kinit}.
16602 @item @code{realms}
16603 This should be a non-empty list of @code{krb5-realm} objects, which clients
16604 may access. Normally, one of them will have a @code{name} field matching
16605 the @code{default-realm} field.
16610 @subsubheading PAM krb5 Service
16613 The @code{pam-krb5} service allows for login authentication and password
16614 management via Kerberos. You will need this service if you want PAM enabled
16615 applications to authenticate users using Kerberos.
16617 @defvr {Scheme Variable} pam-krb5-service-type
16618 A service type for the Kerberos 5 PAM module.
16621 @deftp {Data Type} pam-krb5-configuration
16622 Data type representing the configuration of the Kerberos 5 PAM module This
16623 type has the following parameters:
16625 @item @code{pam-krb5} (default: @code{pam-krb5})
16626 The pam-krb5 package to use.
16628 @item @code{minimum-uid} (default: @code{1000})
16629 The smallest user ID for which Kerberos authentications should be
16630 attempted. Local accounts with lower values will silently fail to
16637 @subsubsection Web-Dienste
16642 The @code{(gnu services web)} module provides the Apache HTTP Server, the
16643 nginx web server, and also a fastcgi wrapper daemon.
16645 @subsubheading Apache HTTP Server
16647 @deffn {Scheme Variable} httpd-service-type
16648 Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server
16649 (@dfn{httpd}). The value for this service type is a
16650 @code{httpd-configuration} record.
16652 A simple example configuration is given below.
16655 (service httpd-service-type
16656 (httpd-configuration
16659 (server-name "www.example.com")
16660 (document-root "/srv/http/www.example.com")))))
16663 Other services can also extend the @code{httpd-service-type} to add to the
16667 (simple-service 'my-extra-server httpd-service-type
16671 (list (string-append
16672 "ServerName "www.example.com
16673 DocumentRoot \"/srv/http/www.example.com\"")))))
16677 The details for the @code{httpd-configuration}, @code{httpd-module},
16678 @code{httpd-config-file} and @code{httpd-virtualhost} record types are given
16681 @deffn {Data Type} httpd-configuration
16682 This data type represents the configuration for the httpd service.
16685 @item @code{package} (default: @code{httpd})
16686 The httpd package to use.
16688 @item @code{pid-file} (default: @code{"/var/run/httpd"})
16689 The pid file used by the shepherd-service.
16691 @item @code{config} (default: @code{(httpd-config-file)})
16692 The configuration file to use with the httpd service. The default value is a
16693 @code{httpd-config-file} record, but this can also be a different
16694 G-expression that generates a file, for example a @code{plain-file}. A file
16695 outside of the store can also be specified through a string.
16700 @deffn {Data Type} httpd-module
16701 This data type represents a module for the httpd service.
16705 The name of the module.
16708 The file for the module. This can be relative to the httpd package being
16709 used, the absolute location of a file, or a G-expression for a file within
16710 the store, for example @code{(file-append mod-wsgi "/modules/mod_wsgi.so")}.
16715 @defvr {Scheme Variable} %default-httpd-modules
16716 A default list of @code{httpd-module} objects.
16719 @deffn {Data Type} httpd-config-file
16720 This data type represents a configuration file for the httpd service.
16723 @item @code{modules} (default: @code{%default-httpd-modules})
16724 The modules to load. Additional modules can be added here, or loaded by
16725 additional configuration.
16727 For example, in order to handle requests for PHP files, you can use Apache’s
16728 @code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}:
16731 (service httpd-service-type
16732 (httpd-configuration
16737 (name "proxy_module")
16738 (file "modules/mod_proxy.so"))
16740 (name "proxy_fcgi_module")
16741 (file "modules/mod_proxy_fcgi.so"))
16742 %default-httpd-modules))
16743 (extra-config (list "\
16744 <FilesMatch \\.php$>
16745 SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
16746 </FilesMatch>"))))))
16747 (service php-fpm-service-type
16748 (php-fpm-configuration
16749 (socket "/var/run/php-fpm.sock")
16750 (socket-group "httpd")))
16753 @item @code{server-root} (default: @code{httpd})
16754 The @code{ServerRoot} in the configuration file, defaults to the httpd
16755 package. Directives including @code{Include} and @code{LoadModule} are taken
16756 as relative to the server root.
16758 @item @code{server-name} (default: @code{#f})
16759 The @code{ServerName} in the configuration file, used to specify the request
16760 scheme, hostname and port that the server uses to identify itself.
16762 This doesn't need to be set in the server config, and can be specifyed in
16763 virtual hosts. The default is @code{#f} to not specify a @code{ServerName}.
16765 @item @code{document-root} (default: @code{"/srv/http"})
16766 The @code{DocumentRoot} from which files will be served.
16768 @item @code{listen} (default: @code{'("80")})
16769 The list of values for the @code{Listen} directives in the config file. The
16770 value should be a list of strings, when each string can specify the port
16771 number to listen on, and optionally the IP address and protocol to use.
16773 @item @code{pid-file} (default: @code{"/var/run/httpd"})
16774 The @code{PidFile} to use. This should match the @code{pid-file} set in the
16775 @code{httpd-configuration} so that the Shepherd service is configured
16778 @item @code{error-log} (default: @code{"/var/log/httpd/error_log"})
16779 The @code{ErrorLog} to which the server will log errors.
16781 @item @code{user} (default: @code{"httpd"})
16782 The @code{User} which the server will answer requests as.
16784 @item @code{group} (default: @code{"httpd"})
16785 The @code{Group} which the server will answer requests as.
16787 @item @code{extra-config} (default: @code{(list "TypesConfig etc/httpd/mime.types")})
16788 A flat list of strings and G-expressions which will be added to the end of
16789 the configuration file.
16791 Any values which the service is extended with will be appended to this list.
16796 @deffn {Data Type} httpd-virtualhost
16797 This data type represents a virtualhost configuration block for the httpd
16800 These should be added to the extra-config for the httpd-service.
16803 (simple-service 'my-extra-server httpd-service-type
16807 (list (string-append
16808 "ServerName "www.example.com
16809 DocumentRoot \"/srv/http/www.example.com\"")))))
16813 @item @code{addresses-and-ports}
16814 The addresses and ports for the @code{VirtualHost} directive.
16816 @item @code{contents}
16817 The contents of the @code{VirtualHost} directive, this should be a list of
16818 strings and G-expressions.
16823 @subsubheading NGINX
16825 @deffn {Scheme Variable} nginx-service-type
16826 Service type for the @uref{https://nginx.org/,NGinx} web server. The value
16827 for this service type is a @code{<nginx-configuration>} record.
16829 A simple example configuration is given below.
16832 (service nginx-service-type
16833 (nginx-configuration
16835 (list (nginx-server-configuration
16836 (server-name '("www.example.com"))
16837 (root "/srv/http/www.example.com"))))))
16840 In addition to adding server blocks to the service configuration directly,
16841 this service can be extended by other services to add server blocks, as in
16845 (simple-service 'my-extra-server nginx-service-type
16846 (list (nginx-server-configuration
16847 (root "/srv/http/extra-website")
16848 (try-files (list "$uri" "$uri/index.html")))))
16852 At startup, @command{nginx} has not yet read its configuration file, so it
16853 uses a default file to log error messages. If it fails to load its
16854 configuration file, that is where error messages are logged. After the
16855 configuration file is loaded, the default error log file changes as per
16856 configuration. In our case, startup error messages can be found in
16857 @file{/var/run/nginx/logs/error.log}, and after configuration in
16858 @file{/var/log/nginx/error.log}. The second location can be changed with
16859 the @var{log-directory} configuration option.
16861 @deffn {Data Type} nginx-configuration
16862 This data type represents the configuration for NGinx. Some configuration
16863 can be done through this and the other provided record types, or
16864 alternatively, a config file can be provided.
16867 @item @code{nginx} (default: @code{nginx})
16868 The nginx package to use.
16870 @item @code{log-directory} (default: @code{"/var/log/nginx"})
16871 The directory to which NGinx will write log files.
16873 @item @code{run-directory} (default: @code{"/var/run/nginx"})
16874 The directory in which NGinx will create a pid file, and write temporary
16877 @item @code{server-blocks} (default: @code{'()})
16878 A list of @dfn{server blocks} to create in the generated configuration file,
16879 the elements should be of type @code{<nginx-server-configuration>}.
16881 The following example would setup NGinx to serve @code{www.example.com} from
16882 the @code{/srv/http/www.example.com} directory, without using HTTPS.
16884 (service nginx-service-type
16885 (nginx-configuration
16887 (list (nginx-server-configuration
16888 (server-name '("www.example.com"))
16889 (root "/srv/http/www.example.com"))))))
16892 @item @code{upstream-blocks} (default: @code{'()})
16893 A list of @dfn{upstream blocks} to create in the generated configuration
16894 file, the elements should be of type @code{<nginx-upstream-configuration>}.
16896 Configuring upstreams through the @code{upstream-blocks} can be useful when
16897 combined with @code{locations} in the @code{<nginx-server-configuration>}
16898 records. The following example creates a server configuration with one
16899 location configuration, that will proxy requests to a upstream
16900 configuration, which will handle requests with two servers.
16905 (nginx-configuration
16907 (list (nginx-server-configuration
16908 (server-name '("www.example.com"))
16909 (root "/srv/http/www.example.com")
16912 (nginx-location-configuration
16914 (body '("proxy_pass http://server-proxy;"))))))))
16916 (list (nginx-upstream-configuration
16917 (name "server-proxy")
16918 (servers (list "server1.example.com"
16919 "server2.example.com")))))))
16922 @item @code{file} (default: @code{#f})
16923 If a configuration @var{file} is provided, this will be used, rather than
16924 generating a configuration file from the provided @code{log-directory},
16925 @code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For
16926 proper operation, these arguments should match what is in @var{file} to
16927 ensure that the directories are created when the service is activated.
16929 This can be useful if you have an existing configuration file, or it's not
16930 possible to do what is required through the other parts of the
16931 nginx-configuration record.
16933 @item @code{server-names-hash-bucket-size} (default: @code{#f})
16934 Bucket size for the server names hash tables, defaults to @code{#f} to use
16935 the size of the processors cache line.
16937 @item @code{server-names-hash-bucket-max-size} (default: @code{#f})
16938 Maximum bucket size for the server names hash tables.
16940 @item @code{extra-content} (default: @code{""})
16941 Extra content for the @code{http} block. Should be string or a string
16942 valued G-expression.
16947 @deftp {Data Type} nginx-server-configuration
16948 Data type representing the configuration of an nginx server block. This
16949 type has the following parameters:
16952 @item @code{listen} (default: @code{'("80" "443 ssl")})
16953 Each @code{listen} directive sets the address and port for IP, or the path
16954 for a UNIX-domain socket on which the server will accept requests. Both
16955 address and port, or only address or only port can be specified. An address
16956 may also be a hostname, for example:
16959 '("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")
16962 @item @code{server-name} (default: @code{(list 'default)})
16963 A list of server names this server represents. @code{'default} represents
16964 the default server for connections matching no other server.
16966 @item @code{root} (default: @code{"/srv/http"})
16967 Root of the website nginx will serve.
16969 @item @code{locations} (default: @code{'()})
16970 A list of @dfn{nginx-location-configuration} or
16971 @dfn{nginx-named-location-configuration} records to use within this server
16974 @item @code{index} (default: @code{(list "index.html")})
16975 Index files to look for when clients ask for a directory. If it cannot be
16976 found, Nginx will send the list of files in the directory.
16978 @item @code{try-files} (default: @code{'()})
16979 A list of files whose existence is checked in the specified order.
16980 @code{nginx} will use the first file it finds to process the request.
16982 @item @code{ssl-certificate} (default: @code{#f})
16983 Where to find the certificate for secure connections. Set it to @code{#f}
16984 if you don't have a certificate or you don't want to use HTTPS.
16986 @item @code{ssl-certificate-key} (default: @code{#f})
16987 Where to find the private key for secure connections. Set it to @code{#f}
16988 if you don't have a key or you don't want to use HTTPS.
16990 @item @code{server-tokens?} (default: @code{#f})
16991 Whether the server should add its configuration to response.
16993 @item @code{raw-content} (default: @code{'()})
16994 A list of raw lines added to the server block.
16999 @deftp {Data Type} nginx-upstream-configuration
17000 Data type representing the configuration of an nginx @code{upstream} block.
17001 This type has the following parameters:
17005 Name for this group of servers.
17007 @item @code{servers}
17008 Specify the addresses of the servers in the group. The address can be
17009 specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name (e.g.@:
17010 @samp{backend1.example.com}) or a path to a UNIX socket using the prefix
17011 @samp{unix:}. For addresses using an IP address or domain name, the default
17012 port is 80, and a different port can be specified explicitly.
17017 @deftp {Data Type} nginx-location-configuration
17018 Data type representing the configuration of an nginx @code{location} block.
17019 This type has the following parameters:
17023 URI which this location block matches.
17025 @anchor{nginx-location-configuration body}
17027 Body of the location block, specified as a list of strings. This can contain
17028 many configuration directives. For example, to pass requests to a upstream
17029 server group defined using an @code{nginx-upstream-configuration} block, the
17030 following directive would be specified in the body @samp{(list "proxy_pass
17031 http://upstream-name;")}.
17036 @deftp {Data Type} nginx-named-location-configuration
17037 Data type representing the configuration of an nginx named location block.
17038 Named location blocks are used for request redirection, and not used for
17039 regular request processing. This type has the following parameters:
17043 Name to identify this location block.
17046 @xref{nginx-location-configuration body}, as the body for named location
17047 blocks can be used in a similar way to the
17048 @code{nginx-location-configuration body}. One restriction is that the body
17049 of a named location block cannot contain location blocks.
17054 @subsubheading Varnish Cache
17056 Varnish is a fast cache server that sits in between web applications and end
17057 users. It proxies requests from clients and caches the accessed URLs such
17058 that multiple requests for the same resource only creates one request to the
17061 @defvr {Scheme Variable} varnish-service-type
17062 Service type for the Varnish daemon.
17065 @deftp {Data Type} varnish-configuration
17066 Data type representing the @code{varnish} service configuration. This type
17067 has the following parameters:
17070 @item @code{package} (default: @code{varnish})
17071 The Varnish package to use.
17073 @item @code{name} (default: @code{"default"})
17074 A name for this Varnish instance. Varnish will create a directory in
17075 @file{/var/varnish/} with this name and keep temporary files there. If the
17076 name starts with a forward slash, it is interpreted as an absolute directory
17079 Pass the @code{-n} argument to other Varnish programs to connect to the
17080 named instance, e.g.@: @command{varnishncsa -n default}.
17082 @item @code{backend} (default: @code{"localhost:8080"})
17083 The backend to use. This option has no effect if @code{vcl} is set.
17085 @item @code{vcl} (default: #f)
17086 The @dfn{VCL} (Varnish Configuration Language) program to run. If this is
17087 @code{#f}, Varnish will proxy @code{backend} using the default
17088 configuration. Otherwise this must be a file-like object with valid VCL
17091 @c Varnish does not support HTTPS, so keep this URL to avoid confusion.
17092 For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you can
17093 do something along these lines:
17096 (define %gnu-mirror
17100 backend gnu @{ .host = "www.gnu.org"; @}"))
17104 (services (cons (service varnish-service-type
17105 (varnish-configuration
17107 (vcl %gnu-mirror)))
17111 The configuration of an already running Varnish instance can be inspected
17112 and changed using the @command{varnishadm} program.
17114 Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and
17115 @url{https://book.varnish-software.com/4.0/,Varnish Book} for comprehensive
17116 documentation on Varnish and its configuration language.
17118 @item @code{listen} (default: @code{'("localhost:80")})
17119 List of addresses Varnish will listen on.
17121 @item @code{storage} (default: @code{'("malloc,128m")})
17122 List of storage backends that will be available in VCL.
17124 @item @code{parameters} (default: @code{'()})
17125 List of run-time parameters in the form @code{'(("parameter" . "value"))}.
17127 @item @code{extra-options} (default: @code{'()})
17128 Additional arguments to pass to the @command{varnishd} process.
17133 @subsubheading FastCGI
17136 FastCGI is an interface between the front-end and the back-end of a web
17137 service. It is a somewhat legacy facility; new web services should
17138 generally just talk HTTP between the front-end and the back-end. However
17139 there are a number of back-end services such as PHP or the optimized HTTP
17140 Git repository access that use FastCGI, so we have support for it in Guix.
17142 To use FastCGI, you configure the front-end web server (e.g., nginx) to
17143 dispatch some subset of its requests to the fastcgi backend, which listens
17144 on a local TCP or UNIX socket. There is an intermediary @code{fcgiwrap}
17145 program that sits between the actual backend process and the web server.
17146 The front-end indicates which backend program to run, passing that
17147 information to the @code{fcgiwrap} process.
17149 @defvr {Scheme Variable} fcgiwrap-service-type
17150 A service type for the @code{fcgiwrap} FastCGI proxy.
17153 @deftp {Data Type} fcgiwrap-configuration
17154 Data type representing the configuration of the @code{fcgiwrap} serice.
17155 This type has the following parameters:
17157 @item @code{package} (default: @code{fcgiwrap})
17158 The fcgiwrap package to use.
17160 @item @code{socket} (default: @code{tcp:127.0.0.1:9000})
17161 The socket on which the @code{fcgiwrap} process should listen, as a string.
17162 Valid @var{socket} values include @code{unix:@var{/path/to/unix/socket}},
17163 @code{tcp:@var{dot.ted.qu.ad}:@var{port}} and
17164 @code{tcp6:[@var{ipv6_addr}]:port}.
17166 @item @code{user} (default: @code{fcgiwrap})
17167 @itemx @code{group} (default: @code{fcgiwrap})
17168 The user and group names, as strings, under which to run the @code{fcgiwrap}
17169 process. The @code{fastcgi} service will ensure that if the user asks for
17170 the specific user or group names @code{fcgiwrap} that the corresponding user
17171 and/or group is present on the system.
17173 It is possible to configure a FastCGI-backed web service to pass HTTP
17174 authentication information from the front-end to the back-end, and to allow
17175 @code{fcgiwrap} to run the back-end process as a corresponding local user.
17176 To enable this capability on the back-end., run @code{fcgiwrap} as the
17177 @code{root} user and group. Note that this capability also has to be
17178 configured on the front-end as well.
17183 PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI
17184 implementation with some additional features useful for sites of any size.
17186 These features include:
17188 @item Adaptive process spawning
17189 @item Basic statistics (similar to Apache's mod_status)
17190 @item Advanced process management with graceful stop/start
17191 @item Ability to start workers with different uid/gid/chroot/environment
17192 and different php.ini (replaces safe_mode)
17193 @item Stdout & stderr logging
17194 @item Emergency restart in case of accidental opcode cache destruction
17195 @item Accelerated upload support
17196 @item Support for a "slowlog"
17197 @item Enhancements to FastCGI, such as fastcgi_finish_request() -
17198 a special function to finish request & flush all data while continuing to do
17199 something time-consuming (video converting, stats processing, etc.)
17201 ...@: and much more.
17203 @defvr {Scheme Variable} php-fpm-service-type
17204 A Service type for @code{php-fpm}.
17207 @deftp {Data Type} php-fpm-configuration
17208 Data Type for php-fpm service configuration.
17210 @item @code{php} (default: @code{php})
17211 The php package to use.
17212 @item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")})
17213 The address on which to accept FastCGI requests. Valid syntaxes are:
17215 @item @code{"ip.add.re.ss:port"}
17216 Listen on a TCP socket to a specific address on a specific port.
17217 @item @code{"port"}
17218 Listen on a TCP socket to all addresses on a specific port.
17219 @item @code{"/path/to/unix/socket"}
17220 Listen on a unix socket.
17223 @item @code{user} (default: @code{php-fpm})
17224 User who will own the php worker processes.
17225 @item @code{group} (default: @code{php-fpm})
17226 Group of the worker processes.
17227 @item @code{socket-user} (default: @code{php-fpm})
17228 User who can speak to the php-fpm socket.
17229 @item @code{socket-group} (default: @code{php-fpm})
17230 Group that can speak to the php-fpm socket.
17231 @item @code{pid-file} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid")})
17232 The process id of the php-fpm process is written to this file once the
17233 service has started.
17234 @item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")})
17235 Log for the php-fpm master process.
17236 @item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)})
17237 Detailed settings for the php-fpm process manager. Must be either:
17239 @item @code{<php-fpm-dynamic-process-manager-configuration>}
17240 @item @code{<php-fpm-static-process-manager-configuration>}
17241 @item @code{<php-fpm-on-demand-process-manager-configuration>}
17243 @item @code{display-errors} (default @code{#f})
17244 Determines whether php errors and warning should be sent to clients and
17245 displayed in their browsers. This is useful for local php development, but
17246 a security risk for public sites, as error messages can reveal passwords and
17248 @item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")})
17249 This file will log the @code{stderr} outputs of php worker processes. Can
17250 be set to @code{#f} to disable logging.
17251 @item @code{file} (default @code{#f})
17252 An optional override of the whole configuration. You can use the
17253 @code{mixed-text-file} function or an absolute filepath for it.
17257 @deftp {Data type} php-fpm-dynamic-process-manager-configuration
17258 Data Type for the @code{dynamic} php-fpm process manager. With the
17259 @code{dynamic} process manager, spare worker processes are kept around based
17260 on it's configured limits.
17262 @item @code{max-children} (default: @code{5})
17263 Maximum of worker processes.
17264 @item @code{start-servers} (default: @code{2})
17265 How many worker processes should be started on start-up.
17266 @item @code{min-spare-servers} (default: @code{1})
17267 How many spare worker processes should be kept around at minimum.
17268 @item @code{max-spare-servers} (default: @code{3})
17269 How many spare worker processes should be kept around at maximum.
17273 @deftp {Data type} php-fpm-static-process-manager-configuration
17274 Data Type for the @code{static} php-fpm process manager. With the
17275 @code{static} process manager, an unchanging number of worker processes are
17278 @item @code{max-children} (default: @code{5})
17279 Maximum of worker processes.
17283 @deftp {Data type} php-fpm-on-demand-process-manager-configuration
17284 Data Type for the @code{on-demand} php-fpm process manager. With the
17285 @code{on-demand} process manager, worker processes are only created as
17288 @item @code{max-children} (default: @code{5})
17289 Maximum of worker processes.
17290 @item @code{process-idle-timeout} (default: @code{10})
17291 The time in seconds after which a process with no requests is killed.
17296 @deffn {Scheme Procedure} nginx-php-fpm-location @
17297 [#:nginx-package nginx] @ [socket (string-append "/var/run/php" @
17298 (version-major (package-version php)) @ "-fpm.sock")] A helper function to
17299 quickly add php to an @code{nginx-server-configuration}.
17302 A simple services setup for nginx with php can look like this:
17304 (services (cons* (service dhcp-client-service-type)
17305 (service php-fpm-service-type)
17306 (service nginx-service-type
17307 (nginx-server-configuration
17308 (server-name '("example.com"))
17309 (root "/srv/http/")
17311 (list (nginx-php-location)))
17313 (ssl-certificate #f)
17314 (ssl-certificate-key #f)))
17318 @cindex cat-avatar-generator
17319 The cat avatar generator is a simple service to demonstrate the use of
17320 php-fpm in @code{Nginx}. It is used to generate cat avatar from a seed, for
17321 instance the hash of a user's email address.
17323 @deffn {Scheme Procedure} cat-avatar-generator-serice @
17324 [#:cache-dir "/var/cache/cat-avatar-generator"] @ [#:package
17325 cat-avatar-generator] @ [#:configuration (nginx-server-configuration)]
17326 Returns an nginx-server-configuration that inherits @code{configuration}.
17327 It extends the nginx configuration to add a server block that serves
17328 @code{package}, a version of cat-avatar-generator. During execution,
17329 cat-avatar-generator will be able to use @code{cache-dir} as its cache
17333 A simple setup for cat-avatar-generator can look like this:
17335 (services (cons* (cat-avatar-generator-service
17337 (nginx-server-configuration
17338 (server-name '("example.com"))))
17343 @subsubheading Hpcguix-web
17345 @cindex hpcguix-web
17346 The @uref{hpcguix-web, https://github.com/UMCUGenetics/hpcguix-web/} program
17347 is a customizable web interface to browse Guix packages, initially designed
17348 for users of high-performance computing (HPC) clusters.
17350 @defvr {Scheme Variable} hpcguix-web-service-type
17351 The service type for @code{hpcguix-web}.
17354 @deftp {Data Type} hpcguix-web-configuration
17355 Data type for the hpcguix-web service configuration.
17359 A gexp (@pxref{G-Ausdrücke}) specifying the hpcguix-web service
17360 configuration. The main items available in this spec are:
17363 @item @code{title-prefix} (default: @code{"hpcguix | "})
17364 The page title prefix.
17366 @item @code{guix-command} (default: @code{"guix"})
17367 The @command{guix} command.
17369 @item @code{package-filter-proc} (default: @code{(const #t)})
17370 A procedure specifying how to filter packages that are displayed.
17372 @item @code{package-page-extension-proc} (default: @code{(const '())})
17373 Extension package for @code{hpcguix-web}.
17375 @item @code{menu} (default: @code{'()})
17376 Additional entry in page @code{menu}.
17378 @item @code{channels} (default: @code{%default-channels})
17379 List of channels from which the package list is built (@pxref{Channels}).
17381 @item @code{package-list-expiration} (default: @code{(* 12 3600)})
17382 The expiration time, in seconds, after which the package list is rebuilt
17383 from the latest instances of the given channels.
17386 See the hpcguix-web repository for a
17387 @uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm,
17390 @item @code{package} (default: @code{hpcguix-web})
17391 The hpcguix-web package to use.
17395 A typical hpcguix-web service declaration looks like this:
17398 (service hpcguix-web-service-type
17399 (hpcguix-web-configuration
17401 #~(define site-config
17402 (hpcweb-configuration
17403 (title-prefix "Guix-HPC - ")
17404 (menu '(("/about" "ABOUT"))))))))
17407 @quotation Anmerkung
17408 The hpcguix-web service periodically updates the package list it publishes
17409 by pulling channels from Git. To that end, it needs to access X.509
17410 certificates so that it can authenticate Git servers when communicating over
17411 HTTPS, and it assumes that @file{/etc/ssl/certs} contains those
17414 Thus, make sure to add @code{nss-certs} or another certificate package to
17415 the @code{packages} field of your configuration. @ref{X.509-Zertifikate},
17416 for more information on X.509 certificates.
17419 @node Zertifikatsdienste
17420 @subsubsection Zertifikatsdienste
17423 @cindex HTTP, HTTPS
17424 @cindex Let's Encrypt
17425 @cindex TLS certificates
17426 The @code{(gnu services certbot)} module provides a service to automatically
17427 obtain a valid TLS certificate from the Let's Encrypt certificate
17428 authority. These certificates can then be used to serve content securely
17429 over HTTPS or other TLS-based protocols, with the knowledge that the client
17430 will be able to verify the server's authenticity.
17432 @url{https://letsencrypt.org/, Let's Encrypt} provides the @code{certbot}
17433 tool to automate the certification process. This tool first securely
17434 generates a key on the server. It then makes a request to the Let's Encrypt
17435 certificate authority (CA) to sign the key. The CA checks that the request
17436 originates from the host in question by using a challenge-response protocol,
17437 requiring the server to provide its response over HTTP. If that protocol
17438 completes successfully, the CA signs the key, resulting in a certificate.
17439 That certificate is valid for a limited period of time, and therefore to
17440 continue to provide TLS services, the server needs to periodically ask the
17441 CA to renew its signature.
17443 The certbot service automates this process: the initial key generation, the
17444 initial certification request to the Let's Encrypt service, the web server
17445 challenge/response integration, writing the certificate to disk, the
17446 automated periodic renewals, and the deployment tasks associated with the
17447 renewal (e.g.@: reloading services, copying keys with different
17450 Certbot is run twice a day, at a random minute within the hour. It won't do
17451 anything until your certificates are due for renewal or revoked, but running
17452 it regularly would give your service a chance of staying online in case a
17453 Let's Encrypt-initiated revocation happened for some reason.
17455 By using this service, you agree to the ACME Subscriber Agreement, which can
17456 be found there: @url{https://acme-v01.api.letsencrypt.org/directory}.
17458 @defvr {Scheme Variable} certbot-service-type
17459 A service type for the @code{certbot} Let's Encrypt client. Its value must
17460 be a @code{certbot-configuration} record as in this example:
17463 (define %nginx-deploy-hook
17465 "nginx-deploy-hook"
17466 #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read)))
17467 (kill pid SIGHUP))))
17469 (service certbot-service-type
17470 (certbot-configuration
17471 (email "foo@@example.net")
17474 (certificate-configuration
17475 (domains '("example.net" "www.example.net"))
17476 (deploy-hook %nginx-deploy-hook))
17477 (certificate-configuration
17478 (domains '("bar.example.net")))))))
17481 See below for details about @code{certbot-configuration}.
17484 @deftp {Data Type} certbot-configuration
17485 Data type representing the configuration of the @code{certbot} service.
17486 This type has the following parameters:
17489 @item @code{package} (default: @code{certbot})
17490 The certbot package to use.
17492 @item @code{webroot} (default: @code{/var/www})
17493 The directory from which to serve the Let's Encrypt challenge/response
17496 @item @code{certificates} (default: @code{()})
17497 A list of @code{certificates-configuration}s for which to generate
17498 certificates and request signatures. Each certificate has a @code{name} and
17499 several @code{domains}.
17502 Mandatory email used for registration, recovery contact, and important
17503 account notifications.
17505 @item @code{rsa-key-size} (default: @code{2048})
17506 Size of the RSA key.
17508 @item @code{default-location} (default: @i{see below})
17509 The default @code{nginx-location-configuration}. Because @code{certbot}
17510 needs to be able to serve challenges and responses, it needs to be able to
17511 run a web server. It does so by extending the @code{nginx} web service with
17512 an @code{nginx-server-configuration} listening on the @var{domains} on port
17513 80, and which has a @code{nginx-location-configuration} for the
17514 @code{/.well-known/} URI path subspace used by Let's Encrypt. @xref{Web-Dienste}, for more on these nginx configuration data types.
17516 Requests to other URL paths will be matched by the @code{default-location},
17517 which if present is added to all @code{nginx-server-configuration}s.
17519 By default, the @code{default-location} will issue a redirect from
17520 @code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving
17521 you to define what to serve on your site via @code{https}.
17523 Pass @code{#f} to not issue a default location.
17527 @deftp {Data Type} certificate-configuration
17528 Data type representing the configuration of a certificate. This type has
17529 the following parameters:
17532 @item @code{name} (default: @i{see below})
17533 This name is used by Certbot for housekeeping and in file paths; it doesn't
17534 affect the content of the certificate itself. To see certificate names, run
17535 @code{certbot certificates}.
17537 Its default is the first provided domain.
17539 @item @code{domains} (default: @code{()})
17540 The first domain provided will be the subject CN of the certificate, and all
17541 domains will be Subject Alternative Names on the certificate.
17543 @item @code{deploy-hook} (default: @code{#f})
17544 Command to be run in a shell once for each successfully issued certificate.
17545 For this command, the shell variable @code{$RENEWED_LINEAGE} will point to
17546 the config live subdirectory (for example,
17547 @samp{"/etc/letsencrypt/live/example.com"}) containing the new certificates
17548 and keys; the shell variable @code{$RENEWED_DOMAINS} will contain a
17549 space-delimited list of renewed certificate domains (for example,
17550 @samp{"example.com www.example.com"}.
17555 For each @code{certificate-configuration}, the certificate is saved to
17556 @code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is saved
17557 to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}.
17559 @subsubsection DNS-Dienste
17560 @cindex DNS (domain name system)
17561 @cindex domain name system (DNS)
17563 The @code{(gnu services dns)} module provides services related to the
17564 @dfn{domain name system} (DNS). It provides a server service for hosting an
17565 @emph{authoritative} DNS server for multiple zones, slave or master. This
17566 service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a caching
17567 and forwarding DNS server for the LAN, which uses
17568 @uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}.
17570 @subsubheading Knot Service
17572 An example configuration of an authoritative server for two zones, one
17573 master and one slave, is:
17576 (define-zone-entries example.org.zone
17577 ;; Name TTL Class Type Data
17578 ("@@" "" "IN" "A" "127.0.0.1")
17579 ("@@" "" "IN" "NS" "ns")
17580 ("ns" "" "IN" "A" "127.0.0.1"))
17582 (define master-zone
17583 (knot-zone-configuration
17584 (domain "example.org")
17586 (origin "example.org")
17587 (entries example.org.zone)))))
17590 (knot-zone-configuration
17591 (domain "plop.org")
17592 (dnssec-policy "default")
17593 (master (list "plop-master"))))
17595 (define plop-master
17596 (knot-remote-configuration
17598 (address (list "208.76.58.171"))))
17602 (services (cons* (service knot-service-type
17603 (knot-configuration
17604 (remotes (list plop-master))
17605 (zones (list master-zone slave-zone))))
17610 @deffn {Scheme Variable} knot-service-type
17611 This is the type for the Knot DNS server.
17613 Knot DNS is an authoritative DNS server, meaning that it can serve multiple
17614 zones, that is to say domain names you would buy from a registrar. This
17615 server is not a resolver, meaning that it can only resolve names for which
17616 it is authoritative. This server can be configured to serve zones as a
17617 master server or a slave server as a per-zone basis. Slave zones will get
17618 their data from masters, and will serve it as an authoritative server. From
17619 the point of view of a resolver, there is no difference between master and
17622 The following data types are used to configure the Knot DNS server:
17625 @deftp {Data Type} knot-key-configuration
17626 Data type representing a key. This type has the following parameters:
17629 @item @code{id} (default: @code{""})
17630 An identifier for other configuration fields to refer to this key. IDs must
17631 be unique and must not be empty.
17633 @item @code{algorithm} (default: @code{#f})
17634 The algorithm to use. Choose between @code{#f}, @code{'hmac-md5},
17635 @code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256},
17636 @code{'hmac-sha384} and @code{'hmac-sha512}.
17638 @item @code{secret} (default: @code{""})
17639 The secret key itself.
17644 @deftp {Data Type} knot-acl-configuration
17645 Data type representing an Access Control List (ACL) configuration. This
17646 type has the following parameters:
17649 @item @code{id} (default: @code{""})
17650 An identifier for ether configuration fields to refer to this key. IDs must
17651 be unique and must not be empty.
17653 @item @code{address} (default: @code{'()})
17654 An ordered list of IP addresses, network subnets, or network ranges
17655 represented with strings. The query must match one of them. Empty value
17656 means that address match is not required.
17658 @item @code{key} (default: @code{'()})
17659 An ordered list of references to keys represented with strings. The string
17660 must match a key ID defined in a @code{knot-key-configuration}. No key
17661 means that a key is not require to match that ACL.
17663 @item @code{action} (default: @code{'()})
17664 An ordered list of actions that are permitted or forbidden by this ACL.
17665 Possible values are lists of zero or more elements from @code{'transfer},
17666 @code{'notify} and @code{'update}.
17668 @item @code{deny?} (default: @code{#f})
17669 When true, the ACL defines restrictions. Listed actions are forbidden.
17670 When false, listed actions are allowed.
17675 @deftp {Data Type} zone-entry
17676 Data type represnting a record entry in a zone file. This type has the
17677 following parameters:
17680 @item @code{name} (default: @code{"@@"})
17681 The name of the record. @code{"@@"} refers to the origin of the zone.
17682 Names are relative to the origin of the zone. For example, in the
17683 @code{example.org} zone, @code{"ns.example.org"} actually refers to
17684 @code{ns.example.org.example.org}. Names ending with a dot are absolute,
17685 which means that @code{"ns.example.org."} refers to @code{ns.example.org}.
17687 @item @code{ttl} (default: @code{""})
17688 The Time-To-Live (TTL) of this record. If not set, the default TTL is used.
17690 @item @code{class} (default: @code{"IN"})
17691 The class of the record. Knot currently supports only @code{"IN"} and
17692 partially @code{"CH"}.
17694 @item @code{type} (default: @code{"A"})
17695 The type of the record. Common types include A (IPv4 address), AAAA (IPv6
17696 address), NS (Name Server) and MX (Mail eXchange). Many other types are
17699 @item @code{data} (default: @code{""})
17700 The data contained in the record. For instance an IP address associated
17701 with an A record, or a domain name associated with an NS record. Remember
17702 that domain names are relative to the origin unless they end with a dot.
17707 @deftp {Data Type} zone-file
17708 Data type representing the content of a zone file. This type has the
17709 following parameters:
17712 @item @code{entries} (default: @code{'()})
17713 The list of entries. The SOA record is taken care of, so you don't need to
17714 put it in the list of entries. This list should probably contain an entry
17715 for your primary authoritative DNS server. Other than using a list of
17716 entries directly, you can use @code{define-zone-entries} to define a object
17717 containing the list of entries more easily, that you can later pass to the
17718 @code{entries} field of the @code{zone-file}.
17720 @item @code{origin} (default: @code{""})
17721 The name of your zone. This parameter cannot be empty.
17723 @item @code{ns} (default: @code{"ns"})
17724 The domain of your primary authoritative DNS server. The name is relative
17725 to the origin, unless it ends with a dot. It is mandatory that this primary
17726 DNS server corresponds to an NS record in the zone and that it is associated
17727 to an IP address in the list of entries.
17729 @item @code{mail} (default: @code{"hostmaster"})
17730 An email address people can contact you at, as the owner of the zone. This
17731 is translated as @code{<mail>@@<origin>}.
17733 @item @code{serial} (default: @code{1})
17734 The serial number of the zone. As this is used to keep track of changes by
17735 both slaves and resolvers, it is mandatory that it @emph{never} decreases.
17736 Always increment it when you make a change in your zone.
17738 @item @code{refresh} (default: @code{(* 2 24 3600)})
17739 The frequency at which slaves will do a zone transfer. This value is a
17740 number of seconds. It can be computed by multiplications or with
17741 @code{(string->duration)}.
17743 @item @code{retry} (default: @code{(* 15 60)})
17744 The period after which a slave will retry to contact its master when it
17745 fails to do so a first time.
17747 @item @code{expiry} (default: @code{(* 14 24 3600)})
17748 Default TTL of records. Existing records are considered correct for at most
17749 this amount of time. After this period, resolvers will invalidate their
17750 cache and check again that it still exists.
17752 @item @code{nx} (default: @code{3600})
17753 Default TTL of inexistant records. This delay is usually short because you
17754 want your new domains to reach everyone quickly.
17759 @deftp {Data Type} knot-remote-configuration
17760 Data type representing a remote configuration. This type has the following
17764 @item @code{id} (default: @code{""})
17765 An identifier for other configuration fields to refer to this remote. IDs
17766 must be unique and must not be empty.
17768 @item @code{address} (default: @code{'()})
17769 An ordered list of destination IP addresses. Addresses are tried in
17770 sequence. An optional port can be given with the @@ separator. For
17771 instance: @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53.
17773 @item @code{via} (default: @code{'()})
17774 An ordered list of source IP addresses. An empty list will have Knot choose
17775 an appropriate source IP. An optional port can be given with the @@
17776 separator. The default is to choose at random.
17778 @item @code{key} (default: @code{#f})
17779 A reference to a key, that is a string containing the identifier of a key
17780 defined in a @code{knot-key-configuration} field.
17785 @deftp {Data Type} knot-keystore-configuration
17786 Data type representing a keystore to hold dnssec keys. This type has the
17787 following parameters:
17790 @item @code{id} (default: @code{""})
17791 The id of the keystore. It must not be empty.
17793 @item @code{backend} (default: @code{'pem})
17794 The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}.
17796 @item @code{config} (default: @code{"/var/lib/knot/keys/keys"})
17797 The configuration string of the backend. An example for the PKCS#11 is:
17798 @code{"pkcs11:token=knot;pin-value=1234
17799 /gnu/store/.../lib/pkcs11/libsofthsm2.so"}. For the pem backend, the string
17800 reprensents a path in the file system.
17805 @deftp {Data Type} knot-policy-configuration
17806 Data type representing a dnssec policy. Knot DNS is able to automatically
17807 sign your zones. It can either generate and manage your keys automatically
17808 or use keys that you generate.
17810 Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that
17811 is used to sign the second, and a Zone Signing Key (ZSK) that is used to
17812 sign the zone. In order to be trusted, the KSK needs to be present in the
17813 parent zone (usually a top-level domain). If your registrar supports
17814 dnssec, you will have to send them your KSK's hash so they can add a DS
17815 record in their zone. This is not automated and need to be done each time
17816 you change your KSK.
17818 The policy also defines the lifetime of keys. Usually, ZSK can be changed
17819 easily and use weaker cryptographic functions (they use lower parameters) in
17820 order to sign records quickly, so they are changed often. The KSK however
17821 requires manual interaction with the registrar, so they are changed less
17822 often and use stronger parameters because they sign only one record.
17824 This type has the following parameters:
17827 @item @code{id} (default: @code{""})
17828 The id of the policy. It must not be empty.
17830 @item @code{keystore} (default: @code{"default"})
17831 A reference to a keystore, that is a string containing the identifier of a
17832 keystore defined in a @code{knot-keystore-configuration} field. The
17833 @code{"default"} identifier means the default keystore (a kasp database that
17834 was setup by this service).
17836 @item @code{manual?} (default: @code{#f})
17837 Whether the key management is manual or automatic.
17839 @item @code{single-type-signing?} (default: @code{#f})
17840 When @code{#t}, use the Single-Type Signing Scheme.
17842 @item @code{algorithm} (default: @code{"ecdsap256sha256"})
17843 An algorithm of signing keys and issued signatures.
17845 @item @code{ksk-size} (default: @code{256})
17846 The length of the KSK. Note that this value is correct for the default
17847 algorithm, but would be unsecure for other algorithms.
17849 @item @code{zsk-size} (default: @code{256})
17850 The length of the ZSK. Note that this value is correct for the default
17851 algorithm, but would be unsecure for other algorithms.
17853 @item @code{dnskey-ttl} (default: @code{'default})
17854 The TTL value for DNSKEY records added into zone apex. The special
17855 @code{'default} value means same as the zone SOA TTL.
17857 @item @code{zsk-lifetime} (default: @code{(* 30 24 3600)})
17858 The period between ZSK publication and the next rollover initiation.
17860 @item @code{propagation-delay} (default: @code{(* 24 3600)})
17861 An extra delay added for each key rollover step. This value should be high
17862 enough to cover propagation of data from the master server to all slaves.
17864 @item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)})
17865 A validity period of newly issued signatures.
17867 @item @code{rrsig-refresh} (default: @code{(* 7 24 3600)})
17868 A period how long before a signature expiration the signature will be
17871 @item @code{nsec3?} (default: @code{#f})
17872 When @code{#t}, NSEC3 will be used instead of NSEC.
17874 @item @code{nsec3-iterations} (default: @code{5})
17875 The number of additional times the hashing is performed.
17877 @item @code{nsec3-salt-length} (default: @code{8})
17878 The length of a salt field in octets, which is appended to the original
17879 owner name before hashing.
17881 @item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)})
17882 The validity period of newly issued salt field.
17887 @deftp {Data Type} knot-zone-configuration
17888 Data type representing a zone served by Knot. This type has the following
17892 @item @code{domain} (default: @code{""})
17893 The domain served by this configuration. It must not be empty.
17895 @item @code{file} (default: @code{""})
17896 The file where this zone is saved. This parameter is ignored by master
17897 zones. Empty means default location that depends on the domain name.
17899 @item @code{zone} (default: @code{(zone-file)})
17900 The content of the zone file. This parameter is ignored by slave zones. It
17901 must contain a zone-file record.
17903 @item @code{master} (default: @code{'()})
17904 A list of master remotes. When empty, this zone is a master. When set,
17905 this zone is a slave. This is a list of remotes identifiers.
17907 @item @code{ddns-master} (default: @code{#f})
17908 The main master. When empty, it defaults to the first master in the list of
17911 @item @code{notify} (default: @code{'()})
17912 A list of slave remote identifiers.
17914 @item @code{acl} (default: @code{'()})
17915 A list of acl identifiers.
17917 @item @code{semantic-checks?} (default: @code{#f})
17918 When set, this adds more semantic checks to the zone.
17920 @item @code{disable-any?} (default: @code{#f})
17921 When set, this forbids queries of the ANY type.
17923 @item @code{zonefile-sync} (default: @code{0})
17924 The delay between a modification in memory and on disk. 0 means immediate
17927 @item @code{serial-policy} (default: @code{'increment})
17928 A policy between @code{'increment} and @code{'unixtime}.
17933 @deftp {Data Type} knot-configuration
17934 Data type representing the Knot configuration. This type has the following
17938 @item @code{knot} (default: @code{knot})
17941 @item @code{run-directory} (default: @code{"/var/run/knot"})
17942 The run directory. This directory will be used for pid file and sockets.
17944 @item @code{listen-v4} (default: @code{"0.0.0.0"})
17945 An ip address on which to listen.
17947 @item @code{listen-v6} (default: @code{"::"})
17948 An ip address on which to listen.
17950 @item @code{listen-port} (default: @code{53})
17951 A port on which to listen.
17953 @item @code{keys} (default: @code{'()})
17954 The list of knot-key-configuration used by this configuration.
17956 @item @code{acls} (default: @code{'()})
17957 The list of knot-acl-configuration used by this configuration.
17959 @item @code{remotes} (default: @code{'()})
17960 The list of knot-remote-configuration used by this configuration.
17962 @item @code{zones} (default: @code{'()})
17963 The list of knot-zone-configuration used by this configuration.
17968 @subsubheading Dnsmasq Service
17970 @deffn {Scheme Variable} dnsmasq-service-type
17971 This is the type of the dnsmasq service, whose value should be an
17972 @code{dnsmasq-configuration} object as in this example:
17975 (service dnsmasq-service-type
17976 (dnsmasq-configuration
17978 (servers '("192.168.1.1"))))
17982 @deftp {Data Type} dnsmasq-configuration
17983 Data type representing the configuration of dnsmasq.
17986 @item @code{package} (default: @var{dnsmasq})
17987 Package object of the dnsmasq server.
17989 @item @code{no-hosts?} (default: @code{#f})
17990 When true, don't read the hostnames in /etc/hosts.
17992 @item @code{port} (default: @code{53})
17993 The port to listen on. Setting this to zero completely disables DNS
17994 responses, leaving only DHCP and/or TFTP functions.
17996 @item @code{local-service?} (default: @code{#t})
17997 Accept DNS queries only from hosts whose address is on a local subnet, ie a
17998 subnet for which an interface exists on the server.
18000 @item @code{listen-addresses} (default: @code{'()})
18001 Listen on the given IP addresses.
18003 @item @code{resolv-file} (default: @code{"/etc/resolv.conf"})
18004 The file to read the IP address of the upstream nameservers from.
18006 @item @code{no-resolv?} (default: @code{#f})
18007 When true, don't read @var{resolv-file}.
18009 @item @code{servers} (default: @code{'()})
18010 Specify IP address of upstream servers directly.
18012 @item @code{cache-size} (default: @code{150})
18013 Set the size of dnsmasq's cache. Setting the cache size to zero disables
18016 @item @code{negative-cache?} (default: @code{#t})
18017 When false, disable negative caching.
18022 @subsubheading ddclient Service
18025 The ddclient service described below runs the ddclient daemon, which takes
18026 care of automatically updating DNS entries for service providers such as
18027 @uref{https://dyn.com/dns/, Dyn}.
18029 The following example show instantiates the service with its default
18033 (service ddclient-service-type)
18036 Note that ddclient needs to access credentials that are stored in a
18037 @dfn{secret file}, by default @file{/etc/ddclient/secrets} (see
18038 @code{secret-file} below.) You are expected to create this file manually,
18039 in an ``out-of-band'' fashion (you @emph{could} make this file part of the
18040 service configuration, for instance by using @code{plain-file}, but it will
18041 be world-readable @i{via} @file{/gnu/store}.) See the examples in the
18042 @file{share/ddclient} directory of the @code{ddclient} package.
18044 @c %start of fragment
18046 Available @code{ddclient-configuration} fields are:
18048 @deftypevr {@code{ddclient-configuration} parameter} package ddclient
18049 The ddclient package.
18053 @deftypevr {@code{ddclient-configuration} parameter} integer daemon
18054 The period after which ddclient will retry to check IP and domain name.
18056 Defaults to @samp{300}.
18060 @deftypevr {@code{ddclient-configuration} parameter} boolean syslog
18061 Use syslog for the output.
18063 Defaults to @samp{#t}.
18067 @deftypevr {@code{ddclient-configuration} parameter} string mail
18070 Defaults to @samp{"root"}.
18074 @deftypevr {@code{ddclient-configuration} parameter} string mail-failure
18075 Mail failed update to user.
18077 Defaults to @samp{"root"}.
18081 @deftypevr {@code{ddclient-configuration} parameter} string pid
18082 The ddclient PID file.
18084 Defaults to @samp{"/var/run/ddclient/ddclient.pid"}.
18088 @deftypevr {@code{ddclient-configuration} parameter} boolean ssl
18089 Enable SSL support.
18091 Defaults to @samp{#t}.
18095 @deftypevr {@code{ddclient-configuration} parameter} string user
18096 Specifies the user name or ID that is used when running ddclient program.
18098 Defaults to @samp{"ddclient"}.
18102 @deftypevr {@code{ddclient-configuration} parameter} string group
18103 Group of the user who will run the ddclient program.
18105 Defaults to @samp{"ddclient"}.
18109 @deftypevr {@code{ddclient-configuration} parameter} string secret-file
18110 Secret file which will be appended to @file{ddclient.conf} file. This file
18111 contains credentials for use by ddclient. You are expected to create it
18114 Defaults to @samp{"/etc/ddclient/secrets.conf"}.
18118 @deftypevr {@code{ddclient-configuration} parameter} list extra-options
18119 Extra options will be appended to @file{ddclient.conf} file.
18121 Defaults to @samp{()}.
18126 @c %end of fragment
18130 @subsubsection VPN-Dienste
18131 @cindex VPN (virtual private network)
18132 @cindex virtual private network (VPN)
18134 The @code{(gnu services vpn)} module provides services related to
18135 @dfn{virtual private networks} (VPNs). It provides a @emph{client} service
18136 for your machine to connect to a VPN, and a @emph{servire} service for your
18137 machine to host a VPN. Both services use @uref{https://openvpn.net/,
18140 @deffn {Scheme Procedure} openvpn-client-service @
18141 [#:config (openvpn-client-configuration)]
18143 Return a service that runs @command{openvpn}, a VPN daemon, as a client.
18146 @deffn {Scheme Procedure} openvpn-server-service @
18147 [#:config (openvpn-server-configuration)]
18149 Return a service that runs @command{openvpn}, a VPN daemon, as a server.
18151 Both can be run simultaneously.
18154 @c %automatically generated documentation
18156 Available @code{openvpn-client-configuration} fields are:
18158 @deftypevr {@code{openvpn-client-configuration} parameter} package openvpn
18159 The OpenVPN package.
18163 @deftypevr {@code{openvpn-client-configuration} parameter} string pid-file
18164 The OpenVPN pid file.
18166 Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
18170 @deftypevr {@code{openvpn-client-configuration} parameter} proto proto
18171 The protocol (UDP or TCP) used to open a channel between clients and
18174 Defaults to @samp{udp}.
18178 @deftypevr {@code{openvpn-client-configuration} parameter} dev dev
18179 The device type used to represent the VPN connection.
18181 Defaults to @samp{tun}.
18185 @deftypevr {@code{openvpn-client-configuration} parameter} string ca
18186 The certificate authority to check connections against.
18188 Defaults to @samp{"/etc/openvpn/ca.crt"}.
18192 @deftypevr {@code{openvpn-client-configuration} parameter} string cert
18193 The certificate of the machine the daemon is running on. It should be
18194 signed by the authority given in @code{ca}.
18196 Defaults to @samp{"/etc/openvpn/client.crt"}.
18200 @deftypevr {@code{openvpn-client-configuration} parameter} string key
18201 The key of the machine the daemon is running on. It must be the key whose
18202 certificate is @code{cert}.
18204 Defaults to @samp{"/etc/openvpn/client.key"}.
18208 @deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo?
18209 Whether to use the lzo compression algorithm.
18211 Defaults to @samp{#t}.
18215 @deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key?
18216 Don't re-read key files across SIGUSR1 or --ping-restart.
18218 Defaults to @samp{#t}.
18222 @deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-tun?
18223 Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1
18224 or --ping-restart restarts.
18226 Defaults to @samp{#t}.
18230 @deftypevr {@code{openvpn-client-configuration} parameter} number verbosity
18233 Defaults to @samp{3}.
18237 @deftypevr {@code{openvpn-client-configuration} parameter} tls-auth-client tls-auth
18238 Add an additional layer of HMAC authentication on top of the TLS control
18239 channel to protect against DoS attacks.
18241 Defaults to @samp{#f}.
18245 @deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage?
18246 Whether to check the server certificate has server usage extension.
18248 Defaults to @samp{#t}.
18252 @deftypevr {@code{openvpn-client-configuration} parameter} bind bind?
18253 Bind to a specific local port number.
18255 Defaults to @samp{#f}.
18259 @deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry?
18260 Retry resolving server address.
18262 Defaults to @samp{#t}.
18266 @deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote
18267 A list of remote servers to connect to.
18269 Defaults to @samp{()}.
18271 Available @code{openvpn-remote-configuration} fields are:
18273 @deftypevr {@code{openvpn-remote-configuration} parameter} string name
18276 Defaults to @samp{"my-server"}.
18280 @deftypevr {@code{openvpn-remote-configuration} parameter} number port
18281 Port number the server listens to.
18283 Defaults to @samp{1194}.
18288 @c %end of automatic openvpn-client documentation
18290 @c %automatically generated documentation
18292 Available @code{openvpn-server-configuration} fields are:
18294 @deftypevr {@code{openvpn-server-configuration} parameter} package openvpn
18295 The OpenVPN package.
18299 @deftypevr {@code{openvpn-server-configuration} parameter} string pid-file
18300 The OpenVPN pid file.
18302 Defaults to @samp{"/var/run/openvpn/openvpn.pid"}.
18306 @deftypevr {@code{openvpn-server-configuration} parameter} proto proto
18307 The protocol (UDP or TCP) used to open a channel between clients and
18310 Defaults to @samp{udp}.
18314 @deftypevr {@code{openvpn-server-configuration} parameter} dev dev
18315 The device type used to represent the VPN connection.
18317 Defaults to @samp{tun}.
18321 @deftypevr {@code{openvpn-server-configuration} parameter} string ca
18322 The certificate authority to check connections against.
18324 Defaults to @samp{"/etc/openvpn/ca.crt"}.
18328 @deftypevr {@code{openvpn-server-configuration} parameter} string cert
18329 The certificate of the machine the daemon is running on. It should be
18330 signed by the authority given in @code{ca}.
18332 Defaults to @samp{"/etc/openvpn/client.crt"}.
18336 @deftypevr {@code{openvpn-server-configuration} parameter} string key
18337 The key of the machine the daemon is running on. It must be the key whose
18338 certificate is @code{cert}.
18340 Defaults to @samp{"/etc/openvpn/client.key"}.
18344 @deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo?
18345 Whether to use the lzo compression algorithm.
18347 Defaults to @samp{#t}.
18351 @deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key?
18352 Don't re-read key files across SIGUSR1 or --ping-restart.
18354 Defaults to @samp{#t}.
18358 @deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-tun?
18359 Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1
18360 or --ping-restart restarts.
18362 Defaults to @samp{#t}.
18366 @deftypevr {@code{openvpn-server-configuration} parameter} number verbosity
18369 Defaults to @samp{3}.
18373 @deftypevr {@code{openvpn-server-configuration} parameter} tls-auth-server tls-auth
18374 Add an additional layer of HMAC authentication on top of the TLS control
18375 channel to protect against DoS attacks.
18377 Defaults to @samp{#f}.
18381 @deftypevr {@code{openvpn-server-configuration} parameter} number port
18382 Specifies the port number on which the server listens.
18384 Defaults to @samp{1194}.
18388 @deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server
18389 An ip and mask specifying the subnet inside the virtual network.
18391 Defaults to @samp{"10.8.0.0 255.255.255.0"}.
18395 @deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6
18396 A CIDR notation specifying the IPv6 subnet inside the virtual network.
18398 Defaults to @samp{#f}.
18402 @deftypevr {@code{openvpn-server-configuration} parameter} string dh
18403 The Diffie-Hellman parameters file.
18405 Defaults to @samp{"/etc/openvpn/dh2048.pem"}.
18409 @deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist
18410 The file that records client IPs.
18412 Defaults to @samp{"/etc/openvpn/ipp.txt"}.
18416 @deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway?
18417 When true, the server will act as a gateway for its clients.
18419 Defaults to @samp{#f}.
18423 @deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client?
18424 When true, clients are allowed to talk to each other inside the VPN.
18426 Defaults to @samp{#f}.
18430 @deftypevr {@code{openvpn-server-configuration} parameter} keepalive keepalive
18431 Causes ping-like messages to be sent back and forth over the link so that
18432 each side knows when the other side has gone down. @code{keepalive}
18433 requires a pair. The first element is the period of the ping sending, and
18434 the second element is the timeout before considering the other side down.
18438 @deftypevr {@code{openvpn-server-configuration} parameter} number max-clients
18439 The maximum number of clients.
18441 Defaults to @samp{100}.
18445 @deftypevr {@code{openvpn-server-configuration} parameter} string status
18446 The status file. This file shows a small report on current connection. It
18447 is truncated and rewritten every minute.
18449 Defaults to @samp{"/var/run/openvpn/status"}.
18453 @deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir
18454 The list of configuration for some clients.
18456 Defaults to @samp{()}.
18458 Available @code{openvpn-ccd-configuration} fields are:
18460 @deftypevr {@code{openvpn-ccd-configuration} parameter} string name
18463 Defaults to @samp{"client"}.
18467 @deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute
18470 Defaults to @samp{#f}.
18474 @deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push
18477 Defaults to @samp{#f}.
18484 @c %end of automatic openvpn-server documentation
18487 @node Network File System
18488 @subsubsection Network File System
18491 The @code{(gnu services nfs)} module provides the following services, which
18492 are most commonly used in relation to mounting or exporting directory trees
18493 as @dfn{network file systems} (NFS).
18495 @subsubheading RPC Bind Service
18498 The RPC Bind service provides a facility to map program numbers into
18499 universal addresses. Many NFS related services use this facility. Hence it
18500 is automatically started when a dependent service starts.
18502 @defvr {Scheme Variable} rpcbind-service-type
18503 A service type for the RPC portmapper daemon.
18507 @deftp {Data Type} rpcbind-configuration
18508 Data type representing the configuration of the RPC Bind Service. This type
18509 has the following parameters:
18511 @item @code{rpcbind} (default: @code{rpcbind})
18512 The rpcbind package to use.
18514 @item @code{warm-start?} (default: @code{#t})
18515 If this parameter is @code{#t}, then the daemon will read a state file on
18516 startup thus reloading state information saved by a previous instance.
18521 @subsubheading Pipefs Pseudo File System
18525 The pipefs file system is used to transfer NFS related data between the
18526 kernel and user space programs.
18528 @defvr {Scheme Variable} pipefs-service-type
18529 A service type for the pipefs pseudo file system.
18532 @deftp {Data Type} pipefs-configuration
18533 Data type representing the configuration of the pipefs pseudo file system
18534 service. This type has the following parameters:
18536 @item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"})
18537 The directory to which the file system is to be attached.
18542 @subsubheading GSS Daemon Service
18545 @cindex global security system
18547 The @dfn{global security system} (GSS) daemon provides strong security for
18548 RPC based protocols. Before exchanging RPC requests an RPC client must
18549 establish a security context. Typically this is done using the Kerberos
18550 command @command{kinit} or automatically at login time using PAM services
18551 (@pxref{Kerberos-Dienste}).
18553 @defvr {Scheme Variable} gss-service-type
18554 A service type for the Global Security System (GSS) daemon.
18557 @deftp {Data Type} gss-configuration
18558 Data type representing the configuration of the GSS daemon service. This
18559 type has the following parameters:
18561 @item @code{nfs-utils} (default: @code{nfs-utils})
18562 The package in which the @command{rpc.gssd} command is to be found.
18564 @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
18565 The directory where the pipefs file system is mounted.
18571 @subsubheading IDMAP Daemon Service
18573 @cindex name mapper
18575 The idmap daemon service provides mapping between user IDs and user names.
18576 Typically it is required in order to access file systems mounted via NFSv4.
18578 @defvr {Scheme Variable} idmap-service-type
18579 A service type for the Identity Mapper (IDMAP) daemon.
18582 @deftp {Data Type} idmap-configuration
18583 Data type representing the configuration of the IDMAP daemon service. This
18584 type has the following parameters:
18586 @item @code{nfs-utils} (default: @code{nfs-utils})
18587 The package in which the @command{rpc.idmapd} command is to be found.
18589 @item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"})
18590 The directory where the pipefs file system is mounted.
18592 @item @code{domain} (default: @code{#f})
18593 The local NFSv4 domain name. This must be a string or @code{#f}. If it is
18594 @code{#f} then the daemon will use the host's fully qualified domain name.
18599 @node Kontinuierliche Integration
18600 @subsubsection Kontinuierliche Integration
18602 @cindex continuous integration
18603 @uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a
18604 continuous integration tool for Guix. It can be used both for development
18605 and for providing substitutes to others (@pxref{Substitute}).
18607 The @code{(gnu services cuirass)} module provides the following service.
18609 @defvr {Scheme Procedure} cuirass-service-type
18610 The type of the Cuirass service. Its value must be a
18611 @code{cuirass-configuration} object, as described below.
18614 To add build jobs, you have to set the @code{specifications} field of the
18615 configuration. Here is an example of a service that polls the Guix
18616 repository and builds the packages from a manifest. Some of the packages
18617 are defined in the @code{"custom-packages"} input, which is the equivalent
18618 of @code{GUIX_PACKAGE_PATH}.
18621 (define %cuirass-specs
18623 '((#:name . "my-manifest")
18624 (#:load-path-inputs . ("guix"))
18625 (#:package-path-inputs . ("custom-packages"))
18626 (#:proc-input . "guix")
18627 (#:proc-file . "build-aux/cuirass/gnu-system.scm")
18628 (#:proc . cuirass-jobs)
18629 (#:proc-args . ((subset . "manifests")
18630 (systems . ("x86_64-linux"))
18631 (manifests . (("config" . "guix/manifest.scm")))))
18632 (#:inputs . (((#:name . "guix")
18633 (#:url . "git://git.savannah.gnu.org/guix.git")
18634 (#:load-path . ".")
18635 (#:branch . "master")
18636 (#:no-compile? . #t))
18637 ((#:name . "config")
18638 (#:url . "git://git.example.org/config.git")
18639 (#:load-path . ".")
18640 (#:branch . "master")
18641 (#:no-compile? . #t))
18642 ((#:name . "custom-packages")
18643 (#:url . "git://git.example.org/custom-packages.git")
18644 (#:load-path . ".")
18645 (#:branch . "master")
18646 (#:no-compile? . #t)))))))
18648 (service cuirass-service-type
18649 (cuirass-configuration
18650 (specifications %cuirass-specs)))
18653 While information related to build jobs is located directly in the
18654 specifications, global settings for the @command{cuirass} process are
18655 accessible in other @code{cuirass-configuration} fields.
18657 @deftp {Data Type} cuirass-configuration
18658 Data type representing the configuration of Cuirass.
18661 @item @code{log-file} (default: @code{"/var/log/cuirass.log"})
18662 Location of the log file.
18664 @item @code{cache-directory} (default: @code{"/var/cache/cuirass"})
18665 Location of the repository cache.
18667 @item @code{user} (default: @code{"cuirass"})
18668 Owner of the @code{cuirass} process.
18670 @item @code{group} (default: @code{"cuirass"})
18671 Owner's group of the @code{cuirass} process.
18673 @item @code{interval} (default: @code{60})
18674 Number of seconds between the poll of the repositories followed by the
18677 @item @code{database} (default: @code{"/var/lib/cuirass/cuirass.db"})
18678 Location of sqlite database which contains the build results and previously
18679 added specifications.
18681 @item @code{ttl} (default: @code{(* 30 24 3600)})
18682 Specifies the time-to-live (TTL) in seconds of garbage collector roots that
18683 are registered for build results. This means that build results are
18684 protected from garbage collection for at least @var{ttl} seconds.
18686 @item @code{port} (default: @code{8081})
18687 Port number used by the HTTP server.
18689 @item --listen=@var{host}
18690 Listen on the network interface for @var{host}. The default is to accept
18691 connections from localhost.
18693 @item @code{specifications} (default: @code{#~'()})
18694 A gexp (@pxref{G-Ausdrücke}) that evaluates to a list of specifications,
18695 where a specification is an association list (@pxref{Associations Lists,,,
18696 guile, GNU Guile Reference Manual}) whose keys are keywords
18697 (@code{#:keyword-example}) as shown in the example above.
18699 @item @code{use-substitutes?} (default: @code{#f})
18700 This allows using substitutes to avoid building every dependencies of a job
18703 @item @code{one-shot?} (default: @code{#f})
18704 Only evaluate specifications and build derivations once.
18706 @item @code{fallback?} (default: @code{#f})
18707 When substituting a pre-built binary fails, fall back to building packages
18710 @item @code{cuirass} (default: @code{cuirass})
18711 The Cuirass package to use.
18715 @node Power Management Services
18716 @subsubsection Power Management Services
18719 @cindex power management with TLP
18720 @subsubheading TLP daemon
18722 The @code{(gnu services pm)} module provides a Guix service definition for
18723 the Linux power management tool TLP.
18725 TLP enables various powersaving modes in userspace and kernel. Contrary to
18726 @code{upower-service}, it is not a passive, monitoring tool, as it will
18727 apply custom settings each time a new power source is detected. More
18728 information can be found at @uref{http://linrunner.de/en/tlp/tlp.html, TLP
18731 @deffn {Scheme Variable} tlp-service-type
18732 The service type for the TLP tool. Its value should be a valid TLP
18733 configuration (see below). To use the default settings, simply write:
18735 (service tlp-service-type)
18739 By default TLP does not need much configuration but most TLP parameters can
18740 be tweaked using @code{tlp-configuration}.
18742 Each parameter definition is preceded by its type; for example,
18743 @samp{boolean foo} indicates that the @code{foo} parameter should be
18744 specified as a boolean. Types starting with @code{maybe-} denote parameters
18745 that won't show up in TLP config file when their value is @code{'disabled}.
18747 @c The following documentation was initially generated by
18748 @c (generate-tlp-documentation) in (gnu services pm). Manually maintained
18749 @c documentation is better, so we shouldn't hesitate to edit below as
18750 @c needed. However if the change you want to make to this documentation
18751 @c can be done in an automated way, it's probably easier to change
18752 @c (generate-documentation) than to make it below and have to deal with
18753 @c the churn as TLP updates.
18755 Available @code{tlp-configuration} fields are:
18757 @deftypevr {@code{tlp-configuration} parameter} package tlp
18762 @deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable?
18763 Set to true if you wish to enable TLP.
18765 Defaults to @samp{#t}.
18769 @deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode
18770 Default mode when no power supply can be detected. Alternatives are AC and
18773 Defaults to @samp{"AC"}.
18777 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-ac
18778 Number of seconds Linux kernel has to wait after the disk goes idle, before
18781 Defaults to @samp{0}.
18785 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat
18786 Same as @code{disk-idle-ac} but on BAT mode.
18788 Defaults to @samp{2}.
18792 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac
18793 Dirty pages flushing periodicity, expressed in seconds.
18795 Defaults to @samp{15}.
18799 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat
18800 Same as @code{max-lost-work-secs-on-ac} but on BAT mode.
18802 Defaults to @samp{60}.
18806 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-ac
18807 CPU frequency scaling governor on AC mode. With intel_pstate driver,
18808 alternatives are powersave and performance. With acpi-cpufreq driver,
18809 alternatives are ondemand, powersave, performance and conservative.
18811 Defaults to @samp{disabled}.
18815 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat
18816 Same as @code{cpu-scaling-governor-on-ac} but on BAT mode.
18818 Defaults to @samp{disabled}.
18822 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-ac
18823 Set the min available frequency for the scaling governor on AC.
18825 Defaults to @samp{disabled}.
18829 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-ac
18830 Set the max available frequency for the scaling governor on AC.
18832 Defaults to @samp{disabled}.
18836 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-min-freq-on-bat
18837 Set the min available frequency for the scaling governor on BAT.
18839 Defaults to @samp{disabled}.
18843 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-scaling-max-freq-on-bat
18844 Set the max available frequency for the scaling governor on BAT.
18846 Defaults to @samp{disabled}.
18850 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-ac
18851 Limit the min P-state to control the power dissipation of the CPU, in AC
18852 mode. Values are stated as a percentage of the available performance.
18854 Defaults to @samp{disabled}.
18858 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-ac
18859 Limit the max P-state to control the power dissipation of the CPU, in AC
18860 mode. Values are stated as a percentage of the available performance.
18862 Defaults to @samp{disabled}.
18866 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat
18867 Same as @code{cpu-min-perf-on-ac} on BAT mode.
18869 Defaults to @samp{disabled}.
18873 @deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat
18874 Same as @code{cpu-max-perf-on-ac} on BAT mode.
18876 Defaults to @samp{disabled}.
18880 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac?
18881 Enable CPU turbo boost feature on AC mode.
18883 Defaults to @samp{disabled}.
18887 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat?
18888 Same as @code{cpu-boost-on-ac?} on BAT mode.
18890 Defaults to @samp{disabled}.
18894 @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-ac?
18895 Allow Linux kernel to minimize the number of CPU cores/hyper-threads used
18896 under light load conditions.
18898 Defaults to @samp{#f}.
18902 @deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat?
18903 Same as @code{sched-powersave-on-ac?} but on BAT mode.
18905 Defaults to @samp{#t}.
18909 @deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog?
18910 Enable Linux kernel NMI watchdog.
18912 Defaults to @samp{#f}.
18916 @deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls
18917 For Linux kernels with PHC patch applied, change CPU voltages. An example
18918 value would be @samp{"F:V F:V F:V F:V"}.
18920 Defaults to @samp{disabled}.
18924 @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-ac
18925 Set CPU performance versus energy saving policy on AC. Alternatives are
18926 performance, normal, powersave.
18928 Defaults to @samp{"performance"}.
18932 @deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat
18933 Same as @code{energy-perf-policy-ac} but on BAT mode.
18935 Defaults to @samp{"powersave"}.
18939 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices
18944 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac
18945 Hard disk advanced power management level.
18949 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat
18950 Same as @code{disk-apm-bat} but on BAT mode.
18954 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-ac
18955 Hard disk spin down timeout. One value has to be specified for each
18956 declared hard disk.
18958 Defaults to @samp{disabled}.
18962 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat
18963 Same as @code{disk-spindown-timeout-on-ac} but on BAT mode.
18965 Defaults to @samp{disabled}.
18969 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-iosched
18970 Select IO scheduler for disk devices. One value has to be specified for
18971 each declared hard disk. Example alternatives are cfq, deadline and noop.
18973 Defaults to @samp{disabled}.
18977 @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-ac
18978 SATA aggressive link power management (ALPM) level. Alternatives are
18979 min_power, medium_power, max_performance.
18981 Defaults to @samp{"max_performance"}.
18985 @deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat
18986 Same as @code{sata-linkpwr-ac} but on BAT mode.
18988 Defaults to @samp{"min_power"}.
18992 @deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist
18993 Exclude specified SATA host devices for link power management.
18995 Defaults to @samp{disabled}.
18999 @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-ac?
19000 Enable Runtime Power Management for AHCI controller and disks on AC mode.
19002 Defaults to @samp{disabled}.
19006 @deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat?
19007 Same as @code{ahci-runtime-pm-on-ac} on BAT mode.
19009 Defaults to @samp{disabled}.
19013 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout
19014 Seconds of inactivity before disk is suspended.
19016 Defaults to @samp{15}.
19020 @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac
19021 PCI Express Active State Power Management level. Alternatives are default,
19022 performance, powersave.
19024 Defaults to @samp{"performance"}.
19028 @deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat
19029 Same as @code{pcie-aspm-ac} but on BAT mode.
19031 Defaults to @samp{"powersave"}.
19035 @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac
19036 Radeon graphics clock speed level. Alternatives are low, mid, high, auto,
19039 Defaults to @samp{"high"}.
19043 @deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat
19044 Same as @code{radeon-power-ac} but on BAT mode.
19046 Defaults to @samp{"low"}.
19050 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac
19051 Radeon dynamic power management method (DPM). Alternatives are battery,
19054 Defaults to @samp{"performance"}.
19058 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat
19059 Same as @code{radeon-dpm-state-ac} but on BAT mode.
19061 Defaults to @samp{"battery"}.
19065 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac
19066 Radeon DPM performance level. Alternatives are auto, low, high.
19068 Defaults to @samp{"auto"}.
19072 @deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat
19073 Same as @code{radeon-dpm-perf-ac} but on BAT mode.
19075 Defaults to @samp{"auto"}.
19079 @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac?
19080 Wifi power saving mode.
19082 Defaults to @samp{#f}.
19086 @deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat?
19087 Same as @code{wifi-power-ac?} but on BAT mode.
19089 Defaults to @samp{#t}.
19093 @deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable?
19094 Disable wake on LAN.
19096 Defaults to @samp{#t}.
19100 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-ac
19101 Timeout duration in seconds before activating audio power saving on Intel
19102 HDA and AC97 devices. A value of 0 disables power saving.
19104 Defaults to @samp{0}.
19108 @deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat
19109 Same as @code{sound-powersave-ac} but on BAT mode.
19111 Defaults to @samp{1}.
19115 @deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller?
19116 Disable controller in powersaving mode on Intel HDA devices.
19118 Defaults to @samp{#t}.
19122 @deftypevr {@code{tlp-configuration} parameter} boolean bay-poweroff-on-bat?
19123 Enable optical drive in UltraBay/MediaBay on BAT mode. Drive can be powered
19124 on again by releasing (and reinserting) the eject lever or by pressing the
19125 disc eject button on newer models.
19127 Defaults to @samp{#f}.
19131 @deftypevr {@code{tlp-configuration} parameter} string bay-device
19132 Name of the optical drive device to power off.
19134 Defaults to @samp{"sr0"}.
19138 @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac
19139 Runtime Power Management for PCI(e) bus devices. Alternatives are on and
19142 Defaults to @samp{"on"}.
19146 @deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat
19147 Same as @code{runtime-pm-ac} but on BAT mode.
19149 Defaults to @samp{"auto"}.
19153 @deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all?
19154 Runtime Power Management for all PCI(e) bus devices, except blacklisted
19157 Defaults to @samp{#t}.
19161 @deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist
19162 Exclude specified PCI(e) device addresses from Runtime Power Management.
19164 Defaults to @samp{disabled}.
19168 @deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist
19169 Exclude PCI(e) devices assigned to the specified drivers from Runtime Power
19174 @deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend?
19175 Enable USB autosuspend feature.
19177 Defaults to @samp{#t}.
19181 @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist
19182 Exclude specified devices from USB autosuspend.
19184 Defaults to @samp{disabled}.
19188 @deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan?
19189 Exclude WWAN devices from USB autosuspend.
19191 Defaults to @samp{#t}.
19195 @deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist
19196 Include specified devices into USB autosuspend, even if they are already
19197 excluded by the driver or via @code{usb-blacklist-wwan?}.
19199 Defaults to @samp{disabled}.
19203 @deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown?
19204 Enable USB autosuspend before shutdown.
19206 Defaults to @samp{disabled}.
19210 @deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup?
19211 Restore radio device state (bluetooth, wifi, wwan) from previous shutdown on
19214 Defaults to @samp{#f}.
19219 @cindex CPU frequency scaling with thermald
19220 @subsubheading Thermald daemon
19222 The @code{(gnu services pm)} module provides an interface to thermald, a CPU
19223 frequency scaling service which helps prevent overheating.
19225 @defvr {Scheme Variable} thermald-service-type
19226 This is the service type for @uref{https://01.org/linux-thermal-daemon/,
19227 thermald}, the Linux Thermal Daemon, which is responsible for controlling
19228 the thermal state of processors and preventing overheating.
19231 @deftp {Data Type} thermald-configuration
19232 Data type representing the configuration of @code{thermald-service-type}.
19235 @item @code{ignore-cpuid-check?} (default: @code{#f})
19236 Ignore cpuid check for supported CPU models.
19238 @item @code{thermald} (default: @var{thermald})
19239 Package object of thermald.
19244 @node Audio-Dienste
19245 @subsubsection Audio-Dienste
19247 The @code{(gnu services audio)} module provides a service to start MPD (the
19248 Music Player Daemon).
19251 @subsubheading Music Player Daemon
19253 The Music Player Daemon (MPD) is a service that can play music while being
19254 controlled from the local machine or over the network by a variety of
19257 The following example shows how one might run @code{mpd} as user
19258 @code{"bob"} on port @code{6666}. It uses pulseaudio for output.
19261 (service mpd-service-type
19267 @defvr {Scheme Variable} mpd-service-type
19268 The service type for @command{mpd}
19271 @deftp {Data Type} mpd-configuration
19272 Data type representing the configuration of @command{mpd}.
19275 @item @code{user} (default: @code{"mpd"})
19276 The user to run mpd as.
19278 @item @code{music-dir} (default: @code{"~/Music"})
19279 The directory to scan for music files.
19281 @item @code{playlist-dir} (default: @code{"~/.mpd/playlists"})
19282 The directory to store playlists.
19284 @item @code{port} (default: @code{"6600"})
19285 The port to run mpd on.
19287 @item @code{address} (default: @code{"any"})
19288 The address that mpd will bind to. To use a Unix domain socket, an absolute
19289 path can be specified here.
19294 @node Virtualisierungsdienste
19295 @subsubsection Virtualization services
19297 The @code{(gnu services virtualization)} module provides services for the
19298 libvirt and virtlog daemons, as well as other virtualization-related
19301 @subsubheading Libvirt daemon
19302 @code{libvirtd} is the server side daemon component of the libvirt
19303 virtualization management system. This daemon runs on host servers and
19304 performs required management tasks for virtualized guests.
19306 @deffn {Scheme Variable} libvirt-service-type
19307 This is the type of the @uref{https://libvirt.org, libvirt daemon}. Its
19308 value must be a @code{libvirt-configuration}.
19311 (service libvirt-service-type
19312 (libvirt-configuration
19313 (unix-sock-group "libvirt")
19314 (tls-port "16555")))
19318 @c Auto-generated with (generate-libvirt-documentation)
19319 Available @code{libvirt-configuration} fields are:
19321 @deftypevr {@code{libvirt-configuration} parameter} package libvirt
19326 @deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls?
19327 Flag listening for secure TLS connections on the public TCP/IP port. must
19328 set @code{listen} for this to have any effect.
19330 It is necessary to setup a CA and issue server certificates before using
19333 Defaults to @samp{#t}.
19337 @deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp?
19338 Listen for unencrypted TCP connections on the public TCP/IP port. must set
19339 @code{listen} for this to have any effect.
19341 Using the TCP socket requires SASL authentication by default. Only SASL
19342 mechanisms which support data encryption are allowed. This is DIGEST_MD5
19343 and GSSAPI (Kerberos5)
19345 Defaults to @samp{#f}.
19349 @deftypevr {@code{libvirt-configuration} parameter} string tls-port
19350 Port for accepting secure TLS connections This can be a port number, or
19353 Defaults to @samp{"16514"}.
19357 @deftypevr {@code{libvirt-configuration} parameter} string tcp-port
19358 Port for accepting insecure TCP connections This can be a port number, or
19361 Defaults to @samp{"16509"}.
19365 @deftypevr {@code{libvirt-configuration} parameter} string listen-addr
19366 IP address or hostname used for client connections.
19368 Defaults to @samp{"0.0.0.0"}.
19372 @deftypevr {@code{libvirt-configuration} parameter} boolean mdns-adv?
19373 Flag toggling mDNS advertisement of the libvirt service.
19375 Alternatively can disable for all services on a host by stopping the Avahi
19378 Defaults to @samp{#f}.
19382 @deftypevr {@code{libvirt-configuration} parameter} string mdns-name
19383 Default mDNS advertisement name. This must be unique on the immediate
19386 Defaults to @samp{"Virtualization Host <hostname>"}.
19390 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-group
19391 UNIX domain socket group ownership. This can be used to allow a 'trusted'
19392 set of users access to management capabilities without becoming root.
19394 Defaults to @samp{"root"}.
19398 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-ro-perms
19399 UNIX socket permissions for the R/O socket. This is used for monitoring VM
19402 Defaults to @samp{"0777"}.
19406 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-rw-perms
19407 UNIX socket permissions for the R/W socket. Default allows only root. If
19408 PolicyKit is enabled on the socket, the default will change to allow
19409 everyone (eg, 0777)
19411 Defaults to @samp{"0770"}.
19415 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-admin-perms
19416 UNIX socket permissions for the admin socket. Default allows only owner
19417 (root), do not change it unless you are sure to whom you are exposing the
19420 Defaults to @samp{"0777"}.
19424 @deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir
19425 The directory in which sockets will be found/created.
19427 Defaults to @samp{"/var/run/libvirt"}.
19431 @deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro
19432 Authentication scheme for UNIX read-only sockets. By default socket
19433 permissions allow anyone to connect
19435 Defaults to @samp{"polkit"}.
19439 @deftypevr {@code{libvirt-configuration} parameter} string auth-unix-rw
19440 Authentication scheme for UNIX read-write sockets. By default socket
19441 permissions only allow root. If PolicyKit support was compiled into
19442 libvirt, the default will be to use 'polkit' auth.
19444 Defaults to @samp{"polkit"}.
19448 @deftypevr {@code{libvirt-configuration} parameter} string auth-tcp
19449 Authentication scheme for TCP sockets. If you don't enable SASL, then all
19450 TCP traffic is cleartext. Don't do this outside of a dev/test scenario.
19452 Defaults to @samp{"sasl"}.
19456 @deftypevr {@code{libvirt-configuration} parameter} string auth-tls
19457 Authentication scheme for TLS sockets. TLS sockets already have encryption
19458 provided by the TLS layer, and limited authentication is done by
19461 It is possible to make use of any SASL authentication mechanism as well, by
19462 using 'sasl' for this option
19464 Defaults to @samp{"none"}.
19468 @deftypevr {@code{libvirt-configuration} parameter} optional-list access-drivers
19469 API access control scheme.
19471 By default an authenticated user is allowed access to all APIs. Access
19472 drivers can place restrictions on this.
19474 Defaults to @samp{()}.
19478 @deftypevr {@code{libvirt-configuration} parameter} string key-file
19479 Server key file path. If set to an empty string, then no private key is
19482 Defaults to @samp{""}.
19486 @deftypevr {@code{libvirt-configuration} parameter} string cert-file
19487 Server key file path. If set to an empty string, then no certificate is
19490 Defaults to @samp{""}.
19494 @deftypevr {@code{libvirt-configuration} parameter} string ca-file
19495 Server key file path. If set to an empty string, then no CA certificate is
19498 Defaults to @samp{""}.
19502 @deftypevr {@code{libvirt-configuration} parameter} string crl-file
19503 Certificate revocation list path. If set to an empty string, then no CRL is
19506 Defaults to @samp{""}.
19510 @deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-sanity-cert
19511 Disable verification of our own server certificates.
19513 When libvirtd starts it performs some sanity checks against its own
19516 Defaults to @samp{#f}.
19520 @deftypevr {@code{libvirt-configuration} parameter} boolean tls-no-verify-cert
19521 Disable verification of client certificates.
19523 Client certificate verification is the primary authentication mechanism.
19524 Any client which does not present a certificate signed by the CA will be
19527 Defaults to @samp{#f}.
19531 @deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list
19532 Whitelist of allowed x509 Distinguished Name.
19534 Defaults to @samp{()}.
19538 @deftypevr {@code{libvirt-configuration} parameter} optional-list sasl-allowed-usernames
19539 Whitelist of allowed SASL usernames. The format for username depends on the
19540 SASL authentication mechanism.
19542 Defaults to @samp{()}.
19546 @deftypevr {@code{libvirt-configuration} parameter} string tls-priority
19547 Override the compile time default TLS priority string. The default is
19548 usually "NORMAL" unless overridden at build time. Only set this is it is
19549 desired for libvirt to deviate from the global default settings.
19551 Defaults to @samp{"NORMAL"}.
19555 @deftypevr {@code{libvirt-configuration} parameter} integer max-clients
19556 Maximum number of concurrent client connections to allow over all sockets
19559 Defaults to @samp{5000}.
19563 @deftypevr {@code{libvirt-configuration} parameter} integer max-queued-clients
19564 Maximum length of queue of connections waiting to be accepted by the
19565 daemon. Note, that some protocols supporting retransmission may obey this
19566 so that a later reattempt at connection succeeds.
19568 Defaults to @samp{1000}.
19572 @deftypevr {@code{libvirt-configuration} parameter} integer max-anonymous-clients
19573 Maximum length of queue of accepted but not yet authenticated clients. Set
19574 this to zero to turn this feature off
19576 Defaults to @samp{20}.
19580 @deftypevr {@code{libvirt-configuration} parameter} integer min-workers
19581 Number of workers to start up initially.
19583 Defaults to @samp{5}.
19587 @deftypevr {@code{libvirt-configuration} parameter} integer max-workers
19588 Maximum number of worker threads.
19590 If the number of active clients exceeds @code{min-workers}, then more
19591 threads are spawned, up to max_workers limit. Typically you'd want
19592 max_workers to equal maximum number of clients allowed.
19594 Defaults to @samp{20}.
19598 @deftypevr {@code{libvirt-configuration} parameter} integer prio-workers
19599 Number of priority workers. If all workers from above pool are stuck, some
19600 calls marked as high priority (notably domainDestroy) can be executed in
19603 Defaults to @samp{5}.
19607 @deftypevr {@code{libvirt-configuration} parameter} integer max-requests
19608 Total global limit on concurrent RPC calls.
19610 Defaults to @samp{20}.
19614 @deftypevr {@code{libvirt-configuration} parameter} integer max-client-requests
19615 Limit on concurrent requests from a single client connection. To avoid one
19616 client monopolizing the server this should be a small fraction of the global
19617 max_requests and max_workers parameter.
19619 Defaults to @samp{5}.
19623 @deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers
19624 Same as @code{min-workers} but for the admin interface.
19626 Defaults to @samp{1}.
19630 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers
19631 Same as @code{max-workers} but for the admin interface.
19633 Defaults to @samp{5}.
19637 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients
19638 Same as @code{max-clients} but for the admin interface.
19640 Defaults to @samp{5}.
19644 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients
19645 Same as @code{max-queued-clients} but for the admin interface.
19647 Defaults to @samp{5}.
19651 @deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests
19652 Same as @code{max-client-requests} but for the admin interface.
19654 Defaults to @samp{5}.
19658 @deftypevr {@code{libvirt-configuration} parameter} integer log-level
19659 Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
19661 Defaults to @samp{3}.
19665 @deftypevr {@code{libvirt-configuration} parameter} string log-filters
19668 A filter allows to select a different logging level for a given category of
19669 logs The format for a filter is one of:
19680 where @code{name} is a string which is matched against the category given in
19681 the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g.,
19682 "remote", "qemu", or "util.json" (the name in the filter can be a substring
19683 of the full category name, in order to match multiple similar categories),
19684 the optional "+" prefix tells libvirt to log stack trace for each message
19685 matching name, and @code{x} is the minimal level where matching messages
19703 Multiple filters can be defined in a single filters statement, they just
19704 need to be separated by spaces.
19706 Defaults to @samp{"3:remote 4:event"}.
19710 @deftypevr {@code{libvirt-configuration} parameter} string log-outputs
19713 An output is one of the places to save logging information The format for an
19718 output goes to stderr
19720 @item x:syslog:name
19721 use syslog for the output and use the given name as the ident
19723 @item x:file:file_path
19724 output to a file, with the given filepath
19727 output to journald logging system
19731 In all case the x prefix is the minimal level, acting as a filter
19748 Multiple outputs can be defined, they just need to be separated by spaces.
19750 Defaults to @samp{"3:stderr"}.
19754 @deftypevr {@code{libvirt-configuration} parameter} integer audit-level
19755 Allows usage of the auditing subsystem to be altered
19759 0: disable all auditing
19762 1: enable auditing, only if enabled on host
19765 2: enable auditing, and exit if disabled on host.
19769 Defaults to @samp{1}.
19773 @deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging
19774 Send audit messages via libvirt logging infrastructure.
19776 Defaults to @samp{#f}.
19780 @deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid
19781 Host UUID. UUID must not have all digits be the same.
19783 Defaults to @samp{""}.
19787 @deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source
19788 Source to read host UUID.
19792 @code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid}
19795 @code{machine-id}: fetch the UUID from @code{/etc/machine-id}
19799 If @code{dmidecode} does not provide a valid UUID a temporary UUID will be
19802 Defaults to @samp{"smbios"}.
19806 @deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval
19807 A keepalive message is sent to a client after @code{keepalive_interval}
19808 seconds of inactivity to check if the client is still responding. If set to
19809 -1, libvirtd will never send keepalive requests; however clients can still
19810 send them and the daemon will send responses.
19812 Defaults to @samp{5}.
19816 @deftypevr {@code{libvirt-configuration} parameter} integer keepalive-count
19817 Maximum number of keepalive messages that are allowed to be sent to the
19818 client without getting any response before the connection is considered
19821 In other words, the connection is automatically closed approximately after
19822 @code{keepalive_interval * (keepalive_count + 1)} seconds since the last
19823 message received from the client. When @code{keepalive-count} is set to 0,
19824 connections will be automatically closed after @code{keepalive-interval}
19825 seconds of inactivity without sending any keepalive messages.
19827 Defaults to @samp{5}.
19831 @deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval
19832 Same as above but for admin interface.
19834 Defaults to @samp{5}.
19838 @deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count
19839 Same as above but for admin interface.
19841 Defaults to @samp{5}.
19845 @deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout
19846 Timeout for Open vSwitch calls.
19848 The @code{ovs-vsctl} utility is used for the configuration and its timeout
19849 option is set by default to 5 seconds to avoid potential infinite waits
19852 Defaults to @samp{5}.
19856 @c %end of autogenerated docs
19858 @subsubheading Virtlog daemon
19859 The virtlogd service is a server side daemon component of libvirt that is
19860 used to manage logs from virtual machine consoles.
19862 This daemon is not used directly by libvirt client applications, rather it
19863 is called on their behalf by @code{libvirtd}. By maintaining the logs in a
19864 standalone daemon, the main @code{libvirtd} daemon can be restarted without
19865 risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec()
19866 itself upon receiving @code{SIGUSR1}, to allow live upgrades without
19869 @deffn {Scheme Variable} virtlog-service-type
19870 This is the type of the virtlog daemon. Its value must be a
19871 @code{virtlog-configuration}.
19874 (service virtlog-service-type
19875 (virtlog-configuration
19876 (max-clients 1000)))
19880 @deftypevr {@code{virtlog-configuration} parameter} integer log-level
19881 Logging level. 4 errors, 3 warnings, 2 information, 1 debug.
19883 Defaults to @samp{3}.
19887 @deftypevr {@code{virtlog-configuration} parameter} string log-filters
19890 A filter allows to select a different logging level for a given category of
19891 logs The format for a filter is one of:
19902 where @code{name} is a string which is matched against the category given in
19903 the @code{VIR_LOG_INIT()} at the top of each libvirt source file, e.g.,
19904 "remote", "qemu", or "util.json" (the name in the filter can be a substring
19905 of the full category name, in order to match multiple similar categories),
19906 the optional "+" prefix tells libvirt to log stack trace for each message
19907 matching name, and @code{x} is the minimal level where matching messages
19925 Multiple filters can be defined in a single filters statement, they just
19926 need to be separated by spaces.
19928 Defaults to @samp{"3:remote 4:event"}.
19932 @deftypevr {@code{virtlog-configuration} parameter} string log-outputs
19935 An output is one of the places to save logging information The format for an
19940 output goes to stderr
19942 @item x:syslog:name
19943 use syslog for the output and use the given name as the ident
19945 @item x:file:file_path
19946 output to a file, with the given filepath
19949 output to journald logging system
19953 In all case the x prefix is the minimal level, acting as a filter
19970 Multiple outputs can be defined, they just need to be separated by spaces.
19972 Defaults to @samp{"3:stderr"}.
19976 @deftypevr {@code{virtlog-configuration} parameter} integer max-clients
19977 Maximum number of concurrent client connections to allow over all sockets
19980 Defaults to @samp{1024}.
19984 @deftypevr {@code{virtlog-configuration} parameter} integer max-size
19985 Maximum file size before rolling over.
19987 Defaults to @samp{2MB}
19991 @deftypevr {@code{virtlog-configuration} parameter} integer max-backups
19992 Maximum number of backup files to keep.
19994 Defaults to @samp{3}
19998 @subsubheading Transparent Emulation with QEMU
20001 @cindex @code{binfmt_misc}
20002 @code{qemu-binfmt-service-type} provides support for transparent emulation
20003 of program binaries built for different architectures---e.g., it allows you
20004 to transparently execute an ARMv7 program on an x86_64 machine. It achieves
20005 this by combining the @uref{https://www.qemu.org, QEMU} emulator and the
20006 @code{binfmt_misc} feature of the kernel Linux.
20008 @defvr {Scheme Variable} qemu-binfmt-service-type
20009 This is the type of the QEMU/binfmt service for transparent emulation. Its
20010 value must be a @code{qemu-binfmt-configuration} object, which specifies the
20011 QEMU package to use as well as the architecture we want to emulated:
20014 (service qemu-binfmt-service-type
20015 (qemu-binfmt-configuration
20016 (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc"))))
20019 In this example, we enable transparent emulation for the ARM and aarch64
20020 platforms. Running @code{herd stop qemu-binfmt} turns it off, and running
20021 @code{herd start qemu-binfmt} turns it back on (@pxref{Invoking herd, the
20022 @command{herd} command,, shepherd, The GNU Shepherd Manual}).
20025 @deftp {Data Type} qemu-binfmt-configuration
20026 This is the configuration for the @code{qemu-binfmt} service.
20029 @item @code{platforms} (default: @code{'()})
20030 The list of emulated QEMU platforms. Each item must be a @dfn{platform
20031 object} as returned by @code{lookup-qemu-platforms} (see below).
20033 @item @code{guix-support?} (default: @code{#f})
20034 When it is true, QEMU and all its dependencies are added to the build
20035 environment of @command{guix-daemon} (@pxref{Aufruf des guix-daemon,
20036 @code{--chroot-directory} option}). This allows the @code{binfmt_misc}
20037 handlers to be used within the build environment, which in turn means that
20038 you can transparently build programs for another architecture.
20040 For example, let's suppose you're on an x86_64 machine and you have this
20044 (service qemu-binfmt-service-type
20045 (qemu-binfmt-configuration
20046 (platforms (lookup-qemu-platforms "arm"))
20047 (guix-support? #t)))
20053 guix build -s armhf-linux inkscape
20057 and it will build Inkscape for ARMv7 @emph{as if it were a native build},
20058 transparently using QEMU to emulate the ARMv7 CPU. Pretty handy if you'd
20059 like to test a package build for an architecture you don't have access to!
20061 @item @code{qemu} (default: @code{qemu})
20062 The QEMU package to use.
20066 @deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{}
20067 Return the list of QEMU platform objects corresponding to
20068 @var{platforms}@dots{}. @var{platforms} must be a list of strings
20069 corresponding to platform names, such as @code{"arm"}, @code{"sparc"},
20070 @code{"mips64el"}, and so on.
20073 @deffn {Scheme Procedure} qemu-platform? @var{obj}
20074 Return true if @var{obj} is a platform object.
20077 @deffn {Scheme Procedure} qemu-platform-name @var{platform}
20078 Return the name of @var{platform}---a string such as @code{"arm"}.
20081 @node Versionskontrolldienste
20082 @subsubsection Versionskontrolldienste
20084 The @code{(gnu services version-control)} module provides a service to allow
20085 remote access to local Git repositories. There are three options: the
20086 @code{git-daemon-service}, which provides access to repositories via the
20087 @code{git://} unsecured TCP-based protocol, extending the @code{nginx} web
20088 server to proxy some requests to @code{git-http-backend}, or providing a web
20089 interface with @code{cgit-service-type}.
20091 @deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)]
20093 Return a service that runs @command{git daemon}, a simple TCP server to
20094 expose repositories over the Git protocol for anonymous access.
20096 The optional @var{config} argument should be a
20097 @code{<git-daemon-configuration>} object, by default it allows read-only
20098 access to exported@footnote{By creating the magic file
20099 "git-daemon-export-ok" in the repository directory.} repositories under
20104 @deftp {Data Type} git-daemon-configuration
20105 Data type representing the configuration for @code{git-daemon-service}.
20108 @item @code{package} (default: @var{git})
20109 Package object of the Git distributed version control system.
20111 @item @code{export-all?} (default: @var{#f})
20112 Whether to allow access for all Git repositories, even if they do not have
20113 the @file{git-daemon-export-ok} file.
20115 @item @code{base-path} (default: @file{/srv/git})
20116 Whether to remap all the path requests as relative to the given path. If
20117 you run git daemon with @var{(base-path "/srv/git")} on example.com, then if
20118 you later try to pull @code{git://example.com/hello.git}, git daemon will
20119 interpret the path as @code{/srv/git/hello.git}.
20121 @item @code{user-path} (default: @var{#f})
20122 Whether to allow @code{~user} notation to be used in requests. When
20123 specified with empty string, requests to @code{git://host/~alice/foo} is
20124 taken as a request to access @code{foo} repository in the home directory of
20125 user @code{alice}. If @var{(user-path "path")} is specified, the same
20126 request is taken as a request to access @code{path/foo} repository in the
20127 home directory of user @code{alice}.
20129 @item @code{listen} (default: @var{'()})
20130 Whether to listen on specific IP addresses or hostnames, defaults to all.
20132 @item @code{port} (default: @var{#f})
20133 Whether to listen on an alternative port, which defaults to 9418.
20135 @item @code{whitelist} (default: @var{'()})
20136 If not empty, only allow access to this list of directories.
20138 @item @code{extra-options} (default: @var{'()})
20139 Extra options will be passed to @code{git daemon}, please run @command{man
20140 git-daemon} for more information.
20145 The @code{git://} protocol lacks authentication. When you pull from a
20146 repository fetched via @code{git://}, you don't know that the data you
20147 receive was modified is really coming from the specified host, and you have
20148 your connection is subject to eavesdropping. It's better to use an
20149 authenticated and encrypted transport, such as @code{https}. Although Git
20150 allows you to serve repositories using unsophisticated file-based web
20151 servers, there is a faster protocol implemented by the
20152 @code{git-http-backend} program. This program is the back-end of a proper
20153 Git web service. It is designed to sit behind a FastCGI proxy. @xref{Web-Dienste}, for more on running the necessary @code{fcgiwrap} daemon.
20155 Guix has a separate configuration data type for serving Git repositories
20158 @deftp {Data Type} git-http-configuration
20159 Data type representing the configuration for @code{git-http-service}.
20162 @item @code{package} (default: @var{git})
20163 Package object of the Git distributed version control system.
20165 @item @code{git-root} (default: @file{/srv/git})
20166 Directory containing the Git repositories to expose to the world.
20168 @item @code{export-all?} (default: @var{#f})
20169 Whether to expose access for all Git repositories in @var{git-root}, even if
20170 they do not have the @file{git-daemon-export-ok} file.
20172 @item @code{uri-path} (default: @file{/git/})
20173 Path prefix for Git access. With the default @code{/git/} prefix, this will
20174 map @code{http://@var{server}/git/@var{repo}.git} to
20175 @code{/srv/git/@var{repo}.git}. Requests whose URI paths do not begin with
20176 this prefix are not passed on to this Git instance.
20178 @item @code{fcgiwrap-socket} (default: @code{127.0.0.1:9000})
20179 The socket on which the @code{fcgiwrap} daemon is listening. @xref{Web-Dienste}.
20183 There is no @code{git-http-service-type}, currently; instead you can create
20184 an @code{nginx-location-configuration} from a @code{git-http-configuration}
20185 and then add that location to a web server.
20187 @deffn {Scheme Procedure} git-http-nginx-location-configuration @
20188 [config=(git-http-configuration)] Compute an
20189 @code{nginx-location-configuration} that corresponds to the given Git http
20190 configuration. An example nginx service definition to serve the default
20191 @file{/srv/git} over HTTPS might be:
20194 (service nginx-service-type
20195 (nginx-configuration
20198 (nginx-server-configuration
20199 (listen '("443 ssl"))
20200 (server-name "git.my-host.org")
20202 "/etc/letsencrypt/live/git.my-host.org/fullchain.pem")
20203 (ssl-certificate-key
20204 "/etc/letsencrypt/live/git.my-host.org/privkey.pem")
20207 (git-http-nginx-location-configuration
20208 (git-http-configuration (uri-path "/"))))))))))
20211 This example assumes that you are using Let's Encrypt to get your TLS
20212 certificate. @xref{Zertifikatsdienste}. The default @code{certbot}
20213 service will redirect all HTTP traffic on @code{git.my-host.org} to HTTPS.
20214 You will also need to add an @code{fcgiwrap} proxy to your system services.
20215 @xref{Web-Dienste}.
20218 @subsubheading Cgit Service
20220 @cindex Cgit service
20221 @cindex Git, web interface
20222 @uref{https://git.zx2c4.com/cgit/, Cgit} is a web frontend for Git
20223 repositories written in C.
20225 The following example will configure the service with default values. By
20226 default, Cgit can be accessed on port 80 (@code{http://localhost:80}).
20229 (service cgit-service-type)
20232 The @code{file-object} type designates either a file-like object
20233 (@pxref{G-Ausdrücke, file-like objects}) or a string.
20235 @c %start of fragment
20237 Available @code{cgit-configuration} fields are:
20239 @deftypevr {@code{cgit-configuration} parameter} package package
20244 @deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx
20245 NGINX configuration.
20249 @deftypevr {@code{cgit-configuration} parameter} file-object about-filter
20250 Specifies a command which will be invoked to format the content of about
20251 pages (both top-level and for each repository).
20253 Defaults to @samp{""}.
20257 @deftypevr {@code{cgit-configuration} parameter} string agefile
20258 Specifies a path, relative to each repository path, which can be used to
20259 specify the date and time of the youngest commit in the repository.
20261 Defaults to @samp{""}.
20265 @deftypevr {@code{cgit-configuration} parameter} file-object auth-filter
20266 Specifies a command that will be invoked for authenticating repository
20269 Defaults to @samp{""}.
20273 @deftypevr {@code{cgit-configuration} parameter} string branch-sort
20274 Flag which, when set to @samp{age}, enables date ordering in the branch ref
20275 list, and when set @samp{name} enables ordering by branch name.
20277 Defaults to @samp{"name"}.
20281 @deftypevr {@code{cgit-configuration} parameter} string cache-root
20282 Path used to store the cgit cache entries.
20284 Defaults to @samp{"/var/cache/cgit"}.
20288 @deftypevr {@code{cgit-configuration} parameter} integer cache-static-ttl
20289 Number which specifies the time-to-live, in minutes, for the cached version
20290 of repository pages accessed with a fixed SHA1.
20292 Defaults to @samp{-1}.
20296 @deftypevr {@code{cgit-configuration} parameter} integer cache-dynamic-ttl
20297 Number which specifies the time-to-live, in minutes, for the cached version
20298 of repository pages accessed without a fixed SHA1.
20300 Defaults to @samp{5}.
20304 @deftypevr {@code{cgit-configuration} parameter} integer cache-repo-ttl
20305 Number which specifies the time-to-live, in minutes, for the cached version
20306 of the repository summary page.
20308 Defaults to @samp{5}.
20312 @deftypevr {@code{cgit-configuration} parameter} integer cache-root-ttl
20313 Number which specifies the time-to-live, in minutes, for the cached version
20314 of the repository index page.
20316 Defaults to @samp{5}.
20320 @deftypevr {@code{cgit-configuration} parameter} integer cache-scanrc-ttl
20321 Number which specifies the time-to-live, in minutes, for the result of
20322 scanning a path for Git repositories.
20324 Defaults to @samp{15}.
20328 @deftypevr {@code{cgit-configuration} parameter} integer cache-about-ttl
20329 Number which specifies the time-to-live, in minutes, for the cached version
20330 of the repository about page.
20332 Defaults to @samp{15}.
20336 @deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl
20337 Number which specifies the time-to-live, in minutes, for the cached version
20340 Defaults to @samp{5}.
20344 @deftypevr {@code{cgit-configuration} parameter} integer cache-size
20345 The maximum number of entries in the cgit cache. When set to @samp{0},
20346 caching is disabled.
20348 Defaults to @samp{0}.
20352 @deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort?
20353 Sort items in the repo list case sensitively.
20355 Defaults to @samp{#t}.
20359 @deftypevr {@code{cgit-configuration} parameter} list clone-prefix
20360 List of common prefixes which, when combined with a repository URL,
20361 generates valid clone URLs for the repository.
20363 Defaults to @samp{()}.
20367 @deftypevr {@code{cgit-configuration} parameter} list clone-url
20368 List of @code{clone-url} templates.
20370 Defaults to @samp{()}.
20374 @deftypevr {@code{cgit-configuration} parameter} file-object commit-filter
20375 Command which will be invoked to format commit messages.
20377 Defaults to @samp{""}.
20381 @deftypevr {@code{cgit-configuration} parameter} string commit-sort
20382 Flag which, when set to @samp{date}, enables strict date ordering in the
20383 commit log, and when set to @samp{topo} enables strict topological ordering.
20385 Defaults to @samp{"git log"}.
20389 @deftypevr {@code{cgit-configuration} parameter} file-object css
20390 URL which specifies the css document to include in all cgit pages.
20392 Defaults to @samp{"/share/cgit/cgit.css"}.
20396 @deftypevr {@code{cgit-configuration} parameter} file-object email-filter
20397 Specifies a command which will be invoked to format names and email address
20398 of committers, authors, and taggers, as represented in various places
20399 throughout the cgit interface.
20401 Defaults to @samp{""}.
20405 @deftypevr {@code{cgit-configuration} parameter} boolean embedded?
20406 Flag which, when set to @samp{#t}, will make cgit generate a HTML fragment
20407 suitable for embedding in other HTML pages.
20409 Defaults to @samp{#f}.
20413 @deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph?
20414 Flag which, when set to @samp{#t}, will make cgit print an ASCII-art commit
20415 history graph to the left of the commit messages in the repository log page.
20417 Defaults to @samp{#f}.
20421 @deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides?
20422 Flag which, when set to @samp{#t}, allows all filter settings to be
20423 overridden in repository-specific cgitrc files.
20425 Defaults to @samp{#f}.
20429 @deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links?
20430 Flag which, when set to @samp{#t}, allows users to follow a file in the log
20433 Defaults to @samp{#f}.
20437 @deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone?
20438 If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git clones.
20440 Defaults to @samp{#t}.
20444 @deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links?
20445 Flag which, when set to @samp{#t}, will make cgit generate extra links
20446 "summary", "commit", "tree" for each repo in the repository index.
20448 Defaults to @samp{#f}.
20452 @deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner?
20453 Flag which, when set to @samp{#t}, will make cgit display the owner of each
20454 repo in the repository index.
20456 Defaults to @samp{#t}.
20460 @deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount?
20461 Flag which, when set to @samp{#t}, will make cgit print the number of
20462 modified files for each commit on the repository log page.
20464 Defaults to @samp{#f}.
20468 @deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount?
20469 Flag which, when set to @samp{#t}, will make cgit print the number of added
20470 and removed lines for each commit on the repository log page.
20472 Defaults to @samp{#f}.
20476 @deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches?
20477 Flag which, when set to @code{#t}, will make cgit display remote branches in
20478 the summary and refs views.
20480 Defaults to @samp{#f}.
20484 @deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links?
20485 Flag which, when set to @code{1}, will make cgit use the subject of the
20486 parent commit as link text when generating links to parent commits in commit
20489 Defaults to @samp{#f}.
20493 @deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving?
20494 Flag which, when set to @samp{#t}, will make cgit use the subject of the
20495 parent commit as link text when generating links to parent commits in commit
20498 Defaults to @samp{#f}.
20502 @deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers?
20503 Flag which, when set to @samp{#t}, will make cgit generate linenumber links
20504 for plaintext blobs printed in the tree view.
20506 Defaults to @samp{#t}.
20510 @deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config?
20511 Flag which, when set to @samp{#f}, will allow cgit to use Git config to set
20512 any repo specific settings.
20514 Defaults to @samp{#f}.
20518 @deftypevr {@code{cgit-configuration} parameter} file-object favicon
20519 URL used as link to a shortcut icon for cgit.
20521 Defaults to @samp{"/favicon.ico"}.
20525 @deftypevr {@code{cgit-configuration} parameter} string footer
20526 The content of the file specified with this option will be included verbatim
20527 at the bottom of all pages (i.e.@: it replaces the standard "generated
20530 Defaults to @samp{""}.
20534 @deftypevr {@code{cgit-configuration} parameter} string head-include
20535 The content of the file specified with this option will be included verbatim
20536 in the HTML HEAD section on all pages.
20538 Defaults to @samp{""}.
20542 @deftypevr {@code{cgit-configuration} parameter} string header
20543 The content of the file specified with this option will be included verbatim
20544 at the top of all pages.
20546 Defaults to @samp{""}.
20550 @deftypevr {@code{cgit-configuration} parameter} file-object include
20551 Name of a configfile to include before the rest of the current config- file
20554 Defaults to @samp{""}.
20558 @deftypevr {@code{cgit-configuration} parameter} string index-header
20559 The content of the file specified with this option will be included verbatim
20560 above the repository index.
20562 Defaults to @samp{""}.
20566 @deftypevr {@code{cgit-configuration} parameter} string index-info
20567 The content of the file specified with this option will be included verbatim
20568 below the heading on the repository index page.
20570 Defaults to @samp{""}.
20574 @deftypevr {@code{cgit-configuration} parameter} boolean local-time?
20575 Flag which, if set to @samp{#t}, makes cgit print commit and tag times in
20576 the servers timezone.
20578 Defaults to @samp{#f}.
20582 @deftypevr {@code{cgit-configuration} parameter} file-object logo
20583 URL which specifies the source of an image which will be used as a logo on
20586 Defaults to @samp{"/share/cgit/cgit.png"}.
20590 @deftypevr {@code{cgit-configuration} parameter} string logo-link
20591 URL loaded when clicking on the cgit logo image.
20593 Defaults to @samp{""}.
20597 @deftypevr {@code{cgit-configuration} parameter} file-object owner-filter
20598 Command which will be invoked to format the Owner column of the main page.
20600 Defaults to @samp{""}.
20604 @deftypevr {@code{cgit-configuration} parameter} integer max-atom-items
20605 Number of items to display in atom feeds view.
20607 Defaults to @samp{10}.
20611 @deftypevr {@code{cgit-configuration} parameter} integer max-commit-count
20612 Number of entries to list per page in "log" view.
20614 Defaults to @samp{50}.
20618 @deftypevr {@code{cgit-configuration} parameter} integer max-message-length
20619 Number of commit message characters to display in "log" view.
20621 Defaults to @samp{80}.
20625 @deftypevr {@code{cgit-configuration} parameter} integer max-repo-count
20626 Specifies the number of entries to list per page on the repository index
20629 Defaults to @samp{50}.
20633 @deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length
20634 Specifies the maximum number of repo description characters to display on
20635 the repository index page.
20637 Defaults to @samp{80}.
20641 @deftypevr {@code{cgit-configuration} parameter} integer max-blob-size
20642 Specifies the maximum size of a blob to display HTML for in KBytes.
20644 Defaults to @samp{0}.
20648 @deftypevr {@code{cgit-configuration} parameter} string max-stats
20649 Maximum statistics period. Valid values are @samp{week},@samp{month},
20650 @samp{quarter} and @samp{year}.
20652 Defaults to @samp{""}.
20656 @deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype
20657 Mimetype for the specified filename extension.
20659 Defaults to @samp{((gif "image/gif") (html "text/html") (jpg "image/jpeg")
20660 (jpeg "image/jpeg") (pdf "application/pdf") (png "image/png") (svg
20661 "image/svg+xml"))}.
20665 @deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file
20666 Specifies the file to use for automatic mimetype lookup.
20668 Defaults to @samp{""}.
20672 @deftypevr {@code{cgit-configuration} parameter} string module-link
20673 Text which will be used as the formatstring for a hyperlink when a submodule
20674 is printed in a directory listing.
20676 Defaults to @samp{""}.
20680 @deftypevr {@code{cgit-configuration} parameter} boolean nocache?
20681 If set to the value @samp{#t} caching will be disabled.
20683 Defaults to @samp{#f}.
20687 @deftypevr {@code{cgit-configuration} parameter} boolean noplainemail?
20688 If set to @samp{#t} showing full author email addresses will be disabled.
20690 Defaults to @samp{#f}.
20694 @deftypevr {@code{cgit-configuration} parameter} boolean noheader?
20695 Flag which, when set to @samp{#t}, will make cgit omit the standard header
20698 Defaults to @samp{#f}.
20702 @deftypevr {@code{cgit-configuration} parameter} project-list project-list
20703 A list of subdirectories inside of @code{repository-directory}, relative to
20704 it, that should loaded as Git repositories. An empty list means that all
20705 subdirectories will be loaded.
20707 Defaults to @samp{()}.
20711 @deftypevr {@code{cgit-configuration} parameter} file-object readme
20712 Text which will be used as default value for @code{cgit-repo-readme}.
20714 Defaults to @samp{""}.
20718 @deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix?
20719 If set to @code{#t} and @code{repository-directory} is enabled, if any
20720 repositories are found with a suffix of @code{.git}, this suffix will be
20721 removed for the URL and name.
20723 Defaults to @samp{#f}.
20727 @deftypevr {@code{cgit-configuration} parameter} integer renamelimit
20728 Maximum number of files to consider when detecting renames.
20730 Defaults to @samp{-1}.
20734 @deftypevr {@code{cgit-configuration} parameter} string repository-sort
20735 The way in which repositories in each section are sorted.
20737 Defaults to @samp{""}.
20741 @deftypevr {@code{cgit-configuration} parameter} robots-list robots
20742 Text used as content for the @code{robots} meta-tag.
20744 Defaults to @samp{("noindex" "nofollow")}.
20748 @deftypevr {@code{cgit-configuration} parameter} string root-desc
20749 Text printed below the heading on the repository index page.
20751 Defaults to @samp{"a fast webinterface for the git dscm"}.
20755 @deftypevr {@code{cgit-configuration} parameter} string root-readme
20756 The content of the file specified with this option will be included verbatim
20757 below thef "about" link on the repository index page.
20759 Defaults to @samp{""}.
20763 @deftypevr {@code{cgit-configuration} parameter} string root-title
20764 Text printed as heading on the repository index page.
20766 Defaults to @samp{""}.
20770 @deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path
20771 If set to @samp{#t} and repository-directory is enabled,
20772 repository-directory will recurse into directories whose name starts with a
20773 period. Otherwise, repository-directory will stay away from such
20774 directories, considered as "hidden". Note that this does not apply to the
20775 ".git" directory in non-bare repos.
20777 Defaults to @samp{#f}.
20781 @deftypevr {@code{cgit-configuration} parameter} list snapshots
20782 Text which specifies the default set of snapshot formats that cgit generates
20785 Defaults to @samp{()}.
20789 @deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory
20790 Name of the directory to scan for repositories (represents
20793 Defaults to @samp{"/srv/git"}.
20797 @deftypevr {@code{cgit-configuration} parameter} string section
20798 The name of the current repository section - all repositories defined after
20799 this option will inherit the current section name.
20801 Defaults to @samp{""}.
20805 @deftypevr {@code{cgit-configuration} parameter} string section-sort
20806 Flag which, when set to @samp{1}, will sort the sections on the repository
20809 Defaults to @samp{""}.
20813 @deftypevr {@code{cgit-configuration} parameter} integer section-from-path
20814 A number which, if defined prior to repository-directory, specifies how many
20815 path elements from each repo path to use as a default section name.
20817 Defaults to @samp{0}.
20821 @deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs?
20822 If set to @samp{#t} shows side-by-side diffs instead of unidiffs per
20825 Defaults to @samp{#f}.
20829 @deftypevr {@code{cgit-configuration} parameter} file-object source-filter
20830 Specifies a command which will be invoked to format plaintext blobs in the
20833 Defaults to @samp{""}.
20837 @deftypevr {@code{cgit-configuration} parameter} integer summary-branches
20838 Specifies the number of branches to display in the repository "summary"
20841 Defaults to @samp{10}.
20845 @deftypevr {@code{cgit-configuration} parameter} integer summary-log
20846 Specifies the number of log entries to display in the repository "summary"
20849 Defaults to @samp{10}.
20853 @deftypevr {@code{cgit-configuration} parameter} integer summary-tags
20854 Specifies the number of tags to display in the repository "summary" view.
20856 Defaults to @samp{10}.
20860 @deftypevr {@code{cgit-configuration} parameter} string strict-export
20861 Filename which, if specified, needs to be present within the repository for
20862 cgit to allow access to that repository.
20864 Defaults to @samp{""}.
20868 @deftypevr {@code{cgit-configuration} parameter} string virtual-root
20869 URL which, if specified, will be used as root for all cgit links.
20871 Defaults to @samp{"/"}.
20875 @deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories
20876 A list of @dfn{cgit-repo} records to use with config.
20878 Defaults to @samp{()}.
20880 Available @code{repository-cgit-configuration} fields are:
20882 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots
20883 A mask of snapshot formats for this repo that cgit generates links for,
20884 restricted by the global @code{snapshots} setting.
20886 Defaults to @samp{()}.
20890 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter
20891 Override the default @code{source-filter}.
20893 Defaults to @samp{""}.
20897 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string url
20898 The relative URL used to access the repository.
20900 Defaults to @samp{""}.
20904 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter
20905 Override the default @code{about-filter}.
20907 Defaults to @samp{""}.
20911 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort
20912 Flag which, when set to @samp{age}, enables date ordering in the branch ref
20913 list, and when set to @samp{name} enables ordering by branch name.
20915 Defaults to @samp{""}.
20919 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url
20920 A list of URLs which can be used to clone repo.
20922 Defaults to @samp{()}.
20926 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter
20927 Override the default @code{commit-filter}.
20929 Defaults to @samp{""}.
20933 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort
20934 Flag which, when set to @samp{date}, enables strict date ordering in the
20935 commit log, and when set to @samp{topo} enables strict topological ordering.
20937 Defaults to @samp{""}.
20941 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string defbranch
20942 The name of the default branch for this repository. If no such branch
20943 exists in the repository, the first branch name (when sorted) is used as
20944 default instead. By default branch pointed to by HEAD, or "master" if there
20945 is no suitable HEAD.
20947 Defaults to @samp{""}.
20951 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc
20952 The value to show as repository description.
20954 Defaults to @samp{""}.
20958 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage
20959 The value to show as repository homepage.
20961 Defaults to @samp{""}.
20965 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter
20966 Override the default @code{email-filter}.
20968 Defaults to @samp{""}.
20972 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph?
20973 A flag which can be used to disable the global setting
20974 @code{enable-commit-graph?}.
20976 Defaults to @samp{disabled}.
20980 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount?
20981 A flag which can be used to disable the global setting
20982 @code{enable-log-filecount?}.
20984 Defaults to @samp{disabled}.
20988 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount?
20989 A flag which can be used to disable the global setting
20990 @code{enable-log-linecount?}.
20992 Defaults to @samp{disabled}.
20996 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches?
20997 Flag which, when set to @code{#t}, will make cgit display remote branches in
20998 the summary and refs views.
21000 Defaults to @samp{disabled}.
21004 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links?
21005 A flag which can be used to override the global setting
21006 @code{enable-subject-links?}.
21008 Defaults to @samp{disabled}.
21012 @deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving?
21013 A flag which can be used to override the global setting
21014 @code{enable-html-serving?}.
21016 Defaults to @samp{disabled}.
21020 @deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide?
21021 Flag which, when set to @code{#t}, hides the repository from the repository
21024 Defaults to @samp{#f}.
21028 @deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore?
21029 Flag which, when set to @samp{#t}, ignores the repository.
21031 Defaults to @samp{#f}.
21035 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object logo
21036 URL which specifies the source of an image which will be used as a logo on
21039 Defaults to @samp{""}.
21043 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link
21044 URL loaded when clicking on the cgit logo image.
21046 Defaults to @samp{""}.
21050 @deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter
21051 Override the default @code{owner-filter}.
21053 Defaults to @samp{""}.
21057 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string module-link
21058 Text which will be used as the formatstring for a hyperlink when a submodule
21059 is printed in a directory listing. The arguments for the formatstring are
21060 the path and SHA1 of the submodule commit.
21062 Defaults to @samp{""}.
21066 @deftypevr {@code{repository-cgit-configuration} parameter} module-link-path module-link-path
21067 Text which will be used as the formatstring for a hyperlink when a submodule
21068 with the specified subdirectory path is printed in a directory listing.
21070 Defaults to @samp{()}.
21074 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats
21075 Override the default maximum statistics period.
21077 Defaults to @samp{""}.
21081 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string name
21082 The value to show as repository name.
21084 Defaults to @samp{""}.
21088 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner
21089 A value used to identify the owner of the repository.
21091 Defaults to @samp{""}.
21095 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string path
21096 An absolute path to the repository directory.
21098 Defaults to @samp{""}.
21102 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string readme
21103 A path (relative to repo) which specifies a file to include verbatim as the
21104 "About" page for this repo.
21106 Defaults to @samp{""}.
21110 @deftypevr {@code{repository-cgit-configuration} parameter} repo-string section
21111 The name of the current repository section - all repositories defined after
21112 this option will inherit the current section name.
21114 Defaults to @samp{""}.
21118 @deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options
21119 Extra options will be appended to cgitrc file.
21121 Defaults to @samp{()}.
21127 @deftypevr {@code{cgit-configuration} parameter} list extra-options
21128 Extra options will be appended to cgitrc file.
21130 Defaults to @samp{()}.
21135 @c %end of fragment
21137 However, it could be that you just want to get a @code{cgitrc} up and
21138 running. In that case, you can pass an @code{opaque-cgit-configuration} as
21139 a record to @code{cgit-service-type}. As its name indicates, an opaque
21140 configuration does not have easy reflective capabilities.
21142 Available @code{opaque-cgit-configuration} fields are:
21144 @deftypevr {@code{opaque-cgit-configuration} parameter} package cgit
21148 @deftypevr {@code{opaque-cgit-configuration} parameter} string string
21149 The contents of the @code{cgitrc}, as a string.
21152 For example, if your @code{cgitrc} is just the empty string, you could
21153 instantiate a cgit service like this:
21156 (service cgit-service-type
21157 (opaque-cgit-configuration
21161 @subsubheading Gitolite Service
21163 @cindex Gitolite service
21164 @cindex Git, hosting
21165 @uref{http://gitolite.com/gitolite/, Gitolite} is a tool for hosting Git
21166 repositories on a central server.
21168 Gitolite can handle multiple repositories and users, and supports flexible
21169 configuration of the permissions for the users on the repositories.
21171 The following example will configure Gitolite using the default @code{git}
21172 user, and the provided SSH public key.
21175 (service gitolite-service-type
21176 (gitolite-configuration
21177 (admin-pubkey (plain-file
21179 "ssh-rsa AAAA... guix@@example.com"))))
21182 Gitolite is configured through a special admin repository which you can
21183 clone, for example, if you setup Gitolite on @code{example.com}, you would
21184 run the following command to clone the admin repository.
21187 git clone git@@example.com:gitolite-admin
21190 When the Gitolite service is activated, the provided @code{admin-pubkey}
21191 will be inserted in to the @file{keydir} directory in the gitolite-admin
21192 repository. If this results in a change in the repository, it will be
21193 committed using the message ``gitolite setup by GNU Guix''.
21195 @deftp {Data Type} gitolite-configuration
21196 Data type representing the configuration for @code{gitolite-service-type}.
21199 @item @code{package} (default: @var{gitolite})
21200 Gitolite package to use.
21202 @item @code{user} (default: @var{git})
21203 User to use for Gitolite. This will be user that you use when accessing
21206 @item @code{group} (default: @var{git})
21207 Group to use for Gitolite.
21209 @item @code{home-directory} (default: @var{"/var/lib/gitolite"})
21210 Directory in which to store the Gitolite configuration and repositories.
21212 @item @code{rc-file} (default: @var{(gitolite-rc-file)})
21213 A ``file-like'' object (@pxref{G-Ausdrücke, file-like objects}),
21214 representing the configuration for Gitolite.
21216 @item @code{admin-pubkey} (default: @var{#f})
21217 A ``file-like'' object (@pxref{G-Ausdrücke, file-like objects}) used to
21218 setup Gitolite. This will be inserted in to the @file{keydir} directory
21219 within the gitolite-admin repository.
21221 To specify the SSH key as a string, use the @code{plain-file} function.
21224 (plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com")
21230 @deftp {Data Type} gitolite-rc-file
21231 Data type representing the Gitolite RC file.
21234 @item @code{umask} (default: @code{#o0077})
21235 This controls the permissions Gitolite sets on the repositories and their
21238 A value like @code{#o0027} will give read access to the group used by
21239 Gitolite (by default: @code{git}). This is necessary when using Gitolite
21240 with software like cgit or gitweb.
21242 @item @code{git-config-keys} (default: @code{""})
21243 Gitolite allows you to set git config values using the "config"
21244 keyword. This setting allows control over the config keys to accept.
21246 @item @code{roles} (default: @code{'(("READERS" . 1) ("WRITERS" . ))})
21247 Set the role names allowed to be used by users running the perms command.
21249 @item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")})
21250 This setting controls the commands and features to enable within Gitolite.
21257 @subsubsection Spieldienste
21259 @subsubheading The Battle for Wesnoth Service
21261 @uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn based
21262 tactical strategy game, with several single player campaigns, and
21263 multiplayer games (both networked and local).
21265 @defvar {Scheme Variable} wesnothd-service-type
21266 Service type for the wesnothd service. Its value must be a
21267 @code{wesnothd-configuration} object. To run wesnothd in the default
21268 configuration, instantiate it as:
21271 (service wesnothd-service-type)
21275 @deftp {Data Type} wesnothd-configuration
21276 Data type representing the configuration of @command{wesnothd}.
21279 @item @code{package} (default: @code{wesnoth-server})
21280 The wesnoth server package to use.
21282 @item @code{port} (default: @code{15000})
21283 The port to bind the server to.
21287 @node Verschiedene Dienste
21288 @subsubsection Verschiedene Dienste
21290 @cindex fingerprint
21291 @subsubheading Fingerprint Service
21293 The @code{(gnu services fingerprint)} module provides a DBus service to read
21294 and identify fingerprints via a fingerprint sensor.
21296 @defvr {Scheme Variable} fprintd-service-type
21297 The service type for @command{fprintd}, which provides the fingerprint
21298 reading capability.
21301 (service fprintd-service-type)
21306 @subsubheading System Control Service
21308 The @code{(gnu services sysctl)} provides a service to configure kernel
21309 parameters at boot.
21311 @defvr {Scheme Variable} sysctl-service-type
21312 The service type for @command{sysctl}, which modifies kernel parameters
21313 under @file{/proc/sys/}. To enable IPv4 forwarding, it can be instantiated
21317 (service sysctl-service-type
21318 (sysctl-configuration
21319 (settings '(("net.ipv4.ip_forward" . "1")))))
21323 @deftp {Data Type} sysctl-configuration
21324 The data type representing the configuration of @command{sysctl}.
21327 @item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"})
21328 The @command{sysctl} executable to use.
21330 @item @code{settings} (default: @code{'()})
21331 An association list specifies kernel parameters and their values.
21336 @subsubheading PC/SC Smart Card Daemon Service
21338 The @code{(gnu services security-token)} module provides the following
21339 service to run @command{pcscd}, the PC/SC Smart Card Daemon.
21340 @command{pcscd} is the daemon program for pcsc-lite and the MuscleCard
21341 framework. It is a resource manager that coordinates communications with
21342 smart card readers, smart cards and cryptographic tokens that are connected
21345 @defvr {Scheme Variable} pcscd-service-type
21346 Service type for the @command{pcscd} service. Its value must be a
21347 @code{pcscd-configuration} object. To run pcscd in the default
21348 configuration, instantiate it as:
21351 (service pcscd-service-type)
21355 @deftp {Data Type} pcscd-configuration
21356 The data type representing the configuration of @command{pcscd}.
21359 @item @code{pcsc-lite} (default: @code{pcsc-lite})
21360 The pcsc-lite package that provides pcscd.
21361 @item @code{usb-drivers} (default: @code{(list ccid)})
21362 List of packages that provide USB drivers to pcscd. Drivers are expected to
21363 be under @file{pcsc/drivers} in the store directory of the package.
21368 @subsubheading Lirc Service
21370 The @code{(gnu services lirc)} module provides the following service.
21372 @deffn {Scheme Procedure} lirc-service [#:lirc lirc] @
21373 [#:device #f] [#:driver #f] [#:config-file #f] @ [#:extra-options '()]
21374 Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that
21375 decodes infrared signals from remote controls.
21377 Optionally, @var{device}, @var{driver} and @var{config-file} (configuration
21378 file name) may be specified. See @command{lircd} manual for details.
21380 Finally, @var{extra-options} is a list of additional command-line options
21381 passed to @command{lircd}.
21385 @subsubheading Spice Service
21387 The @code{(gnu services spice)} module provides the following service.
21389 @deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent]
21390 Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a
21391 daemon that enables sharing the clipboard with a vm and setting the guest
21392 display resolution when the graphical console window resizes.
21395 @subsubsection Dictionary Services
21397 The @code{(gnu services dict)} module provides the following service:
21399 @deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)]
21400 Return a service that runs the @command{dicod} daemon, an implementation of
21401 DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}).
21403 The optional @var{config} argument specifies the configuration for
21404 @command{dicod}, which should be a @code{<dicod-configuration>} object, by
21405 default it serves the GNU Collaborative International Dictonary of English.
21407 You can add @command{open localhost} to your @file{~/.dico} file to make
21408 @code{localhost} the default server for @command{dico} client
21409 (@pxref{Initialization File,,, dico, GNU Dico Manual}).
21412 @deftp {Data Type} dicod-configuration
21413 Data type representing the configuration of dicod.
21416 @item @code{dico} (default: @var{dico})
21417 Package object of the GNU Dico dictionary server.
21419 @item @code{interfaces} (default: @var{'("localhost")})
21420 This is the list of IP addresses and ports and possibly socket file names to
21421 listen to (@pxref{Server Settings, @code{listen} directive,, dico, GNU Dico
21424 @item @code{handlers} (default: @var{'()})
21425 List of @code{<dicod-handler>} objects denoting handlers (module instances).
21427 @item @code{databases} (default: @var{(list %dicod-database:gcide)})
21428 List of @code{<dicod-database>} objects denoting dictionaries to be served.
21432 @deftp {Data Type} dicod-handler
21433 Data type representing a dictionary handler (module instance).
21437 Name of the handler (module instance).
21439 @item @code{module} (default: @var{#f})
21440 Name of the dicod module of the handler (instance). If it is @code{#f}, the
21441 module has the same name as the handler. (@pxref{Module,,, dico, GNU Dico
21444 @item @code{options}
21445 List of strings or gexps representing the arguments for the module handler
21449 @deftp {Data Type} dicod-database
21450 Data type representing a dictionary database.
21454 Name of the database, will be used in DICT commands.
21456 @item @code{handler}
21457 Name of the dicod handler (module instance) used by this database
21458 (@pxref{Handlers,,, dico, GNU Dico Manual}).
21460 @item @code{complex?} (default: @var{#f})
21461 Whether the database configuration complex. The complex configuration will
21462 need a corresponding @code{<dicod-handler>} object, otherwise not.
21464 @item @code{options}
21465 List of strings or gexps representing the arguments for the database
21466 (@pxref{Databases,,, dico, GNU Dico Manual}).
21470 @defvr {Scheme Variable} %dicod-database:gcide
21471 A @code{<dicod-database>} object serving the GNU Collaborative International
21472 Dictionary of English using the @code{gcide} package.
21475 The following is an example @code{dicod-service} configuration.
21478 (dicod-service #:config
21479 (dicod-configuration
21480 (handlers (list (dicod-handler
21484 (list #~(string-append "dbdir=" #$wordnet))))))
21485 (databases (list (dicod-database
21488 (handler "wordnet")
21489 (options '("database=wn")))
21490 %dicod-database:gcide))))
21493 @node Setuid-Programme
21494 @subsection Setuid-Programme
21496 @cindex setuid programs
21497 Some programs need to run with ``root'' privileges, even when they are
21498 launched by unprivileged users. A notorious example is the @command{passwd}
21499 program, which users can run to change their password, and which needs to
21500 access the @file{/etc/passwd} and @file{/etc/shadow} files---something
21501 normally restricted to root, for obvious security reasons. To address that,
21502 these executables are @dfn{setuid-root}, meaning that they always run with
21503 root privileges (@pxref{How Change Persona,,, libc, The GNU C Library
21504 Reference Manual}, for more info about the setuid mechanism.)
21506 The store itself @emph{cannot} contain setuid programs: that would be a
21507 security issue since any user on the system can write derivations that
21508 populate the store (@pxref{Der Store}). Thus, a different mechanism is
21509 used: instead of changing the setuid bit directly on files that are in the
21510 store, we let the system administrator @emph{declare} which programs should
21513 The @code{setuid-programs} field of an @code{operating-system} declaration
21514 contains a list of G-expressions denoting the names of programs to be
21515 setuid-root (@pxref{Das Konfigurationssystem nutzen}). For instance, the
21516 @command{passwd} program, which is part of the Shadow package, can be
21517 designated by this G-expression (@pxref{G-Ausdrücke}):
21520 #~(string-append #$shadow "/bin/passwd")
21523 A default set of setuid programs is defined by the @code{%setuid-programs}
21524 variable of the @code{(gnu system)} module.
21526 @defvr {Scheme Variable} %setuid-programs
21527 A list of G-expressions denoting common programs that are setuid-root.
21529 The list includes commands such as @command{passwd}, @command{ping},
21530 @command{su}, and @command{sudo}.
21533 Under the hood, the actual setuid programs are created in the
21534 @file{/run/setuid-programs} directory at system activation time. The files
21535 in this directory refer to the ``real'' binaries, which are in the store.
21537 @node X.509-Zertifikate
21538 @subsection X.509-Zertifikate
21540 @cindex HTTPS, certificates
21541 @cindex X.509 certificates
21543 Web servers available over HTTPS (that is, HTTP over the transport-layer
21544 security mechanism, TLS) send client programs an @dfn{X.509 certificate}
21545 that the client can then use to @emph{authenticate} the server. To do that,
21546 clients verify that the server's certificate is signed by a so-called
21547 @dfn{certificate authority} (CA). But to verify the CA's signature, clients
21548 must have first acquired the CA's certificate.
21550 Web browsers such as GNU@tie{}IceCat include their own set of CA
21551 certificates, such that they are able to verify CA signatures
21554 However, most other programs that can talk HTTPS---@command{wget},
21555 @command{git}, @command{w3m}, etc.---need to be told where CA certificates
21558 @cindex @code{nss-certs}
21559 In GuixSD, this is done by adding a package that provides certificates to
21560 the @code{packages} field of the @code{operating-system} declaration
21561 (@pxref{„operating-system“-Referenz}). GuixSD includes one such package,
21562 @code{nss-certs}, which is a set of CA certificates provided as part of
21563 Mozilla's Network Security Services.
21565 Note that it is @emph{not} part of @var{%base-packages}, so you need to
21566 explicitly add it. The @file{/etc/ssl/certs} directory, which is where most
21567 applications and libraries look for certificates by default, points to the
21568 certificates installed globally.
21570 Unprivileged users, including users of Guix on a foreign distro, can also
21571 install their own certificate package in their profile. A number of
21572 environment variables need to be defined so that applications and libraries
21573 know where to find them. Namely, the OpenSSL library honors the
21574 @code{SSL_CERT_DIR} and @code{SSL_CERT_FILE} variables. Some applications
21575 add their own environment variables; for instance, the Git version control
21576 system honors the certificate bundle pointed to by the @code{GIT_SSL_CAINFO}
21577 environment variable. Thus, you would typically run something like:
21580 $ guix package -i nss-certs
21581 $ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
21582 $ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
21583 $ export GIT_SSL_CAINFO="$SSL_CERT_FILE"
21586 As another example, R requires the @code{CURL_CA_BUNDLE} environment
21587 variable to point to a certificate bundle, so you would have to run
21588 something like this:
21591 $ guix package -i nss-certs
21592 $ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
21595 For other applications you may want to look up the required environment
21596 variable in the relevant documentation.
21599 @node Name Service Switch
21600 @subsection Name Service Switch
21602 @cindex name service switch
21604 The @code{(gnu system nss)} module provides bindings to the configuration
21605 file of the libc @dfn{name service switch} or @dfn{NSS} (@pxref{NSS
21606 Configuration File,,, libc, The GNU C Library Reference Manual}). In a
21607 nutshell, the NSS is a mechanism that allows libc to be extended with new
21608 ``name'' lookup methods for system databases, which includes host names,
21609 service names, user accounts, and more (@pxref{Name Service Switch, System
21610 Databases and Name Service Switch,, libc, The GNU C Library Reference
21613 The NSS configuration specifies, for each system database, which lookup
21614 method is to be used, and how the various methods are chained together---for
21615 instance, under which circumstances NSS should try the next method in the
21616 list. The NSS configuration is given in the @code{name-service-switch}
21617 field of @code{operating-system} declarations (@pxref{„operating-system“-Referenz, @code{name-service-switch}}).
21620 @cindex .local, host name lookup
21621 As an example, the declaration below configures the NSS to use the
21622 @uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns}
21623 back-end}, which supports host name lookups over multicast DNS (mDNS) for
21624 host names ending in @code{.local}:
21627 (name-service-switch
21628 (hosts (list %files ;first, check /etc/hosts
21630 ;; If the above did not succeed, try
21631 ;; with 'mdns_minimal'.
21633 (name "mdns_minimal")
21635 ;; 'mdns_minimal' is authoritative for
21636 ;; '.local'. When it returns "not found",
21637 ;; no need to try the next methods.
21638 (reaction (lookup-specification
21639 (not-found => return))))
21641 ;; Then fall back to DNS.
21645 ;; Finally, try with the "full" 'mdns'.
21650 Do not worry: the @code{%mdns-host-lookup-nss} variable (see below)
21651 contains this configuration, so you will not have to type it if all you want
21652 is to have @code{.local} host lookup working.
21654 Note that, in this case, in addition to setting the
21655 @code{name-service-switch} of the @code{operating-system} declaration, you
21656 also need to use @code{avahi-service} (@pxref{Netzwerkdienste,
21657 @code{avahi-service}}), or @var{%desktop-services}, which includes it
21658 (@pxref{Desktop-Dienste}). Doing this makes @code{nss-mdns} accessible to
21659 the name service cache daemon (@pxref{Basisdienste, @code{nscd-service}}).
21661 For convenience, the following variables provide typical NSS configurations.
21663 @defvr {Scheme Variable} %default-nss
21664 This is the default name service switch configuration, a
21665 @code{name-service-switch} object.
21668 @defvr {Scheme Variable} %mdns-host-lookup-nss
21669 This is the name service switch configuration with support for host name
21670 lookup over multicast DNS (mDNS) for host names ending in @code{.local}.
21673 The reference for name service switch configuration is given below. It is a
21674 direct mapping of the configuration file format of the C library , so please
21675 refer to the C library manual for more information (@pxref{NSS Configuration
21676 File,,, libc, The GNU C Library Reference Manual}). Compared to the
21677 configuration file format of libc NSS, it has the advantage not only of
21678 adding this warm parenthetic feel that we like, but also static checks: you
21679 will know about syntax errors and typos as soon as you run @command{guix
21682 @deftp {Data Type} name-service-switch
21684 This is the data type representation the configuration of libc's name
21685 service switch (NSS). Each field below represents one of the supported
21702 The system databases handled by the NSS. Each of these fields must be a
21703 list of @code{<name-service>} objects (see below).
21707 @deftp {Data Type} name-service
21709 This is the data type representing an actual name service and the associated
21714 A string denoting the name service (@pxref{Services in the NSS
21715 configuration,,, libc, The GNU C Library Reference Manual}).
21717 Note that name services listed here must be visible to nscd. This is
21718 achieved by passing the @code{#:name-services} argument to
21719 @code{nscd-service} the list of packages providing the needed name services
21720 (@pxref{Basisdienste, @code{nscd-service}}).
21723 An action specified using the @code{lookup-specification} macro
21724 (@pxref{Actions in the NSS configuration,,, libc, The GNU C Library
21725 Reference Manual}). For example:
21728 (lookup-specification (unavailable => continue)
21729 (success => return))
21734 @node Initiale RAM-Disk
21735 @subsection Initiale RAM-Disk
21738 @cindex initial RAM disk
21739 For bootstrapping purposes, the Linux-Libre kernel is passed an @dfn{initial
21740 RAM disk}, or @dfn{initrd}. An initrd contains a temporary root file system
21741 as well as an initialization script. The latter is responsible for mounting
21742 the real root file system, and for loading any kernel modules that may be
21743 needed to achieve that.
21745 The @code{initrd-modules} field of an @code{operating-system} declaration
21746 allows you to specify Linux-libre kernel modules that must be available in
21747 the initrd. In particular, this is where you would list modules needed to
21748 actually drive the hard disk where your root partition is---although the
21749 default value of @code{initrd-modules} should cover most use cases. For
21750 example, assuming you need the @code{megaraid_sas} module in addition to the
21751 default modules to be able to access your root file system, you would write:
21756 (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
21759 @defvr {Scheme Variable} %base-initrd-modules
21760 This is the list of kernel modules included in the initrd by default.
21763 Furthermore, if you need lower-level customization, the @code{initrd} field
21764 of an @code{operating-system} declaration allows you to specify which initrd
21765 you would like to use. The @code{(gnu system linux-initrd)} module provides
21766 three ways to build an initrd: the high-level @code{base-initrd} procedure
21767 and the low-level @code{raw-initrd} and @code{expression->initrd}
21770 The @code{base-initrd} procedure is intended to cover most common uses. For
21771 example, if you want to add a bunch of kernel modules to be loaded at boot
21772 time, you can define the @code{initrd} field of the operating system
21773 declaration like this:
21776 (initrd (lambda (file-systems . rest)
21777 ;; Create a standard initrd but set up networking
21778 ;; with the parameters QEMU expects by default.
21779 (apply base-initrd file-systems
21780 #:qemu-networking? #t
21784 The @code{base-initrd} procedure also handles common use cases that involves
21785 using the system as a QEMU guest, or as a ``live'' system with volatile root
21788 The @code{base-initrd} procedure is built from @code{raw-initrd} procedure.
21789 Unlike @code{base-initrd}, @code{raw-initrd} doesn't do anything high-level,
21790 such as trying to guess which kernel modules and packages should be included
21791 to the initrd. An example use of @code{raw-initrd} is when a user has a
21792 custom Linux kernel configuration and default kernel modules included by
21793 @code{base-initrd} are not available.
21795 The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd}
21796 honors several options passed on the Linux kernel command line (that is,
21797 arguments passed @i{via} the @code{linux} command of GRUB, or the
21798 @code{-append} option of QEMU), notably:
21801 @item --load=@var{boot}
21802 Tell the initial RAM disk to load @var{boot}, a file containing a Scheme
21803 program, once it has mounted the root file system.
21805 GuixSD uses this option to yield control to a boot program that runs the
21806 service activation programs and then spawns the GNU@tie{}Shepherd, the
21807 initialization system.
21809 @item --root=@var{root}
21810 Mount @var{root} as the root file system. @var{root} can be a device name
21811 like @code{/dev/sda1}, a file system label, or a file system UUID.
21813 @item --system=@var{System}
21814 Have @file{/run/booted-system} and @file{/run/current-system} point to
21817 @item modprobe.blacklist=@var{modules}@dots{}
21818 @cindex module, black-listing
21819 @cindex black list, of kernel modules
21820 Instruct the initial RAM disk as well as the @command{modprobe} command
21821 (from the kmod package) to refuse to load @var{modules}. @var{modules} must
21822 be a comma-separated list of module names---e.g., @code{usbkbd,9pnet}.
21825 Start a read-eval-print loop (REPL) from the initial RAM disk before it
21826 tries to load kernel modules and to mount the root file system. Our
21827 marketing team calls it @dfn{boot-to-Guile}. The Schemer in you will love
21828 it. @xref{Using Guile Interactively,,, guile, GNU Guile Reference Manual},
21829 for more information on Guile's REPL.
21833 Now that you know all the features that initial RAM disks produced by
21834 @code{base-initrd} and @code{raw-initrd} provide, here is how to use it and
21835 customize it further.
21838 @cindex initial RAM disk
21839 @deffn {Scheme Procedure} raw-initrd @var{file-systems} @
21840 [#:linux-modules '()] [#:mapped-devices '()] @ [#:helper-packages '()]
21841 [#:qemu-networking? #f] [#:volatile-root? #f] Return a derivation that
21842 builds a raw initrd. @var{file-systems} is a list of file systems to be
21843 mounted by the initrd, possibly in addition to the root file system
21844 specified on the kernel command line via @code{--root}. @var{linux-modules}
21845 is a list of kernel modules to be loaded at boot time. @var{mapped-devices}
21846 is a list of device mappings to realize before @var{file-systems} are
21847 mounted (@pxref{Abgebildete Geräte}). @var{helper-packages} is a list of
21848 packages to be copied in the initrd. It may include @code{e2fsck/static} or
21849 other packages needed by the initrd to check the root file system.
21851 When @var{qemu-networking?} is true, set up networking with the standard
21852 QEMU parameters. When @var{virtio?} is true, load additional modules so
21853 that the initrd can be used as a QEMU guest with para-virtualized I/O
21856 When @var{volatile-root?} is true, the root file system is writable but any
21857 changes to it are lost.
21860 @deffn {Scheme Procedure} base-initrd @var{file-systems} @
21861 [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]@
21862 [#:linux-modules '()] Return as a file-like object a generic initrd, with
21863 kernel modules taken from @var{linux}. @var{file-systems} is a list of
21864 file-systems to be mounted by the initrd, possibly in addition to the root
21865 file system specified on the kernel command line via @code{--root}.
21866 @var{mapped-devices} is a list of device mappings to realize before
21867 @var{file-systems} are mounted.
21869 @var{qemu-networking?} and @var{volatile-root?} behaves as in
21872 The initrd is automatically populated with all the kernel modules necessary
21873 for @var{file-systems} and for the given options. Additional kernel modules
21874 can be listed in @var{linux-modules}. They will be added to the initrd, and
21875 loaded at boot time in the order in which they appear.
21878 Needless to say, the initrds we produce and use embed a statically-linked
21879 Guile, and the initialization program is a Guile program. That gives a lot
21880 of flexibility. The @code{expression->initrd} procedure builds such an
21881 initrd, given the program to run in that initrd.
21883 @deffn {Scheme Procedure} expression->initrd @var{exp} @
21884 [#:guile %guile-static-stripped] [#:name "guile-initrd"] Return as a
21885 file-like object a Linux initrd (a gzipped cpio archive) containing
21886 @var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All
21887 the derivations referenced by @var{exp} are automatically copied to the
21891 @node Bootloader-Konfiguration
21892 @subsection Bootloader-Konfiguration
21895 @cindex boot loader
21897 The operating system supports multiple bootloaders. The bootloader is
21898 configured using @code{bootloader-configuration} declaration. All the
21899 fields of this structure are bootloader agnostic except for one field,
21900 @code{bootloader} that indicates the bootloader to be configured and
21903 Some of the bootloaders do not honor every field of
21904 @code{bootloader-configuration}. For instance, the extlinux bootloader does
21905 not support themes and thus ignores the @code{theme} field.
21907 @deftp {Data Type} bootloader-configuration
21908 The type of a bootloader configuration declaration.
21912 @item @code{bootloader}
21913 @cindex EFI, bootloader
21914 @cindex UEFI, bootloader
21915 @cindex BIOS, bootloader
21916 The bootloader to use, as a @code{bootloader} object. For now
21917 @code{grub-bootloader}, @code{grub-efi-bootloader},
21918 @code{extlinux-bootloader} and @code{u-boot-bootloader} are supported.
21920 @vindex grub-efi-bootloader
21921 @code{grub-efi-bootloader} allows to boot on modern systems using the
21922 @dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should
21923 use if the installation image contains a @file{/sys/firmware/efi} directory
21924 when you boot it on your system.
21926 @vindex grub-bootloader
21927 @code{grub-bootloader} allows you to boot in particular Intel-based machines
21928 in ``legacy'' BIOS mode.
21930 @cindex ARM, bootloaders
21931 @cindex AArch64, bootloaders
21932 Available bootloaders are described in @code{(gnu bootloader @dots{})}
21933 modules. In particular, @code{(gnu bootloader u-boot)} contains definitions
21934 of bootloaders for a wide range of ARM and AArch64 systems, using the
21935 @uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}.
21937 @item @code{target}
21938 This is a string denoting the target onto which to install the bootloader.
21940 The interpretation depends on the bootloader in question. For
21941 @code{grub-bootloader}, for example, it should be a device name understood
21942 by the bootloader @command{installer} command, such as @code{/dev/sda} or
21943 @code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}). For
21944 @code{grub-efi-bootloader}, it should be the mount point of the EFI file
21945 system, usually @file{/boot/efi}.
21947 @item @code{menu-entries} (default: @code{()})
21948 A possibly empty list of @code{menu-entry} objects (see below), denoting
21949 entries to appear in the bootloader menu, in addition to the current system
21950 entry and the entry pointing to previous system generations.
21952 @item @code{default-entry} (default: @code{0})
21953 The index of the default boot menu entry. Index 0 is for the entry of the
21956 @item @code{timeout} (default: @code{5})
21957 The number of seconds to wait for keyboard input before booting. Set to 0
21958 to boot immediately, and to -1 to wait indefinitely.
21960 @item @code{theme} (default: @var{#f})
21961 The bootloader theme object describing the theme to use. If no theme is
21962 provided, some bootloaders might use a default theme, that's true for GRUB.
21964 @item @code{terminal-outputs} (default: @code{'gfxterm})
21965 The output terminals used for the bootloader boot menu, as a list of
21966 symbols. GRUB accepts the values: @code{console}, @code{serial},
21967 @code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text},
21968 @code{morse}, and @code{pkmodem}. This field corresponds to the GRUB
21969 variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple configuration,,,
21970 grub,GNU GRUB manual}).
21972 @item @code{terminal-inputs} (default: @code{'()})
21973 The input terminals used for the bootloader boot menu, as a list of
21974 symbols. For GRUB, the default is the native platform terminal as
21975 determined at run-time. GRUB accepts the values: @code{console},
21976 @code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and
21977 @code{usb_keyboard}. This field corresponds to the GRUB variable
21978 @code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB
21981 @item @code{serial-unit} (default: @code{#f})
21982 The serial unit used by the bootloader, as an integer from 0 to 3. For
21983 GRUB, it is chosen at run-time; currently GRUB chooses 0, which corresponds
21984 to COM1 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
21986 @item @code{serial-speed} (default: @code{#f})
21987 The speed of the serial interface, as an integer. For GRUB, the default
21988 value is chosen at run-time; currently GRUB chooses 9600@tie{}bps
21989 (@pxref{Serial terminal,,, grub,GNU GRUB manual}).
21996 Should you want to list additional boot menu entries @i{via} the
21997 @code{menu-entries} field above, you will need to create them with the
21998 @code{menu-entry} form. For example, imagine you want to be able to boot
21999 another distro (hard to imagine!), you can define a menu entry along these
22004 (label "The Other Distro")
22005 (linux "/boot/old/vmlinux-2.6.32")
22006 (linux-arguments '("root=/dev/sda2"))
22007 (initrd "/boot/old/initrd"))
22012 @deftp {Data Type} menu-entry
22013 The type of an entry in the bootloader menu.
22018 The label to show in the menu---e.g., @code{"GNU"}.
22021 The Linux kernel image to boot, for example:
22024 (file-append linux-libre "/bzImage")
22027 For GRUB, it is also possible to specify a device explicitly in the file
22028 path using GRUB's device naming convention (@pxref{Naming convention,,,
22029 grub, GNU GRUB manual}), for example:
22032 "(hd0,msdos1)/boot/vmlinuz"
22035 If the device is specified explicitly as above, then the @code{device} field
22036 is ignored entirely.
22038 @item @code{linux-arguments} (default: @code{()})
22039 The list of extra Linux kernel command-line arguments---e.g.,
22040 @code{("console=ttyS0")}.
22042 @item @code{initrd}
22043 A G-Expression or string denoting the file name of the initial RAM disk to
22044 use (@pxref{G-Ausdrücke}).
22045 @item @code{device} (default: @code{#f})
22046 The device where the kernel and initrd are to be found---i.e., for GRUB,
22047 @dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}).
22049 This may be a file system label (a string), a file system UUID (a
22050 bytevector, @pxref{Dateisysteme}), or @code{#f}, in which case the
22051 bootloader will search the device containing the file specified by the
22052 @code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It must
22053 @emph{not} be an OS device name such as @file{/dev/sda1}.
22058 @c FIXME: Write documentation once it's stable.
22059 Fow now only GRUB has theme support. GRUB themes are created using the
22060 @code{grub-theme} form, which is not documented yet.
22062 @defvr {Scheme Variable} %default-theme
22063 This is the default GRUB theme used by the operating system if no
22064 @code{theme} field is specified in @code{bootloader-configuration} record.
22066 It comes with a fancy background image displaying the GNU and Guix logos.
22070 @node Aufruf von guix system
22071 @subsection Invoking @code{guix system}
22073 Once you have written an operating system declaration as seen in the
22074 previous section, it can be @dfn{instantiated} using the @command{guix
22075 system} command. The synopsis is:
22078 guix system @var{options}@dots{} @var{action} @var{file}
22081 @var{file} must be the name of a file containing an @code{operating-system}
22082 declaration. @var{action} specifies how the operating system is
22083 instantiated. Currently the following values are supported:
22087 Display available service type definitions that match the given regular
22088 expressions, sorted by relevance:
22091 $ guix system search console font
22092 name: console-fonts
22093 location: gnu/services/base.scm:729:2
22094 extends: shepherd-root
22095 description: Install the given fonts on the specified ttys (fonts are
22096 + per virtual console on GNU/Linux). The value of this service is a list
22097 + of tty/font pairs like:
22099 + '(("tty1" . "LatGrkCyr-8x16"))
22103 location: gnu/services/base.scm:1048:2
22104 extends: shepherd-root
22105 description: Provide console login using the `mingetty' program.
22109 location: gnu/services/base.scm:775:2
22111 description: Provide a console log-in service as specified by its
22112 + configuration value, a `login-configuration' object.
22118 As for @command{guix package --search}, the result is written in
22119 @code{recutils} format, which makes it easy to filter the output
22120 (@pxref{Top, GNU recutils databases,, recutils, GNU recutils manual}).
22123 Build the operating system described in @var{file}, activate it, and switch
22124 to it@footnote{This action (and the related actions @code{switch-generation}
22125 and @code{roll-back}) are usable only on systems already running GuixSD.}.
22127 This effects all the configuration specified in @var{file}: user accounts,
22128 system services, global package list, setuid programs, etc. The command
22129 starts system services specified in @var{file} that are not currently
22130 running; if a service is currently running this command will arrange for it
22131 to be upgraded the next time it is stopped (e.g.@: by @code{herd stop X} or
22132 @code{herd restart X}).
22134 This command creates a new generation whose number is one greater than the
22135 current generation (as reported by @command{guix system list-generations}).
22136 If that generation already exists, it will be overwritten. This behavior
22137 mirrors that of @command{guix package} (@pxref{Aufruf von guix package}).
22139 It also adds a bootloader menu entry for the new OS configuration, ---unless
22140 @option{--no-bootloader} is passed. For GRUB, it moves entries for older
22141 configurations to a submenu, allowing you to choose an older system
22142 generation at boot time should you need it.
22144 @quotation Anmerkung
22145 @c The paragraph below refers to the problem discussed at
22146 @c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>.
22147 It is highly recommended to run @command{guix pull} once before you run
22148 @command{guix system reconfigure} for the first time (@pxref{Aufruf von guix pull}). Failing to do that you would see an older version of Guix once
22149 @command{reconfigure} has completed.
22152 @item switch-generation
22153 @cindex Generationen
22154 Switch to an existing system generation. This action atomically switches
22155 the system profile to the specified system generation. It also rearranges
22156 the system's existing bootloader menu entries. It makes the menu entry for
22157 the specified system generation the default, and it moves the entries for
22158 the other generatiors to a submenu, if supported by the bootloader being
22159 used. The next time the system boots, it will use the specified system
22162 The bootloader itself is not being reinstalled when using this command.
22163 Thus, the installed bootloader is used with an updated configuration file.
22165 The target generation can be specified explicitly by its generation number.
22166 For example, the following invocation would switch to system generation 7:
22169 guix system switch-generation 7
22172 The target generation can also be specified relative to the current
22173 generation with the form @code{+N} or @code{-N}, where @code{+3} means ``3
22174 generations ahead of the current generation,'' and @code{-1} means ``1
22175 generation prior to the current generation.'' When specifying a negative
22176 value such as @code{-1}, you must precede it with @code{--} to prevent it
22177 from being parsed as an option. For example:
22180 guix system switch-generation -- -1
22183 Currently, the effect of invoking this action is @emph{only} to switch the
22184 system profile to an existing generation and rearrange the bootloader menu
22185 entries. To actually start using the target system generation, you must
22186 reboot after running this action. In the future, it will be updated to do
22187 the same things as @command{reconfigure}, like activating and deactivating
22190 This action will fail if the specified generation does not exist.
22194 Switch to the preceding system generation. The next time the system boots,
22195 it will use the preceding system generation. This is the inverse of
22196 @command{reconfigure}, and it is exactly the same as invoking
22197 @command{switch-generation} with an argument of @code{-1}.
22199 Currently, as with @command{switch-generation}, you must reboot after
22200 running this action to actually start using the preceding system generation.
22203 Build the derivation of the operating system, which includes all the
22204 configuration files and programs needed to boot and run the system. This
22205 action does not actually install anything.
22208 Populate the given directory with all the files necessary to run the
22209 operating system specified in @var{file}. This is useful for first-time
22210 installations of GuixSD. For instance:
22213 guix system init my-os-config.scm /mnt
22216 copies to @file{/mnt} all the store items required by the configuration
22217 specified in @file{my-os-config.scm}. This includes configuration files,
22218 packages, and so on. It also creates other essential files needed for the
22219 system to operate correctly---e.g., the @file{/etc}, @file{/var}, and
22220 @file{/run} directories, and the @file{/bin/sh} file.
22222 This command also installs bootloader on the target specified in
22223 @file{my-os-config}, unless the @option{--no-bootloader} option was passed.
22226 @cindex virtual machine
22228 @anchor{guix system vm}
22229 Build a virtual machine that contains the operating system declared in
22230 @var{file}, and return a script to run that virtual machine (VM). Arguments
22231 given to the script are passed to QEMU as in the example below, which
22232 enables networking and requests 1@tie{}GiB of RAM for the emulated machine:
22235 $ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user
22238 The VM shares its store with the host system.
22240 Additional file systems can be shared between the host and the VM using the
22241 @code{--share} and @code{--expose} command-line options: the former
22242 specifies a directory to be shared with write access, while the latter
22243 provides read-only access to the shared directory.
22245 The example below creates a VM in which the user's home directory is
22246 accessible read-only, and where the @file{/exchange} directory is a
22247 read-write mapping of @file{$HOME/tmp} on the host:
22250 guix system vm my-config.scm \
22251 --expose=$HOME --share=$HOME/tmp=/exchange
22254 On GNU/Linux, the default is to boot directly to the kernel; this has the
22255 advantage of requiring only a very tiny root disk image since the store of
22256 the host can then be mounted.
22258 The @code{--full-boot} option forces a complete boot sequence, starting with
22259 the bootloader. This requires more disk space since a root image containing
22260 at least the kernel, initrd, and bootloader data files must be created. The
22261 @code{--image-size} option can be used to specify the size of the image.
22263 @cindex System images, creation in various formats
22264 @cindex Creating system images in various formats
22267 @itemx docker-image
22268 Return a virtual machine, disk image, or Docker image of the operating
22269 system declared in @var{file} that stands alone. By default, @command{guix
22270 system} estimates the size of the image needed to store the system, but you
22271 can use the @option{--image-size} option to specify a value. Docker images
22272 are built to contain exactly what they need, so the @option{--image-size}
22273 option is ignored in the case of @code{docker-image}.
22275 You can specify the root file system type by using the
22276 @option{--file-system-type} option. It defaults to @code{ext4}.
22278 When using @code{vm-image}, the returned image is in qcow2 format, which the
22279 QEMU emulator can efficiently use. @xref{GuixSD in einer VM starten}, for more
22280 information on how to run the image in a virtual machine.
22282 When using @code{disk-image}, a raw disk image is produced; it can be copied
22283 as is to a USB stick, for instance. Assuming @code{/dev/sdc} is the device
22284 corresponding to a USB stick, one can copy the image to it using the
22288 # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc
22291 When using @code{docker-image}, a Docker image is produced. Guix builds the
22292 image from scratch, not from a pre-existing Docker base image. As a result,
22293 it contains @emph{exactly} what you define in the operating system
22294 configuration file. You can then load the image and launch a Docker
22295 container using commands like the following:
22298 image_id="$(docker load < guixsd-docker-image.tar.gz)"
22299 docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\
22300 --entrypoint /var/guix/profiles/system/profile/bin/guile \\
22301 $image_id /var/guix/profiles/system/boot
22304 This command starts a new Docker container from the specified image. It
22305 will boot the GuixSD system in the usual manner, which means it will start
22306 any services you have defined in the operating system configuration.
22307 Depending on what you run in the Docker container, it may be necessary to
22308 give the container additional permissions. For example, if you intend to
22309 build software using Guix inside of the Docker container, you may need to
22310 pass the @option{--privileged} option to @code{docker run}.
22313 Return a script to run the operating system declared in @var{file} within a
22314 container. Containers are a set of lightweight isolation mechanisms
22315 provided by the kernel Linux-libre. Containers are substantially less
22316 resource-demanding than full virtual machines since the kernel, shared
22317 objects, and other resources can be shared with the host system; this also
22318 means they provide thinner isolation.
22320 Currently, the script must be run as root in order to support more than a
22321 single user and group. The container shares its store with the host system.
22323 As with the @code{vm} action (@pxref{guix system vm}), additional file
22324 systems to be shared between the host and container can be specified using
22325 the @option{--share} and @option{--expose} options:
22328 guix system container my-config.scm \
22329 --expose=$HOME --share=$HOME/tmp=/exchange
22332 @quotation Anmerkung
22333 This option requires Linux-libre 3.19 or newer.
22338 @var{options} can contain any of the common build options (@pxref{Gemeinsame Erstellungsoptionen}). In addition, @var{options} can contain one of the
22342 @item --expression=@var{expr}
22343 @itemx -e @var{expr}
22344 Consider the operating-system @var{expr} evaluates to. This is an
22345 alternative to specifying a file which evaluates to an operating system.
22346 This is used to generate the GuixSD installer @pxref{Ein Abbild zur Installation erstellen}).
22348 @item --system=@var{System}
22349 @itemx -s @var{system}
22350 Attempt to build for @var{system} instead of the host system type. This
22351 works as per @command{guix build} (@pxref{Aufruf von guix build}).
22355 Return the derivation file name of the given operating system without
22358 @item --file-system-type=@var{type}
22359 @itemx -t @var{type}
22360 For the @code{disk-image} action, create a file system of the given
22361 @var{type} on the image.
22363 When this option is omitted, @command{guix system} uses @code{ext4}.
22365 @cindex ISO-9660 format
22366 @cindex CD image format
22367 @cindex DVD image format
22368 @code{--file-system-type=iso9660} produces an ISO-9660 image, suitable for
22369 burning on CDs and DVDs.
22371 @item --image-size=@var{size}
22372 For the @code{vm-image} and @code{disk-image} actions, create an image of
22373 the given @var{size}. @var{size} may be a number of bytes, or it may
22374 include a unit as a suffix (@pxref{Block size, size specifications,,
22375 coreutils, GNU Coreutils}).
22377 When this option is omitted, @command{guix system} computes an estimate of
22378 the image size as a function of the size of the system declared in
22381 @item --root=@var{file}
22382 @itemx -r @var{file}
22383 Make @var{file} a symlink to the result, and register it as a garbage
22386 @item --skip-checks
22387 Skip pre-installation safety checks.
22389 By default, @command{guix system init} and @command{guix system reconfigure}
22390 perform safety checks: they make sure the file systems that appear in the
22391 @code{operating-system} declaration actually exist (@pxref{Dateisysteme}),
22392 and that any Linux kernel modules that may be needed at boot time are listed
22393 in @code{initrd-modules} (@pxref{Initiale RAM-Disk}). Passing this option
22394 skips these tests altogether.
22396 @item --on-error=@var{strategy}
22397 Apply @var{strategy} when an error occurs when reading @var{file}.
22398 @var{strategy} may be one of the following:
22401 @item nothing-special
22402 Report the error concisely and exit. This is the default strategy.
22405 Likewise, but also display a backtrace.
22408 Report the error and enter Guile's debugger. From there, you can run
22409 commands such as @code{,bt} to get a backtrace, @code{,locals} to display
22410 local variable values, and more generally inspect the state of the program.
22411 @xref{Debug Commands,,, guile, GNU Guile Reference Manual}, for a list of
22412 available debugging commands.
22416 @quotation Anmerkung
22417 All the actions above, except @code{build} and @code{init}, can use KVM
22418 support in the Linux-libre kernel. Specifically, if the machine has
22419 hardware virtualization support, the corresponding KVM kernel module should
22420 be loaded, and the @file{/dev/kvm} device node must exist and be readable
22421 and writable by the user and by the build users of the daemon (@pxref{Einrichten der Erstellungsumgebung}).
22424 Once you have built, configured, re-configured, and re-re-configured your
22425 GuixSD installation, you may find it useful to list the operating system
22426 generations available on disk---and that you can choose from the bootloader
22431 @item list-generations
22432 List a summary of each generation of the operating system available on disk,
22433 in a human-readable way. This is similar to the @option{--list-generations}
22434 option of @command{guix package} (@pxref{Aufruf von guix package}).
22436 Optionally, one can specify a pattern, with the same syntax that is used in
22437 @command{guix package --list-generations}, to restrict the list of
22438 generations displayed. For instance, the following command displays
22439 generations that are up to 10 days old:
22442 $ guix system list-generations 10d
22447 The @command{guix system} command has even more to offer! The following
22448 sub-commands allow you to visualize how your system services relate to each
22451 @anchor{system-extension-graph}
22454 @item extension-graph
22455 Emit in Dot/Graphviz format to standard output the @dfn{service extension
22456 graph} of the operating system defined in @var{file} (@pxref{Dienstkompositionen}, for more information on service extensions.)
22461 $ guix system extension-graph @var{file} | dot -Tpdf > services.pdf
22464 produces a PDF file showing the extension relations among services.
22466 @anchor{system-shepherd-graph}
22467 @item shepherd-graph
22468 Emit in Dot/Graphviz format to standard output the @dfn{dependency graph} of
22469 shepherd services of the operating system defined in @var{file}.
22470 @xref{Shepherd-Dienste}, for more information and for an example graph.
22474 @node GuixSD in einer VM starten
22475 @subsection Running GuixSD in a Virtual Machine
22477 @cindex virtual machine
22478 To run GuixSD in a virtual machine (VM), one can either use the pre-built
22479 GuixSD VM image distributed at
22480 @indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-vm-image-@value{VERSION}.@var{system}.xz}
22481 , or build their own virtual machine image using @command{guix system
22482 vm-image} (@pxref{Aufruf von guix system}). The returned image is in qcow2
22483 format, which the @uref{http://qemu.org/, QEMU emulator} can efficiently
22487 If you built your own image, you must copy it out of the store (@pxref{Der Store}) and give yourself permission to write to the copy before you can use
22488 it. When invoking QEMU, you must choose a system emulator that is suitable
22489 for your hardware platform. Here is a minimal QEMU invocation that will
22490 boot the result of @command{guix system vm-image} on x86_64 hardware:
22493 $ qemu-system-x86_64 \
22494 -net user -net nic,model=virtio \
22495 -enable-kvm -m 256 /tmp/qemu-image
22498 Here is what each of these options means:
22501 @item qemu-system-x86_64
22502 This specifies the hardware platform to emulate. This should match the
22506 Enable the unprivileged user-mode network stack. The guest OS can access
22507 the host but not vice versa. This is the simplest way to get the guest OS
22510 @item -net nic,model=virtio
22511 You must create a network interface of a given model. If you do not create
22512 a NIC, the boot will fail. Assuming your hardware platform is x86_64, you
22513 can get a list of available NIC models by running
22514 @command{qemu-system-x86_64 -net nic,model=help}.
22517 If your system has hardware virtualization extensions, enabling the virtual
22518 machine support (KVM) of the Linux kernel will make things run faster.
22521 RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB,
22522 which may be insufficient for some operations.
22524 @item /tmp/qemu-image
22525 The file name of the qcow2 image.
22528 The default @command{run-vm.sh} script that is returned by an invocation of
22529 @command{guix system vm} does not add a @command{-net user} flag by
22530 default. To get network access from within the vm add the
22531 @code{(dhcp-client-service)} to your system definition and start the VM
22532 using @command{`guix system vm config.scm` -net user}. An important caveat
22533 of using @command{-net user} for networking is that @command{ping} will not
22534 work, because it uses the ICMP protocol. You'll have to use a different
22535 command to check for network connectivity, for example @command{guix
22538 @subsubsection Connecting Through SSH
22542 To enable SSH inside a VM you need to add a SSH server like
22543 @code{(dropbear-service)} or @code{(lsh-service)} to your VM. The
22544 @code{(lsh-service}) doesn't currently boot unsupervised. It requires you
22545 to type some characters to initialize the randomness generator. In addition
22546 you need to forward the SSH port, 22 by default, to the host. You can do
22550 `guix system vm config.scm` -net user,hostfwd=tcp::10022-:22
22553 To connect to the VM you can run
22556 ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022
22559 The @command{-p} tells @command{ssh} the port you want to connect to.
22560 @command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from
22561 complaining every time you modify your @command{config.scm} file and the
22562 @command{-o StrictHostKeyChecking=no} prevents you from having to allow a
22563 connection to an unknown host every time you connect.
22565 @subsubsection Using @command{virt-viewer} with Spice
22567 As an alternative to the default @command{qemu} graphical client you can use
22568 the @command{remote-viewer} from the @command{virt-viewer} package. To
22569 connect pass the @command{-spice port=5930,disable-ticketing} flag to
22570 @command{qemu}. See previous section for further information on how to do
22573 Spice also allows you to do some nice stuff like share your clipboard with
22574 your VM. To enable that you'll also have to pass the following flags to
22578 -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
22579 -chardev spicevmc,name=vdagent,id=vdagent
22580 -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,
22581 name=com.redhat.spice.0
22584 You'll also need to add the @pxref{Verschiedene Dienste, Spice service}.
22586 @node Dienste definieren
22587 @subsection Dienste definieren
22589 The previous sections show the available services and how one can combine
22590 them in an @code{operating-system} declaration. But how do we define them
22591 in the first place? And what is a service anyway?
22594 * Dienstkompositionen:: Wie Dienste zusammengestellt werden.
22595 * Diensttypen und Dienste:: Typen und Dienste.
22596 * Service-Referenz:: Referenz zur Programmierschnittstelle.
22597 * Shepherd-Dienste:: Eine spezielle Art von Dienst.
22600 @node Dienstkompositionen
22601 @subsubsection Dienstkompositionen
22605 Here we define a @dfn{service} as, broadly, something that extends the
22606 functionality of the operating system. Often a service is a process---a
22607 @dfn{daemon}---started when the system boots: a secure shell server, a Web
22608 server, the Guix build daemon, etc. Sometimes a service is a daemon whose
22609 execution can be triggered by another daemon---e.g., an FTP server started
22610 by @command{inetd} or a D-Bus service activated by @command{dbus-daemon}.
22611 Occasionally, a service does not map to a daemon. For instance, the
22612 ``account'' service collects user accounts and makes sure they exist when
22613 the system runs; the ``udev'' service collects device management rules and
22614 makes them available to the eudev daemon; the @file{/etc} service populates
22615 the @file{/etc} directory of the system.
22617 @cindex service extensions
22618 GuixSD services are connected by @dfn{extensions}. For instance, the secure
22619 shell service @emph{extends} the Shepherd---the GuixSD initialization
22620 system, running as PID@tie{}1---by giving it the command lines to start and
22621 stop the secure shell daemon (@pxref{Netzwerkdienste,
22622 @code{lsh-service}}); the UPower service extends the D-Bus service by
22623 passing it its @file{.service} specification, and extends the udev service
22624 by passing it device management rules (@pxref{Desktop-Dienste,
22625 @code{upower-service}}); the Guix daemon service extends the Shepherd by
22626 passing it the command lines to start and stop the daemon, and extends the
22627 account service by passing it a list of required build user accounts
22628 (@pxref{Basisdienste}).
22630 All in all, services and their ``extends'' relations form a directed acyclic
22631 graph (DAG). If we represent services as boxes and extensions as arrows, a
22632 typical system might provide something like this:
22634 @image{images/service-graph,,5in,Typical service extension graph.}
22636 @cindex system service
22637 At the bottom, we see the @dfn{system service}, which produces the directory
22638 containing everything to run and boot the system, as returned by the
22639 @command{guix system build} command. @xref{Service-Referenz}, to learn
22640 about the other service types shown here. @xref{system-extension-graph, the
22641 @command{guix system extension-graph} command}, for information on how to
22642 generate this representation for a particular operating system definition.
22644 @cindex service types
22645 Technically, developers can define @dfn{service types} to express these
22646 relations. There can be any number of services of a given type on the
22647 system---for instance, a system running two instances of the GNU secure
22648 shell server (lsh) has two instances of @var{lsh-service-type}, with
22649 different parameters.
22651 The following section describes the programming interface for service types
22654 @node Diensttypen und Dienste
22655 @subsubsection Diensttypen und Dienste
22657 A @dfn{service type} is a node in the DAG described above. Let us start
22658 with a simple example, the service type for the Guix build daemon
22659 (@pxref{Aufruf des guix-daemon}):
22662 (define guix-service-type
22666 (list (service-extension shepherd-root-service-type guix-shepherd-service)
22667 (service-extension account-service-type guix-accounts)
22668 (service-extension activation-service-type guix-activation)))
22669 (default-value (guix-configuration))))
22673 It defines three things:
22677 A name, whose sole purpose is to make inspection and debugging easier.
22680 A list of @dfn{service extensions}, where each extension designates the
22681 target service type and a procedure that, given the parameters of the
22682 service, returns a list of objects to extend the service of that type.
22684 Every service type has at least one service extension. The only exception
22685 is the @dfn{boot service type}, which is the ultimate service.
22688 Optionally, a default value for instances of this type.
22691 In this example, @var{guix-service-type} extends three services:
22694 @item shepherd-root-service-type
22695 The @var{guix-shepherd-service} procedure defines how the Shepherd service
22696 is extended. Namely, it returns a @code{<shepherd-service>} object that
22697 defines how @command{guix-daemon} is started and stopped (@pxref{Shepherd-Dienste}).
22699 @item account-service-type
22700 This extension for this service is computed by @var{guix-accounts}, which
22701 returns a list of @code{user-group} and @code{user-account} objects
22702 representing the build user accounts (@pxref{Aufruf des guix-daemon}).
22704 @item activation-service-type
22705 Here @var{guix-activation} is a procedure that returns a gexp, which is a
22706 code snippet to run at ``activation time''---e.g., when the service is
22710 A service of this type is instantiated like this:
22713 (service guix-service-type
22714 (guix-configuration
22716 (use-substitutes? #f)))
22719 The second argument to the @code{service} form is a value representing the
22720 parameters of this specific service instance.
22721 @xref{guix-configuration-type, @code{guix-configuration}}, for information
22722 about the @code{guix-configuration} data type. When the value is omitted,
22723 the default value specified by @code{guix-service-type} is used:
22726 (service guix-service-type)
22729 @var{guix-service-type} is quite simple because it extends other services
22730 but is not extensible itself.
22732 @c @subsubsubsection Extensible Service Types
22734 The service type for an @emph{extensible} service looks like this:
22737 (define udev-service-type
22738 (service-type (name 'udev)
22740 (list (service-extension shepherd-root-service-type
22741 udev-shepherd-service)))
22743 (compose concatenate) ;concatenate the list of rules
22744 (extend (lambda (config rules)
22746 (($ <udev-configuration> udev initial-rules)
22747 (udev-configuration
22748 (udev udev) ;the udev package to use
22749 (rules (append initial-rules rules)))))))))
22752 This is the service type for the
22753 @uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device management
22754 daemon}. Compared to the previous example, in addition to an extension of
22755 @var{shepherd-root-service-type}, we see two new fields:
22759 This is the procedure to @dfn{compose} the list of extensions to services of
22762 Services can extend the udev service by passing it lists of rules; we
22763 compose those extensions simply by concatenating them.
22766 This procedure defines how the value of the service is @dfn{extended} with
22767 the composition of the extensions.
22769 Udev extensions are composed into a list of rules, but the udev service
22770 value is itself a @code{<udev-configuration>} record. So here, we extend
22771 that record by appending the list of rules it contains to the list of
22775 This is a string giving an overview of the service type. The string can
22776 contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}). The
22777 @command{guix system search} command searches these strings and displays
22778 them (@pxref{Aufruf von guix system}).
22781 There can be only one instance of an extensible service type such as
22782 @var{udev-service-type}. If there were more, the @code{service-extension}
22783 specifications would be ambiguous.
22785 Still here? The next section provides a reference of the programming
22786 interface for services.
22788 @node Service-Referenz
22789 @subsubsection Service-Referenz
22791 We have seen an overview of service types (@pxref{Diensttypen und Dienste}). This section provides a reference on how to manipulate services
22792 and service types. This interface is provided by the @code{(gnu services)}
22795 @deffn {Scheme Procedure} service @var{type} [@var{value}]
22796 Return a new service of @var{type}, a @code{<service-type>} object (see
22797 below.) @var{value} can be any object; it represents the parameters of this
22798 particular service instance.
22800 When @var{value} is omitted, the default value specified by @var{type} is
22801 used; if @var{type} does not specify a default value, an error is raised.
22803 For instance, this:
22806 (service openssh-service-type)
22810 is equivalent to this:
22813 (service openssh-service-type
22814 (openssh-configuration))
22817 In both cases the result is an instance of @code{openssh-service-type} with
22818 the default configuration.
22821 @deffn {Scheme Procedure} service? @var{obj}
22822 Return true if @var{obj} is a service.
22825 @deffn {Scheme Procedure} service-kind @var{service}
22826 Return the type of @var{service}---i.e., a @code{<service-type>} object.
22829 @deffn {Scheme Procedure} service-value @var{service}
22830 Return the value associated with @var{service}. It represents its
22834 Here is an example of how a service is created and manipulated:
22838 (service nginx-service-type
22839 (nginx-configuration
22841 (log-directory log-directory)
22842 (run-directory run-directory)
22843 (file config-file))))
22848 (eq? (service-kind s) nginx-service-type)
22852 The @code{modify-services} form provides a handy way to change the
22853 parameters of some of the services of a list such as @var{%base-services}
22854 (@pxref{Basisdienste, @code{%base-services}}). It evaluates to a list of
22855 services. Of course, you could always use standard list combinators such as
22856 @code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, guile,
22857 GNU Guile Reference Manual}); @code{modify-services} simply provides a more
22858 concise form for this common pattern.
22860 @deffn {Scheme Syntax} modify-services @var{services} @
22861 (@var{type} @var{variable} => @var{body}) @dots{}
22863 Modify the services listed in @var{services} according to the given
22864 clauses. Each clause has the form:
22867 (@var{type} @var{variable} => @var{body})
22870 where @var{type} is a service type---e.g., @code{guix-service-type}---and
22871 @var{variable} is an identifier that is bound within the @var{body} to the
22872 service parameters---e.g., a @code{guix-configuration} instance---of the
22873 original service of that @var{type}.
22875 The @var{body} should evaluate to the new service parameters, which will be
22876 used to configure the new service. This new service will replace the
22877 original in the resulting list. Because a service's service parameters are
22878 created using @code{define-record-type*}, you can write a succinct
22879 @var{body} that evaluates to the new service parameters by using the
22880 @code{inherit} feature that @code{define-record-type*} provides.
22882 @xref{Das Konfigurationssystem nutzen}, for example usage.
22886 Next comes the programming interface for service types. This is something
22887 you want to know when writing new service definitions, but not necessarily
22888 when simply looking for ways to customize your @code{operating-system}
22891 @deftp {Data Type} service-type
22892 @cindex service type
22893 This is the representation of a @dfn{service type} (@pxref{Diensttypen und Dienste}).
22897 This is a symbol, used only to simplify inspection and debugging.
22899 @item @code{extensions}
22900 A non-empty list of @code{<service-extension>} objects (see below).
22902 @item @code{compose} (default: @code{#f})
22903 If this is @code{#f}, then the service type denotes services that cannot be
22904 extended---i.e., services that do not receive ``values'' from other
22907 Otherwise, it must be a one-argument procedure. The procedure is called by
22908 @code{fold-services} and is passed a list of values collected from
22909 extensions. It may return any single value.
22911 @item @code{extend} (default: @code{#f})
22912 If this is @code{#f}, services of this type cannot be extended.
22914 Otherwise, it must be a two-argument procedure: @code{fold-services} calls
22915 it, passing it the initial value of the service as the first argument and
22916 the result of applying @code{compose} to the extension values as the second
22917 argument. It must return a value that is a valid parameter value for the
22921 @xref{Diensttypen und Dienste}, for examples.
22924 @deffn {Scheme Procedure} service-extension @var{target-type} @
22925 @var{compute} Return a new extension for services of type
22926 @var{target-type}. @var{compute} must be a one-argument procedure:
22927 @code{fold-services} calls it, passing it the value associated with the
22928 service that provides the extension; it must return a valid value for the
22932 @deffn {Scheme Procedure} service-extension? @var{obj}
22933 Return true if @var{obj} is a service extension.
22936 Occasionally, you might want to simply extend an existing service. This
22937 involves creating a new service type and specifying the extension of
22938 interest, which can be verbose; the @code{simple-service} procedure provides
22939 a shorthand for this.
22941 @deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value}
22942 Return a service that extends @var{target} with @var{value}. This works by
22943 creating a singleton service type @var{name}, of which the returned service
22946 For example, this extends mcron (@pxref{Geplante Auftragsausführung}) with an
22950 (simple-service 'my-mcron-job mcron-service-type
22951 #~(job '(next-hour (3)) "guix gc -F 2G"))
22955 At the core of the service abstraction lies the @code{fold-services}
22956 procedure, which is responsible for ``compiling'' a list of services down to
22957 a single directory that contains everything needed to boot and run the
22958 system---the directory shown by the @command{guix system build} command
22959 (@pxref{Aufruf von guix system}). In essence, it propagates service
22960 extensions down the service graph, updating each node parameters on the way,
22961 until it reaches the root node.
22963 @deffn {Scheme Procedure} fold-services @var{services} @
22964 [#:target-type @var{system-service-type}] Fold @var{services} by propagating
22965 their extensions down to the root of type @var{target-type}; return the root
22966 service adjusted accordingly.
22969 Lastly, the @code{(gnu services)} module also defines several essential
22970 service types, some of which are listed below.
22972 @defvr {Scheme Variable} system-service-type
22973 This is the root of the service graph. It produces the system directory as
22974 returned by the @command{guix system build} command.
22977 @defvr {Scheme Variable} boot-service-type
22978 The type of the ``boot service'', which produces the @dfn{boot script}. The
22979 boot script is what the initial RAM disk runs when booting.
22982 @defvr {Scheme Variable} etc-service-type
22983 The type of the @file{/etc} service. This service is used to create files
22984 under @file{/etc} and can be extended by passing it name/file tuples such
22988 (list `("issue" ,(plain-file "issue" "Welcome!\n")))
22991 In this example, the effect would be to add an @file{/etc/issue} file
22992 pointing to the given file.
22995 @defvr {Scheme Variable} setuid-program-service-type
22996 Type for the ``setuid-program service''. This service collects lists of
22997 executable file names, passed as gexps, and adds them to the set of
22998 setuid-root programs on the system (@pxref{Setuid-Programme}).
23001 @defvr {Scheme Variable} profile-service-type
23002 Type of the service that populates the @dfn{system profile}---i.e., the
23003 programs under @file{/run/current-system/profile}. Other services can
23004 extend it by passing it lists of packages to add to the system profile.
23008 @node Shepherd-Dienste
23009 @subsubsection Shepherd-Dienste
23011 @cindex shepherd services
23013 @cindex init system
23014 The @code{(gnu services shepherd)} module provides a way to define services
23015 managed by the GNU@tie{}Shepherd, which is the GuixSD initialization
23016 system---the first process that is started when the system boots, also known
23017 as PID@tie{}1 (@pxref{Einführung,,, shepherd, The GNU Shepherd Manual}).
23019 Services in the Shepherd can depend on each other. For instance, the SSH
23020 daemon may need to be started after the syslog daemon has been started,
23021 which in turn can only happen once all the file systems have been mounted.
23022 The simple operating system defined earlier (@pxref{Das Konfigurationssystem nutzen}) results in a service graph like this:
23024 @image{images/shepherd-graph,,5in,Typical shepherd service graph.}
23026 You can actually generate such a graph for any operating system definition
23027 using the @command{guix system shepherd-graph} command
23028 (@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}).
23030 The @var{%shepherd-root-service} is a service object representing
23031 PID@tie{}1, of type @var{shepherd-root-service-type}; it can be extended by
23032 passing it lists of @code{<shepherd-service>} objects.
23034 @deftp {Data Type} shepherd-service
23035 The data type representing a service managed by the Shepherd.
23038 @item @code{provision}
23039 This is a list of symbols denoting what the service provides.
23041 These are the names that may be passed to @command{herd start},
23042 @command{herd status}, and similar commands (@pxref{Invoking herd,,,
23043 shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the
23044 @code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details.
23046 @item @code{requirements} (default: @code{'()})
23047 List of symbols denoting the Shepherd services this one depends on.
23049 @item @code{respawn?} (default: @code{#t})
23050 Whether to restart the service when it stops, for instance when the
23051 underlying process dies.
23054 @itemx @code{stop} (default: @code{#~(const #f)})
23055 The @code{start} and @code{stop} fields refer to the Shepherd's facilities
23056 to start and stop processes (@pxref{Service De- and Constructors,,,
23057 shepherd, The GNU Shepherd Manual}). They are given as G-expressions that
23058 get expanded in the Shepherd configuration file (@pxref{G-Ausdrücke}).
23060 @item @code{actions} (default: @code{'()})
23061 @cindex actions, of Shepherd services
23062 This is a list of @code{shepherd-action} objects (see below) defining
23063 @dfn{actions} supported by the service, in addition to the standard
23064 @code{start} and @code{stop} actions. Actions listed here become available
23065 as @command{herd} sub-commands:
23068 herd @var{action} @var{service} [@var{arguments}@dots{}]
23071 @item @code{Dokumentation}
23072 A documentation string, as shown when running:
23075 herd doc @var{service-name}
23078 where @var{service-name} is one of the symbols in @var{provision}
23079 (@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}).
23081 @item @code{modules} (default: @var{%default-modules})
23082 This is the list of modules that must be in scope when @code{start} and
23083 @code{stop} are evaluated.
23088 @deftp {Data Type} shepherd-action
23089 This is the data type that defines additional actions implemented by a
23090 Shepherd service (see above).
23094 Symbol naming the action.
23096 @item Dokumentation
23097 This is a documentation string for the action. It can be viewed by running:
23100 herd doc @var{service} action @var{action}
23104 This should be a gexp that evaluates to a procedure of at least one
23105 argument, which is the ``running value'' of the service (@pxref{Slots of
23106 services,,, shepherd, The GNU Shepherd Manual}).
23109 The following example defines an action called @code{say-hello} that kindly
23115 (documentation "Say hi!")
23116 (procedure #~(lambda (running . args)
23117 (format #t "Hello, friend! arguments: ~s\n"
23122 Assuming this action is added to the @code{example} service, then you can
23126 # herd say-hello example
23127 Hello, friend! arguments: ()
23128 # herd say-hello example a b c
23129 Hello, friend! arguments: ("a" "b" "c")
23132 This, as you can see, is a fairly sophisticated way to say hello.
23133 @xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more
23137 @defvr {Scheme Variable} shepherd-root-service-type
23138 The service type for the Shepherd ``root service''---i.e., PID@tie{}1.
23140 This is the service type that extensions target when they want to create
23141 shepherd services (@pxref{Diensttypen und Dienste}, for an example).
23142 Each extension must pass a list of @code{<shepherd-service>}.
23145 @defvr {Scheme Variable} %shepherd-root-service
23146 This service represents PID@tie{}1.
23150 @node Dokumentation
23151 @section Dokumentation
23153 @cindex documentation, searching for
23154 @cindex searching for documentation
23155 @cindex Info, documentation format
23157 @cindex manual pages
23158 In most cases packages installed with Guix come with documentation. There
23159 are two main documentation formats: ``Info'', a browseable hypertext format
23160 used for GNU software, and ``manual pages'' (or ``man pages''), the linear
23161 documentation format traditionally found on Unix. Info manuals are accessed
23162 with the @command{info} command or with Emacs, and man pages are accessed
23163 using @command{man}.
23165 You can look for documentation of software installed on your system by
23166 keyword. For example, the following command searches for information about
23167 ``TLS'' in Info manuals:
23171 "(emacs)Network Security" -- STARTTLS
23172 "(emacs)Network Security" -- TLS
23173 "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
23174 "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
23179 The command below searches for the same keyword in man pages:
23183 SSL (7) - OpenSSL SSL/TLS library
23184 certtool (1) - GnuTLS certificate tool
23188 These searches are purely local to your computer so you have the guarantee
23189 that documentation you find corresponds to what you have actually installed,
23190 you can access it off-line, and your privacy is respected.
23192 Once you have these results, you can view the relevant documentation by
23196 $ info "(gnutls)Core TLS API"
23206 Info manuals contain sections and indices as well as hyperlinks like those
23207 found in Web pages. The @command{info} reader (@pxref{Top, Info reader,,
23208 info-stnd, Stand-alone GNU Info}) and its Emacs counterpart (@pxref{Misc
23209 Help,,, emacs, The GNU Emacs Manual}) provide intuitive key bindings to
23210 navigate manuals. @xref{Getting Started,,, info, Info: An Introduction},
23211 for an introduction to Info navigation.
23213 @node Dateien zur Fehlersuche installieren
23214 @section Dateien zur Fehlersuche installieren
23216 @cindex debugging files
23217 Program binaries, as produced by the GCC compilers for instance, are
23218 typically written in the ELF format, with a section containing
23219 @dfn{debugging information}. Debugging information is what allows the
23220 debugger, GDB, to map binary code to source code; it is required to debug a
23221 compiled program in good conditions.
23223 The problem with debugging information is that is takes up a fair amount of
23224 disk space. For example, debugging information for the GNU C Library weighs
23225 in at more than 60 MiB. Thus, as a user, keeping all the debugging info of
23226 all the installed programs is usually not an option. Yet, space savings
23227 should not come at the cost of an impediment to debugging---especially in
23228 the GNU system, which should make it easier for users to exert their
23229 computing freedom (@pxref{GNU-Distribution}).
23231 Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a mechanism
23232 that allows users to get the best of both worlds: debugging information can
23233 be stripped from the binaries and stored in separate files. GDB is then
23234 able to load debugging information from those files, when they are available
23235 (@pxref{Separate Debug Files,,, gdb, Debugging with GDB}).
23237 The GNU distribution takes advantage of this by storing debugging
23238 information in the @code{lib/debug} sub-directory of a separate package
23239 output unimaginatively called @code{debug} (@pxref{Pakete mit mehreren Ausgaben.}). Users can choose to install the @code{debug} output of a package
23240 when they need it. For instance, the following command installs the
23241 debugging information for the GNU C Library and for GNU Guile:
23244 guix package -i glibc:debug guile:debug
23247 GDB must then be told to look for debug files in the user's profile, by
23248 setting the @code{debug-file-directory} variable (consider setting it from
23249 the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with GDB}):
23252 (gdb) set debug-file-directory ~/.guix-profile/lib/debug
23255 From there on, GDB will pick up debugging information from the @code{.debug}
23256 files under @file{~/.guix-profile/lib/debug}.
23258 In addition, you will most likely want GDB to be able to show the source
23259 code being debugged. To do that, you will have to unpack the source code of
23260 the package of interest (obtained with @code{guix build --source},
23261 @pxref{Aufruf von guix build}), and to point GDB to that source directory
23262 using the @code{directory} command (@pxref{Source Path, @code{directory},,
23263 gdb, Debugging with GDB}).
23265 @c XXX: keep me up-to-date
23266 The @code{debug} output mechanism in Guix is implemented by the
23267 @code{gnu-build-system} (@pxref{Erstellungssysteme}). Currently, it is
23268 opt-in---debugging information is available only for the packages with
23269 definitions explicitly declaring a @code{debug} output. This may be changed
23270 to opt-out in the future if our build farm servers can handle the load. To
23271 check whether a package has a @code{debug} output, use @command{guix package
23272 --list-available} (@pxref{Aufruf von guix package}).
23275 @node Sicherheitsaktualisierungen
23276 @section Sicherheitsaktualisierungen
23278 @cindex security updates
23279 @cindex security vulnerabilities
23280 Occasionally, important security vulnerabilities are discovered in software
23281 packages and must be patched. Guix developers try hard to keep track of
23282 known vulnerabilities and to apply fixes as soon as possible in the
23283 @code{master} branch of Guix (we do not yet provide a ``stable'' branch
23284 containing only security updates.) The @command{guix lint} tool helps
23285 developers find out about vulnerable versions of software packages in the
23290 gnu/packages/base.scm:652:2: glibc@@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
23291 gnu/packages/gcc.scm:334:2: gcc@@4.9.3: probably vulnerable to CVE-2015-5276
23292 gnu/packages/image.scm:312:2: openjpeg@@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
23296 @xref{Aufruf von guix lint}, for more information.
23298 @quotation Anmerkung
23299 As of version @value{VERSION}, the feature described below is considered
23303 Guix follows a functional package management discipline
23304 (@pxref{Einführung}), which implies that, when a package is changed,
23305 @emph{every package that depends on it} must be rebuilt. This can
23306 significantly slow down the deployment of fixes in core packages such as
23307 libc or Bash, since basically the whole distribution would need to be
23308 rebuilt. Using pre-built binaries helps (@pxref{Substitute}), but
23309 deployment may still take more time than desired.
23312 To address this, Guix implements @dfn{grafts}, a mechanism that allows for
23313 fast deployment of critical updates without the costs associated with a
23314 whole-distribution rebuild. The idea is to rebuild only the package that
23315 needs to be patched, and then to ``graft'' it onto packages explicitly
23316 installed by the user and that were previously referring to the original
23317 package. The cost of grafting is typically very low, and order of
23318 magnitudes lower than a full rebuild of the dependency chain.
23320 @cindex replacements of packages, for grafts
23321 For instance, suppose a security update needs to be applied to Bash. Guix
23322 developers will provide a package definition for the ``fixed'' Bash, say
23323 @var{bash-fixed}, in the usual way (@pxref{Pakete definieren}). Then, the
23324 original package definition is augmented with a @code{replacement} field
23325 pointing to the package containing the bug fix:
23332 (replacement bash-fixed)))
23335 From there on, any package depending directly or indirectly on Bash---as
23336 reported by @command{guix gc --requisites} (@pxref{Aufruf von guix gc})---that
23337 is installed is automatically ``rewritten'' to refer to @var{bash-fixed}
23338 instead of @var{bash}. This grafting process takes time proportional to the
23339 size of the package, usually less than a minute for an ``average'' package
23340 on a recent machine. Grafting is recursive: when an indirect dependency
23341 requires grafting, then grafting ``propagates'' up to the package that the
23342 user is installing.
23344 Currently, the length of the name and version of the graft and that of the
23345 package it replaces (@var{bash-fixed} and @var{bash} in the example above)
23346 must be equal. This restriction mostly comes from the fact that grafting
23347 works by patching files, including binary files, directly. Other
23348 restrictions may apply: for instance, when adding a graft to a package
23349 providing a shared library, the original shared library and its replacement
23350 must have the same @code{SONAME} and be binary-compatible.
23352 The @option{--no-grafts} command-line option allows you to forcefully avoid
23353 grafting (@pxref{Gemeinsame Erstellungsoptionen, @option{--no-grafts}}). Thus, the
23357 guix build bash --no-grafts
23361 returns the store file name of the original Bash, whereas:
23368 returns the store file name of the ``fixed'', replacement Bash. This allows
23369 you to distinguish between the two variants of Bash.
23371 To verify which Bash your whole profile refers to, you can run
23372 (@pxref{Aufruf von guix gc}):
23375 guix gc -R `readlink -f ~/.guix-profile` | grep bash
23379 @dots{} and compare the store file names that you get with those above.
23380 Likewise for a complete GuixSD system generation:
23383 guix gc -R `guix system build my-config.scm` | grep bash
23386 Lastly, to check which Bash running processes are using, you can use the
23387 @command{lsof} command:
23390 lsof | grep /gnu/store/.*bash
23395 @section Paketmodule
23397 From a programming viewpoint, the package definitions of the GNU
23398 distribution are provided by Guile modules in the @code{(gnu packages
23399 @dots{})} name space@footnote{Note that packages under the @code{(gnu
23400 packages @dots{})} module name space are not necessarily ``GNU packages''.
23401 This module naming scheme follows the usual Guile module naming convention:
23402 @code{gnu} means that these modules are distributed as part of the GNU
23403 system, and @code{packages} identifies modules that define packages.}
23404 (@pxref{Module, Guile modules,, guile, GNU Guile Reference Manual}). For
23405 instance, the @code{(gnu packages emacs)} module exports a variable named
23406 @code{emacs}, which is bound to a @code{<package>} object (@pxref{Pakete definieren}).
23408 The @code{(gnu packages @dots{})} module name space is automatically scanned
23409 for packages by the command-line tools. For instance, when running
23410 @code{guix package -i emacs}, all the @code{(gnu packages @dots{})} modules
23411 are scanned until one that exports a package object whose name is
23412 @code{emacs} is found. This package search facility is implemented in the
23413 @code{(gnu packages)} module.
23415 @cindex Anpassung, von Paketen
23416 @cindex package module search path
23417 Users can store package definitions in modules with different names---e.g.,
23418 @code{(my-packages emacs)}@footnote{Note that the file name and module name
23419 must match. For instance, the @code{(my-packages emacs)} module must be
23420 stored in a @file{my-packages/emacs.scm} file relative to the load path
23421 specified with @option{--load-path} or @code{GUIX_PACKAGE_PATH}.
23422 @xref{Modules and the File System,,, guile, GNU Guile Reference Manual}, for
23423 details.}. There are two ways to make these package definitions visible to
23424 the user interfaces:
23428 By adding the directory containing your package modules to the search path
23429 with the @code{-L} flag of @command{guix package} and other commands
23430 (@pxref{Gemeinsame Erstellungsoptionen}), or by setting the @code{GUIX_PACKAGE_PATH}
23431 environment variable described below.
23434 By defining a @dfn{channel} and configuring @command{guix pull} so that it
23435 pulls from it. A channel is essentially a Git repository containing package
23436 modules. @xref{Channels}, for more information on how to define and use
23440 @code{GUIX_PACKAGE_PATH} works similarly to other search path variables:
23442 @defvr {Environment Variable} GUIX_PACKAGE_PATH
23443 This is a colon-separated list of directories to search for additional
23444 package modules. Directories listed in this variable take precedence over
23445 the own modules of the distribution.
23448 The distribution is fully @dfn{bootstrapped} and @dfn{self-contained}: each
23449 package is built based solely on other packages in the distribution. The
23450 root of this dependency graph is a small set of @dfn{bootstrap binaries},
23451 provided by the @code{(gnu packages bootstrap)} module. For more
23452 information on bootstrapping, @pxref{Bootstrapping}.
23454 @node Paketrichtlinien
23455 @section Paketrichtlinien
23457 @cindex packages, creating
23458 The GNU distribution is nascent and may well lack some of your favorite
23459 packages. This section describes how you can help make the distribution
23460 grow. @xref{Mitwirken}, for additional information on how you can help.
23462 Free software packages are usually distributed in the form of @dfn{source
23463 code tarballs}---typically @file{tar.gz} files that contain all the source
23464 files. Adding a package to the distribution means essentially two things:
23465 adding a @dfn{recipe} that describes how to build the package, including a
23466 list of other packages required to build it, and adding @dfn{package
23467 metadata} along with that recipe, such as a description and licensing
23470 In Guix all this information is embodied in @dfn{package definitions}.
23471 Package definitions provide a high-level view of the package. They are
23472 written using the syntax of the Scheme programming language; in fact, for
23473 each package we define a variable bound to the package definition, and
23474 export that variable from a module (@pxref{Paketmodule}). However,
23475 in-depth Scheme knowledge is @emph{not} a prerequisite for creating
23476 packages. For more information on package definitions, @pxref{Pakete definieren}.
23478 Once a package definition is in place, stored in a file in the Guix source
23479 tree, it can be tested using the @command{guix build} command
23480 (@pxref{Aufruf von guix build}). For example, assuming the new package is
23481 called @code{gnew}, you may run this command from the Guix build tree
23482 (@pxref{Guix vor der Installation ausführen}):
23485 ./pre-inst-env guix build gnew --keep-failed
23488 Using @code{--keep-failed} makes it easier to debug build failures since it
23489 provides access to the failed build tree. Another useful command-line
23490 option when debugging is @code{--log-file}, to access the build log.
23492 If the package is unknown to the @command{guix} command, it may be that the
23493 source file contains a syntax error, or lacks a @code{define-public} clause
23494 to export the package variable. To figure it out, you may load the module
23495 from Guile to get more information about the actual error:
23498 ./pre-inst-env guile -c '(use-modules (gnu packages gnew))'
23501 Once your package builds correctly, please send us a patch
23502 (@pxref{Mitwirken}). Well, if you need help, we will be happy to help
23503 you too. Once the patch is committed in the Guix repository, the new
23504 package automatically gets built on the supported platforms by
23505 @url{http://hydra.gnu.org/jobset/gnu/master, our continuous integration
23508 @cindex substituter
23509 Users can obtain the new package definition simply by running @command{guix
23510 pull} (@pxref{Aufruf von guix pull}). When @code{hydra.gnu.org} is done
23511 building the package, installing the package automatically downloads
23512 binaries from there (@pxref{Substitute}). The only place where human
23513 intervention is needed is to review and apply the patch.
23517 * Software-Freiheit:: Was in die Distribution aufgenommen werden
23519 * Paketbenennung:: Was macht einen Namen aus?
23520 * Versionsnummern:: Wenn der Name noch nicht genug ist.
23521 * Zusammenfassungen und Beschreibungen:: Den Nutzern helfen, das richtige
23523 * Python-Module:: Ein Touch britischer Comedy.
23524 * Perl-Module:: Kleine Perlen.
23525 * Java-Pakete:: Kaffeepause.
23526 * Schriftarten:: Schriften verschriftlicht.
23529 @node Software-Freiheit
23530 @subsection Software-Freiheit
23532 @c Adapted from http://www.gnu.org/philosophy/philosophy.html.
23533 @cindex free software
23534 The GNU operating system has been developed so that users can have freedom
23535 in their computing. GNU is @dfn{free software}, meaning that users have the
23536 @url{http://www.gnu.org/philosophy/free-sw.html,four essential freedoms}: to
23537 run the program, to study and change the program in source code form, to
23538 redistribute exact copies, and to distribute modified versions. Packages
23539 found in the GNU distribution provide only software that conveys these four
23542 In addition, the GNU distribution follow the
23543 @url{http://www.gnu.org/distros/free-system-distribution-guidelines.html,free
23544 software distribution guidelines}. Among other things, these guidelines
23545 reject non-free firmware, recommendations of non-free software, and discuss
23546 ways to deal with trademarks and patents.
23548 Some otherwise free upstream package sources contain a small and optional
23549 subset that violates the above guidelines, for instance because this subset
23550 is itself non-free code. When that happens, the offending items are removed
23551 with appropriate patches or code snippets in the @code{origin} form of the
23552 package (@pxref{Pakete definieren}). This way, @code{guix build --source}
23553 returns the ``freed'' source rather than the unmodified upstream source.
23556 @node Paketbenennung
23557 @subsection Paketbenennung
23559 @cindex package name
23560 A package has actually two names associated with it: First, there is the
23561 name of the @emph{Scheme variable}, the one following @code{define-public}.
23562 By this name, the package can be made known in the Scheme code, for instance
23563 as input to another package. Second, there is the string in the @code{name}
23564 field of a package definition. This name is used by package management
23565 commands such as @command{guix package} and @command{guix build}.
23567 Both are usually the same and correspond to the lowercase conversion of the
23568 project name chosen upstream, with underscores replaced with hyphens. For
23569 instance, GNUnet is available as @code{gnunet}, and SDL_net as
23572 We do not add @code{lib} prefixes for library packages, unless these are
23573 already part of the official project name. But @pxref{Python-Module} and
23574 @ref{Perl-Module} for special rules concerning modules for the Python and
23577 Font package names are handled differently, @pxref{Schriftarten}.
23580 @node Versionsnummern
23581 @subsection Versionsnummern
23583 @cindex package version
23584 We usually package only the latest version of a given free software
23585 project. But sometimes, for instance for incompatible library versions, two
23586 (or more) versions of the same package are needed. These require different
23587 Scheme variable names. We use the name as defined in @ref{Paketbenennung}
23588 for the most recent version; previous versions use the same name, suffixed
23589 by @code{-} and the smallest prefix of the version number that may
23590 distinguish the two versions.
23592 The name inside the package definition is the same for all versions of a
23593 package and does not contain any version number.
23595 For instance, the versions 2.24.20 and 3.9.12 of GTK+ may be packaged as
23599 (define-public gtk+
23604 (define-public gtk+-2
23607 (version "2.24.20")
23610 If we also wanted GTK+ 3.8.2, this would be packaged as
23612 (define-public gtk+-3.8
23619 @c See <https://lists.gnu.org/archive/html/guix-devel/2016-01/msg00425.html>,
23620 @c for a discussion of what follows.
23621 @cindex version number, for VCS snapshots
23622 Occasionally, we package snapshots of upstream's version control system
23623 (VCS) instead of formal releases. This should remain exceptional, because
23624 it is up to upstream developers to clarify what the stable release is. Yet,
23625 it is sometimes necessary. So, what should we put in the @code{version}
23628 Clearly, we need to make the commit identifier of the VCS snapshot visible
23629 in the version string, but we also need to make sure that the version string
23630 is monotonically increasing so that @command{guix package --upgrade} can
23631 determine which version is newer. Since commit identifiers, notably with
23632 Git, are not monotonically increasing, we add a revision number that we
23633 increase each time we upgrade to a newer snapshot. The resulting version
23634 string looks like this:
23639 | | `-- upstream commit ID
23641 | `--- Guix package revision
23643 latest upstream version
23646 It is a good idea to strip commit identifiers in the @code{version} field
23647 to, say, 7 digits. It avoids an aesthetic annoyance (assuming aesthetics
23648 have a role to play here) as well as problems related to OS limits such as
23649 the maximum shebang length (127 bytes for the Linux kernel.) It is best to
23650 use the full commit identifiers in @code{origin}s, though, to avoid
23651 ambiguities. A typical package definition may look like this:
23655 (let ((commit "c3f29bc928d5900971f65965feaae59e1272a3f7")
23656 (revision "1")) ;Guix package revision
23658 (version (git-version "0.9" revision commit))
23661 (uri (git-reference
23662 (url "git://example.org/my-package.git")
23664 (sha256 (base32 "1mbikn@dots{}"))
23665 (file-name (git-file-name name version))))
23670 @node Zusammenfassungen und Beschreibungen
23671 @subsection Zusammenfassungen und Beschreibungen
23673 @cindex package description
23674 @cindex package synopsis
23675 As we have seen before, each package in GNU@tie{}Guix includes a synopsis
23676 and a description (@pxref{Pakete definieren}). Synopses and descriptions
23677 are important: They are what @command{guix package --search} searches, and a
23678 crucial piece of information to help users determine whether a given package
23679 suits their needs. Consequently, packagers should pay attention to what
23682 Synopses must start with a capital letter and must not end with a period.
23683 They must not start with ``a'' or ``the'', which usually does not bring
23684 anything; for instance, prefer ``File-frobbing tool'' over ``A tool that
23685 frobs files''. The synopsis should say what the package is---e.g., ``Core
23686 GNU utilities (file, text, shell)''---or what it is used for---e.g., the
23687 synopsis for GNU@tie{}grep is ``Print lines matching a pattern''.
23689 Keep in mind that the synopsis must be meaningful for a very wide audience.
23690 For example, ``Manipulate alignments in the SAM format'' might make sense
23691 for a seasoned bioinformatics researcher, but might be fairly unhelpful or
23692 even misleading to a non-specialized audience. It is a good idea to come up
23693 with a synopsis that gives an idea of the application domain of the
23694 package. In this example, this might give something like ``Manipulate
23695 nucleotide sequence alignments'', which hopefully gives the user a better
23696 idea of whether this is what they are looking for.
23698 Descriptions should take between five and ten lines. Use full sentences,
23699 and avoid using acronyms without first introducing them. Please avoid
23700 marketing phrases such as ``world-leading'', ``industrial-strength'', and
23701 ``next-generation'', and avoid superlatives like ``the most
23702 advanced''---they are not helpful to users looking for a package and may
23703 even sound suspicious. Instead, try to be factual, mentioning use cases and
23706 @cindex Texinfo markup, in package descriptions
23707 Descriptions can include Texinfo markup, which is useful to introduce
23708 ornaments such as @code{@@code} or @code{@@dfn}, bullet lists, or hyperlinks
23709 (@pxref{Overview,,, texinfo, GNU Texinfo}). However you should be careful
23710 when using some characters for example @samp{@@} and curly braces which are
23711 the basic special characters in Texinfo (@pxref{Special Characters,,,
23712 texinfo, GNU Texinfo}). User interfaces such as @command{guix package
23713 --show} take care of rendering it appropriately.
23715 Synopses and descriptions are translated by volunteers
23716 @uref{http://translationproject.org/domain/guix-packages.html, at the
23717 Translation Project} so that as many users as possible can read them in
23718 their native language. User interfaces search them and display them in the
23719 language specified by the current locale.
23721 To allow @command{xgettext} to extract them as translatable strings,
23722 synopses and descriptions @emph{must be literal strings}. This means that
23723 you cannot use @code{string-append} or @code{format} to construct these
23729 (synopsis "This is translatable")
23730 (description (string-append "This is " "*not*" " translatable.")))
23733 Translation is a lot of work so, as a packager, please pay even more
23734 attention to your synopses and descriptions as every change may entail
23735 additional work for translators. In order to help them, it is possible to
23736 make recommendations or instructions visible to them by inserting special
23737 comments like this (@pxref{xgettext Invocation,,, gettext, GNU Gettext}):
23740 ;; TRANSLATORS: "X11 resize-and-rotate" should not be translated.
23741 (description "ARandR is designed to provide a simple visual front end
23742 for the X11 resize-and-rotate (RandR) extension. @dots{}")
23746 @node Python-Module
23747 @subsection Python-Module
23750 We currently package Python 2 and Python 3, under the Scheme variable names
23751 @code{python-2} and @code{python} as explained in @ref{Versionsnummern}. To
23752 avoid confusion and naming clashes with other programming languages, it
23753 seems desirable that the name of a package for a Python module contains the
23754 word @code{python}.
23756 Some modules are compatible with only one version of Python, others with
23757 both. If the package Foo compiles only with Python 3, we name it
23758 @code{python-foo}; if it compiles only with Python 2, we name it
23759 @code{python2-foo}. If it is compatible with both versions, we create two
23760 packages with the corresponding names.
23762 If a project already contains the word @code{python}, we drop this; for
23763 instance, the module python-dateutil is packaged under the names
23764 @code{python-dateutil} and @code{python2-dateutil}. If the project name
23765 starts with @code{py} (e.g.@: @code{pytz}), we keep it and prefix it as
23768 @subsubsection Specifying Dependencies
23769 @cindex inputs, for Python packages
23771 Dependency information for Python packages is usually available in the
23772 package source tree, with varying degrees of accuracy: in the
23773 @file{setup.py} file, in @file{requirements.txt}, or in @file{tox.ini}.
23775 Your mission, when writing a recipe for a Python package, is to map these
23776 dependencies to the appropriate type of ``input'' (@pxref{„package“-Referenz,
23777 inputs}). Although the @code{pypi} importer normally does a good job
23778 (@pxref{Aufruf von guix import}), you may want to check the following check
23779 list to determine which dependency goes where.
23784 We currently package Python 2 with @code{setuptools} and @code{pip}
23785 installed like Python 3.4 has per default. Thus you don't need to specify
23786 either of these as an input. @command{guix lint} will warn you if you do.
23789 Python dependencies required at run time go into @code{propagated-inputs}.
23790 They are typically defined with the @code{install_requires} keyword in
23791 @file{setup.py}, or in the @file{requirements.txt} file.
23794 Python packages required only at build time---e.g., those listed with the
23795 @code{setup_requires} keyword in @file{setup.py}---or only for
23796 testing---e.g., those in @code{tests_require}---go into
23797 @code{native-inputs}. The rationale is that (1) they do not need to be
23798 propagated because they are not needed at run time, and (2) in a
23799 cross-compilation context, it's the ``native'' input that we'd want.
23801 Examples are the @code{pytest}, @code{mock}, and @code{nose} test
23802 frameworks. Of course if any of these packages is also required at
23803 run-time, it needs to go to @code{propagated-inputs}.
23806 Anything that does not fall in the previous categories goes to
23807 @code{inputs}, for example programs or C libraries required for building
23808 Python packages containing C extensions.
23811 If a Python package has optional dependencies (@code{extras_require}), it is
23812 up to you to decide whether to add them or not, based on their
23813 usefulness/overhead ratio (@pxref{Einreichen von Patches, @command{guix size}}).
23819 @subsection Perl-Module
23822 Perl programs standing for themselves are named as any other package, using
23823 the lowercase upstream name. For Perl packages containing a single class,
23824 we use the lowercase class name, replace all occurrences of @code{::} by
23825 dashes and prepend the prefix @code{perl-}. So the class @code{XML::Parser}
23826 becomes @code{perl-xml-parser}. Modules containing several classes keep
23827 their lowercase upstream name and are also prepended by @code{perl-}. Such
23828 modules tend to have the word @code{perl} somewhere in their name, which
23829 gets dropped in favor of the prefix. For instance, @code{libwww-perl}
23830 becomes @code{perl-libwww}.
23834 @subsection Java-Pakete
23837 Java programs standing for themselves are named as any other package, using
23838 the lowercase upstream name.
23840 To avoid confusion and naming clashes with other programming languages, it
23841 is desirable that the name of a package for a Java package is prefixed with
23842 @code{java-}. If a project already contains the word @code{java}, we drop
23843 this; for instance, the package @code{ngsjava} is packaged under the name
23846 For Java packages containing a single class or a small class hierarchy, we
23847 use the lowercase class name, replace all occurrences of @code{.} by dashes
23848 and prepend the prefix @code{java-}. So the class @code{apache.commons.cli}
23849 becomes package @code{java-apache-commons-cli}.
23853 @subsection Schriftarten
23855 @cindex Schriftarten
23856 For fonts that are in general not installed by a user for typesetting
23857 purposes, or that are distributed as part of a larger software package, we
23858 rely on the general packaging rules for software; for instance, this applies
23859 to the fonts delivered as part of the X.Org system or fonts that are part of
23862 To make it easier for a user to search for fonts, names for other packages
23863 containing only fonts are constructed as follows, independently of the
23864 upstream package name.
23866 The name of a package containing only one font family starts with
23867 @code{font-}; it is followed by the foundry name and a dash @code{-} if the
23868 foundry is known, and the font family name, in which spaces are replaced by
23869 dashes (and as usual, all upper case letters are transformed to lower
23870 case). For example, the Gentium font family by SIL is packaged under the
23871 name @code{font-sil-gentium}.
23873 For a package containing several font families, the name of the collection
23874 is used in the place of the font family name. For instance, the Liberation
23875 fonts consist of three families, Liberation Sans, Liberation Serif and
23876 Liberation Mono. These could be packaged separately under the names
23877 @code{font-liberation-sans} and so on; but as they are distributed together
23878 under a common name, we prefer to package them together as
23879 @code{font-liberation}.
23881 In the case where several formats of the same font family or font collection
23882 are packaged separately, a short form of the format, prepended by a dash, is
23883 added to the package name. We use @code{-ttf} for TrueType fonts,
23884 @code{-otf} for OpenType fonts and @code{-type1} for PostScript Type 1
23889 @node Bootstrapping
23890 @section Bootstrapping
23892 @c Adapted from the ELS 2013 paper.
23894 @cindex bootstrapping
23896 Bootstrapping in our context refers to how the distribution gets built
23897 ``from nothing''. Remember that the build environment of a derivation
23898 contains nothing but its declared inputs (@pxref{Einführung}). So there's
23899 an obvious chicken-and-egg problem: how does the first package get built?
23900 How does the first compiler get compiled? Note that this is a question of
23901 interest only to the curious hacker, not to the regular user, so you can
23902 shamelessly skip this section if you consider yourself a ``regular user''.
23904 @cindex bootstrap binaries
23905 The GNU system is primarily made of C code, with libc at its core. The GNU
23906 build system itself assumes the availability of a Bourne shell and
23907 command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and
23908 `grep'. Furthermore, build programs---programs that run @code{./configure},
23909 @code{make}, etc.---are written in Guile Scheme (@pxref{Ableitungen}).
23910 Consequently, to be able to build anything at all, from scratch, Guix relies
23911 on pre-built binaries of Guile, GCC, Binutils, libc, and the other packages
23912 mentioned above---the @dfn{bootstrap binaries}.
23914 These bootstrap binaries are ``taken for granted'', though we can also
23915 re-create them if needed (more on that later).
23917 @unnumberedsubsec Preparing to Use the Bootstrap Binaries
23919 @c As of Emacs 24.3, Info-mode displays the image, but since it's a
23920 @c large image, it's hard to scroll. Oh well.
23921 @image{images/bootstrap-graph,6in,,Dependency graph of the early bootstrap
23924 The figure above shows the very beginning of the dependency graph of the
23925 distribution, corresponding to the package definitions of the @code{(gnu
23926 packages bootstrap)} module. A similar figure can be generated with
23927 @command{guix graph} (@pxref{Aufruf von guix graph}), along the lines of:
23930 guix graph -t derivation \
23931 -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \
23935 At this level of detail, things are slightly complex. First, Guile itself
23936 consists of an ELF executable, along with many source and compiled Scheme
23937 files that are dynamically loaded when it runs. This gets stored in the
23938 @file{guile-2.0.7.tar.xz} tarball shown in this graph. This tarball is part
23939 of Guix's ``source'' distribution, and gets inserted into the store with
23940 @code{add-to-store} (@pxref{Der Store}).
23942 But how do we write a derivation that unpacks this tarball and adds it to
23943 the store? To solve this problem, the @code{guile-bootstrap-2.0.drv}
23944 derivation---the first one that gets built---uses @code{bash} as its
23945 builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls
23946 @code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar}, @file{xz},
23947 and @file{mkdir} are statically-linked binaries, also part of the Guix
23948 source distribution, whose sole purpose is to allow the Guile tarball to be
23951 Once @code{guile-bootstrap-2.0.drv} is built, we have a functioning Guile
23952 that can be used to run subsequent build programs. Its first task is to
23953 download tarballs containing the other pre-built binaries---this is what the
23954 @code{.tar.xz.drv} derivations do. Guix modules such as
23955 @code{ftp-client.scm} are used for this purpose. The
23956 @code{module-import.drv} derivations import those modules in a directory in
23957 the store, using the original layout. The @code{module-import-compiled.drv}
23958 derivations compile those modules, and write them in an output directory
23959 with the right layout. This corresponds to the @code{#:modules} argument of
23960 @code{build-expression->derivation} (@pxref{Ableitungen}).
23962 Finally, the various tarballs are unpacked by the derivations
23963 @code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, etc., at which
23964 point we have a working C tool chain.
23967 @unnumberedsubsec Building the Build Tools
23969 Bootstrapping is complete when we have a full tool chain that does not
23970 depend on the pre-built bootstrap tools discussed above. This no-dependency
23971 requirement is verified by checking whether the files of the final tool
23972 chain contain references to the @file{/gnu/store} directories of the
23973 bootstrap inputs. The process that leads to this ``final'' tool chain is
23974 described by the package definitions found in the @code{(gnu packages
23975 commencement)} module.
23977 The @command{guix graph} command allows us to ``zoom out'' compared to the
23978 graph above, by looking at the level of package objects instead of
23979 individual derivations---remember that a package may translate to several
23980 derivations, typically one derivation to download its source, one to build
23981 the Guile modules it needs, and one to actually build the package from
23982 source. The command:
23985 guix graph -t bag \
23986 -e '(@@@@ (gnu packages commencement)
23987 glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps
23991 produces the dependency graph leading to the ``final'' C
23992 library@footnote{You may notice the @code{glibc-intermediate} label,
23993 suggesting that it is not @emph{quite} final, but as a good approximation,
23994 we will consider it final.}, depicted below.
23996 @image{images/bootstrap-packages,6in,,Dependency graph of the early
23999 @c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>.
24000 The first tool that gets built with the bootstrap binaries is
24001 GNU@tie{}Make---noted @code{make-boot0} above---which is a prerequisite for
24002 all the following packages. From there Findutils and Diffutils get built.
24004 Then come the first-stage Binutils and GCC, built as pseudo cross
24005 tools---i.e., with @code{--target} equal to @code{--host}. They are used to
24006 build libc. Thanks to this cross-build trick, this libc is guaranteed not
24007 to hold any reference to the initial tool chain.
24009 From there the final Binutils and GCC (not shown above) are built. GCC uses
24010 @code{ld} from the final Binutils, and links programs against the just-built
24011 libc. This tool chain is used to build the other packages used by Guix and
24012 by the GNU Build System: Guile, Bash, Coreutils, etc.
24014 And voilà! At this point we have the complete set of build tools that the
24015 GNU Build System expects. These are in the @code{%final-inputs} variable of
24016 the @code{(gnu packages commencement)} module, and are implicitly used by
24017 any package that uses @code{gnu-build-system} (@pxref{Erstellungssysteme,
24018 @code{gnu-build-system}}).
24021 @unnumberedsubsec Building the Bootstrap Binaries
24023 @cindex bootstrap binaries
24024 Because the final tool chain does not depend on the bootstrap binaries,
24025 those rarely need to be updated. Nevertheless, it is useful to have an
24026 automated way to produce them, should an update occur, and this is what the
24027 @code{(gnu packages make-bootstrap)} module provides.
24029 The following command builds the tarballs containing the bootstrap binaries
24030 (Guile, Binutils, GCC, libc, and a tarball containing a mixture of Coreutils
24031 and other basic command-line tools):
24034 guix build bootstrap-tarballs
24037 The generated tarballs are those that should be referred to in the
24038 @code{(gnu packages bootstrap)} module mentioned at the beginning of this
24041 Still here? Then perhaps by now you've started to wonder: when do we reach a
24042 fixed point? That is an interesting question! The answer is unknown, but if
24043 you would like to investigate further (and have significant computational
24044 and storage resources to do so), then let us know.
24046 @unnumberedsubsec Reducing the Set of Bootstrap Binaries
24048 Our bootstrap binaries currently include GCC, Guile, etc. That's a lot of
24049 binary code! Why is that a problem? It's a problem because these big chunks
24050 of binary code are practically non-auditable, which makes it hard to
24051 establish what source code produced them. Every unauditable binary also
24052 leaves us vulnerable to compiler backdoors as described by Ken Thompson in
24053 the 1984 paper @emph{Reflections on Trusting Trust}.
24055 This is mitigated by the fact that our bootstrap binaries were generated
24056 from an earlier Guix revision. Nevertheless it lacks the level of
24057 transparency that we get in the rest of the package dependency graph, where
24058 Guix always gives us a source-to-binary mapping. Thus, our goal is to
24059 reduce the set of bootstrap binaries to the bare minimum.
24061 The @uref{http://bootstrappable.org, Bootstrappable.org web site} lists
24062 on-going projects to do that. One of these is about replacing the bootstrap
24063 GCC with a sequence of assemblers, interpreters, and compilers of increasing
24064 complexity, which could be built from source starting from a simple and
24065 auditable assembler. Your help is welcome!
24069 @section Porting to a New Platform
24071 As discussed above, the GNU distribution is self-contained, and
24072 self-containment is achieved by relying on pre-built ``bootstrap binaries''
24073 (@pxref{Bootstrapping}). These binaries are specific to an operating system
24074 kernel, CPU architecture, and application binary interface (ABI). Thus, to
24075 port the distribution to a platform that is not yet supported, one must
24076 build those bootstrap binaries, and update the @code{(gnu packages
24077 bootstrap)} module to use them on that platform.
24079 Fortunately, Guix can @emph{cross compile} those bootstrap binaries. When
24080 everything goes well, and assuming the GNU tool chain supports the target
24081 platform, this can be as simple as running a command like this one:
24084 guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs
24087 For this to work, the @code{glibc-dynamic-linker} procedure in @code{(gnu
24088 packages bootstrap)} must be augmented to return the right file name for
24089 libc's dynamic linker on that platform; likewise,
24090 @code{system->linux-architecture} in @code{(gnu packages linux)} must be
24091 taught about the new platform.
24093 Once these are built, the @code{(gnu packages bootstrap)} module needs to be
24094 updated to refer to these binaries on the target platform. That is, the
24095 hashes and URLs of the bootstrap tarballs for the new platform must be added
24096 alongside those of the currently supported platforms. The bootstrap Guile
24097 tarball is treated specially: it is expected to be available locally, and
24098 @file{gnu/local.mk} has rules to download it for the supported
24099 architectures; a rule for the new platform must be added as well.
24101 In practice, there may be some complications. First, it may be that the
24102 extended GNU triplet that specifies an ABI (like the @code{eabi} suffix
24103 above) is not recognized by all the GNU tools. Typically, glibc recognizes
24104 some of these, whereas GCC uses an extra @code{--with-abi} configure flag
24105 (see @code{gcc.scm} for examples of how to handle this). Second, some of
24106 the required packages could fail to build for that platform. Lastly, the
24107 generated binaries could be broken for some reason.
24109 @c *********************************************************************
24110 @include contributing.de.texi
24112 @c *********************************************************************
24114 @chapter Danksagungen
24116 Guix is based on the @uref{http://nixos.org/nix/, Nix package manager},
24117 which was designed and implemented by Eelco Dolstra, with contributions from
24118 other people (see the @file{nix/AUTHORS} file in Guix.) Nix pioneered
24119 functional package management, and promoted unprecedented features, such as
24120 transactional package upgrades and rollbacks, per-user profiles, and
24121 referentially transparent build processes. Without this work, Guix would
24124 The Nix-based software distributions, Nixpkgs and NixOS, have also been an
24125 inspiration for Guix.
24127 GNU@tie{}Guix itself is a collective work with contributions from a number
24128 of people. See the @file{AUTHORS} file in Guix for more information on
24129 these fine people. The @file{THANKS} file lists people who have helped by
24130 reporting bugs, taking care of the infrastructure, providing artwork and
24131 themes, making suggestions, and more---thank you!
24134 @c *********************************************************************
24135 @node GNU-Lizenz für freie Dokumentation
24136 @appendix GNU-Lizenz für freie Dokumentation
24137 @cindex license, GNU Free Documentation License
24138 @include fdl-1.3.texi
24140 @c *********************************************************************
24141 @node Konzeptverzeichnis
24142 @unnumbered Konzeptverzeichnis
24145 @node Programmierverzeichnis
24146 @unnumbered Programmierverzeichnis
24147 @syncodeindex tp fn
24148 @syncodeindex vr fn
24153 @c Local Variables:
24154 @c ispell-local-dictionary: "american";