     [file version-de.texi not included]

Copyright © 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 Ludovic Courtès
 Copyright © 2013, 2014, 2016 Andreas Enge

Copyright © 2013 Nikita Karetnikov
 Copyright © 2014, 2015, 2016 Alex Kost
 Copyright © 2015, 2016 Mathieu Lirzin

Copyright © 2014 Pierre-Antoine Rault
 Copyright © 2015 Taylan Ulrich Bayırlı/Kammer
 Copyright © 2015, 2016, 2017 Leo Famulari
 Copyright © 2015, 2016, 2017, 2018, 2019 Ricardo Wurmus
 Copyright © 2016 Ben Woodcroft
 Copyright © 2016, 2017, 2018 Chris Marusich
 Copyright © 2016, 2017, 2018 Efraim Flashner
 Copyright © 2016 John Darrington
 Copyright © 2016, 2017 Nils Gillmann
 Copyright © 2016, 2017, 2018, 2019 Jan Nieuwenhuizen
 Copyright © 2016 Julien Lepiller

Copyright © 2016 Alex ter Weele
 Copyright © 2016, 2017, 2018, 2019 Christopher Baines
 Copyright © 2017, 2018 Clément Lassieur
 Copyright © 2017, 2018 Mathieu Othacehe

Copyright © 2017 Federico Beffa
 Copyright © 2017, 2018 Carlo Zancanaro
 Copyright © 2017 Thomas Danckaert

Copyright © 2017 humanitiesNerd
 Copyright © 2017 Christopher Allan Webber
 Copyright © 2017, 2018 Marius Bakke

Copyright © 2017 Hartmut Goebel
 Copyright © 2017 Maxim Cournoyer
 Copyright © 2017, 2018 Tobias Geerinckx-Rice

Copyright © 2017 George Clemmer
 Copyright © 2017 Andy Wingo
 Copyright © 2017, 2018 Arun Isaac
 Copyright © 2017 nee
 Copyright © 2018 Rutger Helling

Copyright © 2018 Oleg Pykhalov
 Copyright © 2018 Mike Gerwitz
 Copyright © 2018 Pierre-Antoine Rouby
 Copyright © 2018 Gábor Boskovits
 Copyright © 2018 Florian Pelz
 Copyright © 2018 Laura Lazzati
 Copyright © 2018 Alex Vong

Es ist Ihnen gestattet, dieses Dokument zu vervielfältigen, weiterzugeben und/oder zu verändern, unter den Bedingungen der GNU Free Documentation License, entweder gemäß Version 1.3 der Lizenz oder (nach Ihrer Option) einer späteren Version, die von der Free Software Foundation veröffentlicht wurde, ohne unveränderliche Abschnitte, ohne vorderen Umschlagtext und ohne hinteren Umschlagtext. Eine Kopie der Lizenz finden Sie im Abschnitt mit dem Titel »GNU Free Documentation License«.

GNU Guix
********

Dieses Dokument beschreibt GNU Guix, Version VERSION, ein Werkzeug zur funktionalen Verwaltung von Softwarepaketen, das für das GNU-System geschrieben wurde.

Dieses Handbuch ist auch auf Englisch (see GNU Guix Reference Manual) und Französisch verfügbar (see Manuel de référence de GNU Guix). Wenn Sie es in Ihre eigene Sprache übersetzen möchten, dann sind Sie beim Translation Project (https://translationproject.org/domain/guix-manual.html) herzlich willkommen.

Einführung
**********

GNU Guix (``Guix'' is pronounced like ``geeks'', or ``ɡiːks'' using the international phonetic alphabet (IPA).) is a package management tool for and distribution of the GNU system.  Guix makes it easy for unprivileged users to install, upgrade, or remove software packages, to roll back to a previous package set, to build packages from source, and generally assists with the creation and maintenance of software environments.

You can install GNU Guix on top of an existing GNU/Linux system where it complements the available tools without interference (see Installation), or you can use it as a standalone operating system distribution, Guix System (We used to refer to Guix System as ``Guix System Distribution'' or ``GuixSD''.  We now consider it makes more sense to group everything under the ``Guix'' banner since, after all, Guix System is readily available through the guix system command, even if you're using a different distro underneath!).  See GNU-Distribution.

Managing Software the Guix Way
==============================

Guix provides a command-line package management interface (see Paketverwaltung), tools to help with software development (see Development), command-line utilities for more advanced usage, (see Zubehör), as well as Scheme programming interfaces (see Programmierschnittstelle). Der Erstellungs-Daemon ist für das Erstellen von Paketen im Auftrag von Nutzern verantwortlich (see Den Daemon einrichten) und für das Herunterladen vorerstellter Binärdateien aus autorisierten Quellen (see Substitute).

Guix enthält Paketdefinitionen für viele Pakete, von GNU und nicht von GNU, die alle die Freiheit des Computernutzers respektieren (https://www.gnu.org/philosophy/free-sw.html). Es ist erweiterbar: Nutzer können ihre eigenen Paketdefinitionen schreiben (see Pakete definieren) und sie als unabhängige Paketmodule verfügbar machen (see Paketmodule). Es ist auch anpassbar: Nutzer können spezialisierte Paketdefinitionen aus bestehenden ableiten, auch von der Befehlszeile (see Paketumwandlungsoptionen).

Intern implementiert Guix die Disziplin der funktionalen Paketverwaltung, zu der Nix schon die Pionierarbeit geleistet hat (see Danksagungen). In Guix wird der Prozess, ein Paket zu erstellen und zu installieren, als eine Funktion im mathematischen Sinn aufgefasst. Diese Funktion hat Eingaben, wie zum Beispiel Erstellungs-Skripts, einen Compiler und Bibliotheken, und liefert ein installiertes Paket. Als eine reine Funktion hängt sein Ergebnis allein von seinen Eingaben ab — zum Beispiel kann er nicht auf Software oder Skripts Bezug nehmen, die nicht ausdrücklich als Eingaben übergeben wurden. Eine Erstellungsfunktion führt immer zum selben Ergebnis, wenn ihr die gleiche Menge an Eingaben übergeben wurde. Sie kann die Umgebung des laufenden Systems auf keine Weise beeinflussen, zum Beispiel kann sie keine Dateien außerhalb ihrer Erstellungs- und Installationsverzeichnisse verändern. Um dies zu erreichen, laufen Erstellungsprozesse in isolieren Umgebungen (sogenannte Container), wo nur ausdrückliche Eingaben sichtbar sind.

Das Ergebnis von Paketerstellungsfunktionen wird im Dateisystem zwischengespeichert in einem besonderen Verzeichnis, was als der Store bezeichnet wird (see Der Store). Jedes Paket wird in sein eigenes Verzeichnis im Store installiert — standardmäßig ist er unter /gnu/store zu finden. Der Verzeichnisname enthält einen Hash aller Eingaben, anhand derer das Paket erzeugt wurde, somit hat das Ändern einer Eingabe einen völlig anderen Verzeichnisnamen zur Folge.

Dieses Vorgehen ist die Grundlage für die Guix auszeichnenden Funktionalitäten: Unterstützung transaktionsbasierter Paketaktualisierungen und -rückstufungen, Installation von Paketen als einfacher Nutzer sowie Garbage Collection für Pakete (see Funktionalitäten).

GNU-Distribution
================

Guix comes with a distribution of the GNU system consisting entirely of free software (The term ``free'' here refers to the freedom provided to users of that software (http://www.gnu.org/philosophy/free-sw.html).).  The distribution can be installed on its own (see Systeminstallation), but it is also possible to install Guix as a package manager on top of an installed GNU/Linux system (see Installation).  When we need to distinguish between the two, we refer to the standalone distribution as Guix System.

Die Distribution stellt den Kern der GNU-Pakete, also insbesondere GNU libc, GCC und Binutils, sowie zahlreiche zum GNU-Projekt gehörende und nicht dazu gehörende Anwendungen zur Verfügung. Die vollständige Liste verfügbarer Pakete können Sie online (http://www.gnu.org/software/guix/packages) einsehen, oder indem Sie guix package ausführen (see Aufruf von guix package):

     guix package --list-available

Unser Ziel ist, eine zu 100% freie Software-Distribution von Linux-basierten und von anderen GNU-Varianten anzubieten, mit dem Fokus darauf, das GNU-Projekt und die enge Zusammenarbeit seiner Bestandteile zu befördern, sowie die Programme und Werkzeuge hervorzuheben, die die Nutzer dabei unterstützen, von dieser Freiheit Gebrauch zu machen.

Pakete sind zur Zeit auf folgenden Plattformen verfügbar:

x86_64-linux
     Intel/AMD-x86_64-Architektur, Linux-Libre als Kernel,

i686-linux
     Intel-32-Bit-Architektur (IA-32), Linux-Libre als Kernel,

armhf-linux
     ARMv7-A-Architektur mit »hard float«, Thumb-2 und NEON, für die EABI »hard-float application binary interface«, mit Linux-Libre als Kernel.

aarch64-linux
     64-Bit-ARMv8-A-Prozessoren, little-endian, Linux-Libre als Kernel. Derzeit ist dies noch in der Erprobungsphase mit begrenzter Unterstützung. Unter see Mitwirken steht, wie Sie dabei helfen können!

mips64el-linux
     64-Bit-MIPS-Prozessoren, little-endian, insbesondere die Loongson-Reihe, n32-ABI, mit Linux-Libre als Kernel.

With Guix System, you declare all aspects of the operating system configuration and Guix takes care of instantiating the configuration in a transactional, reproducible, and stateless fashion (see Systemkonfiguration).  Guix System uses the Linux-libre kernel, the Shepherd initialization system (see Einführung (The GNU Shepherd Manual)), the well-known GNU utilities and tool chain, as well as the graphical environment or system services of your choice.

Guix System is available on all the above platforms except mips64el-linux.

Informationen, wie auf andere Architekturen oder Kernels portiert werden kann, finden Sie im Abschnitt see Portierung.

Diese Distribution aufzubauen basiert auf Kooperation, und Sie sind herzlich eingeladen, dabei mitzumachen! Im Abschnitt see Mitwirken stehen weitere Informationen, wie Sie uns helfen können.

Installation
************

     We recommend the use of this shell installer script (https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh) to install Guix on top of a running GNU/Linux system, thereafter called a foreign distro. (This section is concerned with the installation of the package manager, which can be done on top of a running GNU/Linux system.  If, instead, you want to install the complete GNU operating system, see Systeminstallation.) The script automates the download, installation, and initial configuration of Guix.  It should be run as the root user.

When installed on a foreign distro, GNU Guix complements the available tools without interference.  Its data lives exclusively in two directories, usually /gnu/store and /var/guix; other files on your system, such as /etc, are left untouched.

Sobald es installiert ist, kann Guix durch Ausführen von guix pull aktualisiert werden (see Aufruf von guix pull).

If you prefer to perform the installation steps manually or want to tweak them, you may find the following subsections useful.  They describe the software requirements of Guix, as well as how to install it manually and get ready to use it.

Aus Binärdatei installieren
===========================

Dieser Abschnitt beschreibt, wie sich Guix auf einem beliebigen System aus einem alle Komponenten umfassenden Tarball installieren lässt, der Binärdateien für Guix und all seine Abhängigkeiten liefert. Dies geht in der Regel schneller, als Guix aus seinen Quelldateien zu installieren, was in den nächsten Abschnitten beschrieben wird. Vorausgesetzt wird hier lediglich, dass GNU tar und Xz verfügbar sind.

Die Installation läuft so ab:

 1. Laden Sie den binären Tarball von https://alpha.gnu.org/gnu/guix/guix-binary-VERSION.SYSTEM.tar.xz herunter, wobei SYSTEM für x86_64-linux steht, falls Sie es auf einer Maschine mit x86_64-Architektur einrichten, auf der bereits der Linux-Kernel läuft, oder entsprechend für andere Maschinen.

     Achten Sie darauf, auch die zugehörige .sig-Datei herunterzuladen und verifizieren Sie damit die Authentizität des Tarballs, ungefähr so:

          $ wget https://alpha.gnu.org/gnu/guix/guix-binary-VERSION.SYSTEM.tar.xz.sig
          $ gpg --verify guix-binary-VERSION.SYSTEM.tar.xz.sig

     Falls dieser Befehl fehlschlägt, weil Sie nicht über den nötigen öffentlichen Schlüssel verfügen, können Sie ihn mit diesem Befehl importieren:

          $ gpg --keyserver pool.sks-keyservers.net \
                --recv-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5

     und den Befehl gpg --verify erneut ausführen.

 2. Nun müssen Sie zum Administratornutzer root wechseln. Abhängig von Ihrer Distribution müssen Sie dazu etwa su - oder sudo -i ausführen. Danach führen Sie als root-Nutzer aus:

          # cd /tmp
          # tar --warning=no-timestamp -xf \
               guix-binary-VERSION.SYSTEM.tar.xz
          # mv var/guix /var/ && mv gnu /

     Dadurch wird /gnu/store (see Der Store) und /var/guix erzeugt. Letzteres enthält ein fertiges Guix-Profil für den Administratornutzer root (wie im nächsten Schritt beschrieben).

     Entpacken Sie den Tarball nicht auf einem schon funktionierenden Guix-System, denn es würde seine eigenen essenziellen Dateien überschreiben.

     Die Befehlszeilenoption --warning=no-timestamp stellt sicher, dass GNU tar nicht vor »unplausibel alten Zeitstempeln« warnt (solche Warnungen traten bei GNU tar 1.26 und älter auf, neue Versionen machen keine Probleme). Sie treten auf, weil alle Dateien im Archiv als Änderungszeitpunkt null eingetragen bekommen haben (das bezeichnet den 1. Januar 1970). Das ist Absicht, damit der Inhalt des Archivs nicht davon abhängt, wann es erstellt wurde, und es somit reproduzierbar wird.

 3. Machen Sie das Profil als ~root/.config/guix/current verfügbar, wo guix pull es aktualisieren kann (see Aufruf von guix pull):

          # mkdir -p ~root/.config/guix
          # ln -sf /var/guix/profiles/per-user/root/current-guix \
                   ~root/.config/guix/current

     »Sourcen« Sie etc/profile, um PATH und andere relevante Umgebungsvariable zu ergänzen:

          # GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \
            source $GUIX_PROFILE/etc/profile

 4. Erzeugen Sie Nutzergruppe und Nutzerkonten für die Erstellungs-Benutzer wie folgt (see Einrichten der Erstellungsumgebung).

 5. Führen Sie den Daemon aus, und lassen Sie ihn automatisch bei jedem Hochfahren starten.

     Wenn Ihre Wirts-Distribution systemd als »init«-System verwendet, können Sie das mit folgenden Befehlen veranlassen:

          # cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \
               /etc/systemd/system/
          # systemctl start guix-daemon && systemctl enable guix-daemon

     Wenn Ihre Wirts-Distribution als »init«-System Upstart verwendet:

          # initctl reload-configuration
          # cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \
               /etc/init/
          # start guix-daemon

     Andernfalls können Sie den Daemon immer noch manuell starten, mit:

          # ~root/.config/guix/current/bin/guix-daemon \
                 --build-users-group=guixbuild

 6. Stellen Sie den guix-Befehl auch anderen Nutzern Ihrer Maschine zur Verfügung, zum Beispiel so:

          # mkdir -p /usr/local/bin
          # cd /usr/local/bin
          # ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix

     Es ist auch eine gute Idee, die Info-Version dieses Handbuchs ebenso verfügbar zu machen:

          # mkdir -p /usr/local/share/info
          # cd /usr/local/share/info
          # for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ;
            do ln -s $i ; done

     Auf diese Art wird, unter der Annahme, dass bei Ihnen /usr/local/share/info im Suchpfad eingetragen ist, das Ausführen von info guix dieses Handbuch öffnen (see Other Info Directories (GNU Texinfo) hat weitere Details, wie Sie den Info-Suchpfad ändern können).

 7. To use substitutes from ci.guix.de.info or one of its mirrors (see Substitute), authorize them:

          # guix archive --authorize < \
               ~root/.config/guix/current/share/guix/ci.guix.de.info.pub

 8. Alle Nutzer müssen womöglich ein paar zusätzliche Schritte ausführen, damit ihre Guix-Umgebung genutzt werden kann, siehe Anwendungen einrichten.

Voilà, die Installation ist fertig!

Sie können nachprüfen, dass Guix funktioniert, indem Sie ein Beispielpaket in das root-Profil installieren:

     # guix package -i hello

Das guix-Paket muss im Profil von root installiert bleiben, damit es nicht vom Müllsammler geholt wird, denn ohne den guix-Befehl wären Sie lahmgelegt. Anders gesagt, entfernen Sie guix nicht mit guix package -r guix.

Der Tarball zur Installation aus einer Binärdatei kann einfach durch Ausführung des folgenden Befehls im Guix-Quellbaum (re-)produziert und verifiziert werden:

     make guix-binary.SYSTEM.tar.xz

... which, in turn, runs:

     guix pack -s SYSTEM --localstatedir \
       --profile-name=current-guix guix

Siehe Aufruf von guix pack für weitere Informationen zu diesem praktischen Werkzeug.

Voraussetzungen
===============

Dieser Abschnitt listet Voraussetzungen auf, um Guix aus seinem Quellcode zu erstellen. Der Erstellungsprozess für Guix ist derselbe wie für andere GNU-Software und wird hier nicht beschrieben. Bitte lesen Sie die Dateien README und INSTALL im Guix-Quellbaum, um weitere Details zu erfahren.

GNU Guix is available for download from its website at https://www.gnu.org/software/guix/.

GNU Guix hat folgende Pakete als Abhängigkeiten:

  * GNU Guile (http://gnu.org/software/guile/), version 2.2.x;

  * Guile-Gcrypt (https://notabug.org/cwebber/guile-gcrypt), Version 0.1.0 oder neuer,

  * GnuTLS (http://gnutls.org/), im Speziellen dessen Bindungen für Guile (see how to install the GnuTLS bindings for Guile (GnuTLS-Guile)),

  * Guile-SQLite3 (https://notabug.org/guile-sqlite3/guile-sqlite3), Version 0.1.0 oder neuer,

  * Guile-Git (https://gitlab.com/guile-git/guile-git), vom August 2017 oder neuer,

  * Guile-JSON (https://savannah.nongnu.org/projects/guile-json/);

  * zlib (http://zlib.net),

  * GNU Make (http://www.gnu.org/software/make/).

Folgende Abhängigkeiten sind optional:

  * Unterstützung für das Auslagern von Erstellungen (see Auslagern des Daemons einrichten) und guix copy (see Aufruf von guix copy) hängt von Guile-SSH (https://github.com/artyom-poptsov/guile-ssh), Version 0.10.2 oder neuer, ab.

  * Wenn libbz2 (http://www.bzip.org) verfügbar ist, kann guix-daemon damit Erstellungsprotokolle komprimieren.

Sofern nicht --disable-daemon beim Aufruf von configure übergeben wurde, benötigen Sie auch folgende Pakete:

  * GNU libgcrypt (http://gnupg.org/),

  * SQLite 3 (http://sqlite.org),

  * GCC's g++ (http://gcc.gnu.org) mit Unterstützung für den C++11-Standard.

Sollten Sie Guix auf einem System konfigurieren, auf dem Guix bereits installiert ist, dann stellen Sie sicher, dasselbe Zustandsverzeichnis wie für die bestehende Installation zu verwenden. Benutzen Sie dazu die Befehlszeilenoption --localstatedir des configure-Skripts (see localstatedir (GNU Coding Standards)). Das configure-Skript schützt vor ungewollter Fehlkonfiguration der LOCALSTATEDIR, damit sie nicht versehentlich Ihren Store verfälschen (see Der Store).

Wenn eine funktionierende Installation of the Nix package manager (http://nixos.org/nix/) verfügbar ist, können Sie Guix stattdessen mit --disable-daemon konfigurieren. In diesem Fall ersetzt Nix die drei oben genannten Abhängigkeiten.

Guix ist mit Nix kompatibel, daher ist es möglich, denselben Store für beide zu verwenden. Dazu müssen Sie an configure nicht nur denselben Wert für --with-store-dir übergeben, sondern auch denselben Wert für --localstatedir. Letzterer ist deswegen essenziell, weil er unter Anderem angibt, wo die Datenbank liegt, in der sich die Metainformationen über den Store befinden. Für Nix sind die Werte standardmäßig --with-store-dir=/nix/store und --localstatedir=/nix/var. Beachten Sie, dass --disable-daemon nicht erforderlich ist, wenn Sie die Absicht haben, den Store mit Nix zu teilen.

Die Testsuite laufen lassen
===========================

Nachdem configure und make erfolgreich durchgelaufen sind, ist es ratsam, den Testkatalog auszuführen. Er kann dabei helfen, Probleme mit der Einrichtung oder Systemumgebung zu finden, oder auch Probleme in Guix selbst — und Testfehler zu melden ist eine wirklich gute Art und Weise, bei der Verbesserung von Guix mitzuhelfen. Um den Testkatalog auszuführen, geben Sie Folgendes ein:

     make check

Testfälle können parallel ausgeführt werden. Sie können die Befehlszeiltenoption -j von GNU make benutzen, damit es schneller geht. Der erste Durchlauf kann auf neuen Maschinen ein paar Minuten dauern, nachfolgende Ausführungen werden schneller sein, weil der für die Tests erstellte Store schon einige Dinge zwischengespeichert haben wird.

Es ist auch möglich, eine Teilmenge der Tests laufen zu lassen, indem Sie die TESTS-Variable des Makefiles ähnlich wie in diesem Beispiel definieren:

     make check TESTS="tests/store.scm tests/cpio.scm"

Standardmäßig werden Testergebnisse pro Datei angezeigt. Um die Details jedes einzelnen Testfalls zu sehen, können Sie wie in diesem Beispiel die SCM_LOG_DRIVER_FLAGS-Variable des Makefiles definieren:

     make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no"

Kommt es zum Fehlschlag, senden Sie bitte eine E-Mail an bug-guix@gnu.org und fügen Sie die Datei test-suite.log als Anhang bei. Bitte geben Sie dabei in Ihrer Nachricht die benutzte Version von Guix an sowie die Versionsnummern der Abhängigkeiten (see Voraussetzungen).

Guix also comes with a whole-system test suite that tests complete Guix System instances.  It can only run on systems where Guix is already installed, using:

     make check-system

Oder, auch hier, indem Sie TESTS definieren, um eine Teilmenge der auszuführenden Tests anzugeben:

     make check-system TESTS="basic mcron"

Diese Systemtests sind in den (gnu tests ...)-Modulen definiert. Sie funktionieren, indem Sie das getestete Betriebssystem mitsamt schlichter Instrumentierung in einer virtuellen Maschine (VM) ausführen. Die Tests können aufwendige Berechnungen durchführen oder sie günstig umgehen, je nachdem, ob für ihre Abhängigkeiten Substitute zur Verfügung stehen (see Substitute). Manche von ihnen nehmen viel Speicherplatz in Anspruch, um die VM-Abbilder zu speichern.

Auch hier gilt: Falls Testfehler auftreten, senden Sie bitte alle Details an bug-guix@gnu.org.

Den Daemon einrichten
=====================

Operationen wie das Erstellen eines Pakets oder Laufenlassen des Müllsammlers werden alle durch einen spezialisierten Prozess durchgeführt, den Erstellungs-Daemon, im Auftrag seiner Kunden (den Clients). Nur der Daemon darf auf den Store und seine zugehörige Datenbank zugreifen. Daher wird jede den Store verändernde Operation durch den Daemon durchgeführt. Zum Beispiel kommunizieren Befehlszeilenwerkzeuge wie guix package und guix build mit dem Daemon (mittels entfernter Prozeduraufrufe), um ihm Anweisungen zu geben, was er tun soll.

Folgende Abschnitte beschreiben, wie Sie die Umgebung des Erstellungs-Daemons ausstatten sollten. Siehe auch Substitute für Informationen darüber, wie Sie es dem Daemon ermöglichen, vorerstellte Binärdateien herunterzuladen.

Einrichten der Erstellungsumgebung
----------------------------------

In einem normalen Mehrbenutzersystem werden Guix und sein Daemon — das Programm guix-daemon — vom Systemadministrator installiert; /gnu/store gehört root und guix-daemon läuft als root. Nicht mit erweiterten Rechten ausgestattete Nutzer können Guix-Werkzeuge benutzen, um Pakete zu erstellen oder anderweitig auf den Store zuzugreifen, und der Daemon wird dies für sie erledigen und dabei sicherstellen, dass der Store in einem konsistenten Zustand verbleibt und sich die Nutzer erstellte Pakete teilen.

Wenn guix-daemon als Administratornutzer root läuft, wollen Sie aber vielleicht dennoch nicht, dass Paketerstellungsprozesse auch als root ablaufen, aus offensichtlichen Sicherheitsgründen. Um dies zu vermeiden, sollte ein besonderer Pool aus Erstellungsbenutzern geschaffen werden, damit vom Daemon gestartete Erstellungsprozesse ihn benutzen. Diese Erstellungsbenutzer müssen weder eine Shell noch ein Persönliches Verzeichnis zugewiesen bekommen, sie werden lediglich benutzt, wenn der Daemon root-Rechte in Erstellungsprozessen ablegt. Mehrere solche Benutzer zu haben, ermöglicht es dem Daemon, verschiedene Erstellungsprozessen unter verschiedenen Benutzeridentifikatoren (UIDs) zu starten, was garantiert, dass sie einander nicht stören — eine essenzielle Funktionalität, da Erstellungen als reine Funktionen angesehen werden (see Einführung).

Auf einem GNU/Linux-System kann ein Pool von Erstellungsbenutzern wie folgt erzeugt werden (mit Bash-Syntax und den Befehlen von shadow):

     # groupadd --system guixbuild
     # for i in `seq -w 1 10`;
       do
         useradd -g guixbuild -G guixbuild                  \
                 -d /var/empty -s `which nologin`           \
                 -c "Guix-Erstellungsbenutzer $i" --system  \
                 guixbuilder$i;
       done

Die Anzahl der Erstellungsbenutzer entscheidet, wieviele Erstellungsaufträge parallel ausgeführt werden können, wie es mit der Befehlszeilenoption --max-jobs vorgegeben werden kann (see --max-jobs). Um guix system vm und ähnliche Befehle nutzen zu können, müssen Sie die Erstellungsbenutzer unter Umständen zur kvm-Benutzergruppe hinzufügen, damit sie Zugriff auf /dev/kvm haben, mit -G guixbuild,kvm statt -G guixbuild (see Aufruf von guix system).

Das Programm guix-daemon kann mit dem folgenden Befehl als root gestartet werden (Wenn Ihre Maschine systemd als »init«-System verwendet, genügt es, die Datei PREFIX/lib/systemd/system/guix-daemon.service in /etc/systemd/system zu platzieren, damit guix-daemon automatisch gestartet wird. Ebenso können Sie, wenn Ihre Maschine Upstart als »init«-System benutzt, die Datei PREFIX/lib/upstart/system/guix-daemon.conf in /etc/init platzieren.):

     # guix-daemon --build-users-group=guixbuild

Auf diese Weise startet der Daemon Erstellungsprozesse in einem chroot als einer der guixbuilder-Benutzer. Auf GNU/Linux enthält die chroot-Umgebung standardmäßig nichts außer:

  * einem minimalen /dev-Verzeichnis, was größtenteils vom /dev des Wirtssystems unabhängig erstellt wurde (»Größtenteils«, denn obwohl die Menge an Dateien, die im /dev des chroots vorkommen, fest ist, können die meisten dieser Dateien nur dann erstellt werden, wenn das Wirtssystem sie auch hat.),

  * dem /proc-Verzeichnis, es zeigt nur die Prozesse des Containers, weil ein separater Namensraum für Prozess-IDs (PIDs) benutzt wird,

  * /etc/passwd mit einem Eintrag für den aktuellen Benutzer und einem Eintrag für den Benutzer nobody,

  * /etc/group mit einem Eintrag für die Gruppe des Benutzers,

  * /etc/hosts mit einem Eintrag, der localhost auf 127.0.0.1 abbildet,

  * einem /tmp-Verzeichnis mit Schreibrechten.

Sie können beeinflussen, in welchem Verzeichnis der Daemon Erstellungsbäume unterbringt, indem sie den Wert der Umgebungsvariablen TMPDIR ändern. Allerdings heißt innerhalb des chroots der Erstellungsbaum immer /tmp/guix-build-NAME.drv-0, wobei NAME der Ableitungsname ist — z.B. coreutils-8.24. Dadurch hat der Wert von TMPDIR keinen Einfluss auf die Erstellungsumgebung, wodurch Unterschiede vermieden werden, falls Erstellungsprozesse den Namen ihres Erstellungsbaumes einfangen.

Der Daemon befolgt außerdem den Wert der Umgebungsvariablen http_proxy für von ihm durchgeführte HTTP-Downloads, sei es für Ableitungen mit fester Ausgabe (see Ableitungen) oder für Substitute (see Substitute).

Wenn Sie Guix als ein Benutzer ohne erweiterte Rechte installieren, ist es dennoch möglich, guix-daemon auszuführen, sofern Sie --disable-chroot übergeben. Allerdings können Erstellungsprozesse dann nicht voneinander und vom Rest des Systems isoliert werden. Daher können sich Erstellungsprozesse gegenseitig stören und auf Programme, Bibliotheken und andere Dateien zugreifen, die dem restlichen System zur Verfügung stehen — was es deutlich schwerer macht, sie als reine Funktionen aufzufassen.

Nutzung der Auslagerungsfunktionalität
--------------------------------------

Wenn erwünscht kann der Erstellungs-Daemon Ableitungserstellungen auslagern auf andere Maschinen, auf denen Guix läuft, mit Hilfe des offload-»Build-Hooks« (Diese Funktionalität ist nur verfügbar, wenn Guile-SSH (https://github.com/artyom-poptsov/guile-ssh) vorhanden ist.). Wenn diese Funktionalität aktiviert ist, wird eine nutzerspezifizierte Liste von Erstellungsmaschinen aus /etc/guix/machines.scm gelesen. Wann immer eine Erstellung angefragt wird, zum Beispiel durch guix build, versucht der Daemon, sie an eine der Erstellungsmaschinen auszulagern, die die Einschränkungen der Ableitung erfüllen, insbesondere ihren Systemtyp — z.B. x86_64-linux. Fehlende Voraussetzungen für die Erstellung werden über SSH auf die Zielmaschine kopiert, welche dann mit der Erstellung weitermacht. Hat sie Erfolg damit, so werden die Ausgabe oder Ausgaben der Erstellung zurück auf die ursprüngliche Maschine kopiert.

Die Datei /etc/guix/machines.scm sieht normalerweise so aus:

     (list (build-machine
             (name "eightysix.example.org")
             (system "x86_64-linux")
             (host-key "ssh-ed25519 AAAAC3Nza...")
             (user "bob")
             (speed 2.))     ;unglaublich schnell!

           (build-machine
             (name "meeps.example.org")
             (system "mips64el-linux")
             (host-key "ssh-rsa AAAAB3Nza...")
             (user "alice")
             (private-key
              (string-append (getenv "HOME")
                             "/.ssh/identität-für-guix"))))

Im obigen Beispiel geben wir eine Liste mit zwei Erstellungsmaschinen vor, eine für die x86_64-Architektur und eine für die mips64el-Architektur.

Tatsächlich ist diese Datei — wenig überraschend! — eine Scheme-Datei, die ausgewertet wird, wenn der offload-Hook gestartet wird. Der Wert, den sie zurückliefert, muss eine Liste von build-machine-Objekten sein. Obwohl dieses Beispiel eine feste Liste von Erstellungsmaschinen zeigt, könnte man auch auf die Idee kommen, etwa mit DNS-SD eine Liste möglicher im lokalen Netzwerk entdeckter Erstellungsmaschinen zu liefern (see Guile-Avahi (Using Avahi in Guile Scheme Programs)). Der Datentyp build-machine wird im Folgenden weiter ausgeführt.

 -- Datentyp: build-machine
     Dieser Datentyp repräsentiert Erstellungsmaschinen, an die der Daemon Erstellungen auslagern darf. Die wichtigen Felder sind:

     name
          Der Hostname (d.h. der Rechnername) der entfernten Maschine.

     system
          Der Systemtyp der entfernten Maschine — z.B. "x86_64-linux".

     user
          Das Benutzerkonto, mit dem eine Verbindung zur entfernten Maschine über SSH aufgebaut werden soll. Beachten Sie, dass das SSH-Schlüsselpaar nicht durch eine Passphrase geschützt sein darf, damit nicht-interaktive Anmeldungen möglich sind.

     host-key
          Dies muss der öffentliche SSH-Host-Schlüssel der Maschine im OpenSSH-Format sein. Er wird benutzt, um die Identität der Maschine zu prüfen, wenn wir uns mit ihr verbinden. Er ist eine lange Zeichenkette, die ungefähr so aussieht:

               ssh-ed25519 AAAAC3NzaC...mde+UhL hint@example.org

          Wenn auf der Maschine der OpenSSH-Daemon, sshd, läuft, ist der Host-Schlüssel in einer Datei wie /etc/ssh/ssh_host_ed25519_key.pub zu finden.

          Wenn auf der Maschine der SSH-Daemon von GNU lsh, nämlich lshd, läuft, befindet sich der Host-Schlüssel in /etc/lsh/host-key.pub oder einer ähnlichen Datei. Er kann ins OpenSSH-Format umgewandelt werden durch lsh-export-key (see Converting keys (LSH Manual)):

               $ lsh-export-key --openssh < /etc/lsh/host-key.pub
               ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV...

     Eine Reihe optionaler Felder kann festgelegt werden:

     port (Vorgabe: 22)
          Portnummer des SSH-Servers auf der Maschine.

     private-key (Vorgabe: ~root/.ssh/id_rsa)
          Die Datei mit dem privaten SSH-Schlüssel, der beim Verbinden zur Maschine genutzt werden soll, im OpenSSH-Format. Dieser Schlüssel darf nicht mit einer Passphrase geschützt sein.

          Beachten Sie, dass als Vorgabewert der private Schlüssel des root-Benutzers genommen wird. Vergewissern Sie sich, dass er existiert, wenn Sie die Standardeinstellung verwenden.

     compression (Vorgabe: "zlib@openssh.com,zlib")
     compression-level (Vorgabe: 3)
          Die Kompressionsmethoden auf SSH-Ebene und das angefragte Kompressionsniveau.

          Beachten Sie, dass Auslagerungen SSH-Kompression benötigen, um beim Übertragen von Dateien an Erstellungsmaschinen und zurück weniger Bandbreite zu benutzen.

     daemon-socket (Vorgabe: "/var/guix/daemon-socket/socket")
          Dateiname des Unix-Sockets, auf dem guix-daemon auf der Maschine lauscht.

     parallel-builds (Vorgabe: 1)
          Die Anzahl der Erstellungen, die auf der Maschine parallel ausgeführt werden können.

     speed (Vorgabe: 1.0)
          Ein »relativer Geschwindigkeitsfaktor«. Der Auslagerungsplaner gibt tendenziell Maschinen mit höherem Geschwindigkeitsfaktor den Vorrang.

     features (Vorgabe: '())
          Eine Liste von Zeichenketten, die besondere von der Maschine unterstützte Funktionalitäten bezeichnen. Ein Beispiel ist "kvm" für Maschinen, die über die KVM-Linux-Module zusammen mit entsprechender Hardware-Unterstützung verfügen. Ableitungen können Funktionalitäten dem Namen nach anfragen und werden dann auf passenden Erstellungsmaschinen eingeplant.

The guix command must be in the search path on the build machines.  You can check whether this is the case by running:

     ssh build-machine guix repl --version

Es gibt noch eine weitere Sache zu tun, sobald machines.scm eingerichtet ist. Wie zuvor erklärt, werden beim Auslagern Dateien zwischen den Stores der Maschinen hin- und hergeschickt. Damit das funktioniert, müssen Sie als Erstes ein Schlüsselpaar auf jeder Maschine erzeugen, damit der Daemon signierte Archive mit den Dateien aus dem Store versenden kann (see Aufruf von guix archive):

     # guix archive --generate-key

Jede Erstellungsmaschine muss den Schlüssel der Hauptmaschine autorisieren, damit diese Store-Objekte von der Hauptmaschine empfangen kann:

     # guix archive --authorize < öffentlicher-schlüssel-hauptmaschine.txt

Andersherum muss auch die Hauptmaschine den jeweiligen Schlüssel jeder Erstellungsmaschine autorisieren.

Der ganze Umstand mit den Schlüsseln soll ausdrücken, dass sich Haupt- und Erstellungsmaschinen paarweise gegenseitig vertrauen. Konkret kann der Erstellungs-Daemon auf der Hauptmaschine die Echtheit von den Erstellungsmaschinen empfangener Dateien gewährleisten (und umgekehrt), und auch dass sie nicht sabotiert wurden und mit einem autorisierten Schlüssel signiert wurden.

Um zu testen, ob Ihr System funktioniert, führen Sie diesen Befehl auf der Hauptmaschine aus:

     # guix offload test

Dadurch wird versucht, zu jeder Erstellungsmaschine eine Verbindung herzustellen, die in /etc/guix/machines.scm angegeben wurde, sichergestellt, dass auf jeder Guile und die Guix-Module nutzbar sind, und jeweils versucht, etwas auf die Erstellungsmaschine zu exportieren und von dort zu imporieren. Dabei auftretende Fehler werden gemeldet.

Wenn Sie stattdessen eine andere Maschinendatei verwenden möchten, geben Sie diese einfach auf der Befehlszeile an:

     # guix offload test maschinen-qualif.scm

Letztendlich können Sie hiermit nur die Teilmenge der Maschinen testen, deren Name zu einem regulären Ausdruck passt:

     # guix offload test maschinen.scm '\.gnu\.org$'

Um die momentane Auslastung aller Erstellungs-Hosts anzuzeigen, führen Sie diesen Befehl auf dem Hauptknoten aus:

     # guix offload status

SELinux-Unterstützung
---------------------

Guix includes an SELinux policy file at etc/guix-daemon.cil that can be installed on a system where SELinux is enabled, in order to label Guix files and to specify the expected behavior of the daemon.  Since Guix System does not provide an SELinux base policy, the daemon policy cannot be used on Guix System.

Installieren der SELinux-Policy
...............................

Um die Richtlinie (Policy) zu installieren, führen Sie folgenden Befehl mit Administratorrechten aus:

     semodule -i etc/guix-daemon.cil

Kennzeichnen Sie dann das Dateisystem neu mit restorecon oder einem anderen, von Ihrem System angebotenen Mechanismus.

Sobald die Richtlinie installiert ist, das Dateisystem neu gekennzeichnet wurde und der Daemon neugestartet wurde, sollte er im Kontext guix_daemon_t laufen. Sie können dies mit dem folgenden Befehl nachprüfen:

     ps -Zax | grep guix-daemon

Beobachten Sie die Protokolldateien von SELinux, wenn Sie einen Befehl wie guix build hello ausführen, um sich zu überzeugen, dass SELinux alle notwendigen Operationen gestattet.

Einschränkungen
...............

Diese Richtlinie ist nicht perfekt. Im Folgenden finden Sie eine Liste von Einschränkungen oder merkwürdigen Verhaltensweisen, die bedacht werden sollten, wenn man die mitgelieferte SELinux-Richtlinie für den Guix-Daemon einspielt.

 1. guix_daemon_socket_t wird nicht wirklich benutzt. Keine der Socket-Operationen benutzt Kontexte, die irgendetwas mit guix_daemon_socket_t zu tun haben. Es schadet nicht, diese ungenutzte Kennzeichnung zu haben, aber es wäre besser, für die Kennzeichnung auch Socket-Regeln festzulegen.

 2. guix gc kann nicht auf beliebige Verknüpfungen zu Profilen zugreifen. Die Kennzeichnung des Ziels einer symbolischen Verknüpfung ist notwendigerweise unabhängig von der Dateikennzeichnung der Verknüpfung. Obwohl alle Profile unter $localstatedir gekennzeichnet sind, erben die Verknüpfungen auf diese Profile die Kennzeichnung desjenigen Verzeichnisses, in dem sie sich befinden. Für Verknüpfungen im Persönlichen Verzeichnis des Benutzers ist das user_home_t, aber Verknüpfungen aus dem Persönlichen Verzeichnis des Administratornutzers, oder /tmp, oder das Arbeitsverzeichnis des HTTP-Servers, etc., funktioniert das nicht. guix gc würde es nicht gestattet, diese Verknüpfungen auszulesen oder zu verfolgen.

 3. Die vom Daemon gebotene Funktionalität, auf TCP-Verbindungen zu lauschen, könnte nicht mehr funktionieren. Dies könnte zusätzliche Regeln brauchen, weil SELinux Netzwerk-Sockets anders behandelt als Dateien.

 4. Derzeit wird allen Dateien mit einem Namen, der zum regulären Ausdruck /gnu/store/.+-(guix-.+|profile)/bin/guix-daemon passt, die Kennzeichnung guix_daemon_exec_t zugewiesen, wodurch jede beliebige Datei mit diesem Namen in irgendeinem Profil gestattet wäre, in der Domäne guix_daemon_t ausgeführt zu werden. Das ist nicht ideal. Ein Angreifer könnte ein Paket erstellen, dass solch eine ausführbare Datei enthält, und den Nutzer überzeugen, es zu installieren und auszuführen. Dadurch käme es in die Domäne guix_daemon_t. Ab diesem Punkt könnte SELinux nicht mehr verhindern, dass es auf Dateien zugreift, auf die Prozesse in dieser Domäne zugreifen dürfen.

     Wir könnten zum Zeitpunkt der Installation eine wesentlich restriktivere Richtlinie generieren, für die nur genau derselbe Dateiname des gerade installierten guix-daemon-Programms als guix_daemon_exec_t gekennzeichnet würde, statt einen vieles umfassenden regulären Ausdruck zu benutzen. Aber dann müsste der Administratornutzer zum Zeitpunkt der Installation jedes Mal die Richtlinie installieren oder aktualisieren müssen, sobald das Guix-Paket aktualisiert wird, dass das tatsächlich in Benutzung befindliche guix-daemon-Programm enthält.

Aufruf von guix-daemon
======================

Das Programm guix-daemon implementiert alle Funktionalitäten, um auf den Store zuzugreifen. Dazu gehört das Starten von Erstellungsprozessen, das Ausführen des Müllsammlers, das Abfragen, ob ein Erstellungsergebnis verfügbar ist, etc. Normalerweise wird er so als Administratornutzer (root) gestartet:

     # guix-daemon --build-users-group=guixbuild

Details, wie Sie ihn einrichten, finden Sie im Abschnitt see Den Daemon einrichten.

Standardmäßig führt guix-daemon Erstellungsprozesse mit unterschiedlichen UIDs aus, die aus der Erstellungsgruppe stammen, deren Name mit --build-users-group übergeben wurde. Außerdem läuft jeder Erstellungsprozess in einer chroot-Umgebung, die nur die Teilmenge des Stores enthält, von der der Erstellungsprozess abhängt, entsprechend seiner Ableitung (see derivation), und ein paar bestimmte Systemverzeichnisse, darunter standardmäßig auch /dev und /dev/pts. Zudem ist die Erstellungsumgebung auf GNU/Linux ein Container: Nicht nur hat er seinen eigenen Dateisystembaum, er hat auch einen separaten Namensraum zum Einhängen von Dateisystemen, seinen eigenen Namensraum für PIDs, für Netzwerke, etc. Dies hilft dabei, reproduzierbare Erstellungen zu garantieren (see Funktionalitäten).

Wenn der Daemon im Auftrag des Nutzers eine Erstellung durchführt, erzeugt er ein Erstellungsverzeichnis, entweder in /tmp oder im Verzeichnis, das durch die Umgebungsvariable TMPDIR angegeben wurde. Dieses Verzeichnis wird mit dem Container geteilt, solange die Erstellung noch läuft, allerdings trägt es im Container stattdessen immer den Namen »/tmp/guix-build-NAME.drv-0«.

Nach Abschluss der Erstellung wird das Erstellungsverzeichnis automatisch entfernt, außer wenn die Erstellung fehlgeschlagen ist und der Client --keep-failed angegeben hat (see --keep-failed).

Der Daemon lauscht auf Verbindungen und erstellt jeweils einen Unterprozess für jede von einem Client begonnene Sitzung (d.h. von einem der guix-Unterbefehle.) Der Befehl guix processes zeigt Ihnen eine Übersicht solcher Systemaktivitäten; damit werden Ihnen alle aktiven Sitzungen und Clients gezeigt. Weitere Informationen finden Sie unter see Aufruf von guix processes.

Die folgenden Befehlszeilenoptionen werden unterstützt:

--build-users-group=GRUPPE
     Verwende die Benutzerkonten aus der GRUPPE, um Erstellungsprozesse auszuführen (see build users).

--no-substitutes
     Benutze keine Substitute für Erstellungsergebnisse. Das heißt, dass alle Objekte lokal erstellt werden müssen, und kein Herunterladen von vorab erstellten Binärdateien erlaubt ist (see Substitute).

     Wenn der Daemon mit --no-substitutes ausgeführt wird, können Clients trotzdem Substitute explizit aktivieren über den entfernten Prozeduraufruf set-build-options (see Der Store).

--substitute-urls=URLS
     Consider URLS the default whitespace-separated list of substitute source URLs.  When this option is omitted, https://ci.guix.de.info is used.

     Das hat zur Folge, dass Substitute von den URLS heruntergeladen werden können, solange sie mit einer Signatur versehen sind, der vertraut wird (see Substitute).

--no-build-hook
     Den »Build-Hook« nicht benutzen.

     »Build-Hook« ist der Name eines Hilfsprogramms, das der Daemon starten kann und an das er Erstellungsanfragen übermittelt. Durch diesen Mechanismus können Erstellungen an andere Maschinen ausgelagert werden (see Auslagern des Daemons einrichten).

--cache-failures
     Fehler bei der Erstellung zwischenspeichern. Normalerweise werden nur erfolgreiche Erstellungen gespeichert.

     Wenn diese Befehlszeilenoption benutzt wird, kann guix gc --list-failures benutzt werden, um die Menge an Store-Objekten abzufragen, die als Fehlschläge markiert sind; guix gc --clear-failures entfernt Store-Objekte aus der Menge zwischengespeicherter Fehlschläge. See Aufruf von guix gc.

--cores=N
-c N
     N CPU-Kerne zum Erstellen jeder Ableitung benutzen; 0 heißt, so viele wie verfügbar sind.

     Der Vorgabewert ist 0, jeder Client kann jedoch eine abweichende Anzahl vorgeben, zum Beispiel mit der Befehlszeilenoption --cores von guix build (see Aufruf von guix build).

     Dadurch wird die Umgebungsvariable NIX_BUILD_CORES im Erstellungsprozess definiert, welcher sie benutzen kann, um intern parallele Ausführungen zuzulassen — zum Beispiel durch Nutzung von make -j$NIX_BUILD_CORES.

--max-jobs=N
-M N
     Höchstenss N Erstellungsaufträge parallel bearbeiten. Der Vorgabewert liegt bei 1. Wird er auf 0 gesetzt, werden keine Erstellungen lokal durchgeführt, stattdessen lagert der Daemon sie nur aus (see Auslagern des Daemons einrichten) oder sie schlagen einfach fehl.

--max-silent-time=SEKUNDEN
     Wenn der Erstellungs- oder Substitutionsprozess länger als SEKUNDEN-lang keine Ausgabe erzeugt, wird er abgebrochen und ein Fehler beim Erstellen gemeldet.

     Der Vorgabewert ist 0, was bedeutet, dass es keine Zeitbeschränkung gibt.

     Clients können einen anderen Wert als den hier angegebenen verwenden lassen (see --max-silent-time).

--timeout=SEKUNDEN
     Entsprechend wird hier der Erstellungs- oder Substitutionsprozess abgebrochen und als Fehlschlag gemeldet, wenn er mehr als SEKUNDEN-lang dauert.

     Der Vorgabewert ist 0, was bedeutet, dass es keine Zeitbeschränkung gibt.

     Clients können einen anderen Wert verwenden lassen (see --timeout).

--rounds=N
     Jede Ableitung N-mal hintereinander erstellen und einen Fehler melden, wenn nacheinander ausgewertete Erstellungsergebnisse nicht Bit für Bit identisch sind. Beachten Sie, dass Clients wie guix build einen anderen Wert verwenden lassen können (see Aufruf von guix build).

     Wenn dies zusammen mit --keep-failed benutzt wird, bleiben die sich unterscheidenden Ausgaben im Store unter dem Namen /gnu/store/...-check. Dadurch können Unterschiede zwischen den beiden Ergebnissen leicht erkannt werden.

--debug
     Informationen zur Fehlersuche ausgeben.

     Dies ist nützlich, um Probleme beim Starten des Daemons nachzuvollziehen; Clients könn aber auch ein abweichenden Wert verwenden lassen, zum Beispiel mit der Befehlszeilenoption --verbosity von guix build (see Aufruf von guix build).

--chroot-directory=VERZEICHNIS
     Füge das VERZEICHNIS zum chroot von Erstellungen hinzu.

     Dadurch kann sich das Ergebnis von Erstellungsprozessen ändern — zum Beispiel, wenn diese optionale Abhängigkeiten aus dem VERZEICHNIS verwenden, wenn sie verfügbar sind, und nicht, wenn es fehlt. Deshalb ist es nicht empfohlen, dass Sie diese Befehlszeilenoption verwenden, besser sollten Sie dafür sorgen, dass jede Ableitung alle von ihr benötigten Eingabgen deklariert.

--disable-chroot
     Erstellungen ohne chroot durchführen.

     Diese Befehlszeilenoption zu benutzen, wird nicht empfohlen, denn auch dadurch bekämen Erstellungsprozesse Zugriff auf nicht deklarierte Abhängigkeiten. Sie ist allerdings unvermeidlich, wenn guix-daemon auf einem Benutzerkonto ohne ausreichende Berechtigungen ausgeführt wird.

--log-compression=TYP
     Erstellungsprotokolle werden entsprechend dem TYP komprimiert, der entweder gzip, bzip2 oder none (für keine Kompression) sein muss.

     Sofern nicht --lose-logs angegeben wurde, werden alle Erstellungsprotokolle in der LOCALSTATEDIR gespeichert. Um Platz zu sparen, komprimiert sie der Daemon standardmäßig automatisch mit bzip2.

--disable-deduplication
     Automatische Dateien-»Deduplizierung« im Store ausschalten.

     Standardmäßig werden zum Store hinzugefügte Objekte automatisch »dedupliziert«: Wenn eine neue Datei mit einer anderen im Store übereinstimmt, wird die neue Datei stattdessen als harte Verknüpfung auf die andere Datei angelegt. Dies reduziert den Speicherverbrauch auf der Platte merklich, jedoch steigt andererseits die Auslastung bei der Ein-/Ausgabe im Erstellungsprozess geringfügig. Durch diese Option wird keine solche Optimierung durchgeführt.

--gc-keep-outputs[=yes|no]
     Gibt an, ob der Müllsammler (Garbage Collector, GC) die Ausgaben lebendiger Ableitungen behalten muss (»yes«) oder nicht (»no«).

     Für »yes« behält der Müllsammler die Ausgaben aller lebendigen Ableitungen im Store — die .drv-Dateien. Der Vorgabewert ist aber »no«, so dass Ableitungsausgaben nur vorgehalten werden, wenn sie von einer Müllsammlerwurzel aus erreichbar sind. Siehe den Abschnitt see Aufruf von guix gc für weitere Informationen zu Müllsammlerwurzeln.

--gc-keep-derivations[=yes|no]
     Gibt an, ob der Müllsammler (GC) Ableitungen behalten muss (»yes«), wenn sie lebendige Ausgaben haben, oder nicht (»no«).

     Für »yes«, den Vorgabewert, behält der Müllsammler Ableitungen — z.B. .drv-Dateien —, solange zumindest eine ihrer Ausgaben lebendig ist. Dadurch können Nutzer den Ursprung der Dateien in ihrem Store nachvollziehen. Setzt man den Wert auf »no«, wird ein bisschen weniger Speicher auf der Platte verbraucht.

     Auf diese Weise überträgt sich, wenn --gc-keep-derivations auf »yes« steht, die Lebendigkeit von Ausgaben auf Ableitungen, und wenn --gc-keep-outputs auf »yes« steht, die Lebendigkeit von Ableitungen auf Ausgaben. Stehen beide auf »yes«, bleiben so alle Erstellungsvoraussetzungen wie Quelldateien, Compiler, Bibliotheken und andere Erstellungswerkzeuge lebendiger Objekte im Store erhalten, ob sie von einer Müllsammlerwurzel aus erreichbar sind oder nicht. Entwickler können sich so erneute Erstellungen oder erneutes Herunterladen sparen.

--impersonate-linux-2.6
     Auf Linux-basierten Systemen wird hiermit vorgetäuscht, dass es sich um Linux 2.6 handeln würde, indem der Kernel für einen uname-Systemaufruf als Version der Veröffentlichung mit 2.6 antwortet.

     Dies kann hilfreich sein, um Programme zu erstellen, die (normalerweise zu Unrecht) von der Kernel-Versionsnummer abhängen.

--lose-logs
     Keine Protokolle der Erstellungen vorhalten. Normalerweise würden solche in LOCALSTATEDIR/guix/log gespeichert.

--system=SYSTEM
     Verwende SYSTEM als aktuellen Systemtyp. Standardmäßig ist dies das Paar aus Befehlssatz und Kernel, welches beim Aufruf von configure erkannt wurde, wie zum Beispiel x86_64-linux.

--listen=ENDPUNKT
     Lausche am ENDPUNKT auf Verbindungen. Dabei wird der ENDPUNKT als Dateiname eines Unix-Sockets verstanden, wenn er mit einem / (Schrägstrich) beginnt. Andernfalls wird der ENDPUNKT als Hostname (d.h. Rechnername) oder als Hostname-Port-Paar verstanden, auf dem gelauscht wird. Hier sind ein paar Beispiele:

     --listen=/gnu/var/daemon
          Lausche auf Verbindungen am Unix-Socket /gnu/var/daemon, falls nötig wird er dazu erstellt.

     --listen=localhost
          Lausche auf TCP-Verbindungen an der Netzwerkschnittstelle, die localhost entspricht, auf Port 44146.

     --listen=128.0.0.42:1234
          Lausche auf TCP-Verbindungen an der Netzwerkschnittstelle, die 128.0.0.42 entspricht, auf Port 1234.

     Diese Befehlszeilenoption kann mehrmals wiederholt werden. In diesem Fall akzeptiert guix-daemon Verbindungen auf allen angegebenen Endpunkten. Benutzer können bei Client-Befehlen angeben, mit welchem Endpunkt sie sich verbinden möchten, indem sie die Umgebungsvariable GUIX_DAEMON_SOCKET festlegen (see GUIX_DAEMON_SOCKET).

          Das Daemon-Protokoll ist weder authentifiziert noch verschlüsselt. Die Benutzung von --listen=HOST eignet sich für lokale Netzwerke, wie z.B. in Rechen-Clustern, wo sich nur solche Knoten mit dem Daemon verbinden, denen man vertraut. In Situationen, wo ein Fernzugriff auf den Daemon durchgeführt wird, empfehlen wir, über Unix-Sockets in Verbindung mit SSH zuzugreifen.

     Wird --listen nicht angegeben, lauscht guix-daemon auf Verbindungen auf dem Unix-Socket, der sich unter LOCALSTATEDIR/guix/daemon-socket/socket befindet.

Anwendungen einrichten
======================

When using Guix on top of GNU/Linux distribution other than Guix System---a so-called foreign distro---a few additional steps are needed to get everything in place.  Here are some of them.

Locales
-------

Über Guix installierte Pakete benutzen nicht die Daten zu Regions- und Spracheinstellungen (Locales) des Wirtssystems. Stattdessen müssen Sie erst eines der Locale-Pakete installieren, die für Guix verfügbar sind, und dann den Wert Ihrer Umgebungsvariablen GUIX_LOCPATH passend festlegen:

     $ guix package -i glibc-locales
     $ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale

Beachten Sie, dass das Paket glibc-locales Daten für alle von GNU libc unterstützten Locales enthält und deswegen um die 110 MiB wiegt. Alternativ gibt es auch glibc-utf8-locales, was kleiner, aber auf ein paar UTF-8-Locales beschränkt ist.

Die Variable GUIX_LOCPATH spielt eine ähnliche Rolle wie LOCPATH (see LOCPATH (The GNU C Library Reference Manual)). Es gibt jedoch zwei wichtige Unterschiede:

 1. GUIX_LOCPATH wird nur von der libc in Guix beachtet und nicht der von Fremddistributionen bereitgestellten libc. Mit GUIX_LOCPATH können Sie daher sicherstellen, dass die Programme der Fremddistribution keine inkompatiblen Locale-Daten von Guix laden.

 2. libc hängt an jeden GUIX_LOCPATH-Eintrag /X.Y an, wobei X.Y die Version von libc ist — z.B. 2.22. Sollte Ihr Guix-Profil eine Mischung aus Programmen enthalten, die an verschiedene libc-Versionen gebunden sind, wird jede nur die Locale-Daten im richtigen Format zu laden versuchen.

Das ist wichtig, weil das Locale-Datenformat verschiedener libc-Versionen inkompatibel sein könnte.

Name Service Switch
-------------------

Wenn Sie Guix auf einer Fremddistribution verwenden, empfehlen wir stärkstens, dass Sie den Name Service Cache Daemon der GNU-C-Bibliothek, nscd, laufen lassen, welcher auf dem Socket /var/run/nscd/socket lauschen sollte. Wenn Sie das nicht tun, könnten mit Guix installierte Anwendungen Probleme beim Auflösen von Hostnamen (d.h. Rechnernamen) oder Benutzerkonten haben, oder sogar abstürzen. Die nächsten Absätze erklären warum.

Die GNU-C-Bibliothek implementiert einen Name Service Switch (NSS), welcher einen erweiterbaren Mechanismus zur allgemeinen »Namensauflösung« darstellt: Hostnamensauflösung, Benutzerkonten und weiteres (see Name Service Switch (The GNU C Library Reference Manual)).

Für die Erweiterbarkeit unterstützt der NSS Plugins, welche neue Implementierungen zur Namensauflösung bieten: Zum Beispiel ermöglicht das Plugin nss-mdns die Namensauflösung für .local-Hostnamen, das Plugin nis gestattet die Auflösung von Benutzerkonten über den Network Information Service (NIS) und so weiter. Diese zusätzlichen »Auflösungsdienste« werden systemweit konfiguriert in /etc/nsswitch.conf und alle auf dem System laufenden Programme halten sich an diese Einstellungen (see NSS Configuration File (The GNU C Reference Manual)).

Wenn sie eine Namensauflösung durchführen — zum Beispiel, indem sie die getaddrinfo-Funktion in C aufrufen — versuchen die Anwendungen als Erstes, sich mit dem nscd zu verbinden; ist dies erfolgreich, führt nscd für sie die weiteren Namensauflösungen durch. Falls nscd nicht läuft, führen sie selbst die Namensauflösungen durch, indem sie die Namensauflösungsdienste in ihren eigenen Adressraum laden und ausführen. Diese Namensauflösungsdienste — die libnss_*.so-Dateien — werden mit dlopen geladen, aber sie kommen von der C-Bibliothek des Wirtssystems und nicht von der C-Bibliothek, mit der die Anwendung gebunden wurde (also der C-Bibliothek von Guix).

Und hier kommt es zum Problem: Wenn die Anwendung mit der C-Bibliothek von Guix (etwa glibc 2.24) gebunden wurde und die NSS-Plugins von einer anderen C-Bibliothek (etwa libnss_mdns.so für glibc 2.22) zu laden versucht, wird sie vermutlich abstürzen oder die Namensauflösungen werden unerwartet fehlschlagen.

Durch das Ausführen von nscd auf dem System wird, neben anderen Vorteilen, dieses Problem der binären Inkompatibilität vermieden, weil diese libnss_*.so-Dateien vom nscd-Prozess geladen werden, nicht in den Anwendungen selbst.

X11-Schriftarten
----------------

Die Mehrheit der grafischen Anwendungen benutzen Fontconfig zum Finden und Laden von Schriftarten und für die Darstellung im X11-Client. Im Paket fontconfig in Guix werden Schriftarten standardmäßig in $HOME/.guix-profile gesucht. Um es grafischen Anwendungen, die mit Guix installiert wurden, zu ermöglichen, Schriftarten anzuzeigen, müssen Sie die Schriftarten auch mit Guix installieren. Essenzielle Pakete für Schriftarten sind unter Anderem gs-fonts, font-dejavu und font-gnu-freefont-ttf.

Um auf Chinesisch, Japanisch oder Koreanisch verfassten Text in grafischen Anwendungen anzeigen zu können, möchten Sie vielleicht font-adobe-source-han-sans oder font-wqy-zenhei installieren. Ersteres hat mehrere Ausgaben, für jede Sprachfamilie eine (see Pakete mit mehreren Ausgaben.). Zum Beispiel installiert folgender Befehl Schriftarten für chinesische Sprachen:

     guix package -i font-adobe-source-han-sans:cn

Ältere Programme wie xterm benutzen kein Fontconfig, sondern X-Server-seitige Schriftartendarstellung. Solche Programme setzen voraus, dass der volle Name einer Schriftart mit XLFD (X Logical Font Description) angegeben wird, z.B. so:

     -*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1

Um solche vollen Namen für die in Ihrem Guix-Profil installierten TrueType-Schriftarten zu verwenden, müssen Sie den Pfad für Schriftarten (Font Path) des X-Servers anpassen:

     xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir))

Danach können Sie den Befehl xlsfonts ausführen (aus dem Paket xlsfonts), um sicherzustellen, dass dort Ihre TrueType-Schriftarten aufgeführt sind.

Nach der Installation der Schriftarten müssen Sie unter Umständen den Schriftarten-Zwischenspeicher (Font-Cache) erneuern, um diese in Anwendungen benutzen zu können. Gleiches gilt, wenn mit Guix installierte Anwendungen anscheinend keine Schriftarten finden können. Um das Erneuern des Font-Caches zu erzwingen, führen Sie fc-cache -f aus. Der Befehl fc-cache wird vom Paket fontconfig angeboten.

X.509-Zertifikate
-----------------

Das Paket nss-certs bietet X.509-Zertifikate, womit Programme die Identität von Web-Servern authentifizieren können, auf die über HTTPS zugegriffen wird.

Wenn Sie Guix auf einer Fremddistribution verwenden, können Sie dieses Paket installieren und die relevanten Umgebungsvariablen festlegen, damit Pakete wissen, wo sie Zertifikate finden. In see X.509-Zertifikate stehen genaue Informationen.

Emacs-Pakete
------------

Wenn Sie mit Guix Pakete für Emacs installieren, werden deren elisp-Dateien entweder in $HOME/.guix-profile/share/emacs/site-lisp/ oder in Unterverzeichnissen von $HOME/.guix-profile/share/emacs/site-lisp/guix.d/ gespeichert. Letzteres Verzeichnis gibt es, weil es Tausende von Emacs-Paketen gibt und sie alle im selben Verzeichnis zu speichern vielleicht nicht verlässlich funktioniert (wegen Namenskonflikten). Daher halten wir es für richtig, für jedes Paket ein anderes Verzeichnis zu benutzen. Das Emacs-Paketsystem organisiert die Dateistruktur ähnlich (see Package Files (The GNU Emacs Manual)).

Standardmäßig »weiß« Emacs (wenn er mit Guix installiert wurde), wo diese Pakete liegen, Sie müssen also nichts selbst konfigurieren. Wenn Sie aber aus irgendeinem Grund mit Guix installierte Pakete nicht automatisch laden lassen möchten, können Sie Emacs mit der Befehlszeilenoption --no-site-file starten (see Init File (The GNU Emacs Manual)).

GCC-Toolchain
-------------

Guix bietet individuelle Compiler-Pakete wie etwa gcc, aber wenn Sie einen vollständigen Satz an Werkzeugen zum Kompilieren und Binden von Quellcode brauchen, werden Sie eigentlich das Paket gcc-toolchain haben wollen. Das Paket bietet eine vollständige GCC-Toolchain für die Entwicklung mit C/C++, einschließlich GCC selbst, der GNU-C-Bibliothek (Header-Dateien und Binärdateien samt Symbolen zur Fehlersuche/Debugging in der debug-Ausgabe), Binutils und einen Wrapper für den Binder/Linker.

The wrapper's purpose is to inspect the -L and -l switches passed to the linker, add corresponding -rpath arguments, and invoke the actual linker with this new set of arguments.  You can instruct the wrapper to refuse to link against libraries not in the store by setting the GUIX_LD_WRAPPER_ALLOW_IMPURITIES environment variable to no.

Systeminstallation
******************

This section explains how to install Guix System on a machine.  Guix, as a package manager, can also be installed on top of a running GNU/Linux system, see Installation.

     Sie lesen diese Dokumentation mit einem Info-Betrachter. Details, wie Sie ihn bedienen, erfahren Sie, indem Sie die Eingabetaste (auch »Return« oder »Enter« genannt) auf folgender Verknüpfung drücken: see Info reader (Stand-alone GNU Info). Drücken Sie danach l, um hierher zurückzukommen.

     Führen Sie alternativ info info auf einer anderen Konsole (tty) aus, um dieses Handbuch offen zu lassen.

Einschränkungen
===============

As of version VERSION, Guix System is not production-ready.  It may contain bugs and lack important features.  Thus, if you are looking for a stable production system that respects your freedom as a computer user, a good solution at this point is to consider one of the more established GNU/Linux distributions (http://www.gnu.org/distros/free-distros.html).  We hope you can soon switch to the Guix System without fear, of course.  In the meantime, you can also keep using your distribution and try out the package manager on top of it (see Installation).

Bevor Sie mit der Installation fortfahren, beachten Sie die folgenden merklichen Einschränkungen der Version VERSION:

  * Für den Installationsprozess wird keine grafische Oberfläche mitgeliefert und er erfordert Erfahrung mit GNU/Linux (siehe die folgenden Unterabschnitte, um ein Gefühl dafür zu bekommen, was wir damit meinen).

  * Der Logical Volume Manager (LVM) wird nicht unterstützt.

  * Immer mehr Systemdienste sind verfügbar (see Dienste), aber manche könnten noch fehlen.

  * More than 8,500 packages are available, but you might occasionally find that a useful package is missing.

  * GNOME, Xfce, LXDE und Enlightenment stehen zur Verfügung (see Desktop-Dienste), ebenso eine Reihe von X11-Fensterverwaltungsprogrammen. Manche grafischen Anwendungen könnten aber noch fehlen, ebenso fehlt KDE.

Sie wurden gewarnt! Dies soll allerdings nicht nur ein Hinweis sein, sondern auch als Einladung aufgefasst werden, uns Fehler (und Erfolgsgeschichten!) zu melden und bei uns mitzumachen, um Guix zu verbessern. Siehe den Abschnitt see Mitwirken.

Hardware-Überlegungen
=====================

GNU Guix focuses on respecting the user's computing freedom.  It builds around the kernel Linux-libre, which means that only hardware for which free software drivers and firmware exist is supported.  Nowadays, a wide range of off-the-shelf hardware is supported on GNU/Linux-libre---from keyboards to graphics cards to scanners and Ethernet controllers.  Unfortunately, there are still areas where hardware vendors deny users control over their own computing, and such hardware is not supported on Guix System.

One of the main areas where free drivers or firmware are lacking is WiFi devices.  WiFi devices known to work include those using Atheros chips (AR9271 and AR7010), which corresponds to the ath9k Linux-libre driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core Revision 5), which corresponds to the b43-open Linux-libre driver. Free firmware exists for both and is available out-of-the-box on Guix System, as part of %BASE-FIRMWARE (see firmware).

Die Free Software Foundation (https://www.fsf.org/) betreibt Respects Your Freedom (https://www.fsf.org/ryf) (RYF), ein Zertifizierungsprogramm für Hardware-Produkte, die Ihre Freiheit und Privatsphäre respektieren und sicherstellen, dass Sie die Kontrolle über Ihr Gerät haben. Wir ermutigen Sie dazu, die Liste RYF-zertifizierter Geräte zu beachten.

Eine weitere nützliche Ressource ist die Website H-Node (https://www.h-node.org/). Dort steht ein Katalog von Hardware-Geräten mit Informationen darüber, wie gut sie von GNU/Linux unterstützt werden.

Installation von USB-Stick oder DVD
===================================

Sie können ein ISO-9660-Installationsabbild von https://alpha.gnu.org/gnu/guix/guixsd-install-VERSION.SYSTEM.iso.xz herunterladen, dass Sie auf einen USB-Stick aufspielen oder auf eine DVD brennen können, wobei Sie für SYSTEM eines der folgenden schreiben müssen:

x86_64-linux
     für ein GNU/Linux-System auf Intel/AMD-kompatiblen 64-Bit-Prozessoren,

i686-linux
     für ein 32-Bit-GNU/Linux-System auf Intel-kompatiblen Prozessoren.

Laden Sie auch die entsprechende .sig-Datei herunter und verifizieren Sie damit die Authentizität Ihres Abbilds, indem Sie diese Befehle eingeben:

     $ wget https://alpha.gnu.org/gnu/guix/guixsd-install-VERSION.SYSTEM.iso.xz.sig
     $ gpg --verify guixsd-install-VERSION.SYSTEM.iso.xz.sig

Falls dieser Befehl fehlschlägt, weil Sie nicht über den nötigen öffentlichen Schlüssel verfügen, können Sie ihn mit diesem Befehl importieren:

     $ gpg --keyserver pool.sks-keyservers.net \
           --recv-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5

und den Befehl gpg --verify erneut ausführen.

Dieses Abbild enthält die Werkzeuge, die Sie zur Installation brauchen. Es ist dafür gedacht,  so wie es ist auf einen hinreichend großen USB-Stick oder eine DVD kopiert zu werden.

Kopieren auf einen USB-Stick
----------------------------

Um das Abbild auf einen USB-Stick zu kopieren, führen Sie folgende Schritte durch:

 1. Entpacken Sie das Abbild mit dem xz-Befehl:

          xz -d guixsd-install-VERSION.SYSTEM.iso.xz

 2. Stecken Sie einen USB-Stick in Ihren Rechner ein, der mindestens 1 GiB groß ist, und bestimmen Sie seinen Gerätenamen. Ist der Gerätename des USB-Sticks /dev/sdX, dann kopieren Sie das Abbild mit dem Befehl:

          dd if=guixsd-install-VERSION.SYSTEM.iso of=/dev/sdX
          sync

     Sie benötigen in der Regel Administratorrechte, um auf /dev/sdX zuzugreifen.

Auf eine DVD brennen
--------------------

Um das Abbild auf eine DVD zu kopieren, führen Sie diese Schritte durch:

 1. Entpacken Sie das Abbild mit dem xz-Befehl:

          xz -d guixsd-install-VERSION.SYSTEM.iso.xz

 2. Legen Sie eine unbespielte DVD in Ihren Rechner ein und bestimmen Sie ihren Gerätenamen. Angenommen der Name des DVD-Laufwerks ist /dev/srX, kopieren Sie das Abbild mit:

          growisofs -dvd-compat -Z /dev/srX=guixsd-install-VERSION.SYSTEM.iso

     Der Zugriff auf /dev/srX setzt in der Regel Administratorrechte voraus.

Das System starten
------------------

Sobald das erledigt ist, sollten Sie Ihr System neu starten und es vom USB-Stick oder der DVD booten können. Dazu müssen Sie wahrscheinlich beim Starten des Rechners in das BIOS- oder UEFI-Boot-Menü gehen, von wo aus Sie auswählen können, dass vom USB-Stick gebootet werden soll.

See Installing Guix in a VM, if, instead, you would like to install Guix System in a virtual machine (VM).

Vor der Installation
====================

Once you have successfully booted your computer using the installation medium, you should end up with the welcome page of the graphical installer. The graphical installer is a text-based user interface built upon the newt library.  It shall guide you through all the different steps needed to install GNU Guix System.  However, as the graphical installer is still under heavy development, you might want to fallback to the original, shell based install process, by switching to TTYs 3 to 6 with the shortcuts CTRL-ALT-F[3-6]. The following sections describe the installation procedure assuming you're using one of those TTYs. They are configured and can be used to run commands as root.

TTY2 shows this documentation, browsable using the Info reader commands (see Stand-alone GNU Info).  The installation system runs the GPM mouse daemon, which allows you to select text with the left mouse button and to paste it with the middle button.

     Für die Installation benötigen Sie Zugang zum Internet, damit fehlende Abhängigkeiten Ihrer Systemkonfiguration heruntergeladen werden können. Im Abschnitt »Netzwerkkonfiguration« weiter unten finden Sie mehr Informationen dazu.

The installation system includes many common tools needed for this task. But it is also a full-blown Guix System, which means that you can install additional packages, should you need it, using guix package (see Aufruf von guix package).

Tastaturbelegung
----------------

Das Installationsabbild verwendet die US-amerikanische QWERTY-Tastaturbelegung. Wenn Sie dies ändern möchten, können Sie den loadkeys-Befehl benutzen. Mit folgendem Befehl würden Sie zum Beispiel die Dvorak-Tastaturbelegung auswählen:

     loadkeys dvorak

Schauen Sie sich an, welche Dateien im Verzeichnis /run/current-system/profile/share/keymaps stehen, um eine Liste verfügbarer Tastaturbelegungen zu sehen. Wenn Sie mehr Informationen brauchen, führen Sie man loadkeys aus.

Netzwerkkonfiguration
---------------------

Führen Sie folgenden Befehl aus, um zu sehen, wie Ihre Netzwerkschnittstellen benannt sind:

     ifconfig -a

... oder mit dem GNU/Linux-eigenen ip-Befehl:

     ip a

Der Name kabelgebundener Schnittstellen (engl. Interfaces) beginnt mit dem Buchstaben e, zum Beispiel heißt die dem ersten fest eingebauten Ethernet-Adapter entsprechende Schnittstelle eno1. Drahtlose Schnittstellen werden mit einem Namen bezeichnet, der mit dem Buchstaben w beginnt, etwa w1p2s0.

Kabelverbindung
     Um ein kabelgebundenes Netzwerk einzurichten, führen Sie den folgenden Befehl aus, wobei Sie statt SCHNITTSTELLE den Namen der kabelgebundenen Schnittstelle eintippen, die Sie benutzen möchten.

          ifconfig SCHNITTSTELLE up

Drahtlose Verbindung
     Um Drahtlosnetzwerke einzurichten, können Sie eine Konfigurationsdatei für das Konfigurationswerkzeug des wpa_supplicant schreiben (wo Sie sie speichern, ist nicht wichtig), indem Sie eines der verfügbaren Textbearbeitungsprogramme wie etwa nano benutzen:

          nano wpa_supplicant.conf

     Zum Beispiel können Sie die folgende Formulierung in der Datei speichern, die für viele Drahtlosnetzwerke funktioniert, sofern Sie die richtige SSID und Passphrase für das Netzwerk eingeben, mit dem Sie sich verbinden möchten:

          network={
            ssid="MEINE-SSID"
            key_mgmt=WPA-PSK
            psk="geheime Passphrase des Netzwerks"
          }

     Starten Sie den Dienst für Drahtlosnetzwerke und lassen Sie ihn im Hintergrund laufen, indem Sie folgenden Befehl eintippen (ersetzen Sie dabei SCHNITTSTELLE durch den Namen der Netzwerkschnittstelle, die Sie benutzen möchten):

          wpa_supplicant -c wpa_supplicant.conf -i SCHNITTSTELLE -B

     Führen Sie man wpa_supplicant aus, um mehr Informationen zu erhalten.

Zu diesem Zeitpunkt müssen Sie sich eine IP-Adresse beschaffen. Auf einem Netzwerk, wo IP-Adressen automatisch via DHCP zugewiesen werden, können Sie das hier ausführen:

     dhclient -v SCHNITTSTELLE

Versuchen Sie, einen Server zu pingen, um zu prüfen, ob sie mit dem Internet verbunden sind und alles richtig funktioniert:

     ping -c 3 gnu.org

Einen Internetzugang herzustellen, ist in jedem Fall nötig, weil das Abbild nicht alle Software und Werkzeuge enthält, die nötig sein könnten.

Wenn Sie möchten, können Sie die weitere Installation auch per Fernwartung durchführen, indem Sie einen SSH-Server starten:

     herd start ssh-daemon

Vergewissern Sie sich vorher, dass Sie entweder ein Passwort mit passwd festgelegt haben, oder dass Sie für OpenSSH eine Authentifizierung über öffentliche Schlüssel eingerichtet haben, bevor Sie sich anmelden.

Plattenpartitionierung
----------------------

Sofern nicht bereits geschehen, ist der nächste Schritt, zu partitionieren und dann die Zielpartition zu formatieren.

Auf dem Installationsabbild sind mehrere Partitionierungswerkzeuge zu finden, einschließlich (see Overview (GNU Parted User Manual)), fdisk und cfdisk. Starten Sie eines davon und partitionieren Sie Ihre Festplatte oder sonstigen Massenspeicher:

     cfdisk

Wenn Ihre Platte mit einer »GUID Partition Table« (GPT) formatiert ist, und Sie vorhaben, die BIOS-basierte Variante des GRUB-Bootloaders  zu installieren (was der Vorgabe entspricht), stellen Sie sicher, dass eine Partition als BIOS-Boot-Partition ausgewiesen ist (see BIOS installation (GNU GRUB manual)).

If you instead wish to use EFI-based GRUB, a FAT32 EFI System Partition (ESP) is required.  This partition can be mounted at /boot/efi for instance and must have the esp flag set.  E.g., for parted:

     parted /dev/sda set 1 esp on

     Falls Sie nicht wissen, ob Sie einen EFI- oder BIOS-basierten GRUB installieren möchten: Wenn bei Ihnen das Verzeichnis /sys/firmware/efi im Dateisystem existiert, möchten Sie vermutlich eine EFI-Installation durchführen, wozu Sie in Ihrer Konfiguration grub-efi-bootloader benutzen. Ansonsten sollten Sie den BIOS-basierten GRUB benutzen, der mit grub-bootloader bezeichnet wird.  Siehe Bootloader-Konfiguration, wenn Sie mehr Informationen über Bootloader brauchen.

Once you are done partitioning the target hard disk drive, you have to create a file system on the relevant partition(s) (Currently Guix System only supports ext4 and btrfs file systems.  In particular, code that reads file system UUIDs and labels only works for these file system types.).  For the ESP, if you have one and assuming it is /dev/sda1, run:

     mkfs.fat -F32 /dev/sda1

Geben Sie Ihren Dateisystemen auch besser eine Bezeichnung (»Label«), damit Sie sie zuverlässig wiedererkennen und später in den file-system-Deklarationen darauf Bezug nehmen können (see Dateisysteme). Dazu benutzen Sie typischerweise die Befehlszeilenoption -L des Befehls mkfs.ext4 oder entsprechende Optionen für andere Befehle. Wenn wir also annehmen, dass /dev/sda2 die Partition ist, auf der Ihr Wurzeldateisystem (englisch »root«) wohnen soll, können Sie dort mit diesem Befehl ein Dateisystem mit der Bezeichnung my-root erstellen:

     mkfs.ext4 -L my-root /dev/sda2

Falls Sie aber vorhaben, die Partition mit dem Wurzeldateisystem zu verschlüsseln, können Sie dazu die Cryptsetup-/LUKS-Werkzeuge verwenden (siehe man cryptsetup, um mehr darüber zu erfahren). Angenommen Sie wollen die Partition für das Wurzeldateisystem verschlüsselt auf /dev/sda2 installieren, dann brauchen Sie eine Befehlsfolge ähnlich wie diese:

     cryptsetup luksFormat /dev/sda2
     cryptsetup open --type luks /dev/sda2 my-partition
     mkfs.ext4 -L my-root /dev/mapper/my-partition

Sobald das erledigt ist, binden Sie dieses Dateisystem als Installationsziel mit dem Einhängepunkt /mnt ein, wozu Sie einen Befehl wie hier eintippen (auch hier unter der Annahme, dass my-root die Bezeichnung des künftigen Wurzeldateisystems ist):

     mount LABEL=my-root /mnt

Also mount any other file systems you would like to use on the target system relative to this path.  If you have opted for /boot/efi as an EFI mount point for example, mount it at /mnt/boot/efi now so it is found by guix system init afterwards.

Wenn Sie zudem auch vorhaben, eine oder mehrere Swap-Partitionen zu benutzen (see swap space (The GNU C Library Reference Manual)), initialisieren Sie diese nun mit mkswap. Angenommen Sie haben eine Swap-Partition auf /dev/sda3, dann würde der Befehl so lauten:

     mkswap /dev/sda3
     swapon /dev/sda3

Alternativ können Sie eine Swap-Datei benutzen. Angenommen, Sie wollten die Datei /swapdatei im neuen System als eine Swapdatei benutzen, dann müssten Sie Folgendes ausführen (Dieses Beispiel wird auf vielen Arten von Dateisystemen funktionieren (z.B. auf ext4). Auf Dateisystemen mit Copy-on-Write (wie z.B. btrfs) können sich die nötigen Schritte unterscheiden. Details finden Sie in der Dokumentation auf den Handbuchseiten von mkswap und swapon.):

     # Das bedeutet 10 GiB Swapspeicher. "count" anpassen zum ändern.
     dd if=/dev/zero of=/mnt/swapfile bs=1MiB count=10240
     # Zur Sicherheit darf nur der Administrator lesen und schreiben.
     chmod 600 /mnt/swapfile
     mkswap /mnt/swapfile
     swapon /mnt/swapfile

Bedenken Sie, dass, wenn Sie die Partition für das Wurzeldateisystem (»root«) verschlüsselt und eine Swap-Datei in diesem Dateisystem wie oben beschrieben erstellt haben, die Verschlüsselung auch die Swap-Datei schützt, genau wie jede andere Datei in dem Dateisystem.

Fortfahren mit der Installation
===============================

Wenn die Partitionen des Installationsziels bereit sind und dessen Wurzeldateisystem unter /mnt eingebunden wurde, kann es losgehen mit der Installation. Führen Sie zuerst aus:

     herd start cow-store /mnt

Dadurch wird /gnu/store copy-on-write, d.h. dorthin von Guix erstellte Pakete werden in ihrer Installationsphase auf dem unter /mnt befindlichen Zieldateisystem gespeichert, statt den Arbeitsspeicher auszulasten. Das ist nötig, weil die erste Phase des Befehls guix system init (siehe unten) viele Dateien nach /gnu/store herunterlädt oder sie erstellt, Änderungen am /gnu/store aber bis dahin wie das übrige Installationssystem nur im Arbeitsspeicher gelagert werden konnten.

Als Nächstes müssen Sie eine Datei bearbeiten und dort eine Deklaration des Betriebssystems, das Sie installieren möchten, hineinschreiben. Zu diesem Zweck sind im Installationssystem drei Texteditoren enthalten. Wir empfehlen, dass Sie GNU nano benutzen (see GNU nano Manual), welcher Syntax und zueinander gehörende Klammern hervorheben kann. Andere mitgelieferte Texteditoren, die Sie benutzen können, sind GNU Zile (ein Emacs-Klon) und nvi (ein Klon des ursprünglichen vi-Editors von BSD). Wir empfehlen sehr, dass Sie diese Datei im Zieldateisystem der Installation speichern, etwa als /mnt/etc/config.scm, weil Sie Ihre Konfigurationsdatei im frisch installierten System noch brauchen werden.

Der Abschnitt see Das Konfigurationssystem nutzen gibt einen Überblick über die Konfigurationsdatei. Die in dem Abschnitt diskutierten Beispielkonfigurationen sind im Installationsabbild im Verzeichnis /etc/configuration zu finden. Um also mit einer Systemkonfiguration anzufangen, die einen grafischen »Display-Server« (eine »Desktop«-Arbeitsumgebung) bietet, könnten Sie so etwas ausführen:

     # mkdir /mnt/etc
     # cp /etc/configuration/desktop.scm /mnt/etc/config.scm
     # nano /mnt/etc/config.scm

Achten Sie darauf, was in Ihrer Konfigurationsdatei steht, und besonders auf Folgendes:

  * Make sure the bootloader-configuration form refers to the target you want to install GRUB on.  It should mention grub-bootloader if you are installing GRUB in the legacy way, or grub-efi-bootloader for newer UEFI systems.  For legacy systems, the target field names a device, like /dev/sda; for UEFI systems it names a path to a mounted EFI partition, like /boot/efi; do make sure the path is currently mounted and a file-system entry is specified in your configuration.

  * Dateisystembezeichnungen müssen mit den jeweiligen device-Feldern in Ihrer file-system-Konfiguration übereinstimmen, sofern Sie in Ihrer file-system-Konfiguration die Prozedur file-system-label für ihre device-Felder benutzen.

  * Gibt es verschlüsselte Partitionen oder RAID-Partitionen, dann müssen sie im mapped-devices-Feld genannt werden (see Zugeordnete Geräte).

Wenn Sie damit fertig sind, Ihre Konfigurationsdatei vorzubereiten, können Sie das neue System initialisieren (denken Sie daran, dass zukünftige Wurzeldateisystem muss unter /mnt wie bereits beschrieben eingebunden sein):

     guix system init /mnt/etc/config.scm /mnt

Dies kopiert alle notwendigen Dateien und installiert GRUB auf /dev/sdX, sofern Sie nicht noch die Befehlszeilenoption --no-bootloader benutzen. Weitere Informationen finden Sie im Abschnitt see Aufruf von guix system. Der Befehl kann das Herunterladen oder Erstellen fehlender Softwarepakete auslösen, was einige Zeit in Anspruch nehmen kann.

Sobald der Befehl erfolgreich — hoffentlich! — durchgelaufen ist, können Sie mit dem Befehl reboot das neue System booten lassen. Der Administratornutzer root hat im neuen System zunächst ein leeres Passwort und Passwörter der anderen Nutzer müssen Sie erst setzen, indem Sie den Befehl passwd als root ausführen, außer Ihre Konfiguration enthält schon Passwörter (see user account passwords).

From then on, you can update the system whenever you want by running, say:

     guix pull
     sudo guix system reconfigure /etc/config.scm

This builds a new system generation with the latest packages and services (see Aufruf von guix system).  We recommend doing that regularly so that your system includes the latest security updates (see Sicherheitsaktualisierungen).

     Note that sudo guix runs your user's guix command and not root's, because sudo leaves PATH unchanged.  To explicitly run root's guix, type sudo -i guix ....

Join us on #guix on the Freenode IRC network or on guix-devel@gnu.org to share your experience---good or not so good.

Installing Guix in a Virtual Machine
====================================

If you'd like to install Guix System in a virtual machine (VM) or on a virtual private server (VPS) rather than on your beloved machine, this section is for you.

To boot a QEMU (http://qemu.org/) VM for installing Guix System in a disk image, follow these steps:

 1. First, retrieve and decompress the Guix system installation image as described previously (see Installation von USB-Stick oder DVD).

 2. Legen Sie nun ein Disk-Image an, das das System nach der Installation enthalten soll. Um ein qcow2-formatiertes Disk-Image zu erstellen, benutzen Sie den Befehl qemu-img:

          qemu-img create -f qcow2 guixsd.img 50G

     Die Datei, die Sie herausbekommen, wird wesentlich kleiner als 50 GB sein (typischerweise kleiner als 1 MB), vergrößert sich aber, wenn der virtualisierte Speicher gefüllt wird.

 3. Starten Sie das USB-Installationsabbild auf einer virtuellen Maschine:

          qemu-system-x86_64 -m 1024 -smp 1 \
            -net user -net nic,model=virtio -boot menu=on \
            -drive file=guixsd-install-VERSION.SYSTEM.iso \
            -drive file=guixsd.img

     Halten Sie obige Reihenfolge der -drive-Befehlszeilenoptionen für die Laufwerke ein.

     Drücken Sie auf der Konsole der virtuellen Maschine schnell die F12-Taste, um ins Boot-Menü zu gelangen. Drücken Sie dort erst die Taste 2 und dann die Eingabetaste RET, um Ihre Auswahl zu bestätigen.

 4. Sie sind nun in der virtuellen Maschine als Administratornutzer root angemeldet und können mit der Installation wie gewohnt fortfahren. Folgen Sie der Anleitung im Abschnitt see Vor der Installation.

Once installation is complete, you can boot the system that's on your guixsd.img image.  See Running Guix in a VM, for how to do that.

Ein Abbild zur Installation erstellen
=====================================

Das oben beschriebene Installationsabbild wurde mit dem Befehl guix system erstellt, genauer gesagt mit:

     guix system disk-image --file-system-type=iso9660 \
       gnu/system/install.scm

Die Datei gnu/system/install.scm finden Sie im Quellbaum von Guix. Schauen Sie sich die Datei und auch den Abschnitt Aufruf von guix system an, um mehr Informationen über das Installationsabbild zu erhalten.

Abbild zur Installation für ARM-Rechner erstellen
=================================================

Viele ARM-Chips funktionieren nur mit ihrer eigenen speziellen Variante des U-Boot (http://www.denx.de/wiki/U-Boot/)-Bootloaders.

Wenn Sie ein Disk-Image erstellen und der Bootloader nicht anderweitig schon installiert ist (auf einem anderen Laufwerk), ist es ratsam, ein Disk-Image zu erstellen, was den Bootloader enthält, mit dem Befehl:

     guix system disk-image --system=armhf-linux -e '((@ (gnu system install) os-with-u-boot) (@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")'

A20-OLinuXino-Lime2 ist der Name des Chips. Wenn Sie einen ungültigen Namen eingeben, wird eine Liste möglicher Chip-Namen ausgegeben.

Paketverwaltung
***************

Der Zweck von GNU Guix ist, Benutzern die leichte Installation, Aktualisierung und Entfernung von Software-Paketen zu ermöglichen, ohne dass sie ihre Erstellungsprozeduren oder Abhängigkeiten kennen müssen. Guix kann natürlich noch mehr als diese offensichtlichen Funktionalitäten.

Dieses Kapitel beschreibt die Hauptfunktionalitäten von Guix, sowie die von Guix angebotenen Paketverwaltungswerkzeuge. Zusätzlich von den im Folgenden beschriebenen Befehlszeilen-Benutzerschnittstellen (see guix package) können Sie auch mit der Emacs-Guix-Schnittstelle (see The Emacs-Guix Reference Manual) arbeiten, nachdem Sie das Paket emacs-guix installiert haben (führen Sie zum Einstieg in Emacs-Guix den Emacs-Befehl M-x guix-help aus):

     guix package -i emacs-guix

Funktionalitäten
================

Wenn Sie Guix benutzen, landet jedes Paket schließlich im Paket-Store in seinem eigenen Verzeichnis — der Name ist ähnlich wie /gnu/store/xxx-package-1.2, wobei xxx eine Zeichenkette in Base32-Darstellung ist.

Statt diese Verzeichnisse direkt anzugeben, haben Nutzer ihr eigenes Profil, welches auf diejenigen Pakete zeigt, die sie tatsächlich benutzen wollen. Diese Profile sind im Persönlichen Verzeichnis des jeweiligen Nutzers gespeichert als $HOME/.guix-profile.

Zum Beispiel installiert alice GCC 4.7.2. Dadurch zeigt dann /home/alice/.guix-profile/bin/gcc auf /gnu/store/...-gcc-4.7.2/bin/gcc. Auf demselben Rechner hat bob bereits GCC 4.8.0 installiert. Das Profil von bob zeigt dann einfach weiterhin auf /gnu/store/...-gcc-4.8.0/bin/gcc — d.h. beide Versionen von GCC koexistieren auf demselben System, ohne sich zu stören.

Der Befehl guix package ist das zentrale Werkzeug, um Pakete zu verwalten (see Aufruf von guix package). Es arbeitet auf dem eigenen Profil jedes Nutzers und kann mit normalen Benutzerrechten ausgeführt werden.

Der Befehl stellt die offensichtlichen Installations-, Entfernungs- und Aktualisierungsoperationen zur Verfügung. Jeder Aufruf ist tatsächlich eine eigene Transaktion: Entweder die angegebene Operation wird erfolgreich durchgeführt, oder gar nichts passiert. Wenn also der Prozess von guix package während der Transaktion beendet wird, oder es zum Stromausfall während der Transaktion kommt, dann bleibt der alte, nutzbare Zustands des Nutzerprofils erhalten.

In addition, any package transaction may be rolled back.  So, if, for example, an upgrade installs a new version of a package that turns out to have a serious bug, users may roll back to the previous instance of their profile, which was known to work well.  Similarly, the global system configuration on Guix is subject to transactional upgrades and roll-back (see Das Konfigurationssystem nutzen).

Alle Pakete im Paket-Store können vom Müllsammler (Garbage Collector) gelöscht werden. Guix ist in der Lage, festzustellen, welche Pakete noch durch Benutzerprofile referenziert werden, und entfernt nur diese, die nachweislich nicht mehr referenziert werden (see Aufruf von guix gc). Benutzer können auch ausdrücklich alte Generationen ihres Profils löschen, damit die zugehörigen Pakete vom Müllsammler gelöscht werden können.

Guix verfolgt einen rein funktionalen Ansatz bei der Paketverwaltung, wie er in der Einleitung beschrieben wurde (see Einführung). Jedes Paketverzeichnis im /gnu/store hat einen Hash all seiner bei der Erstellung benutzten Eingaben im Namen — Compiler, Bibliotheken, Erstellungs-Skripts etc. Diese direkte Entsprechung ermöglicht es Benutzern, eine Paketinstallation zu benutzen, die sicher dem aktuellen Stand ihrer Distribution entspricht. Sie maximiert auch die Reproduzierbarkeit der Erstellungen zu maximieren: Dank der isolierten Erstellungsumgebungen, die benutzt werden, resultiert eine Erstellung wahrscheinlich in bitweise identischen Dateien, auch wenn sie auf unterschiedlichen Maschinen durchgeführt wird (see container).

Auf dieser Grundlage kann Guix transparent Binär- oder Quelldateien ausliefern. Wenn eine vorerstellte Binärdatei für ein /gnu/store-Objekt von einer externen Quelle verfügbar ist — ein Substitut —, lädt Guix sie einfach herunter und entpackt sie, andernfalls erstellt Guix das Paket lokal aus seinem Quellcode (see Substitute). Weil Erstellungsergebnisse normalerweise Bit für Bit reproduzierbar sind, müssen die Nutzer den Servern, die Substitute anbieten, nicht blind vertrauen; sie können eine lokale Erstellung erzwingen und Substitute anfechten (see Aufruf von guix challenge).

Kontrolle über die Erstellungsumgebung ist eine auch für Entwickler nützliche Funktionalität. Der Befehl guix environment ermöglicht es Entwicklern eines Pakets, schnell die richtige Entwicklungsumgebung für ihr Paket einzurichten, ohne manuell die Abhängigkeiten des Pakets in ihr Profil installieren zu müssen (see Aufruf von guix environment).

Ganz Guix und all seine Paketdefinitionen stehen unter Versionskontrolle und guix pull macht es möglich, auf dem Verlauf der Entwicklung von Guix selbst »in der Zeit zu reisen« (see Aufruf von guix pull). Dadurch kann eine Instanz von Guix auf einer anderen Maschine oder zu einem späteren Zeitpunkt genau nachgebildet werden, wodurch auch vollständige Software-Umgebungen gänzlich nachgebildet werden können, mit genauer Provenienzverfolgung, wo diese Software herkommt.

Invoking guix package
=====================

Der Befehl guix package ist ein Werkzeug, womit Nutzer Pakete installieren, aktualisieren, entfernen und auf vorherige Konfigurationen zurücksetzen können. Dabei wird nur das eigene Profil des Nutzers verwendet, und es funktioniert mit normalen Benutzerrechten, ohne Administratorrechte (see Funktionalitäten). Die Syntax ist:

     guix package OPTIONEN

In erster Linie geben die OPTIONEN an, welche Operationen in der Transaktion durchgeführt werden sollen. Nach Abschluss wird ein neues Profil erzeugt, aber vorherige Generationen des Profils bleiben verfügbar, falls der Benutzer auf sie zurückwechseln will.

Um zum Beispiel lua zu entfernen und guile und guile-cairo in einer einzigen Transaktion zu installieren:

     guix package -r lua -i guile guile-cairo

guix package unterstützt auch ein deklaratives Vorgehen, wobei der Nutzer die genaue Menge an Paketen, die verfügbar sein sollen, festlegt und über die Befehlszeilenoption --manifest übergibt (see --manifest).

Für jeden Benutzer wird automatisch eine symbolische Verknüpfung zu seinem Standardprofil angelegt als $HOME/.guix-profile. Diese symbolische Verknüpfung zeigt immer auf die aktuelle Generation des Standardprofils des Benutzers. Somit können Nutzer $HOME/.guix-profile/bin z.B. zu ihrer Umgebungsvariablen PATH hinzufügen. Wenn Sie nicht die Guix System Distribution benutzen, sollten Sie in Betracht ziehen, folgende Zeilen zu Ihrem ~/.bash_profile hinzuzufügen (see Bash Startup Files (The GNU Bash Reference Manual)), damit in neu erzeugten Shells alle Umgebungsvariablen richtig definiert werden:

     GUIX_PROFILE="$HOME/.guix-profile" ; \
     source "$HOME/.guix-profile/etc/profile"

Ist Ihr System für mehrere Nutzer eingerichtet, werden Nutzerprofile an einem Ort gespeichert, der als Müllsammlerwurzel registriert ist, auf die $HOME/.guix-profile zeigt (see Aufruf von guix gc). Dieses Verzeichnis ist normalerweise LOCALSTATEDIR/guix/profiles/per-user/BENUTZER, wobei LOCALSTATEDIR der an configure als --localstatedir übergebene Wert ist und BENUTZER für den jeweiligen Benutzernamen steht. Das per-user-Verzeichnis wird erstellt, wenn guix-daemon gestartet wird, und das Unterverzeichnis BENUTZER wird durch guix package erstellt.

Als OPTIONEN kann vorkommen:

--install=PAKET ...
-i PAKET ...
     Die angegebenen PAKETe installieren.

     Jedes PAKET kann entweder einfach durch seinen Paketnamen aufgeführt werden, wie guile, oder als Paketname gefolgt von einem At-Zeichen @ und einer Versionsnummer, wie guile@1.8.8 oder auch nur guile@1.8 (in letzterem Fall wird die neueste Version mit Präfix 1.8 ausgewählt.)

     Wird keine Versionsnummer angegeben, wird die neueste verfügbare Version ausgewählt. Zudem kann im PAKET ein Doppelpunkt auftauchen, gefolgt vom Namen einer der Ausgaben des Pakets, wie gcc:doc oder binutils@2.22:lib (see Pakete mit mehreren Ausgaben.). Pakete mit zugehörigem Namen (und optional der Version) werden unter den Modulen der GNU-Distribution gesucht (see Paketmodule).

     Manchmal haben Pakete propagierte Eingaben: Als solche werden Abhängigkeiten bezeichnet, die automatisch zusammen mit dem angeforderten Paket installiert werden (im Abschnitt see propagated-inputs in package objects sind weitere Informationen über propagierte Eingaben in Paketdefinitionen zu finden).

     Ein Beispiel ist die GNU-MPC-Bibliothek: Ihre C-Headerdateien verweisen auf die der GNU-MPFR-Bibliothek, welche wiederum auf die der GMP-Bibliothek verweisen. Wenn also MPC installiert wird, werden auch die MPFR- und GMP-Bibliotheken in das Profil installiert; entfernt man MPC, werden auch MPFR und GMP entfernt — außer sie wurden noch auf andere Art ausdrücklich vom Nutzer installiert.

     Abgesehen davon setzen Pakete manchmal die Definition von Umgebungsvariablen für ihre Suchpfade voraus (siehe die Erklärung von --search-paths weiter unten). Alle fehlenden oder womöglich falschen Definitionen von Umgebungsvariablen werden hierbei gemeldet.

--install-from-expression=AUSDRUCK
-e AUSDRUCK
     Das Paket installieren, zu dem der AUSDRUCK ausgewertet wird.

     Beim AUSDRUCK muss es sich um einen Scheme-Ausdruck handeln, der zu einem <package>-Objekt ausgewertet wird. Diese Option ist besonders nützlich, um zwischen gleichnamigen Varianten eines Pakets zu unterscheiden, durch Ausdrücke wie (@ (gnu packages base) guile-final).

     Beachten Sie, dass mit dieser Option die erste Ausgabe des angegebenen Pakets installiert wird, was unzureichend sein kann, wenn eine bestimmte Ausgabe eines Pakets mit mehreren Ausgaben gewünscht ist.

--install-from-file=DATEI
-f DATEI
     Das Paket installieren, zu dem der Code in der DATEI ausgewertet wird.

     Zum Beispiel könnte die DATEI eine Definition wie diese enthalten (see Pakete definieren):

               [file package-hello.scm not included]

     Entwickler könnten es für nützlich erachten, eine solche guix.scm-Datei im Quellbaum ihres Projekts abzulegen, mit der Zwischenstände der Entwicklung getestet und reproduzierbare Erstellungsumgebungen aufgebaut werden können (see Aufruf von guix environment).

--remove=PAKET ...
-r PAKET ...
     Die angegebenen PAKETe entfernen.

     Wie auch bei --install kann jedes PAKET neben dem Paketnamen auch eine Versionsnummer und/oder eine Ausgabe benennen. Zum Beispiel würde -r glibc:debug die debug-Ausgabe von glibc aus dem Profil entfernen.

--upgrade[=REGEXP ...]
-u [REGEXP ...]
     Alle installierten Pakete aktualisieren. Wenn einer oder mehr reguläre Ausdrücke (Regexps) angegeben wurden, werden nur diejenigen installierten Pakete aktualisiert, deren Name zu einer der REGEXPs passt. Siehe auch weiter unten die Befehlszeilenoption --do-not-upgrade.

     Beachten Sie, dass das Paket so auf die neueste Version unter den Paketen gebracht wird, die in der aktuell installierten Distribution vorliegen. Um jedoch Ihre Distribution zu aktualisieren, sollten Sie regelmäßig guix pull ausführen (see Aufruf von guix pull).

--do-not-upgrade[=REGEXP ...]
     In Verbindung mit der Befehlszeilenoption --upgrade, führe keine Aktualisierung von Paketen durch, deren Name zum regulären Ausdruck REGEXP passt. Um zum Beispiel alle Pakete im aktuellen Profil zu aktualisieren mit Ausnahme derer, die »emacs« im Namen haben:

          $ guix package --upgrade . --do-not-upgrade emacs

--manifest=DATEI
-m DATEI
     Erstellt eine neue Generation des Profils aus dem vom Scheme-Code in DATEI gelieferten Manifest-Objekt.

     Dadurch könnrn Sie den Inhalt des Profils deklarieren, statt ihn durch eine Folge von Befehlen wie --install u.Ä. zu generieren. Der Vorteil ist, dass die DATEI unter Versionskontrolle gestellt werden kann, auf andere Maschinen zum Reproduzieren desselben Profils kopiert werden kann und Ähnliches.

     Der Code in der DATEI muss ein Manifest-Objekt liefern, was ungefähr einer Liste von Paketen entspricht:

          (use-package-modules guile emacs)

          (packages->manifest
           (list emacs
                 guile-2.0
                 ;; Eine bestimmte Paketausgabe nutzen.
                 (list guile-2.0 "debug")))

     In diesem Beispiel müssen wir wissen, welche Module die Variablen emacs und guile-2.0 definieren, um die richtige Angabe mit use-package-modules machen zu können, was umständlich sein kann. Wir können auch normale Paketnamen angeben und sie durch specifications->manifest zu den entsprechenden Paketobjekten auflösen, zum Beispiel so:

          (specifications->manifest
           '("emacs" "guile@2.2" "guile@2.2:debug"))

--roll-back
     Wechselt zur vorherigen Generation des Profils zurück — d.h. macht die letzte Transaktion rückgängig.

     In Verbindung mit Befehlszeilenoptionen wie --install wird zuerst zurückgesetzt, bevor andere Aktionen durchgeführt werden.

     Ein Rücksetzen der ersten Generation, die installierte Pakete enthält, wechselt das Profil zur nullten Generation, die keinerlei Dateien enthält, abgesehen von Metadaten über sich selbst.

     Nach dem Zurücksetzen überschreibt das Installieren, Entfernen oder Aktualisieren von Paketen vormals zukünftige Generationen, d.h. der Verlauf der Generationen eines Profils ist immer linear.

--switch-generation=MUSTER
-S MUSTER
     Wechselt zu der bestimmten Generation, die durch das MUSTER bezeichnet wird.

     Als MUSTER kann entweder die Nummer einer Generation oder eine Nummer mit vorangestelltem »+« oder »-« dienen. Letzteres springt die angegebene Anzahl an Generationen vor oder zurück. Zum Beispiel kehrt --switch-generation=+1 nach einem Zurücksetzen wieder zur neueren Generation zurück.

     Der Unterschied zwischen --roll-back und --switch-generation=-1 ist, dass --switch-generation keine nullte Generation erzeugen wird; existiert die angegebene Generation nicht, bleibt schlicht die aktuelle Generation erhalten.

--search-paths[=ART]
     Führe die Definitionen von Umgebungsvariablen auf, in Bash-Syntax, die nötig sein könnten, um alle installierten Pakete nutzen zu können. Diese Umgebungsvariablen werden benutzt, um die Suchpfade für Dateien festzulegen, die von einigen installierten Paketen benutzt werden.

     Zum Beispiel braucht GCC die Umgebungsvariablen CPATH und LIBRARY_PATH, um zu wissen, wo sich im Benutzerprofil Header und Bibliotheken befinden (see Environment Variables (Using the GNU Compiler Collection (GCC))). Wenn GCC und, sagen wir, die C-Bibliothek im Profil installiert sind, schlägt --search-paths also vor, diese Variablen jeweils auf PROFILE/include und PROFILE/lib verweisen zu lassen.

     Die typische Nutzung ist, in der Shell diese Variablen zu definieren:

          $ eval `guix package --search-paths`

     Als ART kann entweder exact, prefix oder suffix gewählt werden, wodurch die gelieferten Definitionen der Umgebungsvariablen entweder exakt die Einstellungen für Guix meldet, oder sie als Präfix oder Suffix an den aktuellen Wert dieser Variablen anhängt. Gibt man keine ART an, wird der Vorgabewert exact verwendet.

     Diese Befehlszeilenoption kann auch benutzt werden, um die kombinierten Suchpfade mehrerer Profile zu berechnen. Betrachten Sie dieses Beispiel:

          $ guix package -p foo -i guile
          $ guix package -p bar -i guile-json
          $ guix package -p foo -p bar --search-paths

     Der letzte Befehl oben meldet auch die Definition der Umgebungsvariablen GUILE_LOAD_PATH, obwohl für sich genommen weder foo noch bar zu dieser Empfehlung führen würden.

--profile=PROFIL
-p PROFIL
     Auf PROFIL anstelle des Standardprofils des Benutzers arbeiten.

--allow-collisions
     Kollidierende Pakete im neuen Profil zulassen. Benutzung auf eigene Gefahr!

     Standardmäßig wird guix package Kollisionen als Fehler auffassen und melden. Zu Kollisionen kommt es, wenn zwei oder mehr verschiedene Versionen oder Varianten desselben Pakets im Profil landen.

--bootstrap
     Erstellt das Profil mit dem Bootstrap-Guile. Diese Option ist nur für Entwickler der Distribution nützlich.

Zusätzlich zu diesen Aktionen unterstützt guix package folgende Befehlszeilenoptionen, um den momentanen Zustand eines Profils oder die Verfügbarkeit von Paketen nachzulesen:

--search=REGEXP
-s REGEXP
     List the available packages whose name, synopsis, or description matches REGEXP (in a case-insensitive fashion), sorted by relevance.  Print all the metadata of matching packages in recutils format (see GNU recutils databases (GNU recutils manual)).

     So können bestimmte Felder mit dem Befehl recsel extrahiert werden, zum Beispiel:

          $ guix package -s malloc | recsel -p name,version,relevance
          name: jemalloc
          version: 4.5.0
          relevance: 6

          name: glibc
          version: 2.25
          relevance: 1

          name: libgc
          version: 7.6.0
          relevance: 1

     Ebenso kann der Name aller zu den Bedingungen der GNU LGPL, Version 3, verfügbaren Pakete ermittelt werden:

          $ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"'
          name: elfutils

          name: gmp
          ...

     Es ist auch möglich, Suchergebnisse näher einzuschränken, indem Sie -s mehrmals übergeben. Zum Beispiel liefert folgender Befehl eines Liste von Brettspielen:

          $ guix package -s '\<board\>' -s game | recsel -p name
          name: gnubg
          ...

     Würden wir -s game weglassen, bekämen wir auch Software-Pakete aufgelistet, die mit »printed circuit boards« (elektronischen Leiterplatten) zu tun haben; ohne die spitzen Klammern um board bekämen wir auch Pakete, die mit »keyboards« (Tastaturen, oder musikalischen Keyboard) zu tun haben.

     Es ist Zeit für ein komplexeres Beispiel. Folgender Befehl sucht kryptographische Bibliotheken, filtert Haskell-, Perl-, Python- und Ruby-Bibliotheken heraus und gibt Namen und Zusammenfassung passender Pakete aus:

          $ guix package -s crypto -s library | \
              recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis

     See Selection Expressions (GNU recutils manual) enthält weitere Informationen über Auswahlausdrücke mit recsel -e.

--show=PAKET
     Zeigt Details über das PAKET aus der Liste verfügbarer Pakete, im recutils-Format (see GNU recutils databases (GNU recutils manual)).

          $ guix package --show=python | recsel -p name,version
          name: python
          version: 2.7.6

          name: python
          version: 3.3.5

     Sie können auch den vollständigen Namen eines Pakets angeben, um Details nur über diese Version angezeigt zu bekommen:

          $ guix package --show=python@3.4 | recsel -p name,version
          name: python
          version: 3.4.3

--list-installed[=REGEXP]
-I [REGEXP]
     Listet die derzeit installierten Pakete im angegebenen Profil auf, die zuletzt installierten Pakete zuletzt. Wenn ein regulärer Ausdruck REGEXP angegeben wird, werden nur installierte Pakete aufgeführt, deren Name zu REGEXP passt.

     Zu jedem installierten Paket werden folgende Informationen angezeigt, durch Tabulatorzeichen getrennt: der Paketname, die Version als Zeichenkette, welche Teile des Pakets installiert sind (zum Beispiel out, wenn die Standard-Paketausgabe installiert ist, include, wenn seine Header installiert sind, usw.) und an welchem Pfad das Paket im Store zu finden ist.

--list-available[=REGEXP]
-A [REGEXP]
     Listet Pakete auf, die in der aktuell installierten Distribution dieses Systems verfügbar sind (see GNU-Distribution). Wenn ein regulärer Ausdruck REGEXP angegeben wird, werden nur Pakete aufgeführt, deren Name zum regulären Ausdruck REGEXP passt.

     Zu jedem Paket werden folgende Informationen getrennt durch Tabulatorzeichen ausgegeben: der Name, die Version als Zeichenkette, die Teile des Programms (see Pakete mit mehreren Ausgaben.) und die Stelle im Quellcode, an der das Paket definiert ist.

--list-generations[=MUSTER]
-l [MUSTER]
     Liefert eine Liste der Generationen zusammen mit dem Datum, an dem sie erzeugt wurden; zu jeder Generation werden zudem die installierten Pakete angezeigt, zuletzt installierte Pakete zuletzt. Beachten Sie, dass die nullte Generation niemals angezeigt wird.

     Zu jedem installierten Paket werden folgende Informationen durch Tabulatorzeichen getrennt angezeigt: der Name des Pakets, die Version als Zeichenkette, welcher Teil des Pakets installiert ist (see Pakete mit mehreren Ausgaben.) und an welcher Stelle sich das Paket im Store befindet.

     Wenn ein MUSTER angegeben wird, liefert der Befehl nur dazu passende Generationen. Gültige Muster sind zum Beispiel:

       * Ganze Zahlen und kommagetrennte ganze Zahlen. Beide Muster bezeichnen Generationsnummern. Zum Beispiel liefert --list-generations=1 die erste Generation.

          Durch --list-generations=1,8,2 werden drei Generationen in der angegebenen Reihenfolge angezeigt. Weder Leerzeichen noch ein Komma am Schluss der Liste ist erlaubt.

       * Bereiche. --list-generations=2..9 gibt die angegebenen Generationen und alles dazwischen aus. Beachten Sie, dass der Bereichsanfang eine kleinere Zahl als das Bereichsende sein muss.

          Sie können auch kein Bereichsende angeben, zum Beispiel liefert --list-generations=2.. alle Generationen ab der zweiten.

       * Zeitdauern. Sie können auch die letzten N Tage, Wochen oder Monate angeben, indem Sie eine ganze Zahl gefolgt von jeweils »d«, »w« oder »m« angeben (dem ersten Buchstaben der Maßeinheit der Dauer im Englischen). Zum Beispiel listet --list-generations=20d die Generationen auf, die höchstens 20 Tage alt sind.

--delete-generations[=MUSTER]
-d [MUSTER]
     Wird kein MUSTER angegeben, werden alle Generationen außer der aktuellen entfernt.

     Dieser Befehl akzeptiert dieselben Muster wie --list-generations. Wenn ein MUSTER angegeben wird, werden die passenden Generationen gelöscht. Wenn das MUSTER für eine Zeitdauer steht, werden diejenigen Generationen gelöscht, die älter als die angegebene Dauer sind. Zum Beispiel löscht --delete-generations=1m die Generationen, die mehr als einen Monat alt sind.

     Falls die aktuelle Generation zum Muster passt, wird sie nicht gelöscht. Auch die nullte Generation wird niemals gelöscht.

     Beachten Sie, dass Sie auf gelöschte Generationen nicht zurückwechseln können. Dieser Befehl sollte also nur mit Vorsicht benutzt werden.

Zu guter Letzt können Sie, da guix package Erstellungsprozesse zu starten vermag, auch alle gemeinsamen Erstellungsoptionen (see Gemeinsame Erstellungsoptionen) verwenden. Auch Paketumwandlungsoptionen wie --with-source sind möglich (see Paketumwandlungsoptionen). Beachten Sie jedoch, dass die verwendeten Paketumwandlungsoptionen verloren gehen, nachdem Sie die Pakete aktualisiert haben. Damit Paketumwandlungen über Aktualisierungen hinweg erhalten bleiben, sollten Sie Ihre eigene Paketvariante in einem Guile-Modul definieren und zur Umgebungsvariablen GUIX_PACKAGE_PATH hinzufügen (see Pakete definieren).

Substitute
==========

Guix kann transparent Binär- oder Quelldateien ausliefern. Das heißt, Dinge können sowohl lokal erstellt, als auch als vorerstellte Objekte von einem Server heruntergeladen werden, oder beides gemischt. Wir bezeichnen diese vorerstellten Objekte als Substitute — sie substituieren lokale Erstellungsergebnisse. In vielen Fällen geht das Herunterladen eines Substituts wesentlich schneller, als Dinge lokal zu erstellen.

Substitute können alles sein, was das Ergebnis einer Ableitungserstellung ist (see Ableitungen). Natürlich sind sie üblicherweise vorerstellte Paket-Binärdateien, aber wenn zum Beispiel ein Quell-Tarball das Ergebnis einer Ableitungserstellung ist, kann auch er als Substitut verfügbar sein.

Offizieller Substitut-Server
----------------------------

The ci.guix.de.info server is a front-end to an official build farm that builds packages from Guix continuously for some architectures, and makes them available as substitutes.  This is the default source of substitutes; it can be overridden by passing the --substitute-urls option either to guix-daemon (see guix-daemon --substitute-urls)  or to client tools such as guix package (see client --substitute-urls option).

Substitut-URLs können entweder HTTP oder HTTPS sein. HTTPS wird empfohlen, weil die Kommunikation verschlüsselt ist; umgekehrt kann bei HTTP die Kommunikation belauscht werden, wodurch der Angreifer zum Beispiel erfahren könnte, ob Ihr System über noch nicht behobene Sicherheitsschwachstellen verfügt.

Substitute von der offiziellen Build-Farm sind standardmäßig erlaubt, wenn Sie die Guix-System-Distribution verwenden (see GNU-Distribution). Auf Fremddistributionen sind sie allerdings standardmäßig ausgeschaltet, solange Sie sie nicht ausdrücklich in einem der empfohlenen Installationsschritte erlaubt haben (see Installation). Die folgenden Absätze beschreiben, wie Sie Substitute für die offizielle Build-Farm an- oder ausschalten; dieselbe Prozedur kann auch benutzt werden, um Substitute für einen beliebigen anderen Substitutsserver zu erlauben.

Substitut-Server autorisieren
-----------------------------

To allow Guix to download substitutes from ci.guix.de.info or a mirror thereof, you must add its public key to the access control list (ACL) of archive imports, using the guix archive command (see Aufruf von guix archive).  Doing so implies that you trust ci.guix.de.info to not be compromised and to serve genuine substitutes.

The public key for ci.guix.de.info is installed along with Guix, in PREFIX/share/guix/ci.guix.de.info.pub, where PREFIX is the installation prefix of Guix.  If you installed Guix from source, make sure you checked the GPG signature of guix-VERSION.tar.gz, which contains this public key file. Then, you can run something like this:

     # guix archive --authorize < PREFIX/share/guix/ci.guix.de.info.pub

     Similarly, the hydra.gnu.org.pub file contains the public key of an independent build farm also run by the project, reachable at https://mirror.hydra.gnu.org.

Sobald es eingerichtet wurde, sollte sich die Ausgabe eines Befehls wie guix build von so etwas:

     $ guix build emacs --dry-run
     Folgende Ableitungen würden erstellt:
        /gnu/store/yr7bnx8xwcayd6j95r2clmkdl1qh688w-emacs-24.3.drv
        /gnu/store/x8qsh1hlhgjx6cwsjyvybnfv2i37z23w-dbus-1.6.4.tar.gz.drv
        /gnu/store/1ixwp12fl950d15h2cj11c73733jay0z-alsa-lib-1.0.27.1.tar.bz2.drv
        /gnu/store/nlma1pw0p603fpfiqy7kn4zm105r5dmw-util-linux-2.21.drv
     ...

in so etwas verwandeln:

     $ guix build emacs --dry-run
     112.3 MB würden heruntergeladen:
        /gnu/store/pk3n22lbq6ydamyymqkkz7i69wiwjiwi-emacs-24.3
        /gnu/store/2ygn4ncnhrpr61rssa6z0d9x22si0va3-libjpeg-8d
        /gnu/store/71yz6lgx4dazma9dwn2mcjxaah9w77jq-cairo-1.12.16
        /gnu/store/7zdhgp0n1518lvfn8mb96sxqfmvqrl7v-libxrender-0.9.7
     ...

This indicates that substitutes from ci.guix.de.info are usable and will be downloaded, when possible, for future builds.

Der Substitutsmechanismus kann global ausgeschaltet werden, indem Sie dem guix-daemon beim Starten die Befehlszeilenoption --no-substitutes übergeben (see Aufruf des guix-daemon). Er kann auch temporär ausgeschaltet werden, indem Sie --no-substitutes an guix package, guix build und andere Befehlszeilenwerkzeuge übergeben.

Substitutauthentifizierung
--------------------------

Guix erkennt, wenn ein verfälschtes Substitut benutzt würde, und meldet einen Fehler. Ebenso werden Substitute ignoriert, die nich signiert sind, oder nicht mit einem in der ACL aufgelisteten Schlüssel signiert sind.

Es gibt nur eine Ausnahme: Wenn ein unautorisierter Server Substitute anbietet, die Bit für Bit identisch mit denen von einem autorisierten Server sind, können sie auch vom unautorisierten Server heruntergeladen werden. Zum Beispiel, angenommen wir haben zwei Substitutserver mit dieser Befehlszeilenoption ausgewählt:

     --substitute-urls="https://a.example.org https://b.example.org"

Wenn in der ACL nur der Schlüssel für b.example.org aufgeführt wurde, aber a.example.org exakt dieselben Substitute anbietet, wird Guix auch Substitute von a.example.org herunterladen, weil es in der Liste zuerst kommt und als Spiegelserver für b.example.org aufgefasst werden kann. In der Praxis haben unabhängige Maschinen bei der Erstellung normalerweise dieselben Binärdateien als Ergebnis, dank bit-reproduzierbarer Erstellungen (siehe unten).

Wenn Sie HTTPS benutzen, wird das X.509-Zertifikat des Servers nicht validiert (mit anderen Worten, die Identität des Servers wird nicht authentifiziert), entgegen dem, was HTTPS-Clients wie Web-Browser normalerweise tun. Da Guix Substitutinformationen selbst überprüft, wie oben erklärt, wäre es unnötig (wohingegen mit X.509-Zertifikaten geprüft wird, ob ein Domain-Name zu öffentlichen Schlüsseln passt).

Proxy-Einstellungen
-------------------

Substitute werden über HTTP oder HTTPS heruntergeladen. Die Umgebungsvariable http_proxy kann in der Umgebung von guix-daemon definiert werden und wirkt sich dann auf das Herunterladen von Substituten aus. Beachten Sie, dass der Wert von http_proxy in der Umgebung, in der guix build, guix package und andere Client-Befehle ausgeführt werden, keine Rolle spielt.

Fehler bei der Substitution
---------------------------

Selbst wenn ein Substitut für eine Ableitung verfügbar ist, schlägt die versuchte Substitution manchmal fehl. Das kann aus vielen Gründen geschehen: die Substitutsserver könnten offline sein, das Substitut könnte kürzlich gelöscht worden sein, die Netzwerkverbindunge könnte unterbrochen worden sein, usw.

Wenn Substitute aktiviert sind und ein Substitut für eine Ableitung zwar verfügbar ist, aber die versuchte Substitution fehlschlägt, kann Guix versuchen, die Ableitung lokal zu erstellen, je nachdem, ob --fallback übergeben wurde (see common build option --fallback). Genauer gesagt, wird keine lokale Erstellung durchgeführt, solange kein --fallback angegeben wurde, und die Ableitung wird als Fehlschlag angesehen. Wenn --fallback übergeben wurde, wird Guix versuchen, die Ableitung lokal zu erstellen, und ob die Ableitung erfolgreich ist oder nicht, hängt davon ab, ob die lokale Erstellung erfolgreich ist oder nicht. Beachten Sie, dass, falls Substitute ausgeschaltet oder erst gar kein Substitut verfügbar ist, immer eine lokale Erstellung durchgeführt wird, egal ob --fallback übergeben wurde oder nicht.

Um eine Vorstellung zu bekommen, wieviele Substitute gerade verfügbar sind, können Sie den Befehl guix weather benutzen (see Aufruf von guix weather). Dieser Befehl zeigt Statistiken darüber an, wie es um die von einem Server verfügbaren Substitute steht.

Vom Vertrauen gegenüber Binärdateien
------------------------------------

Today, each individual's control over their own computing is at the mercy of institutions, corporations, and groups with enough power and determination to subvert the computing infrastructure and exploit its weaknesses.  While using ci.guix.de.info substitutes can be convenient, we encourage users to also build on their own, or even run their own build farm, such that ci.guix.de.info is less of an interesting target.  One way to help is by publishing the software you build using guix publish so that others have one more choice of server to download substitutes from (see Aufruf von guix publish).

Guix hat die richtigen Grundlagen, um die Reproduzierbarkeit von Erstellungen zu maximieren (see Funktionalitäten). In den meisten Fällen sollten unabhängige Erstellungen eines bestimmten Pakets zu bitweise identischen Ergebnissen führen. Wir können also mit Hilfe einer vielschichtigen Menge an unabhängigen Paketerstellungen die Integrität unseres Systems besser gewährleisten. Der Befehl guix challenge hat das Ziel, Nutzern zu ermöglichen, Substitutserver zu beurteilen, und Entwickler dabei zu unterstützen, nichtdeterministische Paketerstellungen zu finden (see Aufruf von guix challenge). Ebenso ermöglicht es die Befehlszeilenoption --check von guix build, dass Nutzer bereits installierte Substitute auf Echtheit zu prüfen, indem sie lokal nachgebaut werden (see guix build --check).

In Zukunft wollen wir, dass Guix Binärdateien an und von Nutzern peer-to-peer veröffentlichen kann. Wenn Sie mit uns dieses Projekt diskuttieren möchten, kommen Sie auf unsere Mailing-Liste guix-devel@gnu.org.

Pakete mit mehreren Ausgaben.
=============================

Oft haben in Guix definierte Pakete eine einzige Ausgabe — d.h. aus dem Quellpaket entsteht genau ein Verzeichnis im Store. Wenn Sie guix package -i glibc ausführen, wird die Standard-Paketausgabe des GNU-libc-Pakets installiert; die Standardausgabe wird out genannt, aber ihr Name kann weggelassen werden, wie sie an obigem Befehl sehen. In diesem speziellen Fall enthält die Standard-Paketausgabe von glibc alle C-Headerdateien, gemeinsamen Bibliotheken (»Shared Libraries«), statische Bibliotheken (»Static Libraries«), Dokumentation für Info sowie andere zusätzliche Dateien.

Manchmal ist es besser, die verschiedenen Arten von Dateien, die aus einem einzelnen Quellpaket hervorgehen, in getrennte Ausgaben zu unterteilen. Zum Beispiel installiert die GLib-C-Bibliothek (die von GTK und damit zusammenhängenden Paketen benutzt wird) mehr als 20 MiB an HTML-Seiten mit Referenzdokumentation. Um den Nutzern, die das nicht brauchen, Platz zu sparen, wird die Dokumentation in einer separaten Ausgabe abgelegt, genannt doc. Um also die Hauptausgabe von GLib zu installieren, zu der alles außer der Dokumentation gehört, ist der Befehl:

     guix package -i glib

Der Befehl, um die Dokumentation zu installieren, ist:

     guix package -i glib:doc

Manche Pakete installieren Programme mit unterschiedlich großem »Abhängigkeiten-Fußabdruck«. Zum Beispiel installiert das Paket WordNet sowohl Befehlszeilenwerkzeuge als auch grafische Benutzerschnittstellen (GUIs). Erstere hängen nur von der C-Bibliothek ab, während Letztere auch von Tcl/Tk und den zu Grunde liegenden X-Bibliotheken abhängen. Jedenfalls belassen wir deshalb die Befehlszeilenwerkzeuge in der Standard-Paketausgabe, während sich die GUIs in einer separaten Ausgabe befinden. So können Benutzer, die die GUIs nicht brauchen, Platz sparen. Der Befehl guix size kann dabei helfen, solche Situationen zu erkennen (see Aufruf von guix size). guix graph kann auch helfen (see Aufruf von guix graph).

In der GNU-Distribution gibt es viele solche Pakete mit mehreren Ausgaben. Andere Konventionen für Ausgabenamen sind zum Beispiel lib für Bibliotheken und eventuell auch ihre Header-Dateien,, bin für eigenständige Programme und debug für Informationen zur Fehlerbehandlung (see Dateien zur Fehlersuche installieren). Die Ausgaben eines Pakets stehen in der dritten Spalte der Anzeige von guix package --list-available (see Aufruf von guix package).

guix gc aufrufen
================

Pakete, die zwar installiert sind, aber nicht benutzt werden, können vom Müllsammler entfernt werden. Mit dem Befehl guix gc können Benutzer den Müllsammler ausdrücklich aufrufen, um Speicher im Verzeichnis /gnu/store freizugeben. Dies ist der einzige Weg, Dateien aus /gnu/store zu entfernen — das manuelle Entfernen von Dateien kann den Store irreparabel beschädigen!

Der Müllsammler kennt eine Reihe von Wurzeln: Jede Datei in /gnu/store, die von einer Wurzel aus erreichbar ist, gilt als lebendig und kann nicht entfernt werden; jede andere Datei gilt als tot und ist ein Kandidat, gelöscht zu werden. Die Menge der Müllsammlerwurzeln (kurz auch »GC-Wurzeln«, von englisch »Garbage Collector«) umfasst Standard-Benutzerprofile; standardmäßig werden diese Müllsammlerwurzeln durch symbolische Verknüpfungen in /var/guix/gcroots dargestellt. Neue Müllsammlerwurzeln können zum Beispiel mit guix build --root festgelegt werden (see Aufruf von guix build).

Bevor Sie mit guix gc --collect-garbage Speicher freimachen, wollen Sie vielleicht alte Generationen von Benutzerprofilen löschen, damit alte Paketerstellungen von diesen Generationen entfernt werden können. Führen Sie dazu guix package --delete-generations aus (see Aufruf von guix package).

Unsere Empfehlung ist, dass Sie den Müllsammler regelmäßig laufen lassen und wenn Sie wenig freien Speicherplatz zur Verfügung haben. Um zum Beispiel sicherzustellen, dass Sie mindestens 5 GB auf Ihrer Platte zur Verfügung haben, benutzen Sie einfach:

     guix gc -F 5G

It is perfectly safe to run as a non-interactive periodic job (see Geplante Auftragsausführung, for how to set up such a job).  Running guix gc with no arguments will collect as much garbage as it can, but that is often inconvenient: you may find yourself having to rebuild or re-download software that is ``dead'' from the GC viewpoint but that is necessary to build other pieces of software---e.g., the compiler tool chain.

Der Befehl guix gc hat drei Arbeitsmodi: Er kann benutzt werden, um als Müllsammler tote Dateien zu entfernen (das Standardverhalten), um ganz bestimmte, angegebene Datein zu löschen (mit der Befehlszeilenoption --delete), um Müllsammlerinformationen auszugeben oder fortgeschrittenere Anfragen zu verarbeiten. Die Müllsammler-Befehlszeilenoptionen sind wie folgt:

--collect-garbage[=MINIMUM]
-C [MINIMUM]
     Lässt Müll sammeln — z.B. nicht erreichbare Dateien in /gnu/store und seinen Unterverzeichnissen. Wird keine andere Befehlszeilenoption angegeben, wird standardmäßig diese durchgeführt.

     Wenn ein MINIMUM angegeben wurde, hört der Müllsammler auf, sobald MINIMUM Bytes gesammelt wurden. Das MINIMUM kann die Anzahl der Bytes bezeichnen oder mit einer Einheit als Suffix versehen sein, wie etwa MiB für Mebibytes und GB für Gigabytes (see size specifications (GNU Coreutils)).

     Wird kein MINIMUM angegeben, sammelt der Müllsammler allen Müll.

--free-space=MENGE
-F MENGE
     Sammelt Müll, bis die angegebene MENGE an freiem Speicher in /gnu/store zur Verfügung steht, falls möglich; die MENGE ist eine Speichergröße wie 500MiB, wie oben beschrieben.

     Wenn die angegebene  MENGE oder mehr bereits in /gnu/store frei verfügbar ist, passiert nichts.

--delete
-d
     Versucht, alle als Argumente angegebenen Dateien oder Verzeichnisse im Store zu löschen. Dies schlägt fehl, wenn manche der Dateien oder Verzeichnisse nicht im Store oder noch immer lebendig sind.

--list-failures
     Store-Objekte auflisten, die zwischengespeicherten Erstellungsfehlern entsprechen.

     Hierbei wird nichts ausgegeben, sofern der Daemon nicht mit --cache-failures gestartet wurde (see --cache-failures).

--clear-failures
     Die angegebenen Store-Objekte aus dem Zwischenspeicher für fehlgeschlagene Erstellungen entfernen.

     Auch diese Option macht nur Sinn, wenn der Daemon mit --cache-failures gestartet wurde. Andernfalls passiert nichts.

--list-dead
     Zeigt die Liste toter Dateien und Verzeichnisse an, die sich noch im Store befinden — das heißt, Dateien, die von keiner Wurzel mehr erreichbar sind.

--list-live
     Zeige die Liste lebendiger Store-Dateien und -Verzeichnisse.

Außerdem können Referenzen unter bestehenden Store-Dateien gefunden werden:

--references
--referrers
     Listet die referenzierten bzw. sie referenzierenden Objekte der angegebenen Store-Dateien auf.

--requisites
-R
     Listet alle Voraussetzungen der als Argumente übergebenen Store-Dateien auf. Voraussetzungen sind die Store-Dateien selbst, ihre Referenzen sowie die Referenzen davon, rekursiv. Mit anderen Worten, die zurückgelieferte Liste ist der transitive Abschluss dieser Store-Dateien.

     Der Abschnitt see Aufruf von guix size erklärt ein Werkzeug, um den Speicherbedarf des Abschlusses eines Elements zu ermitteln. Siehe Aufruf von guix graph für ein Werkzeug, um den Referenzgraphen zu veranschaulichen.

--derivers
     Liefert die Ableitung(en), die zu den angegebenen Store-Objekten führen (see Ableitungen).

     Zum Beispiel liefert dieser Befehl:

          guix gc --derivers `guix package -I ^emacs$ | cut -f4`

     die .drv-Datei(en), die zum in Ihrem Profil installierten emacs-Paket führen.

     Beachten Sie, dass es auch sein kann, dass keine passenden .drv-Dateien existieren, zum Beispiel wenn diese Dateien bereits dem Müllsammler zum Opfer gefallen sind. Es kann auch passieren, dass es mehr als eine passende .drv gibt, bei Ableitungen mit fester Ausgabe.

Zuletzt können Sie mit folgenden Befehlszeilenoptionen die Integrität des Stores prüfen und den Plattenspeicherverbrauch im Zaum halten.

--verify[=OPTIONEN]
     Die Integrität des Stores verifizieren

     Standardmäßig wird sichergestellt, dass alle Store-Objekte, die in der Datenbank des Daemons als gültig markiert wurden, auch tatsächlich in /gnu/store existieren.

     Wenn angegeben, müssen die OPTIONEN eine kommagetrennte Liste aus mindestens einem der Worte contents und repair sein.

     Wenn Sie --verify=contents übergeben, berechnet der Daemon den Hash des Inhalts jedes Store-Objekts und vergleicht ihn mit dem Hash in der Datenbank. Sind die Hashes ungleich, wird eine Datenbeschädigung gemeldet. Weil dabei alle Dateien im Store durchlaufen werden, kann der Befehl viel Zeit brauchen, besonders auf Systemen mit langsamer Platte.

     Mit --verify=repair oder --verify=contents,repair versucht der Daemon, beschädigte Store-Objekte zu reparieren, indem er Substitute für selbige herunterlädt (see Substitute). Weil die Reparatur nicht atomar und daher womöglich riskant ist, kann nur der Systemadministrator den Befehl benutzen. Eine weniger aufwendige Alternative, wenn Sie wissen, welches Objekt beschädigt ist, ist, guix build --repair zu benutzen (see Aufruf von guix build).

--optimize
     Den Store durch Nutzung harter Verknüpfungen für identische Dateien optimieren — mit anderen Worten wird der Store dedupliziert.

     Der Daemon führt Deduplizierung automatisch nach jeder erfolgreichen Erstellung und jedem Importieren eines Archivs durch, sofern er nicht mit --disable-deduplication (see --disable-deduplication) gestartet wurde. Diese Befehlszeilenoption brauchen Sie also in erster Linie dann, wenn der Daemon zuvor mit --disable-deduplication gestartet worden ist.

guix pull aufrufen
==================

Nach der Installation oder Aktualisierung wird stets die neueste Version von Paketen verwendet, die in der aktuell installierten Distribution verfügbar ist. Um die Distribution und die Guix-Werkzeuge zu aktualisieren, führen Sie guix pull aus. Der Befehl lädt den neuesten Guix-Quellcode einschließlich Paketbeschreibungen herunter und installiert ihn. Quellcode wird aus einem Git (https://git-scm.com)-Repository geladen, standardmäßig dem offiziellen Repository von GNU Guix, was Sie aber auch ändern können.

Danach wird guix package Pakete und ihre Versionen entsprechend der gerade heruntergeladenen Kopie von Guix benutzen. Nicht nur das, auch alle Guix-Befehle und Scheme-Module werden aus der neuesten Version von Guix kommen. Neue guix-Unterbefehle, die durch die Aktualisierung hinzugekommen sind, werden also auch verfügbar.

Jeder Nutzer kann seine Kopie von Guix mittels guix pull aktualisieren, wodurch sich nur für den Nutzer etwas verändert, der guix pull ausgeführt hat. Wenn also zum Beispiel der Administratornutzer root den Befehl guix pull ausführt, hat das keine Auswirkungen auf die für den Benutzer alice sichtbare Guix-Version, und umgekehrt.

Das Ergebnis von guix pull ist ein als ~/.config/guix/current verfügbares Profil mit dem neuesten Guix. Stellen Sie sicher, dass es am Anfang Ihres Suchpfades steht, damit Sie auch wirklich das neueste Guix und sein Info-Handbuch sehen (see Dokumentation):

     export PATH="$HOME/.config/guix/current/bin:$PATH"
     export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH"

Die Befehlszeilenoption --list-generations oder kurz -l listet ältere von guix pull erzeugte Generationen auf, zusammen mit Informationen zu deren Provenienz.

     $ guix pull -l
     Generation 1	Jun 10 2018 00:18:18
       guix 65956ad
         repository URL: https://git.savannah.gnu.org/git/guix.git
         branch: origin/master
         commit: 65956ad3526ba09e1f7a40722c96c6ef7c0936fe

     Generation 2	Jun 11 2018 11:02:49
       guix e0cc7f6
         repository URL: https://git.savannah.gnu.org/git/guix.git
         branch: origin/master
         commit: e0cc7f669bec22c37481dd03a7941c7d11a64f1d
       2 new packages: keepalived, libnfnetlink
       6 packages upgraded: emacs-nix-mode@2.0.4,
         guile2.0-guix@0.14.0-12.77a1aac, guix@0.14.0-12.77a1aac,
         heimdal@7.5.0, milkytracker@1.02.00, nix@2.0.4

     Generation 3	Jun 13 2018 23:31:07	(current)
       guix 844cc1c
         repository URL: https://git.savannah.gnu.org/git/guix.git
         branch: origin/master
         commit: 844cc1c8f394f03b404c5bb3aee086922373490c
       28 new packages: emacs-helm-ls-git, emacs-helm-mu, ...
       69 packages upgraded: borg@1.1.6, cheese@3.28.0, ...

Im Abschnitt guix describe werden andere Möglichkeiten erklärt, sich den momentanen Zustand von Guix beschreiben zu lassen.

Das Profil ~/.config/guix/current verhält sich genau wie jedes andere Profil, das von guix package erzeugt wurde (see Aufruf von guix package). Das bedeutet, Sie können seine Generationen auflisten und es auf die vorherige Generation — also das vorherige Guix — zurücksetzen und so weiter:

     $ guix package -p ~/.config/guix/current --roll-back
     switched from generation 3 to 2
     $ guix package -p ~/.config/guix/current --delete-generations=1
     deleting /var/guix/profiles/per-user/charlie/current-guix-1-link

Der Befehl guix pull wird in der Regel ohne Befehlszeilenargumente aufgerufen, aber er versteht auch folgende Befehlszeilenoptionen:

--url=URL
--commit=COMMIT
--branch=BRANCH
     Code wird von der angegebenen URL für den angegebenen COMMIT (eine gültige Commit-ID, dargestellt als hexadezimale Zeichenkette) oder BRANCH heruntergeladen.

     Diese Befehlszeilenoptionen sind manchmal bequemer, aber Sie können Ihre Konfiguration auch in der Datei ~/.config/guix/channels.scm oder über die Option --channels angeben (siehe unten).

--channels=DATEI
-C DATEI
     Die Liste der Kanäle aus der angegebenen DATEI statt aus ~/.config/guix/channels.scm auslesen. Die DATEI muss Scheme-Code enthalten, der zu einer Liste von Kanalobjekten ausgewertet wird. Siehe Kanäle für nähere Informationen.

--list-generations[=MUSTER]
-l [MUSTER]
     Alle Generationen von ~/.config/guix/current bzw., wenn ein MUSTER angegeben wird, die dazu passenden Generationen auflisten. Die Syntax für das MUSTER ist dieselbe wie bei guix package --list-generations (see Aufruf von guix package).

     Im Abschnitt guix describe wird eine Möglichkeit erklärt, sich Informationen nur über die aktuelle Generation anzeigen zu lassen.

--profile=PROFIL
-p PROFIL
     Auf PROFIL anstelle von ~/.config/guix/current arbeiten.

--dry-run
-n
     Anzeigen, welche(r) Commit(s) für die Kanäle benutzt würde(n) und was jeweils erstellt oder substituiert würde, ohne es tatsächlich durchzuführen.

--system=SYSTEM
-s SYSTEM
     Versuchen, für die angegebene Art von SYSTEM geeignete Binärdateien zu erstellen — z.B. i686-linux — statt für die Art von System, das die Erstellung durchführt.

--verbose
     Ausführliche Informationen ausgeben und Erstellungsprotokolle auf der Standardfehlerausgabe ausgeben.

--bootstrap
     Das neueste Guix mit dem Bootstrap-Guile erstellen. Diese Befehlszeilenoption ist nur für Guix-Entwickler von Nutzen.

Mit Hilfe von Kanälen können Sie bei guix pull anweisen, von welchem Repository und welchem Branch Guix aktualisiert werden soll, sowie von welchen weiteren Repositorys Paketmodule bezogen werden sollen. Im Abschnitt see Kanäle finden Sie nähere Informationen.

Außerdem unterstützt guix pull alle gemeinsamen Erstellungsoptionen (see Gemeinsame Erstellungsoptionen).

Kanäle
======

Guix und die Sammlung darin verfügbarer Pakete können Sie durch Ausführen von guix pull aktualisieren (see Aufruf von guix pull). Standardmäßig lädt guix pull Guix selbst vom offiziellen Repository von GNU Guix herunter und installiert es. Diesen Vorgang können Sie anpassen, indem Sie Kanäle in der Datei ~/.config/guix/channels.scm angeben. Ein Kanal enthält eine Angabe einer URL und eines Branches eines zu installierenden Git-Repositorys und Sie können guix pull veranlassen, die Aktualisierungen von einem oder mehreren Kanälen zu beziehen. Mit anderen Worten können Kanäle benutzt werden, um Guix anzupassen und zu erweitern, wie wir im Folgenden sehen werden.

Einen eigenen Guix-Kanal benutzen
---------------------------------

Der Kanal namens guix gibt an, wovon Guix selbst — seine Befehlszeilenwerkzeuge und seine Paketsammlung — heruntergeladen werden sollten. Wenn Sie zum Beispiel mit Ihrer eigenen Kopie des Guix-Repositorys arbeiten möchten und diese auf example.org zu finden ist, und zwar im Branch namens super-hacks, dann schreiben Sie folgende Spezifikation in ~/.config/guix/channels.scm:

     ;; 'guix pull' mein eigenes Repository benutzen lassen.
     (list (channel
             (name 'guix)
             (url "https://example.org/my-guix.git")
             (branch "super-hacks")))

Ab dann wird guix pull seinen Code vom Branch super-hacks des Repositorys auf example.org beziehen.

Weitere Kanäle angeben
----------------------

Sie können auch weitere Kanäle als Bezugsquelle angeben. Sagen wir, Sie haben ein paar eigene Paketvarianten oder persönliche Pakete, von denen Sie meinen, dass sie nicht geeignet sind, ins Guix-Projekt selbst aufgenommen zu werden, die Ihnen aber dennoch wie andere Pakete auf der Befehlszeile zur Verfügung stehen sollen. Dann würden Sie zunächst Module mit diesen Paketdefinitionen schreiben (see Paketmodule) und diese dann in einem Git-Repository verwalten, welches Sie selbst oder jeder andere dann als zusätzlichen Kanal eintragen können, von dem Pakete geladen werden. Klingt gut, oder?

     Bevor Sie, verehrter Nutzer, ausrufen: »Wow, das ist soooo coool!«, und Ihren eigenen Kanal der Welt zur Verfügung stellen, möchten wir Ihnen auch ein paar Worte der Warnung mit auf den Weg geben:

       * Bevor Sie einen Kanal veröffentlichen, überlegen Sie sich bitte erst, ob Sie die Pakete nicht besser zum eigentlichen Guix-Projekt beisteuern (see Mitwirken). Das Guix-Projekt ist gegenüber allen Arten freier Software offen und zum eigentlichen Guix gehörende Pakete stehen allen Guix-Nutzern zur Verfügung, außerdem profitieren sie von Guix’ Qualitätssicherungsprozess.

       * Wenn Sie Paketdefinitionen außerhalb von Guix betreuen, sehen wir Guix-Entwickler es als Ihre Aufgabe an, deren Kompatibilität sicherzstellen. Bedenken Sie, dass Paketmodule und Paketdefinitionen nur Scheme-Code sind, der verschiedene Programmierschnittstellen (APIs) benutzt. Wir nehmen uns das Recht heraus, diese APIs jederzeit zu ändern, damit wir Guix besser machen können, womöglich auf eine Art, wodurch Ihr Kanal nicht mehr funktioniert. Wir ändern APIs nie einfach so, werden aber auch nicht versprechen, APIs nicht zu verändern.

       * Das bedeutet auch, dass Sie, wenn Sie einen externen Kanal verwenden und dieser kaputt geht, Sie dies bitte den Autoren des Kanals und nicht dem Guix-Projekt melden.

     Wir haben Sie gewarnt! Allerdings denken wir auch, dass externe Kanäle eine praktische Möglichkeit sind, die Paketsammlung von Guix zu ergänzen und Ihre Verbesserungen mit anderen zu teilen, wie es dem Grundgedanken freier Software (https://www.gnu.org/philosophy/free-sw.html) entspricht. Bitte schicken Sie eine E-Mail an guix-devel@gnu.org, wenn Sie dies diskutieren möchten.

To use a channel, write ~/.config/guix/channels.scm to instruct guix pull to pull from it in addition to the default Guix channel(s):

     ;; Meine persönlichen Pakete zu denen von Guix dazunehmen.
     (cons (channel
             (name 'meine-persönlichen-pakete)
             (url "https://example.org/personal-packages.git"))
           %default-channels)

Note that the snippet above is (as always!) Scheme code; we use cons to add a channel the list of channels that the variable %default-channels is bound to (see cons and lists (GNU Guile Reference Manual)).  With this file in place, guix pull builds not only Guix but also the package modules from your own repository.  The result in ~/.config/guix/current is the union of Guix with your own package modules:

     $ guix pull --list-generations
     ...
     Generation 19	Aug 27 2018 16:20:48
       guix d894ab8
         repository URL: https://git.savannah.gnu.org/git/guix.git
         branch: master
         commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300
       meine-persönlichen-pakete dd3df5e
         repository URL: https://example.org/personal-packages.git
         branch: master
         commit: dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb
       11 new packages: mein-gimp, mein-emacs-mit-coolen-features, ...
       4 packages upgraded: emacs-racket-mode@0.0.2-2.1b78827, ...

Obige Ausgabe von guix pull zeigt an, dass Generation 19 sowohl Guix als auch Pakete aus dem Kanal meine-persönlichen-pakete enthält. Unter den aufgeführten neuen und aktualisierten Paketen kommen vielleicht manche wie mein-gimp und mein-emacs-mit-coolen-features aus meine-persönlichen-pakete, während andere aus dem Standard-Guix-Kanal kommen.

To create a channel, create a Git repository containing your own package modules and make it available.  The repository can contain anything, but a useful channel will contain Guile modules that export packages.  Once you start using a channel, Guix will behave as if the root directory of that channel's Git repository has been added to the Guile load path (see Load Paths (GNU Guile Reference Manual)).  For example, if your channel contains a file at my-packages/my-tools.scm that defines a Guile module, then the module will be available under the name (my-packages my-tools), and you will be able to use it like any other module (see Module (GNU Guile Reference Manual)).

Declaring Channel Dependencies
------------------------------

Channel authors may decide to augment a package collection provided by other channels.  They can declare their channel to be dependent on other channels in a meta-data file .guix-channel, which is to be placed in the root of the channel repository.

The meta-data file should contain a simple S-expression like this:

     (channel
      (version 0)
      (dependencies
       (channel
        (name some-collection)
        (url "https://example.org/first-collection.git"))
       (channel
        (name some-other-collection)
        (url "https://example.org/second-collection.git")
        (branch "testing"))))

In the above example this channel is declared to depend on two other channels, which will both be fetched automatically.  The modules provided by the channel will be compiled in an environment where the modules of all these declared channels are available.

For the sake of reliability and maintainability, you should avoid dependencies on channels that you don't control, and you should aim to keep the number of dependencies to a minimum.

Guix nachbilden
---------------

Die Ausgabe von guix pull --list-generations oben zeigt genau, aus welchen Commits diese Guix-Instanz erstellt wurde. Wir können Guix so zum Beispiel auf einer anderen Maschine nachbilden, indem wir eine Kanalspezifikation in ~/.config/guix/channels.scm angeben, die auf diese Commits »festgesetzt« ist.

     ;; Ganz bestimmte Commits der relevanten Kanäle installieren.
     (list (channel
            (name 'guix)
            (url "https://git.savannah.gnu.org/git/guix.git")
            (commit "d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300"))
           (channel
            (name 'meine-persönlichen-pakete)
            (url "https://example.org/personal-packages.git")
            (branch "dd3df5e2c8818760a8fc0bd699e55d3b69fef2bb")))

Der Befehl guix describe --format=channels kann diese Kanalliste sogar direkt erzeugen (see Aufruf von guix describe).

Somit läuft auf beiden Maschinen genau dasselbe Guix und es hat Zugang zu genau denselben Paketen. Die Ausgabe von guix build gimp auf der einen Maschine wird Bit für Bit genau dieselbe wie die desselben Befehls auf der anderen Maschine sein. Das bedeutet auch, dass beide Maschinen Zugang zum gesamten Quellcode von Guix und daher auch transitiv Zugang zum Quellcode jedes davon definierten Pakets haben.

Das verleiht Ihnen Superkräfte, mit denen Sie die Provenienz binärer Artefakte sehr feinkörnig nachverfolgen können und Software-Umgebungen nach Belieben nachbilden können. Sie können es als eine Art Fähigkeit zur »Meta-Reproduzierbarkeit« auffassen, wenn Sie möchten. Der Abschnitt see Untergeordnete beschreibt eine weitere Möglichkeit, diese Superkräfte zu nutzen.

Untergeordnete
==============

     Die hier beschriebenen Funktionalitäten sind in der Version VERSION bloß eine »Technologie-Vorschau«, daher kann sich die Schnittstelle in Zukunft noch ändern.

Manchmal könnten Sie Pakete aus der gerade laufenden Fassung von Guix mit denen mischen wollen, die in einer anderen Guix-Version verfügbar sind. Guix-Untergeordnete ermöglichen dies, indem Sie verschiedene Guix-Versionen beliebig mischen können.

Aus technischer Sicht ist ein »Untergeordneter« im Kern ein separater Guix-Prozess, der über eine REPL (see Aufruf von guix repl) mit Ihrem Haupt-Guix-Prozess verbunden ist. Das Modul (guix inferior) ermöglicht es Ihnen, Untergeordnete zu erstellen und mit ihnen zu kommunizieren. Dadurch steht Ihnen auch eine hochsprachliche Schnittstelle zur Verfügung, um die von einem Untergeordneten angebotenen Pakete zu durchsuchen und zu verändern — untergeordnete Pakete.

In Kombination mit Kanälen (see Kanäle) bieten Untergeordnete eine einfache Möglichkeit, mit einer anderen Version von Guix zu interagieren. Nehmen wir zum Beispiel an, Sie wollen das aktuelle guile-Paket in Ihr Profil installieren, zusammen mit dem guile-json, wie es in einer früheren Guix-Version existiert hat — vielleicht weil das neuere guile-json eine inkompatible API hat und Sie daher Ihren Code mit der alten API benutzen möchten. Dazu könnten Sie ein Manifest für guix package --manifest schreiben (see Aufruf von guix package); in diesem Manifest würden Sie einen Untergeordneten für diese alte Guix-Version erzeugen, für die Sie sich interessieren, und aus diesem Untergeordneten das guile-json-Paket holen:

     (use-modules (guix inferior) (guix channels)
                  (srfi srfi-1))   ;für die Prozedur 'first'

     (define channels
       ;; Dies ist die alte Version, aus der wir
       ;; guile-json extrahieren möchten.
       (list (channel
              (name 'guix)
              (url "https://git.savannah.gnu.org/git/guix.git")
              (commit
               "65956ad3526ba09e1f7a40722c96c6ef7c0936fe"))))

     (define inferior
       ;; Ein Untergeordneter, der obige Version repräsentiert.
       (inferior-for-channels channels))

     ;; Daraus erzeugen wir jetzt ein Manifest mit dem aktuellen
     ;; »guile«-Paket und dem alten »guile-json«-Paket.
     (packages->manifest
      (list (first (lookup-inferior-packages inferior "guile-json"))
            (specification->package "guile")))

Bei seiner ersten Ausführung könnte für guix package --manifest erst der angegebene Kanal erstellt werden müssen, bevor der Untergeordnete erstellt werden kann; nachfolgende Durchläufe sind wesentlich schneller, weil diese Guix-Version bereits zwischengespeichert ist.

Folgende Prozeduren werden im Modul (guix inferior) angeboten, um einen Untergeordneten zu öffnen:

 -- Scheme-Prozedur: inferior-for-channels KANÄLE
     [#:cache-directory] [#:ttl] Liefert einen Untergeordneten für die
     KANÄLE, einer Liste von Kanälen. Dazu wird der Zwischenspeicher im Verzeichnis CACHE-DIRECTORY benutzt, dessen Einträge nach TTL Sekunden gesammelt werden dürfen. Mit dieser Prozedur wird eine neue Verbindung zum Erstellungs-Daemon geöffnet.

     Als Nebenwirkung erstellt oder substituiert diese Prozedur unter Umständen Binärdateien für die KANÄLE, was einige Zeit in Anspruch nehmen kann.

 -- Scheme-Prozedur: open-inferior VERZEICHNIS
     [#:command "bin/guix"] Öffnet das untergeordnete Guix mit dem Befehl
     COMMAND im angegebenen VERZEICHNIS durch Ausführung von VERZEICHNIS/COMMAND repl oder entsprechend. Liefert #f, wenn der Untergeordnete nicht gestartet werden konnte.

Die im Folgenden aufgeführten Prozeduren ermöglichen es Ihnen, untergeordnete Pakete abzurufen und zu verändern.

 -- Scheme-Prozedur: inferior-packages UNTERGEORDNETER
     Liefert die Liste der Pakete in UNTERGEORDNETER.

 -- Scheme-Prozedur: lookup-inferior-packages UNTERGEORDNETER NAME
     [VERSION] Liefert die sortierte Liste der untergeordneten Pakete in
     UNTERGEORDNETER, die zum Muster NAME in UNTERGEORDNETER passen, dabei kommen höhere Versionsnummern zuerst. Wenn VERSION auf wahr gesetzt ist, werden nur Pakete geliefert, deren Versionsnummer mit dem Präfix VERSION beginnt.

 -- Scheme-Prozedur: inferior-package? OBJEKT
     Liefert wahr, wenn das OBJ ein Untergeordneter ist.

 -- Scheme-Prozedur: inferior-package-name PAKET
 -- Scheme-Prozedur: inferior-package-version PAKET
 -- Scheme-Prozedur: inferior-package-synopsis PAKET
 -- Scheme-Prozedur: inferior-package-description PAKET
 -- Scheme-Prozedur: inferior-package-home-page PAKET
 -- Scheme-Prozedur: inferior-package-location PAKET
 -- Scheme-Prozedur: inferior-package-inputs PAKET
 -- Scheme-Prozedur: inferior-package-native-inputs PAKET
 -- Scheme-Prozedur: inferior-package-propagated-inputs PAKET
 -- Scheme-Prozedur: inferior-package-transitive-propagated-inputs PAKET
 -- Scheme-Prozedur: inferior-package-native-search-paths PAKET
 -- Scheme-Prozedur: inferior-package-transitive-native-search-paths PAKET
 -- Scheme-Prozedur: inferior-package-search-paths PAKET
     Diese Prozeduren sind das Gegenstück zu den Zugriffsmethoden des Verbunds »package« für Pakete (see »package«-Referenz). Die meisten davon funktionieren durch eine Abfrage auf dem Untergeordneten, von dem das PAKET kommt, weshalb der Untergeordnete noch lebendig sein muss, wenn Sie diese Prozeduren aufrufen.

Untergeordnete Pakete können transparent wie jedes andere Paket oder dateiartige Objekt in G-Ausdrücken verwendet werden (see G-Ausdrücke). Sie werden auch transparent wie reguläre Pakete von der Prozedur packages->manifest behandelt, welche oft in Manifesten benutzt wird (see siehe die Befehlszeilenoption --manifest von guix package). Somit können Sie ein untergeordnetes Paket ziemlich überall dort verwenden, wo Sie ein reguläres Paket einfügen würden: in Manifesten, im Feld packages Ihrer operating-system-Deklaration und so weiter.

guix describe aufrufen
======================

Sie könnten sich des Öfteren Fragen stellen wie: »Welche Version von Guix benutze ich gerade?« oder »Welche Kanäle benutze ich?« Diese Informationen sind in vielen Situationen nützlich: wenn Sie eine Umgebung auf einer anderen Maschine oder mit einem anderen Benutzerkonto nachbilden möchten, wenn Sie einen Fehler melden möchten, wenn Sie festzustellen versuchen, welche Änderung an den von Ihnen verwendeten Kanälen diesen Fehler verursacht hat, oder wenn Sie Ihren Systemzustand zum Zweck der Reproduzierbarkeit festhalten möchten. Der Befehl guix describe gibt Ihnen Antwort auf diese Fragen.

Wenn Sie ihn aus einem mit guix pull bezogenen guix heraus ausführen, zeigt Ihnen guix describe die Kanäle an, aus denen es erstellt wurde, jeweils mitsamt ihrer Repository-URL und Commit-ID (see Kanäle):

     $ guix describe
     Generation 10	Sep 03 2018 17:32:44	(current)
       guix e0fa68c
         repository URL: https://git.savannah.gnu.org/git/guix.git
         branch: master
         commit: e0fa68c7718fffd33d81af415279d6ddb518f727

Wenn Sie mit dem Versionskontrollsystem Git vertraut sind, erkennen Sie vielleicht die Ähnlichkeit zu git describe; die Ausgabe ähnelt auch der von guix pull --list-generations eingeschränkt auf die aktuelle Generation (see die Befehlszeilenoption --list-generations). Weil die oben gezeigte Git-Commit-ID eindeutig eine bestimmte Version von Guix bezeichnet, genügt diese Information, um die von Ihnen benutzte Version von Guix zu beschreiben, und auch, um sie nachzubilden.

Damit es leichter ist, Guix nachzubilden, kann Ihnen guix describe auch eine Liste der Kanäle statt einer menschenlesbaren Beschreibung wie oben liefern:

     $ guix describe -f channels
     (list (channel
             (name 'guix)
             (url "https://git.savannah.gnu.org/git/guix.git")
             (commit
               "e0fa68c7718fffd33d81af415279d6ddb518f727")))

Sie können die Ausgabe in einer Datei speichern, die Sie an guix pull -C auf einer anderen Maschine oder zu einem späteren Zeitpunkt übergeben, wodurch dann eine Instanz von genau derselben Guix-Version installiert wird (see die Befehlszeilenoption -C). Daraufhin können Sie, weil Sie jederzeit dieselbe Version von Guix installieren können, auch gleich eine vollständige Softwareumgebung genau nachbilden. Wir halten das trotz aller Bescheidenheit für klasse und hoffen, dass Ihnen das auch gefällt!

Die genauen Befehlszeilenoptionen, die guix describe unterstützt, lauten wie folgt:

--format=FORMAT
-f FORMAT
     Die Ausgabe im angegebenen FORMAT generieren, was eines der Folgenden sein muss:

     human
          für menschenlesbare Ausgabe,

     Kanäle
          eine Liste von Kanalspezifikationen erzeugen, die an guix pull -C übergeben werden oder als ~/.config/guix/channels.scm eingesetzt werden können (see Aufruf von guix pull),

     json
          generiert eine Liste von Kanalspezifikationen im JSON-Format,

     recutils
          generiert eine Liste von Kanalspezifikationen im Recutils-Format.

--profile=PROFIL
-p PROFIL
     Informationen über das PROFIL anzeigen.

guix archive aufrufen
=====================

Der Befehl guix archive ermöglicht es Nutzern, Dateien im Store in eine einzelne Archivdatei zu exportieren und diese später auf einer Maschine, auf der Guix läuft, zu importieren. Insbesondere können so Store-Objekte von einer Maschine in den Store einer anderen Maschine übertragen werden.

     Wenn Sie nach einer Möglichkeit suchen, Archivdateien für andere Werkzeuge als Guix zu erstellen, finden Sie Informationen dazu im Abschnitt see Aufruf von guix pack.

Führen Sie Folgendes aus, um Store-Dateien als ein Archiv auf die Standardausgabe zu exportieren:

     guix archive --export OPTIONEN SPEZIFIKATIONEN...

SPEZIFIKATIONEN sind dabei entweder die Namen von Store-Dateien oder Paketspezifikationen wie bei guix package (see Aufruf von guix package). Zum Beispiel erzeugt der folgende Befehl ein Archiv der gui-Ausgabe des Pakets git sowie die Hauptausgabe von emacs:

     guix archive --export git:gui /gnu/store/...-emacs-24.3 > groß.nar

Wenn die angegebenen Pakete noch nicht erstellt worden sind, werden sie durch guix archive automatisch erstellt. Der Erstellungsprozess kann durch die gemeinsamen Erstellungsoptionen gesteuert werden (see Gemeinsame Erstellungsoptionen).

Um das emacs-Paket auf eine über SSH verbundene Maschine zu übertragen, würde man dies ausführen:

     guix archive --export -r emacs | ssh die-maschine guix archive --import

Auf gleiche Art kann auch ein vollständiges Benutzerprofil von einer Maschine auf eine andere übertragen werden:

     guix archive --export -r $(readlink -f ~/.guix-profile) | \
       ssh die-maschine guix-archive --import

Jedoch sollten Sie in beiden Beispielen beachten, dass alles, was zu emacs, dem Profil oder deren Abhängigkeiten (wegen -r) gehört, übertragen wird, egal ob es schon im Store der Zielmaschine vorhanden ist oder nicht. Mit der Befehlszeilenoption --missing lässt sich herausfinden, welche Objekte im Ziel-Store noch fehlen. Der Befehl guix copy vereinfacht und optimiert diesen gesamten Prozess, ist also, was Sie in diesem Fall wahrscheinlich eher benutzen wollten (see Aufruf von guix copy).

Archive werden als »Normalisiertes Archiv«, kurz »Nar«, formatiert. Diese Technik folgt einem ähnlichen Gedanken wie beim »tar«-Format, unterscheidet sich aber auf eine für unsere Zwecke angemessene Art. Erstens werden im Nar-Format nicht sämtliche Unix-Metadaten aller Dateien aufgenommen, sondern nur der Dateityp (ob es sich um eine reguläre Datei, ein Verzeichnis oder eine symbolische Verknüpfung handelt). Unix-Dateiberechtigungen sowie Besitzer und Gruppe werden nicht gespeichert. Zweitens entspricht die Reihenfolge, in der der Inhalt von Verzeichnissen abgelegt wird, immer der Reihenfolge, in der die Dateinamen gemäß der C-Locale sortiert würden. Dadurch wird die Erstellung von Archivdateien völlig deterministisch.

Beim Exportieren versieht der Daemon den Inhalt des Archivs mit einer digitalen Signatur.  Diese digitale Signatur wird an das Archiv angehängt. Beim Importieren verifiziert der Daemon die Signatur und lehnt den Import ab, falls die Signatur ungültig oder der signierende Schlüssel nicht autorisiert ist.

Die wichtigsten Befehlszeilenoptionen sind:

--export
     Exportiert die angegebenen Store-Dateien oder Pakete (siehe unten) und schreibt das resultierende Archiv auf die Standardausgabe.

     Abhängigkeiten fehlen in der Ausgabe, außer wenn --recursive angegeben wurde.

-r
--recursive
     Zusammen mit --export wird guix archive hiermit angewiesen, Abhängigkeiten der angegebenen Objekte auch ins Archiv aufzunehmen. Das resultierende Archiv ist somit eigenständig; es enthält den Abschluss der exportierten Store-Objekte.

--import
     Ein Archiv von der Standardeingabe lesen und darin enthaltende Dateien in den Store importieren. Der Import bricht ab, wenn das Archiv keine gültige digitale Signatur hat oder wenn es von einem öffentlichen Schlüssel signiert wurde, der keiner der autorisierten Schlüssel ist (siehe --authorize weiter unten).

--missing
     Eine Liste der Store-Dateinamen von der Standardeingabe lesen, je ein Name pro Zeile, und auf die Standardausgabe die Teilmenge dieser Dateien schreiben, die noch nicht im Store vorliegt.

--generate-key[=PARAMETER]
     Ein neues Schlüsselpaar für den Daemon erzeugen. Dies ist erforderlich, damit Archive mit --export exportiert werden können. Beachten Sie, dass diese Option normalerweise einige Zeit in Anspruch nimmt, da erst Entropie für die Erzeugung des Schlüsselpaares gesammelt werden muss.

     Das erzeugte Schlüsselpaar wird typischerweise unter /etc/guix gespeichert, in den Dateien signing-key.pub (für den öffentlichen Schlüssel) und signing-key.sec (für den privaten Schlüssel, der geheim gehalten werden muss). Wurden keine PARAMETERS angegeben, wird ein ECDSA-Schlüssel unter Verwendung der Kurve Ed25519 erzeugt, oder, falls die Libgcrypt-Version älter als 1.6.0 ist, ein 4096-Bit-RSA-Schlüssel. Sonst geben die PARAMETER für Libgcrypt geeignete Parameter für genkey an (see gcry_pk_genkey (The Libgcrypt Reference Manual)).

--authorize
     Mit dem auf der Standardeingabe übergebenen öffentlichen Schlüssel signierte Importe autorisieren. Der öffentliche Schlüssel muss als »advanced«-formatierter S-Ausdruck gespeichert sein, d.h. im selben Format wie die Datei signing-key.pub.

     Die Liste autorisierter Schlüssel wird in der Datei /etc/guix/acl gespeichert, die auch von Hand bearbeitet werden kann. Die Datei enthält »advanced«-formatierte S-Ausdrücke (http://people.csail.mit.edu/rivest/Sexp.txt) und ist als eine Access Control List für die Simple Public-Key Infrastructure (SPKI) (http://theworld.com/~cme/spki.txt) aufgebaut.

--extract=VERZEICHNIS
-x VERZEICHNIS
     Ein Archiv mit einem einzelnen Objekt lesen, wie es von Substitutservern geliefert wird (see Substitute) und ins VERZEICHNIS entpacken. Dies ist eine systemnahe Operation, die man nur selten direkt benutzt; siehe unten.

     For example, the following command extracts the substitute for Emacs served by ci.guix.de.info to /tmp/emacs:

          $ wget -O - \
            https://ci.guix.de.info/nar/...-emacs-24.5 \
            | bunzip2 | guix archive -x /tmp/emacs

     Archive mit nur einem einzelnen Objekt unterscheiden sich von Archiven für mehrere Dateien, wie sie guix archive --export erzeugt; sie enthalten nur ein einzelnes Store-Objekt und keine eingebettete Signatur. Beim Entpacken findet also keine Signaturprüfung statt und ihrer Ausgabe sollte so erst einmal nicht vertraut werden.

     Der eigentliche Zweck dieser Operation ist, die Inspektion von Archivinhalten von Substitutservern möglich zu machen, auch wenn diesen unter Umständen nicht vertraut wird.

Development
***********

If you are a software developer, Guix provides tools that you should find helpful---independently of the language you're developing in.  This is what this chapter is about.

The guix environment command provides a convenient way to set up development environments containing all the dependencies and tools necessary to work on the software package of your choice.  The guix pack command allows you to create application bundles that can be easily distributed to users who do not run Guix.

guix environment aufrufen
=========================

Der Zweck von guix environment ist es, Hacker beim Aufbau einer reproduzierbaren Entwicklungsumgebung zu unterstützen, ohne dass diese ihr Paketprofil verunreinigen müssen. Das Werkzeug guix environment nimmt eines oder mehrere Pakete entgegen und erstellt erst all ihre Eingaben, um dann eine Shell-Umgebung herzustellen, in der diese benutzt werden können.

Die allgemeine Syntax lautet:

     guix environment OPTIONEN PAKET...

Folgendes Beispiel zeigt, wie eine neue Shell gestartet wird, auf der alles für die Entwicklung von GNU Guile eingerichtet ist:

     guix environment guile

Wenn benötigte Abhängigkeiten noch nicht erstellt worden sind, wird guix environment sie automatisch erstellen lassen. Die Umgebung der neuen Shell ist eine ergänzte Version der Umgebung, in der guix environment ausgeführt wurde. Sie enthält neben den existierenden Umgebungsvariablen auch die nötigen Suchpfade, um das angegebene Paket erstellen zu können. Um eine »reine« Umgebung zu erstellen, in der die ursprünglichen Umgebungsvariablen nicht mehr vorkommen, kann die Befehlszeilenoption --pure benutzt werden (Manchmal ergänzen Nutzer fälschlicherweise Umgebungsvariable wie PATH in ihrer ~/.bashrc-Datei. Das hat zur Folge, dass wenn guix environment Bash startet, selbige ~/.bashrc von Bash gelesen wird und die neuen Umgebungen somit »verunreinigt«. Es ist ein Fehler, solche Umgebungsvariable in .bashrc zu definieren, stattdessen sollten sie in .bash_profile geschrieben werden, was nur von Login-Shells mit »source« geladen wird. See Bash Startup Files (The GNU Bash Reference Manual), für Details über beim Starten von Bash gelesene Dateien).

guix environment definiert die Variable GUIX_ENVIRONMENT in der neu erzeugten Shell. Ihr Wert ist der Dateiname des Profils dieser neuen Umgebung. Das könnten Nutzer verwenden, um zum Beispiel eine besondere Prompt als Eingabeaufforderung für Entwicklungsumgebungen in ihrer .bashrc festzulegen (see Bash Startup Files (The GNU Bash Reference Manual)):

     if [ -n "$GUIX_ENVIRONMENT" ]
     then
         export PS1="\u@\h \w [dev]\$ "
     fi

... or to browse the profile:

     $ ls "$GUIX_ENVIRONMENT/bin"

Des Weiteren kann mehr als ein Paket angegeben werden. In diesem Fall wird die Vereinigung der Eingaben der jeweiligen Pakete zugänglich gemacht. Zum Beispiel erzeugt der folgende Befehl eine Shell, in der alle Abhängigkeiten von sowohl Guile als auch Emacs verfügbar sind:

     guix environment guile emacs

Manchmal will man keine interaktive Shell-Sitzung. Ein beliebiger Befehl kann aufgerufen werden, indem man nach Angabe der Pakete noch -- vor den gewünschten Befehl schreibt, um ihn von den übrigen Argumenten abzutrennen:

     guix environment guile -- make -j4

In anderen Situationen ist es bequemer, aufzulisten, welche Pakete in der Umgebung benötigt werden. Zum Beispiel führt der folgende Befehl python aus einer Umgebung heraus aus, in der Python 2.7 und NumPy enthalten sind:

     guix environment --ad-hoc python2-numpy python-2.7 -- python

Man kann auch sowohl die Abhängigkeiten eines Pakets haben wollen, als auch ein paar zusätzliche Pakete, die nicht Erstellungs- oder Laufzeitabhängigkeiten davon sind, aber trotzdem bei der Entwicklung nützlich sind. Deshalb hängt die Wirkung von der Position der Befehlszeilenoption --ad-hoc ab. Pakete, die links von --ad-hoc stehen, werden als Pakete interpretiert, deren Abhängigkeiten zur Umgebung hinzugefügt werden. Pakete, die rechts stehen, werden selbst zur Umgebung hinzugefügt. Zum Beispiel erzeugt der folgende Befehl eine Guix-Entwicklungsumgebung, die zusätzlich Git und strace umfasst:

     guix environment guix --ad-hoc git strace

Sometimes it is desirable to isolate the environment as much as possible, for maximal purity and reproducibility.  In particular, when using Guix on a host distro that is not Guix System, it is desirable to prevent access to /usr/bin and other system-wide resources from the development environment.  For example, the following command spawns a Guile REPL in a ``container'' where only the store and the current working directory are mounted:

     guix environment --ad-hoc --container guile -- guile

     Die Befehlszeilenoption --container funktioniert nur mit Linux-libre 3.19 oder neuer.

Im Folgenden werden die verfügbaren Befehlszeilenoptionen zusammengefasst.

--root=FILE
-r FILE
     Die DATEI zu einer symbolischen Verknüpfung auf das Profil dieser Umgebung machen und als eine Müllsammlerwurzel registrieren.

     Das ist nützlich, um seine Umgebung vor dem Müllsammler zu schützen und sie »persistent« zu machen.

     Wird diese Option weggelassen, ist die Umgebung nur, solange die Sitzung von guix environment besteht, vor dem Müllsammler sicher. Das bedeutet, wenn Sie das nächste Mal dieselbe Umgebung neu erzeugen, müssen Sie vielleicht Pakete neu erstellen oder neu herunterladen. See Aufruf von guix gc hat mehr Informationen über Müllsammlerwurzeln.

--expression=AUSDRUCK
-e AUSDRUCK
     Eine Umgebung für das Paket oder die Liste von Paketen erzeugen, zu der der AUSDRUCK ausgewertet wird.

     Zum Beispiel startet dies:

          guix environment -e '(@ (gnu packages maths) petsc-openmpi)'

     eine Shell mit der Umgebung für eben diese bestimmte Variante des Pakets PETSc.

     Wenn man dies ausführt:

          guix environment --ad-hoc -e '(@ (gnu) %base-packages)'

     starts a shell with all the base system packages available.

     Die obigen Befehle benutzen nur die Standard-Ausgabe des jeweiligen Pakets. Um andere Ausgaben auszuwählen, können zweielementige Tupel spezifiziert werden:

          guix environment --ad-hoc -e '(list (@ (gnu packages bash) bash) "include")'

--load=DATEI
-l DATEI
     Eine Umgebung erstellen für das Paket oder die Liste von Paketen, zu der der Code in der DATEI ausgewertet wird.

     Zum Beispiel könnte die DATEI eine Definition wie diese enthalten (see Pakete definieren):

               [file environment-gdb.scm not included]

--manifest=DATEI
-m DATEI
     Eine Umgebung für die Pakete erzeugen, die im Manifest-Objekt enthalten sind, das vom Scheme-Code in der DATEI geliefert wird.

     Dies verhält sich ähnlich wie die gleichnamige Option des Befehls guix package (see --manifest) und benutzt auch dieselben Manifestdateien.

--ad-hoc
     Alle angegebenen Pakete in der resultierenden Umgebung einschließen, als wären sie Eingaben eines ad hoc definierten Pakets. Diese Befehlszeilenoption ist nützlich, um schnell Umgebungen aufzusetzen, ohne dafür einen Paketausdruck schreiben zu müssen, der die gewünschten Eingaben enthält.

     Zum Beispiel wird mit diesem Befehl:

          guix environment --ad-hoc guile guile-sdl -- guile

     guile in einer Umgebung ausgeführt, in der sowohl Guile als auch Guile-SDL zur Verfügung stehen.

     Beachten Sie, dass in diesem Beispiel implizit die vorgegebene Ausgabe von guile und guile-sdl verwendet wird, es aber auch möglich ist, eine bestimmte Ausgabe auszuwählen — z.B. wird mit glib:bin die Ausgabe bin von glib gewählt (see Pakete mit mehreren Ausgaben.).

     Diese Befehlszeilenoption kann mit dem standardmäßigen Verhalten von guix environment verbunden werden. Pakete, die vor --ad-hoc aufgeführt werden, werden als Pakete interpretiert, deren Abhängigkeiten zur Umgebung hinzugefügt werden, was dem standardmäßigen Verhalten entspricht. Pakete, die danach aufgeführt werden, werden selbst zur Umgebung hinzugefügt.

--pure
     Unset existing environment variables when building the new environment, except those specified with --preserve (see below.)  This has the effect of creating an environment in which search paths only contain package inputs.

--preserve=REGEXP
-E REGEXP
     When used alongside --pure, preserve the environment variables matching REGEXP---in other words, put them on a ``white list'' of environment variables that must be preserved.  This option can be repeated several times.

          guix environment --pure --preserve=^SLURM --ad-hoc openmpi ... \
            -- mpirun ...

     This example runs mpirun in a context where the only environment variables defined are PATH, environment variables whose name starts with SLURM, as well as the usual ``precious'' variables (HOME, USER, etc.)

--search-paths
     Die Umgebungsvariablendefinitionen anzeigen, aus denen die Umgebung besteht.

--system=SYSTEM
-s SYSTEM
     Versuchen, für das angegebene SYSTEM zu erstellen — z.B. i686-linux.

--container
-C
     Den BEFEHL in einer isolierten Umgebung (einem sogenannten »Container«) ausführen. Das aktuelle Arbeitsverzeichnis außerhalb des Containers wird in den Container zugeordnet. Zusätzlich wird, wenn es mit der Befehlszeilenoption --user nicht anders spezifiziert wurde, ein stellvertretendes persönliches Verzeichnis erzeugt, dessen Inhalt der des wirklichen persönlichen Verzeichnisses ist, sowie eine passend konfigurierte Datei /etc/passwd. Der erzeugte Prozess läuft außerhalb des Containers als der momentane Nutzer, aber im Kontext des Containers hat er Administratorrechte.

--network
-N
     Bei isolierten Umgebungen (»Containern«) wird hiermit der Netzwerk-Namensraum mit dem des Wirtssystems geteilt. Container, die ohne diese Befehlszeilenoption erzeugt wurden, haben nur Zugriff auf das Loopback-Gerät.

--link-profile
-P
     Bei isolierten Umgebungen (»Containern«) wird das Umgebungsprofil im Container als ~/.guix-profile verknüpft. Das ist äquivalent dazu, den Befehl ln -s $GUIX_ENVIRONMENT ~/.guix-profile im Container auszuführen. Wenn das Verzeichnis bereits existiert, schlägt das Verknüpfen fehl und die Umgebung wird nicht hergestellt. Dieser Fehler wird immer eintreten, wenn guix environment im persönlichen Verzeichnis des Benutzers aufgerufen wurde.

     Bestimmte Pakete sind so eingerichtet, dass sie in ~/.guix-profile nach Konfigurationsdateien und Daten suchen, (Zum Beispiel inspiziert das Paket fontconfig das Verzeichnis ~/.guix-profile/share/fonts, um zusätzliche Schriftarten zu finden.) weshalb --link-profile benutzt werden kann, damit sich diese Programme auch in der isolierten Umgebung wie erwartet verhalten.

--user=BENUTZER
-u BENUTZER
     Bei isolierten Umgebungen (»Containern«) wird der Benutzername BENUTZER anstelle des aktuellen Benutzers benutzt. Der erzeugte Eintrag in /etc/passwd im Container wird also den Namen BENUTZER enthalten und das persönliche Verzeichnis wird den Namen /home/BENUTZER tragen; keine GECOS-Daten über den Nutzer werden in die Umgebung übernommen. BENUTZER muss auf dem System nicht existieren.

     Zusätzlich werden alle geteilten oder exponierten Pfade (siehe jeweils --share und --expose), deren Ziel innerhalb des persönlichen Verzeichnisses des aktuellen Benutzers liegt, relativ zu /home/BENUTZER erscheinen, einschließlich der automatischen Zuordnung des aktuellen Arbeitsverzeichnisses.

          # wird Pfade als /home/foo/wd, /home/foo/test und /home/foo/target exponieren
          cd $HOME/wd
          guix environment --container --user=foo \
               --expose=$HOME/test \
               --expose=/tmp/target=$HOME/target

     Obwohl dies das Datenleck von Nutzerdaten durch Pfade im persönlichen Verzeichnis und die Benutzereinträge begrenzt, kann dies nur als Teil einer größeren Lösung für Privatsphäre und Anonymität sinnvoll eingesetzt werden. Es sollte nicht für sich allein dazu eingesetzt werden.

--expose=QUELLE[=ZIEL]
     Bei isolierten Umgebungen (»Containern«) wird das Dateisystem unter QUELLE vom Wirtssystem als Nur-Lese-Dateisystem ZIEL im Container zugänglich gemacht. Wenn kein ZIEL angegeben wurde, wird die QUELLE auch als Ziel-Einhängepunkt in der isolierten Umgebung benutzt.

     Im folgenden Beispiel wird eine Guile-REPL in einer isolierten Umgebung gestartet, in der das persönliche Verzeichnis des Benutzers als Verzeichnis /austausch nur für Lesezugriffe zugänglich gemacht wurde:

          guix environment --container --expose=$HOME=/austausch --ad-hoc guile -- guile

--share=QUELLE[=ZIEL]
     Bei isolierten Umgebungen (»Containern«) wird das Dateisystem unter QUELLE vom Wirtssystem als beschreibbares Dateisystem ZIEL im Container zugänglich gemacht. Wenn kein ZIEL angegeben wurde, wird die QUELLE auch als Ziel-Einhängepunkt in der isolierten Umgebung benutzt.

     Im folgenden Beispiel wird eine Guile-REPL in einer isolierten Umgebung gestartet, in der das persönliche Verzeichnis des Benutzers als Verzeichnis /austausch sowohl für Lese- als auch für Schreibzugriffe zugänglich gemacht wurde:

          guix environment --container --share=$HOME=/austausch --ad-hoc guile -- guile

guix environment also supports all of the common build options that guix build supports (see Gemeinsame Erstellungsoptionen) as well as package transformation options (see Paketumwandlungsoptionen).

guix pack aufrufen
==================

Manchmal möchten Sie Software an Leute weitergeben, die (noch!) nicht das Glück haben, Guix zu benutzen. Mit Guix würden sie nur guix package -i IRGENDETWAS einzutippen brauchen, aber wenn sie kein Guix haben, muss es anders gehen. Hier kommt guix pack ins Spiel.

     Wenn Sie aber nach einer Möglichkeit suchen, Binärdateien unter Maschinen auszutauschen, auf denen Guix bereits läuft, sollten Sie einen Blick auf die Abschnitte see Aufruf von guix copy, Aufruf von guix publish und Aufruf von guix archive werfen.

Der Befehl guix pack erzeugt ein gut verpacktes Software-Bündel: Konkret wird dadurch ein Tarball oder eine andere Art von Archiv mit den Binärdateien der Software erzeugt, die Sie sich gewünscht haben, zusammen mit all ihren Abhängigkeiten. Der resultierende Archiv kann auch auf jeder Maschine genutzt werden, die kein Guix hat, und jeder kann damit genau dieselben Binärdateien benutzen, die Ihnen unter Guix zur Verfügung stehen. Das Bündel wird dabei auf eine Bit für Bit reproduzierbare Art erzeugt, damit auch jeder nachprüfen kann, dass darin wirklich diejenigen Binärdateien enthalten sind, von denen Sie es behaupten.

Um zum Beispiel ein Bündel mit Guile, Emacs, Geiser und all ihren Abhängigkeiten zu erzeugen, führen Sie diesen Befehl aus:

     $ guix pack guile emacs geiser
     ...
     /gnu/store/...-pack.tar.gz

Als Ergebnis erhalten Sie einen Tarball mit einem Verzeichnis /gnu/store, worin sich alles relevanten Pakete befinden. Der resultierende Tarball enthält auch ein Profil mit den drei angegebenen Paketen; es ist dieselbe Art von Profil, die auch guix package -i erzeugen würde. Mit diesem Mechanismus wird auch der binäre Tarball zur Installation von Guix erzeugt (see Aus Binärdatei installieren).

Benutzer des Bündels müssten dann aber zum Beispiel /gnu/store/...-profile/bin/guile eintippen, um Guile auszuführen, was Ihnen zu unbequem sein könnte. Ein Ausweg wäre, dass Sie etwa eine symbolische Verknüpfung /opt/gnu/bin auf das Profil anlegen:

     guix pack -S /opt/gnu/bin=bin guile emacs geiser

Benutzer müssten dann nur noch /opt/gnu/bin/guile eintippen, um Guile zu genießen.

Doch was ist, wenn die Empfängerin Ihres Bündels keine Administratorrechte auf ihrer Maschine hat, das Bündel also nicht ins Wurzelverzeichnis ihres Dateisystems entpacken kann? Dann möchten Sie vielleicht die Befehlszeilenoption --relocatable benutzen (siehe weiter unten). Mit dieser Option werden pfad-agnostische Binärdateien erzeugt, die auch in einem beliebigen anderen Verzeichnis in der Dateisystemhierarchie abgelegt und von dort ausgeführt werden können. In obigem Beispiel würden Benutzer Ihren Tarball in ihr Persönliches Verzeichnis (das »Home«-Verzeichnis) entpacken und von dort den Befehl ./opt/gnu/bin/guile ausführen.

Eine weitere Möglichkeit ist, das Bündel im Format eines Docker-Abbilds (englisch Docker-Image) zu erzeugen. Das geht mit dem folgenden Befehl:

     guix pack -f docker guile emacs geiser

Das Ergebnis ist ein Tarball, der dem Befehl docker load übergeben werden kann. In der Dokumentation von Docker (https://docs.docker.com/engine/reference/commandline/load/) finden Sie nähere Informationen.

Und noch eine weitere Möglichkeit ist, dass Sie ein SquashFS-Abbild mit folgendem Befehl erzeugen:

     guix pack -f squashfs guile emacs geiser

Das Ergebnis ist ein SquashFS-Dateisystemabbild, dass entweder als Dateisystem eingebunden oder mit Hilfe der Singularity-Container-Ausführungsumgebung (http://singularity.lbl.gov) als Dateisystemcontainer benutzt werden kann, mit Befehlen wie singularity shell oder singularity exec.

Es gibt mehrere Befehlszeilenoptionen, mit denen Sie Ihr Bündel anpassen können:

--format=FORMAT
-f FORMAT
     Generiert ein Bündel im angegebenen FORMAT.

     Die verfügbaren Formate sind:

     tarball
          Das standardmäßig benutzte Format. Damit wird ein Tarball generiert, der alle angegebenen Binärdateien und symbolischen Verknüpfungen enthält.

     docker
          Generiert einen Tarball gemäß der Docker Image Specification (https://github.com/docker/docker/blob/master/image/spec/v1.2.md), d.h. der Spezifikation für Docker-Abbilder.

     squashfs
          Generiert ein SquashFS-Abbild, das alle angegebenen Binärdateien und symbolischen Verknüpfungen enthält, sowie leere Einhängepunkte für virtuelle Dateisysteme wie procfs.

--relocatable
-R
     Erzeugt pfad-agnostische Binärdateien — also »portable« Binärdateien, die an einer beliebigen Stelle in der Dateisystemhierarchie platziert und von dort ausgeführt werden können. Zum Beispiel können Sie ein Bash enthalltendes Bündel erzeugen mit:

          guix pack -R -S /meine-bin=bin bash

     ... you can copy that pack to a machine that lacks Guix, and from your home directory as a normal user, run:

          tar xf pack.tar.gz
          ./meine-bin/sh

     Wenn Sie in der so gestarteten Shell dann ls /gnu/store eintippen, sehen Sie, dass Ihnen angezeigt wird, in /gnu/store befänden sich alle Abhängigkeiten von bash, obwohl auf der Maschine überhaupt kein Verzeichnis /gnu/store existiert! Dies ist vermutlich die einfachste Art, mit Guix erstellte Software für eine Maschine ohne Guix auszuliefern.

     Die Sache hat nur einen Haken: Diese Technik funktioniert nur mit Benutzernamensräumen (englisch User namespaces), einer Funktionalität des Linux-Kernels, mit der Benutzer ohne besondere Berechtigungen Dateisysteme einbinden (englisch »mount«) oder die Wurzel des Dateisystems wechseln können (»change root«, kurz »chroot«). Alte Versionen von Linux haben es noch nicht unterstützt und manche Distributionen von GNU/Linux schalten diese Funktionalität ab; auf diesen Systemen werden Programme aus dem Bündel nicht funktionieren, solange sie nicht in das echte Wurzeldateisystem entpackt werden.

--expression=AUSDRUCK
-e AUSDRUCK
     Als Paket benutzen, wozu der AUSDRUCK ausgewertet wird.

     Der Zweck hiervon ist derselbe wie bei der gleichnamigen Befehlszeilenoption in guix build (see --expression in guix build).

--manifest=DATEI
-m DATEI
     Die Pakete benutzen, die im Manifest-Objekt aufgeführt sind, das vom Scheme-Code in der angegebenen DATEI geliefert wird.

     Dies hat einen ähnlichen Zweck wie die gleichnamige Befehlszeilenoption in guix package (see --manifest) und benutzt dieselben Regeln für Manifest-Dateien. Damit können Sie eine Reihe von Paketen einmal definieren und dann sowohl zum Erzeugen von Profilesn als auch zum Erzeugen von Archiven benutzen, letztere für Maschinen, auf denen Guix nicht installiert ist. Beachten Sie, dass Sie entweder eine Manifest-Datei oder eine Liste von Paketen angeben können, aber nicht beides.

--system=SYSTEM
-s SYSTEM
     Versuchen, für die angegebene Art von SYSTEM geeignete Binärdateien zu erstellen — z.B. i686-linux — statt für die Art von System, das die Erstellung durchführt.

--target=TRIPEL
     Lässt für das angegebene TRIPEL cross-erstellen, dieses muss ein gültiges GNU-Tripel wie z.B. "mips64el-linux-gnu" sein (see GNU configuration triplets (Autoconf)).

--compression=WERKZEUG
-C WERKZEUG
     Komprimiert den resultierenden Tarball mit dem angegebenen WERKZEUG — dieses kann gzip, bzip2, xz, lzip oder none für keine Kompression sein.

--symlink=SPEZIFIKATION
-S SPEZIFIKATION
     Fügt die in der SPEZIFIKATION festgelegten symbolischen Verknüpfungen zum Bündel hinzu.  Diese Befehlszeilenoption darf mehrmals vorkommen.

     Die SPEZIFIKATION muss von der Form QUELLORT=ZIELORT sein, wobei der QUELLORT der Ort der symbolischen Verknüpfung, die erstellt wird, und ZIELORT das Ziel der symbolischen Verknüpfung ist.

     Zum Beispiel wird mit -S /opt/gnu/bin=bin eine symbolische Verknüpfung /opt/gnu/bin auf das Unterverzeichnis bin im Profil erzeugt.

--save-provenance
     Save provenance information for the packages passed on the command line. Provenance information includes the URL and commit of the channels in use (see Kanäle).

     Provenance information is saved in the /gnu/store/...-profile/manifest file in the pack, along with the usual package metadata---the name and version of each package, their propagated inputs, and so on.  It is useful information to the recipient of the pack, who then knows how the pack was (supposedly) obtained.

     This option is not enabled by default because, like timestamps, provenance information contributes nothing to the build process.  In other words, there is an infinity of channel URLs and commit IDs that can lead to the same pack.  Recording such ``silent'' metadata in the output thus potentially breaks the source-to-binary bitwise reproducibility property.

--localstatedir
--profile-name=NAME
     Das »lokale Zustandsverzeichnis« /var/guix ins resultierende Bündel aufnehmen, speziell auch das Profil /var/guix/profiles/per-user/root/NAME — der vorgegebene NAME ist guix-profile, was ~root/.guix-profile entspricht.

     /var/guix enthält die Store-Datenbank (see Der Store) sowie die Müllsammlerwurzeln (see Aufruf von guix gc). Es ins Bündel aufzunehmen, bedeutet, dass der enthaltene Store »vollständig« ist und von Guix verwaltet werden kann, andernfalls wäre der Store im Bündel »tot« und nach dem Auspacken des Bündels könnte Guix keine Objekte mehr dort hinzufügen oder entfernen.

     Ein Anwendungsfall hierfür ist der eigenständige, alle Komponenten umfassende binäre Tarball von Guix (see Aus Binärdatei installieren).

--bootstrap
     Mit den Bootstrap-Binärdateien das Bündel erstellen. Diese Option ist nur für Guix-Entwickler nützlich.

Außerdem unterstützt guix pack alle gemeinsamen Erstellungsoptionen (see Gemeinsame Erstellungsoptionen) und alle Paketumwandlungsoptionen (see Paketumwandlungsoptionen).

Programmierschnittstelle
************************

GNU Guix bietet mehrere Programmierschnittstellen (APIs) in der Programmiersprache Scheme an, mit denen Software-Pakete definiert, erstellt und gesucht werden können. Die erste Schnittstelle erlaubt es Nutzern, ihre eigenen Paketdefinitionen in einer Hochsprache zu schreiben. Diese Definitionen nehmen Bezug auf geläufige Konzepte der Paketverwaltung, wie den Namen und die Version eines Pakets, sein Erstellungssystem (Build System) und seine Abhängigkeiten (Dependencies). Diese Definitionen können dann in konkrete Erstellungsaktionen umgewandelt werden.

Erstellungsaktionen werden vom Guix-Daemon für dessen Nutzer durchgeführt. Bei einer normalen Konfiguration hat der Daemon Schreibzugriff auf den Store, also das Verzeichnis /gnu/store, Nutzer hingegen nicht. Die empfohlene Konfiguration lässt den Daemon die Erstellungen in chroot-Umgebungen durchführen, mit eigenen Benutzerkonten für »Erstellungsbenutzer«, um gegenseitige Beeinflussung der Erstellung und des übrigen Systems zu minimieren.

Systemnahe APIs stehen zur Verfügung, um mit dem Daemon und dem Store zu interagieren. Um den Daemon anzuweisen, eine Erstellungsaktion durchzuführen, versorgen ihn Nutzer jeweils mit einer Ableitung. Eine Ableitung ist, wie durchzuführende Erstellungsaktionen, sowie die Umgebungen, in denen sie durchzuführen sind, in Guix eigentlich intern dargestellt werden. Ableitungen verhalten sich zu Paketdefinitionen vergleichbar mit Assembler-Code zu C-Programmen. Der Begriff »Ableitung« kommt daher, dass Erstellungsergebnisse daraus abgeleitet werden.

Dieses Kapitel beschreibt der Reihe nach all diese Programmierschnittstellen (APIs), angefangen mit hochsprachlichen Paketdefinitionen.

Paketmodule
===========

From a programming viewpoint, the package definitions of the GNU distribution are provided by Guile modules in the (gnu packages ...) name space (Note that packages under the (gnu packages ...) module name space are not necessarily ``GNU packages''. This module naming scheme follows the usual Guile module naming convention: gnu means that these modules are distributed as part of the GNU system, and packages identifies modules that define packages.) (see Guile modules (GNU Guile Reference Manual)).  For instance, the (gnu packages emacs) module exports a variable named emacs, which is bound to a <package> object (see Pakete definieren).

The (gnu packages ...) module name space is automatically scanned for packages by the command-line tools.  For instance, when running guix package -i emacs, all the (gnu packages ...) modules are scanned until one that exports a package object whose name is emacs is found.  This package search facility is implemented in the (gnu packages) module.

Users can store package definitions in modules with different names---e.g., (my-packages emacs) (Note that the file name and module name must match.  For instance, the (my-packages emacs) module must be stored in a my-packages/emacs.scm file relative to the load path specified with --load-path or GUIX_PACKAGE_PATH. See Modules and the File System (GNU Guile Reference Manual), for details.).  There are two ways to make these package definitions visible to the user interfaces:

 1. By adding the directory containing your package modules to the search path with the -L flag of guix package and other commands (see Gemeinsame Erstellungsoptionen), or by setting the GUIX_PACKAGE_PATH environment variable described below.

 2. By defining a channel and configuring guix pull so that it pulls from it.  A channel is essentially a Git repository containing package modules.  See Kanäle, for more information on how to define and use channels.

GUIX_PACKAGE_PATH works similarly to other search path variables:

 -- Environment Variable: GUIX_PACKAGE_PATH
     This is a colon-separated list of directories to search for additional package modules.  Directories listed in this variable take precedence over the own modules of the distribution.

The distribution is fully bootstrapped and self-contained: each package is built based solely on other packages in the distribution.  The root of this dependency graph is a small set of bootstrap binaries, provided by the (gnu packages bootstrap) module.  For more information on bootstrapping, see Bootstrapping.

Pakete definieren
=================

Mit den Modulen (guix packages) und (guix build-system) können Paketdefinitionen auf einer hohen Abstraktionsebene geschrieben werden. Zum Beispiel sieht die Paketdefinition bzw. das Rezept für das Paket von GNU Hello so aus:

     (define-module (gnu packages hello)
       #:use-module (guix packages)
       #:use-module (guix download)
       #:use-module (guix build-system gnu)
       #:use-module (guix licenses)
       #:use-module (gnu packages gawk))

     (define-public hello
       (package
         (name "hello")
         (version "2.10")
         (source (origin
                   (method url-fetch)
                   (uri (string-append "mirror://gnu/hello/hello-" version
                                       ".tar.gz"))
                   (sha256
                    (base32
                     "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"))))
         (build-system gnu-build-system)
         (arguments '(#:configure-flags '("--enable-silent-rules")))
         (inputs `(("gawk" ,gawk)))
         (synopsis "Hello, GNU world: An example GNU package")
         (description "Guess what GNU Hello prints!")
         (home-page "http://www.gnu.org/software/hello/")
         (license gpl3+)))

Auch ohne ein Experte in Scheme zu sein, könnten Leser erraten haben, was die verschiedenen Felder dabei bedeuten. Dieser Ausdruck bindet die Variable hello an ein <package>-Objekt, was an sich nur ein Verbund (Record) ist (see Scheme records (GNU Guile Reference Manual)). Die Felder dieses Paket-Objekts lassen sich mit den Prozeduren aus dem Modul (guix packages) auslesen, zum Beispiel liefert (package-name hello) — Überraschung! — "hello".

Mit etwas Glück können Sie die Definition vielleicht teilweise oder sogar ganz aus einer anderen Paketsammlung importieren, indem Sie den Befehl guix import verwenden (see Aufruf von guix import).

In obigem Beispiel wurde HELLO in einem eigenen Modul ganz für sich alleine definiert, und zwar (gnu packages hello). Technisch gesehen muss es nicht unbedingt in einem solchen Modul definiert werden, aber es ist bequem, denn alle Module unter (gnu packages ...) werden automatisch von den Befehlszeilenwerkzeugen gefunden (see Paketmodule).

Ein paar Dinge sind noch erwähnenswert in der obigen Paketdefinition:

  * Das source-Feld für die Quelle des Pakets ist ein <origin>-Objekt, was den Paketursprung angibt (siehe »origin«-Referenz, für eine vollständige Referenz). Hier wird dafür die Methode url-fetch aus dem Modul (guix download) benutzt, d.h. die Quelle ist eine Datei, die über FTP oder HTTP heruntergeladen werden soll.

     Das Präfix mirror://gnu lässt url-fetch einen der GNU-Spiegelserver benutzen, die in (guix download) definiert sind.

     Das Feld sha256 legt den erwarteten SHA256-Hashwert der herunterzuladenden Datei fest. Ihn anzugeben ist Pflicht und er ermöglicht es Guix, die Integrität der Datei zu überprüfen. Die Form (base32 ...) geht der base32-Darstellung des Hash-Wertes voraus. Sie finden die base32-Darstellung mit Hilfe der Befehle guix download (see Aufruf von guix download) und guix hash (see Aufruf von guix hash).

     Wenn nötig kann in der origin-Form auch ein patches-Feld stehen, wo anzuwendende Patches aufgeführt werden, sowie ein snippet-Feld mit einem Scheme-Ausdruck mit den Anweisungen, wie der Quellcode zu modifizieren ist.

  * Das Feld build-system legt fest, mit welcher Prozedur das Paket erstellt werden soll (see Erstellungssysteme). In diesem Beispiel steht GNU-BUILD-SYSTEM für das wohlbekannte GNU-Erstellungssystem, wo Pakete mit der üblichen Befehlsfolge ./configure && make && make check && make install konfiguriert, erstellt und installiert werden.

  * Das Feld arguments gibt an, welche Optionen dem Erstellungssystem mitgegeben werden sollen (see Erstellungssysteme). In diesem Fall interpretiert GNU-BUILD-SYSTEM diese als Auftrag, configure mit der Befehlszeilenoption --enable-silent-rules auszuführen.

     Was hat es mit diesen einfachen Anführungszeichen (') auf sich? Sie gehören zur Syntax von Scheme und führen eine wörtlich zu interpretierende Datenlisten ein; dies nennt sich Maskierung oder Quotierung. ' ist synonym mit quote. See quoting (GNU Guile Reference Manual), enthält weitere Details. Hierbei ist also der Wert des arguments-Feldes eine Liste von Argumenten, die an das Erstellungssystem weitergereicht werden, wie bei apply (see apply (GNU Guile Reference Manual)).

     Ein Doppelkreuz gefolgt von einem Doppelpunkt (#:) definiert ein Scheme-Schlüsselwort (see Keywords (GNU Guile Reference Manual)) und #:configure-flags ist ein Schlüsselwort, um eine Befehlszeilenoption an das Erstellungssystem mitzugeben (see Coding With Keywords (GNU Guile Reference Manual)).

  * Das Feld inputs legt Eingaben an den Erstellungsprozess fest — d.h. Abhängigkeiten des Pakets zur Erstellungs- oder Laufzeit. Hier definieren wir eine Eingabe namens "gawk", deren Wert wir auf den Wert der GAWK-Variablen festlegen; GAWK ist auch selbst wiederum an ein <package>-Objekt als Variablenwert gebunden.

     Auch mit ` (einem Backquote, stattdessen kann man auch das längere Synonym quasiquote schreiben) können wir eine wörtlich als Daten interpretierte Liste im inputs-Feld einführen, aber bei dieser »Quasimaskierung« kann , (ein Komma, oder dessen Synonym unquote) benutzt werden, um den ausgewerteten Wert eines Ausdrucks in diese Liste einzufügen (see unquote (GNU Guile Reference Manual)).

     Beachten Sie, dass GCC, Coreutils, Bash und andere essenzielle Werkzeuge hier nicht als Eingaben aufgeführt werden müssen. Stattdessen sorgt schon GNU-BUILD-SYSTEM dafür, dass diese vorhanden sein müssen (see Erstellungssysteme).

     Sämtliche anderen Abhängigkeiten müssen aber im inputs-Feld aufgezählt werden. Jede hier nicht angegebene Abhängigkeit wird während des Erstellungsprozesses schlicht nicht verfügbar sein, woraus ein Erstellungsfehler resultieren kann.

Siehe »package«-Referenz für eine umfassende Beschreibung aller erlaubten Felder.

Sobald eine Paketdefinition eingesetzt wurde, können Sie das Paket mit Hilfe des Befehlszeilenwerkzeugs guix build dann auch tatsächlich erstellen (see Aufruf von guix build) und dabei jegliche Erstellungsfehler, auf die Sie stoßen, beseitigen (see Fehlschläge beim Erstellen untersuchen). Sie können den Befehl guix edit benutzen, um leicht zur Paketdefinition zurückzuspringen (see Aufruf von guix edit). Unter see Paketrichtlinien finden Sie mehr Informationen darüber, wie Sie Paketdefinitionen testen, und unter Aufruf von guix lint finden Sie Informationen, wie Sie prüfen, ob eine Definition alle Stilkonventionen einhält. Zuletzt finden Sie unter see Kanäle Informationen, wie Sie die Distribution um Ihre eigenen Pakete in einem »Kanal« erweitern.

Zu all dem sei auch erwähnt, dass Sie das Aktualisieren einer Paketdefinition auf eine vom Anbieter neu veröffentlichte Version mit dem Befehl guix refresh teilweise automatisieren können (see Aufruf von guix refresh).

Hinter den Kulissen wird die einem <package>-Objekt entsprechende Ableitung zuerst durch package-derivation berechnet. Diese Ableitung wird in der .drv-Datei unter /gnu/store gespeichert. Die von ihr vorgeschriebenen Erstellungsaktionen können dann durch die Prozedur build-derivations umgesetzt werden (see Der Store).

 -- Scheme-Prozedur: package-derivation STORE PAKET [SYSTEM]
     Das <derivation>-Objekt zum PAKET für das angegebene SYSTEM liefern (see Ableitungen).

     Als PAKET muss ein gültiges <package>-Objekt angegeben werden und das SYSTEM muss eine Zeichenkette sein, die das Zielsystem angibt — z.B. "x86_64-linux" für ein auf x86_64 laufendes Linux-basiertes GNU-System. STORE muss eine Verbindung zum Daemon sein, der die Operationen auf dem Store durchführt (see Der Store).

Auf ähnliche Weise kann eine Ableitung berechnet werden, die ein Paket für ein anderes System cross-erstellt.

 -- Scheme-Prozedur: package-cross-derivation STORE
     PAKET ZIEL [SYSTEM] Liefert das
     <derivation>-Objekt, um das PAKET zu cross-erstellen vom SYSTEM aus für das ZIEL-System.

     Als ZIEL muss ein gültiges GNU-Tripel angegeben werden, was die Ziel-Hardware und das zugehörige Betriebssystem beschreibt, wie z.B. "mips64el-linux-gnu" (see GNU configuration triplets (GNU Configure and Build System)).

Pakete können auf beliebige Art verändert werden. Ein Beispiel für eine nützliche Veränderung ist das Umschreiben von Eingaben, womit der Abhängigkeitsbaum eines Pakets umgeschrieben wird, indem bestimmte Eingaben durch andere ersetzt werden:

 -- Scheme-Prozedur: package-input-rewriting ERSETZUNGEN
     [UMGESCHRIEBENER-NAME] Eine Prozedur liefern, die für ein ihr
     übergebenes Paket dessen direkte und indirekte Abhängigkeit (aber nicht dessen implizite Eingaben) gemäß den ERSETZUNGEN umschreibt. ERSETZUNGEN ist eine Liste von Paketpaaren; das erste Element eines Paares ist das zu ersetzende Paket und das zweite ist, wodurch es ersetzt werden soll.

     Optional kann als UMGESCHRIEBENER-NAME eine ein Argument nehmende Prozedur angegeben werden, die einen Paketnamen nimmt und den Namen nach dem Umschreiben zurückliefert.

Betrachten Sie dieses Beispiel:

     (define libressl-statt-openssl
       ;; Dies ist eine Prozedur, mit der OPENSSL durch LIBRESSL
       ;; rekursiv ersetzt wird.
       (package-input-rewriting `((,openssl . ,libressl))))

     (define git-mit-libressl
       (libressl-statt-openssl git))

Hier definieren wir zuerst eine Umschreibeprozedur, die OPENSSL durch LIBRESSL ersetzt. Dann definieren wir damit eine Variante des GIT-Pakets, die LIBRESSL statt OPENSSL benutzt. Das ist genau, was auch die Befehlszeilenoption --with-input tut (see --with-input).

Eine allgemeiner anwendbare Prozedur, um den Abhängigkeitsgraphen eines Pakets umzuschreiben, ist package-mapping. Sie unterstützt beliebige Änderungen an den Knoten des Graphen.

 -- Scheme-Prozedur: package-mapping PROZEDUR [SCHNITT?]
     Liefert eine Prozedur, die, wenn ihr ein Paket übergeben wird, die an package-mapping übergebene PROZEDUR auf alle vom Paket abhängigen Pakete anwendet. Die Prozedur liefert das resultierende Paket. Wenn SCHNITT? für ein Paket davon einen wahren Wert liefert, findet kein rekursiver Abstieg in dessen Abhängigkeiten statt.

package-Referenz
----------------

Dieser Abschnitt fasst alle in package-Deklarationen zur Verfügung stehenden Optionen zusammen (see Pakete definieren).

 -- Datentyp: package
     Dieser Datentyp steht für ein Paketrezept.

     name
          Der Name des Pakets als Zeichenkette.

     version
          Die Version des Pakets als Zeichenkette.

     source
          Ein Objekt, das beschreibt, wie der Quellcode des Pakets bezogen werden soll. Meistens ist es ein origin-Objekt, welches für eine aus dem Internet heruntergeladene Datei steht (see »origin«-Referenz). Es kann aber auch ein beliebiges anderes »dateiähnliches« Objekt sein, wie z.B. ein local-file, was eine Datei im lokalen Dateisystem bezeichnet (see local-file).

     build-system
          Das Erstellungssystem, mit dem das Paket erstellt werden soll (see Erstellungssysteme).

     arguments (Vorgabe: '())
          Die Argumente, die an das Erstellungssystem übergeben werden sollen. Dies ist eine Liste, typischerweise eine Reihe von Schlüssel-Wert-Paaren.

     inputs (Vorgabe: '())
     native-inputs (Vorgabe: '())
     propagated-inputs (Vorgabe: '())
          In diesen Feldern werden die Abhängigkeiten des Pakets aufgeführt. Jedes dieser Felder enthält eine Liste von Tupeln, wobei jedes Tupel eine Bezeichnung für die Eingabe (als Zeichenkette) als erstes Element, dann ein »package«-, »origin«- oder »derivation«-Objekt (Paket, Ursprung oder Ableitung) als zweites Element und optional die Benennung der davon zu benutzenden Ausgabe umfasst; letztere hat als Vorgabewert "out" (siehe Pakete mit mehreren Ausgaben. für mehr Informationen zu Paketausgaben). Im folgenden Beispiel etwa werden drei Eingaben festgelegt:

               `(("libffi" ,libffi)
                 ("libunistring" ,libunistring)
                 ("glib:bin" ,glib "bin"))  ;Ausgabe "bin" von Glib

          Die Unterscheidung zwischen native-inputs und inputs ist wichtig, damit Cross-Kompilieren möglich ist. Beim Cross-Kompilieren werden als inputs aufgeführte Abhängigkeiten für die Ziel-Prozessorarchitektur (target) erstellt, andersherum werden als native-inputs aufgeführte Abhängigkeiten für die Prozessorarchitektur der erstellenden Maschine (build) erstellt.

          native-inputs listet typischerweise die Werkzeuge auf, die während der Erstellung gebraucht werden, aber nicht zur Laufzeit des Programms gebraucht werden. Beispiele sind Autoconf, Automake, pkg-config, Gettext oder Bison. guix lint kann melden, ob wahrscheinlich Fehler in der Auflistung sind (see Aufruf von guix lint).

          Schließlich ist propagated-inputs ähnlich wie inputs, aber die angegebenen Pakete werden automatisch mit ins Profil installiert, wenn das Paket installiert wird, zu dem sie gehören (siehe guix package, für Informationen darüber, wie guix package mit propagierten Eingaben umgeht).

          Dies ist zum Beispiel nötig, wenn eine C-/C++-Bibliothek Header-Dateien einer anderen Bibliothek braucht, um mit ihr kompilieren zu können, oder wenn sich eine pkg-config-Datei auf eine andere über ihren Requires-Eintrag bezieht.

          Noch ein Beispiel, wo propagated-inputs nützlich ist, sind Sprachen, die den Laufzeit-Suchpfad nicht zusammen mit dem Programm abspeichern (nicht wie etwa im RUNPATH bei ELF-Dateien), also Sprachen wie Guile, Python, Perl und weitere. Damit auch in solchen Sprachen geschriebene Bibliotheken zur Laufzeit den von ihnen benötigten Code finden können, müssen deren Laufzeit-Abhängigkeiten in propagated-inputs statt in inputs aufgeführt werden.

     self-native-input? (Vorgabe: #f)
          Dieses boolesche Feld gibt an, ob das Paket sich selbst als eine native Eingabe beim Cross-Kompilieren braucht.

     outputs (Vorgabe: '("out"))
          Die Liste der Benennungen der Ausgaben des Pakets. Der Abschnitt see Pakete mit mehreren Ausgaben. beschreibt übliche Nutzungen zusätzlicher Ausgaben.

     native-search-paths (Vorgabe: '())
     search-paths (Vorgabe: '())
          Eine Liste von search-path-specification-Objekten, die Umgebungsvariable für von diesem Paket beachtete Suchpfade (»search paths«) beschreiben.

     replacement (Vorgabe: #f)
          Dies muss entweder #f oder ein package-Objekt sein, das als Ersatz (replacement) dieses Pakets benutzt werden soll. Im Abschnitt see grafts, wird dies erklärt.

     synopsis
          Eine einzeilige Beschreibung des Pakets.

     description
          Eine ausführlichere Beschreibung des Pakets.

     license
          Die Lizenz des Pakets; benutzt werden kann ein Wert aus dem Modul (guix licenses) oder eine Liste solcher Werte.

     home-page
          Die URL, die die Homepage des Pakets angibt, als Zeichenkette.

     supported-systems (Vorgabe: %SUPPORTED-SYSTEMS)
          Die Liste der vom Paket unterstützten Systeme als Zeichenketten der Form Architektur-Kernel, zum Beispiel "x86_64-linux".

     maintainers (Vorgabe: '())
          Die Liste der Betreuer (Maintainer) des Pakets als maintainer-Objekte.

     location (Vorgabe: die Stelle im Quellcode, wo die package-Form steht)
          Wo im Quellcode das Paket definiert wurde. Es ist sinnvoll, dieses Feld manuell zuzuweisen, wenn das Paket von einem anderen Paket erbt, weil dann dieses Feld nicht automatisch berichtigt wird.

origin-Referenz
---------------

Dieser Abschnitt fasst alle Optionen zusammen, die in origin-Deklarationen zur Verfügung stehen (see Pakete definieren).

 -- Datentyp: origin
     Mit diesem Datentyp wird ein Ursprung, von dem Quellcode geladen werden kann, beschrieben.

     uri
          Ein Objekt, was die URI des Quellcodes enthält. Der Objekttyp hängt von der Methode ab (siehe unten). Zum Beispiel sind, wenn die URL-FETCH-Methode aus (guix download) benutzt wird, die gültigen Werte für uri: eine URL dargestellt als Zeichenkette oder eine Liste solcher URLs.

     method
          Eine Prozedur, die die URI verwertet.

          Beispiele sind unter Anderem:

          URL-FETCH aus (guix download)
               Herunterladen einer Datei von einer HTTP-, HTTPS- oder FTP-URL, die im uri-Feld angegeben wurde.

          GIT-FETCH aus (guix git-download)
               Das im uri-Feld spezifizierte Repository des Git-Versionskontrollsystems klonen und davon den im uri-Feld als ein git-reference-Objekt angegebenen Commit benutzen; eine git-reference sieht so aus:

                    (git-reference
                      (url "git://git.debian.org/git/pkg-shadow/shadow")
                      (commit "v4.1.5.1"))

     sha256
          Ein Bytevektor, der den SHA-256-Hash der Quelldateien enthält. Typischerweise wird hier mit der base32-Form der Bytevektor aus einer Base-32-Zeichenkette generiert.

          Diese Informationen liefert Ihnen der Befehl guix download (see Aufruf von guix download) oder guix hash (see Aufruf von guix hash).

     file-name (Vorgabe: #f)
          Der Dateiname, unter dem der Quellcode abgespeichert werden sollte. Wenn er auf #f steht, wird ein vernünftiger Name automatisch gewählt. Falls der Quellcode von einer URL geladen wird, wird der Dateiname aus der URL genommen. Wenn der Quellcode von einem Versionskontrollsystem bezogen wird, empfiehlt es sich, den Dateinamen ausdrücklich anzugeben, weil dann keine sprechende Benennung automatisch gefunden werden kann.

     patches (Vorgabe: '())
          Eine Liste von Dateinamen, Ursprüngen oder dateiähnlichen Objekten (see file-like objects) mit Patches, welche auf den Quellcode anzuwenden sind.

          Die Liste von Patches kann nicht von Parametern der Erstellung abhängen. Insbesondere kann sie nicht vom Wert von %current-system oder %current-target-system abḧängen.

     snippet (Vorgabe: #f)
          Ein im Quellcode-Verzeichnis auszuführender G-Ausdruck (see G-Ausdrücke) oder S-Ausdruck. Hiermit kann der Quellcode bequem modifiziert werden, manchmal ist dies bequemer als mit einem Patch.

     patch-flags (Vorgabe: '("-p1"))
          Eine Liste der Befehlszeilenoptionen, die dem patch-Befehl übergeben werden sollen.

     patch-inputs (Vorgabe: #f)
          Eingabepakete oder -ableitungen für den Patch-Prozess. Bei #f werden die üblichen Patcheingaben wie GNU Patch bereitgestellt.

     modules (Vorgabe: '())
          Eine Liste von Guile-Modulen, die während des Patch-Prozesses und während der Ausführung des snippet-Felds geladen werden sollten.

     patch-guile (Vorgabe: #f)
          Welches Guile-Paket für den Patch-Prozess benutzt werden sollte. Bei #f wird ein vernünftiger Vorgabewert angenommen.

Erstellungssysteme
==================

Jede Paketdefinition legt ein Erstellungssystem (»build system«) sowie dessen Argumente fest (see Pakete definieren). Das build-system-Feld steht für die Erstellungsprozedur des Pakets sowie für weitere implizite Eingaben für die Erstellungsprozedur.

Erstellungssysteme sind <build-system>-Objekte. Die Schnittstelle, um solche zu erzeugen und zu verändern, ist im Modul (guix build-system) zu finden, und die eigentlichen Erstellungssysteme werden jeweils von ihren eigenen Modulen exportiert.

Intern funktionieren Erstellungssysteme, indem erst Paketobjekte zu Bags kompiliert werden. Eine Bag (deutsch: Beutel, Sack) ist wie ein Paket, aber mit weniger Zierrat — anders gesagt ist eine Bag eine systemnähere Darstellung eines Pakets, die sämtliche Eingaben des Pakets einschließlich vom Erstellungssystem hinzugefügter Eingaben enthält. Diese Zwischendarstellung wird dann zur eigentlichen Ableitung kompiliert (see Ableitungen).

Erstellungssysteme akzeptieren optional eine Liste von Argumenten. In Paketdefinitionen werden diese über das arguments-Feld übergeben (see Pakete definieren). Sie sind in der Regel Schlüsselwort-Argumente (see keyword arguments in Guile (GNU Guile Reference Manual)). Der Wert dieser Argumente wird normalerweise vom Erstellungssystem in der Erstellungsschicht ausgewertet, d.h. von einem durch den Daemon gestarteten Guile-Prozess (see Ableitungen).

Das häufigste Erstellungssystem ist GNU-BUILD-SYSTEM, was die übliche Erstellungsprozedur für GNU-Pakete und viele andere Pakete darstellt. Es wird vom Modul (guix build-system gnu) bereitgestellt.

 -- Scheme-Variable: gnu-build-system
     GNU-BUILD-SYSTEM steht für das GNU-Erstellungssystem und Varianten desselben (see configuration and makefile conventions (GNU Coding Standards)).

     Kurz gefasst werden Pakete, die es benutzen, konfiguriert, erstellt und installiert mit der üblichen Befehlsfolge ./configure && make && make check && make install. In der Praxis braucht man oft noch ein paar weitere Schritte. Alle Schritte sind in voneinander getrennte Phasen unterteilt. Erwähnt werden sollten (Bitte schauen Sie in den Modulen unter (guix build gnu-build-system), wenn Sie mehr Details zu Erstellungsphasen brauchen.):

     unpack
          Den Quell-Tarball entpacken und das Arbeitsverzeichnis wechseln in den entpackten Quellbaum. Wenn die Quelle bereits ein Verzeichnis ist, wird es in den Quellbaum kopiert und dorthin gewechselt.

     patch-source-shebangs
          »Shebangs« in Quelldateien beheben, damit Sie sich auf die richtigen Store-Dateipfade beziehen. Zum Beispiel könnte #!/bin/sh zu #!/gnu/store/...-bash-4.3/bin/sh geändert werden.

     configure
          Das Skript configure mit einigen vorgegebenen Befehlszeilenoptionen ausführen, wie z.B. mit --prefix=/gnu/store/..., sowie mit den im #:configure-flags-Argument angegebenen Optionen.

     build
          make ausführen mit den Optionen aus der Liste in #:make-flags. Wenn das Argument #:parallel-build? auf wahr gesetzt ist (was der Vorgabewert ist), wird make -j zum Erstellen ausgeführt.

     check
          make check (oder statt check ein anderes bei #:test-target angegebenes Ziel) ausführen, außer falls #:tests? #f gesetzt ist. Wenn das Argument #:parallel-tests? auf wahr gesetzt ist (der Vorgabewert), führe make check -j aus.

     install
          make install mit den in #:make-flags aufgelisteten Optionen ausführen.

     patch-shebangs
          Shebangs in den installierten ausführbaren Dateien beheben.

     strip
          Symbole zur Fehlerbehebung aus ELF-Dateien entfernen (außer #:strip-binaries? ist auf falsch gesetzt) und in die debug-Ausgabe kopieren, falls diese verfügbar ist (see Dateien zur Fehlersuche installieren).

     Das erstellungsseitige Modul (guix build gnu-build-system) definiert %STANDARD-PHASES als die vorgegebene Liste der Erstellungsphasen. %STANDARD-PHASES ist eine Liste von Paaren aus je einem Symbol und einer Prozedur. Letztere implementiert die eigentliche Phase.

     Die Liste der Phasen, die für ein bestimmtes Paket verwendet werden sollen, kann vom Parameter #:phases überschrieben werden. Zum Beispiel werden bei Übergabe von:

          #:phases (modify-phases %standard-phases (delete 'configure))

     alle oben beschriebenen Phasen benutzt außer der configure-Phase.

     Zusätzlich stellt dieses Erstellungssystem sicher, dass die »Standard«-Umgebung für GNU-Pakete zur Verfügung steht. Diese umfasst Werkzeuge wie GCC, libc, Coreutils, Bash, Make, Diffutils, grep und sed (siehe das Modul (guix build-system gnu) für eine vollständige Liste). Wir bezeichnen sie als implizite Eingaben eines Pakets, weil Paketdefinitionen sie nicht aufführen müssen.

Andere <build-system>-Objekte werden definiert, um andere Konventionen und Werkzeuge von Paketen für freie Software zu unterstützen. Die anderen Erstellungssysteme erben den Großteil vom GNU-BUILD-SYSTEM und unterscheiden sich hauptsächlich darin, welche Eingaben dem Erstellungsprozess implizit hinzugefügt werden und welche Liste von Phasen durchlaufen wird. Manche dieser Erstellungssysteme sind im Folgenden aufgeführt.

 -- Scheme-Variable: ant-build-system
     Diese Variable wird vom Modul (guix build-system ant) exportiert. Sie implementiert die Erstellungsprozedur für Java-Pakete, die mit dem Ant build tool (http://ant.apache.org/) erstellt werden können.

     Sowohl ant als auch der Java Development Kit (JDK), wie er vom Paket icedtea bereitgestellt wird, werden zu den Eingaben hinzugefügt. Wenn andere Pakete dafür benutzt werden sollen, können sie jeweils mit den Parametern #:ant und #:jdk festgelegt werden.

     Falls das ursprüngliche Paket über keine nutzbare Ant-Erstellungsdatei (»Ant-Buildfile«) verfügt, kann aus der Angabe im Parameter #:jar-name eine minimale Ant-Erstellungsdatei build.xml erzeugt werden, in der die für die Erstellung durchzuführenden Aufgaben (Tasks) für die Erstellung des angegebenen Jar-Archivs stehen. In diesem Fall kann der Parameter #:source-dir benutzt werden, um das Unterverzeichnis mit dem Quellcode anzugeben; sein Vorgabewert ist »src«.

     Der Parameter #:main-class kann mit einer minimalen Ant-Erstellungsdatei benutzt werden, um die Hauptklasse des resultierenden Jar-Archivs anzugeben. Dies ist nötig, wenn die Jar-Datei ausführbar sein soll. Mit dem Parameter #:test-include kann eine Liste angegeben werden, welche Junit-Tests auszuführen sind. Der Vorgabewert ist (list "**/*Test.java"). Mit #:test-exclude kann ein Teil der Testdateien ignoriert werden. Der Vorgabewert ist (list "**/Abstract*.java"), weil abstrakte Klassen keine ausführbaren Tests enthalten können.

     Der Parameter #:build-target kann benutzt werden, um die Ant-Aufgabe (Task) anzugeben, die während der build-Phase ausgeführt werden soll. Vorgabe ist, dass die Aufgabe (Task) »jar« ausgeführt wird.

 -- Scheme-Variable: android-ndk-build-system
     Diese Variable wird von (guix build-system android-ndk) exportiert. Sie implementiert eine Erstellungsprozedur für das Android NDK (Native Development Kit) benutzende Pakete mit einem Guix-spezifischen Erstellungsprozess.

     Für das Erstellungssystem wird angenommen, dass Pakete die zu ihrer öffentlichen Schnittstelle gehörenden Header-Dateien im Unterverzeichnis "include" der Ausgabe "out" und ihre Bibliotheken im Unterverzeichnis "lib" der Ausgabe "out" platzieren.

     Ebenso wird angenommen, dass es keine im Konflikt stehenden Dateien unter der Vereinigung aller Abhängigkeiten gibt.

     Derzeit wird Cross-Kompilieren hierfür nicht unterstützt, also wird dabei vorausgesetzt, dass Bibliotheken und Header-Dateien dieselben wie im Wirtssystem sind.

 -- Scheme-Variable: asdf-build-system/source
 -- Scheme-Variable: asdf-build-system/sbcl
 -- Scheme-Variable: asdf-build-system/ecl

     Diese Variablen, die vom Modul (guix build-system asdf) exportiert werden, implementieren Erstellungsprozeduren für Common-Lisp-Pakete, welche »ASDF« (https://common-lisp.net/project/asdf/) benutzen. ASDF dient der Systemdefinition für Common-Lisp-Programme und -Bibliotheken.

     Das Erstellungssystem asdf-build-system/source installiert die Pakete in Quellcode-Form und kann via ASDF mit jeder Common-Lisp-Implementierung geladen werden. Die anderen Erstellungssysteme wie asdf-build-system/sbcl installieren binäre Systeme in dem Format, das von einer bestimmten Implementierung verstanden wird. Diese Erstellungssysteme können auch benutzt werden, um ausführbare Programme zu erzeugen oder um Lisp-Abbilder mit einem vorab geladenen Satz von Paketen zu erzeugen.

     Das Erstellungssystem benutzt gewisse Namenskonventionen. Bei Binärpaketen sollte dem Paketnamen die Lispimplementierung als Präfix vorangehen, z.B.sbcl- für asdf-build-system/sbcl.

     Zudem sollte das entsprechende Quellcode-Paket mit der Konvention wie bei Python-Paketen (siehe Python-Module) ein cl- als Präfix bekommen.

     Für Binärpakete sollte für jedes System ein Guix-Paket definiert werden. Wenn für einen Ursprung im origin mehrere Systeme enthalten sind, können Paketvarianten geschrieben werden, mit denen alle Systeme erstellt werden. Quellpakete, die asdf-build-system/source benutzen, können mehrere Systeme enthalten.

     Um ausführbare Programme und Abbilder zu erzeugen, können die erstellungsseitigen Prozeduren build-program und build-image benutzt werden. Sie sollten in einer Erstellungsphase nach der create-symlinks-Phase aufgerufen werden, damit das gerade erstellte System Teil des resultierenden Abbilds sein kann. An build-program muss eine Liste von Common-Lisp-Ausdrücken über das Argument #:entry-program übergeben werden.

     Wenn das System nicht in seiner eigenen gleichnamigen .asd-Datei definiert ist, sollte der Parameter #:asd-file benutzt werden, um anzugeben, in welcher Datei das System definiert ist. Außerdem wird bei Paketen, für deren Tests ein System in einer separaten Datei definiert wurde, dieses System geladen, bevor die Tests ablaufen, wenn es im Parameter #:test-asd-file steht. Ist dafür kein Wert gesetzt, werden die Dateien <system>-tests.asd, <system>-test.asd, tests.asd und test.asd durchsucht, wenn sie existieren.

     Wenn aus irgendeinem Grund der Paketname nicht den Namenskonventionen folgen kann, kann der Parameter #:asd-system-name benutzt werden, um den Namen des Systems anzugeben.

 -- Scheme-Variable: cargo-build-system
     Diese Variable wird vom Modul (guix build-system cargo) exportiert. Damit können Pakete mit Cargo erstellt werden, dem Erstellungswerkzeug der Rust-Programmiersprache (https://www.rust-lang.org).

     In seiner configure-Phase ersetzt dieses Erstellungssystem in der Datei Carto.toml angegebene Abhängigkeiten durch Eingaben im Guix-Paket. Die Phase install installiert die Binärdateien und auch den Quellcode und die Cargo.toml-Datei.

 -- Scheme-Variable: clojure-build-system
     Diese Variable wird durch das Modul (guix build-system clojure) exportiert. Sie implementiert eine einfache Erstellungsprozedur für in Clojure (https://clojure.org/) geschriebene Pakete mit dem guten alten compile in Clojure. Cross-Kompilieren wird noch nicht unterstützt.

     Das Erstellungssystem fügt clojure, icedtea und zip zu den Eingaben hinzu. Sollen stattdessen andere Pakete benutzt werden, können diese jeweils mit den Parametern #:clojure, #:jdk und #:zip spezifiziert werden.

     Eine Liste der Quellcode-Verzeichnisse, Test-Verzeichnisse und Namen der Jar-Dateien können jeweils über die Parameter #:source-dirs, #:test-dirs und #:jar-names angegeben werden. Das Verzeichnis, in das kompiliert wird, sowie die Hauptklasse können jeweils mit den Parametern #:compile-dir und #:main-class angegeben werden. Andere Parameter sind im Folgenden dokumentiert.

     Dieses Erstellungssystem ist eine Erweiterung des ANT-BUILD-SYSTEM, bei der aber die folgenden Phasen geändert wurden:

     build
          Diese Phase ruft compile in Clojure auf, um Quelldateien zu kompilieren, und führt jar aus, um Jar-Dateien aus sowohl Quelldateien als auch kompilierten Dateien zu erzeugen, entsprechend der jeweils in #:aot-include und #:aot-exclude festgelegten Listen aus in der Menge der Quelldateien eingeschlossenen und ausgeschlossenen Bibliotheken. Die Ausschlussliste hat Vorrang vor der Einschlussliste. Diese Listen setzen sich aus Symbolen zusammen, die für Clojure-Bibliotheken stehen oder dem Schlüsselwort #:all entsprechen, was für alle im Quellverzeichis gefundenen Clojure-Bibliotheken steht. Der Parameter #:omit-source? entscheidet, ob Quelldateien in die Jar-Archive aufgenommen werden sollten.

     check
          In dieser Phase werden Tests auf die durch Einschluss- und Ausschlussliste #:test-include bzw. #:test-exclude angegebenen Dateien ausgeführt. Deren Bedeutung ist analog zu #:aot-include und #:aot-exclude, außer dass das besondere Schlüsselwort #:all jetzt für alle Clojure-Bibliotheken in den Test-Verzeichnissen steht. Der Parameter #:tests? entscheidet, ob Tests ausgeführt werden sollen.

     install
          In dieser Phase werden alle zuvor erstellten Jar-Dateien installiert.

     Zusätzlich zu den bereits angegebenen enthält dieses Erstellungssystem noch eine weitere Phase.

     install-doc
          Diese Phase installiert alle Dateien auf oberster Ebene, deren Basisnamen ohne Verzeichnisangabe zu %DOC-REGEX passen. Ein anderer regulärer Ausdruck kann mit dem Parameter #:doc-regex verwendet werden. All die so gefundenen oder (rekursiv) in den mit #:doc-dirs angegebenen Dokumentationsverzeichnissen liegenden Dateien werden installiert.

 -- Scheme-Variable: cmake-build-system
     Diese Variable wird von (guix build-system cmake) exportiert. Sie implementiert die Erstellungsprozedur für Pakete, die das CMake-Erstellungswerkzeug (http://www.cmake.org) benutzen.

     Das Erstellungssystem fügt automatisch das Paket cmake zu den Eingaben hinzu. Welches Paket benutzt wird, kann mit dem Parameter #:cmake geändert werden.

     Der Parameter #:configure-flags wird als Liste von Befehlszeilenoptionen aufgefasst, die an den Befehl cmake übergeben werden. Der Parameter #:build-type abstrahiert, welche Befehlszeilenoptionen dem Compiler übergeben werden; der Vorgabewert ist "RelWithDebInfo" (kurz für »release mode with debugging information«), d.h. kompiliert wird für eine Produktionsumgebung und Informationen zur Fehlerbehebung liegen bei, was ungefähr -O2 -g entspricht, wie bei der Vorgabe für Autoconf-basierte Pakete.

 -- Scheme Variable: dune-build-system
     This variable is exported by (guix build-system dune).  It supports builds of packages using Dune (https://dune.build/), a build tool for the OCaml programming language.  It is implemented as an extension of the ocaml-build-system which is described below.  As such, the #:ocaml and #:findlib parameters can be passed to this build system.

     It automatically adds the dune package to the set of inputs.  Which package is used can be specified with the #:dune parameter.

     There is no configure phase because dune packages typically don't need to be configured.  The #:build-flags parameter is taken as a list of flags passed to the dune command during the build.

     The #:jbuild? parameter can be passed to use the jbuild command instead of the more recent dune command while building a package.  Its default value is #f.

 -- Scheme-Variable: go-build-system
     Diese Variable wird vom Modul (guix build-system go) exportiert. Mit ihr ist eine Erstellungsprozedur für Go-Pakete implementiert, die dem normalen Go-Erstellungsmechanismus (https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies) entspricht.

     Beim Aufruf wird ein Wert für den Schlüssel #:import-path und manchmal auch für #:unpack-path erwartet.  Der »import path« (https://golang.org/doc/code.html#ImportPaths) entspricht dem Dateisystempfad, den die Erstellungsskripts des Pakets und darauf Bezug nehmende Pakete erwarten; durch ihn wird ein Go-Paket eindeutig bezeichnet. Typischerweise setzt er sich aus einer Kombination der entfernten URI des Paketquellcodes und der Dateisystemhierarchie zusammen. Manchmal ist es nötig, den Paketquellcode in ein anderes als das vom »import path« bezeichnete Verzeichnis zu entpacken; diese andere Verzeichnisstruktur sollte dann als #:unpack-path angegeben werden.

     Pakete, die Go-Bibliotheken zur Verfügung stellen, sollten zusammen mit ihrem Quellcode installiert werden. Der Schlüssel #:install-source?, sein Vorgabewert ist #t, steuert, ob Quellcode installiert wird. Bei Paketen, die nur ausführbare Dateien liefern, kann der Wert auf #f gesetzt werden.

 -- Scheme-Variable: glib-or-gtk-build-system
     Diese Variable wird vom Modul (guix build-system glib-or-gtk) exportiert. Sie ist für Pakete gedacht, die GLib oder GTK benutzen.

     Dieses Erstellungssystem fügt die folgenden zwei Phasen zu denen von GNU-BUILD-SYSTEM hinzu:

     glib-or-gtk-wrap
          Die Phase glib-or-gtk-wrap stellt sicher, dass Programme in bin/ in der Lage sind, GLib-»Schemata« und GTK-Module (https://developer.gnome.org/gtk3/stable/gtk-running.html) zu finden. Dazu wird für das Programm ein Wrapper-Skript erzeugt, dass das eigentliche Programm mit den richtigen Werten für die Umgebungsvariablen XDG_DATA_DIRS und GTK_PATH aufruft.

          Es ist möglich, bestimmte Paketausgaben von diesem Wrapping-Prozess auszunehmen, indem Sie eine Liste ihrer Namen im Parameter #:glib-or-gtk-wrap-excluded-outputs angeben. Das ist nützlich, wenn man von einer Ausgabe weiß, dass sie keine Binärdateien enthält, die GLib oder GTK benutzen, und diese Ausgabe durch das Wrappen ohne Not eine weitere Abhängigkeit von GLib und GTK bekäme.

     glib-or-gtk-compile-schemas
          Mit der Phase glib-or-gtk-compile-schemas wird sichergestellt, dass alle GSettings-Schemata (https://developer.gnome.org/gio/stable/glib-compile-schemas.html) für GLib kompiliert werden. Dazu wird das Programm glib-compile-schemas ausgeführt. Es kommt aus dem Paket glib:bin, was automatisch vom Erstellungssystem importiert wird. Welches glib-Paket dieses glib-compile-schemas bereitstellt, kann mit dem Parameter #:glib spezifiziert werden.

     Beide Phasen finden nach der install-Phase statt.

 -- Scheme-Variable: guile-build-system
     Dieses Erstellungssystem ist für Guile-Pakete gedacht, die nur aus Scheme-Code bestehen und so schlicht sind, dass sie nicht einmal ein Makefile und erst recht keinen configure-Skript enthalten. Hierzu wird Scheme-Code mit guild compile kompiliert (see Compilation (GNU Guile Reference Manual)) und die .scm- und .go-Dateien an den richtigen Pfad installiert. Auch Dokumentation wird installiert.

     Das Erstellungssystem unterstützt Cross-Kompilieren durch die Befehlszeilenoption --target für guild compile.

     Mit guile-build-system erstellte Pakete müssen ein Guile-Paket in ihrem native-inputs-Feld aufführen.

 -- Scheme-Variable: minify-build-system
     Diese Variable wird vom Modul (guix build-system minify) exportiert. Sie implementiert eine Prozedur zur Minifikation einfacher JavaScript-Pakete.

     Es fügt uglify-js zur Menge der Eingaben hinzu und komprimiert damit alle JavaScript-Dateien im src-Verzeichnis. Ein anderes Programm zur Minifikation kann verwendet werden, indem es mit dem Parameter #:uglify-js angegeben wird; es wird erwartet, dass das angegebene Paket den minifizierten Code auf der Standardausgabe ausgibt.

     Wenn die Eingabe-JavaScript-Dateien nicht alle im src-Verzeichnis liegen, kann mit dem Parameter #:javascript-files eine Liste der Dateinamen übergeben werden, auf die das Minifikationsprogramm aufgerufen wird.

 -- Scheme-Variable: ocaml-build-system
     Diese Variable wird vom Modul (guix build-system ocaml) exportiert. Mit ihr ist ein Erstellungssystem für OCaml (https://ocaml.org)-Pakete implementiert, was bedeutet, dass es die richtigen auszuführenden Befehle für das jeweilige Paket auswählt. OCaml-Pakete können sehr unterschiedliche Befehle erwarten. Dieses Erstellungssystem probiert manche davon durch.

     Wenn im Paket eine Datei setup.ml auf oberster Ebene vorhanden ist, wird ocaml setup.ml -configure, ocaml setup.ml -build und ocaml setup.ml -install ausgeführt. Das Erstellungssystem wird annehmen, dass die Datei durch OASIS (http://oasis.forge.ocamlcore.org/) erzeugt wurde, und wird das Präfix setzen und Tests aktivieren, wenn diese nicht abgeschaltet wurden. Sie können Befehlszeilenoptionen zum Konfigurieren und Erstellen mit den Parametern #:configure-flags und #:build-flags übergeben. Der Schlüssel #:test-flags kann übergeben werden, um die Befehlszeilenoptionen zu ändern, mit denen die Tests aktiviert werden. Mit dem Parameter #:use-make? kann dieses Erstellungssystem für die build- und install-Phasen abgeschaltet werden.

     Verfügt das Paket über eine configure-Datei, wird angenommen, dass diese von Hand geschrieben wurde mit einem anderen Format für Argumente als bei einem Skript des gnu-build-system. Sie können weitere Befehlszeilenoptionen mit dem Schlüssel #:configure-flags hinzufügen.

     Falls dem Paket ein Makefile beiliegt (oder #:use-make? auf #t gesetzt wurde), wird dieses benutzt und weitere Befehlszeilenoptionen können mit dem Schlüssel #:make-flags zu den build- und install-Phasen hinzugefügt werden.

     Letztlich gibt es in manchen Pakete keine solchen Dateien, sie halten sich aber an bestimmte Konventionen, wo ihr eigenes Erstellungssystem zu finden ist. In diesem Fall führt Guix’ OCaml-Erstellungssystem ocaml pkg/pkg.ml oder ocaml pkg/build.ml aus und kümmert sich darum, dass der Pfad zu dem benötigten findlib-Modul passt. Weitere Befehlszeilenoptionen können über den Schlüssel #:build-flags übergeben werden. Um die Installation kümmert sich opam-installer. In diesem Fall muss das opam-Paket im native-inputs-Feld der Paketdefinition stehen.

     Beachten Sie, dass die meisten OCaml-Pakete davon ausgehen, dass sie in dasselbe Verzeichnis wie OCaml selbst installiert werden, was wir in Guix aber nicht so haben wollen. Solche Pakete installieren ihre .so-Dateien in das Verzeichnis ihres Moduls, was für die meisten anderen Einrichtungen funktioniert, weil es im OCaml-Compilerverzeichnis liegt. Jedoch können so in Guix die Bibliotheken nicht gefunden werden, deswegen benutzen wir CAML_LD_LIBRARY_PATH. Diese Umgebungsvariable zeigt auf lib/ocaml/site-lib/stubslibs und dorthin sollten .so-Bibliotheken installiert werden.

 -- Scheme-Variable: python-build-system
     Diese Variable wird vom Modul (guix build-system python) exportiert. Sie implementiert mehr oder weniger die konventionelle Erstellungsprozedur, wie sie für Python-Pakete üblich ist, d.h. erst wird python setup.py build ausgeführt und dann python setup.py install --prefix=/gnu/store/....

     Für Pakete, die eigenständige Python-Programme nach bin/ installieren, sorgt dieses Erstellungssystem dafür, dass die Programme in ein Wrapper-Skript verpackt werden, welches die eigentlichen Programme mit einer Umgebungsvariablen PYTHONPATH aufruft, die alle Python-Bibliotheken auflistet, von denen die Programme abhängen.

     Welches Python-Paket benutzt wird, um die Erstellung durchzuführen, kann mit dem Parameter #:python bestimmt werden. Das ist nützlich, wenn wir erzwingen wollen, dass ein Paket mit einer bestimmten Version des Python-Interpretierers arbeitet, was nötig sein kann, wenn das Programm nur mit einer einzigen Interpretiererversion kompatibel ist.

     Standardmäßig ruft Guix setup.py auf, was zu setuptools gehört, ähnlich wie es auch pip tut. Manche Pakete sind mit setuptools (und pip) inkompatibel, deswegen können Sie diese Einstellung abschalten, indem Sie den Parameter #:use-setuptools auf #f setzen.

 -- Scheme-Variable: perl-build-system
     Diese Variable wird vom Modul (guix build-system perl) exportiert. Mit ihr wird die Standard-Erstellungsprozedur für Perl-Pakete implementiert, welche entweder darin besteht, perl Build.PL --prefix=/gnu/store/... gefolgt von Build und Build install auszuführen, oder perl Makefile.PL PREFIX=/gnu/store/... gefolgt von make und make install auszuführen, je nachdem, ob eine Datei Build.PL oder eine Datei Makefile.PL in der Paketdistribution vorliegt. Den Vorrang hat erstere, wenn sowohl Build.PL als auch Makefile.PL in der Paketdistribution existieren. Der Vorrang kann umgekehrt werden, indem #t für den Parameter #:make-maker? angegeben wird.

     Der erste Aufruf von perl Makefile.PL oder perl Build.PL übergibt die im Parameter #:make-maker-flags bzw. #:module-build-flags angegebenen Befehlszeilenoptionen, je nachdem, was verwendet wird.

     Welches Perl-Paket dafür benutzt wird, kann mit #:perl angegeben werden.

 -- Scheme-Variable: r-build-system
     Diese Variable wird vom Modul (guix build-system r) exportiert. Sie entspricht einer Implementierung der durch R (http://r-project.org)-Pakete genutzten Erstellungsprozedur, die wenig mehr tut, als R CMD INSTALL --library=/gnu/store/... in einer Umgebung auszuführen, in der die Umgebungsvariable R_LIBS_SITE die Pfade aller R-Pakete unter den Paketeingaben enthält. Tests werden nach der Installation mit der R-Funktion tools::testInstalledPackage ausgeführt.

 -- Scheme-Variable: texlive-build-system
     Diese Variable wird vom Modul (guix build-system texlive) exportiert. Mit ihr werden TeX-Pakete in Stapelverarbeitung (»batch mode«) mit der angegebenen Engine erstellt. Das Erstellungssystem setzt die Variable TEXINPUTS so, dass alle TeX-Quelldateien unter den Eingaben gefunden werden können.

     Standardmäßig wird luatex auf allen Dateien mit der Dateiendung ins ausgeführt. Eine andere Engine oder ein anderes Format kann mit dem Argument #:tex-format angegeben werden. Verschiedene Erstellungsziele können mit dem Argument #:build-targets festgelegt werden, das eine Liste von Dateinamen erwartet. Das Erstellungssystem fügt nur texlive-bin und texlive-latex-base zu den Eingaben hinzu (beide kommen aus dem Modul (gnu packages tex). Für beide kann das zu benutzende Paket jeweils mit den Argumenten #:texlive-bin oder #:texlive-latex-base geändert werden.

     Der Parameter #:tex-directory sagt dem Erstellungssystem, wohin die installierten Dateien im texmf-Verzeichnisbaum installiert werden sollen.

 -- Scheme-Variable: ruby-build-system
     Diese Variable wird vom Modul (guix build-system ruby) exportiert. Sie steht für eine Implementierung der RubyGems-Erstellungsprozedur, die für Ruby-Pakete benutzt wird, wobei gem build gefolgt von gem install ausgeführt wird.

     Das source-Feld eines Pakets, das dieses Erstellungssystem benutzt, verweist typischerweise auf ein Gem-Archiv, weil Ruby-Entwickler dieses Format benutzen, wenn sie ihre Software veröffentlichen. Das Erstellungssystem entpackt das Gem-Archiv, spielt eventuell Patches für den Quellcode ein, führt die Tests aus, verpackt alles wieder in ein Gem-Archiv und installiert dieses. Neben Gem-Archiven darf das Feld auch auf Verzeichnisse und Tarballs verweisen, damit es auch möglich ist, unveröffentlichte Gems aus einem Git-Repository oder traditionelle Quellcode-Veröffentlichungen zu benutzen.

     Welches Ruby-Paket benutzt werden soll, kann mit dem Parameter #:ruby festgelegt werden. Eine Liste zusätzlicher Befehlszeilenoptionen für den Aufruf des gem-Befehls kann mit dem Parameter #:gem-flags angegeben werden.

 -- Scheme-Variable: waf-build-system
     Diese Variable wird durch das Modul (guix build-system waf) exportiert. Damit ist eine Erstellungsprozedur rund um das waf-Skript implementiert. Die üblichen Phasen — configure, build und install — sind implementiert, indem deren Namen als Argumente an das waf-Skript übergeben werden.

     Das waf-Skript wird vom Python-Interpetierer ausgeführt. Mit welchem Python-Paket das Skript ausgeführt werden soll, kann mit dem Parameter #:python angegeben werden.

 -- Scheme-Variable: scons-build-system
     Diese Variable wird vom Modul (guix build-system scons) exportiert. Sie steht für eine Implementierung der Erstellungsprozedur, die das SCons-Softwarekonstruktionswerkzeug (»software construction tool«) benutzt. Das Erstellungssystem führt scons aus, um das Paket zu erstellen, führt mit scons test Tests aus und benutzt scons install, um das Paket zu installieren.

     Zusätzliche Optionen, die an scons übergeben werden sollen, können mit dem Parameter #:scons-flags angegeben werden. Die Python-Version, die benutzt werden soll, um SCons auszuführen, kann festgelegt werden, indem das passende SCons-Paket mit dem Parameter #:scons ausgewählt wird.

 -- Scheme-Variable: haskell-build-system
     Diese Variable wird vom Modul (guix build-system haskell) exportiert. Sie bietet Zugang zur Cabal-Erstellungsprozedur, die von Haskell-Paketen benutzt wird, was bedeutet, runhaskell Setup.hs configure --prefix=/gnu/store/... und runhaskell Setup.hs build auszuführen. Statt das Paket mit dem Befehl runhaskell Setup.hs install zu installieren, benutzt das Erstellungssystem runhaskell Setup.hs copy gefolgt von runhaskell Setup.hs register, um keine Bibliotheken im Store-Verzeichnis des Compilers zu speichern, auf dem keine Schreibberechtigung besteht. Zusätzlich generiert das Erstellungssystem Dokumentation durch Ausführen von runhaskell Setup.hs haddock, außer #:haddock? #f wurde übergeben. Optional können an Haddock Parameter mit Hilfe des Parameters #:haddock-flags übergeben werden. Wird die Datei Setup.hs nicht gefunden, sucht das Erstellungssystem stattdessen nach Setup.lhs.

     Welcher Haskell-Compiler benutzt werden soll, kann über den #:haskell-Parameter angegeben werden. Als Vorgabewert verwendet er ghc.

 -- Scheme-Variable: dub-build-system
     Diese Variable wird vom Modul (guix build-system dub) exportiert. Sie verweist auf eine Implementierung des Dub-Erstellungssystems, das von D-Paketen benutzt wird. Dabei werden dub build und dub run ausgeführt. Die Installation wird durch manuelles Kopieren der Dateien durchgeführt.

     Welcher D-Compiler benutzt wird, kann mit dem Parameter #:ldc festgelegt werden, was als Vorgabewert ldc benutzt.

 -- Scheme-Variable: emacs-build-system
     Diese Variable wird vom Modul (guix build-system emacs) exportiert. Darin wird eine Installationsprozedur ähnlich der des Paketsystems von Emacs selbst implementiert (see Packages (The GNU Emacs Manual)).

     Zunächst wird eine Datei PAKET-autoloads.el erzeugt, dann werden alle Emacs-Lisp-Dateien zu Bytecode kompiliert. Anders als beim Emacs-Paketsystem werden die Info-Dokumentationsdateien in das Standardverzeichnis für Dokumentation verschoben und die Datei dir gelöscht. Jedes Paket wird in sein eigenes Verzeichnis unter share/emacs/site-lisp/guix.d installiert.

 -- Scheme-Variable: font-build-system
     This variable is exported by (guix build-system font).  It implements an installation procedure for font packages where upstream provides pre-compiled TrueType, OpenType, etc. font files that merely need to be copied into place.  It copies font files to standard locations in the output directory.

 -- Scheme-Variable: meson-build-system
     Diese Variable wird vom Modul (guix build-system meson) exportiert. Sie enthält die Erstellungsprozedur für Pakete, die Meson (http://mesonbuild.com) als ihr Erstellungssystem benutzen.

     Mit ihr werden sowohl Meson als auch Ninja (https://ninja-build.org/) zur Menge der Eingaben hinzugefügt; die Pakete dafür können mit den Parametern #:meson und #:ninja geändert werden, wenn nötig. Das vorgegebene Meson-Paket ist meson-for-build, ein besonderes Paket, dessen Besonderheit darin besteht, den RUNPATH von Binärdateien und Bibliotheken nicht zu entfernen, wenn sie installiert werden.

     Dieses Erstellungssystem ist eine Erweiterung für das GNU-BUILD-SYSTEM, aber mit Änderungen an den folgenden Phasen, die Meson-spezifisch sind:

     configure
          Diese Phase führt den meson-Befehl mit den in #:configure-flags angegebenen Befehlszeilenoptionen aus. Die Befehlszeilenoption --build-type wird immer auf plain gesetzt, solange nichts anderes mit dem Parameter #:build-type angegeben wurde.

     build
          Diese Phase ruft ninja auf, um das Paket standardmäßig parallel zu erstellen. Die Vorgabeeinstellung, dass parallel erstellt wird, kann verändert werden durch Setzen von #:parallel-build?.

     check
          Diese Phase führt ninja mit dem als #:test-target spezifizierten Ziel für Tests auf, der Vorgabewert ist das Ziel namens "test".

     install
          Diese Phase führt ninja install aus und kann nicht verändert werden.

     Dazu fügt das Erstellungssystem noch folgende neue Phasen:

     fix-runpath
          In dieser Phase wird sichergestellt, dass alle Binärdateien die von ihnen benötigten Bibliotheken finden können. Die benötigten Bibliotheken werden in den Unterverzeichnissen des Pakets, das erstellt wird, gesucht, und zum RUNPATH hinzugefügt, wann immer es nötig ist. Auch werden diejenigen Referenzen zu Bibliotheken aus der Erstellungsphase wieder entfernt, die bei meson-for-build hinzugefügt wurden, aber eigentlich zur Laufzeit nicht gebraucht werden, wie Abhängigkeiten nur für Tests.

     glib-or-gtk-wrap
          Diese Phase ist dieselbe, die auch im glib-or-gtk-build-system zur Verfügung gestellt wird, und mit Vorgabeeinstellungen wird sie nicht durchlaufen. Wenn sie gebraucht wird, kann sie mit dem Parameter #:glib-or-gtk? aktiviert werden.

     glib-or-gtk-compile-schemas
          Diese Phase ist dieselbe, die auch im glib-or-gtk-build-system zur Verfügung gestellt wird, und mit Vorgabeeinstellungen wird sie nicht durchlaufen. Wenn sie gebraucht wird, kann sie mit dem Parameter #:glib-or-gtk? aktiviert werden.

Letztlich gibt es für die Pakete, die bei weitem nichts so komplexes brauchen, ein »triviales« Erstellungssystem. Es ist in dem Sinn trivial, dass es praktisch keine Hilfestellungen gibt: Es fügt keine impliziten Eingaben hinzu und hat kein Konzept von Erstellungsphasen.

 -- Scheme-Variable: trivial-build-system
     Diese Variable wird vom Modul (guix build-system trivial) exportiert.

     Diesem Erstellungssystem muss im Argument #:builder ein Scheme-Ausdruck übergeben werden, der die Paketausgabe(n) erstellt — wie bei build-expression->derivation (see build-expression->derivation).

Der Store
=========

Konzeptionell ist der Store der Ort, wo Ableitungen nach erfolgreicher Erstellung gespeichert werden — standardmäßig finden Sie ihn in /gnu/store. Unterverzeichnisse im Store werden Store-Objekte oder manchmal auch Store-Pfade genannt. Mit dem Store ist eine Datenbank assoziiert, die Informationen enthält wie zum Beispiel, welche Store-Pfade jeder Store-Pfad jeweils referenziert, und eine Liste, welche Store-Objekte gültig sind, also Ergebnisse erfolgreicher Erstellungen sind. Die Datenbank befindet sich in LOCALSTATEDIR/guix/db, wobei LOCALSTATEDIR das mit --localstatedir bei der Ausführung von »configure« angegebene Zustandsverzeichnis ist, normalerweise /var.

Auf den Store wird nur durch den Daemon im Auftrag seiner Clients zugegriffen (see Aufruf des guix-daemon). Um den Store zu verändern, verbinden sich Clients über einen Unix-Socket mit dem Daemon, senden ihm entsprechende Anfragen und lesen dann dessen Antwort — so etwas nennt sich entfernter Prozeduraufruf (englisch »Remote Procedure Call« oder kurz RPC).

     Benutzer dürfen niemals Dateien in /gnu/store direkt verändern, sonst wären diese nicht mehr konsistent und die Grundannahmen im funktionalen Modell von Guix, dass die Objekte unveränderlich sind, wären dahin (see Einführung).

     Siehe guix gc --verify, für Informationen, wie die Integrität des Stores überprüft und nach versehentlichen Veränderungen unter Umständen wiederhergestellt werden kann.

Das Modul (guix store) bietet Prozeduren an, um sich mit dem Daemon zu verbinden und entfernte Prozeduraufrufe durchzuführen. Diese werden im Folgenden beschrieben. Das vorgegebene Verhalten von open-connection, und daher allen guix-Befehlen, ist, sich mit dem lokalen Daemon oder dem an der in der Umgebungsvariablen GUIX_DAEMON_SOCKET angegeben URL zu verbinden.

 -- Umgebungsvariable: GUIX_DAEMON_SOCKET
     Ist diese Variable gesetzt, dann sollte ihr Wert ein Dateipfad oder eine URI sein, worüber man sich mit dem Daemon verbinden kann. Ist der Wert der Pfad zu einer Datei, bezeichnet dieser einen Unix-Socket, mit dem eine Verbindung hergestellt werden soll. Ist er eine URI, so werden folgende URI-Schemata unterstützt:

     file
     unix
          Für Unix-Sockets. file:///var/guix/daemon-socket/socket kann gleichbedeutend auch als /var/guix/daemon-socket/socket angegeben werden.

     guix
          Solche URIs benennen Verbindungen über TCP/IP ohne Verschlüsselung oder Authentifizierung des entfernten Rechners. Die URI muss den Hostnamen, also den Rechnernamen des entfernten Rechners, und optional eine Port-Nummer angeben (sonst wird als Vorgabe der Port 44146 benutzt):

               guix://master.guix.example.org:1234

          Diese Konfiguration ist für lokale Netzwerke wie etwa in Rechen-Clustern geeignet, wo sich nur vertrauenswürdige Knoten mit dem Erstellungs-Daemon z.B. unter master.guix.example.org verbinden können.

          Die Befehlszeilenoption --listen von guix-daemon kann benutzt werden, damit er auf TCP-Verbindungen lauscht (see --listen).

     ssh
          Mit solchen URIs kann eine Verbindung zu einem entfernten Daemon über SSH hergestellt werden (Diese Funktionalitäts setzt Guile-SSH voraus (see Voraussetzungen).). Eine typische URL sieht so aus:

               ssh://charlie@guix.example.org:22

          Was guix copy betrifft, richtet es sich nach den üblichen OpenSSH-Client-Konfigurationsdateien (see Aufruf von guix copy).

     In Zukunft könnten weitere URI-Schemata unterstützt werden.

          Die Fähigkeit, sich mit entfernten Erstellungs-Daemons zu verbinden, sehen wir als experimentell an, Stand VERSION. Bitte diskutieren Sie mit uns jegliche Probleme oder Vorschläge, die Sie haben könnten (see Mitwirken).

 -- Scheme-Prozedur: open-connection [URI] [#:reserve-space? #t]
     Sich mit dem Daemon über den Unix-Socket an URI verbinden (einer Zeichenkette). Wenn RESERVE-SPACE? wahr ist, lässt ihn das etwas zusätzlichen Speicher im Dateisystem reservieren, damit der Müllsammler auch dann noch funktioniert, wenn die Platte zu voll wird. Liefert ein Server-Objekt.

     URI nimmt standardmäßig den Wert von %DEFAULT-SOCKET-PATH an, was dem bei der Installation mit dem Aufruf von configure ausgewählten Vorgabeort entspricht, gemäß den Befehlszeilenoptionen, mit denen configure aufgerufen wurde.

 -- Scheme-Prozedur: close-connection SERVER
     Die Verbindung zum SERVER trennen.

 -- Scheme-Variable: current-build-output-port
     Diese Variable ist an einen SRFI-39-Parameter gebunden, der auf den Scheme-Port verweist, an den vom Daemon empfangene Erstellungsprotokolle und Fehlerprotokolle geschrieben werden sollen.

Prozeduren, die entfernte Prozeduraufrufe durchführen, nehmen immer ein Server-Objekt als ihr erstes Argument.

 -- Scheme-Prozedur: valid-path? SERVER PFAD
     Liefert #t, wenn der PFAD ein gültiges Store-Objekt benennt, und sonst #f (ein ungültiges Objekt kann auf der Platte gespeichert sein, tatsächlich aber ungültig sein, zum Beispiel weil es das Ergebnis einer abgebrochenen oder fehlgeschlagenen Erstellung ist).

     A &store-protocol-error condition is raised if PATH is not prefixed by the store directory (/gnu/store).

 -- Scheme-Prozedur: add-text-to-store SERVER NAME TEXT [REFERENZEN]
     Den TEXT im Store in einer Datei namens NAME ablegen und ihren Store-Pfad zurückliefern. REFERENZEN ist die Liste der Store-Pfade, die der Store-Pfad dann referenzieren soll.

 -- Scheme-Prozedur: build-derivations SERVER ABLEITUNGEN
     Die ABLEITUNGEN erstellen (eine Liste von <derivation>-Objekten oder von Pfaden zu Ableitungen) und terminieren, sobald der Worker-Prozess mit dem Erstellen fertig ist. Liefert #t bei erfolgreicher Erstellung.

Es sei erwähnt, dass im Modul (guix monads) eine Monade sowie monadische Versionen obiger Prozeduren angeboten werden, damit an Code, der auf den Store zugreift, bequemer gearbeitet werden kann (see Die Store-Monade).

Dieser Abschnitt ist im Moment noch unvollständig.

Ableitungen
===========

Systemnahe Erstellungsaktionen sowie die Umgebung, in der selbige durchzuführen sind, werden durch Ableitungen dargestellt. Eine Ableitung enthält folgende Informationen:

  * Die Ausgaben, die die Ableitung hat. Ableitungen erzeugen mindestens eine Datei bzw. ein Verzeichnis im Store, können aber auch mehrere erzeugen.

  * The inputs of the derivations---i.e., its build-time dependencies---which may be other derivations or plain files in the store (patches, build scripts, etc.)

  * Das System, wofür mit der Ableitung erstellt wird, also ihr Ziel — z.B. x86_64-linux.

  * Der Dateiname eines Erstellungsskripts im Store, zusammen mit den Argumenten, mit denen es aufgerufen werden soll.

  * Eine Liste zu definierender Umgebungsvariabler.

Ableitungen ermöglichen es den Clients des Daemons, diesem Erstellungsaktionen für den Store mitzuteilen. Es gibt davon zwei Arten, sowohl Darstellungen im Arbeitsspeicher jeweils für Client und Daemon, als auch Dateien im Store, deren Namen auf .drv enden — diese Dateien werden als Ableitungspfade bezeichnet. Ableitungspfade können an die Prozedur build-derivations übergeben werden, damit die darin niedergeschriebenen Erstellungsaktionen durchgeführt werden (see Der Store).

Operationen wie das Herunterladen von Dateien und Checkouts von unter Versionskontrolle stehenden Quelldateien, bei denen der Hash des Inhalts im Voraus bekannt ist, werden als Ableitungen mit fester Ausgabe modelliert. Anders als reguläre Ableitungen sind die Ausgaben von Ableitungen mit fester Ausgabe unabhängig von ihren Eingaben — z.B. liefert das Herunterladen desselben Quellcodes dasselbe Ergebnis unabhängig davon, mit welcher Methode und welchen Werkzeugen er heruntergeladen wurde.

The outputs of derivations---i.e., the build results---have a set of references, as reported by the references RPC or the guix gc --references command (see Aufruf von guix gc). References are the set of run-time dependencies of the build results. References are a subset of the inputs of the derivation; this subset is automatically computed by the build daemon by scanning all the files in the outputs.

Das Modul (guix derivations) stellt eine Repräsentation von Ableitungen als Scheme-Objekte zur Verfügung, zusammen mit Prozeduren, um Ableitungen zu erzeugen und zu manipulieren. Die am wenigsten abstrahierte Methode, eine Ableitung zu erzeugen, ist mit der Prozedur derivation:

 -- Scheme-Prozedur: derivation STORE NAME ERSTELLER
     ARGUMENTE [#:outputs '("out")] [#:hash #f] [#:hash-algo #f]
     [#:recursive? #f] [#:inputs '()] [#:env-vars '()]  [#:system
     (%current-system)] [#:references-graphs #f]  [#:allowed-references #f] [#:disallowed-references #f]  [#:leaked-env-vars #f] [#:local-build? #f] [#:substitutable? #t] [#:properties '()] Eine Ableitungen mit den ARGUMENTEn erstellen und das resultierende <derivation>-Objekt liefern.

     Wurden HASH und HASH-ALGO angegeben, wird eine Ableitung mit fester Ausgabe erzeugt — d.h. eine, deren Ausgabe schon im Voraus bekannt ist, wie z.B. beim Herunterladen einer Datei. Wenn des Weiteren auch RECURSIVE? wahr ist, darf die Ableitung mit fester Ausgabe eine ausführbare Datei oder ein Verzeichnis sein und HASH muss die Prüfsumme eines Archivs mit dieser Ausgabe sein.

     Ist REFERENCES-GRAPHS wahr, dann muss es eine Liste von Paaren aus je einem Dateinamen und einem Store-Pfad sein. In diesem Fall wird der Referenzengraph jedes Store-Pfads in einer Datei mit dem angegebenen Namen in der Erstellungsumgebung zugänglich gemacht, in einem einfachen Text-Format.

     Ist ALLOWED-REFERENCES ein wahr, muss es eine Liste von Store-Objekten oder Ausgaben sein, die die Ausgabe der Ableitung referenzieren darf. Ebenso muss DISALLOWED-REFERENCES, wenn es auf wahr gesetzt ist, eine Liste von Dingen bezeichnen, die die Ausgaben nicht referenzieren dürfen.

     Ist LEAKED-ENV-VARS wahr, muss es eine Liste von Zeichenketten sein, die Umgebungsvariable benennen, die aus der Umgebung des Daemons in die Erstellungsumgebung überlaufen — ein »Leck«, englisch »leak«. Dies kann nur in Ableitungen mit fester Ausgabe benutzt werden, also wenn HASH wahr ist. So ein Leck kann zum Beispiel benutzt werden, um Variable wie http_proxy an Ableitungen zu übergeben, die darüber Dateien herunterladen.

     Ist LOCAL-BUILD? wahr, wird die Ableitung als schlechter Kandidat für das Auslagern deklariert, der besser lokal erstellt werden sollte (see Auslagern des Daemons einrichten). Dies betrifft kleine Ableitungen, wo das Übertragen der Daten aufwendiger als ihre Erstellung ist.

     Ist SUBSTITUTABLE? falsch, wird deklariert, dass für die Ausgabe der Ableitung keine Substitute benutzt werden sollen (see Substitute). Das ist nützlich, wenn Pakete erstellt werden, die Details über den Prozessorbefehlssatz des Wirtssystems auslesen.

     PROPERTIES muss eine assoziative Liste enthalten, die »Eigenschaften« der Ableitungen beschreibt. Sie wird genau so, wie sie ist, in der Ableitung gespeichert.

Hier ist ein Beispiel mit einem Shell-Skript, das als Ersteller benutzt wird. Es wird angenommen, dass STORE eine offene Verbindung zum Daemon ist und BASH auf eine ausführbare Bash im Store verweist:

     (use-modules (guix utils)
                  (guix store)
                  (guix derivations))

     (let ((builder   ; das Ersteller-Bash-Skript in den Store einfügen
             (add-text-to-store store "my-builder.sh"
                                "echo Hallo Welt > $out\n" '())))
       (derivation store "foo"
                   bash `("-e" ,builder)
                   #:inputs `((,bash) (,builder))
                   #:env-vars '(("HOME" . "/homeless"))))
     => #<derivation /gnu/store/...-foo.drv => /gnu/store/...-foo>

Wie man sehen kann, ist es umständlich, diese grundlegende Methode direkt zu benutzen. Natürlich ist es besser, Erstellungsskripts in Scheme zu schreiben! Am besten schreibt man den Erstellungscode als »G-Ausdruck« und übergibt ihn an gexp->derivation. Mehr Informationen finden Sie im Abschnitt see G-Ausdrücke.

Doch es gab einmal eine Zeit, zu der gexp->derivation noch nicht existiert hatte und wo das Zusammenstellen von Ableitungen mit Scheme-Erstellungscode noch mit build-expression->derivation bewerkstelligt wurde, was im Folgenden beschrieben wird. Diese Prozedur gilt als veraltet und man sollte nunmehr die viel schönere Prozedur gexp->derivation benutzen.

 -- Scheme-Prozedur: build-expression->derivation STORE
     NAME AUSDRUCK  [#:system (%current-system)] [#:inputs '()]
     [#:outputs '("out")] [#:hash #f] [#:hash-algo #f]  [#:recursive? #f]
     [#:env-vars '()] [#:modules '()]  [#:references-graphs #f] [#:allowed-references #f]  [#:disallowed-references #f]  [#:local-build? #f] [#:substitutable? #t] [#:guile-for-build #f] Liefert eine Ableitung, die den Scheme-Ausdruck AUSDRUCK als Ersteller einer Ableitung namens NAME ausführt. INPUTS muss die Liste der Eingaben enthalten, jeweils als Tupel (Name Ableitungspfad Unterableitung); wird keine UNTERABLEITUNG angegeben, wird "out" angenommen. MODULE ist eine Liste der Namen von Guile-Modulen im momentanen Suchpfad, die in den Store kopiert, kompiliert und zur Verfügung gestellt werden, wenn der AUSDRUCK ausgeführt wird — z.B. ((guix build utils) (guix build gnu-build-system)).

     Der AUSDRUCK wird in einer Umgebung ausgewertet, in der %outputs an eine Liste von Ausgabe-/Pfad-Paaren gebunden wurde und in der %build-inputs an eine Liste von Zeichenkette-/Ausgabepfad-Paaren gebunden wurde, die aus den INPUTS-Eingaben konstruiert worden ist. Optional kann in ENV-VARS eine Liste von Paaren aus Zeichenketten stehen, die Name und Wert von für den Ersteller sichtbaren Umgebungsvariablen angeben. Der Ersteller terminiert, indem er exit mit dem Ergebnis des AUSDRUCKs aufruft; wenn also der AUSDRUCK den Wert #f liefert, wird angenommen, dass die Erstellung fehlgeschlagen ist.

     AUSDRUCK wird mit einer Ableitung GUILE-FOR-BUILD erstellt. Wird kein GUILE-FOR-BUILD angegeben oder steht es auf #f, wird stattdessen der Wert der Fluiden %guile-for-build benutzt.

     Siehe die Erklärungen zur Prozedur derivation für die Bedeutung von REFERENCES-GRAPHS, ALLOWED-REFERENCES, DISALLOWED-REFERENCES, LOCAL-BUILD? und SUBSTITUTABLE?.

Hier ist ein Beispiel einer Ableitung mit nur einer Ausgabe, die ein Verzeichnis erzeugt, in dem eine einzelne Datei enthalten ist:

     (let ((builder '(let ((out (assoc-ref %outputs "out")))
                       (mkdir out)    ; das Verzeichnis
                                      ; /gnu/store/...-goo erstellen
                       (call-with-output-file (string-append out "/test")
                         (lambda (p)
                           (display '(Hallo Guix) p))))))
       (build-expression->derivation store "goo" builder))

     => #<derivation /gnu/store/...-goo.drv => ...>

Die Store-Monade
================

Die auf dem Store arbeitenden Prozeduren, die in den vorigen Abschnitten beschrieben wurden, nehmen alle eine offene Verbindung zum Erstellungs-Daemon als ihr erstes Argument entgegen. Obwohl das ihnen zu Grunde liegende Modell funktional ist, weisen sie doch alle Nebenwirkungen auf oder hängen vom momentanen Zustand des Stores ab.

Ersteres ist umständlich, weil die Verbindung zum Erstellungs-Daemon zwischen all diesen Funktionen durchgereicht werden muss, so dass eine Komposition mit Funktionen ohne diesen Parameter unmöglich wird. Letzteres kann problematisch sein, weil Operationen auf dem Store Nebenwirkungen und/oder Abhängigkeiten von externem Zustand haben und ihre Ausführungsreihenfolge deswegen eine Rolle spielt.

Hier kommt das Modul (guix monads) ins Spiel. Im Rahmen dieses Moduls können Monaden benutzt werden und dazu gehört insbesondere eine für unsere Zwecke sehr nützliche Monade, die Store-Monade. Monaden sind ein Konstrukt, mit dem zwei Dinge möglich sind: eine Assoziation von Werten mit einem »Kontext« (in unserem Fall ist das die Verbindung zum Store) und das Festlegen einer Reihenfolge für Berechnungen (hiermit sind auch Zugriffe auf den Store gemeint). Werte in einer Monade — solche, die mit weiterem Kontext assoziiert sind — werden monadische Werte genannt; Prozeduren, die solche Werte liefern, heißen monadische Prozeduren.

Betrachten Sie folgende »normale« Prozedur:

     (define (sh-symlink store)
       ;; Eine Ableitung liefern, die mit der ausführbaren Datei »bash«
       ;; symbolisch verknüpft.
       (let* ((drv (package-derivation store bash))
              (out (derivation->output-path drv))
              (sh  (string-append out "/bin/bash")))
         (build-expression->derivation store "sh"
                                       `(symlink ,sh %output))))

Unter Verwendung von (guix monads) und (guix gexp) lässt sie sich als monadische Funktion aufschreiben:

     (define (sh-symlink)
       ;; Ebenso, liefert aber einen monadischen Wert.
       (mlet %store-monad ((drv (package->derivation bash)))
         (gexp->derivation "sh"
                           #~(symlink (string-append #$drv "/bin/bash")
                                      #$output))))

An der zweiten Version lassen sich mehrere Dinge beobachten: Der Parameter Store ist jetzt implizit geworden und wurde in die Aufrufe der monadischen Prozeduren package->derivation und gexp->derivation »eingefädelt« und der von package->derivation gelieferte monadische Wert wurde mit mlet statt einem einfachen let gebunden.

Wie sich herausstellt, muss man den Aufruf von package->derivation nicht einmal aufschreiben, weil er implizit geschieht, wie wir später sehen werden (siehe G-Ausdrücke):

     (define (sh-symlink)
       (gexp->derivation "sh"
                         #~(symlink (string-append #$bash "/bin/bash")
                                    #$output)))

Die monadische sh-symlink einfach aufzurufen, bewirkt nichts. Wie jemand einst sagte: »Mit einer Monade geht man um, wie mit Gefangenen, gegen die man keine Beweise hat: Man muss sie laufen lassen.« Um also aus der Monade auszubrechen und die gewünschte Wirkung zu erzielen, muss man run-with-store benutzen:

     (run-with-store (open-connection) (sh-symlink))
     => /gnu/store/...-sh-symlink

Erwähnenswert ist, dass das Modul (guix monad-repl) die REPL von Guile um neue »Meta-Befehle« erweitert, mit denen es leichter ist, mit monadischen Prozeduren umzugehen: run-in-store und enter-store-monad. Mit Ersterer wird ein einzelner monadischer Wert durch den Store »laufen gelassen«:

     scheme@(guile-user)> ,run-in-store (package->derivation hello)
     $1 = #<derivation /gnu/store/...-hello-2.9.drv => ...>

Mit Letzterer wird rekursiv eine weitere REPL betreten, in der alle Rückgabewerte automatisch durch den Store laufen gelassen werden:

     scheme@(guile-user)> ,enter-store-monad
     store-monad@(guile-user) [1]> (package->derivation hello)
     $2 = #<derivation /gnu/store/...-hello-2.9.drv => ...>
     store-monad@(guile-user) [1]> (text-file "foo" "Hallo!")
     $3 = "/gnu/store/...-foo"
     store-monad@(guile-user) [1]> ,q
     scheme@(guile-user)>

Beachten Sie, dass in einer store-monad-REPL keine nicht-monadischen Werte zurückgeliefert werden können.

Die wichtigsten syntaktischen Formen, um mit Monaden im Allgemeinen umzugehen, werden im Modul (guix monads) bereitgestellt und sind im Folgenden beschrieben.

 -- Scheme-Syntax: with-monad MONADE RUMPF ...
     Alle >>=- oder return-Formen im RUMPF in der MONADE auswerten.

 -- Scheme-Syntax: return WERT
     Einen monadischen Wert liefern, der den übergebenen WERT kapselt.

 -- Scheme-Syntax: >>= MWERT MPROZ ...
     Den monadischen Wert MWERT binden, wobei sein »Inhalt« an die monadischen Prozeduren MPROZ... übergeben wird (Diese Operation wird gemeinhin »bind« genannt, aber mit diesem Begriff wird in Guile eine völlig andere Prozedur bezeichnet, die nichts damit zu tun hat. Also benutzen wir dieses etwas kryptische Symbol als Erbe der Haskell-Programmiersprache.). Es kann eine einzelne MPROZ oder mehrere davon geben, wie in diesem Beispiel:

          (run-with-state
              (with-monad %state-monad
                (>>= (return 1)
                     (lambda (x) (return (+ 1 x)))
                     (lambda (x) (return (* 2 x)))))
            'irgendein-Zustand)

          => 4
          => irgendein-Zustand

 -- Scheme-Syntax: mlet MONADE ((VARIABLE MWERT) ...)
     RUMPF ...
 -- Scheme-Syntax: mlet* MONADE ((VARIABLE MWERT) ...)
     RUMPF ...  Die VARIABLEn an die monadischen Werte MWERT im
     RUMPF binden, der eine Folge von Ausdrücken ist. Wie beim bind-Operator kann man es sich vorstellen als »Auspacken« des rohen, nicht-monadischen Werts, der im MWERT steckt, wobei anschließend dieser rohe, nicht-monadische Wert im Sichtbarkeitsbereich des RUMPFs von der VARIABLEn bezeichnet wird. Die Form (VARIABLE -> WERT) bindet die VARIABLE an den »normalen« WERT, wie es let tun würde. Die Bindungsoperation geschieht in der Reihenfolge von links nach rechts. Der letzte Ausdruck des RUMPFS muss ein monadischer Ausdruck sein und dessen Ergebnis wird das Ergebnis von mlet oder mlet* werden, wenn es durch die MONAD laufen gelassen wurde.

     mlet* verhält sich gegenüber mlet wie let* gegenüber let (see Local Bindings (GNU Guile Reference Manual)).

 -- Scheme-System: mbegin MONADE MAUSDRUCK ...
     Der Reihe nach den MAUSDRUCK und die nachfolgenden monadischen Ausdrücke binden und als Ergebnis das des letzten Ausdrucks liefern. Jeder Ausdruck in der Abfolge muss ein monadischer Ausdruck sein.

     Dies verhält sich ähnlich wie mlet, außer dass die Rückgabewerte der monadischen Prozeduren ignoriert werden. In diesem Sinn verhält es sich analog zu begin, nur auf monadischen Ausdrücken.

 -- Scheme-System: mwhen BEDINGUNG MAUSDR0 MAUSDR* ...
     Wenn die BEDINGUNG wahr ist, wird die Folge monadischer Ausdrücke MAUSDR0..MAUSDR* wie bei mbegin ausgewertet. Wenn die BEDINGUNG falsch ist, wird *unspecified* in der momentanen Monade zurückgeliefert. Jeder Ausdruck in der Folge muss ein monadischer Ausdruck sein.

 -- Scheme-System: munless BEDINGUNG MAUSDR0 MAUSDR* ...
     Wenn die BEDINGUNG falsch ist, wird die Folge monadischer Ausdrücke MAUSDR0..MAUSDR* wie bei mbegin ausgewertet. Wenn die BEDINGUNG wahr ist, wird *unspecified* in der momentanen Monade zurückgeliefert. Jeder Ausdruck in der Folge muss ein monadischer Ausdruck sein.

Das Modul (guix monads) macht die Zustandsmonade (englisch »state monad«) verfügbar, mit der ein zusätzlicher Wert — der Zustand — durch die monadischen Prozeduraufrufe gefädelt werden kann.

 -- Scheme-Variable: %state-monad
     Die Zustandsmonade. Prozeduren in der Zustandsmonade können auf den gefädelten Zustand zugreifen und ihn verändern.

     Betrachten Sie das folgende Beispiel. Die Prozedur Quadrat liefert einen Wert in der Zustandsmonade zurück. Sie liefert das Quadrat ihres Arguments, aber sie inkrementiert auch den momentanen Zustandswert:

          (define (Quadrat x)
            (mlet %state-monad ((Anzahl (current-state)))
              (mbegin %state-monad
                (set-current-state (+ 1 Anzahl))
                (return (* x x)))))

          (run-with-state (sequence %state-monad (map Quadrat (iota 3))) 0)
          => (0 1 4)
          => 3

     Wird das »durch« die Zustandsmonade %STATE-MONAD laufen gelassen, erhalten wir jenen zusätzlichen Zustandswert, der der Anzahl der Aufrufe von Quadrat entspricht.

 -- Monadische Prozedur: current-state
     Liefert den momentanen Zustand als einen monadischen Wert.

 -- Monadische Prozedur: set-current-state WERT
     Setzt den momentanen Zustand auf WERT und liefert den vorherigen Zustand als einen monadischen Wert.

 -- Monadische Prozedur: state-push WERT
     Hängt den WERT vorne an den momentanen Zustand an, der eine Liste sein muss. Liefert den vorherigen Zustand als monadischen Wert.

 -- Monadische Prozedur: state-pop
     Entfernt einen Wert vorne vom momentanen Zustand und liefert ihn als monadischen Wert zurück. Dabei wird angenommen, dass es sich beim Zustand um eine Liste handelt.

 -- Scheme-Prozedur: run-with-state MWERT [ZUSTAND]
     Den monadischen Wert MWERT mit ZUSTAND als initialem Zustand laufen lassen. Dies liefert zwei Werte: den Ergebniswert und den Ergebniszustand.

Die zentrale Schnittstelle zur Store-Monade, wie sie vom Modul (guix store) angeboten wird, ist die Folgende:

 -- Scheme-Variable: %store-monad
     Die Store-Monade — ein anderer Name für %STATE-MONAD.

     Werte in der Store-Monade kapseln Zugriffe auf den Store. Sobald seine Wirkung gebraucht wird, muss ein Wert der Store-Monade »ausgewertet« werden, indem er an die Prozedur run-with-store übergeben wird (siehe unten).

 -- Scheme-Prozedur: run-with-store STORE MWERT [#:guile-for-build] [#:system (%current-system)]
     Den MWERT, einen monadischen Wert in der Store-Monade, in der offenen Verbindung STORE laufen lassen.

 -- Monadische Prozedur: text-file NAME TEXT [REFERENZEN]
     Als monadischen Wert den absoluten Dateinamen im Store für eine Datei liefern, deren Inhalt der der Zeichenkette TEXT ist. REFERENZEN ist dabei eine Liste von Store-Objekten, die die Ergebnis-Textdatei referenzieren wird; der Vorgabewert ist die leere Liste.

 -- Monadische Prozedur: binary-file NAME DATEN [REFERENZEN]
     Den absoluten Dateinamen im Store als monadischen Wert für eine Datei liefern, deren Inhalt der des Byte-Vektors DATEN ist. REFERENZEN ist dabei eine Liste von Store-Objekten, die die Ergebnis-Binärdatei referenzieren wird; der Vorgabewert ist die leere Liste.

 -- Monadische Prozedur: interned-file DATEI [NAME]
     [#:recursive? #t] [#:select? (const #t)] Liefert den Namen der DATEI,
     nachdem sie in den Store interniert wurde. Dabei wird der NAME als ihr Store-Name verwendet, oder, wenn kein NAME angegeben wurde, der Basisname der DATEI.

     Ist RECURSIVE? wahr, werden in der DATEI enthaltene Dateien rekursiv hinzugefügt; ist die DATEI eine flache Datei und RECURSIVE? ist wahr, wird ihr Inhalt in den Store eingelagert und ihre Berechtigungs-Bits übernommen.

     Steht RECURSIVE? auf wahr, wird (SELECT? DATEI STAT) für jeden Verzeichniseintrag aufgerufen, wobei DATEI der absolute Dateiname und STAT das Ergebnis von lstat ist, außer auf den Einträgen, wo SELECT? keinen wahren Wert liefert.

     Folgendes Beispiel fügt eine Datei unter zwei verschiedenen Namen in den Store ein:

          (run-with-store (open-connection)
            (mlet %store-monad ((a (interned-file "README"))
                                (b (interned-file "README" "LEGU-MIN")))
              (return (list a b))))

          => ("/gnu/store/rwm...-README" "/gnu/store/44i...-LEGU-MIN")

Das Modul (guix packages) exportiert die folgenden paketbezogenen monadischen Prozeduren:

 -- Monadische Prozedur: package-file PAKET [DATEI]
     [#:system (%current-system)] [#:target #f]  [#:output "out"] Liefert als
     monadischen Wert den absoluten Dateinamen der DATEI innerhalb des Ausgabeverzeichnisses OUTPUT des PAKETs. Wird keine DATEI angegeben, wird der Name des Ausgabeverzeichnisses OUTPUT für das PAKET zurückgeliefert. Ist TARGET wahr, wird sein Wert als das Zielsystem bezeichnendes Tripel zum Cross-Kompilieren benutzt.

 -- Monadische Prozedur: package->derivation PAKET [SYSTEM]
 -- Monadische Prozedur: package->cross-derivation PAKET
     ZIEL [SYSTEM] Monadische Version von package-derivation
     und package-cross-derivation (see Pakete definieren).

G-Ausdrücke
===========

Es gibt also »Ableitungen«, die eine Abfolge von Erstellungsaktionen repräsentieren, die durchgeführt werden müssen, um ein Objekt im Store zu erzeugen (see Ableitungen). Diese Erstellungsaktionen werden durchgeführt, nachdem der Daemon gebeten wurde, die Ableitungen tatsächlich zu erstellen; dann führt der Daemon sie in einer isolierten Umgebung (einem sogenannten Container) aus (see Aufruf des guix-daemon).

Wenig überraschend ist, dass wir diese Erstellungsaktionen gerne in Scheme schreiben würden. Wenn wir das tun, bekommen wir zwei verschiedene Schichten von Scheme-Code (Der Begriff Schicht, englisch Stratum, wurde in diesem Kontext von Manuel Serrano et al. in ihrer Arbeit an Hop geprägt. Oleg Kiselyov, der aufschlussreiche Essays und Code zu diesem Thema (http://okmij.org/ftp/meta-programming/#meta-scheme) geschrieben hat, nennt diese Art der Code-Generierung Staging, deutsch etwa Inszenierung bzw. Aufführung.): den »wirtsseitigen Code« (»host code«) — also Code, der Pakete definiert, mit dem Daemon kommuniziert etc. — und den »erstellungsseitigen Code« (»build code«) — also Code, der die Erstellungsaktionen auch wirklich umsetzt, indem Dateien erstellt werden, make aufgerufen wird etc.

Um eine Ableitung und ihre Erstellungsaktionen zu beschreiben, muss man normalerweise erstellungsseitigen Code im wirtsseitigen Code einbetten. Das bedeutet, man behandelt den erstellungsseitigen Code als Daten, was wegen der Homoikonizität von Scheme — dass Code genauso als Daten repräsentiert werden kann — sehr praktisch ist. Doch brauchen wir hier mehr als nur den normalen Quasimaskierungsmechanismus mit quasiquote in Scheme, wenn wir Erstellungsausdrücke konstruieren möchten.

Das Modul (guix gexp) implementiert G-Ausdrücke, eine Form von S-Ausdrücken, die zu Erstellungsausdrücken angepasst wurden. G-Ausdrücke (englisch »G-expressions«, kurz Gexps) setzen sich grundlegend aus drei syntaktischen Formen zusammen: gexp, ungexp und ungexp-splicing (alternativ einfach: #~, #$ und #$@), die jeweils mit quasiquote, unquote und unquote-splicing vergleichbar sind (see quasiquote (GNU Guile Reference Manual)). Es gibt aber auch erhebliche Unterschiede:

  * G-Ausdrücke sind dafür gedacht, in eine Datei geschrieben zu werden, wo sie von anderen Prozessen ausgeführt oder manipuliert werden können.

  * Wenn ein abstraktes Objekt wie ein Paket oder eine Ableitung innerhalb eines G-Ausdrücks demaskiert wird, ist das Ergebnis davon dasselbe, wie wenn dessen Ausgabedateiname genannt worden wäre.

  * G-Ausdrücke tragen Informationen über die Pakete oder Ableitungen mit sich, auf die sie sich beziehen, und diese Abhängigkeiten werden automatisch zu den sie benutzenden Erstellungsprozessen als Eingaben hinzugefügt.

Dieser Mechanismus ist nicht auf Pakete und Ableitung beschränkt: Es können Compiler definiert werden, die weitere abstrakte, hochsprachliche Objekte auf Ableitungen oder Dateien im Store »herunterbrechen«, womit diese Objekte dann auch in G-Ausdrücken eingefügt werden können. Zum Beispiel sind »dateiartige Objekte« ein nützlicher Typ solcher abstrakter Objekte. Mit ihnen können Dateien leicht in den Store eingefügt und von Ableitungen und Anderem referenziert werden (siehe unten local-file und plain-file).

Zur Veranschaulichung dieser Idee soll uns dieses Beispiel eines G-Ausdrucks dienen:

     (define build-exp
       #~(begin
           (mkdir #$output)
           (chdir #$output)
           (symlink (string-append #$coreutils "/bin/ls")
                    "list-files")))

Indem wir diesen G-Ausdruck an gexp->derivation übergeben, bekommen wir eine Ableitung, die ein Verzeichnis mit genau einer symbolischen Verknüpfung auf /gnu/store/...-coreutils-8.22/bin/ls erstellt:

     (gexp->derivation "das-ding" build-exp)

Wie man es erwarten würde, wird die Zeichenkette "/gnu/store/...-coreutils-8.22" anstelle der Referenzen auf das Paket COREUTILS im eigentlichen Erstellungscode eingefügt und COREUTILS automatisch zu einer Eingabe der Ableitung gemacht. Genauso wird auch #$output (was äquivalent zur Schreibweise (ungexp output) ist) ersetzt durch eine Zeichenkette mit dem Namen der Ausgabe der Ableitung.

Im Kontext der Cross-Kompilierung bietet es sich an, zwischen Referenzen auf die native Erstellung eines Pakets — also der, die auf dem Wirtssystem ausgeführt werden kann — und Referenzen auf Cross-Erstellungen eines Pakets zu unterscheiden. Hierfür spielt #+ dieselbe Rolle wie #$, steht aber für eine Referenz auf eine native Paketerstellung.

     (gexp->derivation "vi"
        #~(begin
            (mkdir #$output)
            (system* (string-append #+coreutils "/bin/ln")
                     "-s"
                     (string-append #$emacs "/bin/emacs")
                     (string-append #$output "/bin/vi")))
        #:target "mips64el-linux-gnu")

Im obigen Beispiel wird die native Erstellung der COREUTILS benutzt, damit ln tatsächlich auf dem Wirtssystem ausgeführt werden kann, aber danach die cross-kompilierte Erstellung von EMACS referenziert.

Eine weitere Funktionalität von G-Ausdrücken stellen importierte Module dar. Manchmal will man bestimmte Guile-Module von der »wirtsseitigen Umgebung« im G-Ausdruck benutzen können, deswegen sollten diese Module in die »erstellungsseitige Umgebung« importiert werden. Die with-imported-modules-Form macht das möglich:

     (let ((build (with-imported-modules '((guix build utils))
                    #~(begin
                        (use-modules (guix build utils))
                        (mkdir-p (string-append #$output "/bin"))))))
       (gexp->derivation "leeres-Verzeichnis"
                         #~(begin
                             #$build
                             (display "Erfolg!\n")
                             #t)))

In diesem Beispiel wird das Modul (guix build utils) automatisch in die isolierte Erstellungsumgebung unseres G-Ausdrucks geholt, so dass (use-modules (guix build utils)) wie erwartet funktioniert.

Normalerweise möchten Sie, dass der Abschluss eines Moduls importiert wird — also das Modul und alle Module, von denen es abhängt — statt nur das Modul selbst. Ansonsten scheitern Versuche, das Modul zu benutzen, weil seine Modulabhängigkeiten fehlen. Die Prozedur source-module-closure berechnet den Abschluss eines Moduls, indem es den Kopf seiner Quelldatei analysiert, deswegen schafft die Prozedur hier Abhilfe:

     (use-modules (guix modules))   ;»source-module-closure« verfügbar machen

     (with-imported-modules (source-module-closure
                              '((guix build utils)
                                (gnu build vm)))
       (gexp->derivation "etwas-mit-vms"
                         #~(begin
                             (use-modules (guix build utils)
                                          (gnu build vm))
                             ...)))

Auf die gleiche Art können Sie auch vorgehen, wenn Sie nicht bloß reine Scheme-Module importieren möchten, sondern auch »Erweiterungen« wie Guile-Anbindungen von C-Bibliotheken oder andere »vollumfängliche« Pakete. Sagen wir, Sie bräuchten das Paket guile-json auf der Erstellungsseite, dann könnten Sie es hiermit bekommen:

     (use-modules (gnu packages guile))  ;für »guile-json«

     (with-extensions (list guile-json)
       (gexp->derivation "etwas-mit-json"
                         #~(begin
                             (use-modules (json))
                             ...)))

Die syntaktische Form, in der G-Ausdrücke konstruiert werden, ist im Folgenden zusammengefasst.

 -- Scheme-Syntax: #~AUSDRUCK
 -- Scheme-Syntax: (gexp AUSDRUCK)
     Liefert einen G-Ausdruck, der den AUSDRUCK enthält. Der AUSDRUCK kann eine oder mehrere der folgenden Formen enthalten:

     #$OBJEKT
     (ungexp OBJEKT)
          Eine Referenz auf das OBJEKT einführen. Das OBJEKT kann einen der unterstützten Typen haben, zum Beispiel ein Paket oder eine Ableitung, so dass die ungexp-Form durch deren Ausgabedateiname ersetzt wird — z.B. "/gnu/store/...-coreutils-8.22.

          Wenn das OBJEKT eine Liste ist, wird diese durchlaufen und alle unterstützten Objekte darin auf diese Weise ersetzt.

          Wenn das OBJEKT ein anderer G-Ausdruck ist, wird sein Inhalt eingefügt und seine Abhängigkeiten zu denen des äußeren G-Ausdrucks hinzugefügt.

          Wenn das OBJEKT eine andere Art von Objekt ist, wird es so wie es ist eingefügt.

     #$OBJEKT:AUSGABE
     (ungexp OBJEKT AUSGABE)
          Dies verhält sich wie die Form oben, bezieht sich aber ausdrücklich auf die angegebene AUSGABE des OBJEKTs — dies ist nützlich, wenn das OBJEKT mehrere Ausgaben generiert (see Pakete mit mehreren Ausgaben.).

     #+OBJEKT
     #+OBJEKT:AUSGABE
     (ungexp-native OBJEKT)
     (ungexp-native OBJEKT AUSGABE)
          Das Gleiche wie ungexp, jedoch wird im Kontext einer Cross-Kompilierung eine Referenz auf die native Erstellung des OBJEKTs eingefügt.

     #$output[:AUSGABE]
     (ungexp output [AUSGABE])
          Fügt eine Referenz auf die angegebene AUSGABE dieser Ableitung ein, oder auf die Hauptausgabe, wenn keine AUSGABE angegeben wurde.

          Dies ist nur bei G-Ausdrücken sinnvoll, die an gexp->derivation übergeben werden.

     #$@LISTE
     (ungexp-splicing LISTE)
          Das Gleiche wie oben, jedoch wird nur der Inhalt der LISTE in die äußere Liste eingespleißt.

     #+@LISTE
     (ungexp-native-splicing LISTE)
          Das Gleiche, aber referenziert werden native Erstellungen der Objekte in der LISTE.

     G-Ausdrücke, die mit gexp oder #~ erzeugt wurden, sind zur Laufzeit Objekte vom Typ gexp? (siehe unten).

 -- Scheme-Syntax: with-imported-modules MODULE RUMPF...
     Markiert die in RUMPF... definierten G-Ausdrücke, dass sie in ihrer Ausführungsumgebung die angegebenen MODULE brauchen.

     Jedes Objekt unter den MODULEn kann der Name eines Moduls wie (guix build utils) sein, oder es kann nacheinander ein Modulname, ein Pfeil und ein dateiartiges Objekt sein:

          `((guix build utils)
            (guix gcrypt)
            ((guix config) => ,(scheme-file "config.scm"
                                            #~(define-module ...))))

     Im Beispiel oben werden die ersten beiden Module vom Suchpfad genommen und das letzte aus dem angegebenen dateiartigen Objekt erzeugt.

     Diese Form hat einen lexikalischen Sichtbarkeitsbereich: Sie wirkt sich auf die direkt in RUMPF... definierten G-Ausdrücke aus, aber nicht auf jene, die, sagen wir, in aus RUMPF... heraus aufgerufenen Prozeduren definiert wurden.

 -- Scheme-Syntax: with-extensions ERWEITERUNGEN RUMPF...
     Markiert die in RUMPF... definierten G-Ausdrücke, dass sie ERWEITERUNGEN in ihrer Erstellungs- und Ausführungsumgebung benötigen. ERWEITERUNGEN sind typischerweise eine Liste von Paketobjekten wie zum Beispiel die im Modul (gnu packages guile) definierten.

     Konkret werden die unter den ERWEITERUNGEN aufgeführten Pakete zum Ladepfad hinzugefügt, während die in RUMPF... aufgeführten importierten Module kompiliert werden und sie werden auch zum Ladepfad des von RUMPF... gelieferten G-Ausdrucks hinzugefügt.

 -- Scheme-Prozedur: gexp? OBJEKT
     Liefert #t, wenn das OBJEKT ein G-Ausdruck ist.

G-Ausdrücke sind dazu gedacht, auf die Platte geschrieben zu werden, entweder als Code, der eine Ableitung erstellt, oder als einfache Dateien im Store. Die monadischen Prozeduren unten ermöglichen Ihnen das (see Die Store-Monade, wenn Sie mehr Informationen über Monaden suchen).

 -- Monadische Prozedur: gexp->derivation NAME AUSDRUCK
     [#:system (%current-system)] [#:target #f] [#:graft? #t]  [#:hash #f]
     [#:hash-algo #f]  [#:recursive? #f] [#:env-vars '()] [#:modules '()] [#:module-path %LOAD-PATH]  [#:effective-version "2.2"] [#:references-graphs #f] [#:allowed-references #f] [#:disallowed-references #f]  [#:leaked-env-vars #f]  [#:script-name (string-append NAME "-builder")]  [#:deprecation-warnings #f] [#:local-build? #f] [#:substitutable? #t]  [#:properties '()] [#:guile-for-build #f] Liefert eine Ableitung unter dem NAMEn, die jeden AUSDRUCK (ein G-Ausdruck) mit GUILE-FOR-BUILD (eine Ableitung) für das SYSTEM erstellt; der AUSDRUCK wird dabei in einer Datei namens SCRIPT-NAME gespeichert. Wenn »TARGET« wahr ist, wird es beim Cross-Kompilieren als Zieltripel für mit AUSDRUCK bezeichnete Pakete benutzt.

     MODULES gilt als veraltet; stattdessen sollte with-imported-modules benutzt werden. Die Bedeutung ist, dass die MODULE im Ausführungskontext des AUSDRUCKs verfügbar gemacht werden; MODULES ist dabei eine Liste von Namen von Guile-Modulen, die im Modulpfad MODULE-PATH gesucht werden, um sie in den Store zu kopieren, zu kompilieren und im Ladepfad während der Ausführung des AUSDRUCKs verfügbar zu machen — z.B. ((guix build utils) (guix build gnu-build-system)).

     EFFECTIVE-VERSION bestimmt, unter welcher Zeichenkette die Erweiterungen des AUSDRUCKs zum Suchpfad hinzugefügt werden (siehe with-extensions) — z.B. "2.2".

     GRAFT? bestimmt, ob vom AUSDRUCK benannte Pakete veredelt werden sollen, falls Veredelungen zur Verfügung stehen.

     Ist REFERENCES-GRAPHS wahr, muss es eine Liste von Tupeln in einer der folgenden Formen sein:

          (DATEINAME PAKET)
          (DATEINAME PAKET AUSGABE)
          (DATEINAME ABLEITUNG)
          (DATEINAME ABLEITUNG AUSGABE)
          (DATEINAME STORE-OBJEKT)

     Bei jedem Element von REFERENCES-GRAPHS wird das rechts Stehende automatisch zu einer Eingabe des Erstellungsprozesses vom AUSDRUCK gemacht. In der Erstellungsumgebung enthält das, was mit DATEINAME bezeichnet wird, den Referenzgraphen des entsprechenden Objekts in einem einfachen Textformat.

     ALLOWED-REFERENCES muss entweder #f oder eine Liste von Ausgabenamen und Paketen sein. Eine solche Liste benennt Store-Objekte, die das Ergebnis referenzieren darf. Jede Referenz auf ein nicht dort aufgeführtes Store-Objekt löst einen Erstellungsfehler aus. Genauso funktioniert DISALLOWED-REFERENCES, was eine Liste von Objekten sein kann, die von den Ausgaben nicht referenziert werden dürfen.

     DEPRECATION-WARNINGS bestimmt, ob beim Kompilieren von Modulen Warnungen angezeigt werden sollen, wenn auf als veraltet markierten Code zugegriffen wird (»deprecation warnings«). DEPRECATION-WARNINGS kann #f, #t oder 'detailed (detailliert) sein.

     Die anderen Argumente verhalten sich wie bei derivation (see Ableitungen).

Die im Folgenden erklärten Prozeduren local-file, plain-file, computed-file, program-file und scheme-file liefern dateiartige Objekte. Das bedeutet, dass diese Objekte, wenn sie in einem G-Ausdruck demaskiert werden, zu einer Datei im Store führen. Betrachten Sie zum Beispiel diesen G-Ausdruck:

     #~(system* #$(file-append glibc "/sbin/nscd") "-f"
                #$(local-file "/tmp/my-nscd.conf"))

Der Effekt hiervon ist, dass /tmp/my-nscd.conf »interniert« wird, indem es in den Store kopiert wird. Sobald er umgeschrieben wurde, zum Beispiel über gexp->derivation, referenziert der G-Ausdruck diese Kopie im /gnu/store. Die Datei in /tmp zu bearbeiten oder zu löschen, hat dann keinen Effekt mehr darauf, was der G-Ausdruck tut. plain-file kann in ähnlicher Weise benutzt werden, es unterscheidet sich aber darin, dass dort der Prozedur der Inhalt der Datei als eine Zeichenkette übergeben wird.

 -- Scheme-Prozedur: local-file DATEI [NAME]
     [#:recursive? #f] [#:select? (const #t)] Liefert ein Objekt, dass die lokale
     Datei DATEI repräsentiert und sie zum Store hinzufügen lässt; dieses Objekt kann in einem G-Ausdruck benutzt werden. Wurde für die DATEI ein relativer Dateiname angegeben, wird sie relativ zur Quelldatei gesucht, in der diese Form steht. Die DATEI wird unter dem angegebenen NAMEn im Store abgelegt — als Vorgabe wird dabei der Basisname der DATEI genommen.

     Ist RECURSIVE? wahr, werden in der DATEI enthaltene Dateien rekursiv hinzugefügt; ist die DATEI eine flache Datei und RECURSIVE? ist wahr, wird ihr Inhalt in den Store eingelagert und ihre Berechtigungs-Bits übernommen.

     Steht RECURSIVE? auf wahr, wird (SELECT? DATEI STAT) für jeden Verzeichniseintrag aufgerufen, wobei DATEI der absolute Dateiname und STAT das Ergebnis von lstat ist, außer auf den Einträgen, wo SELECT? keinen wahren Wert liefert.

     Dies ist das deklarative Gegenstück zur monadischen Prozedur interned-file (see interned-file).

 -- Scheme-Prozedur: plain-file NAME INHALT
     Liefert ein Objekt, das eine Textdatei mit dem angegebenen NAMEn repräsentiert, die den angegebenen INHALT hat (eine Zeichenkette oder ein Bytevektor), welche zum Store hinzugefügt werden soll.

     Dies ist das deklarative Gegenstück zu text-file.

 -- Scheme-Prozedur: computed-file NAME G-AUSDRUCK
     [#:options '(#:local-build? #t)] Liefert ein Objekt, das das Store-Objekt
     mit dem NAMEn repräsentiert, eine Datei oder ein Verzeichnis, das vom G-AUSDRUCK berechnet wurde. OPTIONS ist eine Liste zusätzlicher Argumente, die an gexp->derivation übergeben werden.

     Dies ist das deklarative Gegenstück zu gexp->derivation.

 -- Monadische Prozedur: gexp->script NAME AUSDRUCK
     [#:guile (default-guile)] [#:module-path %load-path] Liefert ein
     ausführbares Skript namens NAME, das den AUSDRUCK mit dem angegebenen GUILE ausführt, wobei vom AUSDRUCK importierte Module in seinem Suchpfad stehen. Die Module des AUSDRUCKs werden dazu im Modulpfad MODULE-PATH gesucht.

     Folgendes Beispiel erstellt ein Skript, das einfach nur den Befehl ls ausführt:

          (use-modules (guix gexp) (gnu packages base))

          (gexp->script "list-files"
                        #~(execl #$(file-append coreutils "/bin/ls")
                                 "ls"))

     Lässt man es durch den Store »laufen« (siehe run-with-store), erhalten wir eine Ableitung, die eine ausführbare Datei /gnu/store/...-list-files generiert, ungefähr so:

          #!/gnu/store/...-guile-2.0.11/bin/guile -ds
          !#
          (execl "/gnu/store/...-coreutils-8.22"/bin/ls" "ls")

 -- Scheme-Prozedur: program-file NAME G-AUSDRUCK
     [#:guile #f] [#:module-path %load-path] Liefert ein Objekt, das eine
     ausführbare Store-Datei NAME repräsentiert, die den G-AUSDRUCK ausführt. GUILE ist das zu verwendende Guile-Paket, mit dem das Skript ausgeführt werden kann. Importierte Module des G-AUSDRUCKs werden im Modulpfad MODULE-PATH gesucht.

     Dies ist das deklarative Gegenstück zu gexp->script.

 -- Monadische Prozedur: gexp->file NAME G-AUSDRUCK
     [#:set-load-path? #t] [#:module-path %load-path]  [#:splice? #f]  [#:guile
     (default-guile)] Liefert eine Ableitung, die eine Datei NAME erstellen wird, deren Inhalt der G-AUSDRUCK ist. Ist SPLICE? wahr, dann wird G-AUSDRUCK stattdessen als eine Liste von mehreren G-Ausdrücken behandelt, die alle in die resultierende Datei gespleißt werden.

     Ist SET-LOAD-PATH? wahr, wird in die resultierende Datei Code hinzugefügt, der den Ladepfad %load-path und den Ladepfad für kompilierte Dateien %load-compiled-path festlegt, die für die importierten Module des G-AUSDRUCKs nötig sind. Die Module des G-AUSDRUCKs werden im Modulpfad MODULE-PATH gesucht.

     Die resultierende Datei referenziert alle Abhängigkeiten des G-AUSDRUCKs oder eine Teilmenge davon.

 -- Scheme-Prozedur: scheme-file NAME G-AUSDRUCK [#:splice? #f]
     Liefert ein Objekt, das die Scheme-Datei NAME mit dem G-AUSDRUCK als Inhalt repräsentiert.

     Dies ist das deklarative Gegenstück zu gexp->file.

 -- Monadische Prozedur: text-file* NAME TEXT ...
     Liefert eine Ableitung als monadischen Wert, welche eine Textdatei erstellt, in der der gesamte TEXT enthalten ist. TEXT kann eine Folge nicht nur von Zeichenketten, sondern auch Objekten beliebigen Typs sein, die in einem G-Ausdruck benutzt werden können, also Paketen, Ableitungen, Objekte lokaler Dateien und so weiter. Die resultierende Store-Datei referenziert alle davon.

     Diese Variante sollte gegenüber text-file bevorzugt verwendet werden, wann immer die zu erstellende Datei Objekte im Store referenzieren wird. Typischerweise ist das der Fall, wenn eine Konfigurationsdatei erstellt wird, die Namen von Store-Dateien enthält, so wie hier:

          (define (profile.sh)
            ;; Liefert den Namen eines Shell-Skripts im Store,
            ;; welcher die Umgebungsvariable »PATH« initialisiert.
            (text-file* "profile.sh"
                        "export PATH=" coreutils "/bin:"
                        grep "/bin:" sed "/bin\n"))

     In diesem Beispiel wird die resultierende Datei /gnu/store/...-profile.sh sowohl COREUTILS, GREP als auch SED referenzieren, so dass der Müllsammler diese nicht löscht, während die resultierende Datei noch lebendig ist.

 -- Scheme-Prozedur: mixed-text-file NAME TEXT ...
     Liefert ein Objekt, was die Store-Datei NAME repräsentiert, die TEXT enthält. TEXT ist dabei eine Folge von Zeichenketten und dateiartigen Objekten wie zum Beispiel:

          (mixed-text-file "profile"
                           "export PATH=" coreutils "/bin:" grep "/bin")

     Dies ist das deklarative Gegenstück zu text-file*.

 -- Scheme-Prozedur: file-union NAME DATEIEN
     Liefert ein <computed-file>, das ein Verzeichnis mit allen DATEIEN enthält. Jedes Objekt in DATEIEN muss eine zweielementige Liste sein, deren erstes Element der im neuen Verzeichnis zu benutzende Dateiname ist und deren zweites Element ein G-Ausdruck ist, der die Zieldatei benennt. Hier ist ein Beispiel:

          (file-union "etc"
                      `(("hosts" ,(plain-file "hosts"
                                              "127.0.0.1 localhost"))
                        ("bashrc" ,(plain-file "bashrc"
                                               "alias ls='ls --color=auto'"))))

     Dies liefert ein Verzeichnis etc, das zwei Dateien enthält.

 -- Scheme-Prozedur: directory-union NAME DINGE
     Liefert ein Verzeichnis, was die Vereinigung (englisch »Union«) der DINGE darstellt, wobei DINGE eine Liste dateiartiger Objekte sein muss, die Verzeichnisse bezeichnen. Zum Beispiel:

          (directory-union "guile+emacs" (list guile emacs))

     Das liefert ein Verzeichnis, welches die Vereinigung der Pakete guile und emacs ist.

 -- Scheme-Prozedur: file-append OBJEKT SUFFIX ...
     Liefert ein dateiartiges Objekt, das zur Aneinanderreihung von OBJEKT und SUFFIX umgeschrieben wird, wobei das OBJEKT ein herunterbrechbares Objekt und jedes SUFFIX eine Zeichenkette sein muss.

     Betrachten Sie zum Beispiel diesen G-Ausdruck:

          (gexp->script "uname-ausfuehren"
                        #~(system* #$(file-append coreutils
                                                  "/bin/uname")))

     Denselben Effekt könnte man erreichen mit:

          (gexp->script "uname-ausfuehren"
                        #~(system* (string-append #$coreutils
                                                  "/bin/uname")))

     Es gibt jedoch einen Unterschied, nämlich enthält das resultierende Skript bei file-append tatsächlich den absoluten Dateinamen als Zeichenkette, während im anderen Fall das resultierende Skript einen Ausdruck (string-append ...) enthält, der den Dateinamen erst zur Laufzeit zusammensetzt.

Natürlich gibt es zusätzlich zu in »wirtsseitigem« Code eingebetteten G-Ausdrücken auch Module mit »erstellungsseitig« nutzbaren Werkzeugen. Um klarzustellen, dass sie dafür gedacht sind, in der Erstellungsschicht benutzt zu werden, bleiben diese Module im Namensraum (guix build ...).

Intern werden hochsprachliche, abstrakte Objekte mit ihrem Compiler entweder zu Ableitungen oder zu Store-Objekten heruntergebrochen. Wird zum Beispiel ein Paket heruntergebrochen, bekommt man eine Ableitung, während ein plain-file zu einem Store-Objekt heruntergebrochen wird. Das wird mit der monadischen Prozedur lower-object bewerkstelligt.

 -- Monadische Prozedur: lower-object OBJEKT [SYSTEM]
     [#:target #f] Liefert die Ableitung oder das Store-Objekt, das dem
     OBJEKT für SYSTEM als Wert in der Store-Monade %STORE-MONAD entspricht, cross-kompiliert für das Zieltripel TARGET, wenn TARGET wahr ist. Das OBJEKT muss ein Objekt sein, für das es einen mit ihm assoziierten G-Ausdruck-Compiler gibt, wie zum Beispiel ein <package>.

guix repl aufrufen
==================

The guix repl command spawns a Guile read-eval-print loop (REPL) for interactive programming (see Using Guile Interactively (GNU Guile Reference Manual)).  Compared to just launching the guile command, guix repl guarantees that all the Guix modules and all its dependencies are available in the search path.  You can use it this way:

     $ guix repl
     scheme@(guile-user)> ,use (gnu packages base)
     scheme@(guile-user)> coreutils
     $1 = #<package coreutils@8.29 gnu/packages/base.scm:327 3e28300>

In addition, guix repl implements a simple machine-readable REPL protocol for use by (guix inferior), a facility to interact with inferiors, separate processes running a potentially different revision of Guix.

Folgende OPTIONEN gibt es:

--type=TYPE
-t TYPE
     Start a REPL of the given TYPE, which can be one of the following:

     guile
          This is default, and it spawns a standard full-featured Guile REPL.

     machine
          Spawn a REPL that uses the machine-readable protocol.  This is the protocol that the (guix inferior) module speaks.

--listen=ENDPUNKT
     By default, guix repl reads from standard input and writes to standard output.  When this option is passed, it will instead listen for connections on ENDPOINT.  Here are examples of valid options:

     --listen=tcp:37146
          Accept connections on localhost on port 37146.

     --listen=unix:/tmp/socket
          Accept connections on the Unix-domain socket /tmp/socket.

Zubehör
*******

Dieser Abschnitt beschreibt die Befehlszeilenwerkzeuge von Guix. Manche davon richten sich hauptsächlich an Entwickler und solche Nutzer, die neue Paketdefinitionen schreiben, andere sind auch für ein breiteres Publikum nützlich. Sie ergänzen die Scheme-Programmierschnittstelle um bequeme Befehle.

Aufruf von guix build
=====================

Der Befehl guix build lässt Pakete oder Ableitungen samt ihrer Abhängigkeiten erstellen und gibt die resultierenden Pfade im Store aus. Beachten Sie, dass das Nutzerprofil dadurch nicht modifiziert wird — eine solche Installation bewirkt der Befehl guix package (see Aufruf von guix package). guix build wird also hauptsächlich von Entwicklern der Distribution benutzt.

Die allgemeine Syntax lautet:

     guix build OPTIONEN PAKET-ODER-ABLEITUNG...

Zum Beispiel wird mit folgendem Befehl die neueste Version von Emacs und von Guile erstellt, das zugehörige Erstellungsprotokoll angezeigt und letztendlich werden die resultierenden Verzeichnisse ausgegeben:

     guix build emacs guile

Folgender Befehl erstellt alle Pakete, die zur Verfügung stehen:

     guix build --quiet --keep-going \
       `guix package -A | cut -f1,2 --output-delimiter=@`

Als PAKET-ODER-ABLEITUNG muss entweder der Name eines in der Software-Distribution zu findenden Pakets, wie etwa coreutils oder coreutils@8.20, oder eine Ableitung wie /gnu/store/...-coreutils-8.19.drv sein. Im ersten Fall wird nach einem Paket mit entsprechendem Namen (und optional der entsprechenden Version) in den Modulen der GNU-Distribution gesucht (see Paketmodule).

Alternativ kann die Befehlszeilenoption --expression benutzt werden, um einen Scheme-Ausdruck anzugeben, der zu einem Paket ausgewertet wird; dies ist nützlich, wenn zwischen mehreren gleichnamigen Paketen oder Paket-Varianten unterschieden werden muss.

Null oder mehr OPTIONEN können angegeben werden. Zur Verfügung stehen die in den folgenden Unterabschnitten beschriebenen Befehlszeilenoptionen.

Gemeinsame Erstellungsoptionen
------------------------------

Einige dieser Befehlszeilenoptionen zur Steuerung des Erstellungsprozess haben guix build und andere Befehle, mit denen Erstellungen ausgelöst werden können, wie guix package oder guix archive, gemeinsam. Das sind folgende:

--load-path=VERZEICHNIS
-L VERZEICHNIS
     Das VERZEICHNIS vorne an den Suchpfad für Paketmodule anfügen (see Paketmodule).

     Damit können Nutzer dafür sorgen, dass ihre eigenen selbstdefinierten Pakete für die Befehlszeilenwerkzeuge sichtbar sind.

--keep-failed
-K
     Den Verzeichnisbaum, in dem fehlgeschlagene Erstellungen durchgeführt wurden, behalten. Wenn also eine Erstellung fehlschlägt, bleibt ihr Erstellungsbaum in /tmp erhalten. Der Name dieses Unterverzeichnisses wird am Ende dem Erstellungsprotokolls ausgegeben. Dies hilft bei der Suche nach Fehlern in Erstellungen. Der Abschnitt see Fehlschläge beim Erstellen untersuchen zeigt Ihnen Hinweise und Tricks, wie Erstellungsfehler untersucht werden können.

     Diese Option hat keine Auswirkungen, wenn eine Verbindung zu einem entfernten Daemon über eine guix://-URI verwendet wurde (see the GUIX_DAEMON_SOCKET variable).

--keep-going
-k
     Weitermachen, auch wenn ein Teil der Erstellungen fehlschlägt. Das bedeutet, dass der Befehl erst terminiert, wenn alle Erstellungen erfolgreich oder mit Fehler durchgeführt wurden.

     Das normale Verhalten ist, abzubrechen, sobald eine der angegebenen Ableitungen fehlschlägt.

--dry-run
-n
     Die Ableitungen nicht erstellen.

--fallback
     Wenn das Substituieren vorerstellter Binärdateien fehlschlägt, diese als »Fallback« lokal selbst erstellen (see Fehler bei der Substitution).

--substitute-urls=URLS
     Die URLS als durch Leerraumzeichen getrennte Liste von Quell-URLs für Substitute anstelle der vorgegebenen URL-Liste für den guix-daemon verwenden (see guix-daemon URLs).

     Das heißt, die Substitute dürfen von den URLS heruntergeladen werden, sofern sie mit einem durch den Systemadministrator autorisierten Schlüssel signiert worden sind (see Substitute).

     Wenn als URLS eine leere Zeichenkette angegeben wurde, verhält es sich, als wären Substitute abgeschaltet.

--no-substitutes
     Benutze keine Substitute für Erstellungsergebnisse. Das heißt, dass alle Objekte lokal erstellt werden müssen, und kein Herunterladen von vorab erstellten Binärdateien erlaubt ist (see Substitute).

--no-grafts
     Pakete nicht »veredeln« (engl. »graft«). Praktisch heißt das, dass als Veredelungen verfügbare Paketaktualisierungen nicht angewandt werden. Der Abschnitt see Sicherheitsaktualisierungen hat weitere Informationen zu Veredelungen.

--rounds=N
     Jede Ableitung N-mal nacheinander erstellen und einen Fehler melden, wenn die aufeinanderfolgenden Erstellungsergebnisse nicht Bit für Bit identisch sind.

     Das ist eine nützliche Methode, um nicht-deterministische Erstellungsprozesse zu erkennen. Nicht-deterministische Erstellungsprozesse sind ein Problem, weil Nutzer dadurch praktisch nicht verifizieren können, ob von Drittanbietern bereitgestellte Binärdateien echt sind. Der Abschnitt see Aufruf von guix challenge erklärt dies genauer.

     Beachten Sie, dass die sich unterscheidenden Erstellungsergebnisse nicht erhalten bleiben, so dass Sie eventuelle Fehler manuell untersuchen müssen, z.B. indem Sie eines oder mehrere der Erstellungsergebnisse guix archive --export auslagern (see Aufruf von guix archive), dann neu erstellen und letztlich die beiden Erstellungsergebnisse vergleichen.

--no-build-hook
     Nicht versuchen, Erstellungen über den »Build-Hook« des Daemons auszulagern (see Auslagern des Daemons einrichten). Somit wird lokal erstellt, statt Erstellungen auf entfernte Maschinen auszulagern.

--max-silent-time=SEKUNDEN
     Wenn der Erstellungs- oder Substitutionsprozess länger als SEKUNDEN-lang keine Ausgabe erzeugt, wird er abgebrochen und ein Fehler beim Erstellen gemeldet.

     Standardmäßig wird die Einstellung für den Daemon benutzt (see --max-silent-time).

--timeout=SEKUNDEN
     Entsprechend wird hier der Erstellungs- oder Substitutionsprozess abgebrochen und als Fehlschlag gemeldet, wenn er mehr als SEKUNDEN-lang dauert.

     Standardmäßig wird die Einstellung für den Daemon benutzt (see --timeout).

-v LEVEL
--verbosity=STUFE
     Use the given verbosity LEVEL, an integer.  Choosing 0 means that no output is produced, 1 is for quiet output, and 2 shows all the build log output on standard error.

--cores=N
-c N
     Die Nutzung von bis zu N Prozessorkernen für die Erstellungen gestatten. Der besondere Wert 0 bedeutet, dass so viele wie möglich benutzt werden.

--max-jobs=N
-M N
     Höchstens N gleichzeitige Erstellungsaufträge erlauben. Im Abschnitt see --max-jobs, finden Sie Details zu dieser Option und der äquivalenten Option des guix-daemon.

--debug=LEVEL
     Produce debugging output coming from the build daemon.  LEVEL must be an integer between 0 and 5; higher means more verbose output.  Setting a level of 4 or more may be helpful when debugging setup issues with the build daemon.

Intern ist guix build im Kern eine Schnittstelle zur Prozedur package-derivation aus dem Modul (guix packages) und zu der Prozedur build-derivations des Moduls (guix derivations).

Neben auf der Befehlszeile übergebenen Optionen beachten guix build und andere guix-Befehle, die Erstellungen durchführen lassen, die Umgebungsvariable GUIX_BUILD_OPTIONS.

 -- Umgebungsvariable: GUIX_BUILD_OPTIONS
     Nutzer können diese Variable auf eine Liste von Befehlszeilenoptionen definieren, die automatisch von guix build und anderen guix-Befehlen, die Erstellungen durchführen lassen, benutzt wird, wie in folgendem Beispiel:

          $ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar"

     Diese Befehlszeilenoptionen werden unabhängig von den auf der Befehlszeile übergebenen Befehlszeilenoptionen grammatikalisch analysiert und das Ergebnis an die bereits analysierten auf der Befehlszeile übergebenen Befehlszeilenoptionen angehängt.

Paketumwandlungsoptionen
------------------------

Eine weitere Gruppe von Befehlszeilenoptionen, die guix build und auch guix package unterstützen, sind Paketumwandlungsoptionen. Diese Optionen ermöglichen es, Paketvarianten zu definieren — zum Beispiel können Pakete aus einem anderen Quellcode als normalerweise erstellt werden. Damit ist es leicht, angepasste Pakete schnell zu erstellen, ohne die vollständigen Definitionen von Paketvarianten einzutippen (see Pakete definieren).

--with-source=QUELLE
--with-source=PAKET=QUELLE
--with-source=PAKET@VERSION=QUELLE
     Den Paketquellcode für das PAKET von der angegebenen QUELLE holen und die VERSION als seine Versionsnummer verwenden. Die QUELLE muss ein Dateiname oder eine URL sein wie bei guix download (see Aufruf von guix download).

     Wird kein PAKET angegeben, wird als Paketname derjenige auf der Befehlszeile angegebene Paketname angenommen, der zur Basis am Ende der QUELLE passt — wenn z.B. als QUELLE die Datei /src/guile-2.0.10.tar.gz angegeben wurde, entspricht das dem guile-Paket.

     Ebenso wird, wenn keine VERSION angegeben wurde, die Version als Zeichenkette aus der QUELLE abgeleitet; im vorherigen Beispiel wäre sie 2.0.10.

     Mit dieser Option können Nutzer versuchen, eine andere Version ihres Pakets auszuprobieren, als die in der Distribution enthaltene Version. Folgendes Beispiel lädt ed-1.7.tar.gz von einem GNU-Spiegelserver herunter und benutzt es als Quelle für das ed-Paket:

          guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz

     Für Entwickler wird es einem durch --with-source leicht gemacht, »Release Candidates«, also Vorabversionen, zu testen:

          guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz

     ... oder ein Checkout eines versionskontrollierten Repositorys in einer isolierten Umgebung zu erstellen:

          $ git clone git://git.sv.gnu.org/guix.git
          $ guix build guix --with-source=guix@1.0=./guix

--with-input=PAKET=ERSATZ
     Abhängigkeiten vom PAKET durch eine Abhängigkeit vom ERSATZ-Paket ersetzen. Als PAKET muss ein Paketname angegeben werden und als ERSATZ eine Paketspezifikation wie guile oder guile@1.8.

     Mit folgendem Befehl wird zum Beispiel Guix erstellt, aber statt der aktuellen stabilen Guile-Version hängt es von der alten Guile-Version guile@2.0 ab:

          guix build --with-input=guile=guile@2.0 guix

     Die Ersetzung ist rekursiv und umfassend. In diesem Beispiel würde nicht nur guix, sondern auch seine Abhängigkeit guile-json (was auch von guile abhängt) für guile@2.0 neu erstellt.

     Implementiert wird das alles mit der Scheme-Prozedur package-input-rewriting (see package-input-rewriting).

--with-graft=PAKET=ERSATZ
     Dies verhält sich ähnlich wie mit --with-input, aber mit dem wichtigen Unterschied, dass nicht die gesamte Abhängigkeitskette neu erstellt wird, sondern das ERSATZ-Paket erstellt und die ursprünglichen Binärdateien, die auf das PAKET verwiesen haben, damit veredelt werden. Im Abschnitt see Sicherheitsaktualisierungen finden Sie weitere Informationen über Veredelungen.

     Zum Beispiel veredelt folgender Befehl Wget und alle Abhängigkeiten davon mit der Version 3.5.4 von GnuTLS, indem Verweise auf die ursprünglich verwendete GnuTLS-Version ersetzt werden:

          guix build --with-graft=gnutls=gnutls@3.5.4 wget

     Das hat den Vorteil, dass es viel schneller geht, als alles neu zu erstellen. Die Sache hat aber einen Haken: Veredelung funktioniert nur, wenn das PAKET und sein ERSATZ miteinander streng kompatibel sind — zum Beispiel muss, wenn diese eine Programmbibliothek zur Verfügung stellen, deren Binärschnittstelle (»Application Binary Interface«, kurz ABI) kompatibel sein. Wenn das ERSATZ-Paket auf irgendeine Art inkompatibel mit dem PAKET ist, könnte das Ergebnispaket unbrauchbar sein. Vorsicht ist also geboten!

--with-branch=PACKAGE=BRANCH
     Build PACKAGE from the latest commit of BRANCH.  The source field of PACKAGE must be an origin with the git-fetch method (see »origin«-Referenz) or a git-checkout object; the repository URL is taken from that source.  Git sub-modules of the repository are fetched, recursively.

     For instance, the following command builds guile-sqlite3 from the latest commit of its master branch, and then builds guix (which depends on it) and cuirass (which depends on guix) against this specific guile-sqlite3 build:

          guix build --with-branch=guile-sqlite3=master cuirass

     Obviously, since it uses the latest commit of the given branch, the result of such a command varies over time.  Nevertheless it is a convenient way to rebuild entire software stacks against the latest commit of one or more packages.  This is particularly useful in the context of continuous integration (CI).

     Checkouts are kept in a cache under ~/.cache/guix/checkouts to speed up consecutive accesses to the same repository.  You may want to clean it up once in a while to save disk space.

--with-commit=PACKAGE=COMMIT
     This is similar to --with-branch, except that it builds from COMMIT rather than the tip of a branch.  COMMIT must be a valid Git commit SHA1 identifier.

Zusätzliche Erstellungsoptionen
-------------------------------

Die unten aufgeführten Befehlszeilenoptionen funktionieren nur mit guix build.

--quiet
-q
     Build quietly, without displaying the build log; this is equivalent to --verbosity=0.  Upon completion, the build log is kept in /var (or similar) and can always be retrieved using the --log-file option.

--file=DATEI
-f DATEI
     Das Paket, die Ableitung oder das dateiähnliche Objekt erstellen, zu dem der Code in der DATEI ausgewertet wird (see file-like objects).

     Zum Beispiel könnte in der DATEI so eine Paketdefinition stehen (see Pakete definieren):

               [file package-hello.scm not included]

--expression=AUSDRUCK
-e AUSDRUCK
     Build the package or derivation EXPR evaluates to.

     For example, EXPR may be (@ (gnu packages guile)  guile-1.8), which unambiguously designates this specific variant of version 1.8 of Guile.

     Alternatively, EXPR may be a G-expression, in which case it is used as a build program passed to gexp->derivation (see G-Ausdrücke).

     Lastly, EXPR may refer to a zero-argument monadic procedure (see Die Store-Monade).  The procedure must return a derivation as a monadic value, which is then passed through run-with-store.

--source
-S
     Build the source derivations of the packages, rather than the packages themselves.

     For instance, guix build -S gcc returns something like /gnu/store/...-gcc-4.7.2.tar.bz2, which is the GCC source tarball.

     The returned source tarball is the result of applying any patches and code snippets specified in the package origin (see Pakete definieren).

--sources
     Fetch and return the source of PACKAGE-OR-DERIVATION and all their dependencies, recursively.  This is a handy way to obtain a local copy of all the source code needed to build PACKAGES, allowing you to eventually build them even without network access.  It is an extension of the --source option and can accept one of the following optional argument values:

     package
          This value causes the --sources option to behave in the same way as the --source option.

     all
          Build the source derivations of all packages, including any source that might be listed as inputs.  This is the default value.

               $ guix build --sources tzdata
               The following derivations will be built:
                  /gnu/store/...-tzdata2015b.tar.gz.drv
                  /gnu/store/...-tzcode2015b.tar.gz.drv

     transitive
          Build the source derivations of all packages, as well of all transitive inputs to the packages.  This can be used e.g. to prefetch package source for later offline building.

               $ guix build --sources=transitive tzdata
               The following derivations will be built:
                  /gnu/store/...-tzcode2015b.tar.gz.drv
                  /gnu/store/...-findutils-4.4.2.tar.xz.drv
                  /gnu/store/...-grep-2.21.tar.xz.drv
                  /gnu/store/...-coreutils-8.23.tar.xz.drv
                  /gnu/store/...-make-4.1.tar.xz.drv
                  /gnu/store/...-bash-4.3.tar.xz.drv
               ...

--system=SYSTEM
-s SYSTEM
     Versuchen, für die angegebene Art von SYSTEM geeignete Binärdateien zu erstellen — z.B. i686-linux — statt für die Art von System, das die Erstellung durchführt.

          The --system flag is for native compilation and must not be confused with cross-compilation.  See --target below for information on cross-compilation.

     An example use of this is on Linux-based systems, which can emulate different personalities.  For instance, passing --system=i686-linux on an x86_64-linux system or --system=armhf-linux on an aarch64-linux system allows you to build packages in a complete 32-bit environment.

          Building for an armhf-linux system is unconditionally enabled on aarch64-linux machines, although certain aarch64 chipsets do not allow for this functionality, notably the ThunderX.

     Similarly, when transparent emulation with QEMU and binfmt_misc is enabled (see qemu-binfmt-service-type), you can build for any system for which a QEMU binfmt_misc handler is installed.

     Builds for a system other than that of the machine you are using can also be offloaded to a remote machine of the right architecture.  See Auslagern des Daemons einrichten, for more information on offloading.

--target=TRIPEL
     Lässt für das angegebene TRIPEL cross-erstellen, dieses muss ein gültiges GNU-Tripel wie z.B. "mips64el-linux-gnu" sein (see GNU configuration triplets (Autoconf)).

--check
     Rebuild PACKAGE-OR-DERIVATION, which are already available in the store, and raise an error if the build results are not bit-for-bit identical.

     This mechanism allows you to check whether previously installed substitutes are genuine (see Substitute), or whether the build result of a package is deterministic.  See Aufruf von guix challenge, for more background information and tools.

     Wenn dies zusammen mit --keep-failed benutzt wird, bleiben die sich unterscheidenden Ausgaben im Store unter dem Namen /gnu/store/...-check. Dadurch können Unterschiede zwischen den beiden Ergebnissen leicht erkannt werden.

--repair
     Attempt to repair the specified store items, if they are corrupt, by re-downloading or rebuilding them.

     This operation is not atomic and thus restricted to root.

--derivations
-d
     Return the derivation paths, not the output paths, of the given packages.

--root=FILE
-r FILE
     Make FILE a symlink to the result, and register it as a garbage collector root.

     Consequently, the results of this guix build invocation are protected from garbage collection until FILE is removed.  When that option is omitted, build results are eligible for garbage collection as soon as the build completes.  See Aufruf von guix gc, for more on GC roots.

--log-file
     Return the build log file names or URLs for the given PACKAGE-OR-DERIVATION, or raise an error if build logs are missing.

     This works regardless of how packages or derivations are specified.  For instance, the following invocations are equivalent:

          guix build --log-file `guix build -d guile`
          guix build --log-file `guix build guile`
          guix build --log-file guile
          guix build --log-file -e '(@ (gnu packages guile) guile-2.0)'

     If a log is unavailable locally, and unless --no-substitutes is passed, the command looks for a corresponding log on one of the substitute servers (as specified with --substitute-urls.)

     So for instance, imagine you want to see the build log of GDB on MIPS, but you are actually on an x86_64 machine:

          $ guix build --log-file gdb -s mips64el-linux
          https://ci.guix.de.info/log/...-gdb-7.10

     You can freely access a huge library of build logs!

Fehlschläge beim Erstellen untersuchen
--------------------------------------

When defining a new package (see Pakete definieren), you will probably find yourself spending some time debugging and tweaking the build until it succeeds.  To do that, you need to operate the build commands yourself in an environment as close as possible to the one the build daemon uses.

To that end, the first thing to do is to use the --keep-failed or -K option of guix build, which will keep the failed build tree in /tmp or whatever directory you specified as TMPDIR (see --keep-failed).

From there on, you can cd to the failed build tree and source the environment-variables file, which contains all the environment variable definitions that were in place when the build failed.  So let's say you're debugging a build failure in package foo; a typical session would look like this:

     $ guix build foo -K
     ... build fails
     $ cd /tmp/guix-build-foo.drv-0
     $ source ./environment-variables
     $ cd foo-1.2

Now, you can invoke commands as if you were the daemon (almost) and troubleshoot your build process.

Sometimes it happens that, for example, a package's tests pass when you run them manually but they fail when the daemon runs them.  This can happen because the daemon runs builds in containers where, unlike in our environment above, network access is missing, /bin/sh does not exist, etc. (see Einrichten der Erstellungsumgebung).

In such cases, you may need to run inspect the build process from within a container similar to the one the build daemon creates:

     $ guix build -K foo
     ...
     $ cd /tmp/guix-build-foo.drv-0
     $ guix environment --no-grafts -C foo --ad-hoc strace gdb
     [env]# source ./environment-variables
     [env]# cd foo-1.2

Here, guix environment -C creates a container and spawns a new shell in it (see Aufruf von guix environment).  The --ad-hoc strace gdb part adds the strace and gdb commands to the container, which would may find handy while debugging.  The --no-grafts option makes sure we get the exact same environment, with ungrafted packages (see Sicherheitsaktualisierungen, for more info on grafts).

To get closer to a container like that used by the build daemon, we can remove /bin/sh:

     [env]# rm /bin/sh

(Don't worry, this is harmless: this is all happening in the throw-away container created by guix environment.)

The strace command is probably not in the search path, but we can run:

     [env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check

In this way, not only you will have reproduced the environment variables the daemon uses, you will also be running the build process in a container similar to the one the daemon uses.

Invoking guix edit
==================

So many packages, so many source files! The guix edit command facilitates the life of users and packagers by pointing their editor at the source file containing the definition of the specified packages.  For instance:

     guix edit gcc@4.9 vim

launches the program specified in the VISUAL or in the EDITOR environment variable to view the recipe of GCC 4.9.3 and that of Vim.

If you are using a Guix Git checkout (see Erstellung aus dem Git), or have created your own packages on GUIX_PACKAGE_PATH (see Paketmodule), you will be able to edit the package recipes.  In other cases, you will be able to examine the read-only recipes for packages currently in the store.

Invoking guix download
======================

When writing a package definition, developers typically need to download a source tarball, compute its SHA256 hash, and write that hash in the package definition (see Pakete definieren).  The guix download tool helps with this task: it downloads a file from the given URI, adds it to the store, and prints both its file name in the store and its SHA256 hash.

The fact that the downloaded file is added to the store saves bandwidth: when the developer eventually tries to build the newly defined package with guix build, the source tarball will not have to be downloaded again because it is already in the store.  It is also a convenient way to temporarily stash files, which may be deleted eventually (see Aufruf von guix gc).

The guix download command supports the same URIs as used in package definitions.  In particular, it supports mirror:// URIs. https URIs (HTTP over TLS) are supported provided the Guile bindings for GnuTLS are available in the user's environment; when they are not available, an error is raised.  See how to install the GnuTLS bindings for Guile (GnuTLS-Guile), for more information.

guix download verifies HTTPS server certificates by loading the certificates of X.509 authorities from the directory pointed to by the SSL_CERT_DIR environment variable (see X.509-Zertifikate), unless --no-check-certificate is used.

The following options are available:

--format=FMT
-f FMT
     Write the hash in the format specified by FMT.  For more information on the valid values for FMT, see Aufruf von guix hash.

--no-check-certificate
     Do not validate the X.509 certificates of HTTPS servers.

     When using this option, you have absolutely no guarantee that you are communicating with the authentic server responsible for the given URL, which makes you vulnerable to ``man-in-the-middle'' attacks.

--output=FILE
-o FILE
     Save the downloaded file to FILE instead of adding it to the store.

Invoking guix hash
==================

The guix hash command computes the SHA256 hash of a file.  It is primarily a convenience tool for anyone contributing to the distribution: it computes the cryptographic hash of a file, which can be used in the definition of a package (see Pakete definieren).

Die allgemeine Syntax lautet:

     guix hash OPTION FILE

When FILE is - (a hyphen), guix hash computes the hash of data read from standard input.  guix hash has the following options:

--format=FMT
-f FMT
     Write the hash in the format specified by FMT.

     Supported formats: nix-base32, base32, base16 (hex and hexadecimal can be used as well).

     If the --format option is not specified, guix hash will output the hash in nix-base32.  This representation is used in the definitions of packages.

--recursive
-r
     Compute the hash on FILE recursively.

     In this case, the hash is computed on an archive containing FILE, including its children if it is a directory.  Some of the metadata of FILE is part of the archive; for instance, when FILE is a regular file, the hash is different depending on whether FILE is executable or not.  Metadata such as time stamps has no impact on the hash (see Aufruf von guix archive).

--exclude-vcs
-x
     When combined with --recursive, exclude version control system directories (.bzr, .git, .hg, etc.)

     As an example, here is how you would compute the hash of a Git checkout, which is useful when using the git-fetch method (see »origin«-Referenz):

          $ git clone http://example.org/foo.git
          $ cd foo
          $ guix hash -rx .

Invoking guix import
====================

The guix import command is useful for people who would like to add a package to the distribution with as little work as possible---a legitimate demand.  The command knows of a few repositories from which it can ``import'' package metadata.  The result is a package definition, or a template thereof, in the format we know (see Pakete definieren).

Die allgemeine Syntax lautet:

     guix import IMPORTER OPTIONS...

IMPORTER specifies the source from which to import package metadata, and OPTIONS specifies a package identifier and other options specific to IMPORTER.  Currently, the available ``importers'' are:

gnu
     Import metadata for the given GNU package.  This provides a template for the latest version of that GNU package, including the hash of its source tarball, and its canonical synopsis and description.

     Additional information such as the package dependencies and its license needs to be figured out manually.

     For example, the following command returns a package definition for GNU Hello:

          guix import gnu hello

     Specific command-line options are:

     --key-download=POLICY
          As for guix refresh, specify the policy to handle missing OpenPGP keys when verifying the package signature.  See --key-download.

pypi
     Import metadata from the Python Package Index (https://pypi.python.org/).  Information is taken from the JSON-formatted description available at pypi.python.org and usually includes all the relevant information, including package dependencies.  For maximum efficiency, it is recommended to install the unzip utility, so that the importer can unzip Python wheels and gather data from them.

     The command below imports metadata for the itsdangerous Python package:

          guix import pypi itsdangerous

     --recursive
     -r
          Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

gem
     Import metadata from RubyGems (https://rubygems.org/).  Information is taken from the JSON-formatted description available at rubygems.org and includes most relevant information, including runtime dependencies. There are some caveats, however.  The metadata doesn't distinguish between synopses and descriptions, so the same string is used for both fields. Additionally, the details of non-Ruby dependencies required to build native extensions is unavailable and left as an exercise to the packager.

     The command below imports metadata for the rails Ruby package:

          guix import gem rails

     --recursive
     -r
          Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

cpan
     Import metadata from MetaCPAN (https://www.metacpan.org/). Information is taken from the JSON-formatted metadata provided through MetaCPAN's API (https://fastapi.metacpan.org/) and includes most relevant information, such as module dependencies.  License information should be checked closely.  If Perl is available in the store, then the corelist utility will be used to filter core modules out of the list of dependencies.

     The command command below imports metadata for the Acme::Boolean Perl module:

          guix import cpan Acme::Boolean

cran
     Import metadata from CRAN (https://cran.r-project.org/), the central repository for the GNU R statistical and graphical environment (http://r-project.org).

     Information is extracted from the DESCRIPTION file of the package.

     The command command below imports metadata for the Cairo R package:

          guix import cran Cairo

     When --recursive is added, the importer will traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

     When --archive=bioconductor is added, metadata is imported from Bioconductor (https://www.bioconductor.org/), a repository of R packages for for the analysis and comprehension of high-throughput genomic data in bioinformatics.

     Information is extracted from the DESCRIPTION file of a package published on the web interface of the Bioconductor SVN repository.

     The command below imports metadata for the GenomicRanges R package:

          guix import cran --archive=bioconductor GenomicRanges

texlive
     Import metadata from CTAN (http://www.ctan.org/), the comprehensive TeX archive network for TeX packages that are part of the TeX Live distribution (https://www.tug.org/texlive/).

     Information about the package is obtained through the XML API provided by CTAN, while the source code is downloaded from the SVN repository of the Tex Live project.  This is done because the CTAN does not keep versioned archives.

     The command command below imports metadata for the fontspec TeX package:

          guix import texlive fontspec

     When --archive=DIRECTORY is added, the source code is downloaded not from the latex sub-directory of the texmf-dist/source tree in the TeX Live SVN repository, but from the specified sibling directory under the same root.

     The command below imports metadata for the ifxetex package from CTAN while fetching the sources from the directory texmf/source/generic:

          guix import texlive --archive=generic ifxetex

json
     Import package metadata from a local JSON file.  Consider the following example package definition in JSON format:

          {
            "name": "hello",
            "version": "2.10",
            "source": "mirror://gnu/hello/hello-2.10.tar.gz",
            "build-system": "gnu",
            "home-page": "https://www.gnu.org/software/hello/",
            "synopsis": "Hello, GNU world: An example GNU package",
            "description": "GNU Hello prints a greeting.",
            "license": "GPL-3.0+",
            "native-inputs": ["gcc@6"]
          }

     The field names are the same as for the <package> record (see Pakete definieren).  References to other packages are provided as JSON lists of quoted package specification strings such as guile or guile@2.0.

     The importer also supports a more explicit source definition using the common fields for <origin> records:

          {
            ...
            "source": {
              "method": "url-fetch",
              "uri": "mirror://gnu/hello/hello-2.10.tar.gz",
              "sha256": {
                "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i"
              }
            }
            ...
          }

     The command below reads metadata from the JSON file hello.json and outputs a package expression:

          guix import json hello.json

nix
     Import metadata from a local copy of the source of the Nixpkgs distribution (http://nixos.org/nixpkgs/) (This relies on the nix-instantiate command of Nix (http://nixos.org/nix/).).  Package definitions in Nixpkgs are typically written in a mixture of Nix-language and Bash code.  This command only imports the high-level package structure that is written in the Nix language.  It normally includes all the basic fields of a package definition.

     When importing a GNU package, the synopsis and descriptions are replaced by their canonical upstream variant.

     Usually, you will first need to do:

          export NIX_REMOTE=daemon

     so that nix-instantiate does not try to open the Nix database.

     As an example, the command below imports the package definition of LibreOffice (more precisely, it imports the definition of the package bound to the libreoffice top-level attribute):

          guix import nix ~/path/to/nixpkgs libreoffice

hackage
     Import metadata from the Haskell community's central package archive Hackage (https://hackage.haskell.org/).  Information is taken from Cabal files and includes all the relevant information, including package dependencies.

     Specific command-line options are:

     --stdin
     -s
          Read a Cabal file from standard input.

     --no-test-dependencies
     -t
          Do not include dependencies required only by the test suites.

     --cabal-environment=ALIST
     -e ALIST
          ALIST is a Scheme alist defining the environment in which the Cabal conditionals are evaluated.  The accepted keys are: os, arch, impl and a string representing the name of a flag.  The value associated with a flag has to be either the symbol true or false.  The value associated with other keys has to conform to the Cabal file format definition.  The default value associated with the keys os, arch and impl is linux, x86_64 and ghc, respectively.

     --recursive
     -r
          Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

     The command below imports metadata for the latest version of the HTTP Haskell package without including test dependencies and specifying the value of the flag network-uri as false:

          guix import hackage -t -e "'((\"network-uri\" . false))" HTTP

     A specific package version may optionally be specified by following the package name by an at-sign and a version number as in the following example:

          guix import hackage mtl@2.1.3.1

stackage
     The stackage importer is a wrapper around the hackage one.  It takes a package name, looks up the package version included in a long-term support (LTS) Stackage (https://www.stackage.org) release and uses the hackage importer to retrieve its metadata.  Note that it is up to you to select an LTS release compatible with the GHC compiler used by Guix.

     Specific command-line options are:

     --no-test-dependencies
     -t
          Do not include dependencies required only by the test suites.

     --lts-version=VERSION
     -l VERSION
          VERSION is the desired LTS release version.  If omitted the latest release is used.

     --recursive
     -r
          Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

     The command below imports metadata for the HTTP Haskell package included in the LTS Stackage release version 7.18:

          guix import stackage --lts-version=7.18 HTTP

elpa
     Import metadata from an Emacs Lisp Package Archive (ELPA) package repository (see Packages (The GNU Emacs Manual)).

     Specific command-line options are:

     --archive=REPO
     -a REPO
          REPO identifies the archive repository from which to retrieve the information.  Currently the supported repositories and their identifiers are:

            - GNU (http://elpa.gnu.org/packages), selected by the gnu identifier.  This is the default.

               Packages from elpa.gnu.org are signed with one of the keys contained in the GnuPG keyring at share/emacs/25.1/etc/package-keyring.gpg (or similar) in the emacs package (see ELPA package signatures (The GNU Emacs Manual)).

            - MELPA-Stable (http://stable.melpa.org/packages), selected by the melpa-stable identifier.

            - MELPA (http://melpa.org/packages), selected by the melpa identifier.

     --recursive
     -r
          Traverse the dependency graph of the given upstream package recursively and generate package expressions for all those packages that are not yet in Guix.

crate
     Import metadata from the crates.io Rust package repository crates.io (https://crates.io).

opam
     Import metadata from the OPAM (https://opam.ocaml.org/) package repository used by the OCaml community.

The structure of the guix import code is modular.  It would be useful to have more importers for other package formats, and your help is welcome here (see Mitwirken).

Invoking guix refresh
=====================

The primary audience of the guix refresh command is developers of the GNU software distribution.  By default, it reports any packages provided by the distribution that are outdated compared to the latest upstream version, like this:

     $ guix refresh
     gnu/packages/gettext.scm:29:13: gettext would be upgraded from 0.18.1.1 to 0.18.2.1
     gnu/packages/glib.scm:77:12: glib would be upgraded from 2.34.3 to 2.37.0

Alternately, one can specify packages to consider, in which case a warning is emitted for packages that lack an updater:

     $ guix refresh coreutils guile guile-ssh
     gnu/packages/ssh.scm:205:2: warning: no updater for guile-ssh
     gnu/packages/guile.scm:136:12: guile would be upgraded from 2.0.12 to 2.0.13

guix refresh browses the upstream repository of each package and determines the highest version number of the releases therein.  The command knows how to update specific types of packages: GNU packages, ELPA packages, etc.---see the documentation for --type below.  There are many packages, though, for which it lacks a method to determine whether a new upstream release is available.  However, the mechanism is extensible, so feel free to get in touch with us to add a new method!

--recursive
     Consider the packages specified, and all the packages upon which they depend.

          $ guix refresh --recursive coreutils
          gnu/packages/acl.scm:35:2: warning: no updater for acl
          gnu/packages/m4.scm:30:12: info: 1.4.18 is already the latest version of m4
          gnu/packages/xml.scm:68:2: warning: no updater for expat
          gnu/packages/multiprecision.scm:40:12: info: 6.1.2 is already the latest version of gmp
          ...

Sometimes the upstream name differs from the package name used in Guix, and guix refresh needs a little help.  Most updaters honor the upstream-name property in package definitions, which can be used to that effect:

     (define-public network-manager
       (package
         (name "network-manager")
         ;; ...
         (properties '((upstream-name . "NetworkManager")))))

When passed --update, it modifies distribution source files to update the version numbers and source tarball hashes of those package recipes (see Pakete definieren).  This is achieved by downloading each package's latest source tarball and its associated OpenPGP signature, authenticating the downloaded tarball against its signature using gpg, and finally computing its hash.  When the public key used to sign the tarball is missing from the user's keyring, an attempt is made to automatically retrieve it from a public key server; when this is successful, the key is added to the user's keyring; otherwise, guix refresh reports an error.

The following options are supported:

--expression=AUSDRUCK
-e AUSDRUCK
     Als Paket benutzen, wozu der AUSDRUCK ausgewertet wird.

     This is useful to precisely refer to a package, as in this example:

          guix refresh -l -e '(@@ (gnu packages commencement) glibc-final)'

     This command lists the dependents of the ``final'' libc (essentially all the packages.)

--update
-u
     Update distribution source files (package recipes) in place.  This is usually run from a checkout of the Guix source tree (see Guix vor der Installation ausführen):

          $ ./pre-inst-env guix refresh -s non-core -u

     See Pakete definieren, for more information on package definitions.

--select=[SUBSET]
-s SUBSET
     Select all the packages in SUBSET, one of core or non-core.

     The core subset refers to all the packages at the core of the distribution---i.e., packages that are used to build ``everything else''. This includes GCC, libc, Binutils, Bash, etc.  Usually, changing one of these packages in the distribution entails a rebuild of all the others. Thus, such updates are an inconvenience to users in terms of build time or bandwidth used to achieve the upgrade.

     The non-core subset refers to the remaining packages.  It is typically useful in cases where an update of the core packages would be inconvenient.

--manifest=DATEI
-m DATEI
     Select all the packages from the manifest in FILE. This is useful to check if any packages of the user manifest can be updated.

--type=UPDATER
-t UPDATER
     Select only packages handled by UPDATER (may be a comma-separated list of updaters).  Currently, UPDATER may be one of:

     gnu
          the updater for GNU packages;

     gnome
          the updater for GNOME packages;

     kde
          the updater for KDE packages;

     xorg
          the updater for X.org packages;

     kernel.org
          the updater for packages hosted on kernel.org;

     elpa
          the updater for ELPA (http://elpa.gnu.org/) packages;

     cran
          the updater for CRAN (https://cran.r-project.org/) packages;

     bioconductor
          the updater for Bioconductor (https://www.bioconductor.org/) R packages;

     cpan
          the updater for CPAN (http://www.cpan.org/) packages;

     pypi
          the updater for PyPI (https://pypi.python.org) packages.

     gem
          the updater for RubyGems (https://rubygems.org) packages.

     github
          the updater for GitHub (https://github.com) packages.

     hackage
          the updater for Hackage (https://hackage.haskell.org) packages.

     stackage
          the updater for Stackage (https://www.stackage.org) packages.

     crate
          the updater for Crates (https://crates.io) packages.

     For instance, the following command only checks for updates of Emacs packages hosted at elpa.gnu.org and for updates of CRAN packages:

          $ guix refresh --type=elpa,cran
          gnu/packages/statistics.scm:819:13: r-testthat would be upgraded from 0.10.0 to 0.11.0
          gnu/packages/emacs.scm:856:13: emacs-auctex would be upgraded from 11.88.6 to 11.88.9

In addition, guix refresh can be passed one or more package names, as in this example:

     $ ./pre-inst-env guix refresh -u emacs idutils gcc@4.8

The command above specifically updates the emacs and idutils packages.  The --select option would have no effect in this case.

When considering whether to upgrade a package, it is sometimes convenient to know which packages would be affected by the upgrade and should be checked for compatibility.  For this the following option may be used when passing guix refresh one or more package names:

--list-updaters
-L
     List available updaters and exit (see --type above.)

     For each updater, display the fraction of packages it covers; at the end, display the fraction of packages covered by all these updaters.

--list-dependent
-l
     List top-level dependent packages that would need to be rebuilt as a result of upgrading one or more packages.

     See the reverse-package type of guix graph, for information on how to visualize the list of dependents of a package.

Be aware that the --list-dependent option only approximates the rebuilds that would be required as a result of an upgrade.  More rebuilds might be required under some circumstances.

     $ guix refresh --list-dependent flex
     Building the following 120 packages would ensure 213 dependent packages are rebuilt:
     hop@2.4.0 geiser@0.4 notmuch@0.18 mu@0.9.9.5 cflow@1.4 idutils@4.6 ...

The command above lists a set of packages that could be built to check for compatibility with an upgraded flex package.

--list-transitive
     List all the packages which one or more packages depend upon.

          $ guix refresh --list-transitive flex
          flex@2.6.4 depends on the following 25 packages: perl@5.28.0 help2man@1.47.6
          bison@3.0.5 indent@2.2.10 tar@1.30 gzip@1.9 bzip2@1.0.6 xz@5.2.4 file@5.33 ...

The command above lists a set of packages which, when changed, would cause flex to be rebuilt.

The following options can be used to customize GnuPG operation:

--gpg=COMMAND
     Use COMMAND as the GnuPG 2.x command.  COMMAND is searched for in $PATH.

--keyring=DATEI
     Use FILE as the keyring for upstream keys.  FILE must be in the keybox format.  Keybox files usually have a name ending in .kbx and the GNU Privacy Guard (GPG) can manipulate these files (see kbxutil (Using the GNU Privacy Guard), for information on a tool to manipulate keybox files).

     When this option is omitted, guix refresh uses ~/.config/guix/upstream/trustedkeys.kbx as the keyring for upstream signing keys.  OpenPGP signatures are checked against keys from this keyring; missing keys are downloaded to this keyring as well (see --key-download below.)

     You can export keys from your default GPG keyring into a keybox file using commands like this one:

          gpg --export rms@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx

     Likewise, you can fetch keys to a specific keybox file like this:

          gpg --no-default-keyring --keyring mykeyring.kbx \
            --recv-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5

     --keyring (Using the GNU Privacy Guard), for more information on GPG's --keyring option.

--key-download=POLICY
     Handle missing OpenPGP keys according to POLICY, which may be one of:

     always
          Always download missing OpenPGP keys from the key server, and add them to the user's GnuPG keyring.

     never
          Never try to download missing OpenPGP keys.  Instead just bail out.

     interactive
          When a package signed with an unknown OpenPGP key is encountered, ask the user whether to download it or not.  This is the default behavior.

--key-server=HOST
     Use HOST as the OpenPGP key server when importing a public key.

The github updater uses the GitHub API (https://developer.github.com/v3/) to query for new releases.  When used repeatedly e.g. when refreshing all packages, GitHub will eventually refuse to answer any further API requests.  By default 60 API requests per hour are allowed, and a full refresh on all GitHub packages in Guix requires more than this. Authentication with GitHub through the use of an API token alleviates these limits.  To use an API token, set the environment variable GUIX_GITHUB_TOKEN to a token procured from https://github.com/settings/tokens or otherwise.

Invoking guix lint
==================

The guix lint command is meant to help package developers avoid common errors and use a consistent style.  It runs a number of checks on a given set of packages in order to find common mistakes in their definitions.  Available checkers include (see --list-checkers for a complete list):

synopsis
description
     Validate certain typographical and stylistic rules about package descriptions and synopses.

inputs-should-be-native
     Identify inputs that should most likely be native inputs.

source
home-page
mirror-url
github-url
source-file-name
     Probe home-page and source URLs and report those that are invalid.  Suggest a mirror:// URL when applicable.  If the source URL redirects to a GitHub URL, recommend usage of the GitHub URL.  Check that the source file name is meaningful, e.g. is not just a version number or ``git-checkout'', without a declared file-name (see »origin«-Referenz).

source-unstable-tarball
     Parse the source URL to determine if a tarball from GitHub is autogenerated or if it is a release tarball.  Unfortunately GitHub's autogenerated tarballs are sometimes regenerated.

cve
     Report known vulnerabilities found in the Common Vulnerabilities and Exposures (CVE) databases of the current and past year published by the US NIST (https://nvd.nist.gov/download.cfm#CVE_FEED).

     To view information about a particular vulnerability, visit pages such as:

       * https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD

       * https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD

     where CVE-YYYY-ABCD is the CVE identifier---e.g., CVE-2015-7554.

     Package developers can specify in package recipes the Common Platform Enumeration (CPE) (https://nvd.nist.gov/cpe.cfm) name and version of the package when they differ from the name or version that Guix uses, as in this example:

          (package
            (name "grub")
            ;; ...
            ;; CPE calls this package "grub2".
            (properties '((cpe-name . "grub2")
                          (cpe-version . "2.3")))

     Some entries in the CVE database do not specify which version of a package they apply to, and would thus ``stick around'' forever.  Package developers who found CVE alerts and verified they can be ignored can declare them as in this example:

          (package
            (name "t1lib")
            ;; ...
            ;; These CVEs no longer apply and can be safely ignored.
            (properties `((lint-hidden-cve . ("CVE-2011-0433"
                                              "CVE-2011-1553"
                                              "CVE-2011-1554"
                                              "CVE-2011-5244")))))

formatting
     Warn about obvious source code formatting issues: trailing white space, use of tabulations, etc.

Die allgemeine Syntax lautet:

     guix lint OPTIONS PACKAGE...

If no package is given on the command line, then all packages are checked. The OPTIONS may be zero or more of the following:

--list-checkers
-l
     List and describe all the available checkers that will be run on packages and exit.

--checkers
-c
     Only enable the checkers specified in a comma-separated list using the names returned by --list-checkers.

Invoking guix size
==================

The guix size command helps package developers profile the disk usage of packages.  It is easy to overlook the impact of an additional dependency added to a package, or the impact of using a single output for a package that could easily be split (see Pakete mit mehreren Ausgaben.).  Such are the typical issues that guix size can highlight.

The command can be passed one or more package specifications such as gcc@4.8 or guile:debug, or a file name in the store. Consider this example:

     $ guix size coreutils
     store item                               total    self
     /gnu/store/...-gcc-5.5.0-lib           60.4    30.1  38.1%
     /gnu/store/...-glibc-2.27              30.3    28.8  36.6%
     /gnu/store/...-coreutils-8.28          78.9    15.0  19.0%
     /gnu/store/...-gmp-6.1.2               63.1     2.7   3.4%
     /gnu/store/...-bash-static-4.4.12       1.5     1.5   1.9%
     /gnu/store/...-acl-2.2.52              61.1     0.4   0.5%
     /gnu/store/...-attr-2.4.47             60.6     0.2   0.3%
     /gnu/store/...-libcap-2.25             60.5     0.2   0.2%
     total: 78.9 MiB

The store items listed here constitute the transitive closure of Coreutils---i.e., Coreutils and all its dependencies, recursively---as would be returned by:

     $ guix gc -R /gnu/store/...-coreutils-8.23

Here the output shows three columns next to store items.  The first column, labeled ``total'', shows the size in mebibytes (MiB) of the closure of the store item---that is, its own size plus the size of all its dependencies. The next column, labeled ``self'', shows the size of the item itself.  The last column shows the ratio of the size of the item itself to the space occupied by all the items listed here.

In this example, we see that the closure of Coreutils weighs in at 79 MiB, most of which is taken by libc and GCC's run-time support libraries.  (That libc and GCC's libraries represent a large fraction of the closure is not a problem per se because they are always available on the system anyway.)

When the package(s) passed to guix size are available in the store (More precisely, guix size looks for the ungrafted variant of the given package(s), as returned by guix build PACKAGE --no-grafts.  See Sicherheitsaktualisierungen, for information on grafts.), guix size queries the daemon to determine its dependencies, and measures its size in the store, similar to du -ms --apparent-size (see du invocation (GNU Coreutils)).

When the given packages are not in the store, guix size reports information based on the available substitutes (see Substitute).  This makes it possible it to profile disk usage of store items that are not even on disk, only available remotely.

You can also specify several package names:

     $ guix size coreutils grep sed bash
     store item                               total    self
     /gnu/store/...-coreutils-8.24          77.8    13.8  13.4%
     /gnu/store/...-grep-2.22               73.1     0.8   0.8%
     /gnu/store/...-bash-4.3.42             72.3     4.7   4.6%
     /gnu/store/...-readline-6.3            67.6     1.2   1.2%
     ...
     total: 102.3 MiB

In this example we see that the combination of the four packages takes 102.3 MiB in total, which is much less than the sum of each closure since they have a lot of dependencies in common.

The available options are:

--substitute-urls=URLS
     Use substitute information from URLS.  See the same option for guix build.

--sort=KEY
     Sort lines according to KEY, one of the following options:

     self
          the size of each item (the default);

     Abschluss
          the total size of the item's closure.

--map-file=FILE
     Write a graphical map of disk usage in PNG format to FILE.

     For the example above, the map looks like this:

     map of Coreutils disk usage produced by guix size

     This option requires that Guile-Charting (http://wingolog.org/software/guile-charting/) be installed and visible in Guile's module search path.  When that is not the case, guix size fails as it tries to load it.

--system=SYSTEM
-s SYSTEM
     Consider packages for SYSTEM---e.g., x86_64-linux.

Invoking guix graph
===================

Packages and their dependencies form a graph, specifically a directed acyclic graph (DAG).  It can quickly become difficult to have a mental model of the package DAG, so the guix graph command provides a visual representation of the DAG.  By default, guix graph emits a DAG representation in the input format of Graphviz (http://www.graphviz.org/), so its output can be passed directly to the dot command of Graphviz.  It can also emit an HTML page with embedded JavaScript code to display a ``chord diagram'' in a Web browser, using the d3.js (https://d3js.org/) library, or emit Cypher queries to construct a graph in a graph database supporting the openCypher (http://www.opencypher.org/) query language.  The general syntax is:

     guix graph OPTIONS PACKAGE...

For example, the following command generates a PDF file representing the package DAG for the GNU Core Utilities, showing its build-time dependencies:

     guix graph coreutils | dot -Tpdf > dag.pdf

The output looks like this:

Dependency graph of the GNU Coreutils

Nice little graph, no?

But there is more than one graph! The one above is concise: it is the graph of package objects, omitting implicit inputs such as GCC, libc, grep, etc. It is often useful to have such a concise graph, but sometimes one may want to see more details.  guix graph supports several types of graphs, allowing you to choose the level of detail:

package
     This is the default type used in the example above.  It shows the DAG of package objects, excluding implicit dependencies.  It is concise, but filters out many details.

reverse-package
     This shows the reverse DAG of packages.  For example:

          guix graph --type=reverse-package ocaml

     ... yields the graph of packages that depend on OCaml.

     Note that for core packages this can yield huge graphs.  If all you want is to know the number of packages that depend on a given package, use guix refresh --list-dependent (see --list-dependent).

bag-emerged
     This is the package DAG, including implicit inputs.

     For instance, the following command:

          guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf

     ... yields this bigger graph:

     Detailed dependency graph of the GNU Coreutils

     At the bottom of the graph, we see all the implicit inputs of GNU-BUILD-SYSTEM (see gnu-build-system).

     Now, note that the dependencies of these implicit inputs---that is, the bootstrap dependencies (see Bootstrapping)---are not shown here, for conciseness.

bag
     Similar to bag-emerged, but this time including all the bootstrap dependencies.

bag-with-origins
     Similar to bag, but also showing origins and their dependencies.

Ableitung
     This is the most detailed representation: It shows the DAG of derivations (see Ableitungen) and plain store items.  Compared to the above representation, many additional nodes are visible, including build scripts, patches, Guile modules, etc.

     For this type of graph, it is also possible to pass a .drv file name instead of a package name, as in:

          guix graph -t derivation `guix system build -d my-config.scm`

module
     This is the graph of package modules (see Paketmodule).  For example, the following command shows the graph for the package module that defines the guile package:

          guix graph -t module guile | dot -Tpdf > module-graph.pdf

All the types above correspond to build-time dependencies.  The following graph type represents the run-time dependencies:

references
     This is the graph of references of a package output, as returned by guix gc --references (see Aufruf von guix gc).

     If the given package output is not available in the store, guix graph attempts to obtain dependency information from substitutes.

     Here you can also pass a store file name instead of a package name.  For example, the command below produces the reference graph of your profile (which can be big!):

          guix graph -t references `readlink -f ~/.guix-profile`

referrers
     This is the graph of the referrers of a store item, as returned by guix gc --referrers (see Aufruf von guix gc).

     This relies exclusively on local information from your store.  For instance, let us suppose that the current Inkscape is available in 10 profiles on your machine; guix graph -t referrers inkscape will show a graph rooted at Inkscape and with those 10 profiles linked to it.

     It can help determine what is preventing a store item from being garbage collected.

The available options are the following:

--type=TYPE
-t TYPE
     Produce a graph output of TYPE, where TYPE must be one of the values listed above.

--list-types
     List the supported graph types.

--backend=BACKEND
-b BACKEND
     Produce a graph using the selected BACKEND.

--list-backends
     List the supported graph backends.

     Currently, the available backends are Graphviz and d3.js.

--expression=AUSDRUCK
-e AUSDRUCK
     Als Paket benutzen, wozu der AUSDRUCK ausgewertet wird.

     This is useful to precisely refer to a package, as in this example:

          guix graph -e '(@@ (gnu packages commencement) gnu-make-final)'

--system=SYSTEM
-s SYSTEM
     Display the graph for SYSTEM---e.g., i686-linux.

     The package dependency graph is largely architecture-independent, but there are some architecture-dependent bits that this option allows you to visualize.

guix publish aufrufen
=====================

Der Zweck von guix publish ist, es Nutzern zu ermöglichen, ihren Store auf einfache Weise mit anderen zu teilen, die ihn dann als Substitutserver einsetzen können (see Substitute).

When guix publish runs, it spawns an HTTP server which allows anyone with network access to obtain substitutes from it.  This means that any machine running Guix can also act as if it were a build farm, since the HTTP interface is compatible with Hydra, the software behind the ci.guix.de.info build farm.

Um Sicherheit zu gewährleisten, wird jedes Substitut signiert, so dass Empfänger dessen Authentizität und Integrität nachprüfen können (siehe Substitute). Weil guix publish den Signierschlüssel des Systems benutzt, der nur vom Systemadministrator gelesen werden kann, muss es als der Administratornutzer »root« gestartet werden. Mit der Befehlszeilenoption --user werden Administratorrechte bald nach dem Start wieder abgelegt.

Das Schlüsselpaar zum Signieren muss erzeugt werden, bevor guix publish gestartet wird. Dazu können Sie guix archive --generate-key ausführen (see Aufruf von guix archive).

Die allgemeine Syntax lautet:

     guix publish OPTIONEN...

Wird guix publish ohne weitere Argumente ausgeführt, wird damit ein HTTP-Server gestartet, der auf Port 8080 lauscht:

     guix publish

Sobald ein Server zum Veröffentlichen autorisiert wurde (see Aufruf von guix archive), kann der Daemon davon Substitute herunterladen:

     guix-daemon --substitute-urls=http://example.org:8080

Nach den Voreinstellungen komprimiert guix publish Archive erst dann, wenn sie angefragt werden. Dieser »dynamische« Modus bietet sich an, weil so nichts weiter eingerichtet werden muss und er direkt verfügbar ist. Wenn Sie allerdings viele Clients bedienen wollen, empfehlen wir, dass Sie die Befehlszeilenoption --cache benutzen, die das Zwischenspeichern der komprimierten Archive aktiviert, bevor diese an die Clients geschickt werden — siehe unten für Details. Mit dem Befehl guix weather haben Sie eine praktische Methode zur Hand, zu überprüfen, was so ein Server anbietet (see Aufruf von guix weather).

Als Bonus dient guix publish auch als inhaltsadressierbarer Spiegelserver für Quelldateien, die in origin-Verbundsobjekten eingetragen sind (see »origin«-Referenz). Wenn wir zum Beispiel annehmen, dass guix publish auf example.org läuft, liefert folgende URL die rohe hello-2.10.tar.gz-Datei mit dem angegebenen SHA256-Hash als ihre Prüfsumme (dargestellt im nix-base32-Format, siehe Aufruf von guix hash):

     http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1...ndq1i

Offensichtlich funktionieren diese URLs nur mit solchen Dateien, die auch im Store vorliegen; in anderen Fällen werden sie 404 (»Nicht gefunden«) zurückliefern.

Erstellungsprotokolle sind unter /log-URLs abrufbar:

     http://example.org/log/gwspk...-guile-2.2.3

Ist der guix-daemon so eingestellt, dass er Erstellungsprotokolle komprimiert abspeichert, wie es voreingestellt ist (see Aufruf des guix-daemon), liefern /log-URLs das unveränderte komprimierte Protokoll, mit einer entsprechenden Content-Type- und/oder Content-Encoding-Kopfzeile. Wir empfehlen dabei, dass Sie den guix-daemon mit --log-compression=gzip ausführen, weil Web-Browser dieses Format automatisch dekomprimieren können, was bei bzip2-Kompression nicht der Fall ist.

The following options are available:

--port=PORT
-p PORT
     Auf HTTP-Anfragen auf diesem PORT lauschen.

--listen=HOST
     Auf der Netzwerkschnittstelle für den angegebenen HOST, also der angegebenen Rechneradresse, lauschen. Vorgegeben ist, Verbindungen mit jeder Schnittstelle zu akzeptieren.

--user=BENUTZER
-u BENUTZER
     So früh wie möglich alle über die Berechtigungen des BENUTZERs hinausgehenden Berechtigungen ablegen — d.h. sobald der Server-Socket geöffnet und der Signierschlüssel gelesen wurde.

--compression[=STUFE]
-C [STUFE]
     Daten auf der angegebenen Kompressions-STUFE komprimieren. Wird als STUFE null angegeben, wird Kompression deaktiviert. Der Bereich von 1 bis 9 entspricht unterschiedlichen gzip-Kompressionsstufen: 1 ist am schnellsten, während 9 am besten komprimiert (aber den Prozessor mehr auslastet). Der Vorgabewert ist 3.

     Wenn --cache nicht übergeben wird, werden Daten dynamisch immer erst dann komprimiert, wenn sie abgeschickt werden; komprimierte Datenströme landen in keinem Zwischenspeicher. Um also die Auslastung der Maschine, auf der guix publish läuft, zu reduzieren, kann es eine gute Idee sein, eine niedrige Kompressionsstufe zu wählen, guix publish einen Proxy mit Zwischenspeicher (einen »Caching Proxy«) voranzuschalten, oder --cache zu benutzen. --cache zu benutzen, hat den Vorteil, dass guix publish damit eine Content-Length-HTTP-Kopfzeile seinen Antworten beifügen kann.

--cache=VERZEICHNIS
-c VERZEICHNIS
     Archive und Metadaten (.narinfo-URLs) in das VERZEICHNIS zwischenspeichern und nur solche Archive versenden, die im Zwischenspeicher vorliegen.

     Wird diese Befehlszeilenoption weggelassen, dann werden Archive und Metadaten »dynamisch« erst auf eine Anfrage hin erzeugt. Dadurch kann die verfügbare Bandbreite reduziert werden, besonders wenn Kompression aktiviert ist, weil die Operation dann durch die Prozessorleistung beschränkt sein kann. Noch ein Nachteil des voreingestellten Modus ist, dass die Länge der Archive nicht im Voraus bekannt ist, guix publish also keine Content-Length-HTTP-Kopfzeile an seine Antworten anfügt, wodurch Clients nicht wissen können, welche Datenmenge noch heruntergeladen werden muss.

     Im Gegensatz dazu liefert, wenn --cache benutzt wird, die erste Anfrage nach einem Store-Objekt (über dessen .narinfo-URL) den Fehlercode 404, und im Hintergrund wird ein Prozess gestartet, der das Archiv in den Zwischenspeicher einlagert (auf Englisch sagen wir »bake the archive«), d.h. seine .narinfo wird berechnet und das Archiv, falls nötig, komprimiert. Sobald das Archiv im VERZEICHNIS zwischengespeichert wurde, werden nachfolgende Anfragen erfolgreich sein und direkt aus dem Zwischenspeicher bedient, der garantiert, dass Clients optimale Bandbreite genießen.

     Der Prozess zum Einlagern wird durch Worker-Threads umgesetzt. Der Vorgabe entsprechend wird dazu pro Prozessorkern ein Thread erzeugt, aber dieses Verhalten kann angepasst werden. Siehe --workers weiter unten.

     Wird --ttl verwendet, werden zwischengespeicherte Einträge automatisch gelöscht, sobald die dabei angegebene Zeit abgelaufen ist.

--workers=N
     Wird --cache benutzt, wird die Reservierung von N Worker-Threads angefragt, um Archive einzulagern.

--ttl=TTL
     Cache-Control-HTTP-Kopfzeilen erzeugen, die eine Time-to-live (TTL) von TTL signalisieren. Für TTL muss eine Dauer (mit dem Anfangsbuchstaben der Maßeinheit der Dauer im Englischen) angegeben werden: 5d bedeutet 5 Tage, 1m bedeutet 1 Monat und so weiter.

     Das ermöglicht es Guix, Substitutinformationen TTL lang zwischenzuspeichern. Beachten Sie allerdings, dass guix publish selbst nicht garantiert, dass die davon angebotenen Store-Objekte so lange verfügbar bleiben, wie es die TTL vorsieht.

     Des Weiteren können bei Nutzung von --cache die zwischengespeicherten Einträge gelöscht werden, wenn auf sie TTL lang nicht zugegriffen wurde und kein ihnen entsprechendes Objekt mehr im Store existiert.

--nar-path=PFAD
     Den PFAD als Präfix für die URLs von »nar«-Dateien benutzen (see normalized archives).

     Vorgegeben ist, dass Nars unter einer URL mit /nar/gzip/...-coreutils-8.25 angeboten werden. Mit dieser Befehlszeilenoption können Sie den /nar-Teil durch den angegebenen PFAD ersetzen.

--public-key=DATEI
--private-key=DATEI
     Die angegebenen DATEIen als das Paar aus öffentlichem und privatem Schlüssel zum Signieren veröffentlichter Store-Objekte benutzen.

     Die Dateien müssen demselben Schlüsselpaar entsprechen (der private Schlüssel wird zum Signieren benutzt, der öffentliche Schlüssel wird lediglich in den Metadaten der Signatur aufgeführt). Die Dateien müssen Schlüssel im kanonischen (»canonical«) S-Ausdruck-Format enthalten, wie es von guix archive --generate-key erzeugt wird (see Aufruf von guix archive). Vorgegeben ist, dass /etc/guix/signing-key.pub und /etc/guix/signing-key.sec benutzt werden.

--repl[=PORT]
-r [PORT]
     Einen Guile-REPL-Server (see REPL Servers (GNU Guile Reference Manual)) auf diesem PORT starten (37146 ist voreingestellt). Dies kann zur Fehlersuche auf einem laufenden »guix publish«-Server benutzt werden.

Enabling guix publish on Guix System is a one-liner: just instantiate a guix-publish-service-type service in the services field of the operating-system declaration (see guix-publish-service-type).

Falls Sie Guix aber auf einer »Fremddistribution« laufen lassen, folgen Sie folgenden Anweisungen:

  * Wenn Ihre Wirtsdistribution systemd als »init«-System benutzt:

          # ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \
                  /etc/systemd/system/
          # systemctl start guix-publish && systemctl enable guix-publish

  * Wenn Ihre Wirts-Distribution als »init«-System Upstart verwendet:

          # ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/
          # start guix-publish

  * Verfahren Sie andernfalls auf die gleiche Art für das »init«-System, das Ihre Distribution verwendet.

Invoking guix challenge
=======================

Do the binaries provided by this server really correspond to the source code it claims to build? Is a package build process deterministic? These are the questions the guix challenge command attempts to answer.

The former is obviously an important question: Before using a substitute server (see Substitute), one had better verify that it provides the right binaries, and thus challenge it.  The latter is what enables the former: If package builds are deterministic, then independent builds of the package should yield the exact same result, bit for bit; if a server provides a binary different from the one obtained locally, it may be either corrupt or malicious.

We know that the hash that shows up in /gnu/store file names is the hash of all the inputs of the process that built the file or directory---compilers, libraries, build scripts, etc. (see Einführung).  Assuming deterministic build processes, one store file name should map to exactly one build output.  guix challenge checks whether there is, indeed, a single mapping by comparing the build outputs of several independent builds of any given store item.

The command output looks like this:

     $ guix challenge --substitute-urls="https://ci.guix.de.info https://guix.example.org"
     updating list of substitutes from 'https://ci.guix.de.info'... 100.0%
     updating list of substitutes from 'https://guix.example.org'... 100.0%
     /gnu/store/...-openssl-1.0.2d contents differ:
       local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
       https://ci.guix.de.info/nar/...-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q
       https://guix.example.org/nar/...-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim
     /gnu/store/...-git-2.5.0 contents differ:
       local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha
       https://ci.guix.de.info/nar/...-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f
       https://guix.example.org/nar/...-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73
     /gnu/store/...-pius-2.1.1 contents differ:
       local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
       https://ci.guix.de.info/nar/...-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax
       https://guix.example.org/nar/...-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs

     ...

     6,406 store items were analyzed:
       - 4,749 (74.1%) were identical
       - 525 (8.2%) differed
       - 1,132 (17.7%) were inconclusive

In this example, guix challenge first scans the store to determine the set of locally-built derivations---as opposed to store items that were downloaded from a substitute server---and then queries all the substitute servers.  It then reports those store items for which the servers obtained a result different from the local build.

As an example, guix.example.org always gets a different answer. Conversely, ci.guix.de.info agrees with local builds, except in the case of Git.  This might indicate that the build process of Git is non-deterministic, meaning that its output varies as a function of various things that Guix does not fully control, in spite of building packages in isolated environments (see Funktionalitäten).  Most common sources of non-determinism include the addition of timestamps in build results, the inclusion of random numbers, and directory listings sorted by inode number. See https://reproducible-builds.org/docs/, for more information.

To find out what is wrong with this Git binary, we can do something along these lines (see Aufruf von guix archive):

     $ wget -q -O - https://ci.guix.de.info/nar/...-git-2.5.0 \
        | guix archive -x /tmp/git
     $ diff -ur --no-dereference /gnu/store/...-git.2.5.0 /tmp/git

This command shows the difference between the files resulting from the local build, and the files resulting from the build on ci.guix.de.info (see Comparing and Merging Files).  The diff command works great for text files.  When binary files differ, a better option is Diffoscope (https://diffoscope.org/), a tool that helps visualize differences for all kinds of files.

Once you have done that work, you can tell whether the differences are due to a non-deterministic build process or to a malicious server.  We try hard to remove sources of non-determinism in packages to make it easier to verify substitutes, but of course, this is a process that involves not just Guix, but a large part of the free software community.  In the meantime, guix challenge is one tool to help address the problem.

If you are writing packages for Guix, you are encouraged to check whether ci.guix.de.info and other substitute servers obtain the same build result as you did with:

     $ guix challenge PACKAGE

where PACKAGE is a package specification such as guile@2.0 or glibc:debug.

Die allgemeine Syntax lautet:

     guix challenge OPTIONS [PACKAGES...]

When a difference is found between the hash of a locally-built item and that of a server-provided substitute, or among substitutes provided by different servers, the command displays it as in the example above and its exit code is 2 (other non-zero exit codes denote other kinds of errors.)

The one option that matters is:

--substitute-urls=URLS
     Consider URLS the whitespace-separated list of substitute source URLs to compare to.

--verbose
-v
     Show details about matches (identical contents) in addition to information about mismatches.

Invoking guix copy
==================

The guix copy command copies items from the store of one machine to that of another machine over a secure shell (SSH) connection (This command is available only when Guile-SSH was found.  See Voraussetzungen, for details.).  For example, the following command copies the coreutils package, the user's profile, and all their dependencies over to HOST, logged in as USER:

     guix copy --to=USER@HOST \
               coreutils `readlink -f ~/.guix-profile`

If some of the items to be copied are already present on HOST, they are not actually sent.

The command below retrieves libreoffice and gimp from HOST, assuming they are available there:

     guix copy --from=HOST libreoffice gimp

The SSH connection is established using the Guile-SSH client, which is compatible with OpenSSH: it honors ~/.ssh/known_hosts and ~/.ssh/config, and uses the SSH agent for authentication.

The key used to sign items that are sent must be accepted by the remote machine.  Likewise, the key used by the remote machine to sign items you are retrieving must be in /etc/guix/acl so it is accepted by your own daemon.  See Aufruf von guix archive, for more information about store item authentication.

Die allgemeine Syntax lautet:

     guix copy [--to=SPEC|--from=SPEC] ITEMS...

You must always specify one of the following options:

--to=SPEC
--from=SPEC
     Specify the host to send to or receive from.  SPEC must be an SSH spec such as example.org, charlie@example.org, or charlie@example.org:2222.

The ITEMS can be either package names, such as gimp, or store items, such as /gnu/store/...-idutils-4.6.

When specifying the name of a package to send, it is first built if needed, unless --dry-run was specified.  Common build options are supported (see Gemeinsame Erstellungsoptionen).

Invoking guix container
=======================

     As of version VERSION, this tool is experimental.  The interface is subject to radical change in the future.

The purpose of guix container is to manipulate processes running within an isolated environment, commonly known as a ``container'', typically created by the guix environment (see Aufruf von guix environment) and guix system container (see Aufruf von guix system) commands.

Die allgemeine Syntax lautet:

     guix container ACTION OPTIONS...

ACTION specifies the operation to perform with a container, and OPTIONS specifies the context-specific arguments for the action.

The following actions are available:

exec
     Execute a command within the context of a running container.

     The syntax is:

          guix container exec PID PROGRAM ARGUMENTS...

     PID specifies the process ID of the running container.  PROGRAM specifies an executable file name within the root file system of the container.  ARGUMENTS are the additional options that will be passed to PROGRAM.

     The following command launches an interactive login shell inside a Guix system container, started by guix system container, and whose process ID is 9001:

          guix container exec 9001 /run/current-system/profile/bin/bash --login

     Note that the PID cannot be the parent process of a container.  It must be PID 1 of the container or one of its child processes.

Invoking guix weather
=====================

Occasionally you're grumpy because substitutes are lacking and you end up building packages by yourself (see Substitute).  The guix weather command reports on substitute availability on the specified servers so you can have an idea of whether you'll be grumpy today.  It can sometimes be useful info as a user, but it is primarily useful to people running guix publish (see Aufruf von guix publish).

Here's a sample run:

     $ guix weather --substitute-urls=https://guix.example.org
     computing 5,872 package derivations for x86_64-linux...
     looking for 6,128 store items on https://guix.example.org..
     updating list of substitutes from 'https://guix.example.org'... 100.0%
     https://guix.example.org
       43.4% substitutes available (2,658 out of 6,128)
       7,032.5 MiB of nars (compressed)
       19,824.2 MiB on disk (uncompressed)
       0.030 seconds per request (182.9 seconds in total)
       33.5 requests per second

       9.8% (342 out of 3,470) of the missing items are queued
       867 queued builds
           x86_64-linux: 518 (59.7%)
           i686-linux: 221 (25.5%)
           aarch64-linux: 128 (14.8%)
       build rate: 23.41 builds per hour
           x86_64-linux: 11.16 builds per hour
           i686-linux: 6.03 builds per hour
           aarch64-linux: 6.41 builds per hour

As you can see, it reports the fraction of all the packages for which substitutes are available on the server---regardless of whether substitutes are enabled, and regardless of whether this server's signing key is authorized.  It also reports the size of the compressed archives (``nars'') provided by the server, the size the corresponding store items occupy in the store (assuming deduplication is turned off), and the server's throughput. The second part gives continuous integration (CI) statistics, if the server supports it.  In addition, using the --coverage option, guix weather can list ``important'' package substitutes missing on the server (see below).

To achieve that, guix weather queries over HTTP(S) meta-data (narinfos) for all the relevant store items.  Like guix challenge, it ignores signatures on those substitutes, which is innocuous since the command only gathers statistics and cannot install those substitutes.

Among other things, it is possible to query specific system types and specific package sets.  The available options are listed below.

--substitute-urls=URLS
     URLS is the space-separated list of substitute server URLs to query. When this option is omitted, the default set of substitute servers is queried.

--system=SYSTEM
-s SYSTEM
     Query substitutes for SYSTEM---e.g., aarch64-linux.  This option can be repeated, in which case guix weather will query substitutes for several system types.

--manifest=DATEI
     Instead of querying substitutes for all the packages, only ask for those specified in FILE.  FILE must contain a manifest, as with the -m option of guix package (see Aufruf von guix package).

--coverage[=COUNT]
-c [COUNT]
     Report on substitute coverage for packages: list packages with at least COUNT dependents (zero by default) for which substitutes are unavailable.  Dependent packages themselves are not listed: if B depends on A and A has no substitutes, only A is listed, even though B usually lacks substitutes as well.  The result looks like this:

          $ guix weather --substitute-urls=https://ci.guix.de.info -c 10
          computing 8,983 package derivations for x86_64-linux...
          looking for 9,343 store items on https://ci.guix.de.info...
          updating substitutes from 'https://ci.guix.de.info'... 100.0%
          https://ci.guix.de.info
            64.7% substitutes available (6,047 out of 9,343)
          ...
          2502 packages are missing from 'https://ci.guix.de.info' for 'x86_64-linux', among which:
              58  kcoreaddons@5.49.0      /gnu/store/...-kcoreaddons-5.49.0
              46  qgpgme@1.11.1           /gnu/store/...-qgpgme-1.11.1
              37  perl-http-cookiejar@0.008  /gnu/store/...-perl-http-cookiejar-0.008
              ...

     What this example shows is that kcoreaddons and presumably the 58 packages that depend on it have no substitutes at ci.guix.de.info; likewise for qgpgme and the 46 packages that depend on it.

     If you are a Guix developer, or if you are taking care of this build farm, you'll probably want to have a closer look at these packages: they may simply fail to build.

guix processes aufrufen
=======================

The guix processes command can be useful to developers and system administrators, especially on multi-user machines and on build farms: it lists the current sessions (connections to the daemon), as well as information about the processes involved (Remote sessions, when guix-daemon is started with --listen specifying a TCP endpoint, are not listed.).  Here's an example of the information it returns:

     $ sudo guix processes
     SessionPID: 19002
     ClientPID: 19090
     ClientCommand: guix environment --ad-hoc python

     SessionPID: 19402
     ClientPID: 19367
     ClientCommand: guix publish -u guix-publish -p 3000 -C 9 ...

     SessionPID: 19444
     ClientPID: 19419
     ClientCommand: cuirass --cache-directory /var/cache/cuirass ...
     LockHeld: /gnu/store/...-perl-ipc-cmd-0.96.lock
     LockHeld: /gnu/store/...-python-six-bootstrap-1.11.0.lock
     LockHeld: /gnu/store/...-libjpeg-turbo-2.0.0.lock
     ChildProcess: 20495: guix offload x86_64-linux 7200 1 28800
     ChildProcess: 27733: guix offload x86_64-linux 7200 1 28800
     ChildProcess: 27793: guix offload x86_64-linux 7200 1 28800

In this example we see that guix-daemon has three clients: guix environment, guix publish, and the Cuirass continuous integration tool; their process identifier (PID) is given by the ClientPID field.  The SessionPID field gives the PID of the guix-daemon sub-process of this particular session.

The LockHeld fields show which store items are currently locked by this session, which corresponds to store items being built or substituted (the LockHeld field is not displayed when guix processes is not running as root.)  Last, by looking at the ChildProcess field, we understand that these three builds are being offloaded (see Auslagern des Daemons einrichten).

The output is in Recutils format so we can use the handy recsel command to select sessions of interest (see Selection Expressions (GNU recutils manual)).  As an example, the command shows the command line and PID of the client that triggered the build of a Perl package:

     $ sudo guix processes | \
         recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"'
     ClientPID: 19419
     ClientCommand: cuirass --cache-directory /var/cache/cuirass ...

Systemkonfiguration
*******************

Die Guix-Systemdistribution unterstützt einen Mechanismus zur konsistenten Konfiguration des gesamten Systems. Damit meinen wir, dass alle Aspekte der globalen Systemkonfiguration an einem Ort stehen, d.h. die zur Verfügung gestellten Systemdienste, die Zeitzone und Einstellungen zur Locale (also die Anpassung an regionale Gepflogenheiten und Sprachen) sowie Benutzerkonten. Sie alle werden an derselben Stelle deklariert. So eine Systemkonfiguration kann instanziiert, also umgesetzt, werden.

Einer der Vorteile, die ganze Systemkonfiguration unter die Kontrolle von Guix zu stellen, ist, dass so transaktionelle Systemaktualisierungen möglich werden und dass diese rückgängig gemacht werden können, wenn das aktualisierte System nicht richtig funktioniert (see Funktionalitäten). Ein anderer Vorteil ist, dass dieselbe Systemkonfiguration leicht auf einer anderen Maschine oder zu einem späteren Zeitpunkt benutzt werden kann, ohne dazu eine weitere Schicht administrativer Werkzeuge über den systemeigenen Werkzeugen einsetzen zu müssen.

In diesem Abschnitt wird dieser Mechanismus beschrieben. Zunächst betrachten wir ihn aus der Perspektive eines Administrators. Dabei wird erklärt, wie das System konfiguriert und instanziiert werden kann. Dann folgt eine Demonstration, wie der Mechanismus erweitert werden kann, etwa um neue Systemdienste zu unterstützen.

Das Konfigurationssystem nutzen
===============================

Das Betriebssystem können Sie konfigurieren, indem Sie eine operating-system-Deklaration in einer Datei speichern, die Sie dann dem Befehl guix system übergeben (see Aufruf von guix system). Eine einfache Konfiguration mit den vorgegebenen Systemdiensten und dem vorgegebenen Linux-Libre als Kernel und mit einer initialen RAM-Disk und einem Bootloader, sieht so aus:

          [file os-config-bare-bones.texi not included]

Dieses Beispiel sollte selbsterklärend sein. Manche der Felder oben, wie etwa host-name und bootloader, müssen angegeben werden. Andere sind optional, wie etwa packages und services, sind optional; werden sie nicht angegeben, nehmen sie einen Vorgabewert an.

Im Folgenden werden die Effekte von einigen der wichtigsten Feldern erläutert (see »operating-system«-Referenz, für Details zu allen verfügbaren Feldern), dann wird beschrieben, wie man das Betriebssystem mit guix system instanziieren kann.

Bootloader
----------

Das bootloader-Feld beschreibt, mit welcher Methode Ihr System »gebootet« werden soll. Maschinen, die auf Intel-Prozessoren basieren, können im alten »Legacy«-BIOS-Modus gebootet werden, wie es im obigen Beispiel der Fall wäre. Neuere Maschinen benutzen stattdessen das Unified Extensible Firmware Interface (UEFI) zum Booten. In diesem Fall sollte das bootloader-Feld in etwa so aussehen:

     (bootloader-configuration
       (bootloader grub-efi-bootloader)
       (target "/boot/efi"))

Siehe den Abschnitt see Bootloader-Konfiguration für weitere Informationen zu den verfügbaren Konfigurationsoptionen.

global sichtbare Pakete
-----------------------

Im Feld packages werden Pakete aufgeführt, die auf dem System für alle Benutzerkonten global sichtbar sein sollen, d.h. in der PATH-Umgebungsvariablen jedes Nutzers, zusätzlich zu den nutzereigenen Profilen (see Aufruf von guix package). Die Variable %BASE-PACKAGES bietet alle Werkzeuge, die man für grundlegende Nutzer- und Administratortätigkeiten erwarten würde, einschließlich der GNU Core Utilities, der GNU Networking Utilities, des leichtgewichtigen Texteditors GNU Zile, find, grep und so weiter. Obiges Beispiel fügt zu diesen noch das Programm GNU Screen hinzu, welches aus dem Modul (gnu packages screen) genommen wird (see Paketmodule). Die Syntax (list package output) kann benutzt werden, um eine bestimmte Ausgabe eines Pakets auszuwählen:

     (use-modules (gnu packages))
     (use-modules (gnu packages dns))

     (operating-system
       ;; ...
       (packages (cons (list bind "utils")
                       %base-packages)))

Sich auf Pakete anhand ihres Variablennamens zu beziehen, wie oben bei bind, hat den Vorteil, dass der Name eindeutig ist; Tippfehler werden direkt als »unbound variables« gemeldet. Der Nachteil ist, dass man wissen muss, in welchem Modul ein Paket definiert wird, um die Zeile mit use-package-modules entsprechend zu ergänzen. Um dies zu vermeiden, kann man auch die Prozedur specification->package aus dem Modul (gnu packages) aufrufen, welche das einem angegebenen Namen oder Name-Versions-Paar zu Grunde liegende Paket liefert:

     (use-modules (gnu packages))

     (operating-system
       ;; ...
       (packages (append (map specification->package
                              '("tcpdump" "htop" "gnupg@2.0"))
                         %base-packages)))

Systemdienste
-------------

The services field lists system services to be made available when the system starts (see Dienste).  The operating-system declaration above specifies that, in addition to the basic services, we want the OpenSSH secure shell daemon listening on port 2222 (see openssh-service-type).  Under the hood, openssh-service-type arranges so that sshd is started with the right command-line options, possibly with supporting configuration files generated as needed (see Dienste definieren).

Gelegentlich werden Sie die Basis-Dienste nicht einfach so, wie sie sind, benutzen, sondern anpassen wollen. Benutzen Sie modify-services (see modify-services), um die Liste der Basis-Dienste zu modifizieren.

Wenn Sie zum Beispiel guix-daemon und Mingetty (das Programm, womit Sie sich auf der Konsole anmelden) in der %BASE-SERVICES-Liste modifizieren möchten (see %base-services), schreiben Sie das Folgende in Ihre Betriebssystemdeklaration:

     (define %my-services
       ;; Meine ganz eigene Liste von Diensten.
       (modify-services %base-services
         (guix-service-type config =>
                            (guix-configuration
                             (inherit config)
                             (use-substitutes? #f)
                             (extra-options '("--gc-keep-derivations"))))
         (mingetty-service-type config =>
                                (mingetty-configuration
                                 (inherit config)))))

     (operating-system
       ;; ...
       (services %my-services))

Dadurch ändert sich die Konfiguration — d.h. die Dienst-Parameter — der guix-service-type-Instanz und die aller mingetty-service-type-Instanzen in der %BASE-SERVICES-Liste. Das funktioniert so: Zunächst arrangieren wir, dass die ursprüngliche Konfiguration an den Bezeichner config im RUMPF gebunden wird, dann schreiben wir den RUMPF, damit er zur gewünschten Konfiguration ausgewertet wird. Beachten Sie insbesondere, wie wir mit inherit eine neue Konfiguration erzeugen, die dieselben Werte wie die alte Konfiguration hat, aber mit ein paar Modifikationen.

Die Konfiguration für typische »Schreibtisch«-Nutzung zum Arbeiten, mit einer verschlüsselten Partition für das Wurzeldateisystem, einem X11-Display-Server, GNOME und Xfce (Benutzer können im Anmeldebildschirm auswählen, welche dieser Arbeitsumgebungen sie möchten, indem sie die Taste F1 drücken), Netzwerkverwaltung, Verwaltungswerkzeugen für den Energieverbrauch, und Weiteres, würde so aussehen:

          [file os-config-desktop.texi not included]

Ein grafisches System mit einer Auswahl an leichtgewichtigen Fenster-Managern statt voll ausgestatteten Arbeitsumgebungen würde so aussehen:

          [file os-config-lightweight-desktop.texi not included]

Dieses Beispiel bezieht sich auf das Dateisystem hinter /boot/efi über dessen UUID, 1234-ABCD. Schreiben Sie statt dieser UUID die richtige UUID für Ihr System, wie sie der Befehl blkid liefert.

Im Abschnitt see Desktop-Dienste finden Sie eine genaue Liste der unter %DESKTOP-SERVICES angebotenen Dienste. Der Abschnitt see X.509-Zertifikate hat Hintergrundinformationen über das nss-certs-Paket, das hier benutzt wird.

Beachten Sie, dass %DESKTOP-SERVICES nur eine Liste von die Dienste repräsentierenden service-Objekten ist. Wenn Sie Dienste daraus entfernen möchten, können Sie dazu die Prozeduren zum Filtern von Listen benutzen (see SRFI-1 Filtering and Partitioning (GNU Guile Reference Manual)). Beispielsweise liefert der folgende Ausdruck eine Liste mit allen Diensten von %DESKTOP-SERVICES außer dem Avahi-Dienst.

     (remove (lambda (service)
               (eq? (service-kind service) avahi-service-type))
             %desktop-services)

Das System instanziieren
------------------------

Angenommen, Sie haben die operating-system-Deklaration in einer Datei my-system-config.scm gespeichert, dann instanziiert der Befehl guix system reconfigure my-system-config.scm diese Konfiguration und macht sie zum voreingestellten GRUB-Boot-Eintrag (see Aufruf von guix system).

Der normale Weg, die Systemkonfiguration nachträglich zu ändern, ist, die Datei zu aktualisieren und guix system reconfigure erneut auszuführen. Man sollte nie die Dateien in /etc bearbeiten oder den Systemzustand mit Befehlen wie useradd oder grub-install verändern. Tatsächlich müssen Sie das ausdrücklich vermeiden, sonst verfällt nicht nur Ihre Garantie, sondern Sie können Ihr System auch nicht mehr auf eine alte Version des Systems zurücksetzen, falls das jemals notwendig wird.

Zurücksetzen bezieht sich hierbei darauf, dass jedes Mal, wenn Sie guix system reconfigure ausführen, eine neue Generation des Systems erzeugt wird — ohne vorherige Generationen zu verändern. Alte Systemgenerationen bekommen einen Eintrag im Boot-Menü des Bootloaders, womit Sie alte Generationen beim Booten des Rechners auswählen können, wenn mit der neuesten Generation etwas nicht stimmt. Eine beruhigende Vorstellung, oder? Der Befehl guix system list-generations führt die auf der Platte verfügbaren Systemgenerationen auf. Es ist auch möglich, das System mit den Befehlen guix system roll-back und guix system switch-generation zurückzusetzen.

Obwohl der Befehl guix system reconfigure vorherige Generationen nicht verändern wird, müssen Sie Acht geben, dass wenn die momentan aktuelle Generation nicht die neueste ist (z.B. nach einem Aufruf von guix system roll-back), weil guix system reconfigure alle neueren Generationen überschreibt (see Aufruf von guix system).

Die Programmierschnittstelle
----------------------------

Auf der Ebene von Scheme wird der Großteil der operating-system-Deklaration mit der folgenden monadischen Prozedur instanziiert (see Die Store-Monade):

 -- Monadische Prozedur: operating-system-derivation os
     Liefert eine Ableitung, mit der ein operating-system-Objekt OS erstellt wird (see Ableitungen).

     Die Ausgabe der Ableitung ist ein einzelnes Verzeichnis mit Verweisen auf alle Pakete, Konfigurationsdateien und andere unterstützenden Dateien, die nötig sind, um OS zu instanziieren.

This procedure is provided by the (gnu system) module.  Along with (gnu services) (see Dienste), this module contains the guts of Guix System.  Make sure to visit it!

operating-system-Referenz
=========================

Dieser Abschnitt fasst alle Optionen zusammen, die für operating-system-Deklarationen zur Verfügung stehen (see Das Konfigurationssystem nutzen).

 -- Datentyp: operating-system
     Der die Betriebssystemkonfiguration repräsentierende Datentyp. Damit meinen wir die globale Konfiguration des Systems und nicht die, die sich nur auf einzelne Nutzer bezieht (see Das Konfigurationssystem nutzen).

     kernel (Vorgabe: LINUX-LIBRE)
          Das Paket für den zu nutzenden Betriebssystem-Kernel als »package«-Objekt (Derzeit wird nur der Kernel Linux-libre unterstützt. In der Zukunft wird man auch GNU Hurd benutzen können.).

     kernel-arguments (Vorgabe: '())
          Eine Liste aus Zeichenketten oder G-Ausdrücken, die für zusätzliche Argumente an den Kernel stehen, die ihm auf seiner Befehlszeile übergeben werden — wie z.B. ("console=ttyS0").

     bootloader
          Das Konfigurationsobjekt für den Bootloader, mit dem das System gestartet wird. Siehe Bootloader-Konfiguration.

     initrd-modules (Vorgabe: %base-initrd-modules)
          Die Liste der Linux-Kernel-Module, die in der initialen RAM-Disk zur Verfügung stehen sollen see Initiale RAM-Disk.

     initrd (Vorgabe: base-initrd)
          Eine Prozedur, die eine initiale RAM-Disk für den Linux-Kernel liefert. Dieses Feld gibt es, damit auch sehr systemnahe Anpassungen vorgenommen werden können, aber für die normale Nutzung sollte man es kaum brauchen. Siehe Initiale RAM-Disk.

     firmware (Vorgabe: %BASE-FIRMWARE)
          Eine Liste der Firmware-Pakete, die vom Betriebssystem-Kernel geladen werden können.

          Vorgegeben ist, dass für Atheros- und Broadcom-basierte WLAN-Geräte nötige Firmware geladen werden kann (genauer jeweils die Linux-libre-Module ath9k und b43-open). Siehe den Abschnitt see Hardware-Überlegungen, für mehr Informationen zu unterstützter Hardware.

     host-name
          Der Hostname

     hosts-file
          Ein dateiartiges Objekt (see file-like objects), das für /etc/hosts benutzt werden soll (see Host Names (The GNU C Library Reference Manual)). Der Vorgabewert ist eine Datei mit Einträgen für localhost und HOST-NAME.

     mapped-devices (Vorgabe: '())
          Eine Liste zugeordneter Geräte (»mapped devices«). Siehe Zugeordnete Geräte.

     file-systems
          Eine Liste von Dateisystemen. Siehe Dateisysteme.

     swap-devices (Vorgabe: '())
          Eine Liste von Zeichenketten, die Geräte identifizieren oder als »Swap-Speicher« genutzte Dateien identifizieren (see Memory Concepts (The GNU C Library Reference Manual)). Beispiele wären etwa '("/dev/sda3") oder '("/swapdatei"). Es ist möglich, eine Swap-Datei auf dem Dateisystem eines zugeordneten Geräts anzugeben, sofern auch die Gerätezuordnung und das Dateisystem mit angegeben werden. Siehe Zugeordnete Geräte und Dateisysteme.

     users (Vorgabe: %base-user-accounts)
     groups (Vorgabe: %BASE-GROUPS)
          Liste der Benutzerkonten und Benutzergruppen. Siehe Benutzerkonten.

          Wenn in der users-Liste kein Benutzerkonto mit der UID-Kennung 0 aufgeführt wird, wird automatisch für den Administrator ein »root«-Benutzerkonto mit UID-Kennung 0 hinzugefügt.

     skeletons (Vorgabe: (default-skeletons))
          Eine Liste von Tupeln aus je einem Ziel-Dateinamen und einem dateiähnlichen Objekt (see file-like objects). Diese Objekte werden als Skeleton-Dateien im Persönlichen Verzeichnis (»Home«-Verzeichnis) jedes neuen Benutzerkontos angelegt.

          Ein gültiger Wert könnte zum Beispiel so aussehen:

               `((".bashrc" ,(plain-file "bashrc" "echo Hallo\n"))
                 (".guile" ,(plain-file "guile"
                                        "(use-modules (ice-9 readline))
                                         (activate-readline)")))

     issue (Vorgabe: %DEFAULT-ISSUE)
          Eine Zeichenkette, die als Inhalt der Datei /etc/issue verwendet werden soll, der jedes Mal angezeigt wird, wenn sich ein Nutzer auf einer Textkonsole anmeldet.

     packages (Vorgabe: %BASE-PACKAGES)
          Die Menge der Pakete, die ins globale Profil installiert werden sollen, welches unter /run/current-system/profile zu finden ist.

          Die vorgegebene Paketmenge umfasst zum Kern des Systems gehörende Werkzeuge (»core utilities«). Es ist empfehlenswert, nicht zum Kern gehörende Werkzeuge (»non-core«) stattdessen in Nutzerprofile zu installieren (see Aufruf von guix package).

     timezone
          Eine Zeichenkette, die die Zeitzone bezeichnet, wie z.B. "Europe/Berlin".

          Mit dem Befehl tzselect können Sie herausfinden, welche Zeichenkette der Zeitzone Ihrer Region entspricht. Wenn Sie eine ungültige Zeichenkette angeben, schlägt guix system fehl.

     locale (Vorgabe: "en_US.utf8")
          Der Name der als Voreinstellung zu verwendenden Locale (see Locale Names (The GNU C Library Reference Manual)). Siehe Locales für weitere Informationen.

     locale-definitions (Vorgabe: %DEFAULT-LOCALE-DEFINITIONS)
          Die Liste der Locale-Definitionen, die kompiliert werden sollen und dann im laufenden System benutzt werden können. Siehe Locales.

     locale-libcs (Vorgabe: (list GLIBC))
          Die Liste der GNU-libc-Pakete, deren Locale-Daten und -Werkzeuge zum Erzeugen der Locale-Definitionen verwendet werden sollen. Siehe Locales für eine Erläuterung der Kompatibilitätsauswirkungen, deretwegen man diese Option benutzen wollen könnte.

     name-service-switch (Vorgabe: %DEFAULT-NSS)
          Die Konfiguration des Name Service Switch (NSS) der libc — ein <name-service-switch>-Objekt. Siehe Name Service Switch, für Details.

     services (Vorgabe: %BASE-SERVICES)
          Eine Liste von »service«-Objekten, die die Systemdienste repräsentieren. Siehe Dienste.

     pam-services (Vorgabe: (base-pam-services))
          Dienste für »Pluggable Authentication Modules« (PAM) von Linux.

     setuid-programs (Vorgabe: %SETUID-PROGRAMS)
          Eine Liste von Zeichenketten liefernden G-Ausdrücken, die setuid-Programme bezeichnen. Siehe Setuid-Programme.

     sudoers-file (Vorgabe: %SUDOERS-SPECIFICATION)
          Der Inhalt der Datei /etc/sudoers als ein dateiähnliches Objekt (see local-file und plain-file).

          Diese Datei gibt an, welche Nutzer den Befehl sudo benutzen dürfen, was sie damit tun und welche Berechtigungen sie so erhalten können. Die Vorgabe ist, dass nur der Administratornutzer root und Mitglieder der Benutzergruppe wheel den sudo-Befehl verwenden dürfen.

Dateisysteme
============

Die Liste der Dateisysteme, die eingebunden werden sollen, steht im file-systems-Feld der Betriebssystemdeklaration (see Das Konfigurationssystem nutzen). Jedes Dateisystem wird mit der file-system-Form deklariert, etwa so:

     (file-system
       (mount-point "/home")
       (device "/dev/sda3")
       (type "ext4"))

Wie immer müssen manche Felder angegeben werden — die, die im Beispiel oben stehen —, während andere optional sind. Die Felder werden nun beschrieben.

 -- Datentyp: file-system
     Objekte dieses Typs repräsentieren einzubindende Dateisysteme. Sie weisen folgende Komponenten auf:

     type
          Eine Zeichenkette, die den Typ des Dateisystems spezifiziert, z.B. "ext4".

     mount-point
          Der Einhängepunkt, d.h. der Pfad, an dem das Dateisystem eingebunden werden soll.

     device
          Hiermit wird die »Quelle« des Dateisystems bezeichnet. Sie kann eines von drei Dingen sein: die Bezeichnung (»Labels«) eines Dateisystems, die UUID-Kennung des Dateisystems oder der Name eines /dev-Knotens. Mit Bezeichnungen und UUIDs kann man Dateisysteme benennen, ohne den Gerätenamen festzuschreiben (Beachten Sie: Obwohl es verführerisch ist, mit /dev/disk/by-uuid und ähnlichen Gerätenamen dasselbe Resultat bekommen zu wollen, raten wir davon ab: Diese speziellen Gerätenamen werden erst vom udev-Daemon erzeugt und sind, wenn die Geräte eingebunden werden, vielleicht noch nicht verfügbar.).

          Dateisystem-Bezeichnungen (»Labels«) werden mit der Prozedur file-system-label erzeugt und UUID-Kennungen werden mit uuid erzeugt, während Knoten in /dev mit ihrem Pfad als einfache Zeichenketten aufgeführt werden. Hier ist ein Beispiel, wie wir ein Dateisystem anhand seiner Bezeichnung aufführen, wie sie vom Befehl e2label angezeigt wird:

               (file-system
                 (mount-point "/home")
                 (type "ext4")
                 (device (file-system-label "my-home")))

          UUID-Kennungen werden mit der uuid-Form von ihrer Darstellung als Zeichenkette (wie sie vom Befehl tune2fs -l angezeigt wird) konvertiert (Die uuid-Form nimmt 16-Byte-UUIDs entgegen, wie sie in RFC 4122 (https://tools.ietf.org/html/rfc4122) definiert sind. Diese Form der UUID wird unter Anderem von der ext2-Familie von Dateisystemen verwendet, sie unterscheidet sich jedoch zum Beispiel von den »UUID« genannten Kennungen, wie man sie bei FAT-Dateisystemen findet.) wie hier:

               (file-system
                 (mount-point "/home")
                 (type "ext4")
                 (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")))

          Wenn die Quelle eines Dateisystems ein zugeordnetes Gerät (see Zugeordnete Geräte) ist, muss sich das device-Feld auf den zugeordneten Gerätenamen beziehen — z.B. "/dev/mapper/root-partition". Das ist nötig, damit das System weiß, dass das Einbinden des Dateisystems davon abhängt, die entsprechende Gerätezuordnung hergestellt zu haben.

     flags (Vorgabe: '())
          Eine Liste von Symbolen, die Einbinde-Flags (»mount flags«) bezeichnen. Erkannt werden unter Anderem read-only, bind-mount, no-dev (Zugang zu besonderen Dateien verweigern), no-suid (setuid- und setgid-Bits ignorieren) und no-exec (Programmausführungen verweigern).

     options (Vorgabe: #f)
          Entweder #f oder eine Zeichenkette mit Einbinde-Optionen (»mount options«).

     mount? (Vorgabe: #t)
          Dieser Wert zeigt an, ob das Dateisystem automatisch eingebunden werden soll, wenn das System gestartet wird. Ist der Wert #f, dann erhält das Dateisystem nur einen Eintrag in der Datei /etc/fstab (welche vom mount-Befehl zum Einbinden gelesen wird), es wird aber nicht automatisch eingebunden.

     needed-for-boot? (Vorgabe: #f)
          Dieser boolesche Wert gibt an, ob das Dateisystem zum Hochfahren des Systems notwendig ist. In diesem Fall wird das Dateisystem eingebunden, wenn die initiale RAM-Disk (initrd) geladen wird. Für zum Beispiel das Wurzeldateisystem ist dies ohnehin immer der Fall.

     check? (Vorgabe: #t)
          Dieser boolesche Wert sagt aus, ob das Dateisystem vor dem Einbinden auf Fehler hin geprüft werden soll.

     create-mount-point? (Vorgabe: #f)
          Steht dies auf wahr, wird der Einhängepunkt vor dem Einbinden erstellt, wenn er noch nicht existiert.

     dependencies (Vorgabe: '())
          Dies ist eine Liste von <file-system>- oder <mapped-device>-Objekten, die Dateisysteme repräsentieren, die vor diesem Dateisystem eingebunden oder zugeordnet werden müssen (und nach diesem ausgehängt oder geschlossen werden müssen).

          Betrachten Sie zum Beispiel eine Hierarchie von Einbindungen: /sys/fs/cgroup ist eine Abhängigkeit von /sys/fs/cgroup/cpu und /sys/fs/cgroup/memory.

          Ein weiteres Beispiel ist ein Dateisystem, was von einem zugeordneten Gerät abhängt, zum Beispiel zur Verschlüsselung einer Partition (see Zugeordnete Geräte).

Das Modul (gnu system file-systems) exportiert die folgenden nützlichen Variablen.

 -- Scheme-Variable: %base-file-systems
     Hiermit werden essenzielle Dateisysteme bezeichnet, die für normale Systeme unverzichtbar sind, wie zum Beispiel %PSEUDO-TERMINAL-FILE-SYSTEM und %IMMUTABLE-STORE (siehe unten). Betriebssystemdeklaration sollten auf jeden Fall mindestens diese enthalten.

 -- Scheme-Variable: %pseudo-terminal-file-system
     Das als /dev/pts einzubindende Dateisystem. Es unterstützt über openpty und ähnliche Funktionen erstellte Pseudo-Terminals (see Pseudo-Terminals (The GNU C Library Reference Manual)). Pseudo-Terminals werden von Terminal-Emulatoren wie xterm benutzt.

 -- Scheme-Variable: %shared-memory-file-system
     Dieses Dateisystem wird als /dev/shm eingebunden, um Speicher zwischen Prozessen teilen zu können (see shm_open (The GNU C Library Reference Manual)).

 -- Scheme-Variable: %immutable-store
     Dieses Dateisystem vollzieht einen »bind mount« des /gnu/store, um ihn für alle Nutzer einschließlich des Administratornutzers root nur lesbar zu machen, d.h. Schreibrechte zu entziehen. Dadurch kann als root ausgeführte Software, oder der Systemadministrator, nicht aus Versehen den Store modifizieren.

     Der Daemon kann weiterhin in den Store schreiben, indem er ihn selbst mit Schreibrechten in seinem eigenen »Namensraum« einbindet.

 -- Scheme-Variable: %binary-format-file-system
     Das binfmt_misc-Dateisystem, durch das beliebige Dateitypen als ausführbare Dateien auf der Anwendungsebene (dem User Space) zugänglich gemacht werden können. Es setzt voraus, dass das Kernel-Modul binfmt.ko geladen wurde.

 -- Scheme-Variable: %fuse-control-file-system
     Das fusectl-Dateisystem, womit »unprivilegierte« Nutzer ohne besondere Berechtigungen im User Space FUSE-Dateisysteme einbinden und aushängen können. Dazu muss das Kernel-Modul fuse.ko geladen sein.

Zugeordnete Geräte
==================

Der Linux-Kernel unterstützt das Konzept der Gerätezuordnung: Ein blockorientiertes Gerät wie eine Festplattenpartition kann einem neuen Gerät zugeordnet werden, gewöhnlich unter /dev/mapper/, wobei das neue Gerät durchlaufende Daten zusätzlicher Verarbeitung unterzogen werden (Beachten Sie, dass mit GNU Hurd kein Unterschied zwischen dem Konzept eines »zugeordneten Geräts« und dem eines Dateisystems besteht: Dort werden bei beiden Ein- und Ausgabeoperationen auf eine Datei in Operationen auf dessen Hintergrundspeicher übersetzt. Hurd implementiert zugeordnete Geräte genau wie Dateisysteme mit dem generischen Übersetzer-Mechanismus (see Translators (The GNU Hurd Reference Manual)).). Ein typisches Beispiel ist eine Gerätezuordnung zur Verschlüsselung: Jeder Schreibzugriff auf das zugeordnete Gerät wird transparent verschlüsselt und jeder Lesezugriff ebenso entschlüsselt. Guix erweitert dieses Konzept, indem es darunter jedes Gerät und jede Menge von Geräten versteht, die auf irgendeine Weise umgewandelt wird, um ein neues Gerät zu bilden; zum Beispiel entstehen auch RAID-Geräte aus einem Verbund mehrerer anderer Geräte, wie etwa Festplatten oder Partition zu einem einzelnen Gerät, das sich wie eine Partition verhält. Ein weiteres Beispiel, das noch nicht in Guix implementiert wurde, sind »LVM logical volumes«.

Zugeordnete Geräte werden mittels einer mapped-device-Form deklariert, die wie folgt definiert ist; Beispiele folgen weiter unten.

 -- Datentyp: mapped-device
     Objekte dieses Typs repräsentieren Gerätezuordnungen, die gemacht werden, wenn das System hochfährt.

     source
          Es handelt sich entweder um eine Zeichenkette, die den Namen eines zuzuordnenden blockorientierten Geräts angibt, wie "/dev/sda3", oder um eine Liste solcher Zeichenketten, sofern mehrere Geräts zu einem neuen Gerät verbunden werden.

     target
          Diese Zeichenkette gibt den Namen des neuen zugeordneten Geräts an. Bei Kernel-Zuordnern, wie verschlüsselten Geräten vom Typ luks-device-mapping, wird durch Angabe von "my-partition" ein Gerät "/dev/mapper/my-partition" erzeugt. Bei RAID-Geräten vom Typ raid-device-mapping muss der Gerätename als voller Pfad wie zum Beispiel "/dev/md0" angegeben werden.

     type
          Dies muss ein mapped-device-kind-Objekt sein, das angibt, wie die Quelle SOURCE dem Ziel TARGET zugeordnet wird.

 -- Scheme-Variable: luks-device-mapping
     Hiermit wird ein blockorientiertes Gerät mit LUKS verschlüsselt, mit Hilfe des Befehls cryptsetup aus dem gleichnamigen Paket. Dazu wird das Linux-Kernel-Modul dm-crypt vorausgesetzt.

 -- Scheme-Variable: raid-device-mapping
     Dies definiert ein RAID-Gerät, das mit dem Befehl mdadm aus dem gleichnamigen Paket als Verbund zusammengestellt wird. Es setzt voraus, dass das Linux-Kernel-Modul für das entsprechende RAID-Level geladen ist, z.B. raid456 für RAID-4, RAID-5 oder RAID-6, oder raid10 für RAID-10.

Das folgende Beispiel gibt eine Zuordnung von /dev/sda3 auf /dev/mapper/home mit LUKS an — dem Linux Unified Key Setup (https://gitlab.com/cryptsetup/cryptsetup), einem Standardmechanismus zur Plattenverschlüsselung. Das Gerät /dev/mapper/home kann dann als device einer file-system-Deklaration benutzt werden (see Dateisysteme).

     (mapped-device
       (source "/dev/sda3")
       (target "home")
       (type luks-device-mapping))

Um nicht davon abhängig zu sein, wie Ihre Geräte nummeriert werden, können Sie auch die LUKS-UUID (unique identifier, d.h. den eindeutigen Bezeichner) des Quellgeräts auf der Befehlszeile ermitteln:

     cryptsetup luksUUID /dev/sda3

und wie folgt benutzen:

     (mapped-device
       (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44"))
       (target "home")
       (type luks-device-mapping))

Es ist auch wünschenswert, Swap-Speicher zu verschlüsseln, da in den Swap-Speicher sensible Daten ausgelagert werden können. Eine Möglichkeit ist, eine Swap-Datei auf einem mit LUKS-Verschlüsselung zugeordneten Dateisystem zu verwenden. Dann wird die Swap-Datei verschlüsselt, weil das ganze Gerät verschlüsselt wird. Ein Beispiel finden Sie im Abschnitt see Disk Partitioning.

Ein RAID-Gerät als Verbund der Partitionen /dev/sda1 und /dev/sdb1 kann wie folgt deklariert werden:

     (mapped-device
       (source (list "/dev/sda1" "/dev/sdb1"))
       (target "/dev/md0")
       (type raid-device-mapping))

Das Gerät /dev/md0 kann als device in einer file-system-Deklaration dienen (see Dateisysteme). Beachten Sie, dass das RAID-Level dabei nicht angegeben werden muss; es wird während der initialen Erstellung und Formatierung des RAID-Geräts festgelegt und später automatisch bestimmt.

Benutzerkonten
==============

Benutzerkonten und Gruppen werden allein durch die operating-system-Deklaration des Betriebssystems verwaltet. Sie werden mit den user-account- und user-group-Formen angegeben:

     (user-account
       (name "alice")
       (group "users")
       (supplementary-groups '("wheel"   ;zur sudo-Nutzung usw. berechtigen
                               "audio"   ;Soundkarte
                               "video"   ;Videogeräte wie Webcams
                               "cdrom")) ;die gute alte CD-ROM
       (comment "Bobs Schwester")
       (home-directory "/home/alice"))

Beim Hochfahren oder nach Abschluss von guix system reconfigure stellt das System sicher, dass nur die in der operating-system-Deklaration angegebenen Benutzerkonten und Gruppen existieren, mit genau den angegebenen Eigenschaften. Daher gehen durch direkten Aufruf von Befehlen wie useradd erwirkte Erstellungen oder Modifikationen von Konten oder Gruppen verloren, sobald rekonfiguriert oder neugestartet wird. So wird sichergestellt, dass das System genau so funktioniert, wie es deklariert wurde.

 -- Datentyp: user-account
     Objekte dieses Typs repräsentieren Benutzerkonten. Darin können folgende Komponenten aufgeführt werden:

     name
          Der Name des Benutzerkontos.

     group
          Dies ist der Name (als Zeichenkette) oder die Bezeichnung (als Zahl) der Benutzergruppe, zu der dieses Konto gehört.

     supplementary-groups (Vorgabe: '())
          Dies kann optional als Liste von Gruppennamen angegeben werden, zu denen dieses Konto auch gehört.

     uid (Vorgabe: #f)
          Dies ist entweder der Benutzeridentifikator dieses Kontos (seine »User ID«) als Zahl oder #f. Bei Letzterem wird vom System automatisch eine Zahl gewählt, wenn das Benutzerkonto erstellt wird.

     comment (Vorgabe: "")
          Ein Kommentar zu dem Konto, wie etwa der vollständige Name des Kontoinhabers.

     home-directory
          Der Name des Persönlichen Verzeichnisses (»Home«-Verzeichnis) für dieses Konto.

     create-home-directory? (Vorgabe: #t)
          Zeigt an, ob das Persönliche Verzeichnis für das Konto automatisch erstellt werden soll, falls es noch nicht existiert.

     shell (Vorgabe: Bash)
          Ein G-Ausdruck, der den Dateinamen des Programms angibt, das dem Benutzer als Shell dienen soll (see G-Ausdrücke).

     system? (Vorgabe: #f)
          Dieser boolesche Wert zeigt an, ob das Konto ein »System«-Benutzerkonto ist. Systemkonten werden manchmal anders behandelt, zum Beispiel werden sie auf graphischen Anmeldebildschirmen nicht aufgeführt.

     password (Vorgabe: #f)
          Normalerweise lassen Sie dieses Feld auf #f und initialisieren Benutzerpasswörter als root mit dem passwd-Befehl. Die Benutzer lässt man ihr eigenes Passwort dann mit passwd ändern. Mit passwd festgelegte Passwörter bleiben natürlich beim Neustarten und beim Rekonfigurieren erhalten.

          If you do want to set an initial password for an account, then this field must contain the encrypted password, as a string.  You can use the crypt procedure for this purpose:

               (user-account
                 (name "charlie")
                 (home-directory "/home/charlie")
                 (group "users")

                 ;; Specify a SHA-512-hashed initial password.
                 (password (crypt "InitialPassword!" "$6$abc")))

               The hash of this initial password will be available in a file in /gnu/store, readable by all the users, so this method must be used with care.

          See Passphrase Storage (The GNU C Library Reference Manual), for more information on password encryption, and Encryption (GNU Guile Reference Manual), for information on Guile's crypt procedure.

Benutzergruppen-Deklarationen sind noch einfacher aufgebaut:

     (user-group (name "students"))

 -- Datentyp: user-group
     Dieser Typ gibt, nun ja, eine Benutzergruppe an. Es gibt darin nur ein paar Felder:

     name
          Der Name der Gruppe.

     id (Vorgabe: #f)
          Der Gruppenbezeichner (eine Zahl). Wird er als #f angegeben, wird automatisch eine neue Zahl reserviert, wenn die Gruppe erstellt wird.

     system? (Vorgabe: #f)
          Dieser boolesche Wert gibt an, ob es sich um eine »System«-Gruppe handelt. Systemgruppen sind solche mit einer kleinen Zahl als Bezeichner.

     password (Vorgabe: #f)
          Wie, Benutzergruppen können ein Passwort haben? Nun ja, anscheinend schon. Wenn es nicht auf #f steht, gibt dieses Feld das Passwort der Gruppe an.

Um Ihnen das Leben zu erleichtern, gibt es eine Variable, worin alle grundlegenden Benutzergruppen aufgeführt sind, die man erwarten könnte:

 -- Scheme-Variable: %base-groups
     Die Liste von Basis-Benutzergruppen, von denen Benutzer und/oder Pakete erwarten könnten, dass sie auf dem System existieren. Dazu gehören Gruppen wie »root«, »wheel« und »users«, sowie Gruppen, um den Zugriff auf bestimmte Geräte einzuschränken, wie »audio«, »disk« und »cdrom«.

 -- Scheme-Variable: %base-user-accounts
     Diese Liste enthält Basis-Systembenutzerkonten, von denen Programme erwarten können, dass sie auf einem GNU/Linux-System existieren, wie das Konto »nobody«.

     Beachten Sie, dass das Konto »root« für den Administratornutzer nicht dazugehört. Es ist ein Sonderfall und wird automatisch erzeugt, egal ob es spezifiziert wurde oder nicht.

Locales
=======

Eine Locale legt die kulturellen Konventionen einer bestimmten Sprache und Region auf der Welt fest (see Locales (The GNU C Library Reference Manual)). Jede Locale hat einen Namen, der typischerweise von der Form SPRACHE_TERRITORIUM.KODIERUNG — z.B. benennt fr_LU.utf8 die Locale für französische Sprache mit den kulturellen Konventionen aus Luxemburg unter Verwendung der UTF-8-Kodierung.

Normalerweise werden Sie eine standardmäßig zu verwendende Locale für die Maschine vorgeben wollen, indem Sie das locale-Feld der operating-system-Deklaration verwenden (see locale).

Die ausgewählte Locale wird automatisch zu den dem System bekannten Locale-Definitionen hinzugefügt, falls nötig, und ihre Kodierung wird aus dem Namen hergeleitet — z.B. wird angenommen, dass bo_CN.utf8 als Kodierung UTF-8 verwendet. Zusätzliche Locale-Definitionen können im Feld locale-definitions vom operating-system festgelegt werden — das ist zum Beispiel dann nützlich, wenn die Kodierung nicht aus dem Locale-Namen hergeleitet werden konnte. Die vorgegebene Menge an Locale-Definitionen enthält manche weit verbreiteten Locales, aber um Platz zu sparen, nicht alle verfügbaren Locales.

Um zum Beispiel die nordfriesische Locale für Deutschland hinzuzufügen, könnte der Wert des Feldes wie folgt aussehen:

     (cons (locale-definition
             (name "fy_DE.utf8") (source "fy_DE"))
           %default-locale-definitions)

Um Platz zu sparen, könnte man auch wollen, dass locale-definitions nur die tatsächlich benutzen Locales aufführt, wie etwa:

     (list (locale-definition
             (name "ja_JP.eucjp") (source "ja_JP")
             (charset "EUC-JP")))

Die kompilierten Locale-Definitionen sind unter /run/current-system/locale/X.Y verfügbar, wobei X.Y die Version von libc bezeichnet. Dies entspricht dem Pfad, an dem eine von Guix ausgelieferte GNU libc standardmäßig nach Locale-Daten sucht. Er kann überschrieben werden durch die Umgebungsvariable LOCPATH (see LOCPATH und Locale-Pakete).

Die locale-definition-Form wird vom Modul (gnu system locale) zur Verfügung gestellt.  Details folgen unten.

 -- Datentyp: locale-definition
     Dies ist der Datentyp einer Locale-Definition.

     name
          Der Name der Locale. Siehe Locale Names (The GNU C Library Reference Manual) für mehr Informationen zu Locale-Namen.

     source
          Der Name der Quelle der Locale. Typischerweise ist das der Teil aus SPRACHE_TERRITORIUM des Locale-Namens.

     charset (Vorgabe: "UTF-8")
          Der »Zeichensatz« oder das »Code set«, d.h. die Kodierung dieser Locale, wie die IANA sie definiert (http://www.iana.org/assignments/character-sets).

 -- Scheme-Variable: %default-locale-definitions
     Eine Liste häufig benutzter UTF-8-Locales, die als Vorgabewert des locale-definitions-Feldes in operating-system-Deklarationen benutzt wird.

     Diese Locale-Definitionen benutzen das normalisierte Codeset für den Teil des Namens, der nach dem Punkt steht (see normalized codeset (The GNU C Library Reference Manual)). Zum Beispiel ist uk_UA.utf8 enthalten, dagegen ist etwa uk_UA.UTF-8 darin nicht enthalten.

Kompatibilität der Locale-Daten
-------------------------------

operating-system-Deklarationen verfügen über ein locale-libcs-Feld, um die GNU libc-Pakete anzugeben, die zum Kompilieren von Locale-Deklarationen verwendet werden sollen (see »operating-system«-Referenz). »Was interessiert mich das?«, könnten Sie fragen. Naja, leider ist das binäre Format der Locale-Daten von einer libc-Version auf die nächste manchmal nicht miteinander kompatibel.

Zum Beispiel kann ein mit der libc-Version 2.21 gebundenes Programm keine mit libc 2.22 erzeugten Locale-Daten lesen; schlimmer noch, das Programm terminiert statt einfach die inkompatiblen Locale-Daten zu ignorieren (Versionen 2.23 von GNU libc und neuere werden inkompatible Locale-Daten nur mehr überspringen, was schon einmal eine Verbesserung ist.). Ähnlich kann ein gegen libc 2.22 gebundenes Programm die meisten, aber nicht alle, Locale-Daten von libc 2.21 lesen (Daten zu LC_COLLATE sind aber zum Beispiel inkompatibel); somit schlagen Aufrufe von setlocale vielleicht fehl, aber das Programm läuft weiter.

The ``problem'' with Guix is that users have a lot of freedom: They can choose whether and when to upgrade software in their profiles, and might be using a libc version different from the one the system administrator used to build the system-wide locale data.

Glücklicherweise können »unprivilegierte« Nutzer ohne zusätzliche Berechtigungen dann zumindest ihre eigenen Locale-Daten installieren und GUIX_LOCPATH entsprechend definieren (see GUIX_LOCPATH und Locale-Pakete).

Trotzdem ist es am besten, wenn die systemweiten Locale-Daten unter /run/current-system/locale für alle libc-Versionen erstellt werden, die auf dem System noch benutzt werden, damit alle Programme auf sie zugreifen können — was auf einem Mehrbenutzersystem ganz besonders wichtig ist. Dazu kann der Administrator des Systems mehrere libc-Pakete im locale-libcs-Feld vom operating-system angeben:

     (use-package-modules base)

     (operating-system
       ;; ...
       (locale-libcs (list glibc-2.21 (canonical-package glibc))))

Mit diesem Beispiel ergäbe sich ein System, was Locale-Definitionen sowohl für libc 2.21 als auch die aktuelle Version von libc in /run/current-system/locale hat.

Dienste
=======

Ein wichtiger Bestandteil des Schreibens einer operating-system-Deklaration ist das Auflisten der Systemdienste und ihrer Konfiguration (see Das Konfigurationssystem nutzen). Systemdienste sind typischerweise im Hintergrund laufende Daemon-Programme, die beim Hochfahren des Systems gestartet werden, oder andere Aktionen, die zu dieser Zeit durchgeführt werden müssen — wie das Konfigurieren des Netzwerkzugangs.

Guix has a broad definition of ``service'' (see Dienstkompositionen), but many services are managed by the GNU Shepherd (see Shepherd-Dienste).  On a running system, the herd command allows you to list the available services, show their status, start and stop them, or do other specific operations (see Jump Start (The GNU Shepherd Manual)).  For example:

     # herd status

Dieser Befehl, durchgeführt als root, listet die momentan definierten Dienste auf. Der Befehl herd doc fasst kurz zusammen, was ein gegebener Dienst ist und welche Aktionen mit ihm assoziiert sind:

     # herd doc nscd
     Run libc's name service cache daemon (nscd).

     # herd doc nscd action invalidate
     invalidate: Invalidate the given cache--e.g., 'hosts' for host name lookups.

Die Unterbefehle start, stop und restart haben die Wirkung, die man erwarten würde. Zum Beispiel kann mit folgenden Befehlen der nscd-Dienst angehalten und der Xorg-Display-Server neu gestartet werden:

     # herd stop nscd
     Service nscd has been stopped.
     # herd restart xorg-server
     Service xorg-server has been stopped.
     Service xorg-server has been started.

Die folgenden Abschnitte dokumentieren die verfügbaren Dienste, die in einer operating-system-Deklaration benutzt werden können, angefangen mit den Diensten im Kern des Systems (»core services«)

Basisdienste
------------

Das Modul (gnu services base) stellt Definitionen für Basis-Dienste zur Verfügung, von denen man erwartet, dass das System sie anbietet. Im Folgenden sind die von diesem Modul exportierten Dienste aufgeführt.

 -- Scheme-Variable: %base-services
     Diese Variable enthält eine Liste von Basis-Diensten, die man auf einem System vorzufinden erwartet (siehe Diensttypen und Dienste für weitere Informationen zu Dienstobjekten): ein Anmeldungsdienst (mingetty) auf jeder Konsole (jedem »tty«), syslogd, den Name Service Cache Daemon (nscd) von libc, die udev-Geräteverwaltung und weitere.

     Dies ist der Vorgabewert für das services-Feld für die Dienste von operating-system-Deklarationen. Normalerweise werden Sie, wenn Sie ein Betriebssystem anpassen, Dienste an die %BASE-SERVICES-Liste anhängen, wie hier gezeigt:

          (append (list (service avahi-service-type)
                        (service openssh-service-type))
                  %base-services)

 -- Scheme-Variable: special-files-service-type
     Dieser Dienst richtet »besondere Dateien« wie /bin/sh ein; eine Instanz des Dienstes ist Teil der %base-services.

     Der mit special-files-service-type-Diensten assoziierte Wert muss eine Liste von Tupeln sein, deren erstes Element eine »besondere Datei« und deren zweites Element deren Zielpfad ist. Der Vorgabewert ist:

          `(("/bin/sh" ,(file-append BASH "/bin/sh")))

     Wenn Sie zum Beispiel auch /usr/bin/env zu Ihrem System hinzufügen möchten, können Sie den Wert ändern auf:

          `(("/bin/sh" ,(file-append BASH "/bin/sh"))
            ("/usr/bin/env" ,(file-append COREUTILS "/bin/env")))

     Da dieser Dienst Teil der %base-services ist, können Sie modify-services benutzen, um die Liste besonderer Dateien abzuändern (see modify-services). Die leichte Alternative, um eine besondere Datei hinzuzufügen, ist über die Prozedur extra-special-file (siehe unten).

 -- Scheme-Prozedur: extra-special-file DATEI ZIEL
     Das ZIEL als »besondere Datei« DATEI verwenden.

     Beispielsweise können Sie die folgenden Zeilen in das services-Feld Ihrer Betriebssystemdeklaration einfügen für eine symbolische Verknüpfung /usr/bin/env:

          (extra-special-file "/usr/bin/env"
                              (file-append coreutils "/bin/env"))

 -- Scheme-Prozedur: host-name-service NAME
     Liefert einen Dienst, der den Rechnernamen (den »Host«-Namen des Rechners) als NAME festlegt.

 -- Scheme-Prozedur: login-service KONFIGURATION
     Liefert einen Dienst, der die Benutzeranmeldung möglich macht. Dazu verwendet er die angegebene KONFIGURATION, ein <login-configuration>-Objekt, das unter Anderem die beim Anmelden angezeigte Mitteilung des Tages (englisch »Message of the Day«) festlegt.

 -- Datentyp: login-configuration
     Dies ist der Datentyp, der die Anmeldekonfiguration repräsentiert.

     motd
          Ein dateiartiges Objekt, das die »Message of the Day« enthält.

     allow-empty-passwords? (Vorgabe: #t)
          Leere Passwörter standardmäßig zulassen, damit sich neue Anwender anmelden können, direkt nachdem das Benutzerkonto »root« für den Administrator angelegt wurde.

 -- Scheme-Prozedur: mingetty-service KONFIGURATION
     Liefert einen Dienst, der mingetty nach den Vorgaben der KONFIGURATION ausführt, einem <mingetty-configuration>-Objekt, das unter Anderem die Konsole (das »tty«) festlegt, auf der mingetty laufen soll.

 -- Datentyp: mingetty-configuration
     Dieser Datentyp repräsentiert die Konfiguration von Mingetty, der vorgegebenen Implementierung zur Anmeldung auf einer virtuellen Konsole.

     tty
          Der Name der Konsole, auf der diese Mingetty-Instanz läuft — z.B. "tty1".

     auto-login (Vorgabe: #f)
          Steht dieses Feld auf wahr, muss es eine Zeichenkette sein, die den Benutzernamen angibt, als der man vom System automatisch angemeldet wird. Ist es #f, so muss zur Anmeldung ein Benutzername und ein Passwort eingegeben werden.

     login-program (Vorgabe: #f)
          Dies muss entweder #f sein, dann wird das voreingestellte Anmeldeprogramm benutzt (login aus dem Shadow-Werkzeugsatz) oder der Name des Anmeldeprogramms als G-Ausdruck.

     login-pause? (Vorgabe: #f)
          Ist es auf #t gesetzt, sorgt es in Verbindung mit AUTO-LOGIN dafür, dass der Benutzer eine Taste drücken muss, ehe eine Anmelde-Shell gestartet wird.

     mingetty (Vorgabe: MINGETTY)
          Welches Mingetty-Paket benutzt werden soll.

 -- Scheme-Prozedur: agetty-service KONFIGURATION
     Liefert einen Dienst, um agetty entsprechend der KONFIGURATION auszuführen, welche ein <agetty-configuration>-Objekt sein muss, das unter Anderem festlegt, auf welchem tty es laufen soll.

 -- Datentyp: agetty-configuration
     Dies ist der Datentyp, der die Konfiguration von agetty repräsentiert, was Anmeldungen auf einer virtuellen oder seriellen Konsole implementiert. Siehe die Handbuchseite agetty(8) für mehr Informationen.

     tty
          Der Name der Konsole, auf der diese Instanz von agetty läuft, als Zeichenkette — z.B. "ttyS0". Dieses Argument ist optional, sein Vorgabewert ist eine vernünftige Wahl unter den seriellen Schnittstellen, auf deren Benutzung der Linux-Kernel eingestellt ist.

          Hierzu wird, wenn in der Kernel-Befehlszeile ein Wert für eine Option namens agetty.tty festgelegt wurde, der Gerätename daraus für agetty extrahiert und benutzt.

          Andernfalls wird agetty, falls auf der Kernel-Befehlszeile eine Option console mit einem tty vorkommt, den daraus extrahierten Gerätenamen der seriellen Schnittstelle benutzen.

          In both cases, agetty will leave the other serial device settings (baud rate etc.) alone---in the hope that Linux pinned them to the correct values.

     baud-rate (Vorgabe: #f)
          Eine Zeichenkette, die aus einer kommagetrennten Liste von einer oder mehreren Baud-Raten besteht, absteigend sortiert.

     term (Vorgabe: #f)
          Eine Zeichenkette, die den Wert enthält, der für die Umgebungsvariable TERM benutzt werden soll.

     eight-bits? (Vorgabe: #f)
          Steht dies auf #t, wird angenommen, dass das tty 8-Bit-korrekt ist, so dass die Paritätserkennung abgeschaltet wird.

     auto-login (Vorgabe: #f)
          Wird hier ein Anmeldename als eine Zeichenkette übergeben, wird der angegebene Nutzer automatisch angemeldet, ohne nach einem Anmeldenamen oder Passwort zu fragen.

     no-reset? (Vorgabe: #f)
          Steht dies auf #t, werden die Cflags des Terminals (d.h. dessen Steuermodi) nicht zurückgesetzt.

     host (Vorgabe: #f)
          Dies akzeptiert eine Zeichenkette mit dem einzutragenden Anmeldungs-Rechnernamen "login_host", der in die Datei /var/run/utmpx geschrieben wird.

     remote? (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird in Verbindung mit HOST eine Befehlszeilenoption -r für einen falschen Rechnernamen (»Fakehost«) in der Befehlszeile des mit LOGIN-PROGRAM angegebenen Anmeldeprogramms übergeben.

     flow-control? (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird Hardware-Flusssteuerung (RTS/CTS) aktiviert.

     no-issue? (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird der Inhalt der Datei /etc/issue nicht angezeigt, bevor die Anmeldeaufforderung zu sehen ist.

     init-string (Vorgabe: #f)
          Dies akzeptiert eine Zeichenkette, die zum tty oder zum Modem zuerst vor allem Anderen gesendet wird. Es kann benutzt werden, um ein Modem zu initialisieren.

     no-clear? (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird agetty den Bildschirm nicht löschen, bevor es die Anmeldeaufforderung anzeigt.

     login-program (Vorgabe: (file-append shadow "/bin/login"))
          Hier muss entweder ein G-Ausdruck mit dem Namen eines Anmeldeprogramms übergeben werden, oder dieses Feld wird nicht gesetzt, so dass als Vorgabewert das Programm login aus dem Shadow-Werkzeugsatz verwendet wird.

     local-line (Vorgabe: #f)
          Steuert den Leitungsschalter CLOCAL. Hierfür wird eines von drei Symbolen als Argument akzeptiert, 'auto, 'always oder 'never. Für #f wählt agetty als Vorgabewert 'auto.

     extract-baud? (Vorgabe: #f)
          Ist dies auf #t gesetzt, so wird agetty angewiesen, die Baud-Rate aus den Statusmeldungen mancher Arten von Modem abzulesen.

     skip-login? (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird der Benutzer nicht aufgefordert, einen Anmeldenamen einzugeben. Dies kann zusammen mit dem LOGIN-PROGRAM-Feld benutzt werden, um nicht standardkonforme Anmeldesysteme zu benutzen.

     no-newline? (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird kein Zeilenumbruch ausgegeben, bevor die Datei /etc/issue ausgegeben wird.

     login-options (Vorgabe: #f)
          Dieses Feld akzeptiert eine Zeichenkette mit den Befehlszeilenoptionen für das Anmeldeprogramm. Beachten Sie, dass bei einem selbst gewählten LOGIN-PROGRAM ein böswilliger Nutzer versuchen könnte, als Anmeldenamen etwas mit eingebetteten Befehlszeilenoptionen anzugeben, die vom Anmeldeprogramm interpretiert werden könnten.

     login-pause (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird auf das Drücken einer beliebigen Taste gewartet, bevor die Anmeldeaufforderung angezeigt wird. Hiermit kann in Verbindung mit AUTO-LOGIN weniger Speicher verbraucht werden, indem man Shells erst erzeugt, wenn sie benötigt werden.

     chroot (Vorgabe: #f)
          Wechselt die Wurzel des Dateisystems auf das angegebene Verzeichnis. Dieses Feld akzeptiert einen Verzeichnispfad als Zeichenkette.

     hangup? (Vorgabe: #f)
          Mit dem Linux-Systemaufruf vhangup auf dem angegebenen Terminal virtuell auflegen.

     keep-baud? (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird versucht, die bestehende Baud-Rate beizubehalten. Die Baud-Raten aus dem Feld BAUD-RATE werden benutzt, wenn agetty ein BREAK-Zeichen empfängt.

     timeout (Vorgabe: #f)
          Ist dies auf einen ganzzahligen Wert gesetzt, wird terminiert, falls kein Benutzername innerhalb von TIMEOUT Sekunden eingelesen werden konnte.

     detect-case? (Vorgabe: #f)
          Ist dies auf #t gesetzt, wird Unterstützung für die Erkennung von Terminals aktiviert, die nur Großschreibung beherrschen. Mit dieser Einstellung wird, wenn ein Anmeldename nur aus Großbuchstaben besteht, dieser als Anzeichen dafür aufgefasst, dass das Terminal nur Großbuchstaben beherrscht, und einige Umwandlungen von Groß- in Kleinbuchstaben aktiviert. Beachten Sie, dass dabei keine Unicode-Zeichen unterstützt werden.

     wait-cr? (Vorgabe: #f)
          Wenn dies auf #t gesetzt ist, wird gewartet, bis der Benutzer oder das Modem einen Wagenrücklauf (»Carriage Return«) oder einen Zeilenvorschub (»Linefeed«) absendet, ehe /etc/issue oder eine Anmeldeaufforderung angezeigt wird. Dies wird typischerweise zusammen mit dem Feld INIT-STRING benutzt.

     no-hints? (Vorgabe: #f)
          Ist es auf #t gesetzt, werden keine Hinweise zu den Feststelltasten Num-Taste, Umschaltsperre (»Caps Lock«) und Rollen-Taste (»Scroll Lock«) angezeigt.

     no-hostname? (Vorgabe: #f)
          Das vorgegebene Verhalten ist, den Rechnernamen auszugeben. Ist dieses Feld auf #t gesetzt, wird überhaupt kein Rechnername angezeigt.

     long-hostname? (Vorgabe: #f)
          Das vorgegebene Verhalten ist, den Rechnernamen nur bis zu seinem ersten Punkt anzuzeigen. Ist dieses Feld auf #t gesetzt, wird der vollständige Rechnername (der »Fully Qualified Hostname«), wie ihn gethostname oder getaddrinfo liefern, angezeigt.

     erase-characters (Vorgabe: #f)
          Dieses Feld akzeptiert eine Zeichenkette aus Zeichen, die auch als Rücktaste (zum Löschen) interpretiert werden sollen, wenn der Benutzer seinen Anmeldenamen eintippt.

     kill-characters (Vorgabe: #f)
          Dieses Feld akzeptiert eine Zeichenkette aus Zeichen, deren Eingabe als »ignoriere alle vorherigen Zeichen« interpretiert werden soll (auch »kill«-Zeichen genannt), wenn der Benutzer seinen Anmeldenamen eintippt.

     chdir (Vorgabe: #f)
          Dieses Feld akzeptiert eine Zeichenkette, die einen Verzeichnispfad angibt, zu dem vor der Anmeldung gewechselt wird.

     delay (Vorgabe: #f)
          Dieses Feld akzeptiert eine ganze Zahl mit der Anzahl Sekunden, die gewartet werden soll, bis ein tty geöffnet und die Anmeldeaufforderung angezeigt wird.

     nice (Vorgabe: #f)
          Dieses Feld akzeptiert eine ganze Zahl mit dem »nice«-Wert, mit dem das Anmeldeprogramm ausgeführt werden soll.

     extra-options (Vorgabe: '())
          Dieses Feld ist ein »Notausstieg«, mit dem Nutzer beliebige Befehlszeilenoptionen direkt an agetty übergeben können. Diese müssen hier als eine Liste von Zeichenketten angegeben werden.

 -- Scheme-Prozedur: kmscon-service-type KONFIGURATION
     Liefert einen Dienst, um kmscon (https://www.freedesktop.org/wiki/Software/kmscon) entsprechend der KONFIGURATION auszuführen. Diese ist ein <kmscon-configuration>-Objekt, das unter Anderem angibt, auf welchem tty es ausgeführt werden soll.

 -- Datentyp: kmscon-configuration
     Dieser Datentyp repräsentiert die Konfiguration von Kmscon, die das Anmelden auf virtuellen Konsolen ermöglicht.

     virtual-terminal
          Der Name der Konsole, auf der diese Kmscon läuft — z.B. "tty1".

     login-program (Vorgabe: #~(string-append #$shadow "/bin/login"))
          Ein G-Ausdruck, der den Namen des Anmeldeprogramms angibt. Als Vorgabe wird das Anmeldeprogramm login aus dem Shadow-Werkzeugsatz verwendet.

     login-arguments (Vorgabe: '("-p"))
          Eine Liste der Argumente, die an login übergeben werden sollen.

     auto-login (Vorgabe: #f)
          Wird hier ein Anmeldename als eine Zeichenkette übergeben, wird der angegebene Nutzer automatisch angemeldet, ohne nach einem Anmeldenamen oder Passwort zu fragen.

     hardware-acceleration? (Vorgabe: #f)
          Ob Hardware-Beschleunigung verwendet werden soll.

     kmscon (Vorgabe: KMSCON)
          Das Kmscon-Paket, das benutzt werden soll.

 -- Scheme-Prozedur: nscd-service [KONFIGURATION] [#:glibc glibc]
     [#:name-services '()] Liefert einen Dienst, der den Name Service Cache
     Daemon (nscd) von libc mit der angegebenen KONFIGURATION ausführt — diese muss ein <nscd-configuration>-Objekt sein. Siehe Name Service Switch für ein Beispiel.

     Der Einfachheit halber bietet der Shepherd-Dienst für nscd die folgenden Aktionen an:

     invalidate
          Dies macht den angegebenen Zwischenspeicher ungültig. Wenn Sie zum Beispiel:

               herd invalidate nscd hosts

          ausführen, wird der Zwischenspeicher für die Auflösung von Rechnernamen (von »Host«-Namen) des nscd ungültig.

     statistics
          Wenn Sie herd statistics nscd ausführen, werden Ihnen Informationen angezeigt, welche Ihnen Informationen über den nscd-Zustand und die Zwischenspeicher angezeigt.

 -- Scheme-Variable: %nscd-default-configuration
     Dies ist der vorgegebene Wert für die <nscd-configuration> (siehe unten), die nscd-service benutzt. Die Konfiguration benutzt die Zwischenspeicher, die in %NSCD-DEFAULT-CACHES definiert sind; siehe unten.

 -- Datentyp: nscd-configuration
     Dieser Datentyp repräsentiert die Konfiguration des Name Service Caching Daemon (kurz »nscd«).

     name-services (Vorgabe: '())
          Liste von Paketen, die Namensdienste bezeichnen, die für den nscd sichtbar sein müssen, z.B. (list NSS-MDNS).

     glibc (Vorgabe: GLIBC)
          Ein Paket-Objekt, das die GNU-C-Bibliothek angibt, woraus der nscd-Befehl genommen werden soll.

     log-file (Vorgabe: "/var/log/nscd.log")
          Name der nscd-Protokolldatei. Hierhin werden Ausgaben zur Fehlersuche geschrieben, falls debug-level echt positiv ist.

     debug-level (Vorgabe: 0)
          Eine ganze Zahl, die den Detailgrad der Ausgabe zur Fehlersuche angibt. Größere Zahlen bewirken eine ausführlichere Ausgabe.

     caches (Vorgabe: %NSCD-DEFAULT-CACHES)
          Liste der <nscd-cache>-Objekte, die repräsentieren, was alles zwischengespeichert werden soll; siehe unten.

 -- Datentyp: nscd-cache
     Ein Datentyp, der eine Zwischenspeicher-Datenbank von nscd mitsamt ihren Parametern definiert.

     Datenbank
          Dies ist ein Symbol, was den Namen der Datenbank repräsentiert, die zwischengespeichert werden soll. Gültige Werte sind passwd, group, hosts und services, womit jeweils die entsprechende NSS-Datenbank bezeichnet wird (see NSS Basics (The GNU C Library Reference Manual)).

     positive-time-to-live
     negative-time-to-live (Vorgabe: 20)
          Eine Zahl, die für die Anzahl an Sekunden steht, die ein erfolgreiches (positives) oder erfolgloses (negatives) Nachschlageresultat im Zwischenspeicher verbleibt.

     check-files? (Vorgabe: #t)
          Ob auf Änderungen an den der DATABASE entsprechenden Dateien reagiert werden soll.

          Wenn DATABASE zum Beispiel hosts ist, wird, wenn dieses Feld gesetzt ist, nscd Änderungen an /etc/hosts beobachten und berücksichtigen.

     persistent? (Vorgabe: #t)
          Ob der Zwischenspeicher dauerhaft auf der Platte gespeichert werden soll.

     shared? (Vorgabe: #t)
          Ob der Zwischenspeicher zwischen den Nutzern geteilt werden soll.

     max-database-size (Vorgabe: 32 MiB)
          Die Maximalgröße des Datenbank-Zwischenspeichers in Bytes.

 -- Scheme-Variable: %nscd-default-caches
     Liste von <nscd-cache>-Objekten, die von der vorgegebenen nscd-configuration benutzt werden (siehe oben).

     Damit wird dauerhaftes und aggressives Zwischenspeichern beim Nachschlagen von Dienst- und Rechnernamen (»Host«-Namen) aktiviert. Letzteres verbessert die Leistungsfähigkeit beim Nachschlagen von Rechnernamen, sorgt für mehr Widerstandsfähigkeit gegenüber unverlässlichen Namens-Servern und bietet außerdem einen besseren Schutz der Privatsphäre — oftmals befindet sich das Ergebnis einer Anfrage nach einem Rechnernamen bereits im lokalen Zwischenspeicher und externe Namens-Server müssen nicht miteinbezogen werden.

 -- Datentyp: syslog-configuration
     Dieser Datentyp repräsentiert die Konfiguration des syslog-Daemons.

     syslogd (Vorgabe: #~(string-append #$inetutils "/libexec/syslogd"))
          Welcher Syslog-Daemon benutzt werden soll.

     config-file (Vorgabe: %default-syslog.conf)
          Die zu benutzende syslog-Konfigurationsdatei.

 -- Scheme-Prozedur: syslog-service KONFIGURATION
     Liefert einen Dienst, der einen syslog-Daemon entsprechend der KONFIGURATION ausführt.

     See syslogd invocation (GNU Inetutils), für weitere Informationen über die Syntax der Konfiguration.

 -- Scheme-Variable: guix-service-type
     Dies ist der Typ für den Dienst, der den Erstellungs-Daemon guix-daemon ausführt (see Aufruf des guix-daemon). Als Wert muss ein guix-configuration-Verbundsobjekt verwendet werden, wie unten beschrieben.

 -- Datentyp: guix-configuration
     Dieser Datentyp repräsentiert die Konfiguration des Erstellungs-Daemons von Guix. Siehe Aufruf des guix-daemon für weitere Informationen.

     guix (Vorgabe: GUIX)
          Das zu verwendende Guix-Paket.

     build-group (Vorgabe: "guixbuild")
          Der Name der Gruppe, zu der die Erstellungs-Benutzerkonten gehören.

     build-accounts (Vorgabe: 10)
          Die Anzahl zu erzeugender Erstellungs-Benutzerkonten.

     authorize-key? (Vorgabe: #t)
          Whether to authorize the substitute keys listed in authorized-keys---by default that of ci.guix.de.info (see Substitute).

     authorized-keys (Vorgabe: %DEFAULT-AUTHORIZED-GUIX-KEYS)
          The list of authorized key files for archive imports, as a list of string-valued gexps (see Aufruf von guix archive).  By default, it contains that of ci.guix.de.info (see Substitute).

     use-substitutes? (Vorgabe: #t)
          Ob Substitute benutzt werden sollen.

     substitute-urls (Vorgabe: %DEFAULT-SUBSTITUTE-URLS)
          Die Liste der URLs, auf denen nach Substituten gesucht wird, wenn nicht anders angegeben.

     max-silent-time (Vorgabe: 0)
     timeout (Vorgabe: 0)
          Die Anzahl an Sekunden, die jeweils nichts in die Ausgabe geschrieben werden darf bzw. die es insgesamt dauern darf, bis ein Erstellungsprozess abgebrochen wird. Beim Wert null wird nie abgebrochen.

     log-compression (Vorgabe: 'bzip2)
          Die für Erstellungsprotokolle zu benutzende Kompressionsmethode — entweder gzip, bzip2 oder none.

     extra-options (Vorgabe: '())
          Eine Liste zusätzlicher Befehlszeilenoptionen zu guix-daemon.

     log-file (Vorgabe: "/var/log/guix-daemon.log")
          Die Datei, in die die Standardausgabe und die Standardfehlerausgabe von guix-daemon geschrieben werden.

     http-proxy (Vorgabe: #f)
          Der für das Herunterladen von Ableitungen mit fester Ausgabe und von Substituten zu verwendende HTTP-Proxy.

     tmpdir (Vorgabe: #f)
          Ein Verzeichnispfad, der angibt, wo guix-daemon seine Erstellungen durchführt.

 -- Scheme-Prozedur: udev-service [#:udev EUDEV #:rules '()]
     Führt UDEV aus, was zur Laufzeit Gerätedateien ins Verzeichnis /dev einfügt. udev-Regeln können über die RULES-Variable als eine Liste von Dateien übergeben werden. Die Prozeduren UDEV-RULE und FILE->UDEV-RULE aus (gnu services base) vereinfachen die Erstellung einer solchen Regeldatei.

 -- Scheme-Prozedur: udev-rule [DATEINAME INHALT]
     Liefert eine udev-Regeldatei mit dem angegebenen DATEINAMEn, in der die vom Literal INHALT definierten Regeln stehen.

     Im folgenden Beispiel wird eine Regel für ein USB-Gerät definiert und in der Datei 90-usb-ding.rules gespeichert. Mit der Regel wird ein Skript ausgeführt, sobald ein USB-Gerät mit der angegebenen Produktkennung erkannt wird.

          (define %beispiel-udev-rule
            (udev-rule
              "90-usb-ding.rules"
              (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", "
                             "ATTR{product}==\"Beispiel\", "
                             "RUN+=\"/pfad/zum/skript\"")))

     The herd rules udev command, as root, returns the name of the directory containing all the active udev rules.

Hier zeigen wir, wie man den vorgegebenen UDEV-SERVICE um sie erweitern kann.

     (operating-system
      ;; ...
      (services
      (modify-services %desktop-services
        (udev-service-type config =>
          (udev-configuration (inherit config)
           (rules (append (udev-configuration-rules config)
                          (list %beispiel-udev-rule))))))))

 -- Scheme-Prozedur: file->udev-rule [DATEINAME DATEI]
     Liefert eine udev-Datei mit dem angegebenen DATEINAMEn, in der alle in der DATEI, einem dateiartigen Objekt, definierten Regeln stehen.

     Folgendes Beispiel stellt dar, wie wir eine bestehende Regeldatei verwenden können.

          (use-modules (guix download)     ;für url-fetch
                       (guix packages)     ;für origin
                       ;; ...)

          (define %android-udev-rules
            (file->udev-rule
              "51-android-udev.rules"
              (let ((version "20170910"))
                (origin
                 (method url-fetch)
                 (uri (string-append "https://raw.githubusercontent.com/M0Rf30/"
                                     "android-udev-rules/" version "/51-android.rules"))
                 (sha256
                  (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003"))))))

Zusätzlich können Guix-Paketdefinitionen unter den RULES aufgeführt werden, um die udev-Regeln um diejenigen Definitionen zu ergänzen, die im Unterverzeichnis lib/udev/rules.d des jeweiligen Pakets aufgeführt sind. Statt des bisherigen Beispiels zu FILE->UDEV-RULE hätten wir also auch das Paket ANDROID-UDEV-RULES benutzen können, das in Guix im Modul (gnu packages android) vorhanden ist.

Das folgende Beispiel zeit, wie dieses Paket ANDROID-UDEV-RULES benutzt werden kann, damit das »Android-Tool« adb Geräte erkennen kann, ohne dafür Administratorrechte vorauszusetzen. Man sieht hier auch, wie die Benutzergruppe adbusers erstellt werden kann, die existieren muss, damit die im Paket ANDROID-UDEV-RULES definierten Regeln richtig funktionieren. Um so eine Benutzergruppe zu erzeugen, müssen wir sie sowohl unter den SUPPLEMENTARY-GROUPS unserer USER-ACCOUNT-Deklaration aufführen, als auch sie im GROUPS-Feld des OPERATING-SYSTEM-Verbundsobjekts aufführen.

     (use-modules (gnu packages android)  ;für android-udev-rules
                  (gnu system shadow)     ;für user-group
                  ;; ...)

     (operating-system
       ;; ...
       (users (cons (user-acount
                     ;; ...
                     (supplementary-groups
                      '("adbusers"   ;für adb
                        "wheel" "netdev" "audio" "video"))
                     ;; ...)))

       (groups (cons (user-group (system? #t) (name "adbusers"))
                     %base-groups))

       ;; ...

       (services
        (modify-services %desktop-services
          (udev-service-type
           config =>
           (udev-configuration (inherit config)
                               (rules (cons android-udev-rules
                                            (udev-configuration-rules config))))))))

 -- Scheme-Variable: urandom-seed-service-type
     Etwas Entropie in der Datei %RANDOM-SEED-FILE aufsparen, die als Startwert (als sogenannter »Seed«) für /dev/urandom dienen kann, nachdem das System neu gestartet wurde. Es wird auch versucht, /dev/urandom beim Hochfahren mit Werten aus /dev/hwrng zu starten, falls /dev/hwrng existiert und lesbar ist.

 -- Scheme-Variable: %random-seed-file
     Der Name der Datei, in der einige zufällige Bytes vom URANDOM-SEED-SERVICE abgespeichert werden, um sie nach einem Neustart von dort als Startwert für /dev/urandom auslesen zu können. Als Vorgabe wird /var/lib/random-seed verwendet.

 -- Scheme-Prozedur: console-keymap-service DATEIEN ...
     Liefert einen Dienst, um Tastenzuordnungen (»Keymaps«) für die Konsole aus den DATEIEN laden zu können. Dazu wird der Befehl loadkeys aufgerufen. Wahrscheinlich möchten Sie irgendeine vorgefertigte Keymap laden, etwa so:

          (console-keymap-service "dvorak")

     Oder um zum Beispiel eine schwedische Tastaturbelegung zu bekommen, könnten Sie die folgenden Keymaps kombinieren müssen:

          (console-keymap-service "se-lat6" "se-fi-lat6")

     Sie können alternativ auch den oder die vollständigen Dateinamen Ihrer Keymap(s) angeben. Siehe man loadkeys für Details.

 -- Scheme-Variable: gpm-service-type
     Dieser Typ wird für den Dienst verwendet, der GPM ausführt, den »General-Purpose Mouse Daemon«, welcher zur Linux-Konsole Mausunterstützung hinzufügt. GPM ermöglicht es seinen Benutzern, auch in der Konsole die Maus zu benutzen und damit etwa Text auszuwählen, zu kopieren und einzufügen.

     Der Wert für Dienste dieses Typs muss eine gpm-configuration sein (siehe unten). Dieser Dienst gehört nicht zu den %BASE-SERVICES.

 -- Datentyp: gpm-configuration
     Repräsentiert die Konfiguration von GPM.

     options (Vorgabe: %default-gpm-options)
          Befehlszeilenoptionen, die an gpm übergeben werden. Die vorgegebenen Optionen weisen gpm an, auf Maus-Ereignisse auf der Datei /dev/input/mice zu lauschen. Siehe Command Line (gpm manual) für weitere Informationen.

     gpm (Vorgabe: gpm)
          Das GPM-Paket, was benutzt werden soll.

 -- Scheme-Variable: guix-publish-service-type
     Dies ist der Diensttyp für guix publish (see Aufruf von guix publish). Sein Wert muss ein guix-publish-configuration-Objekt sein, wie im Folgenden beschrieben.

     Hierbei wird angenommen, dass /etc/guix bereits ein mit guix archive --generate-key erzeugtes Schlüsselpaar zum Signieren enthält (see Aufruf von guix archive). Falls nicht, wird der Dienst beim Starten fehlschlagen.

 -- Datentyp: guix-publish-configuration
     Der Datentyp, der die Konfiguration des »guix publish«-Dienstes repräsentiert.

     guix (Vorgabe: guix)
          Das zu verwendende Guix-Paket.

     port (Vorgabe: 80)
          Der TCP-Port, auf dem auf Verbindungen gelauscht werden soll.

     host (Vorgabe: "localhost")
          Unter welcher Rechneradresse (welchem »Host«, also welcher Netzwerkschnittstelle) auf Verbindungen gelauscht wird. Benutzen Sie "0.0.0.0", wenn auf allen verfügbaren Netzwerkschnittstellen gelauscht werden soll.

     compression-level (Vorgabe: 3)
          Die gzip-Kompressionsstufe, mit der Substitute komprimiert werden sollen. Benutzen Sie 0, um Kompression völlig abzuschalten, und 9 für das höchste Kompressionsverhältnis, zu Lasten von zusätzlicher Prozessorauslastung.

     nar-path (Vorgabe: "nar")
          Der URL-Pfad, unter dem »Nars« zum Herunterladen angeboten werden. Siehe --nar-path, für Details.

     cache (Vorgabe: #f)
          Wenn dies #f ist, werden Archive nicht zwischengespeichert, sondern erst bei einer Anfrage erzeugt. Andernfalls sollte dies der Name eines Verzeichnisses sein — z.B. "/var/cache/guix/publish" —, in das guix publish fertige Archive und Metadaten zwischenspeichern soll. Siehe --cache, für weitere Informationen über die jeweiligen Vor- und Nachteile.

     workers (Vorgabe: #f)
          Ist dies eine ganze Zahl, gibt es die Anzahl der Worker-Threads an, die zum Zwischenspeichern benutzt werden; ist es #f, werden so viele benutzt, wie es Prozessoren gibt. Siehe --workers, für mehr Informationen.

     ttl (Vorgabe: #f)
          Wenn dies eine ganze Zahl ist, bezeichnet sie die Time-to-live als die Anzahl der Sekunden, die heruntergeladene veröffentlichte Archive zwischengespeichert werden dürfen. Siehe --ttl, für mehr Informationen.

 -- Scheme-Prozedur: rngd-service [#:rng-tools RNG-TOOLS]
     [#:device "/dev/hwrng"] Liefert einen Dienst, der das
     rngd-Programm aus den RNG-TOOLS benutzt, um das mit DEVICE bezeichnete Gerät zum Entropie-Pool des Kernels hinzuzufügen. Dieser Dienst wird fehlschlagen, falls das mit DEVICE bezeichnete Gerät nicht existiert.

 -- Scheme-Prozedur: pam-limits-service [#:limits '()]

     Liefert einen Dienst, der eine Konfigurationsdatei für das pam_limits-Modul (http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html) installiert. Diese Prozedur nimmt optional eine Liste von pam-limits-entry-Werten entgegen, die benutzt werden können, um ulimit-Limits und nice-Prioritäten für Benutzersitzungen festzulegen.

     Die folgenden Limit-Definitionen setzen zwei harte und weiche Limits für alle Anmeldesitzungen für Benutzer in der realtime-Gruppe.

          (pam-limits-service
           (list
            (pam-limits-entry "@realtime" 'both 'rtprio 99)
            (pam-limits-entry "@realtime" 'both 'memlock 'unlimited)))

     Der erste Eintrag erhöht die maximale Echtzeit-Priorität für unprivilegierte Prozesse ohne zusätzliche Berechtigungen; der zweite Eintrag hebt jegliche Einschränkungen des maximalen Adressbereichs auf, der im Speicher reserviert werden darf. Diese Einstellungen werden in dieser Form oft für Echtzeit-Audio-Systeme verwendet.

Geplante Auftragsausführung
---------------------------

The (gnu services mcron) module provides an interface to GNU mcron, a daemon to run jobs at scheduled times (see GNU mcron).  GNU mcron is similar to the traditional Unix cron daemon; the main difference is that it is implemented in Guile Scheme, which provides a lot of flexibility when specifying the scheduling of jobs and their actions.

The example below defines an operating system that runs the updatedb (see Invoking updatedb (Finding Files))  and the guix gc commands (see Aufruf von guix gc) daily, as well as the mkid command on behalf of an unprivileged user (see mkid invocation (ID Database Utilities)).  It uses gexps to introduce job definitions that are passed to mcron (see G-Ausdrücke).

     (use-modules (guix) (gnu) (gnu services mcron))
     (use-package-modules base idutils)

     (define updatedb-job
       ;; Run 'updatedb' at 3AM every day.  Here we write the
       ;; job's action as a Scheme procedure.
       #~(job '(next-hour '(3))
              (lambda ()
                (execl (string-append #$findutils "/bin/updatedb")
                       "updatedb"
                       "--prunepaths=/tmp /var/tmp /gnu/store"))))

     (define garbage-collector-job
       ;; Collect garbage 5 minutes after midnight every day.
       ;; The job's action is a shell command.
       #~(job "5 0 * * *"            ;Vixie cron syntax
              "guix gc -F 1G"))

     (define idutils-job
       ;; Update the index database as user "charlie" at 12:15PM
       ;; and 19:15PM.  This runs from the user's home directory.
       #~(job '(next-minute-from (next-hour '(12 19)) '(15))
              (string-append #$idutils "/bin/mkid src")
              #:user "charlie"))

     (operating-system
       ;; ...
       (services (cons (service mcron-service-type
                                (mcron-configuration
                                 (jobs (list garbage-collector-job
                                             updatedb-job
                                             idutils-job))))
                       %base-services)))

See mcron job specifications (GNU mcron), for more information on mcron job specifications.  Below is the reference of the mcron service.

On a running system, you can use the schedule action of the service to visualize the mcron jobs that will be executed next:

     # herd schedule mcron

The example above lists the next five tasks that will be executed, but you can also specify the number of tasks to display:

     # herd schedule mcron 10

 -- Scheme Variable: mcron-service-type
     This is the type of the mcron service, whose value is an mcron-configuration object.

     This service type can be the target of a service extension that provides it additional job specifications (see Dienstkompositionen).  In other words, it is possible to define services that provide additional mcron jobs to run.

 -- Data Type: mcron-configuration
     Data type representing the configuration of mcron.

     mcron (default: MCRON)
          The mcron package to use.

     jobs
          This is a list of gexps (see G-Ausdrücke), where each gexp corresponds to an mcron job specification (see mcron job specifications (GNU mcron)).

Log-Rotation
------------

Log files such as those found in /var/log tend to grow endlessly, so it's a good idea to rotate them once in a while---i.e., archive their contents in separate files, possibly compressed.  The (gnu services admin) module provides an interface to GNU Rot[t]log, a log rotation tool (see GNU Rot[t]log Manual).

The example below defines an operating system that provides log rotation with the default settings, for commonly encountered log files.

     (use-modules (guix) (gnu))
     (use-service-modules admin mcron)
     (use-package-modules base idutils)

     (operating-system
       ;; ...
       (services (cons (service rottlog-service-type)
                       %base-services)))

 -- Scheme Variable: rottlog-service-type
     This is the type of the Rottlog service, whose value is a rottlog-configuration object.

     Other services can extend this one with new log-rotation objects (see below), thereby augmenting the set of files to be rotated.

     This service type can define mcron jobs (see Geplante Auftragsausführung) to run the rottlog service.

 -- Data Type: rottlog-configuration
     Data type representing the configuration of rottlog.

     rottlog (default: rottlog)
          The Rottlog package to use.

     rc-file (default: (file-append rottlog "/etc/rc"))
          The Rottlog configuration file to use (see Mandatory RC Variables (GNU Rot[t]log Manual)).

     rotations (default: %default-rotations)
          A list of log-rotation objects as defined below.

     jobs
          This is a list of gexps where each gexp corresponds to an mcron job specification (see Geplante Auftragsausführung).

 -- Data Type: log-rotation
     Data type representing the rotation of a group of log files.

     Taking an example from the Rottlog manual (see Period Related File Examples (GNU Rot[t]log Manual)), a log rotation might be defined like this:

          (log-rotation
            (frequency 'daily)
            (files '("/var/log/apache/*"))
            (options '("storedir apache-archives"
                       "rotate 6"
                       "notifempty"
                       "nocompress")))

     The list of fields is as follows:

     frequency (default: 'weekly)
          The log rotation frequency, a symbol.

     files
          The list of files or file glob patterns to rotate.

     options (default: '())
          The list of rottlog options for this rotation (see Configuration parameters (GNU Rot[t]lg Manual)).

     post-rotate (default: #f)
          Either #f or a gexp to execute once the rotation has completed.

 -- Scheme Variable: %default-rotations
     Specifies weekly rotation of %ROTATED-FILES and a couple of other files.

 -- Scheme Variable: %rotated-files
     The list of syslog-controlled files to be rotated.  By default it is: '("/var/log/messages" "/var/log/secure").

Netzwerkdienste
---------------

The (gnu services networking) module provides services to configure the network interface.

 -- Scheme Variable: dhcp-client-service-type
     This is the type of services that run DHCP, a Dynamic Host Configuration Protocol (DHCP) client, on all the non-loopback network interfaces.  Its value is the DHCP client package to use, isc-dhcp by default.

 -- Scheme Procedure: dhcpd-service-type
     This type defines a service that runs a DHCP daemon.  To create a service of this type, you must supply a <dhcpd-configuration>.  For example:

          (service dhcpd-service-type
                   (dhcpd-configuration
                    (config-file (local-file "my-dhcpd.conf"))
                    (interfaces '("enp0s25"))))

 -- Data Type: dhcpd-configuration

     package (default: isc-dhcp)
          The package that provides the DHCP daemon.  This package is expected to provide the daemon at sbin/dhcpd relative to its output directory. The default package is the ISC's DHCP server (http://www.isc.org/products/DHCP).

     config-file (default: #f)
          The configuration file to use.  This is required.  It will be passed to dhcpd via its -cf option.  This may be any ``file-like'' object (see file-like objects).  See man dhcpd.conf for details on the configuration file syntax.

     version (default: "4")
          The DHCP version to use.  The ISC DHCP server supports the values ``4'', ``6'', and ``4o6''.  These correspond to the dhcpd program options -4, -6, and -4o6.  See man dhcpd for details.

     run-directory (default: "/run/dhcpd")
          The run directory to use.  At service activation time, this directory will be created if it does not exist.

     pid-file (default: "/run/dhcpd/dhcpd.pid")
          The PID file to use.  This corresponds to the -pf option of dhcpd.  See man dhcpd for details.

     interfaces (default: '())
          The names of the network interfaces on which dhcpd should listen for broadcasts.  If this list is not empty, then its elements (which must be strings) will be appended to the dhcpd invocation when starting the daemon.  It may not be necessary to explicitly specify any interfaces here; see man dhcpd for details.

 -- Scheme Variable: static-networking-service-type
     This is the type for statically-configured network interfaces.

 -- Scheme Procedure: static-networking-service INTERFACE IP
     [#:netmask #f] [#:gateway #f] [#:name-servers '()]  [#:requirement
     '(udev)] Return a service that starts INTERFACE with address IP.  If NETMASK is true, use it as the network mask.  If GATEWAY is true, it must be a string specifying the default network gateway.  REQUIREMENT can be used to declare a dependency on another service before configuring the interface.

     This procedure can be called several times, one for each network interface of interest.  Behind the scenes what it does is extend static-networking-service-type with additional network interfaces to handle.

     Zum Beispiel:

          (static-networking-service "eno1" "192.168.1.82"
                                     #:gateway "192.168.1.2"
                                     #:name-servers '("192.168.1.2"))

 -- Scheme Procedure: wicd-service [#:wicd WICD]
     Return a service that runs Wicd (https://launchpad.net/wicd), a network management daemon that aims to simplify wired and wireless networking.

     This service adds the WICD package to the global profile, providing several commands to interact with the daemon and configure networking: wicd-client, a graphical user interface, and the wicd-cli and wicd-curses user interfaces.

 -- Scheme Variable: modem-manager-service-type
     This is the service type for the ModemManager (https://wiki.gnome.org/Projects/ModemManager) service. The value for this service type is a modem-manager-configuration record.

     This service is part of %desktop-services (see Desktop-Dienste).

 -- Data Type: modem-manager-configuration
     Repräsentiert die Konfiguration vom ModemManager.

     modem-manager (Vorgabe: modem-manager)
          Das ModemManager-Paket, was benutzt werden soll.

 -- Scheme Variable: network-manager-service-type
     This is the service type for the NetworkManager (https://wiki.gnome.org/Projects/NetworkManager) service. The value for this service type is a network-manager-configuration record.

     This service is part of %desktop-services (see Desktop-Dienste).

 -- Data Type: network-manager-configuration
     Data type representing the configuration of NetworkManager.

     network-manager (default: network-manager)
          The NetworkManager package to use.

     dns (default: "default")
          Processing mode for DNS, which affects how NetworkManager uses the resolv.conf configuration file.

          default
               NetworkManager will update resolv.conf to reflect the nameservers provided by currently active connections.

          dnsmasq
               NetworkManager will run dnsmasq as a local caching nameserver, using a "split DNS" configuration if you are connected to a VPN, and then update resolv.conf to point to the local nameserver.

          none
               NetworkManager will not modify resolv.conf.

     vpn-plugins (default: '())
          This is the list of available plugins for virtual private networks (VPNs). An example of this is the network-manager-openvpn package, which allows NetworkManager to manage VPNs via OpenVPN.

 -- Scheme Variable: connman-service-type
     This is the service type to run Connman (https://01.org/connman), a network connection manager.

     Its value must be an connman-configuration record as in this example:

          (service connman-service-type
                   (connman-configuration
                     (disable-vpn? #t)))

     See below for details about connman-configuration.

 -- Data Type: connman-configuration
     Data Type representing the configuration of connman.

     connman (default: CONNMAN)
          The connman package to use.

     disable-vpn? (default: #f)
          When true, disable connman's vpn plugin.

 -- Scheme Variable: wpa-supplicant-service-type
     This is the service type to run WPA supplicant (https://w1.fi/wpa_supplicant/), an authentication daemon required to authenticate against encrypted WiFi or ethernet networks.

 -- Data Type: wpa-supplicant-configuration
     Repräsentiert die Konfiguration des WPA-Supplikanten.

     Sie hat folgende Parameter:

     wpa-supplicant (Vorgabe: wpa-supplicant)
          Das WPA-Supplicant-Paket, was benutzt werden soll.

     dbus? (Vorgabe: #t)
          Whether to listen for requests on D-Bus.

     pid-file (Vorgabe: "/var/run/wpa_supplicant.pid")
          Wo die PID-Datei abgelegt wird.

     interface (Vorgabe: #f)
          If this is set, it must specify the name of a network interface that WPA supplicant will control.

     config-file (default: #f)
          Optionale Konfigurationsdatei.

     extra-options (Vorgabe: '())
          List of additional command-line arguments to pass to the daemon.

 -- Scheme Variable: iptables-service-type
     This is the service type to set up an iptables configuration.  iptables is a packet filtering framework supported by the Linux kernel.  This service supports configuring iptables for both IPv4 and IPv6.  A simple example configuration rejecting all incoming connections except those to the ssh port 22 is shown below.

          (service iptables-service-type
                   (iptables-configuration
                    (ipv4-rules (plain-file "iptables.rules" "*filter
          :INPUT ACCEPT
          :FORWARD ACCEPT
          :OUTPUT ACCEPT
          -A INPUT -p tcp --dport 22 -j ACCEPT
          -A INPUT -j REJECT --reject-with icmp-port-unreachable
          COMMIT
          "))
                    (ipv6-rules (plain-file "ip6tables.rules" "*filter
          :INPUT ACCEPT
          :FORWARD ACCEPT
          :OUTPUT ACCEPT
          -A INPUT -p tcp --dport 22 -j ACCEPT
          -A INPUT -j REJECT --reject-with icmp6-port-unreachable
          COMMIT
          "))))

 -- Datentyp: iptables-configuration
     Repräsentiert die iptables-Konfiguration.

     iptables (Vorgabe: iptables)
          The iptables package that provides iptables-restore and ip6tables-restore.

     ipv4-rules (Vorgabe: %iptables-accept-all-rules)
          The iptables rules to use.  It will be passed to iptables-restore. This may be any ``file-like'' object (see file-like objects).

     ipv6-rules (Vorgabe: %iptables-accept-all-rules)
          The ip6tables rules to use.  It will be passed to ip6tables-restore. This may be any ``file-like'' object (see file-like objects).

 -- Scheme Variable: ntp-service-type
     This is the type of the service running the Network Time Protocol (NTP) (http://www.ntp.org) daemon, ntpd.  The daemon will keep the system clock synchronized with that of the specified NTP servers.

     The value of this service is an ntpd-configuration object, as described below.

 -- Datentyp: ntp-configuration
     Der Datentyp für die Dienstkonfiguration des NTP-Dienstes.

     servers (Vorgabe: %ntp-servers)
          This is the list of servers (host names) with which ntpd will be synchronized.

     allow-large-adjustment? (default: #f)
          This determines whether ntpd is allowed to make an initial adjustment of more than 1,000 seconds.

     ntp (Vorgabe: ntp)
          Das NTP-Paket, was benutzt werden soll.

 -- Scheme Variable: %ntp-servers
     List of host names used as the default NTP servers.  These are servers of the NTP Pool Project (https://www.ntppool.org/en/).

 -- Scheme Procedure: openntpd-service-type
     Run the ntpd, the Network Time Protocol (NTP) daemon, as implemented by OpenNTPD (http://www.openntpd.org).  The daemon will keep the system clock synchronized with that of the given servers.

          (service
           openntpd-service-type
           (openntpd-configuration
            (listen-on '("127.0.0.1" "::1"))
            (sensor '("udcf0 correction 70000"))
            (constraint-from '("www.gnu.org"))
            (constraints-from '("https://www.google.com/"))
            (allow-large-adjustment? #t)))

 -- Data Type: openntpd-configuration

     openntpd (default: (file-append openntpd "/sbin/ntpd"))
          The openntpd executable to use.

     listen-on (default: '("127.0.0.1" "::1"))
          A list of local IP addresses or hostnames the ntpd daemon should listen on.

     query-from (default: '())
          A list of local IP address the ntpd daemon should use for outgoing queries.

     sensor (default: '())
          Specify a list of timedelta sensor devices ntpd should use.  ntpd will listen to each sensor that acutally exists and ignore non-existant ones.  See upstream documentation (https://man.openbsd.org/ntpd.conf) for more information.

     server (default: %NTP-SERVERS)
          Specify a list of IP addresses or hostnames of NTP servers to synchronize to.

     servers (default: '())
          Specify a list of IP addresses or hostnames of NTP pools to synchronize to.

     constraint-from (default: '())
          ntpd can be configured to query the ‘Date’ from trusted HTTPS servers via TLS.  This time information is not used for precision but acts as an authenticated constraint, thereby reducing the impact of unauthenticated NTP man-in-the-middle attacks.  Specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide a constraint.

     constraints-from (default: '())
          As with constraint from, specify a list of URLs, IP addresses or hostnames of HTTPS servers to provide a constraint.  Should the hostname resolve to multiple IP addresses, ntpd will calculate a median constraint from all of them.

     allow-large-adjustment? (default: #f)
          Determines if ntpd is allowed to make an initial adjustment of more than 180 seconds.

 -- Scheme variable: inetd-service-type
     This service runs the inetd (see inetd invocation (GNU Inetutils)) daemon.  inetd listens for connections on internet sockets, and lazily starts the specified server program when a connection is made on one of these sockets.

     The value of this service is an inetd-configuration object.  The following example configures the inetd daemon to provide the built-in echo service, as well as an smtp service which forwards smtp traffic over ssh to a server smtp-server behind a gateway hostname:

          (service
           inetd-service-type
           (inetd-configuration
            (entries (list
                      (inetd-entry
                       (name "echo")
                       (socket-type 'stream)
                       (protocol "tcp")
                       (wait? #f)
                       (user "root"))
                      (inetd-entry
                       (node "127.0.0.1")
                       (name "smtp")
                       (socket-type 'stream)
                       (protocol "tcp")
                       (wait? #f)
                       (user "root")
                       (program (file-append openssh "/bin/ssh"))
                       (arguments
                        '("ssh" "-qT" "-i" "/path/to/ssh_key"
                          "-W" "smtp-server:25" "user@hostname")))))

     See below for more details about inetd-configuration.

 -- Data Type: inetd-configuration
     Data type representing the configuration of inetd.

     program (default: (file-append inetutils "/libexec/inetd"))
          The inetd executable to use.

     entries (default: '())
          A list of inetd service entries.  Each entry should be created by the inetd-entry constructor.

 -- Data Type: inetd-entry
     Data type representing an entry in the inetd configuration.  Each entry corresponds to a socket where inetd will listen for requests.

     node (Vorgabe: #f)
          Optional string, a comma-separated list of local addresses inetd should use when listening for this service.  See Configuration file (GNU Inetutils) for a complete description of all options.

     name
          A string, the name must correspond to an entry in /etc/services.

     socket-type
          One of 'stream, 'dgram, 'raw, 'rdm or 'seqpacket.

     protocol
          A string, must correspond to an entry in /etc/protocols.

     wait? (Vorgabe: #t)
          Whether inetd should wait for the server to exit before listening to new service requests.

     user
          A string containing the user (and, optionally, group) name of the user as whom the server should run.  The group name can be specified in a suffix, separated by a colon or period, i.e. "user", "user:group" or "user.group".

     program (default: "internal")
          The server program which will serve the requests, or "internal" if inetd should use a built-in service.

     arguments (Vorgabe: '())
          A list strings or file-like objects, which are the server program's arguments, starting with the zeroth argument, i.e. the name of the program itself.  For inetd's internal services, this entry must be '() or '("internal").

     See Configuration file (GNU Inetutils) for a more detailed discussion of each configuration field.

 -- Scheme Variable: tor-service-type
     This is the type for a service that runs the Tor (https://torproject.org) anonymous networking daemon.  The service is configured using a <tor-configuration> record.  By default, the Tor daemon runs as the tor unprivileged user, which is a member of the tor group.

 -- Datentyp: tor-configuration

     tor (Vorgabe: tor)
          The package that provides the Tor daemon.  This package is expected to provide the daemon at bin/tor relative to its output directory.  The default package is the Tor Project's (https://www.torproject.org) implementation.

     config-file (Vorgabe: (plain-file "empty" ""))
          The configuration file to use.  It will be appended to a default configuration file, and the final configuration file will be passed to tor via its -f option.  This may be any ``file-like'' object (see file-like objects).  See man tor for details on the configuration file syntax.

     hidden-services (Vorgabe: '())
          The list of <hidden-service> records to use.  For any hidden service you include in this list, appropriate configuration to enable the hidden service will be automatically added to the default configuration file.  You may conveniently create <hidden-service> records using the tor-hidden-service procedure described below.

     socks-socket-type (Vorgabe: 'tcp)
          The default socket type that Tor should use for its SOCKS socket.  This must be either 'tcp or 'unix.  If it is 'tcp, then by default Tor will listen on TCP port 9050 on the loopback interface (i.e., localhost).  If it is 'unix, then Tor will listen on the UNIX domain socket /var/run/tor/socks-sock, which will be made writable by members of the tor group.

          If you want to customize the SOCKS socket in more detail, leave socks-socket-type at its default value of 'tcp and use config-file to override the default by providing your own SocksPort option.

 -- Scheme Procedure: tor-hidden-service NAME MAPPING
     Define a new Tor hidden service called NAME and implementing MAPPING.  MAPPING is a list of port/host tuples, such as:

           '((22 "127.0.0.1:22")
             (80 "127.0.0.1:8080"))

     In this example, port 22 of the hidden service is mapped to local port 22, and port 80 is mapped to local port 8080.

     This creates a /var/lib/tor/hidden-services/NAME directory, where the hostname file contains the .onion host name for the hidden service.

     See the Tor project's documentation (https://www.torproject.org/docs/tor-hidden-service.html.en) for more information.

The (gnu services rsync) module provides the following services:

You might want an rsync daemon if you have files that you want available so anyone (or just yourself) can download existing files or upload new files.

 -- Scheme Variable: rsync-service-type
     This is the type for the rsync (https://rsync.samba.org) rsync daemon, rsync-configuration record as in this example:

          (service rsync-service-type)

     See below for details about rsync-configuration.

 -- Data Type: rsync-configuration
     Data type representing the configuration for rsync-service.

     package (default: RSYNC)
          rsync package to use.

     port-number (default: 873)
          TCP port on which rsync listens for incoming connections.  If port is less than 1024 rsync needs to be started as the root user and group.

     pid-file (default: "/var/run/rsyncd/rsyncd.pid")
          Name of the file where rsync writes its PID.

     lock-file (default: "/var/run/rsyncd/rsyncd.lock")
          Name of the file where rsync writes its lock file.

     log-file (default: "/var/log/rsyncd.log")
          Name of the file where rsync writes its log file.

     use-chroot? (default: #T)
          Whether to use chroot for rsync shared directory.

     share-path (default: /srv/rsync)
          Location of the rsync shared directory.

     share-comment (default: "Rsync share")
          Comment of the rsync shared directory.

     read-only? (default: #F)
          Read-write permissions to shared directory.

     timeout (default: 300)
          I/O timeout in seconds.

     user (default: "ROOT")
          Owner of the rsync process.

     group (default: "ROOT")
          Group of the rsync process.

     uid (default: "RSYNCD")
          User name or user ID that file transfers to and from that module should take place as when the daemon was run as root.

     gid (default: "RSYNCD")
          Group name or group ID that will be used when accessing the module.

Furthermore, (gnu services ssh) provides the following services.

 -- Scheme Procedure: lsh-service [#:host-key "/etc/lsh/host-key"]
     [#:daemonic? #t] [#:interfaces '()] [#:port-number 22]
     [#:allow-empty-passwords? #f] [#:root-login? #f]  [#:syslog-output? #t]
     [#:x11-forwarding? #t]  [#:tcp/ip-forwarding? #t] [#:password-authentication? #t]  [#:public-key-authentication? #t] [#:initialize? #t] Run the lshd program from LSH to listen on port PORT-NUMBER.  HOST-KEY must designate a file containing the host key, and readable only by root.

     When DAEMONIC? is true, lshd will detach from the controlling terminal and log its output to syslogd, unless one sets SYSLOG-OUTPUT? to false.  Obviously, it also makes lsh-service depend on existence of syslogd service.  When PID-FILE? is true, lshd writes its PID to the file called PID-FILE.

     When INITIALIZE? is true, automatically create the seed and host key upon service activation if they do not exist yet.  This may take long and require interaction.

     When INITIALIZE? is false, it is up to the user to initialize the randomness generator (see lsh-make-seed (LSH Manual)), and to create a key pair with the private key stored in file HOST-KEY (see lshd basics (LSH Manual)).

     When INTERFACES is empty, lshd listens for connections on all the network interfaces; otherwise, INTERFACES must be a list of host names or addresses.

     ALLOW-EMPTY-PASSWORDS? specifies whether to accept log-ins with empty passwords, and ROOT-LOGIN? specifies whether to accept log-ins as root.

     The other options should be self-descriptive.

 -- Scheme Variable: openssh-service-type
     This is the type for the OpenSSH (http://www.openssh.org) secure shell daemon, sshd.  Its value must be an openssh-configuration record as in this example:

          (service openssh-service-type
                   (openssh-configuration
                     (x11-forwarding? #t)
                     (permit-root-login 'without-password)
                     (authorized-keys
                       `(("alice" ,(local-file "alice.pub"))
                         ("bob" ,(local-file "bob.pub"))))))

     See below for details about openssh-configuration.

     This service can be extended with extra authorized keys, as in this example:

          (service-extension openssh-service-type
                             (const `(("charlie"
                                       ,(local-file "charlie.pub")))))

 -- Data Type: openssh-configuration
     This is the configuration record for OpenSSH's sshd.

     pid-file (default: "/var/run/sshd.pid")
          Name of the file where sshd writes its PID.

     port-number (default: 22)
          TCP port on which sshd listens for incoming connections.

     permit-root-login (default: #f)
          This field determines whether and when to allow logins as root.  If #f, root logins are disallowed; if #t, they are allowed.  If it's the symbol 'without-password, then root logins are permitted but not with password-based authentication.

     allow-empty-passwords? (default: #f)
          When true, users with empty passwords may log in.  When false, they may not.

     password-authentication? (default: #t)
          When true, users may log in with their password.  When false, they have other authentication methods.

     public-key-authentication? (default: #t)
          When true, users may log in using public key authentication.  When false, users have to use other authentication method.

          Authorized public keys are stored in ~/.ssh/authorized_keys.  This is used only by protocol version 2.

     x11-forwarding? (default: #f)
          When true, forwarding of X11 graphical client connections is enabled---in other words, ssh options -X and -Y will work.

     allow-agent-forwarding? (Vorgabe: #t)
          Whether to allow agent forwarding.

     allow-tcp-forwarding? (Vorgabe: #t)
          Whether to allow TCP forwarding.

     gateway-ports? (Vorgabe: #f)
          Whether to allow gateway ports.

     challenge-response-authentication? (default: #f)
          Specifies whether challenge response authentication is allowed (e.g. via PAM).

     use-pam? (default: #t)
          Enables the Pluggable Authentication Module interface.  If set to #t, this will enable PAM authentication using challenge-response-authentication? and password-authentication?, in addition to PAM account and session module processing for all authentication types.

          Because PAM challenge response authentication usually serves an equivalent role to password authentication, you should disable either challenge-response-authentication? or password-authentication?.

     print-last-log? (default: #t)
          Specifies whether sshd should print the date and time of the last user login when a user logs in interactively.

     subsystems (default: '(("sftp" "internal-sftp")))
          Configures external subsystems (e.g. file transfer daemon).

          This is a list of two-element lists, each of which containing the subsystem name and a command (with optional arguments) to execute upon subsystem request.

          The command internal-sftp implements an in-process SFTP server. Alternately, one can specify the sftp-server command:

               (service openssh-service-type
                        (openssh-configuration
                         (subsystems
                          `(("sftp" ,(file-append openssh "/libexec/sftp-server"))))))

     accepted-environment (default: '())
          List of strings describing which environment variables may be exported.

          Each string gets on its own line.  See the AcceptEnv option in man sshd_config.

          This example allows ssh-clients to export the COLORTERM variable.  It is set by terminal emulators, which support colors.  You can use it in your shell's ressource file to enable colors for the prompt and commands if this variable is set.

               (service openssh-service-type
                        (openssh-configuration
                          (accepted-environment '("COLORTERM"))))

     authorized-keys (default: '())
          This is the list of authorized keys.  Each element of the list is a user name followed by one or more file-like objects that represent SSH public keys.  For example:

               (openssh-configuration
                 (authorized-keys
                   `(("rekado" ,(local-file "rekado.pub"))
                     ("chris" ,(local-file "chris.pub"))
                     ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub")))))

          registers the specified public keys for user accounts rekado, chris, and root.

          Additional authorized keys can be specified via service-extension.

          Note that this does not interfere with the use of ~/.ssh/authorized_keys.

     log-level (Vorgabe: 'info)
          This is a symbol specifying the logging level: quiet, fatal, error, info, verbose, debug, etc.  See the man page for sshd_config for the full list of level names.

     extra-content (Vorgabe: "")
          This field can be used to append arbitrary text to the configuration file. It is especially useful for elaborate configurations that cannot be expressed otherwise.  This configuration, for example, would generally disable root logins, but permit them from one specific IP address:

               (openssh-configuration
                 (extra-content "\
               Match Address 192.168.0.1
                 PermitRootLogin yes"))

 -- Scheme Procedure: dropbear-service [CONFIG]
     Run the Dropbear SSH daemon (https://matt.ucc.asn.au/dropbear/dropbear.html) with the given CONFIG, a <dropbear-configuration> object.

     For example, to specify a Dropbear service listening on port 1234, add this call to the operating system's services field:

          (dropbear-service (dropbear-configuration
                              (port-number 1234)))

 -- Data Type: dropbear-configuration
     This data type represents the configuration of a Dropbear SSH daemon.

     dropbear (default: DROPBEAR)
          The Dropbear package to use.

     port-number (default: 22)
          The TCP port where the daemon waits for incoming connections.

     syslog-output? (default: #t)
          Whether to enable syslog output.

     pid-file (default: "/var/run/dropbear.pid")
          File name of the daemon's PID file.

     root-login? (default: #f)
          Whether to allow root logins.

     allow-empty-passwords? (default: #f)
          Whether to allow empty passwords.

     password-authentication? (default: #t)
          Whether to enable password-based authentication.

 -- Scheme Variable: %facebook-host-aliases
     This variable contains a string for use in /etc/hosts (see Host Names (The GNU C Library Reference Manual)).  Each line contains a entry that maps a known server name of the Facebook on-line service---e.g., www.facebook.com---to the local host---127.0.0.1 or its IPv6 equivalent, ::1.

     This variable is typically used in the hosts-file field of an operating-system declaration (see /etc/hosts):

          (use-modules (gnu) (guix))

          (operating-system
            (host-name "mymachine")
            ;; ...
            (hosts-file
              ;; Create a /etc/hosts file with aliases for "localhost"
              ;; and "mymachine", as well as for Facebook servers.
              (plain-file "hosts"
                          (string-append (local-host-aliases host-name)
                                         %facebook-host-aliases))))

     This mechanism can prevent programs running locally, such as Web browsers, from accessing Facebook.

The (gnu services avahi) provides the following definition.

 -- Scheme Variable: avahi-service-type
     This is the service that runs avahi-daemon, a system-wide mDNS/DNS-SD responder that allows for service discovery and ``zero-configuration'' host name lookups (see http://avahi.org/). Its value must be a zero-configuration record---see below.

     This service extends the name service cache daemon (nscd) so that it can resolve .local host names using nss-mdns (http://0pointer.de/lennart/projects/nss-mdns/).  See Name Service Switch, for information on host name resolution.

     Additionally, add the AVAHI package to the system profile so that commands such as avahi-browse are directly usable.

 -- Data Type: avahi-configuration
     Data type representation the configuration for Avahi.

     host-name (default: #f)
          If different from #f, use that as the host name to publish for this machine; otherwise, use the machine's actual host name.

     publish? (default: #t)
          When true, allow host names and services to be published (broadcast) over the network.

     publish-workstation? (default: #t)
          When true, avahi-daemon publishes the machine's host name and IP address via mDNS on the local network.  To view the host names published on your local network, you can run:

               avahi-browse _workstation._tcp

     wide-area? (default: #f)
          When true, DNS-SD over unicast DNS is enabled.

     ipv4? (default: #t)
     ipv6? (default: #t)
          These fields determine whether to use IPv4/IPv6 sockets.

     domains-to-browse (default: '())
          This is a list of domains to browse.

 -- Scheme Variable: openvswitch-service-type
     This is the type of the Open vSwitch (http://www.openvswitch.org) service, whose value should be an openvswitch-configuration object.

 -- Data Type: openvswitch-configuration
     Data type representing the configuration of Open vSwitch, a multilayer virtual switch which is designed to enable massive network automation through programmatic extension.

     package (default: OPENVSWITCH)
          Package object of the Open vSwitch.

X Window
--------

Support for the X Window graphical display system---specifically Xorg---is provided by the (gnu services xorg) module.  Note that there is no xorg-service procedure.  Instead, the X server is started by the login manager, by default SLiM.

To use X11, you must install at least one window manager---for example the windowmaker or openbox packages---preferably by adding it to the packages field of your operating system definition (see system-wide packages).

 -- Scheme Variable: slim-service-type
     This is the type for the SLiM graphical login manager for X11.

     SLiM looks for session types described by the .desktop files in /run/current-system/profile/share/xsessions and allows users to choose a session from the log-in screen using F1.  Packages such as xfce, sawfish, and ratpoison provide .desktop files; adding them to the system-wide set of packages automatically makes them available at the log-in screen.

     In addition, ~/.xsession files are honored.  When available, ~/.xsession must be an executable that starts a window manager and/or other X clients.

 -- Data Type: slim-configuration
     Data type representing the configuration of slim-service-type.

     allow-empty-passwords? (Vorgabe: #t)
          Whether to allow logins with empty passwords.

     auto-login? (default: #f)
     default-user (default: "")
          When auto-login? is false, SLiM presents a log-in screen.

          When auto-login? is true, SLiM logs in directly as default-user.

     theme (default: %default-slim-theme)
     theme-name (default: %default-slim-theme-name)
          The graphical theme to use and its name.

     auto-login-session (default: #f)
          If true, this must be the name of the executable to start as the default session---e.g., (file-append windowmaker "/bin/windowmaker").

          If false, a session described by one of the available .desktop files in /run/current-system/profile and ~/.guix-profile will be used.

               You must install at least one window manager in the system profile or in your user profile.  Failing to do that, if auto-login-session is false, you will be unable to log in.

     startx (default: (xorg-start-command))
          The command used to start the X11 graphical server.

     xauth (default: xauth)
          The XAuth package to use.

     shepherd (default: shepherd)
          The Shepherd package used when invoking halt and reboot.

     sessreg (default: sessreg)
          The sessreg package used in order to register the session.

     slim (default: slim)
          The SLiM package to use.

 -- Scheme Variable: %default-theme
 -- Scheme Variable: %default-theme-name
     The default SLiM theme and its name.

 -- Data Type: sddm-configuration
     This is the data type representing the sddm service configuration.

     display-server (default: "x11")
          Select display server to use for the greeter. Valid values are "x11" or "wayland".

     numlock (default: "on")
          Valid values are "on", "off" or "none".

     halt-command (default #~(string-apppend #$shepherd "/sbin/halt"))
          Command to run when halting.

     reboot-command (default #~(string-append #$shepherd "/sbin/reboot"))
          Command to run when rebooting.

     theme (default "maldives")
          Theme to use. Default themes provided by SDDM are "elarun" or "maldives".

     themes-directory (default "/run/current-system/profile/share/sddm/themes")
          Directory to look for themes.

     faces-directory (default "/run/current-system/profile/share/sddm/faces")
          Directory to look for faces.

     default-path (default "/run/current-system/profile/bin")
          Default PATH to use.

     minimum-uid (default 1000)
          Minimum UID to display in SDDM.

     maximum-uid (default 2000)
          Maximum UID to display in SDDM

     remember-last-user? (default #t)
          Remember last user.

     remember-last-session? (default #t)
          Remember last session.

     hide-users (default "")
          Usernames to hide from SDDM greeter.

     hide-shells (default #~(string-append #$shadow "/sbin/nologin"))
          Users with shells listed will be hidden from the SDDM greeter.

     session-command (default #~(string-append #$sddm "/share/sddm/scripts/wayland-session"))
          Script to run before starting a wayland session.

     sessions-directory (default "/run/current-system/profile/share/wayland-sessions")
          Directory to look for desktop files starting wayland sessions.

     xorg-server-path (default xorg-start-command)
          Path to xorg-server.

     xauth-path (default #~(string-append #$xauth "/bin/xauth"))
          Path to xauth.

     xephyr-path (default #~(string-append #$xorg-server "/bin/Xephyr"))
          Path to Xephyr.

     xdisplay-start (default #~(string-append #$sddm "/share/sddm/scripts/Xsetup"))
          Script to run after starting xorg-server.

     xdisplay-stop (default #~(string-append #$sddm "/share/sddm/scripts/Xstop"))
          Script to run before stopping xorg-server.

     xsession-command (Vorgabe: xinitrc)
          Script to run before starting a X session.

     xsessions-directory (default: "/run/current-system/profile/share/xsessions")
          Directory to look for desktop files starting X sessions.

     minimum-vt (default: 7)
          Minimum VT to use.

     xserver-arguments (default "-nolisten tcp")
          Arguments to pass to xorg-server.

     auto-login-user (default "")
          User to use for auto-login.

     auto-login-session (default "")
          Desktop file to use for auto-login.

     relogin? (default #f)
          Relogin after logout.

 -- Scheme Procedure: sddm-service config
     Return a service that spawns the SDDM graphical login manager for config of type <sddm-configuration>.

            (sddm-service (sddm-configuration
                           (auto-login-user "Alice")
                           (auto-login-session "xfce.desktop")))

 -- Scheme Procedure: xorg-start-command [#:guile]
     [#:modules %default-xorg-modules]  [#:fonts %default-xorg-fonts]
     [#:configuration-file (xorg-configuration-file ...)]  [#:xorg-server
     XORG-SERVER] [#:xserver-arguments '("-nolisten" "tcp")] Return a startx script in which MODULES, a list of X module packages, and FONTS, a list of X font directories, are available.  See xorg-wrapper for more details on the arguments.  The result should be used in place of startx.

     Usually the X server is started by a login manager.

This procedure is useful to override command line options for the X server, such as having it listen to over TCP:

     (operating-system
       ...
       (services
         (modify-services %desktop-services
           (slim-service-type config =>
             (slim-configuration
               (inherit config)
               (startx (xorg-start-command
                        #:xserver-arguments '("-listen" "tcp"))))))))

 -- Scheme Procedure: xorg-configuration-file
     [#:modules %default-xorg-modules]  [#:fonts %default-xorg-fonts]
     [#:drivers '()] [#:resolutions '()] [#:extra-config '()] Return a
     configuration file for the Xorg server containing search paths for all the common drivers.

     MODULES must be a list of module packages loaded by the Xorg server---e.g., xf86-video-vesa, xf86-input-keyboard, and so on.  FONTS must be a list of font directories to add to the server's font path.

     DRIVERS must be either the empty list, in which case Xorg chooses a graphics driver automatically, or a list of driver names that will be tried in this order---e.g., ("modesetting" "vesa").

     Likewise, when RESOLUTIONS is the empty list, Xorg chooses an appropriate screen resolution; otherwise, it must be a list of resolutions---e.g., ((1024 768) (640 480)).

     Last, EXTRA-CONFIG is a list of strings or objects appended to the configuration file.  It is used to pass extra text to be added verbatim to the configuration file.

     This procedure is especially useful to configure a different keyboard layout than the default US keymap.  For instance, to use the ``bépo'' keymap by default on the display manager:

          (define bepo-evdev
            "Section \"InputClass\"
                  Identifier \"evdev keyboard catchall\"
                  Driver \"evdev\"
                  MatchIsKeyboard \"on\"
                  Option \"xkb_layout\" \"fr\"
                  Option \"xkb_variant\" \"bepo\"
          EndSection")

          (operating-system
            ...
            (services
              (modify-services %desktop-services
                (slim-service-type config =>
                  (slim-configuration
                    (inherit config)
                    (startx (xorg-start-command
                             #:configuration-file
                             (xorg-configuration-file
                               #:extra-config
                               (list bepo-evdev)))))))))

     The MatchIsKeyboard line specifies that we only apply the configuration to keyboards.  Without this line, other devices such as touchpad may not work correctly because they will be attached to the wrong driver.  In this example, the user typically used setxkbmap fr bepo to set their favorite keymap once logged in.  The first argument corresponds to the layout, while the second argument corresponds to the variant.  The xkb_variant line can be omitted to select the default variant.

 -- Scheme Procedure: screen-locker-service PACKAGE [PROGRAM]
     Add PACKAGE, a package for a screen locker or screen saver whose command is PROGRAM, to the set of setuid programs and add a PAM entry for it.  For example:

          (screen-locker-service xlockmore "xlock")

     makes the good ol' XlockMore usable.

Druckdienste
------------

The (gnu services cups) module provides a Guix service definition for the CUPS printing service.  To add printer support to a Guix system, add a cups-service to the operating system definition:

 -- Scheme Variable: cups-service-type
     The service type for the CUPS print server.  Its value should be a valid CUPS configuration (see below).  To use the default settings, simply write:

          (service cups-service-type)

The CUPS configuration controls the basic things about your CUPS installation: what interfaces it listens on, what to do if a print job fails, how much logging to do, and so on.  To actually add a printer, you have to visit the http://localhost:631 URL, or use a tool such as GNOME's printer configuration services.  By default, configuring a CUPS service will generate a self-signed certificate if needed, for secure connections to the print server.

Suppose you want to enable the Web interface of CUPS and also add support for Epson printers via the escpr package and for HP printers via the hplip-minimal package.  You can do that directly, like this (you need to use the (gnu packages cups) module):

     (service cups-service-type
              (cups-configuration
                (web-interface? #t)
                (extensions
                  (list cups-filters escpr hplip-minimal))))

Note: If you wish to use the Qt5 based GUI which comes with the hplip package then it is suggested that you install the hplip package, either in your OS configuration file or as your user.

The available configuration parameters follow.  Each parameter definition is preceded by its type; for example, string-list foo indicates that the foo parameter should be specified as a list of strings.  There is also a way to specify the configuration as a string, if you have an old cupsd.conf file that you want to port over from some other system; see the end for more details.

Available cups-configuration fields are:

 -- cups-configuration parameter: package cups
     The CUPS package.

 -- cups-configuration parameter: package-list extensions
     Drivers and other extensions to the CUPS package.

 -- cups-configuration parameter: files-configuration files-configuration
     Configuration of where to write logs, what directories to use for print spools, and related privileged configuration parameters.

     Available files-configuration fields are:

      -- files-configuration parameter: log-location access-log
          Defines the access log filename.  Specifying a blank filename disables access log generation.  The value stderr causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background.  The value syslog causes log entries to be sent to the system log daemon. The server name may be included in filenames using the string %s, as in /var/log/cups/%s-access_log.

          Defaults to "/var/log/cups/access_log".

      -- files-configuration parameter: file-name cache-dir
          Where CUPS should cache data.

          Defaults to "/var/cache/cups".

      -- files-configuration parameter: string config-file-perm
          Specifies the permissions for all configuration files that the scheduler writes.

          Note that the permissions for the printers.conf file are currently masked to only allow access from the scheduler user (typically root).  This is done because printer device URIs sometimes contain sensitive authentication information that should not be generally known on the system.  There is no way to disable this security feature.

          Defaults to "0640".

      -- files-configuration parameter: log-location error-log
          Defines the error log filename.  Specifying a blank filename disables access log generation.  The value stderr causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background.  The value syslog causes log entries to be sent to the system log daemon.  The server name may be included in filenames using the string %s, as in /var/log/cups/%s-error_log.

          Defaults to "/var/log/cups/error_log".

      -- files-configuration parameter: string fatal-errors
          Specifies which errors are fatal, causing the scheduler to exit.  The kind strings are:

          none
               No errors are fatal.

          all
               All of the errors below are fatal.

          browse
               Browsing initialization errors are fatal, for example failed connections to the DNS-SD daemon.

          config
               Configuration file syntax errors are fatal.

          listen
               Listen or Port errors are fatal, except for IPv6 failures on the loopback or any addresses.

          log
               Log file creation or write errors are fatal.

          permissions
               Bad startup file permissions are fatal, for example shared TLS certificate and key files with world-read permissions.

          Defaults to "all -browse".

      -- files-configuration parameter: boolean file-device?
          Specifies whether the file pseudo-device can be used for new printer queues.  The URI file:///dev/null is always allowed.

          Defaults to #f.

      -- files-configuration parameter: string group
          Specifies the group name or ID that will be used when executing external programs.

          Defaults to "lp".

      -- files-configuration parameter: string log-file-perm
          Specifies the permissions for all log files that the scheduler writes.

          Defaults to "0644".

      -- files-configuration parameter: log-location page-log
          Defines the page log filename.  Specifying a blank filename disables access log generation.  The value stderr causes log entries to be sent to the standard error file when the scheduler is running in the foreground, or to the system log daemon when run in the background.  The value syslog causes log entries to be sent to the system log daemon.  The server name may be included in filenames using the string %s, as in /var/log/cups/%s-page_log.

          Defaults to "/var/log/cups/page_log".

      -- files-configuration parameter: string remote-root
          Specifies the username that is associated with unauthenticated accesses by clients claiming to be the root user.  The default is remroot.

          Defaults to "remroot".

      -- files-configuration parameter: file-name request-root
          Specifies the directory that contains print jobs and other HTTP request data.

          Defaults to "/var/spool/cups".

      -- files-configuration parameter: sandboxing sandboxing
          Specifies the level of security sandboxing that is applied to print filters, backends, and other child processes of the scheduler; either relaxed or strict.  This directive is currently only used/supported on macOS.

          Defaults to strict.

      -- files-configuration parameter: file-name server-keychain
          Specifies the location of TLS certificates and private keys.  CUPS will look for public and private keys in this directory: a .crt files for PEM-encoded certificates and corresponding .key files for PEM-encoded private keys.

          Defaults to "/etc/cups/ssl".

      -- files-configuration parameter: file-name server-root
          Specifies the directory containing the server configuration files.

          Defaults to "/etc/cups".

      -- files-configuration parameter: boolean sync-on-close?
          Specifies whether the scheduler calls fsync(2) after writing configuration or state files.

          Defaults to #f.

      -- files-configuration parameter: space-separated-string-list system-group
          Specifies the group(s) to use for @SYSTEM group authentication.

      -- files-configuration parameter: file-name temp-dir
          Specifies the directory where temporary files are stored.

          Defaults to "/var/spool/cups/tmp".

      -- files-configuration parameter: string user
          Specifies the user name or ID that is used when running external programs.

          Defaults to "lp".

 -- cups-configuration parameter: access-log-level access-log-level
     Specifies the logging level for the AccessLog file.  The config level logs when printers and classes are added, deleted, or modified and when configuration files are accessed or updated.  The actions level logs when print jobs are submitted, held, released, modified, or canceled, and any of the conditions for config.  The all level logs all requests.

     Defaults to actions.

 -- cups-configuration parameter: boolean auto-purge-jobs?
     Specifies whether to purge job history data automatically when it is no longer required for quotas.

     Defaults to #f.

 -- cups-configuration parameter: browse-local-protocols browse-local-protocols
     Specifies which protocols to use for local printer sharing.

     Defaults to dnssd.

 -- cups-configuration parameter: boolean browse-web-if?
     Specifies whether the CUPS web interface is advertised.

     Defaults to #f.

 -- cups-configuration parameter: boolean browsing?
     Specifies whether shared printers are advertised.

     Defaults to #f.

 -- cups-configuration parameter: string classification
     Specifies the security classification of the server.  Any valid banner name can be used, including "classified", "confidential", "secret", "topsecret", and "unclassified", or the banner can be omitted to disable secure printing functions.

     Defaults to "".

 -- cups-configuration parameter: boolean classify-override?
     Specifies whether users may override the classification (cover page) of individual print jobs using the job-sheets option.

     Defaults to #f.

 -- cups-configuration parameter: default-auth-type default-auth-type
     Specifies the default type of authentication to use.

     Defaults to Basic.

 -- cups-configuration parameter: default-encryption default-encryption
     Specifies whether encryption will be used for authenticated requests.

     Defaults to Required.

 -- cups-configuration parameter: string default-language
     Specifies the default language to use for text and web content.

     Defaults to "en".

 -- cups-configuration parameter: string default-paper-size
     Specifies the default paper size for new print queues.  "Auto" uses a locale-specific default, while "None" specifies there is no default paper size.  Specific size names are typically "Letter" or "A4".

     Defaults to "Auto".

 -- cups-configuration parameter: string default-policy
     Specifies the default access policy to use.

     Defaults to "default".

 -- cups-configuration parameter: boolean default-shared?
     Specifies whether local printers are shared by default.

     Defaults to #t.

 -- cups-configuration parameter: non-negative-integer dirty-clean-interval
     Specifies the delay for updating of configuration and state files, in seconds.  A value of 0 causes the update to happen as soon as possible, typically within a few milliseconds.

     Defaults to 30.

 -- cups-configuration parameter: error-policy error-policy
     Specifies what to do when an error occurs.  Possible values are abort-job, which will discard the failed print job; retry-job, which will retry the job at a later time; retry-this-job, which retries the failed job immediately; and stop-printer, which stops the printer.

     Defaults to stop-printer.

 -- cups-configuration parameter: non-negative-integer filter-limit
     Specifies the maximum cost of filters that are run concurrently, which can be used to minimize disk, memory, and CPU resource problems.  A limit of 0 disables filter limiting.  An average print to a non-PostScript printer needs a filter limit of about 200.  A PostScript printer needs about half that (100).  Setting the limit below these thresholds will effectively limit the scheduler to printing a single job at any time.

     Defaults to 0.

 -- cups-configuration parameter: non-negative-integer filter-nice
     Specifies the scheduling priority of filters that are run to print a job. The nice value ranges from 0, the highest priority, to 19, the lowest priority.

     Defaults to 0.

 -- cups-configuration parameter: host-name-lookups host-name-lookups
     Specifies whether to do reverse lookups on connecting clients.  The double setting causes cupsd to verify that the hostname resolved from the address matches one of the addresses returned for that hostname.  Double lookups also prevent clients with unregistered addresses from connecting to your server.  Only set this option to #t or double if absolutely required.

     Defaults to #f.

 -- cups-configuration parameter: non-negative-integer job-kill-delay
     Specifies the number of seconds to wait before killing the filters and backend associated with a canceled or held job.

     Defaults to 30.

 -- cups-configuration parameter: non-negative-integer job-retry-interval
     Specifies the interval between retries of jobs in seconds.  This is typically used for fax queues but can also be used with normal print queues whose error policy is retry-job or retry-current-job.

     Defaults to 30.

 -- cups-configuration parameter: non-negative-integer job-retry-limit
     Specifies the number of retries that are done for jobs.  This is typically used for fax queues but can also be used with normal print queues whose error policy is retry-job or retry-current-job.

     Defaults to 5.

 -- cups-configuration parameter: boolean keep-alive?
     Specifies whether to support HTTP keep-alive connections.

     Defaults to #t.

 -- cups-configuration parameter: non-negative-integer keep-alive-timeout
     Specifies how long an idle client connection remains open, in seconds.

     Defaults to 30.

 -- cups-configuration parameter: non-negative-integer limit-request-body
     Specifies the maximum size of print files, IPP requests, and HTML form data.  A limit of 0 disables the limit check.

     Defaults to 0.

 -- cups-configuration parameter: multiline-string-list listen
     Listens on the specified interfaces for connections.  Valid values are of the form ADDRESS:PORT, where ADDRESS is either an IPv6 address enclosed in brackets, an IPv4 address, or * to indicate all addresses.  Values can also be file names of local UNIX domain sockets.  The Listen directive is similar to the Port directive but allows you to restrict access to specific interfaces or networks.

 -- cups-configuration parameter: non-negative-integer listen-back-log
     Specifies the number of pending connections that will be allowed.  This normally only affects very busy servers that have reached the MaxClients limit, but can also be triggered by large numbers of simultaneous connections.  When the limit is reached, the operating system will refuse additional connections until the scheduler can accept the pending ones.

     Defaults to 128.

 -- cups-configuration parameter: location-access-control-list location-access-controls
     Specifies a set of additional access controls.

     Available location-access-controls fields are:

      -- location-access-controls parameter: file-name path
          Specifies the URI path to which the access control applies.

      -- location-access-controls parameter: access-control-list access-controls
          Access controls for all access to this path, in the same format as the access-controls of operation-access-control.

          Defaults to ().

      -- location-access-controls parameter: method-access-control-list method-access-controls
          Access controls for method-specific access to this path.

          Defaults to ().

          Available method-access-controls fields are:

           -- method-access-controls parameter: boolean reverse?
               If #t, apply access controls to all methods except the listed methods.  Otherwise apply to only the listed methods.

               Defaults to #f.

           -- method-access-controls parameter: method-list methods
               Methods to which this access control applies.

               Defaults to ().

           -- method-access-controls parameter: access-control-list access-controls
               Access control directives, as a list of strings.  Each string should be one directive, such as "Order allow,deny".

               Defaults to ().

 -- cups-configuration parameter: non-negative-integer log-debug-history
     Specifies the number of debugging messages that are retained for logging if an error occurs in a print job.  Debug messages are logged regardless of the LogLevel setting.

     Defaults to 100.

 -- cups-configuration parameter: log-level log-level
     Specifies the level of logging for the ErrorLog file.  The value none stops all logging while debug2 logs everything.

     Defaults to info.

 -- cups-configuration parameter: log-time-format log-time-format
     Specifies the format of the date and time in the log files.  The value standard logs whole seconds while usecs logs microseconds.

     Defaults to standard.

 -- cups-configuration parameter: non-negative-integer max-clients
     Specifies the maximum number of simultaneous clients that are allowed by the scheduler.

     Defaults to 100.

 -- cups-configuration parameter: non-negative-integer max-clients-per-host
     Specifies the maximum number of simultaneous clients that are allowed from a single address.

     Defaults to 100.

 -- cups-configuration parameter: non-negative-integer max-copies
     Specifies the maximum number of copies that a user can print of each job.

     Defaults to 9999.

 -- cups-configuration parameter: non-negative-integer max-hold-time
     Specifies the maximum time a job may remain in the indefinite hold state before it is canceled.  A value of 0 disables cancellation of held jobs.

     Defaults to 0.

 -- cups-configuration parameter: non-negative-integer max-jobs
     Specifies the maximum number of simultaneous jobs that are allowed.  Set to 0 to allow an unlimited number of jobs.

     Defaults to 500.

 -- cups-configuration parameter: non-negative-integer max-jobs-per-printer
     Specifies the maximum number of simultaneous jobs that are allowed per printer.  A value of 0 allows up to MaxJobs jobs per printer.

     Defaults to 0.

 -- cups-configuration parameter: non-negative-integer max-jobs-per-user
     Specifies the maximum number of simultaneous jobs that are allowed per user.  A value of 0 allows up to MaxJobs jobs per user.

     Defaults to 0.

 -- cups-configuration parameter: non-negative-integer max-job-time
     Specifies the maximum time a job may take to print before it is canceled, in seconds.  Set to 0 to disable cancellation of "stuck" jobs.

     Defaults to 10800.

 -- cups-configuration parameter: non-negative-integer max-log-size
     Specifies the maximum size of the log files before they are rotated, in bytes.  The value 0 disables log rotation.

     Defaults to 1048576.

 -- cups-configuration parameter: non-negative-integer multiple-operation-timeout
     Specifies the maximum amount of time to allow between files in a multiple file print job, in seconds.

     Defaults to 300.

 -- cups-configuration parameter: string page-log-format
     Specifies the format of PageLog lines.  Sequences beginning with percent (%) characters are replaced with the corresponding information, while all other characters are copied literally.  The following percent sequences are recognized:

     %%
          insert a single percent character

     %{name}
          insert the value of the specified IPP attribute

     %C
          insert the number of copies for the current page

     %P
          insert the current page number

     %T
          insert the current date and time in common log format

     %j
          insert the job ID

     %p
          insert the printer name

     %u
          insert the username

     A value of the empty string disables page logging.  The string %p %u %j %T %P %C %{job-billing} %{job-originating-host-name} %{job-name} %{media} %{sides} creates a page log with the standard items.

     Defaults to "".

 -- cups-configuration parameter: environment-variables environment-variables
     Passes the specified environment variable(s) to child processes; a list of strings.

     Defaults to ().

 -- cups-configuration parameter: policy-configuration-list policies
     Specifies named access control policies.

     Available policy-configuration fields are:

      -- policy-configuration parameter: string name
          Name of the policy.

      -- policy-configuration parameter: string job-private-access
          Specifies an access list for a job's private values.  @ACL maps to the printer's requesting-user-name-allowed or requesting-user-name-denied values.  @OWNER maps to the job's owner.  @SYSTEM maps to the groups listed for the system-group field of the files-config configuration, which is reified into the cups-files.conf(5) file.  Other possible elements of the access list include specific user names, and @GROUP to indicate members of a specific group.  The access list may also be simply all or default.

          Defaults to "@OWNER @SYSTEM".

      -- policy-configuration parameter: string job-private-values
          Specifies the list of job values to make private, or all, default, or none.

          Defaults to "job-name job-originating-host-name job-originating-user-name phone".

      -- policy-configuration parameter: string subscription-private-access
          Specifies an access list for a subscription's private values.  @ACL maps to the printer's requesting-user-name-allowed or requesting-user-name-denied values.  @OWNER maps to the job's owner.  @SYSTEM maps to the groups listed for the system-group field of the files-config configuration, which is reified into the cups-files.conf(5) file.  Other possible elements of the access list include specific user names, and @GROUP to indicate members of a specific group.  The access list may also be simply all or default.

          Defaults to "@OWNER @SYSTEM".

      -- policy-configuration parameter: string subscription-private-values
          Specifies the list of job values to make private, or all, default, or none.

          Defaults to "notify-events notify-pull-method notify-recipient-uri notify-subscriber-user-name notify-user-data".

      -- policy-configuration parameter: operation-access-control-list access-controls
          Access control by IPP operation.

          Defaults to ().

 -- cups-configuration parameter: boolean-or-non-negative-integer preserve-job-files
     Specifies whether job files (documents) are preserved after a job is printed.  If a numeric value is specified, job files are preserved for the indicated number of seconds after printing.  Otherwise a boolean value applies indefinitely.

     Defaults to 86400.

 -- cups-configuration parameter: boolean-or-non-negative-integer preserve-job-history
     Specifies whether the job history is preserved after a job is printed.  If a numeric value is specified, the job history is preserved for the indicated number of seconds after printing.  If #t, the job history is preserved until the MaxJobs limit is reached.

     Defaults to #t.

 -- cups-configuration parameter: non-negative-integer reload-timeout
     Specifies the amount of time to wait for job completion before restarting the scheduler.

     Defaults to 30.

 -- cups-configuration parameter: string rip-cache
     Specifies the maximum amount of memory to use when converting documents into bitmaps for a printer.

     Defaults to "128m".

 -- cups-configuration parameter: string server-admin
     Specifies the email address of the server administrator.

     Defaults to "root@localhost.localdomain".

 -- cups-configuration parameter: host-name-list-or-* server-alias
     The ServerAlias directive is used for HTTP Host header validation when clients connect to the scheduler from external interfaces.  Using the special name * can expose your system to known browser-based DNS rebinding attacks, even when accessing sites through a firewall.  If the auto-discovery of alternate names does not work, we recommend listing each alternate name with a ServerAlias directive instead of using *.

     Defaults to *.

 -- cups-configuration parameter: string server-name
     Specifies the fully-qualified host name of the server.

     Defaults to "localhost".

 -- cups-configuration parameter: server-tokens server-tokens
     Specifies what information is included in the Server header of HTTP responses.  None disables the Server header.  ProductOnly reports CUPS.  Major reports CUPS 2.  Minor reports CUPS 2.0.  Minimal reports CUPS 2.0.0. OS reports CUPS 2.0.0 (UNAME) where UNAME is the output of the uname command.  Full reports CUPS 2.0.0 (UNAME) IPP/2.0.

     Defaults to Minimal.

 -- cups-configuration parameter: string set-env
     Set the specified environment variable to be passed to child processes.

     Defaults to "variable value".

 -- cups-configuration parameter: multiline-string-list ssl-listen
     Listens on the specified interfaces for encrypted connections.  Valid values are of the form ADDRESS:PORT, where ADDRESS is either an IPv6 address enclosed in brackets, an IPv4 address, or * to indicate all addresses.

     Defaults to ().

 -- cups-configuration parameter: ssl-options ssl-options
     Sets encryption options.  By default, CUPS only supports encryption using TLS v1.0 or higher using known secure cipher suites.  The AllowRC4 option enables the 128-bit RC4 cipher suites, which are required for some older clients that do not implement newer ones.  The AllowSSL3 option enables SSL v3.0, which is required for some older clients that do not support TLS v1.0.

     Defaults to ().

 -- cups-configuration parameter: boolean strict-conformance?
     Specifies whether the scheduler requires clients to strictly adhere to the IPP specifications.

     Defaults to #f.

 -- cups-configuration parameter: non-negative-integer timeout
     Specifies the HTTP request timeout, in seconds.

     Defaults to 300.

 -- cups-configuration parameter: boolean web-interface?
     Specifies whether the web interface is enabled.

     Defaults to #f.

At this point you're probably thinking ``oh dear, Guix manual, I like you but you can stop already with the configuration options''.  Indeed. However, one more point: it could be that you have an existing cupsd.conf that you want to use.  In that case, you can pass an opaque-cups-configuration as the configuration of a cups-service-type.

Available opaque-cups-configuration fields are:

 -- opaque-cups-configuration parameter: package cups
     The CUPS package.

 -- opaque-cups-configuration parameter: string cupsd.conf
     The contents of the cupsd.conf, as a string.

 -- opaque-cups-configuration parameter: string cups-files.conf
     The contents of the cups-files.conf file, as a string.

For example, if your cupsd.conf and cups-files.conf are in strings of the same name, you could instantiate a CUPS service like this:

     (service cups-service-type
              (opaque-cups-configuration
                (cupsd.conf cupsd.conf)
                (cups-files.conf cups-files.conf)))

Desktop-Dienste
---------------

The (gnu services desktop) module provides services that are usually useful in the context of a ``desktop'' setup---that is, on a machine running a graphical display server, possibly with graphical user interfaces, etc. It also defines services that provide specific desktop environments like GNOME, XFCE or MATE.

To simplify things, the module defines a variable containing the set of services that users typically expect on a machine with a graphical environment and networking:

 -- Scheme Variable: %desktop-services
     This is a list of services that builds upon %BASE-SERVICES and adds or adjusts services for a typical ``desktop'' setup.

     In particular, it adds a graphical login manager (see slim-service), screen lockers, a network management tool (see network-manager-service-type), energy and color management services, the elogind login and seat manager, the Polkit privilege service, the GeoClue location service, the AccountsService daemon that allows authorized users change system passwords, an NTP client (see Netzwerkdienste), the Avahi daemon, and has the name service switch service configured to be able to use nss-mdns (see mDNS).

The %DESKTOP-SERVICES variable can be used as the services field of an operating-system declaration (see services).

Additionally, the gnome-desktop-service, xfce-desktop-service, mate-desktop-service-type and enlightenment-desktop-service-type procedures can add GNOME, XFCE, MATE and/or Enlightenment to a system.  To ``add GNOME'' means that system-level services like the backlight adjustment helpers and the power management utilities are added to the system, extending polkit and dbus appropriately, allowing GNOME to operate with elevated privileges on a limited number of special-purpose system interfaces. Additionally, adding a service made by gnome-desktop-service adds the GNOME metapackage to the system profile.  Likewise, adding the XFCE service not only adds the xfce metapackage to the system profile, but it also gives the Thunar file manager the ability to open a ``root-mode'' file management window, if the user authenticates using the administrator's password via the standard polkit graphical interface.  To ``add MATE'' means that polkit and dbus are extended appropriately, allowing MATE to operate with elevated privileges on a limited number of special-purpose system interfaces.  Additionally, adding a service of type mate-desktop-service-type adds the MATE metapackage to the system profile.  ``Adding Enlightenment'' means that dbus is extended appropriately, and several of Enlightenment's binaries are set as setuid, allowing Enlightenment's screen locker and other functionality to work as expetected.

The desktop environments in Guix use the Xorg display server by default.  If you'd like to use the newer display server protocol called Wayland, you need to use the sddm-service instead of the slim-service for the graphical login manager.  You should then select the ``GNOME (Wayland)'' session in SDDM.  Alternatively you can also try starting GNOME on Wayland manually from a TTY with the command ``XDG_SESSION_TYPE=wayland exec dbus-run-session gnome-session``.  Currently only GNOME has support for Wayland.

 -- Scheme Procedure: gnome-desktop-service
     Return a service that adds the gnome package to the system profile, and extends polkit with the actions from gnome-settings-daemon.

 -- Scheme Procedure: xfce-desktop-service
     Return a service that adds the xfce package to the system profile, and extends polkit with the ability for thunar to manipulate the file system as root from within a user session, after the user has authenticated with the administrator's password.

 -- Scheme Variable: mate-desktop-service-type
     This is the type of the service that runs the MATE desktop environment (https://mate-desktop.org/).  Its value is a mate-desktop-configuration object (see below.)

     This service adds the mate package to the system profile, and extends polkit with the actions from mate-settings-daemon.

 -- Data Type: mate-desktop-configuration
     Configuration record for the MATE desktop environment.

     mate (default mate)
          The MATE package to use.

 -- Scheme Variable: enlightenment-desktop-service-type
     Return a service that adds the enlightenment package to the system profile, and extends dbus with actions from efl.

 -- Data Type: enlightenment-desktop-service-configuration

     enlightenment (Vorgabe: enlightenment)
          Das Enlightenment-Paket, was benutzt werden soll.

Because the GNOME, XFCE and MATE desktop services pull in so many packages, the default %desktop-services variable doesn't include any of them by default.  To add GNOME, XFCE or MATE, just cons them onto %desktop-services in the services field of your operating-system:

     (use-modules (gnu))
     (use-service-modules desktop)
     (operating-system
       ...
       ;; cons* adds items to the list given as its last argument.
       (services (cons* (gnome-desktop-service)
                        (xfce-desktop-service)
                        %desktop-services))
       ...)

These desktop environments will then be available as options in the graphical login window.

The actual service definitions included in %desktop-services and provided by (gnu services dbus) and (gnu services desktop) are described below.

 -- Scheme Procedure: dbus-service [#:dbus DBUS] [#:services '()]
     Return a service that runs the ``system bus'', using DBUS, with support for SERVICES.

     D-Bus (http://dbus.freedesktop.org/) is an inter-process communication facility.  Its system bus is used to allow system services to communicate and to be notified of system-wide events.

     SERVICES must be a list of packages that provide an etc/dbus-1/system.d directory containing additional D-Bus configuration and policy files.  For example, to allow avahi-daemon to use the system bus, SERVICES must be equal to (list avahi).

 -- Scheme Procedure: elogind-service [#:config CONFIG]
     Return a service that runs the elogind login and seat management daemon.  Elogind (https://github.com/elogind/elogind) exposes a D-Bus interface that can be used to know which users are logged in, know what kind of sessions they have open, suspend the system, inhibit system suspend, reboot the system, and other tasks.

     Elogind handles most system-level power events for a computer, for example suspending the system when a lid is closed, or shutting it down when the power button is pressed.

     The CONFIG keyword argument specifies the configuration for elogind, and should be the result of an (elogind-configuration (PARAMETER VALUE)...) invocation.  Available parameters and their default values are:

     kill-user-processes?
          #f

     kill-only-users
          ()

     kill-exclude-users
          ("root")

     inhibit-delay-max-seconds
          5

     handle-power-key
          poweroff

     handle-suspend-key
          suspend

     handle-hibernate-key
          hibernate

     handle-lid-switch
          suspend

     handle-lid-switch-docked
          ignore

     power-key-ignore-inhibited?
          #f

     suspend-key-ignore-inhibited?
          #f

     hibernate-key-ignore-inhibited?
          #f

     lid-switch-ignore-inhibited?
          #t

     holdoff-timeout-seconds
          30

     idle-action
          ignore

     idle-action-seconds
          (* 30 60)

     runtime-directory-size-percent
          10

     runtime-directory-size
          #f

     remove-ipc?
          #t

     suspend-state
          ("mem" "standby" "freeze")

     suspend-mode
          ()

     hibernate-state
          ("disk")

     hibernate-mode
          ("platform" "shutdown")

     hybrid-sleep-state
          ("disk")

     hybrid-sleep-mode
          ("suspend" "platform" "shutdown")

 -- Scheme Procedure: accountsservice-service
     [#:accountsservice ACCOUNTSSERVICE] Return a service that runs
     AccountsService, a system service that can list available accounts, change their passwords, and so on.  AccountsService integrates with PolicyKit to enable unprivileged users to acquire the capability to modify their system configuration. the accountsservice web site (https://www.freedesktop.org/wiki/Software/AccountsService/) for more information.

     The ACCOUNTSSERVICE keyword argument is the accountsservice package to expose as a service.

 -- Scheme Procedure: polkit-service
     [#:polkit POLKIT] Return a service that runs the
     Polkit privilege management service (http://www.freedesktop.org/wiki/Software/polkit/), which allows system administrators to grant access to privileged operations in a structured way.  By querying the Polkit service, a privileged system component can know when it should grant additional capabilities to ordinary users.  For example, an ordinary user can be granted the capability to suspend the system if the user is logged in locally.

 -- Scheme Variable: upower-service-type
     Service that runs upowerd (http://upower.freedesktop.org/), a system-wide monitor for power consumption and battery levels, with the given configuration settings.

     It implements the org.freedesktop.UPower D-Bus interface, and is notably used by GNOME.

 -- Data Type: upower-configuration
     Data type representation the configuration for UPower.

     upower (default: UPOWER)
          Package to use for upower.

     watts-up-pro? (default: #f)
          Enable the Watts Up Pro device.

     poll-batteries? (default: #t)
          Enable polling the kernel for battery level changes.

     ignore-lid? (default: #f)
          Ignore the lid state, this can be useful if it's incorrect on a device.

     use-percentage-for-policy? (default: #f)
          Whether battery percentage based policy should be used.  The default is to use the time left, change to #t to use the percentage.

     percentage-low (default: 10)
          When use-percentage-for-policy? is #t, this sets the percentage at which the battery is considered low.

     percentage-critical (default: 3)
          When use-percentage-for-policy? is #t, this sets the percentage at which the battery is considered critical.

     percentage-action (default: 2)
          When use-percentage-for-policy? is #t, this sets the percentage at which action will be taken.

     time-low (default: 1200)
          When use-time-for-policy? is #f, this sets the time remaining in seconds at which the battery is considered low.

     time-critical (default: 300)
          When use-time-for-policy? is #f, this sets the time remaining in seconds at which the battery is considered critical.

     time-action (default: 120)
          When use-time-for-policy? is #f, this sets the time remaining in seconds at which action will be taken.

     critical-power-action (default: 'hybrid-sleep)
          The action taken when percentage-action or time-action is reached (depending on the configuration of use-percentage-for-policy?).

          Possible values are:

            * 'power-off

            * 'hibernate

            * 'hybrid-sleep.

 -- Scheme Procedure: udisks-service [#:udisks UDISKS]
     Return a service for UDisks (http://udisks.freedesktop.org/docs/latest/), a disk management daemon that provides user interfaces with notifications and ways to mount/unmount disks.  Programs that talk to UDisks include the udisksctl command, part of UDisks, and GNOME Disks.

 -- Scheme Procedure: colord-service [#:colord COLORD]
     Return a service that runs colord, a system service with a D-Bus interface to manage the color profiles of input and output devices such as screens and scanners.  It is notably used by the GNOME Color Manager graphical tool.  See the colord web site (http://www.freedesktop.org/software/colord/) for more information.

 -- Scheme Procedure: geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()]
     Return a configuration allowing an application to access GeoClue location data.  NAME is the Desktop ID of the application, without the .desktop part.  If ALLOWED? is true, the application will have access to location information by default.  The boolean SYSTEM? value indicates whether an application is a system component or not.  Finally USERS is a list of UIDs of all users for which this application is allowed location info access.  An empty users list means that all users are allowed.

 -- Scheme Variable: %standard-geoclue-applications
     The standard list of well-known GeoClue application configurations, granting authority to the GNOME date-and-time utility to ask for the current location in order to set the time zone, and allowing the IceCat and Epiphany web browsers to request location information.  IceCat and Epiphany both query the user before allowing a web page to know the user's location.

 -- Scheme Procedure: geoclue-service [#:colord COLORD]
     [#:whitelist '()]  [#:wifi-geolocation-url
     "https://location.services.mozilla.com/v1/geolocate?key=geoclue"] [#:submit-data? #f] [#:wifi-submission-url "https://location.services.mozilla.com/v1/submit?key=geoclue"] [#:submission-nick "geoclue"]  [#:applications %standard-geoclue-applications] Return a service that runs the GeoClue location service.  This service provides a D-Bus interface to allow applications to request access to a user's physical location, and optionally to add information to online location databases.  See the GeoClue web site (https://wiki.freedesktop.org/www/Software/GeoClue/) for more information.

 -- Scheme Procedure: bluetooth-service [#:bluez BLUEZ]
     [#:auto-enable? #f] Return a service that runs the bluetoothd
     daemon, which manages all the Bluetooth devices and provides a number of D-Bus interfaces.  When AUTO-ENABLE? is true, the bluetooth controller is powered automatically at boot, which can be useful when using a bluetooth keyboard or mouse.

     Users need to be in the lp group to access the D-Bus service.

Tondienste
----------

The (gnu services sound) module provides a service to configure the Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the preferred ALSA output driver.

 -- Scheme Variable: alsa-service-type
     This is the type for the Advanced Linux Sound Architecture (https://alsa-project.org/) (ALSA) system, which generates the /etc/asound.conf configuration file.  The value for this type is a alsa-configuration record as in this example:

          (service alsa-service-type)

     See below for details about alsa-configuration.

 -- Datentyp: alsa-configuration
     Repräsentiert die Konfiguration für den Dienst alsa-service.

     alsa-plugins (Vorgabe: ALSA-PLUGINS)
          alsa-plugins-Paket, was benutzt werden soll.

     pulseaudio? (Vorgabe: #T)
          Whether ALSA applications should transparently be made to use the PulseAudio (http://www.pulseaudio.org/) sound server.

          Using PulseAudio allows you to run several sound-producing applications at the same time and to individual control them via pavucontrol, among other things.

     extra-options (Vorgabe: "")
          String to append to the /etc/asound.conf file.

Individual users who want to override the system configuration of ALSA can do it with the ~/.asoundrc file:

     # In guix, we have to specify the absolute path for plugins.
     pcm_type.jack {
       lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so"
     }

     # Routing ALSA to jack:
     # <http://jackaudio.org/faq/routing_alsa.html>.
     pcm.rawjack {
       type jack
       playback_ports {
         0 system:playback_1
         1 system:playback_2
       }

       capture_ports {
         0 system:capture_1
         1 system:capture_2
       }
     }

     pcm.!default {
       type plug
       slave {
         pcm "rawjack"
       }
     }

See https://www.alsa-project.org/main/index.php/Asoundrc for the details.

Datenbankdienste
----------------

The (gnu services databases) module provides the following services.

 -- Scheme Procedure: postgresql-service [#:postgresql postgresql]
     [#:config-file] [#:data-directory ``/var/lib/postgresql/data'']  [#:port
     5432] [#:locale ``en_US.utf8''] [#:extension-packages '()] Return a service that runs POSTGRESQL, the PostgreSQL database server.

     The PostgreSQL daemon loads its runtime configuration from CONFIG-FILE, creates a database cluster with LOCALE as the default locale, stored in DATA-DIRECTORY.  It then listens on PORT.

     Additional extensions are loaded from packages listed in EXTENSION-PACKAGES.  Extensions are available at runtime.  For instance, to create a geographic database using the postgis extension, a user can configure the postgresql-service as in this example:

          (use-package-modules databases geo)

          (operating-system
            ...
            ;; postgresql is required to run `psql' but postgis is not required for
            ;; proper operation.
            (packages (cons* postgresql %base-packages))
            (services
              (cons*
                (postgresql-service #:extension-packages (list postgis))
                %base-services)))

     Then the extension becomes visible and you can initialise an empty geographic database in this way:

          psql -U postgres
          > create database postgistest;
          > \connect postgistest;
          > create extension postgis;
          > create extension postgis_topology;

     There is no need to add this field for contrib extensions such as hstore or dblink as they are already loadable by postgresql.  This field is only required to add extensions provided by other packages.

 -- Scheme Procedure: mysql-service [#:config (mysql-configuration)]
     Return a service that runs mysqld, the MySQL or MariaDB database server.

     The optional CONFIG argument specifies the configuration for mysqld, which should be a <mysql-configuration> object.

 -- Data Type: mysql-configuration
     Data type representing the configuration of MYSQL-SERVICE.

     mysql (default: MARIADB)
          Package object of the MySQL database server, can be either MARIADB or MYSQL.

          For MySQL, a temporary root password will be displayed at activation time. For MariaDB, the root password is empty.

     port (default: 3306)
          TCP port on which the database server listens for incoming connections.

 -- Scheme Variable: memcached-service-type
     This is the service type for the Memcached (https://memcached.org/) service, which provides a distributed in memory cache.  The value for the service type is a memcached-configuration object.

     (service memcached-service-type)

 -- Data Type: memcached-configuration
     Data type representing the configuration of memcached.

     memcached (default: memcached)
          The Memcached package to use.

     interfaces (default: '("0.0.0.0"))
          Network interfaces on which to listen.

     tcp-port (default: 11211)
          Port on which to accept connections on,

     udp-port (default: 11211)
          Port on which to accept UDP connections on, a value of 0 will disable listening on a UDP socket.

     additional-options (default: '())
          Additional command line options to pass to memcached.

 -- Scheme Variable: mongodb-service-type
     This is the service type for MongoDB (https://www.mongodb.com/).  The value for the service type is a mongodb-configuration object.

     (service mongodb-service-type)

 -- Data Type: mongodb-configuration
     Data type representing the configuration of mongodb.

     mongodb (default: mongodb)
          The MongoDB package to use.

     config-file (default: %default-mongodb-configuration-file)
          The configuration file for MongoDB.

     data-directory (default: "/var/lib/mongodb")
          This value is used to create the directory, so that it exists and is owned by the mongodb user.  It should match the data-directory which MongoDB is configured to use through the configuration file.

 -- Scheme Variable: redis-service-type
     This is the service type for the Redis (https://redis.io/) key/value store, whose value is a redis-configuration object.

 -- Data Type: redis-configuration
     Data type representing the configuration of redis.

     redis (default: redis)
          The Redis package to use.

     bind (default: "127.0.0.1")
          Network interface on which to listen.

     port (default: 6379)
          Port on which to accept connections on, a value of 0 will disable listening on a TCP socket.

     working-directory (default: "/var/lib/redis")
          Directory in which to store the database and related files.

Mail-Dienste
------------

The (gnu services mail) module provides Guix service definitions for email services: IMAP, POP3, and LMTP servers, as well as mail transport agents (MTAs).  Lots of acronyms! These services are detailed in the subsections below.

Dovecot Service
...............

 -- Scheme Procedure: dovecot-service [#:config (dovecot-configuration)]
     Return a service that runs the Dovecot IMAP/POP3/LMTP mail server.

By default, Dovecot does not need much configuration; the default configuration object created by (dovecot-configuration) will suffice if your mail is delivered to ~/Maildir.  A self-signed certificate will be generated for TLS-protected connections, though Dovecot will also listen on cleartext ports by default.  There are a number of options, though, which mail administrators might need to change, and as is the case with other services, Guix allows the system administrator to specify these parameters via a uniform Scheme interface.

For example, to specify that mail is located at maildir~/.mail, one would instantiate the Dovecot service like this:

     (dovecot-service #:config
                      (dovecot-configuration
                       (mail-location "maildir:~/.mail")))

The available configuration parameters follow.  Each parameter definition is preceded by its type; for example, string-list foo indicates that the foo parameter should be specified as a list of strings.  There is also a way to specify the configuration as a string, if you have an old dovecot.conf file that you want to port over from some other system; see the end for more details.

Available dovecot-configuration fields are:

 -- dovecot-configuration parameter: package dovecot
     The dovecot package.

 -- dovecot-configuration parameter: comma-separated-string-list listen
     A list of IPs or hosts where to listen for connections.  * listens on all IPv4 interfaces, :: listens on all IPv6 interfaces.  If you want to specify non-default ports or anything more complex, customize the address and port fields of the inet-listener of the specific services you are interested in.

 -- dovecot-configuration parameter: protocol-configuration-list protocols
     List of protocols we want to serve.  Available protocols include imap, pop3, and lmtp.

     Available protocol-configuration fields are:

      -- protocol-configuration parameter: string name
          The name of the protocol.

      -- protocol-configuration parameter: string auth-socket-path
          UNIX socket path to the master authentication server to find users.  This is used by imap (for shared users) and lda.  It defaults to "/var/run/dovecot/auth-userdb".

      -- protocol-configuration parameter: space-separated-string-list mail-plugins
          Space separated list of plugins to load.

      -- protocol-configuration parameter: non-negative-integer mail-max-userip-connections
          Maximum number of IMAP connections allowed for a user from each IP address. NOTE: The username is compared case-sensitively.  Defaults to 10.

 -- dovecot-configuration parameter: service-configuration-list services
     List of services to enable.  Available services include imap, imap-login, pop3, pop3-login, auth, and lmtp.

     Available service-configuration fields are:

      -- service-configuration parameter: string kind
          The service kind.  Valid values include director, imap-login, pop3-login, lmtp, imap, pop3, auth, auth-worker, dict, tcpwrap, quota-warning, or anything else.

      -- service-configuration parameter: listener-configuration-list listeners
          Listeners for the service.  A listener is either a unix-listener-configuration, a fifo-listener-configuration, or an inet-listener-configuration.  Defaults to ().

          Available unix-listener-configuration fields are:

           -- unix-listener-configuration parameter: string path
               Path to the file, relative to base-dir field.  This is also used as the section name.

           -- unix-listener-configuration parameter: string mode
               The access mode for the socket.  Defaults to "0600".

           -- unix-listener-configuration parameter: string user
               The user to own the socket.  Defaults to "".

           -- unix-listener-configuration parameter: string group
               The group to own the socket.  Defaults to "".

          Available fifo-listener-configuration fields are:

           -- fifo-listener-configuration parameter: string path
               Path to the file, relative to base-dir field.  This is also used as the section name.

           -- fifo-listener-configuration parameter: string mode
               The access mode for the socket.  Defaults to "0600".

           -- fifo-listener-configuration parameter: string user
               The user to own the socket.  Defaults to "".

           -- fifo-listener-configuration parameter: string group
               The group to own the socket.  Defaults to "".

          Available inet-listener-configuration fields are:

           -- inet-listener-configuration parameter: string protocol
               The protocol to listen for.

           -- inet-listener-configuration parameter: string address
               The address on which to listen, or empty for all addresses.  Defaults to "".

           -- inet-listener-configuration parameter: non-negative-integer port
               The port on which to listen.

           -- inet-listener-configuration parameter: boolean ssl?
               Whether to use SSL for this service; yes, no, or required.  Defaults to #t.

      -- service-configuration parameter: non-negative-integer client-limit
          Maximum number of simultaneous client connections per process.  Once this number of connections is received, the next incoming connection will prompt Dovecot to spawn another process.  If set to 0, default-client-limit is used instead.

          Defaults to 0.

      -- service-configuration parameter: non-negative-integer service-count
          Number of connections to handle before starting a new process.  Typically the only useful values are 0 (unlimited) or 1.  1 is more secure, but 0 is faster.  <doc/wiki/LoginProcess.txt>.  Defaults to 1.

      -- service-configuration parameter: non-negative-integer process-limit
          Maximum number of processes that can exist for this service.  If set to 0, default-process-limit is used instead.

          Defaults to 0.

      -- service-configuration parameter: non-negative-integer process-min-avail
          Number of processes to always keep waiting for more connections.  Defaults to 0.

      -- service-configuration parameter: non-negative-integer vsz-limit
          If you set service-count 0, you probably need to grow this.  Defaults to 256000000.

 -- dovecot-configuration parameter: dict-configuration dict
     Dict configuration, as created by the dict-configuration constructor.

     Available dict-configuration fields are:

      -- dict-configuration parameter: free-form-fields entries
          A list of key-value pairs that this dict should hold.  Defaults to ().

 -- dovecot-configuration parameter: passdb-configuration-list passdbs
     A list of passdb configurations, each one created by the passdb-configuration constructor.

     Available passdb-configuration fields are:

      -- passdb-configuration parameter: string driver
          The driver that the passdb should use.  Valid values include pam, passwd, shadow, bsdauth, and static.  Defaults to "pam".

      -- passdb-configuration parameter: space-separated-string-list args
          Space separated list of arguments to the passdb driver.  Defaults to "".

 -- dovecot-configuration parameter: userdb-configuration-list userdbs
     List of userdb configurations, each one created by the userdb-configuration constructor.

     Available userdb-configuration fields are:

      -- userdb-configuration parameter: string driver
          The driver that the userdb should use.  Valid values include passwd and static.  Defaults to "passwd".

      -- userdb-configuration parameter: space-separated-string-list args
          Space separated list of arguments to the userdb driver.  Defaults to "".

      -- userdb-configuration parameter: free-form-args override-fields
          Override fields from passwd.  Defaults to ().

 -- dovecot-configuration parameter: plugin-configuration plugin-configuration
     Plug-in configuration, created by the plugin-configuration constructor.

 -- dovecot-configuration parameter: list-of-namespace-configuration namespaces
     List of namespaces.  Each item in the list is created by the namespace-configuration constructor.

     Available namespace-configuration fields are:

      -- namespace-configuration parameter: string name
          Name for this namespace.

      -- namespace-configuration parameter: string type
          Namespace type: private, shared or public.  Defaults to "private".

      -- namespace-configuration parameter: string separator
          Hierarchy separator to use. You should use the same separator for all namespaces or some clients get confused.  / is usually a good one. The default however depends on the underlying mail storage format.  Defaults to "".

      -- namespace-configuration parameter: string prefix
          Prefix required to access this namespace.  This needs to be different for all namespaces. For example Public/.  Defaults to "".

      -- namespace-configuration parameter: string location
          Physical location of the mailbox. This is in the same format as mail_location, which is also the default for it.  Defaults to "".

      -- namespace-configuration parameter: boolean inbox?
          There can be only one INBOX, and this setting defines which namespace has it.  Defaults to #f.

      -- namespace-configuration parameter: boolean hidden?
          If namespace is hidden, it's not advertised to clients via NAMESPACE extension. You'll most likely also want to set list? #f.  This is mostly useful when converting from another server with different namespaces which you want to deprecate but still keep working.  For example you can create hidden namespaces with prefixes ~/mail/, ~%u/mail/ and mail/.  Defaults to #f.

      -- namespace-configuration parameter: boolean list?
          Show the mailboxes under this namespace with the LIST command. This makes the namespace visible for clients that do not support the NAMESPACE extension.  The special children value lists child mailboxes, but hides the namespace prefix.  Defaults to #t.

      -- namespace-configuration parameter: boolean subscriptions?
          Namespace handles its own subscriptions.  If set to #f, the parent namespace handles them.  The empty prefix should always have this as #t).  Defaults to #t.

      -- namespace-configuration parameter: mailbox-configuration-list mailboxes
          List of predefined mailboxes in this namespace.  Defaults to ().

          Available mailbox-configuration fields are:

           -- mailbox-configuration parameter: string name
               Name for this mailbox.

           -- mailbox-configuration parameter: string auto
               create will automatically create this mailbox.  subscribe will both create and subscribe to the mailbox.  Defaults to "no".

           -- mailbox-configuration parameter: space-separated-string-list special-use
               List of IMAP SPECIAL-USE attributes as specified by RFC 6154.  Valid values are \All, \Archive, \Drafts, \Flagged, \Junk, \Sent, and \Trash.  Defaults to ().

 -- dovecot-configuration parameter: file-name base-dir
     Base directory where to store runtime data.  Defaults to "/var/run/dovecot/".

 -- dovecot-configuration parameter: string login-greeting
     Greeting message for clients.  Defaults to "Dovecot ready.".

 -- dovecot-configuration parameter: space-separated-string-list login-trusted-networks
     List of trusted network ranges.  Connections from these IPs are allowed to override their IP addresses and ports (for logging and for authentication checks).  disable-plaintext-auth is also ignored for these networks. Typically you would specify your IMAP proxy servers here.  Defaults to ().

 -- dovecot-configuration parameter: space-separated-string-list login-access-sockets
     List of login access check sockets (e.g. tcpwrap).  Defaults to ().

 -- dovecot-configuration parameter: boolean verbose-proctitle?
     Show more verbose process titles (in ps).  Currently shows user name and IP address.  Useful for seeing who is actually using the IMAP processes (e.g. shared mailboxes or if the same uid is used for multiple accounts). Defaults to #f.

 -- dovecot-configuration parameter: boolean shutdown-clients?
     Should all processes be killed when Dovecot master process shuts down. Setting this to #f means that Dovecot can be upgraded without forcing existing client connections to close (although that could also be a problem if the upgrade is e.g. due to a security fix).  Defaults to #t.

 -- dovecot-configuration parameter: non-negative-integer doveadm-worker-count
     If non-zero, run mail commands via this many connections to doveadm server, instead of running them directly in the same process.  Defaults to 0.

 -- dovecot-configuration parameter: string doveadm-socket-path
     UNIX socket or host:port used for connecting to doveadm server.  Defaults to "doveadm-server".

 -- dovecot-configuration parameter: space-separated-string-list import-environment
     List of environment variables that are preserved on Dovecot startup and passed down to all of its child processes.  You can also give key=value pairs to always set specific settings.

 -- dovecot-configuration parameter: boolean disable-plaintext-auth?
     Disable LOGIN command and all other plaintext authentications unless SSL/TLS is used (LOGINDISABLED capability).  Note that if the remote IP matches the local IP (i.e. you're connecting from the same computer), the connection is considered secure and plaintext authentication is allowed.  See also ssl=required setting.  Defaults to #t.

 -- dovecot-configuration parameter: non-negative-integer auth-cache-size
     Authentication cache size (e.g. #e10e6).  0 means it's disabled. Note that bsdauth, PAM and vpopmail require cache-key to be set for caching to be used.  Defaults to 0.

 -- dovecot-configuration parameter: string auth-cache-ttl
     Time to live for cached data.  After TTL expires the cached record is no longer used, *except* if the main database lookup returns internal failure. We also try to handle password changes automatically: If user's previous authentication was successful, but this one wasn't, the cache isn't used. For now this works only with plaintext authentication.  Defaults to "1 hour".

 -- dovecot-configuration parameter: string auth-cache-negative-ttl
     TTL for negative hits (user not found, password mismatch).  0 disables caching them completely.  Defaults to "1 hour".

 -- dovecot-configuration parameter: space-separated-string-list auth-realms
     List of realms for SASL authentication mechanisms that need them.  You can leave it empty if you don't want to support multiple realms.  Many clients simply use the first one listed here, so keep the default realm first. Defaults to ().

 -- dovecot-configuration parameter: string auth-default-realm
     Default realm/domain to use if none was specified.  This is used for both SASL realms and appending @domain to username in plaintext logins. Defaults to "".

 -- dovecot-configuration parameter: string auth-username-chars
     List of allowed characters in username.  If the user-given username contains a character not listed in here, the login automatically fails.  This is just an extra check to make sure user can't exploit any potential quote escaping vulnerabilities with SQL/LDAP databases.  If you want to allow all characters, set this value to empty.  Defaults to "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@".

 -- dovecot-configuration parameter: string auth-username-translation
     Username character translations before it's looked up from databases.  The value contains series of from -> to characters.  For example #@/@ means that # and / characters are translated to @. Defaults to "".

 -- dovecot-configuration parameter: string auth-username-format
     Username formatting before it's looked up from databases.  You can use the standard variables here, e.g. %Lu would lowercase the username, %n would drop away the domain if it was given, or %n-AT-%d would change the @ into -AT-.  This translation is done after auth-username-translation changes.  Defaults to "%Lu".

 -- dovecot-configuration parameter: string auth-master-user-separator
     If you want to allow master users to log in by specifying the master username within the normal username string (i.e. not using SASL mechanism's support for it), you can specify the separator character here. The format is then <username><separator><master username>.  UW-IMAP uses * as the separator, so that could be a good choice.  Defaults to "".

 -- dovecot-configuration parameter: string auth-anonymous-username
     Username to use for users logging in with ANONYMOUS SASL mechanism. Defaults to "anonymous".

 -- dovecot-configuration parameter: non-negative-integer auth-worker-max-count
     Maximum number of dovecot-auth worker processes.  They're used to execute blocking passdb and userdb queries (e.g. MySQL and PAM).  They're automatically created and destroyed as needed.  Defaults to 30.

 -- dovecot-configuration parameter: string auth-gssapi-hostname
     Host name to use in GSSAPI principal names.  The default is to use the name returned by gethostname().  Use $ALL (with quotes) to allow all keytab entries.  Defaults to "".

 -- dovecot-configuration parameter: string auth-krb5-keytab
     Kerberos keytab to use for the GSSAPI mechanism.  Will use the system default (usually /etc/krb5.keytab) if not specified.  You may need to change the auth service to run as root to be able to read this file. Defaults to "".

 -- dovecot-configuration parameter: boolean auth-use-winbind?
     Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon and ntlm-auth helper.  <doc/wiki/Authentication/Mechanisms/Winbind.txt>. Defaults to #f.

 -- dovecot-configuration parameter: file-name auth-winbind-helper-path
     Path for Samba's ntlm-auth helper binary.  Defaults to "/usr/bin/ntlm_auth".

 -- dovecot-configuration parameter: string auth-failure-delay
     Time to delay before replying to failed authentications.  Defaults to "2 secs".

 -- dovecot-configuration parameter: boolean auth-ssl-require-client-cert?
     Require a valid SSL client certificate or the authentication fails. Defaults to #f.

 -- dovecot-configuration parameter: boolean auth-ssl-username-from-cert?
     Take the username from client's SSL certificate, using X509_NAME_get_text_by_NID() which returns the subject's DN's CommonName.  Defaults to #f.

 -- dovecot-configuration parameter: space-separated-string-list auth-mechanisms
     List of wanted authentication mechanisms.  Supported mechanisms are: plain, login, digest-md5, cram-md5, ntlm, rpa, apop, anonymous, gssapi, otp, skey, and gss-spnego.  NOTE: See also disable-plaintext-auth setting.

 -- dovecot-configuration parameter: space-separated-string-list director-servers
     List of IPs or hostnames to all director servers, including ourself.  Ports can be specified as ip:port.  The default port is the same as what director service's inet-listener is using.  Defaults to ().

 -- dovecot-configuration parameter: space-separated-string-list director-mail-servers
     List of IPs or hostnames to all backend mail servers.  Ranges are allowed too, like 10.0.0.10-10.0.0.30.  Defaults to ().

 -- dovecot-configuration parameter: string director-user-expire
     How long to redirect users to a specific server after it no longer has any connections.  Defaults to "15 min".

 -- dovecot-configuration parameter: string director-username-hash
     How the username is translated before being hashed.  Useful values include %Ln if user can log in with or without @domain, %Ld if mailboxes are shared within domain.  Defaults to "%Lu".

 -- dovecot-configuration parameter: string log-path
     Log file to use for error messages.  syslog logs to syslog, /dev/stderr logs to stderr.  Defaults to "syslog".

 -- dovecot-configuration parameter: string info-log-path
     Log file to use for informational messages.  Defaults to log-path. Defaults to "".

 -- dovecot-configuration parameter: string debug-log-path
     Log file to use for debug messages.  Defaults to info-log-path. Defaults to "".

 -- dovecot-configuration parameter: string syslog-facility
     Syslog facility to use if you're logging to syslog.  Usually if you don't want to use mail, you'll use local0..local7.  Also other standard facilities are supported.  Defaults to "mail".

 -- dovecot-configuration parameter: boolean auth-verbose?
     Log unsuccessful authentication attempts and the reasons why they failed. Defaults to #f.

 -- dovecot-configuration parameter: boolean auth-verbose-passwords?
     In case of password mismatches, log the attempted password.  Valid values are no, plain and sha1.  sha1 can be useful for detecting brute force password attempts vs.  user simply trying the same password over and over again.  You can also truncate the value to n chars by appending ":n" (e.g. sha1:6).  Defaults to #f.

 -- dovecot-configuration parameter: boolean auth-debug?
     Even more verbose logging for debugging purposes.  Shows for example SQL queries.  Defaults to #f.

 -- dovecot-configuration parameter: boolean auth-debug-passwords?
     In case of password mismatches, log the passwords and used scheme so the problem can be debugged.  Enabling this also enables auth-debug. Defaults to #f.

 -- dovecot-configuration parameter: boolean mail-debug?
     Enable mail process debugging.  This can help you figure out why Dovecot isn't finding your mails.  Defaults to #f.

 -- dovecot-configuration parameter: boolean verbose-ssl?
     Show protocol level SSL errors.  Defaults to #f.

 -- dovecot-configuration parameter: string log-timestamp
     Prefix for each line written to log file.  % codes are in strftime(3) format.  Defaults to "\"%b %d %H:%M:%S \"".

 -- dovecot-configuration parameter: space-separated-string-list login-log-format-elements
     List of elements we want to log.  The elements which have a non-empty variable value are joined together to form a comma-separated string.

 -- dovecot-configuration parameter: string login-log-format
     Login log format.  %s contains login-log-format-elements string, %$ contains the data we want to log.  Defaults to "%$: %s".

 -- dovecot-configuration parameter: string mail-log-prefix
     Log prefix for mail processes.  See doc/wiki/Variables.txt for list of possible variables you can use.  Defaults to "\"%s(%u)<%{pid}><%{session}>: \"".

 -- dovecot-configuration parameter: string deliver-log-format
     Format to use for logging mail deliveries.  You can use variables:

     %$
          Delivery status message (e.g. saved to INBOX)

     %m
          Message-ID

     %s
          Subject

     %f
          From address

     %p
          Physical size

     %w
          Virtual size.

     Defaults to "msgid=%m: %$".

 -- dovecot-configuration parameter: string mail-location
     Location for users' mailboxes.  The default is empty, which means that Dovecot tries to find the mailboxes automatically.  This won't work if the user doesn't yet have any mail, so you should explicitly tell Dovecot the full location.

     If you're using mbox, giving a path to the INBOX file (e.g. /var/mail/%u) isn't enough.  You'll also need to tell Dovecot where the other mailboxes are kept.  This is called the "root mail directory", and it must be the first path given in the mail-location setting.

     There are a few special variables you can use, eg.:

     %u
          username

     %n
          user part in user@domain, same as %u if there's no domain

     %d
          domain part in user@domain, empty if there's no domain

     %h
          home director

     See doc/wiki/Variables.txt for full list.  Some examples:

     maildir:~/Maildir

     mbox:~/mail:INBOX=/var/mail/%u

     mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/%

     Defaults to "".

 -- dovecot-configuration parameter: string mail-uid
     System user and group used to access mails.  If you use multiple, userdb can override these by returning uid or gid fields.  You can use either numbers or names.  <doc/wiki/UserIds.txt>.  Defaults to "".

 -- dovecot-configuration parameter: string mail-gid

     Defaults to "".

 -- dovecot-configuration parameter: string mail-privileged-group
     Group to enable temporarily for privileged operations.  Currently this is used only with INBOX when either its initial creation or dotlocking fails. Typically this is set to "mail" to give access to /var/mail.  Defaults to "".

 -- dovecot-configuration parameter: string mail-access-groups
     Grant access to these supplementary groups for mail processes.  Typically these are used to set up access to shared mailboxes.  Note that it may be dangerous to set these if users can create symlinks (e.g. if "mail" group is set here, ln -s /var/mail ~/mail/var could allow a user to delete others' mailboxes, or ln -s /secret/shared/box ~/mail/mybox would allow reading it).  Defaults to "".

 -- dovecot-configuration parameter: boolean mail-full-filesystem-access?
     Allow full file system access to clients.  There's no access checks other than what the operating system does for the active UID/GID.  It works with both maildir and mboxes, allowing you to prefix mailboxes names with e.g. /path/ or ~user/.  Defaults to #f.

 -- dovecot-configuration parameter: boolean mmap-disable?
     Don't use mmap() at all.  This is required if you store indexes to shared file systems (NFS or clustered file system).  Defaults to #f.

 -- dovecot-configuration parameter: boolean dotlock-use-excl?
     Rely on O_EXCL to work when creating dotlock files.  NFS supports O_EXCL since version 3, so this should be safe to use nowadays by default.  Defaults to #t.

 -- dovecot-configuration parameter: string mail-fsync
     When to use fsync() or fdatasync() calls:

     optimized
          Whenever necessary to avoid losing important data

     always
          Useful with e.g. NFS when write()s are delayed

     never
          Never use it (best performance, but crashes can lose data).

     Defaults to "optimized".

 -- dovecot-configuration parameter: boolean mail-nfs-storage?
     Mail storage exists in NFS.  Set this to yes to make Dovecot flush NFS caches whenever needed.  If you're using only a single mail server this isn't needed.  Defaults to #f.

 -- dovecot-configuration parameter: boolean mail-nfs-index?
     Mail index files also exist in NFS.  Setting this to yes requires mmap-disable? #t and fsync-disable? #f.  Defaults to #f.

 -- dovecot-configuration parameter: string lock-method
     Locking method for index files.  Alternatives are fcntl, flock and dotlock. Dotlocking uses some tricks which may create more disk I/O than other locking methods.  NFS users: flock doesn't work, remember to change mmap-disable.  Defaults to "fcntl".

 -- dovecot-configuration parameter: file-name mail-temp-dir
     Directory in which LDA/LMTP temporarily stores incoming mails >128 kB. Defaults to "/tmp".

 -- dovecot-configuration parameter: non-negative-integer first-valid-uid
     Valid UID range for users.  This is mostly to make sure that users can't log in as daemons or other system users.  Note that denying root logins is hardcoded to dovecot binary and can't be done even if first-valid-uid is set to 0.  Defaults to 500.

 -- dovecot-configuration parameter: non-negative-integer last-valid-uid

     Defaults to 0.

 -- dovecot-configuration parameter: non-negative-integer first-valid-gid
     Valid GID range for users.  Users having non-valid GID as primary group ID aren't allowed to log in.  If user belongs to supplementary groups with non-valid GIDs, those groups are not set.  Defaults to 1.

 -- dovecot-configuration parameter: non-negative-integer last-valid-gid

     Defaults to 0.

 -- dovecot-configuration parameter: non-negative-integer mail-max-keyword-length
     Maximum allowed length for mail keyword name.  It's only forced when trying to create new keywords.  Defaults to 50.

 -- dovecot-configuration parameter: colon-separated-file-name-list valid-chroot-dirs
     List of directories under which chrooting is allowed for mail processes (i.e. /var/mail will allow chrooting to /var/mail/foo/bar too).  This setting doesn't affect login-chroot mail-chroot or auth chroot settings.  If this setting is empty, "/./" in home dirs are ignored. WARNING: Never add directories here which local users can modify, that may lead to root exploit.  Usually this should be done only if you don't allow shell access for users.  <doc/wiki/Chrooting.txt>.  Defaults to ().

 -- dovecot-configuration parameter: string mail-chroot
     Default chroot directory for mail processes.  This can be overridden for specific users in user database by giving /./ in user's home directory (e.g. /home/./user chroots into /home).  Note that usually there is no real need to do chrooting, Dovecot doesn't allow users to access files outside their mail directory anyway.  If your home directories are prefixed with the chroot directory, append "/." to mail-chroot. <doc/wiki/Chrooting.txt>.  Defaults to "".

 -- dovecot-configuration parameter: file-name auth-socket-path
     UNIX socket path to master authentication server to find users.  This is used by imap (for shared users) and lda.  Defaults to "/var/run/dovecot/auth-userdb".

 -- dovecot-configuration parameter: file-name mail-plugin-dir
     Directory where to look up mail plugins.  Defaults to "/usr/lib/dovecot".

 -- dovecot-configuration parameter: space-separated-string-list mail-plugins
     List of plugins to load for all services.  Plugins specific to IMAP, LDA, etc. are added to this list in their own .conf files.  Defaults to ().

 -- dovecot-configuration parameter: non-negative-integer mail-cache-min-mail-count
     The minimum number of mails in a mailbox before updates are done to cache file.  This allows optimizing Dovecot's behavior to do less disk writes at the cost of more disk reads.  Defaults to 0.

 -- dovecot-configuration parameter: string mailbox-idle-check-interval
     When IDLE command is running, mailbox is checked once in a while to see if there are any new mails or other changes.  This setting defines the minimum time to wait between those checks.  Dovecot can also use dnotify, inotify and kqueue to find out immediately when changes occur.  Defaults to "30 secs".

 -- dovecot-configuration parameter: boolean mail-save-crlf?
     Save mails with CR+LF instead of plain LF.  This makes sending those mails take less CPU, especially with sendfile() syscall with Linux and FreeBSD. But it also creates a bit more disk I/O which may just make it slower.  Also note that if other software reads the mboxes/maildirs, they may handle the extra CRs wrong and cause problems.  Defaults to #f.

 -- dovecot-configuration parameter: boolean maildir-stat-dirs?
     By default LIST command returns all entries in maildir beginning with a dot.  Enabling this option makes Dovecot return only entries which are directories.  This is done by stat()ing each entry, so it causes more disk I/O.  (For systems setting struct dirent->d_type this check is free and it's done always regardless of this setting).  Defaults to #f.

 -- dovecot-configuration parameter: boolean maildir-copy-with-hardlinks?
     When copying a message, do it with hard links whenever possible.  This makes the performance much better, and it's unlikely to have any side effects. Defaults to #t.

 -- dovecot-configuration parameter: boolean maildir-very-dirty-syncs?
     Assume Dovecot is the only MUA accessing Maildir: Scan cur/ directory only when its mtime changes unexpectedly or when we can't find the mail otherwise.  Defaults to #f.

 -- dovecot-configuration parameter: space-separated-string-list mbox-read-locks
     Which locking methods to use for locking mbox.  There are four available:

     dotlock
          Create <mailbox>.lock file.  This is the oldest and most NFS-safe solution. If you want to use /var/mail/ like directory, the users will need write access to that directory.

     dotlock-try
          Same as dotlock, but if it fails because of permissions or because there isn't enough disk space, just skip it.

     fcntl
          Use this if possible.  Works with NFS too if lockd is used.

     flock
          May not exist in all systems.  Doesn't work with NFS.

     lockf
          May not exist in all systems.  Doesn't work with NFS.

     You can use multiple locking methods; if you do the order they're declared in is important to avoid deadlocks if other MTAs/MUAs are using multiple locking methods as well.  Some operating systems don't allow using some of them simultaneously.

 -- dovecot-configuration parameter: space-separated-string-list mbox-write-locks

 -- dovecot-configuration parameter: string mbox-lock-timeout
     Maximum time to wait for lock (all of them) before aborting.  Defaults to "5 mins".

 -- dovecot-configuration parameter: string mbox-dotlock-change-timeout
     If dotlock exists but the mailbox isn't modified in any way, override the lock file after this much time.  Defaults to "2 mins".

 -- dovecot-configuration parameter: boolean mbox-dirty-syncs?
     When mbox changes unexpectedly we have to fully read it to find out what changed.  If the mbox is large this can take a long time.  Since the change is usually just a newly appended mail, it'd be faster to simply read the new mails.  If this setting is enabled, Dovecot does this but still safely fallbacks to re-reading the whole mbox file whenever something in mbox isn't how it's expected to be.  The only real downside to this setting is that if some other MUA changes message flags, Dovecot doesn't notice it immediately.  Note that a full sync is done with SELECT, EXAMINE, EXPUNGE and CHECK commands.  Defaults to #t.

 -- dovecot-configuration parameter: boolean mbox-very-dirty-syncs?
     Like mbox-dirty-syncs, but don't do full syncs even with SELECT, EXAMINE, EXPUNGE or CHECK commands.  If this is set, mbox-dirty-syncs is ignored.  Defaults to #f.

 -- dovecot-configuration parameter: boolean mbox-lazy-writes?
     Delay writing mbox headers until doing a full write sync (EXPUNGE and CHECK commands and when closing the mailbox).  This is especially useful for POP3 where clients often delete all mails.  The downside is that our changes aren't immediately visible to other MUAs.  Defaults to #t.

 -- dovecot-configuration parameter: non-negative-integer mbox-min-index-size
     If mbox size is smaller than this (e.g. 100k), don't write index files. If an index file already exists it's still read, just not updated.  Defaults to 0.

 -- dovecot-configuration parameter: non-negative-integer mdbox-rotate-size
     Maximum dbox file size until it's rotated.  Defaults to 10000000.

 -- dovecot-configuration parameter: string mdbox-rotate-interval
     Maximum dbox file age until it's rotated.  Typically in days.  Day begins from midnight, so 1d = today, 2d = yesterday, etc.  0 = check disabled. Defaults to "1d".

 -- dovecot-configuration parameter: boolean mdbox-preallocate-space?
     When creating new mdbox files, immediately preallocate their size to mdbox-rotate-size.  This setting currently works only in Linux with some file systems (ext4, xfs).  Defaults to #f.

 -- dovecot-configuration parameter: string mail-attachment-dir
     sdbox and mdbox support saving mail attachments to external files, which also allows single instance storage for them.  Other backends don't support this for now.

     WARNING: This feature hasn't been tested much yet.  Use at your own risk.

     Directory root where to store mail attachments.  Disabled, if empty. Defaults to "".

 -- dovecot-configuration parameter: non-negative-integer mail-attachment-min-size
     Attachments smaller than this aren't saved externally.  It's also possible to write a plugin to disable saving specific attachments externally. Defaults to 128000.

 -- dovecot-configuration parameter: string mail-attachment-fs
     File system backend to use for saving attachments:

     posix
          No SiS done by Dovecot (but this might help FS's own deduplication)

     sis posix
          SiS with immediate byte-by-byte comparison during saving

     sis-queue posix
          SiS with delayed comparison and deduplication.

     Defaults to "sis posix".

 -- dovecot-configuration parameter: string mail-attachment-hash
     Hash format to use in attachment filenames.  You can add any text and variables: %{md4}, %{md5}, %{sha1}, %{sha256}, %{sha512}, %{size}.  Variables can be truncated, e.g. %{sha256:80} returns only first 80 bits. Defaults to "%{sha1}".

 -- dovecot-configuration parameter: non-negative-integer default-process-limit

     Defaults to 100.

 -- dovecot-configuration parameter: non-negative-integer default-client-limit

     Defaults to 1000.

 -- dovecot-configuration parameter: non-negative-integer default-vsz-limit
     Default VSZ (virtual memory size) limit for service processes.  This is mainly intended to catch and kill processes that leak memory before they eat up everything.  Defaults to 256000000.

 -- dovecot-configuration parameter: string default-login-user
     Login user is internally used by login processes.  This is the most untrusted user in Dovecot system.  It shouldn't have access to anything at all.  Defaults to "dovenull".

 -- dovecot-configuration parameter: string default-internal-user
     Internal user is used by unprivileged processes.  It should be separate from login user, so that login processes can't disturb other processes.  Defaults to "dovecot".

 -- dovecot-configuration parameter: string ssl?
     SSL/TLS support: yes, no, required.  <doc/wiki/SSL.txt>.  Defaults to "required".

 -- dovecot-configuration parameter: string ssl-cert
     PEM encoded X.509 SSL/TLS certificate (public key).  Defaults to "</etc/dovecot/default.pem".

 -- dovecot-configuration parameter: string ssl-key
     PEM encoded SSL/TLS private key.  The key is opened before dropping root privileges, so keep the key file unreadable by anyone but root.  Defaults to "</etc/dovecot/private/default.pem".

 -- dovecot-configuration parameter: string ssl-key-password
     If key file is password protected, give the password here.  Alternatively give it when starting dovecot with -p parameter.  Since this file is often world-readable, you may want to place this setting instead to a different. Defaults to "".

 -- dovecot-configuration parameter: string ssl-ca
     PEM encoded trusted certificate authority.  Set this only if you intend to use ssl-verify-client-cert? #t.  The file should contain the CA certificate(s) followed by the matching CRL(s).  (e.g. ssl-ca </etc/ssl/certs/ca.pem).  Defaults to "".

 -- dovecot-configuration parameter: boolean ssl-require-crl?
     Require that CRL check succeeds for client certificates.  Defaults to #t.

 -- dovecot-configuration parameter: boolean ssl-verify-client-cert?
     Request client to send a certificate.  If you also want to require it, set auth-ssl-require-client-cert? #t in auth section.  Defaults to #f.

 -- dovecot-configuration parameter: string ssl-cert-username-field
     Which field from certificate to use for username.  commonName and x500UniqueIdentifier are the usual choices.  You'll also need to set auth-ssl-username-from-cert? #t.  Defaults to "commonName".

 -- dovecot-configuration parameter: string ssl-min-protocol
     Minimum SSL protocol version to accept.  Defaults to "TLSv1".

 -- dovecot-configuration parameter: string ssl-cipher-list
     SSL ciphers to use.  Defaults to "ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@STRENGTH".

 -- dovecot-configuration parameter: string ssl-crypto-device
     SSL crypto device to use, for valid values run "openssl engine".  Defaults to "".

 -- dovecot-configuration parameter: string postmaster-address
     Address to use when sending rejection mails.  %d expands to recipient domain.  Defaults to "postmaster@%d".

 -- dovecot-configuration parameter: string hostname
     Hostname to use in various parts of sent mails (e.g. in Message-Id)  and in LMTP replies.  Default is the system's real hostname@domain.  Defaults to "".

 -- dovecot-configuration parameter: boolean quota-full-tempfail?
     If user is over quota, return with temporary failure instead of bouncing the mail.  Defaults to #f.

 -- dovecot-configuration parameter: file-name sendmail-path
     Binary to use for sending mails.  Defaults to "/usr/sbin/sendmail".

 -- dovecot-configuration parameter: string submission-host
     If non-empty, send mails via this SMTP host[:port] instead of sendmail. Defaults to "".

 -- dovecot-configuration parameter: string rejection-subject
     Subject: header to use for rejection mails.  You can use the same variables as for rejection-reason below.  Defaults to "Rejected: %s".

 -- dovecot-configuration parameter: string rejection-reason
     Human readable error message for rejection mails.  You can use variables:

     %n
          CRLF

     %r
          reason

     %s
          original subject

     %t
          recipient

     Defaults to "Your message to <%t> was automatically rejected:%n%r".

 -- dovecot-configuration parameter: string recipient-delimiter
     Delimiter character between local-part and detail in email address. Defaults to "+".

 -- dovecot-configuration parameter: string lda-original-recipient-header
     Header where the original recipient address (SMTP's RCPT TO: address) is taken from if not available elsewhere.  With dovecot-lda -a parameter overrides this.  A commonly used header for this is X-Original-To.  Defaults to "".

 -- dovecot-configuration parameter: boolean lda-mailbox-autocreate?
     Should saving a mail to a nonexistent mailbox automatically create it?. Defaults to #f.

 -- dovecot-configuration parameter: boolean lda-mailbox-autosubscribe?
     Should automatically created mailboxes be also automatically subscribed?. Defaults to #f.

 -- dovecot-configuration parameter: non-negative-integer imap-max-line-length
     Maximum IMAP command line length.  Some clients generate very long command lines with huge mailboxes, so you may need to raise this if you get "Too long argument" or "IMAP command line too large" errors often.  Defaults to 64000.

 -- dovecot-configuration parameter: string imap-logout-format
     IMAP logout format string:

     %i
          total number of bytes read from client

     %o
          total number of bytes sent to client.

     See doc/wiki/Variables.txt for a list of all the variables you can use.  Defaults to "in=%i out=%o deleted=%{deleted} expunged=%{expunged} trashed=%{trashed} hdr_count=%{fetch_hdr_count} hdr_bytes=%{fetch_hdr_bytes} body_count=%{fetch_body_count} body_bytes=%{fetch_body_bytes}".

 -- dovecot-configuration parameter: string imap-capability
     Override the IMAP CAPABILITY response.  If the value begins with '+', add the given capabilities on top of the defaults (e.g. +XFOO XBAR).  Defaults to "".

 -- dovecot-configuration parameter: string imap-idle-notify-interval
     How long to wait between "OK Still here" notifications when client is IDLEing.  Defaults to "2 mins".

 -- dovecot-configuration parameter: string imap-id-send
     ID field names and values to send to clients.  Using * as the value makes Dovecot use the default value.  The following fields have default values currently: name, version, os, os-version, support-url, support-email. Defaults to "".

 -- dovecot-configuration parameter: string imap-id-log
     ID fields sent by client to log.  * means everything.  Defaults to "".

 -- dovecot-configuration parameter: space-separated-string-list imap-client-workarounds
     Workarounds for various client bugs:

     delay-newmail
          Send EXISTS/RECENT new mail notifications only when replying to NOOP and CHECK commands.  Some clients ignore them otherwise, for example OSX Mail (<v2.1).  Outlook Express breaks more badly though, without this it may show user "Message no longer in server" errors.  Note that OE6 still breaks even with this workaround if synchronization is set to "Headers Only".

     tb-extra-mailbox-sep
          Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and adds extra / suffixes to mailbox names.  This option causes Dovecot to ignore the extra / instead of treating it as invalid mailbox name.

     tb-lsub-flags
          Show \Noselect flags for LSUB replies with LAYOUT=fs (e.g. mbox).  This makes Thunderbird realize they aren't selectable and show them greyed out, instead of only later giving "not selectable" popup error.

     Defaults to ().

 -- dovecot-configuration parameter: string imap-urlauth-host
     Host allowed in URLAUTH URLs sent by client.  "*" allows all.  Defaults to "".

Whew! Lots of configuration options.  The nice thing about it though is that Guix has a complete interface to Dovecot's configuration language.  This allows not only a nice way to declare configurations, but also offers reflective capabilities as well: users can write code to inspect and transform configurations from within Scheme.

However, it could be that you just want to get a dovecot.conf up and running.  In that case, you can pass an opaque-dovecot-configuration as the #:config parameter to dovecot-service.  As its name indicates, an opaque configuration does not have easy reflective capabilities.

Available opaque-dovecot-configuration fields are:

 -- opaque-dovecot-configuration parameter: package dovecot
     The dovecot package.

 -- opaque-dovecot-configuration parameter: string string
     The contents of the dovecot.conf, as a string.

For example, if your dovecot.conf is just the empty string, you could instantiate a dovecot service like this:

     (dovecot-service #:config
                      (opaque-dovecot-configuration
                       (string "")))

OpenSMTPD Service
.................

 -- Scheme Variable: opensmtpd-service-type
     This is the type of the OpenSMTPD (https://www.opensmtpd.org) service, whose value should be an opensmtpd-configuration object as in this example:

          (service opensmtpd-service-type
                   (opensmtpd-configuration
                     (config-file (local-file "./my-smtpd.conf"))))

 -- Data Type: opensmtpd-configuration
     Data type representing the configuration of opensmtpd.

     package (default: OPENSMTPD)
          Package object of the OpenSMTPD SMTP server.

     config-file (default: %DEFAULT-OPENSMTPD-FILE)
          File-like object of the OpenSMTPD configuration file to use.  By default it listens on the loopback network interface, and allows for mail from users and daemons on the local machine, as well as permitting email to remote servers.  Run man smtpd.conf for more information.

Exim Service
............

 -- Scheme Variable: exim-service-type
     This is the type of the Exim (https://exim.org) mail transfer agent (MTA), whose value should be an exim-configuration object as in this example:

          (service exim-service-type
                   (exim-configuration
                     (config-file (local-file "./my-exim.conf"))))

In order to use an exim-service-type service you must also have a mail-aliases-service-type service present in your operating-system (even if it has no aliases).

 -- Data Type: exim-configuration
     Data type representing the configuration of exim.

     package (default: EXIM)
          Package object of the Exim server.

     config-file (default: #f)
          File-like object of the Exim configuration file to use. If its value is #f then use the default configuration file from the package provided in package. The resulting configuration file is loaded after setting the exim_user and exim_group configuration variables.

Mail Aliases Service
....................

 -- Scheme Variable: mail-aliases-service-type
     This is the type of the service which provides /etc/aliases, specifying how to deliver mail to users on this system.

          (service mail-aliases-service-type
                   '(("postmaster" "bob")
                     ("bob" "bob@example.com" "bob@example2.com")))

The configuration for a mail-aliases-service-type service is an association list denoting how to deliver mail that comes to this system. Each entry is of the form (alias addresses ...), with alias specifying the local alias and addresses specifying where to deliver this user's mail.

The aliases aren't required to exist as users on the local system. In the above example, there doesn't need to be a postmaster entry in the operating-system's user-accounts in order to deliver the postmaster mail to bob (which subsequently would deliver mail to bob@example.com and bob@example2.com).

Kurznachrichtendienste
----------------------

The (gnu services messaging) module provides Guix service definitions for messaging services: currently only Prosody is supported.

Prosody Service
...............

 -- Scheme Variable: prosody-service-type
     This is the type for the Prosody XMPP communication server (https://prosody.im).  Its value must be a prosody-configuration record as in this example:

          (service prosody-service-type
                   (prosody-configuration
                    (modules-enabled (cons "groups" "mam" %default-modules-enabled))
                    (int-components
                     (list
                      (int-component-configuration
                       (hostname "conference.example.net")
                       (plugin "muc")
                       (mod-muc (mod-muc-configuration)))))
                    (virtualhosts
                     (list
                      (virtualhost-configuration
                       (domain "example.net"))))))

     See below for details about prosody-configuration.

By default, Prosody does not need much configuration.  Only one virtualhosts field is needed: it specifies the domain you wish Prosody to serve.

You can perform various sanity checks on the generated configuration with the prosodyctl check command.

Prosodyctl will also help you to import certificates from the letsencrypt directory so that the prosody user can access them.  See https://prosody.im/doc/letsencrypt.

     prosodyctl --root cert import /etc/letsencrypt/live

The available configuration parameters follow.  Each parameter definition is preceded by its type; for example, string-list foo indicates that the foo parameter should be specified as a list of strings.  Types starting with maybe- denote parameters that won't show up in prosody.cfg.lua when their value is 'disabled.

There is also a way to specify the configuration as a string, if you have an old prosody.cfg.lua file that you want to port over from some other system; see the end for more details.

The file-object type designates either a file-like object (see file-like objects) or a file name.

Available prosody-configuration fields are:

 -- prosody-configuration parameter: package prosody
     The Prosody package.

 -- prosody-configuration parameter: file-name data-path
     Location of the Prosody data storage directory.  See https://prosody.im/doc/configure.  Defaults to "/var/lib/prosody".

 -- prosody-configuration parameter: file-object-list plugin-paths
     Additional plugin directories.  They are searched in all the specified paths in order.  See https://prosody.im/doc/plugins_directory.  Defaults to ().

 -- prosody-configuration parameter: file-name certificates
     Every virtual host and component needs a certificate so that clients and servers can securely verify its identity.  Prosody will automatically load certificates/keys from the directory specified here.  Defaults to "/etc/prosody/certs".

 -- prosody-configuration parameter: string-list admins
     This is a list of accounts that are admins for the server.  Note that you must create the accounts separately.  See https://prosody.im/doc/admins and https://prosody.im/doc/creating_accounts.  Example: (admins '("user1@example.com" "user2@example.net")) Defaults to ().

 -- prosody-configuration parameter: boolean use-libevent?
     Enable use of libevent for better performance under high load.  See https://prosody.im/doc/libevent.  Defaults to #f.

 -- prosody-configuration parameter: module-list modules-enabled
     This is the list of modules Prosody will load on startup.  It looks for mod_modulename.lua in the plugins folder, so make sure that exists too.  Documentation on modules can be found at: https://prosody.im/doc/modules.  Defaults to ("roster" "saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" "version" "uptime" "time" "ping" "pep" "register" "admin_adhoc").

 -- prosody-configuration parameter: string-list modules-disabled
     "offline", "c2s" and "s2s" are auto-loaded, but should you want to disable them then add them to this list.  Defaults to ().

 -- prosody-configuration parameter: file-object groups-file
     Path to a text file where the shared groups are defined.  If this path is empty then mod_groups does nothing.  See https://prosody.im/doc/modules/mod_groups.  Defaults to "/var/lib/prosody/sharedgroups.txt".

 -- prosody-configuration parameter: boolean allow-registration?
     Disable account creation by default, for security.  See https://prosody.im/doc/creating_accounts.  Defaults to #f.

 -- prosody-configuration parameter: maybe-ssl-configuration ssl
     These are the SSL/TLS-related settings.  Most of them are disabled so to use Prosody's defaults.  If you do not completely understand these options, do not add them to your config, it is easy to lower the security of your server using them.  See https://prosody.im/doc/advanced_ssl_config.

     Available ssl-configuration fields are:

      -- ssl-configuration parameter: maybe-string protocol
          This determines what handshake to use.

      -- ssl-configuration parameter: maybe-file-name key
          Path to your private key file.

      -- ssl-configuration parameter: maybe-file-name certificate
          Path to your certificate file.

      -- ssl-configuration parameter: file-object capath
          Path to directory containing root certificates that you wish Prosody to trust when verifying the certificates of remote servers.  Defaults to "/etc/ssl/certs".

      -- ssl-configuration parameter: maybe-file-object cafile
          Path to a file containing root certificates that you wish Prosody to trust. Similar to capath but with all certificates concatenated together.

      -- ssl-configuration parameter: maybe-string-list verify
          A list of verification options (these mostly map to OpenSSL's set_verify() flags).

      -- ssl-configuration parameter: maybe-string-list options
          A list of general options relating to SSL/TLS.  These map to OpenSSL's set_options().  For a full list of options available in LuaSec, see the LuaSec source.

      -- ssl-configuration parameter: maybe-non-negative-integer depth
          How long a chain of certificate authorities to check when looking for a trusted root certificate.

      -- ssl-configuration parameter: maybe-string ciphers
          An OpenSSL cipher string.  This selects what ciphers Prosody will offer to clients, and in what order.

      -- ssl-configuration parameter: maybe-file-name dhparam
          A path to a file containing parameters for Diffie-Hellman key exchange.  You can create such a file with: openssl dhparam -out /etc/prosody/certs/dh-2048.pem 2048

      -- ssl-configuration parameter: maybe-string curve
          Curve for Elliptic curve Diffie-Hellman. Prosody's default is "secp384r1".

      -- ssl-configuration parameter: maybe-string-list verifyext
          A list of "extra" verification options.

      -- ssl-configuration parameter: maybe-string password
          Password for encrypted private keys.

 -- prosody-configuration parameter: boolean c2s-require-encryption?
     Whether to force all client-to-server connections to be encrypted or not. See https://prosody.im/doc/modules/mod_tls.  Defaults to #f.

 -- prosody-configuration parameter: string-list disable-sasl-mechanisms
     Set of mechanisms that will never be offered.  See https://prosody.im/doc/modules/mod_saslauth.  Defaults to ("DIGEST-MD5").

 -- prosody-configuration parameter: boolean s2s-require-encryption?
     Whether to force all server-to-server connections to be encrypted or not. See https://prosody.im/doc/modules/mod_tls.  Defaults to #f.

 -- prosody-configuration parameter: boolean s2s-secure-auth?
     Whether to require encryption and certificate authentication.  This provides ideal security, but requires servers you communicate with to support encryption AND present valid, trusted certificates.  See https://prosody.im/doc/s2s#security.  Defaults to #f.

 -- prosody-configuration parameter: string-list s2s-insecure-domains
     Many servers don't support encryption or have invalid or self-signed certificates.  You can list domains here that will not be required to authenticate using certificates.  They will be authenticated using DNS.  See https://prosody.im/doc/s2s#security.  Defaults to ().

 -- prosody-configuration parameter: string-list s2s-secure-domains
     Even if you leave s2s-secure-auth? disabled, you can still require valid certificates for some domains by specifying a list here.  See https://prosody.im/doc/s2s#security.  Defaults to ().

 -- prosody-configuration parameter: string authentication
     Select the authentication backend to use.  The default provider stores passwords in plaintext and uses Prosody's configured data storage to store the authentication data.  If you do not trust your server please see https://prosody.im/doc/modules/mod_auth_internal_hashed for information about using the hashed backend.  See also https://prosody.im/doc/authentication Defaults to "internal_plain".

 -- prosody-configuration parameter: maybe-string log
     Set logging options.  Advanced logging configuration is not yet supported by the Guix Prosody Service.  See https://prosody.im/doc/logging. Defaults to "*syslog".

 -- prosody-configuration parameter: file-name pidfile
     File to write pid in.  See https://prosody.im/doc/modules/mod_posix. Defaults to "/var/run/prosody/prosody.pid".

 -- prosody-configuration parameter: maybe-non-negative-integer http-max-content-size
     Maximum allowed size of the HTTP body (in bytes).

 -- prosody-configuration parameter: maybe-string http-external-url
     Some modules expose their own URL in various ways.  This URL is built from the protocol, host and port used.  If Prosody sits behind a proxy, the public URL will be http-external-url instead.  See https://prosody.im/doc/http#external_url.

 -- prosody-configuration parameter: virtualhost-configuration-list virtualhosts
     A host in Prosody is a domain on which user accounts can be created.  For example if you want your users to have addresses like "john.smith@example.com" then you need to add a host "example.com".  All options in this list will apply only to this host.

     Note: the name "virtual" host is used in configuration to avoid confusion with the actual physical host that Prosody is installed on.  A single Prosody instance can serve many domains, each one defined as a VirtualHost entry in Prosody's configuration.  Conversely a server that hosts a single domain would have just one VirtualHost entry.

     See https://prosody.im/doc/configure#virtual_host_settings.

     Available virtualhost-configuration fields are:

     all these prosody-configuration fields: admins, use-libevent?, modules-enabled, modules-disabled, groups-file, allow-registration?, ssl, c2s-require-encryption?, disable-sasl-mechanisms, s2s-require-encryption?, s2s-secure-auth?, s2s-insecure-domains, s2s-secure-domains, authentication, log, http-max-content-size, http-external-url, raw-content, plus:
      -- virtualhost-configuration parameter: string domain
          Domain you wish Prosody to serve.

 -- prosody-configuration parameter: int-component-configuration-list int-components
     Components are extra services on a server which are available to clients, usually on a subdomain of the main server (such as "mycomponent.example.com").  Example components might be chatroom servers, user directories, or gateways to other protocols.

     Internal components are implemented with Prosody-specific plugins.  To add an internal component, you simply fill the hostname field, and the plugin you wish to use for the component.

     See https://prosody.im/doc/components.  Defaults to ().

     Available int-component-configuration fields are:

     all these prosody-configuration fields: admins, use-libevent?, modules-enabled, modules-disabled, groups-file, allow-registration?, ssl, c2s-require-encryption?, disable-sasl-mechanisms, s2s-require-encryption?, s2s-secure-auth?, s2s-insecure-domains, s2s-secure-domains, authentication, log, http-max-content-size, http-external-url, raw-content, plus:
      -- int-component-configuration parameter: string hostname
          Hostname of the component.

      -- int-component-configuration parameter: string plugin
          Plugin you wish to use for the component.

      -- int-component-configuration parameter: maybe-mod-muc-configuration mod-muc
          Multi-user chat (MUC) is Prosody's module for allowing you to create hosted chatrooms/conferences for XMPP users.

          General information on setting up and using multi-user chatrooms can be found in the "Chatrooms" documentation (https://prosody.im/doc/chatrooms), which you should read if you are new to XMPP chatrooms.

          See also https://prosody.im/doc/modules/mod_muc.

          Available mod-muc-configuration fields are:

           -- mod-muc-configuration parameter: string name
               The name to return in service discovery responses.  Defaults to "Prosody Chatrooms".

           -- mod-muc-configuration parameter: string-or-boolean restrict-room-creation
               If #t, this will only allow admins to create new chatrooms. Otherwise anyone can create a room.  The value "local" restricts room creation to users on the service's parent domain.  E.g. user@example.com can create rooms on rooms.example.com.  The value "admin" restricts to service administrators only.  Defaults to #f.

           -- mod-muc-configuration parameter: non-negative-integer max-history-messages
               Maximum number of history messages that will be sent to the member that has just joined the room.  Defaults to 20.

 -- prosody-configuration parameter: ext-component-configuration-list ext-components
     External components use XEP-0114, which most standalone components support. To add an external component, you simply fill the hostname field.  See https://prosody.im/doc/components.  Defaults to ().

     Available ext-component-configuration fields are:

     all these prosody-configuration fields: admins, use-libevent?, modules-enabled, modules-disabled, groups-file, allow-registration?, ssl, c2s-require-encryption?, disable-sasl-mechanisms, s2s-require-encryption?, s2s-secure-auth?, s2s-insecure-domains, s2s-secure-domains, authentication, log, http-max-content-size, http-external-url, raw-content, plus:
      -- ext-component-configuration parameter: string component-secret
          Password which the component will use to log in.

      -- ext-component-configuration parameter: string hostname
          Hostname of the component.

 -- prosody-configuration parameter: non-negative-integer-list component-ports
     Port(s) Prosody listens on for component connections.  Defaults to (5347).

 -- prosody-configuration parameter: string component-interface
     Interface Prosody listens on for component connections.  Defaults to "127.0.0.1".

 -- prosody-configuration parameter: maybe-raw-content raw-content
     Raw content that will be added to the configuration file.

It could be that you just want to get a prosody.cfg.lua up and running.  In that case, you can pass an opaque-prosody-configuration record as the value of prosody-service-type.  As its name indicates, an opaque configuration does not have easy reflective capabilities. Available opaque-prosody-configuration fields are:

 -- opaque-prosody-configuration parameter: package prosody
     The prosody package.

 -- opaque-prosody-configuration parameter: string prosody.cfg.lua
     The contents of the prosody.cfg.lua to use.

For example, if your prosody.cfg.lua is just the empty string, you could instantiate a prosody service like this:

     (service prosody-service-type
              (opaque-prosody-configuration
               (prosody.cfg.lua "")))

BitlBee Service
...............

BitlBee (http://bitlbee.org) is a gateway that provides an IRC interface to a variety of messaging protocols such as XMPP.

 -- Scheme Variable: bitlbee-service-type
     This is the service type for the BitlBee (http://bitlbee.org) IRC gateway daemon.  Its value is a bitlbee-configuration (see below).

     To have BitlBee listen on port 6667 on localhost, add this line to your services:

          (service bitlbee-service-type)

 -- Data Type: bitlbee-configuration
     This is the configuration for BitlBee, with the following fields:

     interface (default: "127.0.0.1")
     port (default: 6667)
          Listen on the network interface corresponding to the IP address specified in INTERFACE, on PORT.

          When INTERFACE is 127.0.0.1, only local clients can connect; when it is 0.0.0.0, connections can come from any networking interface.

     package (default: bitlbee)
          The BitlBee package to use.

     plugins (Vorgabe: '())
          List of plugin packages to use---e.g., bitlbee-discord.

     extra-settings (default: "")
          Configuration snippet added as-is to the BitlBee configuration file.

Quassel Service
...............

Quassel (https://quassel-irc.org/) is a distributed IRC client, meaning that one or more clients can attach to and detach from the central core.

 -- Scheme Variable: quassel-service-type
     This is the service type for the Quassel (https://quassel-irc.org/) IRC backend daemon.  Its value is a quassel-configuration (see below).

 -- Data Type: quassel-configuration
     This is the configuration for Quassel, with the following fields:

     quassel (default: quassel)
          The Quassel package to use.

     interface (default: "::,0.0.0.0")

     port (default: 4242)
          Listen on the network interface(s) corresponding to the IPv4 or IPv6 interfaces specified in the comma delimited INTERFACE, on PORT.

     loglevel (default: "Info")
          The level of logging desired.  Accepted values are Debug, Info, Warning and Error.

Telefondienste
--------------

This section describes how to set up and run a Murmur server.  Murmur is the server of the Mumble (https://mumble.info) voice-over-IP (VoIP) suite.

 -- Data Type: murmur-configuration
     The service type for the Murmur server.  An example configuration can look like this:

          (service murmur-service-type
                   (murmur-configuration
                    (welcome-text
                      "Welcome to this Mumble server running on Guix!")
                    (cert-required? #t) ;disallow text password logins
                    (ssl-cert "/etc/letsencrypt/live/mumble.example.com/fullchain.pem")
                    (ssl-key "/etc/letsencrypt/live/mumble.example.com/privkey.pem")))

     After reconfiguring your system, you can manually set the murmur SuperUser password with the command that is printed during the activation phase.

     It is recommended to register a normal Mumble user account and grant it admin or moderator rights.  You can use the mumble client to login as new normal user, register yourself, and log out.  For the next step login with the name SuperUser use the SuperUser password that you set previously, and grant your newly registered mumble user administrator or moderator rights and create some channels.

     Available murmur-configuration fields are:

     package (default: mumble)
          Package that contains bin/murmurd.

     user (default: "murmur")
          User who will run the Murmur server.

     group (default: "murmur")
          Group of the user who will run the murmur server.

     port (default: 64738)
          Port on which the server will listen.

     welcome-text (default: "")
          Welcome text sent to clients when they connect.

     server-password (default: "")
          Password the clients have to enter in order to connect.

     max-users (default: 100)
          Maximum of users that can be connected to the server at once.

     max-user-bandwidth (default: #f)
          Maximum voice traffic a user can send per second.

     database-file (default: "/var/lib/murmur/db.sqlite")
          File name of the sqlite database.  The service's user will become the owner of the directory.

     log-file (default: "/var/log/murmur/murmur.log")
          File name of the log file.  The service's user will become the owner of the directory.

     autoban-attempts (default: 10)
          Maximum number of logins a user can make in autoban-timeframe without getting auto banned for autoban-time.

     autoban-timeframe (default: 120)
          Timeframe for autoban in seconds.

     autoban-time (default: 300)
          Amount of time in seconds for which a client gets banned when violating the autoban limits.

     opus-threshold (default: 100)
          Percentage of clients that need to support opus before switching over to opus audio codec.

     channel-nesting-limit (default: 10)
          How deep channels can be nested at maximum.

     channelname-regex (default: #f)
          A string in form of a Qt regular expression that channel names must conform to.

     username-regex (default: #f)
          A string in form of a Qt regular expression that user names must conform to.

     text-message-length (default: 5000)
          Maximum size in bytes that a user can send in one text chat message.

     image-message-length (default: (* 128 1024))
          Maximum size in bytes that a user can send in one image message.

     cert-required? (default: #f)
          If it is set to #t clients that use weak password authentification will not be accepted. Users must have completed the certificate wizard to join.

     remember-channel? (Vorgabe: #f)
          Should murmur remember the last channel each user was in when they disconnected and put them into the remembered channel when they rejoin.

     allow-html? (default: #f)
          Should html be allowed in text messages, user comments, and channel descriptions.

     allow-ping? (default: #f)
          Setting to true exposes the current user count, the maximum user count, and the server's maximum bandwidth per client to unauthenticated users. In the Mumble client, this information is shown in the Connect dialog.

          Disabling this setting will prevent public listing of the server.

     bonjour? (default: #f)
          Should the server advertise itself in the local network through the bonjour protocol.

     send-version? (default: #f)
          Should the murmur server version be exposed in ping requests.

     log-days (default: 31)
          Murmur also stores logs in the database, which are accessible via RPC.  The default is 31 days of months, but you can set this setting to 0 to keep logs forever, or -1 to disable logging to the database.

     obfuscate-ips? (Vorgabe: #t)
          Should logged ips be obfuscated to protect the privacy of users.

     ssl-cert (default: #f)
          File name of the SSL/TLS certificate used for encrypted connections.

               (ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem")

     ssl-key (default: #f)
          Filepath to the ssl private key used for encrypted connections.

               (ssl-key "/etc/letsencrypt/live/example.com/privkey.pem")

     ssl-dh-params (default: #f)
          File name of a PEM-encoded file with Diffie-Hellman parameters for the SSL/TLS encryption.  Alternatively you set it to "@ffdhe2048", "@ffdhe3072", "@ffdhe4096", "@ffdhe6144" or "@ffdhe8192" to use bundled parameters from RFC 7919.

     ssl-ciphers (default: #f)
          The ssl-ciphers option chooses the cipher suites to make available for use in SSL/TLS.

          This option is specified using OpenSSL cipher list notation (https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT).

          It is recommended that you try your cipher string using 'openssl ciphers <string>' before setting it here, to get a feel for which cipher suites you will get.  After setting this option, it is recommend that you inspect your Murmur log to ensure that Murmur is using the cipher suites that you expected it to.

          Note: Changing this option may impact the backwards compatibility of your Murmur server, and can remove the ability for older Mumble clients to be able to connect to it.

     public-registration (default: #f)
          Must be a <murmur-public-registration-configuration> record or #f.

          You can optionally register your server in the public server list that the mumble client shows on startup.  You cannot register your server if you have set a server-password, or set allow-ping to #f.

          It might take a few hours until it shows up in the public list.

     file (default: #f)
          Optional alternative override for this configuration.

 -- Data Type: murmur-public-registration-configuration
     Configuration for public registration of a murmur service.

     name
          This is a display name for your server. Not to be confused with the hostname.

     password
          A password to identify your registration.  Subsequent updates will need the same password. Don't lose your password.

     url
          This should be a http:// or https:// link to your web site.

     hostname (default: #f)
          By default your server will be listed by its IP address.  If it is set your server will be linked by this host name instead.

Überwachungsdienste
-------------------

Tailon Service
..............

Tailon (https://tailon.readthedocs.io/) is a web application for viewing and searching log files.

The following example will configure the service with default values.  By default, Tailon can be accessed on port 8080 (http://localhost:8080).

     (service tailon-service-type)

The following example customises more of the Tailon configuration, adding sed to the list of allowed commands.

     (service tailon-service-type
              (tailon-configuration
                (config-file
                  (tailon-configuration-file
                    (allowed-commands '("tail" "grep" "awk" "sed"))))))

 -- Data Type: tailon-configuration
     Data type representing the configuration of Tailon.  This type has the following parameters:

     config-file (default: (tailon-configuration-file))
          The configuration file to use for Tailon. This can be set to a tailon-configuration-file record value, or any gexp (see G-Ausdrücke).

          For example, to instead use a local file, the local-file function can be used:

               (service tailon-service-type
                        (tailon-configuration
                          (config-file (local-file "./my-tailon.conf"))))

     package (default: tailon)
          The tailon package to use.

 -- Data Type: tailon-configuration-file
     Data type representing the configuration options for Tailon.  This type has the following parameters:

     files (default: (list "/var/log"))
          List of files to display. The list can include strings for a single file or directory, or a list, where the first item is the name of a subsection, and the remaining items are the files or directories in that subsection.

     bind (default: "localhost:8080")
          Address and port to which Tailon should bind on.

     relative-root (default: #f)
          URL path to use for Tailon, set to #f to not use a path.

     allow-transfers? (default: #t)
          Allow downloading the log files in the web interface.

     follow-names? (default: #t)
          Allow tailing of not-yet existent files.

     tail-lines (default: 200)
          Number of lines to read initially from each file.

     allowed-commands (default: (list "tail" "grep" "awk"))
          Commands to allow running. By default, sed is disabled.

     debug? (default: #f)
          Set debug? to #t to show debug messages.

     wrap-lines (default: #t)
          Initial line wrapping state in the web interface. Set to #t to initially wrap lines (the default), or to #f to initially not wrap lines.

     http-auth (default: #f)
          HTTP authentication type to use. Set to #f to disable authentication (the default). Supported values are "digest" or "basic".

     users (default: #f)
          If HTTP authentication is enabled (see http-auth), access will be restricted to the credentials provided here. To configure users, use a list of pairs, where the first element of the pair is the username, and the 2nd element of the pair is the password.

               (tailon-configuration-file
                 (http-auth "basic")
                 (users     '(("user1" . "password1")
                              ("user2" . "password2"))))

Darkstat Service
................

Darkstat is a packet sniffer that captures network traffic, calculates statistics about usage, and serves reports over HTTP.

 -- Variable: Scheme Variable darkstat-service-type
     This is the service type for the darkstat (https://unix4lyfe.org/darkstat/) service, its value must be a darkstat-configuration record as in this example:

          (service darkstat-service-type
                   (darkstat-configuration
                     (interface "eno1")))

 -- Data Type: darkstat-configuration
     Data type representing the configuration of darkstat.

     package (default: darkstat)
          The darkstat package to use.

     interface
          Capture traffic on the specified network interface.

     port (default: "667")
          Bind the web interface to the specified port.

     bind-address (default: "127.0.0.1")
          Bind the web interface to the specified address.

     base (default: "/")
          Specify the path of the base URL.  This can be useful if darkstat is accessed via a reverse proxy.

Prometheus Node Exporter Service
................................

The Prometheus ``node exporter'' makes hardware and operating system statistics provided by the Linux kernel available for the Prometheus monitoring system.  This service should be deployed on all physical nodes and virtual machines, where monitoring these statistics is desirable.

 -- Variable: Scheme variable prometheus-node-exporter-service-type
     This is the service type for the prometheus-node-exporter (https://github.com/prometheus/node_exporter/) service, its value must be a prometheus-node-exporter-configuration record as in this example:

          (service prometheus-node-exporter-service-type
                   (prometheus-node-exporter-configuration
                     (web-listen-address ":9100")))

 -- Data Type: prometheus-node-exporter-configuration
     Repräsentiert die Konfiguration von node_exporter.

     package (Vorgabe: go-github-com-prometheus-node-exporter)
          Das Paket für den prometheus-node-exporter, was benutzt werden soll.

     web-listen-address (Vorgabe: ":9100")
          Bind the web interface to the specified address.

Zabbix server
.............

Zabbix provides monitoring metrics, among others network utilization, CPU load and disk space consumption:

  * High performance, high capacity (able to monitor hundreds of thousands of devices).

  * Auto-discovery of servers and network devices and interfaces.

  * Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others.

  * Distributed monitoring with centralized web administration.

  * Native high performance agents.

  * SLA, and ITIL KPI metrics on reporting.

  * High-level (business) view of monitored resources through user-defined visual console screens and dashboards.

  * Remote command execution through Zabbix proxies.

Available zabbix-server-configuration fields are:

 -- zabbix-server-configuration parameter: package zabbix-server
     The zabbix-server package.

 -- zabbix-server-configuration parameter: string user
     User who will run the Zabbix server.

     Defaults to "zabbix".

 -- zabbix-server-configuration parameter: group group
     Group who will run the Zabbix server.

     Defaults to "zabbix".

 -- zabbix-server-configuration parameter: string db-host
     Database host name.

     Defaults to "127.0.0.1".

 -- zabbix-server-configuration parameter: string db-name
     Database name.

     Defaults to "zabbix".

 -- zabbix-server-configuration parameter: string db-user
     Database user.

     Defaults to "zabbix".

 -- zabbix-server-configuration parameter: string db-password
     Database password.  Please, use include-files with DBPassword=SECRET inside a specified file instead.

     Defaults to "".

 -- zabbix-server-configuration parameter: number db-port
     Database port.

     Defaults to 5432.

 -- zabbix-server-configuration parameter: string log-type
     Specifies where log messages are written to:

       * system - syslog.

       * file - file specified with log-file parameter.

       * console - standard output.

     Defaults to "".

 -- zabbix-server-configuration parameter: string log-file
     Log file name for log-type file parameter.

     Defaults to "/var/log/zabbix/server.log".

 -- zabbix-server-configuration parameter: string pid-file
     Name of PID file.

     Defaults to "/var/run/zabbix/zabbix_server.pid".

 -- zabbix-server-configuration parameter: string ssl-ca-location
     The location of certificate authority (CA) files for SSL server certificate verification.

     Defaults to "/etc/ssl/certs/ca-certificates.crt".

 -- zabbix-server-configuration parameter: string ssl-cert-location
     Location of SSL client certificates.

     Defaults to "/etc/ssl/certs".

 -- zabbix-server-configuration parameter: string extra-options
     Extra options will be appended to Zabbix server configuration file.

     Defaults to "".

 -- zabbix-server-configuration parameter: include-files include-files
     You may include individual files or all files in a directory in the configuration file.

     Defaults to ().

Zabbix agent
............

Zabbix agent gathers information for Zabbix server.

Available zabbix-agent-configuration fields are:

 -- zabbix-agent-configuration parameter: package zabbix-agent
     The zabbix-agent package.

 -- zabbix-agent-configuration parameter: string user
     User who will run the Zabbix agent.

     Defaults to "zabbix".

 -- zabbix-agent-configuration parameter: group group
     Group who will run the Zabbix agent.

     Defaults to "zabbix".

 -- zabbix-agent-configuration parameter: string hostname
     Unique, case sensitive hostname which is required for active checks and must match hostname as configured on the server.

     Defaults to "Zabbix server".

 -- zabbix-agent-configuration parameter: string log-type
     Specifies where log messages are written to:

       * system - syslog.

       * file - file specified with log-file parameter.

       * console - standard output.

     Defaults to "".

 -- zabbix-agent-configuration parameter: string log-file
     Log file name for log-type file parameter.

     Defaults to "/var/log/zabbix/agent.log".

 -- zabbix-agent-configuration parameter: string pid-file
     Name of PID file.

     Defaults to "/var/run/zabbix/zabbix_agent.pid".

 -- zabbix-agent-configuration parameter: list server
     List of IP addresses, optionally in CIDR notation, or hostnames of Zabbix servers and Zabbix proxies.  Incoming connections will be accepted only from the hosts listed here.

     Defaults to ("127.0.0.1").

 -- zabbix-agent-configuration parameter: list server-active
     List of IP:port (or hostname:port) pairs of Zabbix servers and Zabbix proxies for active checks.  If port is not specified, default port is used. If this parameter is not specified, active checks are disabled.

     Defaults to ("127.0.0.1").

 -- zabbix-agent-configuration parameter: string extra-options
     Extra options will be appended to Zabbix server configuration file.

     Defaults to "".

 -- zabbix-agent-configuration parameter: include-files include-files
     You may include individual files or all files in a directory in the configuration file.

     Defaults to ().

Zabbix front-end
................

This service provides a WEB interface to Zabbix server.

Available zabbix-front-end-configuration fields are:

 -- zabbix-front-end-configuration parameter: nginx-server-configuration-list nginx
     NGINX configuration.

 -- zabbix-front-end-configuration parameter: string db-host
     Database host name.

     Defaults to "localhost".

 -- zabbix-front-end-configuration parameter: number db-port
     Database port.

     Defaults to 5432.

 -- zabbix-front-end-configuration parameter: string db-name
     Database name.

     Defaults to "zabbix".

 -- zabbix-front-end-configuration parameter: string db-user
     Database user.

     Defaults to "zabbix".

 -- zabbix-front-end-configuration parameter: string db-password
     Database password.  Please, use db-secret-file instead.

     Defaults to "".

 -- zabbix-front-end-configuration parameter: string db-secret-file
     Secret file which will be appended to zabbix.conf.php file.  This file contains credentials for use by Zabbix front-end.  You are expected to create it manually.

     Defaults to "".

 -- zabbix-front-end-configuration parameter: string zabbix-host
     Zabbix server hostname.

     Defaults to "localhost".

 -- zabbix-front-end-configuration parameter: number zabbix-port
     Zabbix server port.

     Defaults to 10051.

Kerberos-Dienste
----------------

The (gnu services kerberos) module provides services relating to the authentication protocol Kerberos.

Krb5 Service
............

Programs using a Kerberos client library normally expect a configuration file in /etc/krb5.conf.  This service generates such a file from a definition provided in the operating system declaration.  It does not cause any daemon to be started.

No ``keytab'' files are provided by this service---you must explicitly create them.  This service is known to work with the MIT client library, mit-krb5.  Other implementations have not been tested.

 -- Scheme Variable: krb5-service-type
     A service type for Kerberos 5 clients.

Here is an example of its use:

     (service krb5-service-type
              (krb5-configuration
               (default-realm "EXAMPLE.COM")
               (allow-weak-crypto? #t)
               (realms (list
                        (krb5-realm
                         (name "EXAMPLE.COM")
                         (admin-server "groucho.example.com")
                         (kdc "karl.example.com"))
                        (krb5-realm
                         (name "ARGRX.EDU")
                         (admin-server "kerb-admin.argrx.edu")
                         (kdc "keys.argrx.edu"))))))

This example provides a Kerberos 5 client configuration which:

  * Recognizes two realms, viz: ``EXAMPLE.COM'' and ``ARGRX.EDU'', both of which have distinct administration servers and key distribution centers;

  * Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly specified by clients;

  * Accepts services which only support encryption types known to be weak.

The krb5-realm and krb5-configuration types have many fields. Only the most commonly used ones are described here.  For a full list, and more detailed explanation of each, see the MIT krb5.conf documentation.

 -- Data Type: krb5-realm

     name
          This field is a string identifying the name of the realm.  A common convention is to use the fully qualified DNS name of your organization, converted to upper case.

     admin-server
          This field is a string identifying the host where the administration server is running.

     kdc
          This field is a string identifying the key distribution center for the realm.

 -- Data Type: krb5-configuration

     allow-weak-crypto? (default: #f)
          If this flag is #t then services which only offer encryption algorithms known to be weak will be accepted.

     default-realm (default: #f)
          This field should be a string identifying the default Kerberos realm for the client.  You should set this field to the name of your Kerberos realm.  If this value is #f then a realm must be specified with every Kerberos principal when invoking programs such as kinit.

     realms
          This should be a non-empty list of krb5-realm objects, which clients may access.  Normally, one of them will have a name field matching the default-realm field.

PAM krb5 Service
................

The pam-krb5 service allows for login authentication and password management via Kerberos.  You will need this service if you want PAM enabled applications to authenticate users using Kerberos.

 -- Scheme Variable: pam-krb5-service-type
     A service type for the Kerberos 5 PAM module.

 -- Data Type: pam-krb5-configuration
     Data type representing the configuration of the Kerberos 5 PAM module This type has the following parameters:

     pam-krb5 (default: pam-krb5)
          The pam-krb5 package to use.

     minimum-uid (default: 1000)
          The smallest user ID for which Kerberos authentications should be attempted.  Local accounts with lower values will silently fail to authenticate.

Web-Dienste
-----------

The (gnu services web) module provides the Apache HTTP Server, the nginx web server, and also a fastcgi wrapper daemon.

Apache HTTP Server
..................

 -- Scheme Variable: httpd-service-type
     Service type for the Apache HTTP (https://httpd.apache.org/) server (httpd).  The value for this service type is a httpd-configuration record.

     A simple example configuration is given below.

          (service httpd-service-type
                   (httpd-configuration
                     (config
                       (httpd-config-file
                         (server-name "www.example.com")
                         (document-root "/srv/http/www.example.com")))))

     Other services can also extend the httpd-service-type to add to the configuration.

          (simple-service 'my-extra-server httpd-service-type
                          (list
                            (httpd-virtualhost
                              "*:80"
                              (list (string-append
                                     "ServerName "www.example.com
                                      DocumentRoot \"/srv/http/www.example.com\"")))))

The details for the httpd-configuration, httpd-module, httpd-config-file and httpd-virtualhost record types are given below.

 -- Data Type: httpd-configuration
     This data type represents the configuration for the httpd service.

     package (default: httpd)
          The httpd package to use.

     pid-file (default: "/var/run/httpd")
          The pid file used by the shepherd-service.

     config (default: (httpd-config-file))
          The configuration file to use with the httpd service. The default value is a httpd-config-file record, but this can also be a different G-expression that generates a file, for example a plain-file. A file outside of the store can also be specified through a string.

 -- Data Type: httpd-module
     This data type represents a module for the httpd service.

     name
          The name of the module.

     file
          The file for the module. This can be relative to the httpd package being used, the absolute location of a file, or a G-expression for a file within the store, for example (file-append mod-wsgi "/modules/mod_wsgi.so").

 -- Scheme Variable: %default-httpd-modules
     A default list of httpd-module objects.

 -- Data Type: httpd-config-file
     This data type represents a configuration file for the httpd service.

     modules (default: %default-httpd-modules)
          The modules to load. Additional modules can be added here, or loaded by additional configuration.

          For example, in order to handle requests for PHP files, you can use Apache’s mod_proxy_fcgi module along with php-fpm-service-type:

               (service httpd-service-type
                        (httpd-configuration
                         (config
                          (httpd-config-file
                           (modules (cons*
                                     (httpd-module
                                      (name "proxy_module")
                                      (file "modules/mod_proxy.so"))
                                     (httpd-module
                                      (name "proxy_fcgi_module")
                                      (file "modules/mod_proxy_fcgi.so"))
                                     %default-httpd-modules))
                           (extra-config (list "\
               <FilesMatch \\.php$>
                   SetHandler \"proxy:unix:/var/run/php-fpm.sock|fcgi://localhost/\"
               </FilesMatch>"))))))
               (service php-fpm-service-type
                        (php-fpm-configuration
                         (socket "/var/run/php-fpm.sock")
                         (socket-group "httpd")))

     server-root (default: httpd)
          The ServerRoot in the configuration file, defaults to the httpd package. Directives including Include and LoadModule are taken as relative to the server root.

     server-name (default: #f)
          The ServerName in the configuration file, used to specify the request scheme, hostname and port that the server uses to identify itself.

          This doesn't need to be set in the server config, and can be specifyed in virtual hosts. The default is #f to not specify a ServerName.

     document-root (default: "/srv/http")
          The DocumentRoot from which files will be served.

     listen (default: '("80"))
          The list of values for the Listen directives in the config file. The value should be a list of strings, when each string can specify the port number to listen on, and optionally the IP address and protocol to use.

     pid-file (default: "/var/run/httpd")
          The PidFile to use. This should match the pid-file set in the httpd-configuration so that the Shepherd service is configured correctly.

     error-log (default: "/var/log/httpd/error_log")
          The ErrorLog to which the server will log errors.

     user (default: "httpd")
          The User which the server will answer requests as.

     group (default: "httpd")
          The Group which the server will answer requests as.

     extra-config (default: (list "TypesConfig etc/httpd/mime.types"))
          A flat list of strings and G-expressions which will be added to the end of the configuration file.

          Any values which the service is extended with will be appended to this list.

 -- Data Type: httpd-virtualhost
     This data type represents a virtualhost configuration block for the httpd service.

     These should be added to the extra-config for the httpd-service.

          (simple-service 'my-extra-server httpd-service-type
                          (list
                            (httpd-virtualhost
                              "*:80"
                              (list (string-append
                                     "ServerName "www.example.com
                                      DocumentRoot \"/srv/http/www.example.com\"")))))

     addresses-and-ports
          The addresses and ports for the VirtualHost directive.

     contents
          The contents of the VirtualHost directive, this should be a list of strings and G-expressions.

NGINX
.....

 -- Scheme Variable: nginx-service-type
     Service type for the NGinx (https://nginx.org/) web server.  The value for this service type is a <nginx-configuration> record.

     A simple example configuration is given below.

          (service nginx-service-type
                   (nginx-configuration
                     (server-blocks
                       (list (nginx-server-configuration
                               (server-name '("www.example.com"))
                               (root "/srv/http/www.example.com"))))))

     In addition to adding server blocks to the service configuration directly, this service can be extended by other services to add server blocks, as in this example:

          (simple-service 'my-extra-server nginx-service-type
                          (list (nginx-server-configuration
                                  (root "/srv/http/extra-website")
                                  (try-files (list "$uri" "$uri/index.html")))))

At startup, nginx has not yet read its configuration file, so it uses a default file to log error messages.  If it fails to load its configuration file, that is where error messages are logged.  After the configuration file is loaded, the default error log file changes as per configuration.  In our case, startup error messages can be found in /var/run/nginx/logs/error.log, and after configuration in /var/log/nginx/error.log.  The second location can be changed with the LOG-DIRECTORY configuration option.

 -- Data Type: nginx-configuration
     This data type represents the configuration for NGinx. Some configuration can be done through this and the other provided record types, or alternatively, a config file can be provided.

     nginx (default: nginx)
          The nginx package to use.

     log-directory (default: "/var/log/nginx")
          The directory to which NGinx will write log files.

     run-directory (default: "/var/run/nginx")
          The directory in which NGinx will create a pid file, and write temporary files.

     server-blocks (default: '())
          A list of server blocks to create in the generated configuration file, the elements should be of type <nginx-server-configuration>.

          The following example would setup NGinx to serve www.example.com from the /srv/http/www.example.com directory, without using HTTPS.

               (service nginx-service-type
                        (nginx-configuration
                          (server-blocks
                            (list (nginx-server-configuration
                                    (server-name '("www.example.com"))
                                    (root "/srv/http/www.example.com"))))))

     upstream-blocks (default: '())
          A list of upstream blocks to create in the generated configuration file, the elements should be of type <nginx-upstream-configuration>.

          Configuring upstreams through the upstream-blocks can be useful when combined with locations in the <nginx-server-configuration> records.  The following example creates a server configuration with one location configuration, that will proxy requests to a upstream configuration, which will handle requests with two servers.

               (service
                 nginx-service-type
                 (nginx-configuration
                   (server-blocks
                     (list (nginx-server-configuration
                             (server-name '("www.example.com"))
                             (root "/srv/http/www.example.com")
                             (locations
                               (list
                                 (nginx-location-configuration
                                 (uri "/path1")
                                 (body '("proxy_pass http://server-proxy;"))))))))
                   (upstream-blocks
                     (list (nginx-upstream-configuration
                             (name "server-proxy")
                             (servers (list "server1.example.com"
                                            "server2.example.com")))))))

     file (default: #f)
          If a configuration FILE is provided, this will be used, rather than generating a configuration file from the provided log-directory, run-directory, server-blocks and upstream-blocks.  For proper operation, these arguments should match what is in FILE to ensure that the directories are created when the service is activated.

          This can be useful if you have an existing configuration file, or it's not possible to do what is required through the other parts of the nginx-configuration record.

     server-names-hash-bucket-size (default: #f)
          Bucket size for the server names hash tables, defaults to #f to use the size of the processors cache line.

     server-names-hash-bucket-max-size (default: #f)
          Maximum bucket size for the server names hash tables.

     extra-content (Vorgabe: "")
          Extra content for the http block.  Should be string or a string valued G-expression.

 -- Data Type: nginx-server-configuration
     Data type representing the configuration of an nginx server block.  This type has the following parameters:

     listen (default: '("80" "443 ssl"))
          Each listen directive sets the address and port for IP, or the path for a UNIX-domain socket on which the server will accept requests.  Both address and port, or only address or only port can be specified.  An address may also be a hostname, for example:

               '("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000")

     server-name (default: (list 'default))
          A list of server names this server represents. 'default represents the default server for connections matching no other server.

     root (default: "/srv/http")
          Root of the website nginx will serve.

     locations (default: '())
          A list of nginx-location-configuration or nginx-named-location-configuration records to use within this server block.

     index (default: (list "index.html"))
          Index files to look for when clients ask for a directory.  If it cannot be found, Nginx will send the list of files in the directory.

     try-files (default: '())
          A list of files whose existence is checked in the specified order. nginx will use the first file it finds to process the request.

     ssl-certificate (default: #f)
          Where to find the certificate for secure connections.  Set it to #f if you don't have a certificate or you don't want to use HTTPS.

     ssl-certificate-key (default: #f)
          Where to find the private key for secure connections.  Set it to #f if you don't have a key or you don't want to use HTTPS.

     server-tokens? (default: #f)
          Whether the server should add its configuration to response.

     raw-content (default: '())
          A list of raw lines added to the server block.

 -- Data Type: nginx-upstream-configuration
     Data type representing the configuration of an nginx upstream block. This type has the following parameters:

     name
          Name for this group of servers.

     servers
          Specify the addresses of the servers in the group.  The address can be specified as a IP address (e.g. 127.0.0.1), domain name (e.g. backend1.example.com) or a path to a UNIX socket using the prefix unix:.  For addresses using an IP address or domain name, the default port is 80, and a different port can be specified explicitly.

 -- Data Type: nginx-location-configuration
     Data type representing the configuration of an nginx location block. This type has the following parameters:

     uri
          URI which this location block matches.

     body
          Body of the location block, specified as a list of strings. This can contain many configuration directives.  For example, to pass requests to a upstream server group defined using an nginx-upstream-configuration block, the following directive would be specified in the body (list "proxy_pass http://upstream-name;").

 -- Data Type: nginx-named-location-configuration
     Data type representing the configuration of an nginx named location block. Named location blocks are used for request redirection, and not used for regular request processing.  This type has the following parameters:

     name
          Name to identify this location block.

     body
          See nginx-location-configuration body, as the body for named location blocks can be used in a similar way to the nginx-location-configuration body.  One restriction is that the body of a named location block cannot contain location blocks.

Varnish Cache
.............

Varnish is a fast cache server that sits in between web applications and end users.  It proxies requests from clients and caches the accessed URLs such that multiple requests for the same resource only creates one request to the back-end.

 -- Scheme Variable: varnish-service-type
     Service type for the Varnish daemon.

 -- Data Type: varnish-configuration
     Data type representing the varnish service configuration.  This type has the following parameters:

     package (Vorgabe: varnish)
          Das Varnish-Paket, was benutzt werden soll.

     name (Vorgabe: "default")
          A name for this Varnish instance.  Varnish will create a directory in /var/varnish/ with this name and keep temporary files there.  If the name starts with a forward slash, it is interpreted as an absolute directory name.

          Pass the -n argument to other Varnish programs to connect to the named instance, e.g. varnishncsa -n default.

     backend (Vorgabe: "localhost:8080")
          The backend to use.  This option has no effect if vcl is set.

     vcl (Vorgabe: #f)
          The VCL (Varnish Configuration Language) program to run.  If this is #f, Varnish will proxy backend using the default configuration.  Otherwise this must be a file-like object with valid VCL syntax.

          For example, to mirror www.gnu.org (http://www.gnu.org) with VCL you can do something along these lines:

               (define %gnu-mirror
                 (plain-file
                  "gnu.vcl"
                  "vcl 4.1;
               backend gnu { .host = "www.gnu.org"; }"))

               (operating-system
                 ...
                 (services (cons (service varnish-service-type
                                          (varnish-configuration
                                           (listen '(":80"))
                                           (vcl %gnu-mirror)))
                                 %base-services)))

          The configuration of an already running Varnish instance can be inspected and changed using the varnishadm program.

          Consult the Varnish User Guide (https://varnish-cache.org/docs/) and Varnish Book (https://book.varnish-software.com/4.0/) for comprehensive documentation on Varnish and its configuration language.

     listen (Vorgabe: '("localhost:80"))
          List of addresses Varnish will listen on.

     storage (Vorgabe: '("malloc,128m"))
          List of storage backends that will be available in VCL.

     parameters (Vorgabe: '())
          List of run-time parameters in the form '(("parameter" . "value")).

     extra-options (Vorgabe: '())
          Additional arguments to pass to the varnishd process.

FastCGI
.......

FastCGI is an interface between the front-end and the back-end of a web service.  It is a somewhat legacy facility; new web services should generally just talk HTTP between the front-end and the back-end.  However there are a number of back-end services such as PHP or the optimized HTTP Git repository access that use FastCGI, so we have support for it in Guix.

To use FastCGI, you configure the front-end web server (e.g., nginx) to dispatch some subset of its requests to the fastcgi backend, which listens on a local TCP or UNIX socket.  There is an intermediary fcgiwrap program that sits between the actual backend process and the web server. The front-end indicates which backend program to run, passing that information to the fcgiwrap process.

 -- Scheme Variable: fcgiwrap-service-type
     A service type for the fcgiwrap FastCGI proxy.

 -- Data Type: fcgiwrap-configuration
     Data type representing the configuration of the fcgiwrap service. This type has the following parameters:

     package (default: fcgiwrap)
          The fcgiwrap package to use.

     socket (default: tcp:127.0.0.1:9000)
          The socket on which the fcgiwrap process should listen, as a string. Valid SOCKET values include unix:/PATH/TO/UNIX/SOCKET, tcp:DOT.TED.QU.AD:PORT and tcp6:[IPV6_ADDR]:port.

     user (default: fcgiwrap)
     group (default: fcgiwrap)
          The user and group names, as strings, under which to run the fcgiwrap process.  The fastcgi service will ensure that if the user asks for the specific user or group names fcgiwrap that the corresponding user and/or group is present on the system.

          It is possible to configure a FastCGI-backed web service to pass HTTP authentication information from the front-end to the back-end, and to allow fcgiwrap to run the back-end process as a corresponding local user. To enable this capability on the back-end., run fcgiwrap as the root user and group.  Note that this capability also has to be configured on the front-end as well.

PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI implementation with some additional features useful for sites of any size.

These features include:

  * Adaptive process spawning

  * Basic statistics (similar to Apache's mod_status)

  * Advanced process management with graceful stop/start

  * Ability to start workers with different uid/gid/chroot/environment and different php.ini (replaces safe_mode)

  * Stdout & stderr logging

  * Emergency restart in case of accidental opcode cache destruction

  * Accelerated upload support

  * Support for a "slowlog"

  * Enhancements to FastCGI, such as fastcgi_finish_request() - a special function to finish request & flush all data while continuing to do something time-consuming (video converting, stats processing, etc.)

... and much more.

 -- Scheme Variable: php-fpm-service-type
     A Service type for php-fpm.

 -- Data Type: php-fpm-configuration
     Data Type for php-fpm service configuration.

     php (default: php)
          The php package to use.

     socket (default: (string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock"))
          The address on which to accept FastCGI requests.  Valid syntaxes are:

          "ip.add.re.ss:port"
               Listen on a TCP socket to a specific address on a specific port.

          "port"
               Listen on a TCP socket to all addresses on a specific port.

          "/path/to/unix/socket"
               Listen on a unix socket.

     user (default: php-fpm)
          User who will own the php worker processes.

     group (default: php-fpm)
          Group of the worker processes.

     socket-user (default: php-fpm)
          User who can speak to the php-fpm socket.

     socket-group (default: php-fpm)
          Group that can speak to the php-fpm socket.

     pid-file (default: (string-append "/var/run/php" (version-major (package-version php)) "-fpm.pid"))
          The process id of the php-fpm process is written to this file once the service has started.

     log-file (default: (string-append "/var/log/php" (version-major (package-version php)) "-fpm.log"))
          Log for the php-fpm master process.

     process-manager (default: (php-fpm-dynamic-process-manager-configuration))
          Detailed settings for the php-fpm process manager.  Must be either:

          <php-fpm-dynamic-process-manager-configuration>

          <php-fpm-static-process-manager-configuration>

          <php-fpm-on-demand-process-manager-configuration>

     display-errors (default #f)
          Determines whether php errors and warning should be sent to clients and displayed in their browsers.  This is useful for local php development, but a security risk for public sites, as error messages can reveal passwords and personal data.

     timezone (default #f)
          Specifies php_admin_value[date.timezone] parameter.

     workers-logfile (default (string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log"))
          This file will log the stderr outputs of php worker processes.  Can be set to #f to disable logging.

     file (default #f)
          An optional override of the whole configuration.  You can use the mixed-text-file function or an absolute filepath for it.

 -- Data type: php-fpm-dynamic-process-manager-configuration
     Data Type for the dynamic php-fpm process manager.  With the dynamic process manager, spare worker processes are kept around based on it's configured limits.

     max-children (default: 5)
          Maximum of worker processes.

     start-servers (default: 2)
          How many worker processes should be started on start-up.

     min-spare-servers (default: 1)
          How many spare worker processes should be kept around at minimum.

     max-spare-servers (default: 3)
          How many spare worker processes should be kept around at maximum.

 -- Data type: php-fpm-static-process-manager-configuration
     Data Type for the static php-fpm process manager.  With the static process manager, an unchanging number of worker processes are created.

     max-children (default: 5)
          Maximum of worker processes.

 -- Data type: php-fpm-on-demand-process-manager-configuration
     Data Type for the on-demand php-fpm process manager.  With the on-demand process manager, worker processes are only created as requests arrive.

     max-children (default: 5)
          Maximum of worker processes.

     process-idle-timeout (default: 10)
          The time in seconds after which a process with no requests is killed.

 -- Scheme Procedure: nginx-php-fpm-location
     [#:nginx-package nginx]  [socket (string-append "/var/run/php"
     (version-major (package-version php))  "-fpm.sock")] A helper function to
     quickly add php to an nginx-server-configuration.

A simple services setup for nginx with php can look like this:

     (services (cons* (service dhcp-client-service-type)
                      (service php-fpm-service-type)
                      (service nginx-service-type
                               (nginx-server-configuration
                                (server-name '("example.com"))
                                (root "/srv/http/")
                                (locations
                                 (list (nginx-php-location)))
                                (listen '("80"))
                                (ssl-certificate #f)
                                (ssl-certificate-key #f)))
                      %base-services))

The cat avatar generator is a simple service to demonstrate the use of php-fpm in Nginx.  It is used to generate cat avatar from a seed, for instance the hash of a user's email address.

 -- Scheme Procedure: cat-avatar-generator-service
     [#:cache-dir "/var/cache/cat-avatar-generator"]  [#:package
     cat-avatar-generator]  [#:configuration (nginx-server-configuration)] Returns an nginx-server-configuration that inherits configuration. It extends the nginx configuration to add a server block that serves package, a version of cat-avatar-generator.  During execution, cat-avatar-generator will be able to use cache-dir as its cache directory.

A simple setup for cat-avatar-generator can look like this:

     (services (cons* (cat-avatar-generator-service
                       #:configuration
                       (nginx-server-configuration
                         (server-name '("example.com"))))
                      ...
                      %base-services))

Hpcguix-web
...........

The https://github.com/UMCUGenetics/hpcguix-web/ (hpcguix-web) program is a customizable web interface to browse Guix packages, initially designed for users of high-performance computing (HPC)  clusters.

 -- Scheme Variable: hpcguix-web-service-type
     The service type for hpcguix-web.

 -- Data Type: hpcguix-web-configuration
     Data type for the hpcguix-web service configuration.

     specs
          A gexp (see G-Ausdrücke) specifying the hpcguix-web service configuration.  The main items available in this spec are:

          title-prefix (Vorgabe: "hpcguix | ")
               Das Präfix der Webseitentitel.

          guix-command (Vorgabe: "guix")
               Der guix-Befehl.

          package-filter-proc (Vorgabe: (const #t))
               Eine Prozedur, die festlegt, wie anzuzeigende Pakete gefiltert werden.

          package-page-extension-proc (Vorgabe: (const '()))
               Extension package for hpcguix-web.

          menu (Vorgabe: '())
               Additional entry in page menu.

          channels (Vorgabe: %default-channels)
               List of channels from which the package list is built (see Kanäle).

          package-list-expiration (Vorgabe: (* 12 3600))
               The expiration time, in seconds, after which the package list is rebuilt from the latest instances of the given channels.

          See the hpcguix-web repository for a complete example (https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm).

     package (Vorgabe: hpcguix-web)
          Das hpcguix-web-Paket, was benutzt werden soll.

A typical hpcguix-web service declaration looks like this:

     (service hpcguix-web-service-type
              (hpcguix-web-configuration
               (specs
                #~(define site-config
                    (hpcweb-configuration
                     (title-prefix "Guix-HPC - ")
                     (menu '(("/about" "ABOUT"))))))))

     The hpcguix-web service periodically updates the package list it publishes by pulling channels from Git.  To that end, it needs to access X.509 certificates so that it can authenticate Git servers when communicating over HTTPS, and it assumes that /etc/ssl/certs contains those certificates.

     Thus, make sure to add nss-certs or another certificate package to the packages field of your configuration.  X.509-Zertifikate, for more information on X.509 certificates.

Zertifikatsdienste
------------------

The (gnu services certbot) module provides a service to automatically obtain a valid TLS certificate from the Let's Encrypt certificate authority.  These certificates can then be used to serve content securely over HTTPS or other TLS-based protocols, with the knowledge that the client will be able to verify the server's authenticity.

Let's Encrypt (https://letsencrypt.org/) provides the certbot tool to automate the certification process.  This tool first securely generates a key on the server.  It then makes a request to the Let's Encrypt certificate authority (CA) to sign the key.  The CA checks that the request originates from the host in question by using a challenge-response protocol, requiring the server to provide its response over HTTP.  If that protocol completes successfully, the CA signs the key, resulting in a certificate. That certificate is valid for a limited period of time, and therefore to continue to provide TLS services, the server needs to periodically ask the CA to renew its signature.

The certbot service automates this process: the initial key generation, the initial certification request to the Let's Encrypt service, the web server challenge/response integration, writing the certificate to disk, the automated periodic renewals, and the deployment tasks associated with the renewal (e.g. reloading services, copying keys with different permissions).

Certbot is run twice a day, at a random minute within the hour.  It won't do anything until your certificates are due for renewal or revoked, but running it regularly would give your service a chance of staying online in case a Let's Encrypt-initiated revocation happened for some reason.

By using this service, you agree to the ACME Subscriber Agreement, which can be found there: https://acme-v01.api.letsencrypt.org/directory.

 -- Scheme Variable: certbot-service-type
     A service type for the certbot Let's Encrypt client.  Its value must be a certbot-configuration record as in this example:

          (define %nginx-deploy-hook
            (program-file
             "nginx-deploy-hook"
             #~(let ((pid (call-with-input-file "/var/run/nginx/pid" read)))
                 (kill pid SIGHUP))))

          (service certbot-service-type
                   (certbot-configuration
                    (email "foo@example.net")
                    (certificates
                     (list
                      (certificate-configuration
                       (domains '("example.net" "www.example.net"))
                       (deploy-hook %nginx-deploy-hook))
                      (certificate-configuration
                       (domains '("bar.example.net")))))))

     See below for details about certbot-configuration.

 -- Data Type: certbot-configuration
     Data type representing the configuration of the certbot service. This type has the following parameters:

     package (default: certbot)
          The certbot package to use.

     webroot (default: /var/www)
          The directory from which to serve the Let's Encrypt challenge/response files.

     certificates (default: ())
          A list of certificates-configurations for which to generate certificates and request signatures.  Each certificate has a name and several domains.

     email
          Mandatory email used for registration, recovery contact, and important account notifications.

     rsa-key-size (default: 2048)
          Size of the RSA key.

     default-location (default: see below)
          The default nginx-location-configuration.  Because certbot needs to be able to serve challenges and responses, it needs to be able to run a web server.  It does so by extending the nginx web service with an nginx-server-configuration listening on the DOMAINS on port 80, and which has a nginx-location-configuration for the /.well-known/ URI path subspace used by Let's Encrypt.  See Web-Dienste, for more on these nginx configuration data types.

          Requests to other URL paths will be matched by the default-location, which if present is added to all nginx-server-configurations.

          By default, the default-location will issue a redirect from http://DOMAIN/... to https://DOMAIN/..., leaving you to define what to serve on your site via https.

          Pass #f to not issue a default location.

 -- Data Type: certificate-configuration
     Data type representing the configuration of a certificate.  This type has the following parameters:

     name (default: see below)
          This name is used by Certbot for housekeeping and in file paths; it doesn't affect the content of the certificate itself.  To see certificate names, run certbot certificates.

          Its default is the first provided domain.

     domains (default: ())
          The first domain provided will be the subject CN of the certificate, and all domains will be Subject Alternative Names on the certificate.

     deploy-hook (default: #f)
          Command to be run in a shell once for each successfully issued certificate. For this command, the shell variable $RENEWED_LINEAGE will point to the config live subdirectory (for example, "/etc/letsencrypt/live/example.com") containing the new certificates and keys; the shell variable $RENEWED_DOMAINS will contain a space-delimited list of renewed certificate domains (for example, "example.com www.example.com".

For each certificate-configuration, the certificate is saved to /etc/letsencrypt/live/NAME/fullchain.pem and the key is saved to /etc/letsencrypt/live/NAME/privkey.pem.

DNS-Dienste
-----------

The (gnu services dns) module provides services related to the domain name system (DNS).  It provides a server service for hosting an authoritative DNS server for multiple zones, slave or master.  This service uses Knot DNS (https://www.knot-dns.cz/).  And also a caching and forwarding DNS server for the LAN, which uses dnsmasq (http://www.thekelleys.org.uk/dnsmasq/doc.html).

Knot-Dienst
...........

An example configuration of an authoritative server for two zones, one master and one slave, is:

     (define-zone-entries example.org.zone
     ;; Name TTL Class Type Data
       ("@"  ""  "IN"  "A"  "127.0.0.1")
       ("@"  ""  "IN"  "NS" "ns")
       ("ns" ""  "IN"  "A"  "127.0.0.1"))

     (define master-zone
       (knot-zone-configuration
         (domain "example.org")
         (zone (zone-file
                 (origin "example.org")
                 (entries example.org.zone)))))

     (define slave-zone
       (knot-zone-configuration
         (domain "plop.org")
         (dnssec-policy "default")
         (master (list "plop-master"))))

     (define plop-master
       (knot-remote-configuration
         (id "plop-master")
         (address (list "208.76.58.171"))))

     (operating-system
       ;; ...
       (services (cons* (service knot-service-type
                          (knot-configuration
                            (remotes (list plop-master))
                            (zones (list master-zone slave-zone))))
                        ;; ...
                        %base-services)))

 -- Scheme Variable: knot-service-type
     This is the type for the Knot DNS server.

     Knot DNS is an authoritative DNS server, meaning that it can serve multiple zones, that is to say domain names you would buy from a registrar.  This server is not a resolver, meaning that it can only resolve names for which it is authoritative.  This server can be configured to serve zones as a master server or a slave server as a per-zone basis.  Slave zones will get their data from masters, and will serve it as an authoritative server.  From the point of view of a resolver, there is no difference between master and slave.

     The following data types are used to configure the Knot DNS server:

 -- Data Type: knot-key-configuration
     Data type representing a key.  This type has the following parameters:

     id (default: "")
          An identifier for other configuration fields to refer to this key. IDs must be unique and must not be empty.

     algorithm (default: #f)
          The algorithm to use.  Choose between #f, 'hmac-md5, 'hmac-sha1, 'hmac-sha224, 'hmac-sha256, 'hmac-sha384 and 'hmac-sha512.

     secret (default: "")
          The secret key itself.

 -- Data Type: knot-acl-configuration
     Data type representing an Access Control List (ACL) configuration.  This type has the following parameters:

     id (default: "")
          An identifier for ether configuration fields to refer to this key. IDs must be unique and must not be empty.

     address (default: '())
          An ordered list of IP addresses, network subnets, or network ranges represented with strings.  The query must match one of them.  Empty value means that address match is not required.

     key (default: '())
          An ordered list of references to keys represented with strings.  The string must match a key ID defined in a knot-key-configuration.  No key means that a key is not require to match that ACL.

     action (default: '())
          An ordered list of actions that are permitted or forbidden by this ACL. Possible values are lists of zero or more elements from 'transfer, 'notify and 'update.

     deny? (default: #f)
          When true, the ACL defines restrictions.  Listed actions are forbidden. When false, listed actions are allowed.

 -- Data Type: zone-entry
     Data type represnting a record entry in a zone file.  This type has the following parameters:

     name (default: "@")
          The name of the record.  "@" refers to the origin of the zone. Names are relative to the origin of the zone.  For example, in the example.org zone, "ns.example.org" actually refers to ns.example.org.example.org.  Names ending with a dot are absolute, which means that "ns.example.org." refers to ns.example.org.

     ttl (default: "")
          The Time-To-Live (TTL) of this record.  If not set, the default TTL is used.

     class (default: "IN")
          The class of the record.  Knot currently supports only "IN" and partially "CH".

     type (default: "A")
          The type of the record.  Common types include A (IPv4 address), AAAA (IPv6 address), NS (Name Server) and MX (Mail eXchange).  Many other types are defined.

     data (default: "")
          The data contained in the record.  For instance an IP address associated with an A record, or a domain name associated with an NS record.  Remember that domain names are relative to the origin unless they end with a dot.

 -- Data Type: zone-file
     Data type representing the content of a zone file.  This type has the following parameters:

     entries (default: '())
          The list of entries.  The SOA record is taken care of, so you don't need to put it in the list of entries.  This list should probably contain an entry for your primary authoritative DNS server.  Other than using a list of entries directly, you can use define-zone-entries to define a object containing the list of entries more easily, that you can later pass to the entries field of the zone-file.

     origin (default: "")
          The name of your zone.  This parameter cannot be empty.

     ns (default: "ns")
          The domain of your primary authoritative DNS server.  The name is relative to the origin, unless it ends with a dot.  It is mandatory that this primary DNS server corresponds to an NS record in the zone and that it is associated to an IP address in the list of entries.

     mail (default: "hostmaster")
          An email address people can contact you at, as the owner of the zone.  This is translated as <mail>@<origin>.

     serial (default: 1)
          The serial number of the zone.  As this is used to keep track of changes by both slaves and resolvers, it is mandatory that it never decreases. Always increment it when you make a change in your zone.

     refresh (default: (* 2 24 3600))
          The frequency at which slaves will do a zone transfer.  This value is a number of seconds.  It can be computed by multiplications or with (string->duration).

     retry (default: (* 15 60))
          The period after which a slave will retry to contact its master when it fails to do so a first time.

     expiry (default: (* 14 24 3600))
          Default TTL of records.  Existing records are considered correct for at most this amount of time.  After this period, resolvers will invalidate their cache and check again that it still exists.

     nx (default: 3600)
          Default TTL of inexistant records.  This delay is usually short because you want your new domains to reach everyone quickly.

 -- Data Type: knot-remote-configuration
     Data type representing a remote configuration.  This type has the following parameters:

     id (default: "")
          An identifier for other configuration fields to refer to this remote. IDs must be unique and must not be empty.

     address (default: '())
          An ordered list of destination IP addresses.  Addresses are tried in sequence.  An optional port can be given with the @ separator.  For instance: (list "1.2.3.4" "2.3.4.5@53").  Default port is 53.

     via (default: '())
          An ordered list of source IP addresses.  An empty list will have Knot choose an appropriate source IP.  An optional port can be given with the @ separator.  The default is to choose at random.

     key (default: #f)
          A reference to a key, that is a string containing the identifier of a key defined in a knot-key-configuration field.

 -- Data Type: knot-keystore-configuration
     Data type representing a keystore to hold dnssec keys.  This type has the following parameters:

     id (default: "")
          The id of the keystore.  It must not be empty.

     backend (default: 'pem)
          The backend to store the keys in.  Can be 'pem or 'pkcs11.

     config (default: "/var/lib/knot/keys/keys")
          The configuration string of the backend.  An example for the PKCS#11 is: "pkcs11:token=knot;pin-value=1234 /gnu/store/.../lib/pkcs11/libsofthsm2.so".  For the pem backend, the string reprensents a path in the file system.

 -- Data Type: knot-policy-configuration
     Data type representing a dnssec policy.  Knot DNS is able to automatically sign your zones.  It can either generate and manage your keys automatically or use keys that you generate.

     Dnssec is usually implemented using two keys: a Key Signing Key (KSK) that is used to sign the second, and a Zone Signing Key (ZSK) that is used to sign the zone.  In order to be trusted, the KSK needs to be present in the parent zone (usually a top-level domain).  If your registrar supports dnssec, you will have to send them your KSK's hash so they can add a DS record in their zone.  This is not automated and need to be done each time you change your KSK.

     The policy also defines the lifetime of keys.  Usually, ZSK can be changed easily and use weaker cryptographic functions (they use lower parameters) in order to sign records quickly, so they are changed often.  The KSK however requires manual interaction with the registrar, so they are changed less often and use stronger parameters because they sign only one record.

     This type has the following parameters:

     id (default: "")
          The id of the policy.  It must not be empty.

     keystore (default: "default")
          A reference to a keystore, that is a string containing the identifier of a keystore defined in a knot-keystore-configuration field.  The "default" identifier means the default keystore (a kasp database that was setup by this service).

     manual? (default: #f)
          Whether the key management is manual or automatic.

     single-type-signing? (default: #f)
          When #t, use the Single-Type Signing Scheme.

     algorithm (default: "ecdsap256sha256")
          An algorithm of signing keys and issued signatures.

     ksk-size (default: 256)
          The length of the KSK.  Note that this value is correct for the default algorithm, but would be unsecure for other algorithms.

     zsk-size (default: 256)
          The length of the ZSK.  Note that this value is correct for the default algorithm, but would be unsecure for other algorithms.

     dnskey-ttl (default: 'default)
          The TTL value for DNSKEY records added into zone apex.  The special 'default value means same as the zone SOA TTL.

     zsk-lifetime (default: (* 30 24 3600))
          The period between ZSK publication and the next rollover initiation.

     propagation-delay (default: (* 24 3600))
          An extra delay added for each key rollover step.  This value should be high enough to cover propagation of data from the master server to all slaves.

     rrsig-lifetime (default: (* 14 24 3600))
          A validity period of newly issued signatures.

     rrsig-refresh (default: (* 7 24 3600))
          A period how long before a signature expiration the signature will be refreshed.

     nsec3? (default: #f)
          When #t, NSEC3 will be used instead of NSEC.

     nsec3-iterations (default: 5)
          The number of additional times the hashing is performed.

     nsec3-salt-length (default: 8)
          The length of a salt field in octets, which is appended to the original owner name before hashing.

     nsec3-salt-lifetime (default: (* 30 24 3600))
          The validity period of newly issued salt field.

 -- Data Type: knot-zone-configuration
     Data type representing a zone served by Knot.  This type has the following parameters:

     domain (default: "")
          The domain served by this configuration.  It must not be empty.

     file (default: "")
          The file where this zone is saved.  This parameter is ignored by master zones.  Empty means default location that depends on the domain name.

     zone (default: (zone-file))
          The content of the zone file.  This parameter is ignored by slave zones.  It must contain a zone-file record.

     master (default: '())
          A list of master remotes.  When empty, this zone is a master.  When set, this zone is a slave.  This is a list of remotes identifiers.

     ddns-master (default: #f)
          The main master.  When empty, it defaults to the first master in the list of masters.

     notify (default: '())
          A list of slave remote identifiers.

     acl (default: '())
          A list of acl identifiers.

     semantic-checks? (default: #f)
          When set, this adds more semantic checks to the zone.

     disable-any? (default: #f)
          When set, this forbids queries of the ANY type.

     zonefile-sync (default: 0)
          The delay between a modification in memory and on disk.  0 means immediate synchronization.

     serial-policy (default: 'increment)
          A policy between 'increment and 'unixtime.

 -- Data Type: knot-configuration
     Data type representing the Knot configuration.  This type has the following parameters:

     knot (default: knot)
          The Knot package.

     run-directory (default: "/var/run/knot")
          The run directory.  This directory will be used for pid file and sockets.

     listen-v4 (default: "0.0.0.0")
          An ip address on which to listen.

     listen-v6 (default: "::")
          An ip address on which to listen.

     listen-port (default: 53)
          A port on which to listen.

     keys (default: '())
          The list of knot-key-configuration used by this configuration.

     acls (default: '())
          The list of knot-acl-configuration used by this configuration.

     remotes (default: '())
          The list of knot-remote-configuration used by this configuration.

     zones (default: '())
          The list of knot-zone-configuration used by this configuration.

Dnsmasq-Dienst
..............

 -- Scheme Variable: dnsmasq-service-type
     This is the type of the dnsmasq service, whose value should be an dnsmasq-configuration object as in this example:

          (service dnsmasq-service-type
                   (dnsmasq-configuration
                     (no-resolv? #t)
                     (servers '("192.168.1.1"))))

 -- Datentyp: dnsmasq-configuration
     Repräsentiert die dnsmasq-Konfiguration.

     package (Vorgabe: DNSMASQ)
          Package object of the dnsmasq server.

     no-hosts? (Vorgabe: #f)
          When true, don't read the hostnames in /etc/hosts.

     port (Vorgabe: 53)
          The port to listen on.  Setting this to zero completely disables DNS responses, leaving only DHCP and/or TFTP functions.

     local-service? (Vorgabe: #t)
          Accept DNS queries only from hosts whose address is on a local subnet, ie a subnet for which an interface exists on the server.

     listen-addresses (Vorgabe: '())
          Listen on the given IP addresses.

     resolv-file (Vorgabe: "/etc/resolv.conf")
          The file to read the IP address of the upstream nameservers from.

     no-resolv? (Vorgabe: #f)
          When true, don't read RESOLV-FILE.

     servers (default: '())
          Specify IP address of upstream servers directly.

     cache-size (Vorgabe: 150)
          Set the size of dnsmasq's cache.  Setting the cache size to zero disables caching.

     negative-cache? (Vorgabe: #t)
          When false, disable negative caching.

ddclient-Dienst
...............

The ddclient service described below runs the ddclient daemon, which takes care of automatically updating DNS entries for service providers such as Dyn (https://dyn.com/dns/).

The following example show instantiates the service with its default configuration:

     (service ddclient-service-type)

Note that ddclient needs to access credentials that are stored in a secret file, by default /etc/ddclient/secrets (see secret-file below.)  You are expected to create this file manually, in an ``out-of-band'' fashion (you could make this file part of the service configuration, for instance by using plain-file, but it will be world-readable via /gnu/store.)  See the examples in the share/ddclient directory of the ddclient package.

Available ddclient-configuration fields are:

 -- ddclient-configuration parameter: package ddclient
     Das ddclient-Paket.

 -- ddclient-configuration parameter: integer daemon
     The period after which ddclient will retry to check IP and domain name.

     Defaults to 300.

 -- ddclient-configuration parameter: boolean syslog
     Use syslog for the output.

     Defaults to #t.

 -- ddclient-configuration parameter: string mail
     Mail to user.

     Defaults to "root".

 -- ddclient-configuration parameter: string mail-failure
     Den Nutzer per Mail bei fehlgeschlagenen Aktualisierungen benachrichtigen.

     Defaults to "root".

 -- ddclient-configuration parameter: string pid
     PID-Datei für den ddclient.

     Defaults to "/var/run/ddclient/ddclient.pid".

 -- ddclient-configuration parameter: boolean ssl
     Enable SSL support.

     Defaults to #t.

 -- ddclient-configuration parameter: string user
     Specifies the user name or ID that is used when running ddclient program.

     Defaults to "ddclient".

 -- ddclient-configuration parameter: string group
     Group of the user who will run the ddclient program.

     Defaults to "ddclient".

 -- ddclient-configuration parameter: string secret-file
     Secret file which will be appended to ddclient.conf file.  This file contains credentials for use by ddclient.  You are expected to create it manually.

     Defaults to "/etc/ddclient/secrets.conf".

 -- ddclient-configuration parameter: list extra-options
     Extra options will be appended to ddclient.conf file.

     Defaults to ().

VPN-Dienste
-----------

The (gnu services vpn) module provides services related to virtual private networks (VPNs).  It provides a client service for your machine to connect to a VPN, and a servire service for your machine to host a VPN.  Both services use OpenVPN (https://openvpn.net/).

 -- Scheme Procedure: openvpn-client-service
     [#:config (openvpn-client-configuration)]

     Return a service that runs openvpn, a VPN daemon, as a client.

 -- Scheme Procedure: openvpn-server-service
     [#:config (openvpn-server-configuration)]

     Return a service that runs openvpn, a VPN daemon, as a server.

     Both can be run simultaneously.

Available openvpn-client-configuration fields are:

 -- openvpn-client-configuration parameter: package openvpn
     The OpenVPN package.

 -- openvpn-client-configuration parameter: string pid-file
     The OpenVPN pid file.

     Defaults to "/var/run/openvpn/openvpn.pid".

 -- openvpn-client-configuration parameter: proto proto
     The protocol (UDP or TCP) used to open a channel between clients and servers.

     Defaults to udp.

 -- openvpn-client-configuration parameter: dev dev
     The device type used to represent the VPN connection.

     Defaults to tun.

 -- openvpn-client-configuration parameter: string ca
     The certificate authority to check connections against.

     Defaults to "/etc/openvpn/ca.crt".

 -- openvpn-client-configuration parameter: string cert
     The certificate of the machine the daemon is running on.  It should be signed by the authority given in ca.

     Defaults to "/etc/openvpn/client.crt".

 -- openvpn-client-configuration parameter: string key
     The key of the machine the daemon is running on.  It must be the key whose certificate is cert.

     Defaults to "/etc/openvpn/client.key".

 -- openvpn-client-configuration parameter: boolean comp-lzo?
     Whether to use the lzo compression algorithm.

     Defaults to #t.

 -- openvpn-client-configuration parameter: boolean persist-key?
     Don't re-read key files across SIGUSR1 or --ping-restart.

     Defaults to #t.

 -- openvpn-client-configuration parameter: boolean persist-tun?
     Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or --ping-restart restarts.

     Defaults to #t.

 -- openvpn-client-configuration parameter: number verbosity
     Verbosity level.

     Defaults to 3.

 -- openvpn-client-configuration parameter: tls-auth-client tls-auth
     Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks.

     Defaults to #f.

 -- openvpn-client-configuration parameter: key-usage verify-key-usage?
     Whether to check the server certificate has server usage extension.

     Defaults to #t.

 -- openvpn-client-configuration parameter: bind bind?
     Bind to a specific local port number.

     Defaults to #f.

 -- openvpn-client-configuration parameter: resolv-retry resolv-retry?
     Retry resolving server address.

     Defaults to #t.

 -- openvpn-client-configuration parameter: openvpn-remote-list remote
     A list of remote servers to connect to.

     Defaults to ().

     Available openvpn-remote-configuration fields are:

      -- openvpn-remote-configuration parameter: string name
          Server name.

          Defaults to "my-server".

      -- openvpn-remote-configuration parameter: number port
          Port number the server listens to.

          Defaults to 1194.

Available openvpn-server-configuration fields are:

 -- openvpn-server-configuration parameter: package openvpn
     The OpenVPN package.

 -- openvpn-server-configuration parameter: string pid-file
     The OpenVPN pid file.

     Defaults to "/var/run/openvpn/openvpn.pid".

 -- openvpn-server-configuration parameter: proto proto
     The protocol (UDP or TCP) used to open a channel between clients and servers.

     Defaults to udp.

 -- openvpn-server-configuration parameter: dev dev
     The device type used to represent the VPN connection.

     Defaults to tun.

 -- openvpn-server-configuration parameter: string ca
     The certificate authority to check connections against.

     Defaults to "/etc/openvpn/ca.crt".

 -- openvpn-server-configuration parameter: string cert
     The certificate of the machine the daemon is running on.  It should be signed by the authority given in ca.

     Defaults to "/etc/openvpn/client.crt".

 -- openvpn-server-configuration parameter: string key
     The key of the machine the daemon is running on.  It must be the key whose certificate is cert.

     Defaults to "/etc/openvpn/client.key".

 -- openvpn-server-configuration parameter: boolean comp-lzo?
     Whether to use the lzo compression algorithm.

     Defaults to #t.

 -- openvpn-server-configuration parameter: boolean persist-key?
     Don't re-read key files across SIGUSR1 or --ping-restart.

     Defaults to #t.

 -- openvpn-server-configuration parameter: boolean persist-tun?
     Don't close and reopen TUN/TAP device or run up/down scripts across SIGUSR1 or --ping-restart restarts.

     Defaults to #t.

 -- openvpn-server-configuration parameter: number verbosity
     Verbosity level.

     Defaults to 3.

 -- openvpn-server-configuration parameter: tls-auth-server tls-auth
     Add an additional layer of HMAC authentication on top of the TLS control channel to protect against DoS attacks.

     Defaults to #f.

 -- openvpn-server-configuration parameter: number port
     Specifies the port number on which the server listens.

     Defaults to 1194.

 -- openvpn-server-configuration parameter: ip-mask server
     An ip and mask specifying the subnet inside the virtual network.

     Defaults to "10.8.0.0 255.255.255.0".

 -- openvpn-server-configuration parameter: cidr6 server-ipv6
     A CIDR notation specifying the IPv6 subnet inside the virtual network.

     Defaults to #f.

 -- openvpn-server-configuration parameter: string dh
     The Diffie-Hellman parameters file.

     Defaults to "/etc/openvpn/dh2048.pem".

 -- openvpn-server-configuration parameter: string ifconfig-pool-persist
     The file that records client IPs.

     Defaults to "/etc/openvpn/ipp.txt".

 -- openvpn-server-configuration parameter: gateway redirect-gateway?
     When true, the server will act as a gateway for its clients.

     Defaults to #f.

 -- openvpn-server-configuration parameter: boolean client-to-client?
     When true, clients are allowed to talk to each other inside the VPN.

     Defaults to #f.

 -- openvpn-server-configuration parameter: keepalive keepalive
     Causes ping-like messages to be sent back and forth over the link so that each side knows when the other side has gone down.  keepalive requires a pair.  The first element is the period of the ping sending, and the second element is the timeout before considering the other side down.

 -- openvpn-server-configuration parameter: number max-clients
     The maximum number of clients.

     Defaults to 100.

 -- openvpn-server-configuration parameter: string status
     The status file.  This file shows a small report on current connection.  It is truncated and rewritten every minute.

     Defaults to "/var/run/openvpn/status".

 -- openvpn-server-configuration parameter: openvpn-ccd-list client-config-dir
     The list of configuration for some clients.

     Defaults to ().

     Available openvpn-ccd-configuration fields are:

      -- openvpn-ccd-configuration parameter: string name
          Client name.

          Defaults to "client".

      -- openvpn-ccd-configuration parameter: ip-mask iroute
          Client own network

          Defaults to #f.

      -- openvpn-ccd-configuration parameter: ip-mask ifconfig-push
          Client VPN IP.

          Defaults to #f.

Network File System
-------------------

The (gnu services nfs) module provides the following services, which are most commonly used in relation to mounting or exporting directory trees as network file systems (NFS).

RPC Bind Service
................

The RPC Bind service provides a facility to map program numbers into universal addresses.  Many NFS related services use this facility.  Hence it is automatically started when a dependent service starts.

 -- Scheme Variable: rpcbind-service-type
     A service type for the RPC portmapper daemon.

 -- Data Type: rpcbind-configuration
     Data type representing the configuration of the RPC Bind Service.  This type has the following parameters:

     rpcbind (default: rpcbind)
          The rpcbind package to use.

     warm-start? (default: #t)
          If this parameter is #t, then the daemon will read a state file on startup thus reloading state information saved by a previous instance.

Pipefs Pseudo File System
.........................

The pipefs file system is used to transfer NFS related data between the kernel and user space programs.

 -- Scheme Variable: pipefs-service-type
     A service type for the pipefs pseudo file system.

 -- Data Type: pipefs-configuration
     Data type representing the configuration of the pipefs pseudo file system service.  This type has the following parameters:

     mount-point (default: "/var/lib/nfs/rpc_pipefs")
          The directory to which the file system is to be attached.

GSS Daemon Service
..................

The global security system (GSS) daemon provides strong security for RPC based protocols.  Before exchanging RPC requests an RPC client must establish a security context.  Typically this is done using the Kerberos command kinit or automatically at login time using PAM services (see Kerberos-Dienste).

 -- Scheme Variable: gss-service-type
     A service type for the Global Security System (GSS) daemon.

 -- Data Type: gss-configuration
     Data type representing the configuration of the GSS daemon service.  This type has the following parameters:

     nfs-utils (default: nfs-utils)
          The package in which the rpc.gssd command is to be found.

     pipefs-directory (default: "/var/lib/nfs/rpc_pipefs")
          The directory where the pipefs file system is mounted.

IDMAP Daemon Service
....................

The idmap daemon service provides mapping between user IDs and user names. Typically it is required in order to access file systems mounted via NFSv4.

 -- Scheme Variable: idmap-service-type
     A service type for the Identity Mapper (IDMAP) daemon.

 -- Data Type: idmap-configuration
     Data type representing the configuration of the IDMAP daemon service.  This type has the following parameters:

     nfs-utils (default: nfs-utils)
          The package in which the rpc.idmapd command is to be found.

     pipefs-directory (default: "/var/lib/nfs/rpc_pipefs")
          The directory where the pipefs file system is mounted.

     domain (default: #f)
          The local NFSv4 domain name.  This must be a string or #f.  If it is #f then the daemon will use the host's fully qualified domain name.

Kontinuierliche Integration
---------------------------

Cuirass (https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git) is a continuous integration tool for Guix.  It can be used both for development and for providing substitutes to others (see Substitute).

The (gnu services cuirass) module provides the following service.

 -- Scheme Procedure: cuirass-service-type
     The type of the Cuirass service.  Its value must be a cuirass-configuration object, as described below.

To add build jobs, you have to set the specifications field of the configuration.  Here is an example of a service that polls the Guix repository and builds the packages from a manifest.  Some of the packages are defined in the "custom-packages" input, which is the equivalent of GUIX_PACKAGE_PATH.

     (define %cuirass-specs
       #~(list
          '((#:name . "my-manifest")
            (#:load-path-inputs . ("guix"))
            (#:package-path-inputs . ("custom-packages"))
            (#:proc-input . "guix")
            (#:proc-file . "build-aux/cuirass/gnu-system.scm")
            (#:proc . cuirass-jobs)
            (#:proc-args . ((subset . "manifests")
                            (systems . ("x86_64-linux"))
                            (manifests . (("config" . "guix/manifest.scm")))))
            (#:inputs . (((#:name . "guix")
                          (#:url . "git://git.savannah.gnu.org/guix.git")
                          (#:load-path . ".")
                          (#:branch . "master")
                          (#:no-compile? . #t))
                         ((#:name . "config")
                          (#:url . "git://git.example.org/config.git")
                          (#:load-path . ".")
                          (#:branch . "master")
                          (#:no-compile? . #t))
                         ((#:name . "custom-packages")
                          (#:url . "git://git.example.org/custom-packages.git")
                          (#:load-path . ".")
                          (#:branch . "master")
                          (#:no-compile? . #t)))))))

     (service cuirass-service-type
              (cuirass-configuration
               (specifications %cuirass-specs)))

While information related to build jobs is located directly in the specifications, global settings for the cuirass process are accessible in other cuirass-configuration fields.

 -- Data Type: cuirass-configuration
     Data type representing the configuration of Cuirass.

     log-file (default: "/var/log/cuirass.log")
          Location of the log file.

     cache-directory (default: "/var/cache/cuirass")
          Location of the repository cache.

     user (default: "cuirass")
          Owner of the cuirass process.

     group (default: "cuirass")
          Owner's group of the cuirass process.

     interval (default: 60)
          Number of seconds between the poll of the repositories followed by the Cuirass jobs.

     database (Vorgabe: "/var/lib/cuirass/cuirass.db")
          Location of sqlite database which contains the build results and previously added specifications.

     ttl (Vorgabe: (* 30 24 3600))
          Specifies the time-to-live (TTL) in seconds of garbage collector roots that are registered for build results.  This means that build results are protected from garbage collection for at least TTL seconds.

     port (default: 8081)
          Port number used by the HTTP server.

     --listen=HOST
          Listen on the network interface for HOST.  The default is to accept connections from localhost.

     specifications (default: #~'())
          A gexp (see G-Ausdrücke) that evaluates to a list of specifications, where a specification is an association list (see Associations Lists (GNU Guile Reference Manual)) whose keys are keywords (#:keyword-example) as shown in the example above.

     use-substitutes? (default: #f)
          This allows using substitutes to avoid building every dependencies of a job from source.

     one-shot? (default: #f)
          Only evaluate specifications and build derivations once.

     fallback? (default: #f)
          When substituting a pre-built binary fails, fall back to building packages locally.

     cuirass (default: cuirass)
          The Cuirass package to use.

Dienste zur Stromverbrauchsverwaltung
-------------------------------------

TLP-Daemon
..........

The (gnu services pm) module provides a Guix service definition for the Linux power management tool TLP.

TLP enables various powersaving modes in userspace and kernel.  Contrary to upower-service, it is not a passive, monitoring tool, as it will apply custom settings each time a new power source is detected.  More information can be found at TLP home page (http://linrunner.de/en/tlp/tlp.html).

 -- Scheme Variable: tlp-service-type
     The service type for the TLP tool.  Its value should be a valid TLP configuration (see below).  To use the default settings, simply write:

          (service tlp-service-type)

By default TLP does not need much configuration but most TLP parameters can be tweaked using tlp-configuration.

Each parameter definition is preceded by its type; for example, boolean foo indicates that the foo parameter should be specified as a boolean.  Types starting with maybe- denote parameters that won't show up in TLP config file when their value is 'disabled.

Available tlp-configuration fields are:

 -- tlp-configuration parameter: package tlp
     The TLP package.

 -- tlp-configuration parameter: boolean tlp-enable?
     Set to true if you wish to enable TLP.

     Defaults to #t.

 -- tlp-configuration parameter: string tlp-default-mode
     Default mode when no power supply can be detected.  Alternatives are AC and BAT.

     Defaults to "AC".

 -- tlp-configuration parameter: non-negative-integer disk-idle-secs-on-ac
     Number of seconds Linux kernel has to wait after the disk goes idle, before syncing on AC.

     Defaults to 0.

 -- tlp-configuration parameter: non-negative-integer disk-idle-secs-on-bat
     Same as disk-idle-ac but on BAT mode.

     Defaults to 2.

 -- tlp-configuration parameter: non-negative-integer max-lost-work-secs-on-ac
     Dirty pages flushing periodicity, expressed in seconds.

     Defaults to 15.

 -- tlp-configuration parameter: non-negative-integer max-lost-work-secs-on-bat
     Same as max-lost-work-secs-on-ac but on BAT mode.

     Defaults to 60.

 -- tlp-configuration parameter: maybe-space-separated-string-list cpu-scaling-governor-on-ac
     CPU frequency scaling governor on AC mode.  With intel_pstate driver, alternatives are powersave and performance.  With acpi-cpufreq driver, alternatives are ondemand, powersave, performance and conservative.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-space-separated-string-list cpu-scaling-governor-on-bat
     Same as cpu-scaling-governor-on-ac but on BAT mode.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-non-negative-integer cpu-scaling-min-freq-on-ac
     Set the min available frequency for the scaling governor on AC.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-non-negative-integer cpu-scaling-max-freq-on-ac
     Set the max available frequency for the scaling governor on AC.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-non-negative-integer cpu-scaling-min-freq-on-bat
     Set the min available frequency for the scaling governor on BAT.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-non-negative-integer cpu-scaling-max-freq-on-bat
     Set the max available frequency for the scaling governor on BAT.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-non-negative-integer cpu-min-perf-on-ac
     Limit the min P-state to control the power dissipation of the CPU, in AC mode.  Values are stated as a percentage of the available performance.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-non-negative-integer cpu-max-perf-on-ac
     Limit the max P-state to control the power dissipation of the CPU, in AC mode.  Values are stated as a percentage of the available performance.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-non-negative-integer cpu-min-perf-on-bat
     Same as cpu-min-perf-on-ac on BAT mode.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-non-negative-integer cpu-max-perf-on-bat
     Same as cpu-max-perf-on-ac on BAT mode.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-boolean cpu-boost-on-ac?
     Enable CPU turbo boost feature on AC mode.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-boolean cpu-boost-on-bat?
     Same as cpu-boost-on-ac? on BAT mode.

     Defaults to disabled.

 -- tlp-configuration parameter: boolean sched-powersave-on-ac?
     Allow Linux kernel to minimize the number of CPU cores/hyper-threads used under light load conditions.

     Defaults to #f.

 -- tlp-configuration parameter: boolean sched-powersave-on-bat?
     Same as sched-powersave-on-ac? but on BAT mode.

     Defaults to #t.

 -- tlp-configuration parameter: boolean nmi-watchdog?
     Enable Linux kernel NMI watchdog.

     Defaults to #f.

 -- tlp-configuration parameter: maybe-string phc-controls
     For Linux kernels with PHC patch applied, change CPU voltages.  An example value would be "F:V F:V F:V F:V".

     Defaults to disabled.

 -- tlp-configuration parameter: string energy-perf-policy-on-ac
     Set CPU performance versus energy saving policy on AC.  Alternatives are performance, normal, powersave.

     Defaults to "performance".

 -- tlp-configuration parameter: string energy-perf-policy-on-bat
     Same as energy-perf-policy-ac but on BAT mode.

     Defaults to "powersave".

 -- tlp-configuration parameter: space-separated-string-list disks-devices
     Hard disk devices.

 -- tlp-configuration parameter: space-separated-string-list disk-apm-level-on-ac
     Hard disk advanced power management level.

 -- tlp-configuration parameter: space-separated-string-list disk-apm-level-on-bat
     Same as disk-apm-bat but on BAT mode.

 -- tlp-configuration parameter: maybe-space-separated-string-list disk-spindown-timeout-on-ac
     Hard disk spin down timeout.  One value has to be specified for each declared hard disk.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-space-separated-string-list disk-spindown-timeout-on-bat
     Same as disk-spindown-timeout-on-ac but on BAT mode.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-space-separated-string-list disk-iosched
     Select IO scheduler for disk devices.  One value has to be specified for each declared hard disk.  Example alternatives are cfq, deadline and noop.

     Defaults to disabled.

 -- tlp-configuration parameter: string sata-linkpwr-on-ac
     SATA aggressive link power management (ALPM) level.  Alternatives are min_power, medium_power, max_performance.

     Defaults to "max_performance".

 -- tlp-configuration parameter: string sata-linkpwr-on-bat
     Same as sata-linkpwr-ac but on BAT mode.

     Defaults to "min_power".

 -- tlp-configuration parameter: maybe-string sata-linkpwr-blacklist
     Exclude specified SATA host devices for link power management.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-on-off-boolean ahci-runtime-pm-on-ac?
     Enable Runtime Power Management for AHCI controller and disks on AC mode.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-on-off-boolean ahci-runtime-pm-on-bat?
     Same as ahci-runtime-pm-on-ac on BAT mode.

     Defaults to disabled.

 -- tlp-configuration parameter: non-negative-integer ahci-runtime-pm-timeout
     Seconds of inactivity before disk is suspended.

     Defaults to 15.

 -- tlp-configuration parameter: string pcie-aspm-on-ac
     PCI Express Active State Power Management level.  Alternatives are default, performance, powersave.

     Defaults to "performance".

 -- tlp-configuration parameter: string pcie-aspm-on-bat
     Same as pcie-aspm-ac but on BAT mode.

     Defaults to "powersave".

 -- tlp-configuration parameter: string radeon-power-profile-on-ac
     Radeon graphics clock speed level.  Alternatives are low, mid, high, auto, default.

     Defaults to "high".

 -- tlp-configuration parameter: string radeon-power-profile-on-bat
     Same as radeon-power-ac but on BAT mode.

     Defaults to "low".

 -- tlp-configuration parameter: string radeon-dpm-state-on-ac
     Radeon dynamic power management method (DPM).  Alternatives are battery, performance.

     Defaults to "performance".

 -- tlp-configuration parameter: string radeon-dpm-state-on-bat
     Same as radeon-dpm-state-ac but on BAT mode.

     Defaults to "battery".

 -- tlp-configuration parameter: string radeon-dpm-perf-level-on-ac
     Radeon DPM performance level.  Alternatives are auto, low, high.

     Defaults to "auto".

 -- tlp-configuration parameter: string radeon-dpm-perf-level-on-bat
     Same as radeon-dpm-perf-ac but on BAT mode.

     Defaults to "auto".

 -- tlp-configuration parameter: on-off-boolean wifi-pwr-on-ac?
     Wifi power saving mode.

     Defaults to #f.

 -- tlp-configuration parameter: on-off-boolean wifi-pwr-on-bat?
     Same as wifi-power-ac? but on BAT mode.

     Defaults to #t.

 -- tlp-configuration parameter: y-n-boolean wol-disable?
     Disable wake on LAN.

     Defaults to #t.

 -- tlp-configuration parameter: non-negative-integer sound-power-save-on-ac
     Timeout duration in seconds before activating audio power saving on Intel HDA and AC97 devices.  A value of 0 disables power saving.

     Defaults to 0.

 -- tlp-configuration parameter: non-negative-integer sound-power-save-on-bat
     Same as sound-powersave-ac but on BAT mode.

     Defaults to 1.

 -- tlp-configuration parameter: y-n-boolean sound-power-save-controller?
     Disable controller in powersaving mode on Intel HDA devices.

     Defaults to #t.

 -- tlp-configuration parameter: boolean bay-poweroff-on-bat?
     Enable optical drive in UltraBay/MediaBay on BAT mode.  Drive can be powered on again by releasing (and reinserting) the eject lever or by pressing the disc eject button on newer models.

     Defaults to #f.

 -- tlp-configuration parameter: string bay-device
     Name of the optical drive device to power off.

     Defaults to "sr0".

 -- tlp-configuration parameter: string runtime-pm-on-ac
     Runtime Power Management for PCI(e) bus devices.  Alternatives are on and auto.

     Defaults to "on".

 -- tlp-configuration parameter: string runtime-pm-on-bat
     Same as runtime-pm-ac but on BAT mode.

     Defaults to "auto".

 -- tlp-configuration parameter: boolean runtime-pm-all?
     Runtime Power Management for all PCI(e) bus devices, except blacklisted ones.

     Defaults to #t.

 -- tlp-configuration parameter: maybe-space-separated-string-list runtime-pm-blacklist
     Exclude specified PCI(e) device addresses from Runtime Power Management.

     Defaults to disabled.

 -- tlp-configuration parameter: space-separated-string-list runtime-pm-driver-blacklist
     Exclude PCI(e) devices assigned to the specified drivers from Runtime Power Management.

 -- tlp-configuration parameter: boolean usb-autosuspend?
     Enable USB autosuspend feature.

     Defaults to #t.

 -- tlp-configuration parameter: maybe-string usb-blacklist
     Exclude specified devices from USB autosuspend.

     Defaults to disabled.

 -- tlp-configuration parameter: boolean usb-blacklist-wwan?
     Exclude WWAN devices from USB autosuspend.

     Defaults to #t.

 -- tlp-configuration parameter: maybe-string usb-whitelist
     Include specified devices into USB autosuspend, even if they are already excluded by the driver or via usb-blacklist-wwan?.

     Defaults to disabled.

 -- tlp-configuration parameter: maybe-boolean usb-autosuspend-disable-on-shutdown?
     Enable USB autosuspend before shutdown.

     Defaults to disabled.

 -- tlp-configuration parameter: boolean restore-device-state-on-startup?
     Restore radio device state (bluetooth, wifi, wwan) from previous shutdown on system startup.

     Defaults to #f.

Thermald-Daemon
...............

The (gnu services pm) module provides an interface to thermald, a CPU frequency scaling service which helps prevent overheating.

 -- Scheme Variable: thermald-service-type
     This is the service type for thermald (https://01.org/linux-thermal-daemon/), the Linux Thermal Daemon, which is responsible for controlling the thermal state of processors and preventing overheating.

 -- Data Type: thermald-configuration
     Data type representing the configuration of thermald-service-type.

     ignore-cpuid-check? (default: #f)
          Ignore cpuid check for supported CPU models.

     thermald (default: THERMALD)
          Package object of thermald.

Audio-Dienste
-------------

The (gnu services audio) module provides a service to start MPD (the Music Player Daemon).

Music Player Daemon
...................

The Music Player Daemon (MPD) is a service that can play music while being controlled from the local machine or over the network by a variety of clients.

The following example shows how one might run mpd as user "bob" on port 6666.  It uses pulseaudio for output.

     (service mpd-service-type
              (mpd-configuration
               (user "bob")
               (port "6666")))

 -- Scheme Variable: mpd-service-type
     The service type for mpd

 -- Data Type: mpd-configuration
     Data type representing the configuration of mpd.

     user (default: "mpd")
          The user to run mpd as.

     music-dir (default: "~/Music")
          The directory to scan for music files.

     playlist-dir (default: "~/.mpd/playlists")
          The directory to store playlists.

     port (default: "6600")
          The port to run mpd on.

     address (default: "any")
          The address that mpd will bind to.  To use a Unix domain socket, an absolute path can be specified here.

Virtualization services
-----------------------

The (gnu services virtualization) module provides services for the libvirt and virtlog daemons, as well as other virtualization-related services.

Libvirt daemon
..............

libvirtd is the server side daemon component of the libvirt virtualization management system. This daemon runs on host servers and performs required management tasks for virtualized guests.

 -- Scheme Variable: libvirt-service-type
     This is the type of the libvirt daemon (https://libvirt.org).  Its value must be a libvirt-configuration.

          (service libvirt-service-type
                   (libvirt-configuration
                    (unix-sock-group "libvirt")
                    (tls-port "16555")))

Available libvirt-configuration fields are:

 -- libvirt-configuration parameter: package libvirt
     Libvirt package.

 -- libvirt-configuration parameter: boolean listen-tls?
     Flag listening for secure TLS connections on the public TCP/IP port.  must set listen for this to have any effect.

     It is necessary to setup a CA and issue server certificates before using this capability.

     Defaults to #t.

 -- libvirt-configuration parameter: boolean listen-tcp?
     Listen for unencrypted TCP connections on the public TCP/IP port.  must set listen for this to have any effect.

     Using the TCP socket requires SASL authentication by default.  Only SASL mechanisms which support data encryption are allowed.  This is DIGEST_MD5 and GSSAPI (Kerberos5)

     Defaults to #f.

 -- libvirt-configuration parameter: string tls-port
     Port for accepting secure TLS connections This can be a port number, or service name

     Defaults to "16514".

 -- libvirt-configuration parameter: string tcp-port
     Port for accepting insecure TCP connections This can be a port number, or service name

     Defaults to "16509".

 -- libvirt-configuration parameter: string listen-addr
     IP address or hostname used for client connections.

     Defaults to "0.0.0.0".

 -- libvirt-configuration parameter: boolean mdns-adv?
     Flag toggling mDNS advertisement of the libvirt service.

     Alternatively can disable for all services on a host by stopping the Avahi daemon.

     Defaults to #f.

 -- libvirt-configuration parameter: string mdns-name
     Default mDNS advertisement name.  This must be unique on the immediate broadcast network.

     Defaults to "Virtualization Host <hostname>".

 -- libvirt-configuration parameter: string unix-sock-group
     UNIX domain socket group ownership.  This can be used to allow a 'trusted' set of users access to management capabilities without becoming root.

     Defaults to "root".

 -- libvirt-configuration parameter: string unix-sock-ro-perms
     UNIX socket permissions for the R/O socket.  This is used for monitoring VM status only.

     Defaults to "0777".

 -- libvirt-configuration parameter: string unix-sock-rw-perms
     UNIX socket permissions for the R/W socket.  Default allows only root.  If PolicyKit is enabled on the socket, the default will change to allow everyone (eg, 0777)

     Defaults to "0770".

 -- libvirt-configuration parameter: string unix-sock-admin-perms
     UNIX socket permissions for the admin socket.  Default allows only owner (root), do not change it unless you are sure to whom you are exposing the access to.

     Defaults to "0777".

 -- libvirt-configuration parameter: string unix-sock-dir
     The directory in which sockets will be found/created.

     Defaults to "/var/run/libvirt".

 -- libvirt-configuration parameter: string auth-unix-ro
     Authentication scheme for UNIX read-only sockets.  By default socket permissions allow anyone to connect

     Defaults to "polkit".

 -- libvirt-configuration parameter: string auth-unix-rw
     Authentication scheme for UNIX read-write sockets.  By default socket permissions only allow root.  If PolicyKit support was compiled into libvirt, the default will be to use 'polkit' auth.

     Defaults to "polkit".

 -- libvirt-configuration parameter: string auth-tcp
     Authentication scheme for TCP sockets.  If you don't enable SASL, then all TCP traffic is cleartext.  Don't do this outside of a dev/test scenario.

     Defaults to "sasl".

 -- libvirt-configuration parameter: string auth-tls
     Authentication scheme for TLS sockets.  TLS sockets already have encryption provided by the TLS layer, and limited authentication is done by certificates.

     It is possible to make use of any SASL authentication mechanism as well, by using 'sasl' for this option

     Defaults to "none".

 -- libvirt-configuration parameter: optional-list access-drivers
     API access control scheme.

     By default an authenticated user is allowed access to all APIs.  Access drivers can place restrictions on this.

     Defaults to ().

 -- libvirt-configuration parameter: string key-file
     Server key file path.  If set to an empty string, then no private key is loaded.

     Defaults to "".

 -- libvirt-configuration parameter: string cert-file
     Server key file path.  If set to an empty string, then no certificate is loaded.

     Defaults to "".

 -- libvirt-configuration parameter: string ca-file
     Server key file path.  If set to an empty string, then no CA certificate is loaded.

     Defaults to "".

 -- libvirt-configuration parameter: string crl-file
     Certificate revocation list path.  If set to an empty string, then no CRL is loaded.

     Defaults to "".

 -- libvirt-configuration parameter: boolean tls-no-sanity-cert
     Disable verification of our own server certificates.

     When libvirtd starts it performs some sanity checks against its own certificates.

     Defaults to #f.

 -- libvirt-configuration parameter: boolean tls-no-verify-cert
     Disable verification of client certificates.

     Client certificate verification is the primary authentication mechanism. Any client which does not present a certificate signed by the CA will be rejected.

     Defaults to #f.

 -- libvirt-configuration parameter: optional-list tls-allowed-dn-list
     Whitelist of allowed x509 Distinguished Name.

     Defaults to ().

 -- libvirt-configuration parameter: optional-list sasl-allowed-usernames
     Whitelist of allowed SASL usernames.  The format for username depends on the SASL authentication mechanism.

     Defaults to ().

 -- libvirt-configuration parameter: string tls-priority
     Override the compile time default TLS priority string.  The default is usually "NORMAL" unless overridden at build time.  Only set this is it is desired for libvirt to deviate from the global default settings.

     Defaults to "NORMAL".

 -- libvirt-configuration parameter: integer max-clients
     Maximum number of concurrent client connections to allow over all sockets combined.

     Defaults to 5000.

 -- libvirt-configuration parameter: integer max-queued-clients
     Maximum length of queue of connections waiting to be accepted by the daemon.  Note, that some protocols supporting retransmission may obey this so that a later reattempt at connection succeeds.

     Defaults to 1000.

 -- libvirt-configuration parameter: integer max-anonymous-clients
     Maximum length of queue of accepted but not yet authenticated clients.  Set this to zero to turn this feature off

     Defaults to 20.

 -- libvirt-configuration parameter: integer min-workers
     Number of workers to start up initially.

     Defaults to 5.

 -- libvirt-configuration parameter: integer max-workers
     Maximum number of worker threads.

     If the number of active clients exceeds min-workers, then more threads are spawned, up to max_workers limit.  Typically you'd want max_workers to equal maximum number of clients allowed.

     Defaults to 20.

 -- libvirt-configuration parameter: integer prio-workers
     Number of priority workers.  If all workers from above pool are stuck, some calls marked as high priority (notably domainDestroy) can be executed in this pool.

     Defaults to 5.

 -- libvirt-configuration parameter: integer max-requests
     Total global limit on concurrent RPC calls.

     Defaults to 20.

 -- libvirt-configuration parameter: integer max-client-requests
     Limit on concurrent requests from a single client connection.  To avoid one client monopolizing the server this should be a small fraction of the global max_requests and max_workers parameter.

     Defaults to 5.

 -- libvirt-configuration parameter: integer admin-min-workers
     Same as min-workers but for the admin interface.

     Defaults to 1.

 -- libvirt-configuration parameter: integer admin-max-workers
     Same as max-workers but for the admin interface.

     Defaults to 5.

 -- libvirt-configuration parameter: integer admin-max-clients
     Same as max-clients but for the admin interface.

     Defaults to 5.

 -- libvirt-configuration parameter: integer admin-max-queued-clients
     Same as max-queued-clients but for the admin interface.

     Defaults to 5.

 -- libvirt-configuration parameter: integer admin-max-client-requests
     Same as max-client-requests but for the admin interface.

     Defaults to 5.

 -- libvirt-configuration parameter: integer log-level
     Logging level.  4 errors, 3 warnings, 2 information, 1 debug.

     Defaults to 3.

 -- libvirt-configuration parameter: string log-filters
     Logging filters.

     A filter allows to select a different logging level for a given category of logs The format for a filter is one of:

       * x:name

       * x:+name

     where name is a string which is matched against the category given in the VIR_LOG_INIT() at the top of each libvirt source file, e.g., "remote", "qemu", or "util.json" (the name in the filter can be a substring of the full category name, in order to match multiple similar categories), the optional "+" prefix tells libvirt to log stack trace for each message matching name, and x is the minimal level where matching messages should be logged:

       * 1: DEBUG

       * 2: INFO

       * 3: WARNING

       * 4: ERROR

     Multiple filters can be defined in a single filters statement, they just need to be separated by spaces.

     Defaults to "3:remote 4:event".

 -- libvirt-configuration parameter: string log-outputs
     Logging outputs.

     An output is one of the places to save logging information The format for an output can be:

     x:stderr
          output goes to stderr

     x:syslog:name
          use syslog for the output and use the given name as the ident

     x:file:file_path
          output to a file, with the given filepath

     x:journald
          output to journald logging system

     In all case the x prefix is the minimal level, acting as a filter

       * 1: DEBUG

       * 2: INFO

       * 3: WARNING

       * 4: ERROR

     Multiple outputs can be defined, they just need to be separated by spaces.

     Defaults to "3:stderr".

 -- libvirt-configuration parameter: integer audit-level
     Allows usage of the auditing subsystem to be altered

       * 0: disable all auditing

       * 1: enable auditing, only if enabled on host

       * 2: enable auditing, and exit if disabled on host.

     Defaults to 1.

 -- libvirt-configuration parameter: boolean audit-logging
     Send audit messages via libvirt logging infrastructure.

     Defaults to #f.

 -- libvirt-configuration parameter: optional-string host-uuid
     Host UUID.  UUID must not have all digits be the same.

     Defaults to "".

 -- libvirt-configuration parameter: string host-uuid-source
     Source to read host UUID.

       * smbios: fetch the UUID from dmidecode -s system-uuid

       * machine-id: fetch the UUID from /etc/machine-id

     If dmidecode does not provide a valid UUID a temporary UUID will be generated.

     Defaults to "smbios".

 -- libvirt-configuration parameter: integer keepalive-interval
     A keepalive message is sent to a client after keepalive_interval seconds of inactivity to check if the client is still responding.  If set to -1, libvirtd will never send keepalive requests; however clients can still send them and the daemon will send responses.

     Defaults to 5.

 -- libvirt-configuration parameter: integer keepalive-count
     Maximum number of keepalive messages that are allowed to be sent to the client without getting any response before the connection is considered broken.

     In other words, the connection is automatically closed approximately after keepalive_interval * (keepalive_count + 1) seconds since the last message received from the client.  When keepalive-count is set to 0, connections will be automatically closed after keepalive-interval seconds of inactivity without sending any keepalive messages.

     Defaults to 5.

 -- libvirt-configuration parameter: integer admin-keepalive-interval
     Same as above but for admin interface.

     Defaults to 5.

 -- libvirt-configuration parameter: integer admin-keepalive-count
     Same as above but for admin interface.

     Defaults to 5.

 -- libvirt-configuration parameter: integer ovs-timeout
     Timeout for Open vSwitch calls.

     The ovs-vsctl utility is used for the configuration and its timeout option is set by default to 5 seconds to avoid potential infinite waits blocking libvirt.

     Defaults to 5.

Virtlog daemon
..............

The virtlogd service is a server side daemon component of libvirt that is used to manage logs from virtual machine consoles.

This daemon is not used directly by libvirt client applications, rather it is called on their behalf by libvirtd. By maintaining the logs in a standalone daemon, the main libvirtd daemon can be restarted without risk of losing logs. The virtlogd daemon has the ability to re-exec() itself upon receiving SIGUSR1, to allow live upgrades without downtime.

 -- Scheme Variable: virtlog-service-type
     This is the type of the virtlog daemon.  Its value must be a virtlog-configuration.

          (service virtlog-service-type
                   (virtlog-configuration
                    (max-clients 1000)))

 -- virtlog-configuration parameter: integer log-level
     Logging level.  4 errors, 3 warnings, 2 information, 1 debug.

     Defaults to 3.

 -- virtlog-configuration parameter: string log-filters
     Logging filters.

     A filter allows to select a different logging level for a given category of logs The format for a filter is one of:

       * x:name

       * x:+name

     where name is a string which is matched against the category given in the VIR_LOG_INIT() at the top of each libvirt source file, e.g., "remote", "qemu", or "util.json" (the name in the filter can be a substring of the full category name, in order to match multiple similar categories), the optional "+" prefix tells libvirt to log stack trace for each message matching name, and x is the minimal level where matching messages should be logged:

       * 1: DEBUG

       * 2: INFO

       * 3: WARNING

       * 4: ERROR

     Multiple filters can be defined in a single filters statement, they just need to be separated by spaces.

     Defaults to "3:remote 4:event".

 -- virtlog-configuration parameter: string log-outputs
     Logging outputs.

     An output is one of the places to save logging information The format for an output can be:

     x:stderr
          output goes to stderr

     x:syslog:name
          use syslog for the output and use the given name as the ident

     x:file:file_path
          output to a file, with the given filepath

     x:journald
          output to journald logging system

     In all case the x prefix is the minimal level, acting as a filter

       * 1: DEBUG

       * 2: INFO

       * 3: WARNING

       * 4: ERROR

     Multiple outputs can be defined, they just need to be separated by spaces.

     Defaults to "3:stderr".

 -- virtlog-configuration parameter: integer max-clients
     Maximum number of concurrent client connections to allow over all sockets combined.

     Defaults to 1024.

 -- virtlog-configuration parameter: integer max-size
     Maximum file size before rolling over.

     Defaults to 2MB

 -- virtlog-configuration parameter: integer max-backups
     Maximum number of backup files to keep.

     Defaults to 3

Transparent Emulation with QEMU
...............................

qemu-binfmt-service-type provides support for transparent emulation of program binaries built for different architectures---e.g., it allows you to transparently execute an ARMv7 program on an x86_64 machine.  It achieves this by combining the QEMU (https://www.qemu.org) emulator and the binfmt_misc feature of the kernel Linux.

 -- Scheme Variable: qemu-binfmt-service-type
     This is the type of the QEMU/binfmt service for transparent emulation.  Its value must be a qemu-binfmt-configuration object, which specifies the QEMU package to use as well as the architecture we want to emulated:

          (service qemu-binfmt-service-type
                   (qemu-binfmt-configuration
                     (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc"))))

     In this example, we enable transparent emulation for the ARM and aarch64 platforms.  Running herd stop qemu-binfmt turns it off, and running herd start qemu-binfmt turns it back on (see the herd command (The GNU Shepherd Manual)).

 -- Data Type: qemu-binfmt-configuration
     This is the configuration for the qemu-binfmt service.

     platforms (default: '())
          The list of emulated QEMU platforms.  Each item must be a platform object as returned by lookup-qemu-platforms (see below).

     guix-support? (default: #f)
          When it is true, QEMU and all its dependencies are added to the build environment of guix-daemon (see --chroot-directory option).  This allows the binfmt_misc handlers to be used within the build environment, which in turn means that you can transparently build programs for another architecture.

          For example, let's suppose you're on an x86_64 machine and you have this service:

               (service qemu-binfmt-service-type
                        (qemu-binfmt-configuration
                          (platforms (lookup-qemu-platforms "arm"))
                          (guix-support? #t)))

          You can run:

               guix build -s armhf-linux inkscape

          and it will build Inkscape for ARMv7 as if it were a native build, transparently using QEMU to emulate the ARMv7 CPU.  Pretty handy if you'd like to test a package build for an architecture you don't have access to!

     qemu (default: qemu)
          The QEMU package to use.

 -- Scheme Procedure: lookup-qemu-platforms PLATFORMS...
     Return the list of QEMU platform objects corresponding to PLATFORMS....  PLATFORMS must be a list of strings corresponding to platform names, such as "arm", "sparc", "mips64el", and so on.

 -- Scheme Procedure: qemu-platform? OBJ
     Return true if OBJ is a platform object.

 -- Scheme Procedure: qemu-platform-name PLATFORM
     Return the name of PLATFORM---a string such as "arm".

Versionskontrolldienste
-----------------------

The (gnu services version-control) module provides a service to allow remote access to local Git repositories.  There are three options: the git-daemon-service, which provides access to repositories via the git:// unsecured TCP-based protocol, extending the nginx web server to proxy some requests to git-http-backend, or providing a web interface with cgit-service-type.

 -- Scheme Procedure: git-daemon-service [#:config (git-daemon-configuration)]

     Return a service that runs git daemon, a simple TCP server to expose repositories over the Git protocol for anonymous access.

     The optional CONFIG argument should be a <git-daemon-configuration> object, by default it allows read-only access to exported (By creating the magic file "git-daemon-export-ok" in the repository directory.) repositories under /srv/git.

 -- Data Type: git-daemon-configuration
     Data type representing the configuration for git-daemon-service.

     package (default: GIT)
          Package object of the Git distributed version control system.

     export-all? (default: #F)
          Whether to allow access for all Git repositories, even if they do not have the git-daemon-export-ok file.

     base-path (default: /srv/git)
          Whether to remap all the path requests as relative to the given path.  If you run git daemon with (BASE-PATH "/SRV/GIT") on example.com, then if you later try to pull git://example.com/hello.git, git daemon will interpret the path as /srv/git/hello.git.

     user-path (default: #F)
          Whether to allow ~user notation to be used in requests.  When specified with empty string, requests to git://host/~alice/foo is taken as a request to access foo repository in the home directory of user alice.  If (USER-PATH "PATH") is specified, the same request is taken as a request to access path/foo repository in the home directory of user alice.

     listen (default: '())
          Whether to listen on specific IP addresses or hostnames, defaults to all.

     port (default: #F)
          Whether to listen on an alternative port, which defaults to 9418.

     whitelist (default: '())
          If not empty, only allow access to this list of directories.

     extra-options (default: '())
          Extra options will be passed to git daemon, please run man git-daemon for more information.

The git:// protocol lacks authentication.  When you pull from a repository fetched via git://, you don't know that the data you receive was modified is really coming from the specified host, and you have your connection is subject to eavesdropping.  It's better to use an authenticated and encrypted transport, such as https.  Although Git allows you to serve repositories using unsophisticated file-based web servers, there is a faster protocol implemented by the git-http-backend program.  This program is the back-end of a proper Git web service.  It is designed to sit behind a FastCGI proxy.  See Web-Dienste, for more on running the necessary fcgiwrap daemon.

Guix has a separate configuration data type for serving Git repositories over HTTP.

 -- Data Type: git-http-configuration
     Data type representing the configuration for git-http-service.

     package (default: GIT)
          Package object of the Git distributed version control system.

     git-root (default: /srv/git)
          Directory containing the Git repositories to expose to the world.

     export-all? (default: #F)
          Whether to expose access for all Git repositories in GIT-ROOT, even if they do not have the git-daemon-export-ok file.

     uri-path (default: /git/)
          Path prefix for Git access.  With the default /git/ prefix, this will map http://SERVER/git/REPO.git to /srv/git/REPO.git.  Requests whose URI paths do not begin with this prefix are not passed on to this Git instance.

     fcgiwrap-socket (default: 127.0.0.1:9000)
          The socket on which the fcgiwrap daemon is listening.  See Web-Dienste.

There is no git-http-service-type, currently; instead you can create an nginx-location-configuration from a git-http-configuration and then add that location to a web server.

 -- Scheme Procedure: git-http-nginx-location-configuration
     [config=(git-http-configuration)] Compute an
     nginx-location-configuration that corresponds to the given Git http configuration.  An example nginx service definition to serve the default /srv/git over HTTPS might be:

          (service nginx-service-type
                   (nginx-configuration
                    (server-blocks
                     (list
                      (nginx-server-configuration
                       (listen '("443 ssl"))
                       (server-name "git.my-host.org")
                       (ssl-certificate
                        "/etc/letsencrypt/live/git.my-host.org/fullchain.pem")
                       (ssl-certificate-key
                        "/etc/letsencrypt/live/git.my-host.org/privkey.pem")
                       (locations
                        (list
                         (git-http-nginx-location-configuration
                          (git-http-configuration (uri-path "/"))))))))))

     This example assumes that you are using Let's Encrypt to get your TLS certificate.  See Zertifikatsdienste.  The default certbot service will redirect all HTTP traffic on git.my-host.org to HTTPS. You will also need to add an fcgiwrap proxy to your system services. See Web-Dienste.

Cgit Service
............

Cgit (https://git.zx2c4.com/cgit/) is a web frontend for Git repositories written in C.

The following example will configure the service with default values.  By default, Cgit can be accessed on port 80 (http://localhost:80).

     (service cgit-service-type)

The file-object type designates either a file-like object (see file-like objects) or a string.

Available cgit-configuration fields are:

 -- cgit-configuration parameter: package package
     The CGIT package.

 -- cgit-configuration parameter: nginx-server-configuration-list nginx
     NGINX configuration.

 -- cgit-configuration parameter: file-object about-filter
     Specifies a command which will be invoked to format the content of about pages (both top-level and for each repository).

     Defaults to "".

 -- cgit-configuration parameter: string agefile
     Specifies a path, relative to each repository path, which can be used to specify the date and time of the youngest commit in the repository.

     Defaults to "".

 -- cgit-configuration parameter: file-object auth-filter
     Specifies a command that will be invoked for authenticating repository access.

     Defaults to "".

 -- cgit-configuration parameter: string branch-sort
     Flag which, when set to age, enables date ordering in the branch ref list, and when set name enables ordering by branch name.

     Defaults to "name".

 -- cgit-configuration parameter: string cache-root
     Path used to store the cgit cache entries.

     Defaults to "/var/cache/cgit".

 -- cgit-configuration parameter: integer cache-static-ttl
     Number which specifies the time-to-live, in minutes, for the cached version of repository pages accessed with a fixed SHA1.

     Defaults to -1.

 -- cgit-configuration parameter: integer cache-dynamic-ttl
     Number which specifies the time-to-live, in minutes, for the cached version of repository pages accessed without a fixed SHA1.

     Defaults to 5.

 -- cgit-configuration parameter: integer cache-repo-ttl
     Number which specifies the time-to-live, in minutes, for the cached version of the repository summary page.

     Defaults to 5.

 -- cgit-configuration parameter: integer cache-root-ttl
     Number which specifies the time-to-live, in minutes, for the cached version of the repository index page.

     Defaults to 5.

 -- cgit-configuration parameter: integer cache-scanrc-ttl
     Number which specifies the time-to-live, in minutes, for the result of scanning a path for Git repositories.

     Defaults to 15.

 -- cgit-configuration parameter: integer cache-about-ttl
     Number which specifies the time-to-live, in minutes, for the cached version of the repository about page.

     Defaults to 15.

 -- cgit-configuration parameter: integer cache-snapshot-ttl
     Number which specifies the time-to-live, in minutes, for the cached version of snapshots.

     Defaults to 5.

 -- cgit-configuration parameter: integer cache-size
     The maximum number of entries in the cgit cache.  When set to 0, caching is disabled.

     Defaults to 0.

 -- cgit-configuration parameter: boolean case-sensitive-sort?
     Sort items in the repo list case sensitively.

     Defaults to #t.

 -- cgit-configuration parameter: list clone-prefix
     List of common prefixes which, when combined with a repository URL, generates valid clone URLs for the repository.

     Defaults to ().

 -- cgit-configuration parameter: list clone-url
     List of clone-url templates.

     Defaults to ().

 -- cgit-configuration parameter: file-object commit-filter
     Command which will be invoked to format commit messages.

     Defaults to "".

 -- cgit-configuration parameter: string commit-sort
     Flag which, when set to date, enables strict date ordering in the commit log, and when set to topo enables strict topological ordering.

     Defaults to "git log".

 -- cgit-configuration parameter: file-object css
     URL which specifies the css document to include in all cgit pages.

     Defaults to "/share/cgit/cgit.css".

 -- cgit-configuration parameter: file-object email-filter
     Specifies a command which will be invoked to format names and email address of committers, authors, and taggers, as represented in various places throughout the cgit interface.

     Defaults to "".

 -- cgit-configuration parameter: boolean embedded?
     Flag which, when set to #t, will make cgit generate a HTML fragment suitable for embedding in other HTML pages.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-commit-graph?
     Flag which, when set to #t, will make cgit print an ASCII-art commit history graph to the left of the commit messages in the repository log page.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-filter-overrides?
     Flag which, when set to #t, allows all filter settings to be overridden in repository-specific cgitrc files.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-follow-links?
     Flag which, when set to #t, allows users to follow a file in the log view.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-http-clone?
     If set to #t, cgit will act as an dumb HTTP endpoint for Git clones.

     Defaults to #t.

 -- cgit-configuration parameter: boolean enable-index-links?
     Flag which, when set to #t, will make cgit generate extra links "summary", "commit", "tree" for each repo in the repository index.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-index-owner?
     Flag which, when set to #t, will make cgit display the owner of each repo in the repository index.

     Defaults to #t.

 -- cgit-configuration parameter: boolean enable-log-filecount?
     Flag which, when set to #t, will make cgit print the number of modified files for each commit on the repository log page.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-log-linecount?
     Flag which, when set to #t, will make cgit print the number of added and removed lines for each commit on the repository log page.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-remote-branches?
     Flag which, when set to #t, will make cgit display remote branches in the summary and refs views.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-subject-links?
     Flag which, when set to 1, will make cgit use the subject of the parent commit as link text when generating links to parent commits in commit view.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-html-serving?
     Flag which, when set to #t, will make cgit use the subject of the parent commit as link text when generating links to parent commits in commit view.

     Defaults to #f.

 -- cgit-configuration parameter: boolean enable-tree-linenumbers?
     Flag which, when set to #t, will make cgit generate linenumber links for plaintext blobs printed in the tree view.

     Defaults to #t.

 -- cgit-configuration parameter: boolean enable-git-config?
     Flag which, when set to #f, will allow cgit to use Git config to set any repo specific settings.

     Defaults to #f.

 -- cgit-configuration parameter: file-object favicon
     URL used as link to a shortcut icon for cgit.

     Defaults to "/favicon.ico".

 -- cgit-configuration parameter: string footer
     The content of the file specified with this option will be included verbatim at the bottom of all pages (i.e. it replaces the standard "generated by..." message).

     Defaults to "".

 -- cgit-configuration parameter: string head-include
     The content of the file specified with this option will be included verbatim in the HTML HEAD section on all pages.

     Defaults to "".

 -- cgit-configuration parameter: string header
     The content of the file specified with this option will be included verbatim at the top of all pages.

     Defaults to "".

 -- cgit-configuration parameter: file-object include
     Name of a configfile to include before the rest of the current config- file is parsed.

     Defaults to "".

 -- cgit-configuration parameter: string index-header
     The content of the file specified with this option will be included verbatim above the repository index.

     Defaults to "".

 -- cgit-configuration parameter: string index-info
     The content of the file specified with this option will be included verbatim below the heading on the repository index page.

     Defaults to "".

 -- cgit-configuration parameter: boolean local-time?
     Flag which, if set to #t, makes cgit print commit and tag times in the servers timezone.

     Defaults to #f.

 -- cgit-configuration parameter: file-object logo
     URL which specifies the source of an image which will be used as a logo on all cgit pages.

     Defaults to "/share/cgit/cgit.png".

 -- cgit-configuration parameter: string logo-link
     URL loaded when clicking on the cgit logo image.

     Defaults to "".

 -- cgit-configuration parameter: file-object owner-filter
     Command which will be invoked to format the Owner column of the main page.

     Defaults to "".

 -- cgit-configuration parameter: integer max-atom-items
     Number of items to display in atom feeds view.

     Defaults to 10.

 -- cgit-configuration parameter: integer max-commit-count
     Number of entries to list per page in "log" view.

     Defaults to 50.

 -- cgit-configuration parameter: integer max-message-length
     Number of commit message characters to display in "log" view.

     Defaults to 80.

 -- cgit-configuration parameter: integer max-repo-count
     Specifies the number of entries to list per page on the repository index page.

     Defaults to 50.

 -- cgit-configuration parameter: integer max-repodesc-length
     Specifies the maximum number of repo description characters to display on the repository index page.

     Defaults to 80.

 -- cgit-configuration parameter: integer max-blob-size
     Specifies the maximum size of a blob to display HTML for in KBytes.

     Defaults to 0.

 -- cgit-configuration parameter: string max-stats
     Maximum statistics period.  Valid values are week,month, quarter and year.

     Defaults to "".

 -- cgit-configuration parameter: mimetype-alist mimetype
     Mimetype for the specified filename extension.

     Defaults to ((gif "image/gif") (html "text/html") (jpg "image/jpeg") (jpeg "image/jpeg") (pdf "application/pdf") (png "image/png") (svg "image/svg+xml")).

 -- cgit-configuration parameter: file-object mimetype-file
     Specifies the file to use for automatic mimetype lookup.

     Defaults to "".

 -- cgit-configuration parameter: string module-link
     Text which will be used as the formatstring for a hyperlink when a submodule is printed in a directory listing.

     Defaults to "".

 -- cgit-configuration parameter: boolean nocache?
     If set to the value #t caching will be disabled.

     Defaults to #f.

 -- cgit-configuration parameter: boolean noplainemail?
     If set to #t showing full author email addresses will be disabled.

     Defaults to #f.

 -- cgit-configuration parameter: boolean noheader?
     Flag which, when set to #t, will make cgit omit the standard header on all pages.

     Defaults to #f.

 -- cgit-configuration parameter: project-list project-list
     A list of subdirectories inside of repository-directory, relative to it, that should loaded as Git repositories.  An empty list means that all subdirectories will be loaded.

     Defaults to ().

 -- cgit-configuration parameter: file-object readme
     Text which will be used as default value for cgit-repo-readme.

     Defaults to "".

 -- cgit-configuration parameter: boolean remove-suffix?
     If set to #t and repository-directory is enabled, if any repositories are found with a suffix of .git, this suffix will be removed for the URL and name.

     Defaults to #f.

 -- cgit-configuration parameter: integer renamelimit
     Maximum number of files to consider when detecting renames.

     Defaults to -1.

 -- cgit-configuration parameter: string repository-sort
     The way in which repositories in each section are sorted.

     Defaults to "".

 -- cgit-configuration parameter: robots-list robots
     Text used as content for the robots meta-tag.

     Defaults to ("noindex" "nofollow").

 -- cgit-configuration parameter: string root-desc
     Text printed below the heading on the repository index page.

     Defaults to "a fast webinterface for the git dscm".

 -- cgit-configuration parameter: string root-readme
     The content of the file specified with this option will be included verbatim below thef "about" link on the repository index page.

     Defaults to "".

 -- cgit-configuration parameter: string root-title
     Text printed as heading on the repository index page.

     Defaults to "".

 -- cgit-configuration parameter: boolean scan-hidden-path
     If set to #t and repository-directory is enabled, repository-directory will recurse into directories whose name starts with a period.  Otherwise, repository-directory will stay away from such directories, considered as "hidden".  Note that this does not apply to the ".git" directory in non-bare repos.

     Defaults to #f.

 -- cgit-configuration parameter: list snapshots
     Text which specifies the default set of snapshot formats that cgit generates links for.

     Defaults to ().

 -- cgit-configuration parameter: repository-directory repository-directory
     Name of the directory to scan for repositories (represents scan-path).

     Defaults to "/srv/git".

 -- cgit-configuration parameter: string section
     The name of the current repository section - all repositories defined after this option will inherit the current section name.

     Defaults to "".

 -- cgit-configuration parameter: string section-sort
     Flag which, when set to 1, will sort the sections on the repository listing by name.

     Defaults to "".

 -- cgit-configuration parameter: integer section-from-path
     A number which, if defined prior to repository-directory, specifies how many path elements from each repo path to use as a default section name.

     Defaults to 0.

 -- cgit-configuration parameter: boolean side-by-side-diffs?
     If set to #t shows side-by-side diffs instead of unidiffs per default.

     Defaults to #f.

 -- cgit-configuration parameter: file-object source-filter
     Specifies a command which will be invoked to format plaintext blobs in the tree view.

     Defaults to "".

 -- cgit-configuration parameter: integer summary-branches
     Specifies the number of branches to display in the repository "summary" view.

     Defaults to 10.

 -- cgit-configuration parameter: integer summary-log
     Specifies the number of log entries to display in the repository "summary" view.

     Defaults to 10.

 -- cgit-configuration parameter: integer summary-tags
     Specifies the number of tags to display in the repository "summary" view.

     Defaults to 10.

 -- cgit-configuration parameter: string strict-export
     Filename which, if specified, needs to be present within the repository for cgit to allow access to that repository.

     Defaults to "".

 -- cgit-configuration parameter: string virtual-root
     URL which, if specified, will be used as root for all cgit links.

     Defaults to "/".

 -- cgit-configuration parameter: repository-cgit-configuration-list repositories
     A list of cgit-repo records to use with config.

     Defaults to ().

     Available repository-cgit-configuration fields are:

      -- repository-cgit-configuration parameter: repo-list snapshots
          A mask of snapshot formats for this repo that cgit generates links for, restricted by the global snapshots setting.

          Defaults to ().

      -- repository-cgit-configuration parameter: repo-file-object source-filter
          Override the default source-filter.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string url
          The relative URL used to access the repository.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-file-object about-filter
          Override the default about-filter.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string branch-sort
          Flag which, when set to age, enables date ordering in the branch ref list, and when set to name enables ordering by branch name.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-list clone-url
          A list of URLs which can be used to clone repo.

          Defaults to ().

      -- repository-cgit-configuration parameter: repo-file-object commit-filter
          Override the default commit-filter.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string commit-sort
          Flag which, when set to date, enables strict date ordering in the commit log, and when set to topo enables strict topological ordering.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string defbranch
          The name of the default branch for this repository.  If no such branch exists in the repository, the first branch name (when sorted) is used as default instead.  By default branch pointed to by HEAD, or "master" if there is no suitable HEAD.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string desc
          The value to show as repository description.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string homepage
          The value to show as repository homepage.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-file-object email-filter
          Override the default email-filter.

          Defaults to "".

      -- repository-cgit-configuration parameter: maybe-repo-boolean enable-commit-graph?
          A flag which can be used to disable the global setting enable-commit-graph?.

          Defaults to disabled.

      -- repository-cgit-configuration parameter: maybe-repo-boolean enable-log-filecount?
          A flag which can be used to disable the global setting enable-log-filecount?.

          Defaults to disabled.

      -- repository-cgit-configuration parameter: maybe-repo-boolean enable-log-linecount?
          A flag which can be used to disable the global setting enable-log-linecount?.

          Defaults to disabled.

      -- repository-cgit-configuration parameter: maybe-repo-boolean enable-remote-branches?
          Flag which, when set to #t, will make cgit display remote branches in the summary and refs views.

          Defaults to disabled.

      -- repository-cgit-configuration parameter: maybe-repo-boolean enable-subject-links?
          A flag which can be used to override the global setting enable-subject-links?.

          Defaults to disabled.

      -- repository-cgit-configuration parameter: maybe-repo-boolean enable-html-serving?
          A flag which can be used to override the global setting enable-html-serving?.

          Defaults to disabled.

      -- repository-cgit-configuration parameter: repo-boolean hide?
          Flag which, when set to #t, hides the repository from the repository index.

          Defaults to #f.

      -- repository-cgit-configuration parameter: repo-boolean ignore?
          Flag which, when set to #t, ignores the repository.

          Defaults to #f.

      -- repository-cgit-configuration parameter: repo-file-object logo
          URL which specifies the source of an image which will be used as a logo on this repo’s pages.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string logo-link
          URL loaded when clicking on the cgit logo image.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-file-object owner-filter
          Override the default owner-filter.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string module-link
          Text which will be used as the formatstring for a hyperlink when a submodule is printed in a directory listing.  The arguments for the formatstring are the path and SHA1 of the submodule commit.

          Defaults to "".

      -- repository-cgit-configuration parameter: module-link-path module-link-path
          Text which will be used as the formatstring for a hyperlink when a submodule with the specified subdirectory path is printed in a directory listing.

          Defaults to ().

      -- repository-cgit-configuration parameter: repo-string max-stats
          Override the default maximum statistics period.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string name
          The value to show as repository name.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string owner
          A value used to identify the owner of the repository.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string path
          An absolute path to the repository directory.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string readme
          A path (relative to repo) which specifies a file to include verbatim as the "About" page for this repo.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-string section
          The name of the current repository section - all repositories defined after this option will inherit the current section name.

          Defaults to "".

      -- repository-cgit-configuration parameter: repo-list extra-options
          Extra options will be appended to cgitrc file.

          Defaults to ().

 -- cgit-configuration parameter: list extra-options
     Extra options will be appended to cgitrc file.

     Defaults to ().

However, it could be that you just want to get a cgitrc up and running.  In that case, you can pass an opaque-cgit-configuration as a record to cgit-service-type.  As its name indicates, an opaque configuration does not have easy reflective capabilities.

Available opaque-cgit-configuration fields are:

 -- opaque-cgit-configuration parameter: package cgit
     The cgit package.

 -- opaque-cgit-configuration parameter: string string
     The contents of the cgitrc, as a string.

For example, if your cgitrc is just the empty string, you could instantiate a cgit service like this:

     (service cgit-service-type
              (opaque-cgit-configuration
               (cgitrc "")))

Gitolite-Dienst
...............

Gitolite (http://gitolite.com/gitolite/) is a tool for hosting Git repositories on a central server.

Gitolite can handle multiple repositories and users, and supports flexible configuration of the permissions for the users on the repositories.

The following example will configure Gitolite using the default git user, and the provided SSH public key.

     (service gitolite-service-type
              (gitolite-configuration
                (admin-pubkey (plain-file
                                "yourname.pub"
                                "ssh-rsa AAAA... guix@example.com"))))

Gitolite is configured through a special admin repository which you can clone, for example, if you setup Gitolite on example.com, you would run the following command to clone the admin repository.

     git clone git@example.com:gitolite-admin

When the Gitolite service is activated, the provided admin-pubkey will be inserted in to the keydir directory in the gitolite-admin repository.  If this results in a change in the repository, it will be committed using the message ``gitolite setup by GNU Guix''.

 -- Datentyp: gitolite-configuration
     Repräsentiert die Konfiguration vom gitolite-service-type.

     package (Vorgabe: GITOLITE)
          Welches Gitolite-Paket benutzt werden soll.

     user (Vorgabe: GIT)
          User to use for Gitolite.  This will be user that you use when accessing Gitolite over SSH.

     group (Vorgabe: GIT)
          Group to use for Gitolite.

     home-directory (Vorgabe: "/VAR/LIB/GITOLITE")
          Directory in which to store the Gitolite configuration and repositories.

     rc-file (Vorgabe: (GITOLITE-RC-FILE))
          A ``file-like'' object (see file-like objects), representing the configuration for Gitolite.

     admin-pubkey (Vorgabe: #F)
          A ``file-like'' object (see file-like objects) used to setup Gitolite.  This will be inserted in to the keydir directory within the gitolite-admin repository.

          To specify the SSH key as a string, use the plain-file function.

               (plain-file "yourname.pub" "ssh-rsa AAAA... guix@example.com")

 -- Datentyp: gitolite-rc-file
     Repräsentiert die Gitolie-RC-Datei.

     umask (Vorgabe: #o0077)
          This controls the permissions Gitolite sets on the repositories and their contents.

          A value like #o0027 will give read access to the group used by Gitolite (by default: git). This is necessary when using Gitolite with software like cgit or gitweb.

     git-config-keys (Vorgabe: "")
          Gitolite allows you to set git config values using the "config" keyword. This setting allows control over the config keys to accept.

     roles (Vorgabe: '(("READERS" . 1) ("WRITERS" . )))
          Set the role names allowed to be used by users running the perms command.

     enable (default: '("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb"))
          This setting controls the commands and features to enable within Gitolite.

Spieldienste
------------

The Battle for Wesnoth Service
..............................

The Battle for Wesnoth (https://wesnoth.org) is a fantasy, turn based tactical strategy game, with several single player campaigns, and multiplayer games (both networked and local).

 -- Variable: Scheme Variable wesnothd-service-type
     Service type for the wesnothd service.  Its value must be a wesnothd-configuration object.  To run wesnothd in the default configuration, instantiate it as:

          (service wesnothd-service-type)

 -- Data Type: wesnothd-configuration
     Data type representing the configuration of wesnothd.

     package (default: wesnoth-server)
          The wesnoth server package to use.

     port (default: 15000)
          The port to bind the server to.

Verschiedene Dienste
--------------------

Fingerabdrucklese-Dienst
........................

The (gnu services fingerprint) module provides a DBus service to read and identify fingerprints via a fingerprint sensor.

 -- Scheme Variable: fprintd-service-type
     The service type for fprintd, which provides the fingerprint reading capability.

          (service fprintd-service-type)

System Control Service
......................

The (gnu services sysctl) provides a service to configure kernel parameters at boot.

 -- Scheme Variable: sysctl-service-type
     The service type for sysctl, which modifies kernel parameters under /proc/sys/.  To enable IPv4 forwarding, it can be instantiated as:

          (service sysctl-service-type
                   (sysctl-configuration
                     (settings '(("net.ipv4.ip_forward" . "1")))))

 -- Data Type: sysctl-configuration
     The data type representing the configuration of sysctl.

     sysctl (default: (file-append procps "/sbin/sysctl")
          The sysctl executable to use.

     settings (default: '())
          An association list specifies kernel parameters and their values.

PC/SC Smart Card Daemon Service
...............................

The (gnu services security-token) module provides the following service to run pcscd, the PC/SC Smart Card Daemon. pcscd is the daemon program for pcsc-lite and the MuscleCard framework. It is a resource manager that coordinates communications with smart card readers, smart cards and cryptographic tokens that are connected to the system.

 -- Scheme Variable: pcscd-service-type
     Service type for the pcscd service.  Its value must be a pcscd-configuration object.  To run pcscd in the default configuration, instantiate it as:

          (service pcscd-service-type)

 -- Datentyp: pcscd-configuration
     Repräsentiert die Konfiguration von pcscd.

     pcsc-lite (Vorgabe: pcsc-lite)
          The pcsc-lite package that provides pcscd.

     usb-drivers (Vorgabe: (list ccid))
          List of packages that provide USB drivers to pcscd. Drivers are expected to be under pcsc/drivers in the store directory of the package.

Lirc Service
............

The (gnu services lirc) module provides the following service.

 -- Scheme Procedure: lirc-service [#:lirc lirc]
     [#:device #f] [#:driver #f] [#:config-file #f]  [#:extra-options '()]
     Return a service that runs LIRC (http://www.lirc.org), a daemon that decodes infrared signals from remote controls.

     Optionally, DEVICE, DRIVER and CONFIG-FILE (configuration file name) may be specified.  See lircd manual for details.

     Finally, EXTRA-OPTIONS is a list of additional command-line options passed to lircd.

Spice Service
.............

The (gnu services spice) module provides the following service.

 -- Scheme Procedure: spice-vdagent-service [#:spice-vdagent]
     Returns a service that runs VDAGENT (http://www.spice-space.org), a daemon that enables sharing the clipboard with a vm and setting the guest display resolution when the graphical console window resizes.

Dictionary Services
-------------------

The (gnu services dict) module provides the following service:

 -- Scheme Procedure: dicod-service [#:config (dicod-configuration)]
     Return a service that runs the dicod daemon, an implementation of DICT server (see Dicod (GNU Dico Manual)).

     The optional CONFIG argument specifies the configuration for dicod, which should be a <dicod-configuration> object, by default it serves the GNU Collaborative International Dictonary of English.

     You can add open localhost to your ~/.dico file to make localhost the default server for dico client (see Initialization File (GNU Dico Manual)).

 -- Data Type: dicod-configuration
     Data type representing the configuration of dicod.

     dico (default: DICO)
          Package object of the GNU Dico dictionary server.

     interfaces (default: '("LOCALHOST"))
          This is the list of IP addresses and ports and possibly socket file names to listen to (see listen directive (GNU Dico Manual)).

     handlers (default: '())
          List of <dicod-handler> objects denoting handlers (module instances).

     databases (default: (LIST %DICOD-DATABASE:GCIDE))
          List of <dicod-database> objects denoting dictionaries to be served.

 -- Data Type: dicod-handler
     Data type representing a dictionary handler (module instance).

     name
          Name of the handler (module instance).

     module (default: #F)
          Name of the dicod module of the handler (instance).  If it is #f, the module has the same name as the handler.  (see Module (GNU Dico Manual)).

     options
          List of strings or gexps representing the arguments for the module handler

 -- Data Type: dicod-database
     Data type representing a dictionary database.

     name
          Name of the database, will be used in DICT commands.

     handler
          Name of the dicod handler (module instance) used by this database (see Handlers (GNU Dico Manual)).

     complex? (default: #F)
          Whether the database configuration complex.  The complex configuration will need a corresponding <dicod-handler> object, otherwise not.

     options
          List of strings or gexps representing the arguments for the database (see Databases (GNU Dico Manual)).

 -- Scheme Variable: %dicod-database:gcide
     A <dicod-database> object serving the GNU Collaborative International Dictionary of English using the gcide package.

The following is an example dicod-service configuration.

     (dicod-service #:config
       (dicod-configuration
        (handlers (list (dicod-handler
                         (name "wordnet")
                         (module "dictorg")
                         (options
                          (list #~(string-append "dbdir=" #$wordnet))))))
        (databases (list (dicod-database
                          (name "wordnet")
                          (complex? #t)
                          (handler "wordnet")
                          (options '("database=wn")))
                         %dicod-database:gcide))))

Docker Service
..............

The (gnu services docker) module provides the following service.

 -- Scheme Variable: docker-service-type

     This is the type of the service that runs Docker (http://www.docker.com), a daemon that can execute application bundles (sometimes referred to as ``containers'') in isolated environments.

 -- Data Type: docker-configuration
     This is the data type representing the configuration of Docker and Containerd.

     package (default: docker)
          The Docker package to use.

     containerd (default: CONTAINERD)
          The Containerd package to use.

Setuid-Programme
================

Some programs need to run with ``root'' privileges, even when they are launched by unprivileged users.  A notorious example is the passwd program, which users can run to change their password, and which needs to access the /etc/passwd and /etc/shadow files---something normally restricted to root, for obvious security reasons.  To address that, these executables are setuid-root, meaning that they always run with root privileges (see How Change Persona (The GNU C Library Reference Manual), for more info about the setuid mechanism.)

The store itself cannot contain setuid programs: that would be a security issue since any user on the system can write derivations that populate the store (see Der Store).  Thus, a different mechanism is used: instead of changing the setuid bit directly on files that are in the store, we let the system administrator declare which programs should be setuid root.

The setuid-programs field of an operating-system declaration contains a list of G-expressions denoting the names of programs to be setuid-root (see Das Konfigurationssystem nutzen).  For instance, the passwd program, which is part of the Shadow package, can be designated by this G-expression (see G-Ausdrücke):

     #~(string-append #$shadow "/bin/passwd")

A default set of setuid programs is defined by the %setuid-programs variable of the (gnu system) module.

 -- Scheme Variable: %setuid-programs
     A list of G-expressions denoting common programs that are setuid-root.

     The list includes commands such as passwd, ping, su, and sudo.

Under the hood, the actual setuid programs are created in the /run/setuid-programs directory at system activation time.  The files in this directory refer to the ``real'' binaries, which are in the store.

X.509-Zertifikate
=================

Über HTTPS verfügbare Webserver (also HTTP mit gesicherter Transportschicht, englisch »Transport-Layer Security«, kurz TLS) senden Client-Programmen ein X.509-Zertifikat, mit dem der Client den Server dann authentifizieren kann. Dazu verifiziert der Client, dass das Zertifikat des Servers von einer sogenannten Zertifizierungsstelle signiert wurde (englisch Certificate Authority, kurz CA). Damit er aber die Signatur der Zertifizierungsstelle verifizieren kann, muss jeder Client das Zertifikat der Zertifizierungsstelle besitzen.

Web-Browser wie GNU IceCat liefern ihre eigenen CA-Zertifikate mit, damit sie von Haus aus Zertifikate verifizieren können.

Den meisten anderen Programmen, die HTTPS sprechen können — wget, git, w3m etc. — muss allerdings erst mitgeteilt werden, wo die CA-Zertifikate installiert sind.

In Guix, this is done by adding a package that provides certificates to the packages field of the operating-system declaration (see »operating-system«-Referenz).  Guix includes one such package, nss-certs, which is a set of CA certificates provided as part of Mozilla's Network Security Services.

Beachten Sie, dass es nicht zu den %BASE-PACKAGES gehört, Sie es also ausdrücklich hinzufügen müssen. Das Verzeichnis /etc/ssl/certs, wo die meisten Anwendungen und Bibliotheken ihren Voreinstellungen entsprechend nach Zertifikaten suchen, verweist auf die global installierten Zertifikate.

Unprivilegierte Benutzer, wie die, die Guix auf einer Fremddistribution benutzen, können sich auch lokal ihre eigenen Pakete mit Zertifikaten in ihr Profil installieren. Eine Reihe von Umgebungsvariablen muss dazu definiert werden, damit Anwendungen und Bibliotheken wissen, wo diese Zertifikate zu finden sind. Und zwar folgt die OpenSSL-Bibliothek den Umgebungsvariablen SSL_CERT_DIR und SSL_CERT_FILE, manche Anwendungen benutzen stattdessen aber ihre eigenen Umgebungsvariablen. Das Versionskontrollsystem Git liest den Ort zum Beispiel aus der Umgebungsvariablen GIT_SSL_CAINFO aus. Sie würden typischerweise also so etwas ausführen:

     $ guix package -i nss-certs
     $ export SSL_CERT_DIR="$HOME/.guix-profile/etc/ssl/certs"
     $ export SSL_CERT_FILE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"
     $ export GIT_SSL_CAINFO="$SSL_CERT_FILE"

Ein weiteres Beispiel ist R, was voraussetzt, dass die Umgebungsvariable CURL_CA_BUNDLE auf ein Zertifikatsbündel verweist, weshalb Sie etwas wie hier ausführen müssten:

     $ guix package -i nss-certs
     $ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt"

Für andere Anwendungen möchten Sie die Namen der benötigten Umgebungsvariablen vielleicht in deren Dokumentation nachschlagen.

Name Service Switch
===================

The (gnu system nss) module provides bindings to the configuration file of the libc name service switch or NSS (see NSS Configuration File (The GNU C Library Reference Manual)).  In a nutshell, the NSS is a mechanism that allows libc to be extended with new ``name'' lookup methods for system databases, which includes host names, service names, user accounts, and more (see System Databases and Name Service Switch (The GNU C Library Reference Manual)).

The NSS configuration specifies, for each system database, which lookup method is to be used, and how the various methods are chained together---for instance, under which circumstances NSS should try the next method in the list.  The NSS configuration is given in the name-service-switch field of operating-system declarations (see name-service-switch).

As an example, the declaration below configures the NSS to use the nss-mdns back-end (http://0pointer.de/lennart/projects/nss-mdns/), which supports host name lookups over multicast DNS (mDNS)  for host names ending in .local:

     (name-service-switch
        (hosts (list %files    ;first, check /etc/hosts

                     ;; If the above did not succeed, try
                     ;; with 'mdns_minimal'.
                     (name-service
                       (name "mdns_minimal")

                       ;; 'mdns_minimal' is authoritative for
                       ;; '.local'.  When it returns "not found",
                       ;; no need to try the next methods.
                       (reaction (lookup-specification
                                  (not-found => return))))

                     ;; Then fall back to DNS.
                     (name-service
                       (name "dns"))

                     ;; Finally, try with the "full" 'mdns'.
                     (name-service
                       (name "mdns")))))

Do not worry: the %mdns-host-lookup-nss variable (see below) contains this configuration, so you will not have to type it if all you want is to have .local host lookup working.

Note that, in this case, in addition to setting the name-service-switch of the operating-system declaration, you also need to use avahi-service-type (see avahi-service-type), or %DESKTOP-SERVICES, which includes it (see Desktop-Dienste).  Doing this makes nss-mdns accessible to the name service cache daemon (see nscd-service).

For convenience, the following variables provide typical NSS configurations.

 -- Scheme Variable: %default-nss
     This is the default name service switch configuration, a name-service-switch object.

 -- Scheme Variable: %mdns-host-lookup-nss
     This is the name service switch configuration with support for host name lookup over multicast DNS (mDNS) for host names ending in .local.

The reference for name service switch configuration is given below.  It is a direct mapping of the configuration file format of the C library , so please refer to the C library manual for more information (see NSS Configuration File (The GNU C Library Reference Manual)).  Compared to the configuration file format of libc NSS, it has the advantage not only of adding this warm parenthetic feel that we like, but also static checks: you will know about syntax errors and typos as soon as you run guix system.

 -- Data Type: name-service-switch

     This is the data type representation the configuration of libc's name service switch (NSS).  Each field below represents one of the supported system databases.

     aliases
     ethers
     group
     gshadow
     hosts
     initgroups
     netgroup
     networks
     password
     public-key
     rpc
     services
     shadow
          The system databases handled by the NSS.  Each of these fields must be a list of <name-service> objects (see below).

 -- Data Type: name-service

     This is the data type representing an actual name service and the associated lookup action.

     name
          A string denoting the name service (see Services in the NSS configuration (The GNU C Library Reference Manual)).

          Note that name services listed here must be visible to nscd.  This is achieved by passing the #:name-services argument to nscd-service the list of packages providing the needed name services (see nscd-service).

     reaction
          An action specified using the lookup-specification macro (see Actions in the NSS configuration (The GNU C Library Reference Manual)).  For example:

               (lookup-specification (unavailable => continue)
                                     (success => return))

Initiale RAM-Disk
=================

For bootstrapping purposes, the Linux-Libre kernel is passed an initial RAM disk, or initrd.  An initrd contains a temporary root file system as well as an initialization script.  The latter is responsible for mounting the real root file system, and for loading any kernel modules that may be needed to achieve that.

The initrd-modules field of an operating-system declaration allows you to specify Linux-libre kernel modules that must be available in the initrd.  In particular, this is where you would list modules needed to actually drive the hard disk where your root partition is---although the default value of initrd-modules should cover most use cases.  For example, assuming you need the megaraid_sas module in addition to the default modules to be able to access your root file system, you would write:

     (operating-system
       ;; ...
       (initrd-modules (cons "megaraid_sas" %base-initrd-modules)))

 -- Scheme Variable: %base-initrd-modules
     This is the list of kernel modules included in the initrd by default.

Furthermore, if you need lower-level customization, the initrd field of an operating-system declaration allows you to specify which initrd you would like to use.  The (gnu system linux-initrd) module provides three ways to build an initrd: the high-level base-initrd procedure and the low-level raw-initrd and expression->initrd procedures.

The base-initrd procedure is intended to cover most common uses.  For example, if you want to add a bunch of kernel modules to be loaded at boot time, you can define the initrd field of the operating system declaration like this:

     (initrd (lambda (file-systems . rest)
               ;; Create a standard initrd but set up networking
               ;; with the parameters QEMU expects by default.
               (apply base-initrd file-systems
                      #:qemu-networking? #t
                      rest)))

The base-initrd procedure also handles common use cases that involves using the system as a QEMU guest, or as a ``live'' system with volatile root file system.

The base-initrd procedure is built from raw-initrd procedure. Unlike base-initrd, raw-initrd doesn't do anything high-level, such as trying to guess which kernel modules and packages should be included to the initrd. An example use of raw-initrd is when a user has a custom Linux kernel configuration and default kernel modules included by base-initrd are not available.

The initial RAM disk produced by base-initrd or raw-initrd honors several options passed on the Linux kernel command line (that is, arguments passed via the linux command of GRUB, or the -append option of QEMU), notably:

--load=BOOT
     Tell the initial RAM disk to load BOOT, a file containing a Scheme program, once it has mounted the root file system.

     Guix uses this option to yield control to a boot program that runs the service activation programs and then spawns the GNU Shepherd, the initialization system.

--root=ROOT
     Mount ROOT as the root file system.  ROOT can be a device name like /dev/sda1, a file system label, or a file system UUID.

--system=SYSTEM
     Have /run/booted-system and /run/current-system point to SYSTEM.

modprobe.blacklist=MODULES...
     Instruct the initial RAM disk as well as the modprobe command (from the kmod package) to refuse to load MODULES.  MODULES must be a comma-separated list of module names---e.g., usbkbd,9pnet.

--repl
     Start a read-eval-print loop (REPL) from the initial RAM disk before it tries to load kernel modules and to mount the root file system.  Our marketing team calls it boot-to-Guile.  The Schemer in you will love it.  See Using Guile Interactively (GNU Guile Reference Manual), for more information on Guile's REPL.

Now that you know all the features that initial RAM disks produced by base-initrd and raw-initrd provide, here is how to use it and customize it further.

 -- Scheme Procedure: raw-initrd FILE-SYSTEMS
     [#:linux-modules '()] [#:mapped-devices '()]  [#:helper-packages '()]
     [#:qemu-networking? #f] [#:volatile-root? #f] Return a derivation that builds a raw initrd.  FILE-SYSTEMS is a list of file systems to be mounted by the initrd, possibly in addition to the root file system specified on the kernel command line via --root.  LINUX-MODULES is a list of kernel modules to be loaded at boot time.  MAPPED-DEVICES is a list of device mappings to realize before FILE-SYSTEMS are mounted (see Zugeordnete Geräte).  HELPER-PACKAGES is a list of packages to be copied in the initrd. It may include e2fsck/static or other packages needed by the initrd to check the root file system.

     When QEMU-NETWORKING? is true, set up networking with the standard QEMU parameters.  When VIRTIO? is true, load additional modules so that the initrd can be used as a QEMU guest with para-virtualized I/O drivers.

     When VOLATILE-ROOT? is true, the root file system is writable but any changes to it are lost.

 -- Scheme Procedure: base-initrd FILE-SYSTEMS
     [#:mapped-devices '()] [#:qemu-networking? #f] [#:volatile-root? #f]
     [#:linux-modules '()] Return as a file-like object a generic initrd, with
     kernel modules taken from LINUX.  FILE-SYSTEMS is a list of file-systems to be mounted by the initrd, possibly in addition to the root file system specified on the kernel command line via --root. MAPPED-DEVICES is a list of device mappings to realize before FILE-SYSTEMS are mounted.

     QEMU-NETWORKING? and VOLATILE-ROOT? behaves as in raw-initrd.

     The initrd is automatically populated with all the kernel modules necessary for FILE-SYSTEMS and for the given options.  Additional kernel modules can be listed in LINUX-MODULES.  They will be added to the initrd, and loaded at boot time in the order in which they appear.

Needless to say, the initrds we produce and use embed a statically-linked Guile, and the initialization program is a Guile program.  That gives a lot of flexibility.  The expression->initrd procedure builds such an initrd, given the program to run in that initrd.

 -- Scheme Procedure: expression->initrd EXP
     [#:guile %guile-static-stripped] [#:name "guile-initrd"] Return as a
     file-like object a Linux initrd (a gzipped cpio archive)  containing GUILE and that evaluates EXP, a G-expression, upon booting.  All the derivations referenced by EXP are automatically copied to the initrd.

Bootloader-Konfiguration
========================

The operating system supports multiple bootloaders.  The bootloader is configured using bootloader-configuration declaration.  All the fields of this structure are bootloader agnostic except for one field, bootloader that indicates the bootloader to be configured and installed.

Some of the bootloaders do not honor every field of bootloader-configuration.  For instance, the extlinux bootloader does not support themes and thus ignores the theme field.

 -- Data Type: bootloader-configuration
     The type of a bootloader configuration declaration.

     bootloader
          The bootloader to use, as a bootloader object. For now grub-bootloader, grub-efi-bootloader, extlinux-bootloader and u-boot-bootloader are supported.

          grub-efi-bootloader allows to boot on modern systems using the Unified Extensible Firmware Interface (UEFI).  This is what you should use if the installation image contains a /sys/firmware/efi directory when you boot it on your system.

          grub-bootloader allows you to boot in particular Intel-based machines in ``legacy'' BIOS mode.

          Available bootloaders are described in (gnu bootloader ...) modules.  In particular, (gnu bootloader u-boot) contains definitions of bootloaders for a wide range of ARM and AArch64 systems, using the U-Boot bootloader (http://www.denx.de/wiki/U-Boot/).

     target
          This is a string denoting the target onto which to install the bootloader.

          The interpretation depends on the bootloader in question.  For grub-bootloader, for example, it should be a device name understood by the bootloader installer command, such as /dev/sda or (hd0) (see Invoking grub-install (GNU GRUB Manual)).  For grub-efi-bootloader, it should be the mount point of the EFI file system, usually /boot/efi.

     menu-entries (default: ())
          A possibly empty list of menu-entry objects (see below), denoting entries to appear in the bootloader menu, in addition to the current system entry and the entry pointing to previous system generations.

     default-entry (default: 0)
          The index of the default boot menu entry.  Index 0 is for the entry of the current system.

     timeout (default: 5)
          The number of seconds to wait for keyboard input before booting.  Set to 0 to boot immediately, and to -1 to wait indefinitely.

     theme (default: #F)
          The bootloader theme object describing the theme to use.  If no theme is provided, some bootloaders might use a default theme, that's true for GRUB.

     terminal-outputs (default: 'gfxterm)
          The output terminals used for the bootloader boot menu, as a list of symbols.  GRUB accepts the values: console, serial, serial_{0-3}, gfxterm, vga_text, mda_text, morse, and pkmodem.  This field corresponds to the GRUB variable GRUB_TERMINAL_OUTPUT (see Simple configuration (GNU GRUB manual)).

     terminal-inputs (default: '())
          The input terminals used for the bootloader boot menu, as a list of symbols.  For GRUB, the default is the native platform terminal as determined at run-time.  GRUB accepts the values: console, serial, serial_{0-3}, at_keyboard, and usb_keyboard.  This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT (see Simple configuration (GNU GRUB manual)).

     serial-unit (default: #f)
          The serial unit used by the bootloader, as an integer from 0 to 3.  For GRUB, it is chosen at run-time; currently GRUB chooses 0, which corresponds to COM1 (see Serial terminal (GNU GRUB manual)).

     serial-speed (default: #f)
          The speed of the serial interface, as an integer.  For GRUB, the default value is chosen at run-time; currently GRUB chooses 9600 bps (see Serial terminal (GNU GRUB manual)).

Should you want to list additional boot menu entries via the menu-entries field above, you will need to create them with the menu-entry form.  For example, imagine you want to be able to boot another distro (hard to imagine!), you can define a menu entry along these lines:

     (menu-entry
       (label "The Other Distro")
       (linux "/boot/old/vmlinux-2.6.32")
       (linux-arguments '("root=/dev/sda2"))
       (initrd "/boot/old/initrd"))

Details below.

 -- Data Type: menu-entry
     The type of an entry in the bootloader menu.

     label
          The label to show in the menu---e.g., "GNU".

     linux
          The Linux kernel image to boot, for example:

               (file-append linux-libre "/bzImage")

          For GRUB, it is also possible to specify a device explicitly in the file path using GRUB's device naming convention (see Naming convention (GNU GRUB manual)), for example:

               "(hd0,msdos1)/boot/vmlinuz"

          If the device is specified explicitly as above, then the device field is ignored entirely.

     linux-arguments (default: ())
          The list of extra Linux kernel command-line arguments---e.g., ("console=ttyS0").

     initrd
          A G-Expression or string denoting the file name of the initial RAM disk to use (see G-Ausdrücke).

     device (default: #f)
          The device where the kernel and initrd are to be found---i.e., for GRUB, root for this menu entry (see root (GNU GRUB manual)).

          This may be a file system label (a string), a file system UUID (a bytevector, see Dateisysteme), or #f, in which case the bootloader will search the device containing the file specified by the linux field (see search (GNU GRUB manual)).  It must not be an OS device name such as /dev/sda1.

Fow now only GRUB has theme support. GRUB themes are created using the grub-theme form, which is not documented yet.

 -- Scheme Variable: %default-theme
     This is the default GRUB theme used by the operating system if no theme field is specified in bootloader-configuration record.

     It comes with a fancy background image displaying the GNU and Guix logos.

guix system aufrufen
====================

Sobald Sie eine Betriebssystemdeklaration geschrieben haben, wie wir sie in den vorangehenden Abschnitten gesehen haben, kann diese instanziiert werden, indem Sie den Befehl guix system aufrufen. Zusammengefasst:

     guix system OPTIONEN... AKTION DATEI

DATEI muss der Name einer Datei sein, in der eine Betriebssystemdeklaration als operating-system-Objekt steht. AKTION gibt an, wie das Betriebssystem instanziiert wird. Derzeit werden folgende Werte dafür unterstützt:

search
     Verfügbare Diensttypendefinitionen anzeigen, die zum angegebenen regulären Ausdruck passen, sortiert nach Relevanz:

          $ guix system search console font
          name: console-fonts
          location: gnu/services/base.scm:729:2
          extends: shepherd-root
          description: Install the given fonts on the specified ttys (fonts are
          + per virtual console on GNU/Linux).  The value of this service is a list
          + of tty/font pairs like:
          +
          +      '(("tty1" . "LatGrkCyr-8x16"))
          relevance: 20

          name: mingetty
          location: gnu/services/base.scm:1048:2
          extends: shepherd-root
          description: Provide console login using the `mingetty' program.
          relevance: 2

          name: login
          location: gnu/services/base.scm:775:2
          extends: pam
          description: Provide a console log-in service as specified by its
          + configuration value, a `login-configuration' object.
          relevance: 2

          ...

     Wie auch bei guix package --search wird das Ergebnis im recutils-Format geliefert, so dass es leicht ist, die Ausgabe zu filtern (see GNU recutils databases (GNU recutils manual)).

reconfigure
     Build the operating system described in FILE, activate it, and switch to it (This action (and the related actions switch-generation and roll-back) are usable only on systems already running Guix System.).

     This effects all the configuration specified in FILE: user accounts, system services, global package list, setuid programs, etc.  The command starts system services specified in FILE that are not currently running; if a service is currently running this command will arrange for it to be upgraded the next time it is stopped (e.g. by herd stop X or herd restart X).

     Dieser Befehl erzeugt eine neue Generation, deren Nummer (wie guix system list-generations sie anzeigt) um eins größer als die der aktuellen Generation ist. Wenn die so nummerierte Generation bereits existiert, wird sie überschrieben. Dieses Verhalten entspricht dem von guix package (see Aufruf von guix package).

     Des Weiteren wird für den Bootloader ein Menüeintrag für die neue Betriebssystemkonfiguration hinzugefügt, außer die Befehlszeilenoption --no-bootloader wurde übergeben. Bei GRUB werden Einträge für ältere Konfigurationen in ein Untermenü verschoben, so dass Sie auch eine ältere Systemgeneration beim Booten noch hochfahren können, falls es notwendig wird.

          Es ist sehr zu empfehlen, guix pull einmal auszuführen, bevor Sie guix system reconfigure zum ersten Mal aufrufen (see Aufruf von guix pull). Wenn Sie das nicht tun, könnten Sie nach dem Abschluss von reconfigure eine ältere Version von Guix vorfinden, als Sie vorher hatten.

switch-generation
     Zu einer bestehenden Systemgeneration wechseln. Diese Aktion wechselt das Systemprofil atomar auf die angegebene Systemgeneration. Hiermit werden auch die bestehenden Menüeinträge des Bootloaders umgeordnet. Der Menüeintrag für die angegebene Systemgeneration wird voreingestellt und die Einträge der anderen Generationen werden in ein Untermenü verschoben, sofern der verwendete Bootloader dies unterstützt. Das nächste Mal, wenn das System gestartet wird, wird die hier angegebene Systemgeneration hochgefahren.

     Der Bootloader selbst wird durch diesen Befehl nicht neu installiert. Es wird also lediglich der bereits installierte Bootloader mit einer neuen Konfigurationsdatei benutzt werden.

     Die Zielgeneration kann ausdrücklich über ihre Generationsnummer angegeben werden. Zum Beispiel würde folgender Aufruf einen Wechsel zur Systemgeneration 7 bewirken:

          guix system switch-generation 7

     Die Zielgeneration kann auch relativ zur aktuellen Generation angegeben werden, in der Form +N oder -N, wobei +3 zum Beispiel »3 Generationen weiter als die aktuelle Generation« bedeuten würde und -1 »1 Generation vor der aktuellen Generation« hieße. Wenn Sie einen negativen Wert wie -1 angeben, müssen Sie -- der Befehlszeilenoption voranstellen, damit die negative Zahl nicht selbst als Befehlszeilenoption aufgefasst wird. Zum Beispiel:

          guix system switch-generation -- -1

     Zur Zeit bewirkt ein Aufruf dieser Aktion nur einen Wechsel des Systemprofils auf eine bereits existierende Generation und ein Umordnen der Bootloader-Menüeinträge. Um die Ziel-Systemgeneration aber tatsächlich zu benutzen, müssen Sie Ihr System neu hochfahren, nachdem Sie diese Aktion ausgeführt haben. In einer zukünftigen Version von Guix wird diese Aktion einmal dieselben Dinge tun, wie reconfigure, also etwa Dienste aktivieren und deaktivieren.

     Diese Aktion schlägt fehl, wenn die angegebene Generation nicht existiert.

roll-back
     Zur vorhergehenden Systemgeneration wechseln. Wenn das System das nächste Mal hochgefahren wird, wird es die vorhergehende Systemgeneration benutzen. Dies ist die Umkehrung von reconfigure und tut genau dasselbe, wie switch-generation mit dem Argument -1 aufzurufen.

     Wie auch bei switch-generation müssen Sie derzeit, nachdem Sie diese Aktion aufgerufen haben, Ihr System neu starten, um die vorhergehende Systemgeneration auch tatsächlich zu benutzen.

delete-generations
     Delete system generations, making them candidates for garbage collection (see Aufruf von guix gc, for information on how to run the ``garbage collector'').

     This works in the same way as guix package --delete-generations (see --delete-generations).  With no arguments, all system generations but the current one are deleted:

          guix system delete-generations

     You can also select the generations you want to delete.  The example below deletes all the system generations that are more than two month old:

          guix system delete-generations 2m

     Running this command automatically reinstalls the bootloader with an updated list of menu entries---e.g., the ``old generations'' sub-menu in GRUB no longer lists the generations that have been deleted.

build
     Die Ableitung des Betriebssystems erstellen, einschließlich aller Konfigurationsdateien und Programme, die zum Booten und Starten benötigt werden. Diese Aktion installiert jedoch nichts davon.

init
     Populate the given directory with all the files necessary to run the operating system specified in FILE.  This is useful for first-time installations of Guix System.  For instance:

          guix system init my-os-config.scm /mnt

     Hiermit werden alle Store-Objekte nach /mnt kopiert, die von der in my-os-config.scm angegebenen Konfiguration vorausgesetzt werden. Dazu gehören Konfigurationsdateien, Pakete und so weiter. Auch andere essenzielle Dateien, die auf dem System vorhanden sein müssen, damit es richtig funktioniert, werden erzeugt — z.B. die Verzeichnisse /etc, /var und /run und die Datei /bin/sh.

     Dieser Befehl installiert auch den Bootloader auf dem in my-os-config angegebenen Ziel, außer die Befehlszeilenoption --no-bootloader wurde übergeben.

vm
     Build a virtual machine that contains the operating system declared in FILE, and return a script to run that virtual machine (VM).

          The vm action and others below can use KVM support in the Linux-libre kernel.  Specifically, if the machine has hardware virtualization support, the corresponding KVM kernel module should be loaded, and the /dev/kvm device node must exist and be readable and writable by the user and by the build users of the daemon (see Einrichten der Erstellungsumgebung).

     Arguments given to the script are passed to QEMU as in the example below, which enables networking and requests 1 GiB of RAM for the emulated machine:

          $ /gnu/store/...-run-vm.sh -m 1024 -net user

     Die virtuelle Maschine verwendet denselben Store wie das Wirtssystem.

     Mit den Befehlszeilenoptionen --share und --expose können weitere Dateisysteme zwischen dem Wirtssystem und der VM geteilt werden: Der erste Befehl gibt ein mit Schreibzugriff zu teilendes Verzeichnis an, während der letzte Befehl nur Lesezugriff auf das gemeinsame Verzeichnis gestattet.

     Im folgenden Beispiel wird eine virtuelle Maschine erzeugt, die auf das Persönliche Verzeichnis des Benutzers nur Lesezugriff hat, wo das Verzeichnis /austausch aber mit Lese- und Schreibzugriff dem Verzeichnis $HOME/tmp auf dem Wirtssystem zugeordnet wurde:

          guix system vm my-config.scm \
             --expose=$HOME --share=$HOME/tmp=/austausch

     Für GNU/Linux ist das vorgegebene Verhalten, direkt in den Kernel zu booten, wodurch nur ein sehr winziges »Disk-Image« (eine Datei mit einem Abbild des Plattenspeichers der virtuellen Maschine) für das Wurzeldateisystem nötig wird, weil der Store des Wirtssystems davon eingebunden werden kann.

     Mit der Befehlszeilenoption --full-boot wird erzwungen, einen vollständigen Bootvorgang durchzuführen, angefangen mit dem Bootloader. Dadurch wird mehr Plattenplatz verbraucht, weil dazu ein Disk-Image mindestens mit dem Kernel, initrd und Bootloader-Datendateien erzeugt werden muss. Mit der Befehlszeilenoption --image-size kann die Größe des Disk-Images angegeben werden.

vm-image
disk-image
docker-image
     Ein eigenständiges Disk-Image für eine virtuelle Maschine, ein allgemeines Disk-Image oder ein Docker-Abbild für das in der DATEI deklarierte Betriebssystem liefern. Das vorgegebene Verhalten von guix system ist, die Größe des Images zu schätzen, die zum Speichern des Systems benötigt wird, aber Sie können mit der Befehlszeilenoption --image-size selbst Ihre gewünschte Größe bestimmen. Docker-Abbilder werden aber so erstellt, dass sie gerade nur das enthalten, was für sie nötig ist, daher wird die Befehlszeilenoption --image-size im Fall von docker-image ignoriert.

     Sie können den Dateisystemtyp für das Wurzeldateisystem mit der Befehlszeilenoption --file-system-type festlegen. Vorgegeben ist, ext4 zu verwenden.

     When using vm-image, the returned image is in qcow2 format, which the QEMU emulator can efficiently use. See Running Guix in a VM, for more information on how to run the image in a virtual machine.

     Wenn Sie ein disk-image anfordern, wird ein rohes Disk-Image hergestellt; es kann zum Beispiel auf einen USB-Stick kopiert werden. Angenommen /dev/sdc ist das dem USB-Stick entsprechende Gerät, dann kann das Disk-Image mit dem folgenden Befehls darauf kopiert werden:

          # dd if=$(guix system disk-image my-os.scm) of=/dev/sdc

     Wenn Sie ein docker-image anfordern, wird ein Abbild für Docker hergestellt. Guix erstellt das Abbild von Grund auf und nicht aus einem vorerstellten Docker-Basisabbild heraus, daher enthält es exakt das, was Sie in der Konfigurationsdatei für das Betriebssystem angegeben haben. Sie können das Abbild dann wie folgt laden und einen Docker-Container damit erzeugen:

          image_id="$(docker load < guixsd-docker-image.tar.gz)"
          docker run -e GUIX_NEW_SYSTEM=/var/guix/profiles/system \\
              --entrypoint /var/guix/profiles/system/profile/bin/guile \\
              $image_id /var/guix/profiles/system/boot

     This command starts a new Docker container from the specified image.  It will boot the Guix system in the usual manner, which means it will start any services you have defined in the operating system configuration.  Depending on what you run in the Docker container, it may be necessary to give the container additional permissions.  For example, if you intend to build software using Guix inside of the Docker container, you may need to pass the --privileged option to docker run.

container
     Liefert ein Skript, um das in der DATEI deklarierte Betriebssystem in einem Container auszuführen. Mit Container wird hier eine Reihe ressourcenschonender Isolierungsmechanismen im Kernel Linux-libre bezeichnet. Container beanspruchen wesentlich weniger Ressourcen als vollumfängliche virtuelle Maschinen, weil der Kernel, Bibliotheken in gemeinsam nutzbaren Objektdateien (»Shared Objects«) sowie andere Ressourcen mit dem Wirtssystem geteilt werden können. Damit ist also eine »dünnere« Isolierung möglich.

     Zur Zeit muss das Skript als Administratornutzer »root« ausgeführt werden, damit darin mehr als nur ein einzelner Benutzer und eine Benutzergruppe unterstützt wird. Der Container teilt seinen Store mit dem Wirtssystem.

     Wie bei der Aktion vm (see guix system vm) können zusätzlich weitere Dateisysteme zwischen Wirt und Container geteilt werden, indem man die Befehlszeilenoptionen --share und --expose verwendet:

          guix system container my-config.scm \
             --expose=$HOME --share=$HOME/tmp=/austausch

          Diese Befehlszeilenoption funktioniert nur mit Linux-libre 3.19 oder neuer.

Unter den OPTIONEN können beliebige gemeinsame Erstellungsoptionen aufgeführt werden (siehe Gemeinsame Erstellungsoptionen). Des Weiteren kann als OPTIONEN Folgendes angegeben werden:

--expression=AUSDRUCK
-e AUSDRUCK
     Consider the operating-system EXPR evaluates to.  This is an alternative to specifying a file which evaluates to an operating system. This is used to generate the Guix system installer see Ein Abbild zur Installation erstellen).

--system=SYSTEM
-s SYSTEM
     Versuche, für das angegebene SYSTEM statt für denselben Systemtyp wie auf dem Wirtssystem zu erstellen. Dies funktioniert wie bei guix build (see Aufruf von guix build).

--derivation
-d
     Liefert den Namen der Ableitungsdatei für das angegebene Betriebssystem, ohne dazu etwas zu erstellen.

--file-system-type=TYP
-t TYPE
     Für die Aktion disk-image wird hiermit ein Dateisystem des angegebenen TYPs im Abbild bzw. Disk-Image erzeugt.

     Wird diese Befehlszeilenoption nicht angegeben, so benutzt guix system als Dateisystemtyp ext4.

     --file-system-type=iso9660 erzeugt ein Abbild im Format ISO-9660, was für das Brennen auf CDs und DVDs geeignet ist.

--image-size=GRÖSSE
     Für die Aktionen vm-image und disk-image wird hiermit festgelegt, dass ein Abbild der angegebenen GRÖSSE erstellt werden soll. Die GRÖSSE kann als Zahl die Anzahl Bytes angeben oder mit einer Einheit als Suffix versehen werden (siehe size specifications (GNU Coreutils)).

     Wird keine solche Befehlszeilenoption angegeben, berechnet guix system eine Schätzung der Abbildgröße anhand der Größe des in der DATEI deklarierten Systems.

--root=FILE
-r FILE
     Make FILE a symlink to the result, and register it as a garbage collector root.

--skip-checks
     Die Konfiguration nicht vor der Installation zur Sicherheit auf Fehler prüfen.

     Das vorgegebene Verhalten von guix system init und guix system reconfigure sieht vor, die Konfiguration zur Sicherheit auf Fehler hin zu überprüfen, die ihr Autor übersehen haben könnte: Es wird sichergestellt, dass die in der operating-system-Deklaration erwähnten Dateisysteme tatsächlich existieren (see Dateisysteme) und dass alle Linux-Kernelmodule, die beim Booten benötigt werden könnten, auch im initrd-modules-Feld aufgeführt sind (see Initiale RAM-Disk). Mit dieser Befehlszeilenoption werden diese Tests allesamt übersprungen.

--on-error=STRATEGIE
     Beim Auftreten eines Fehlers beim Einlesen der DATEI die angegebene STRATEGIE verfolgen. Als STRATEGIE dient eine der Folgenden:

     nothing-special
          Nichts besonderes; der Fehler wird kurz gemeldet und der Vorgang abgebrochen. Dies ist die vorgegebene Strategie.

     backtrace
          Ebenso, aber zusätzlich wird eine Rückverfolgung des Fehlers (ein »Backtrace«) angezeigt.

     debug
          Nach dem Melden des Fehlers wird der Debugger von Guile zur Fehlersuche gestartet. Von dort können Sie Befehle ausführen, zum Beispiel können Sie sich mit ,bt eine Rückverfolgung (»Backtrace«) anzeigen lassen und mit ,locals die Werte lokaler Variabler anzeigen lassen. Im Allgemeinen können Sie mit Befehlen den Zustand des Programms inspizieren. Siehe Debug Commands (GNU Guile Reference Manual) für eine Liste verfügbarer Befehle zur Fehlersuche.

Once you have built, configured, re-configured, and re-re-configured your Guix installation, you may find it useful to list the operating system generations available on disk---and that you can choose from the bootloader boot menu:

list-generations
     Eine für Menschen verständliche Zusammenfassung jeder auf der Platte verfügbaren Generation des Betriebssystems ausgeben. Dies ähnelt der Befehlszeilenoption --list-generations von guix package (see Aufruf von guix package).

     Optional kann ein Muster angegeben werden, was dieselbe Syntax wie guix package --list-generations benutzt, um damit die Liste anzuzeigender Generationen einzuschränken. Zum Beispiel zeigt der folgende Befehl Generationen an, die bis zu 10 Tage alt sind:

          $ guix system list-generations 10d

Der Befehl guix system hat sogar noch mehr zu bieten! Mit folgenden Unterbefehlen wird Ihnen visualisiert, wie Ihre Systemdienste voneinander abhängen:

extension-graph
     Im Dot-/Graphviz-Format auf die Standardausgabe den Diensterweiterungsgraphen des in der DATEI definierten Betriebssystems ausgeben (see Dienstkompositionen, für mehr Informationen zu Diensterweiterungen).

     Der Befehl:

          $ guix system extension-graph FILE | dot -Tpdf > services.pdf

     erzeugt eine PDF-Datei, in der die Erweiterungsrelation unter Diensten angezeigt wird.

shepherd-graph
     Im Dot-/Graphviz-Format auf die Standardausgabe den Abhängigkeitsgraphen der Shepherd-Dienste des in der DATEI definierten Betriebssystems ausgeben. Siehe Shepherd-Dienste für mehr Informationen sowie einen Beispielgraphen.

Running Guix in a Virtual Machine
=================================

To run Guix in a virtual machine (VM), one can either use the pre-built Guix VM image distributed at https://alpha.gnu.org/gnu/guix/guixsd-vm-image-VERSION.SYSTEM.xz , or build their own virtual machine image using guix system vm-image (see Aufruf von guix system).  The returned image is in qcow2 format, which the QEMU emulator (http://qemu.org/) can efficiently use.

If you built your own image, you must copy it out of the store (see Der Store) and give yourself permission to write to the copy before you can use it.  When invoking QEMU, you must choose a system emulator that is suitable for your hardware platform.  Here is a minimal QEMU invocation that will boot the result of guix system vm-image on x86_64 hardware:

     $ qemu-system-x86_64 \
        -net user -net nic,model=virtio \
        -enable-kvm -m 256 /tmp/qemu-image

Here is what each of these options means:

qemu-system-x86_64
     This specifies the hardware platform to emulate.  This should match the host.

-net user
     Enable the unprivileged user-mode network stack.  The guest OS can access the host but not vice versa.  This is the simplest way to get the guest OS online.

-net nic,model=virtio
     You must create a network interface of a given model.  If you do not create a NIC, the boot will fail.  Assuming your hardware platform is x86_64, you can get a list of available NIC models by running qemu-system-x86_64 -net nic,model=help.

-enable-kvm
     If your system has hardware virtualization extensions, enabling the virtual machine support (KVM) of the Linux kernel will make things run faster.

-m 256
     RAM available to the guest OS, in mebibytes.  Defaults to 128 MiB, which may be insufficient for some operations.

/tmp/qemu-image
     The file name of the qcow2 image.

The default run-vm.sh script that is returned by an invocation of guix system vm does not add a -net user flag by default.  To get network access from within the vm add the (dhcp-client-service) to your system definition and start the VM using `guix system vm config.scm` -net user.  An important caveat of using -net user for networking is that ping will not work, because it uses the ICMP protocol.  You'll have to use a different command to check for network connectivity, for example guix download.

Connecting Through SSH
----------------------

To enable SSH inside a VM you need to add a SSH server like (dropbear-service) or (lsh-service) to your VM.  The (lsh-service) doesn't currently boot unsupervised.  It requires you to type some characters to initialize the randomness generator.  In addition you need to forward the SSH port, 22 by default, to the host.  You can do this with

     `guix system vm config.scm` -net user,hostfwd=tcp::10022-:22

To connect to the VM you can run

     ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022

The -p tells ssh the port you want to connect to. -o UserKnownHostsFile=/dev/null prevents ssh from complaining every time you modify your config.scm file and the -o StrictHostKeyChecking=no prevents you from having to allow a connection to an unknown host every time you connect.

Using virt-viewer with Spice
----------------------------

As an alternative to the default qemu graphical client you can use the remote-viewer from the virt-viewer package.  To connect pass the -spice port=5930,disable-ticketing flag to qemu.  See previous section for further information on how to do this.

Spice also allows you to do some nice stuff like share your clipboard with your VM.  To enable that you'll also have to pass the following flags to qemu:

     -device virtio-serial-pci,id=virtio-serial0,max_ports=16,bus=pci.0,addr=0x5
     -chardev spicevmc,name=vdagent,id=vdagent
     -device virtserialport,nr=1,bus=virtio-serial0.0,chardev=vdagent,
     name=com.redhat.spice.0

You'll also need to add the see Spice service.

Dienste definieren
==================

The previous sections show the available services and how one can combine them in an operating-system declaration.  But how do we define them in the first place? And what is a service anyway?

Dienstkompositionen
-------------------

Here we define a service as, broadly, something that extends the functionality of the operating system.  Often a service is a process---a daemon---started when the system boots: a secure shell server, a Web server, the Guix build daemon, etc.  Sometimes a service is a daemon whose execution can be triggered by another daemon---e.g., an FTP server started by inetd or a D-Bus service activated by dbus-daemon. Occasionally, a service does not map to a daemon.  For instance, the ``account'' service collects user accounts and makes sure they exist when the system runs; the ``udev'' service collects device management rules and makes them available to the eudev daemon; the /etc service populates the /etc directory of the system.

Guix system services are connected by extensions.  For instance, the secure shell service extends the Shepherd---the initialization system, running as PID 1---by giving it the command lines to start and stop the secure shell daemon (see openssh-service-type); the UPower service extends the D-Bus service by passing it its .service specification, and extends the udev service by passing it device management rules (see upower-service); the Guix daemon service extends the Shepherd by passing it the command lines to start and stop the daemon, and extends the account service by passing it a list of required build user accounts (see Basisdienste).

All in all, services and their ``extends'' relations form a directed acyclic graph (DAG).  If we represent services as boxes and extensions as arrows, a typical system might provide something like this:

Typical service extension graph.

At the bottom, we see the system service, which produces the directory containing everything to run and boot the system, as returned by the guix system build command.  See Service-Referenz, to learn about the other service types shown here.  See the guix system extension-graph command, for information on how to generate this representation for a particular operating system definition.

Technically, developers can define service types to express these relations.  There can be any number of services of a given type on the system---for instance, a system running two instances of the GNU secure shell server (lsh) has two instances of lsh-service-type, with different parameters.

The following section describes the programming interface for service types and services.

Diensttypen und Dienste
-----------------------

A service type is a node in the DAG described above.  Let us start with a simple example, the service type for the Guix build daemon (see Aufruf des guix-daemon):

     (define guix-service-type
       (service-type
        (name 'guix)
        (extensions
         (list (service-extension shepherd-root-service-type guix-shepherd-service)
               (service-extension account-service-type guix-accounts)
               (service-extension activation-service-type guix-activation)))
        (default-value (guix-configuration))))

It defines three things:

 1. A name, whose sole purpose is to make inspection and debugging easier.

 2. A list of service extensions, where each extension designates the target service type and a procedure that, given the parameters of the service, returns a list of objects to extend the service of that type.

     Every service type has at least one service extension.  The only exception is the boot service type, which is the ultimate service.

 3. Optionally, a default value for instances of this type.

In this example, GUIX-SERVICE-TYPE extends three services:

shepherd-root-service-type
     The GUIX-SHEPHERD-SERVICE procedure defines how the Shepherd service is extended.  Namely, it returns a <shepherd-service> object that defines how guix-daemon is started and stopped (see Shepherd-Dienste).

account-service-type
     This extension for this service is computed by GUIX-ACCOUNTS, which returns a list of user-group and user-account objects representing the build user accounts (see Aufruf des guix-daemon).

activation-service-type
     Here GUIX-ACTIVATION is a procedure that returns a gexp, which is a code snippet to run at ``activation time''---e.g., when the service is booted.

A service of this type is instantiated like this:

     (service guix-service-type
              (guix-configuration
                (build-accounts 5)
                (use-substitutes? #f)))

The second argument to the service form is a value representing the parameters of this specific service instance. See guix-configuration, for information about the guix-configuration data type.  When the value is omitted, the default value specified by guix-service-type is used:

     (service guix-service-type)

GUIX-SERVICE-TYPE is quite simple because it extends other services but is not extensible itself.

The service type for an extensible service looks like this:

     (define udev-service-type
       (service-type (name 'udev)
                     (extensions
                      (list (service-extension shepherd-root-service-type
                                               udev-shepherd-service)))

                     (compose concatenate)       ;concatenate the list of rules
                     (extend (lambda (config rules)
                               (match config
                                 (($ <udev-configuration> udev initial-rules)
                                  (udev-configuration
                                   (udev udev)   ;the udev package to use
                                   (rules (append initial-rules rules)))))))))

This is the service type for the eudev device management daemon (https://wiki.gentoo.org/wiki/Project:Eudev).  Compared to the previous example, in addition to an extension of SHEPHERD-ROOT-SERVICE-TYPE, we see two new fields:

compose
     This is the procedure to compose the list of extensions to services of this type.

     Services can extend the udev service by passing it lists of rules; we compose those extensions simply by concatenating them.

extend
     This procedure defines how the value of the service is extended with the composition of the extensions.

     Udev extensions are composed into a list of rules, but the udev service value is itself a <udev-configuration> record.  So here, we extend that record by appending the list of rules it contains to the list of contributed rules.

description
     This is a string giving an overview of the service type.  The string can contain Texinfo markup (see Overview (GNU Texinfo)).  The guix system search command searches these strings and displays them (see Aufruf von guix system).

There can be only one instance of an extensible service type such as UDEV-SERVICE-TYPE.  If there were more, the service-extension specifications would be ambiguous.

Still here? The next section provides a reference of the programming interface for services.

Service-Referenz
----------------

We have seen an overview of service types (see Diensttypen und Dienste).  This section provides a reference on how to manipulate services and service types.  This interface is provided by the (gnu services) module.

 -- Scheme Procedure: service TYPE [VALUE]
     Return a new service of TYPE, a <service-type> object (see below.)  VALUE can be any object; it represents the parameters of this particular service instance.

     When VALUE is omitted, the default value specified by TYPE is used; if TYPE does not specify a default value, an error is raised.

     For instance, this:

          (service openssh-service-type)

     is equivalent to this:

          (service openssh-service-type
                   (openssh-configuration))

     In both cases the result is an instance of openssh-service-type with the default configuration.

 -- Scheme Procedure: service? OBJ
     Return true if OBJ is a service.

 -- Scheme Procedure: service-kind SERVICE
     Return the type of SERVICE---i.e., a <service-type> object.

 -- Scheme Procedure: service-value SERVICE
     Return the value associated with SERVICE.  It represents its parameters.

Here is an example of how a service is created and manipulated:

     (define s
       (service nginx-service-type
                (nginx-configuration
                 (nginx nginx)
                 (log-directory log-directory)
                 (run-directory run-directory)
                 (file config-file))))

     (service? s)
     => #t

     (eq? (service-kind s) nginx-service-type)
     => #t

The modify-services form provides a handy way to change the parameters of some of the services of a list such as %BASE-SERVICES (see %base-services).  It evaluates to a list of services.  Of course, you could always use standard list combinators such as map and fold to do that (see List Library (GNU Guile Reference Manual)); modify-services simply provides a more concise form for this common pattern.

 -- Scheme-Syntax: modify-services DIENSTE
     (TYP VARIABLE => RUMPF) ...

     Passt die von DIENSTE bezeichnete Dienst-Liste entsprechend den angegebenen Klauseln an. Jede Klausel hat die Form:

          (TYP VARIABLE => RUMPF)

     wobei TYP einen Diensttyp (»service type«) bezeichnet — wie zum Beispiel guix-service-type — und VARIABLE ein Bezeichner ist, der im RUMPF an die Dienst-Parameter — z.B. eine guix-configuration-Instanz — des ursprünglichen Dienstes mit diesem TYP gebunden wird.

     Der RUMPF muss zu den neuen Dienst-Parametern ausgewertet werden, welche benutzt werden, um den neuen Dienst zu konfigurieren. Dieser neue Dienst wird das Original in der resultierenden Liste ersetzen. Weil die Dienstparameter eines Dienstes mit define-record-type* erzeugt werden, können Sie einen kurzen RUMPF schreiben, der zu den neuen Dienstparametern ausgewertet wird, indem Sie die Funktionalität namens inherit benutzen, die von define-record-type* bereitgestellt wird.

     Siehe Das Konfigurationssystem nutzen für ein Anwendungsbeispiel.

Next comes the programming interface for service types.  This is something you want to know when writing new service definitions, but not necessarily when simply looking for ways to customize your operating-system declaration.

 -- Data Type: service-type
     This is the representation of a service type (see Diensttypen und Dienste).

     name
          This is a symbol, used only to simplify inspection and debugging.

     extensions
          A non-empty list of <service-extension> objects (see below).

     compose (default: #f)
          If this is #f, then the service type denotes services that cannot be extended---i.e., services that do not receive ``values'' from other services.

          Otherwise, it must be a one-argument procedure.  The procedure is called by fold-services and is passed a list of values collected from extensions.  It may return any single value.

     extend (default: #f)
          If this is #f, services of this type cannot be extended.

          Otherwise, it must be a two-argument procedure: fold-services calls it, passing it the initial value of the service as the first argument and the result of applying compose to the extension values as the second argument.  It must return a value that is a valid parameter value for the service instance.

     See Diensttypen und Dienste, for examples.

 -- Scheme Procedure: service-extension TARGET-TYPE
     COMPUTE Return a new extension for services of type
     TARGET-TYPE.  COMPUTE must be a one-argument procedure: fold-services calls it, passing it the value associated with the service that provides the extension; it must return a valid value for the target service.

 -- Scheme Procedure: service-extension? OBJ
     Return true if OBJ is a service extension.

Occasionally, you might want to simply extend an existing service.  This involves creating a new service type and specifying the extension of interest, which can be verbose; the simple-service procedure provides a shorthand for this.

 -- Scheme Procedure: simple-service NAME TARGET VALUE
     Return a service that extends TARGET with VALUE.  This works by creating a singleton service type NAME, of which the returned service is an instance.

     For example, this extends mcron (see Geplante Auftragsausführung) with an additional job:

          (simple-service 'my-mcron-job mcron-service-type
                          #~(job '(next-hour (3)) "guix gc -F 2G"))

At the core of the service abstraction lies the fold-services procedure, which is responsible for ``compiling'' a list of services down to a single directory that contains everything needed to boot and run the system---the directory shown by the guix system build command (see Aufruf von guix system).  In essence, it propagates service extensions down the service graph, updating each node parameters on the way, until it reaches the root node.

 -- Scheme Procedure: fold-services SERVICES
     [#:target-type SYSTEM-SERVICE-TYPE] Fold SERVICES by propagating
     their extensions down to the root of type TARGET-TYPE; return the root service adjusted accordingly.

Lastly, the (gnu services) module also defines several essential service types, some of which are listed below.

 -- Scheme Variable: system-service-type
     This is the root of the service graph.  It produces the system directory as returned by the guix system build command.

 -- Scheme Variable: boot-service-type
     The type of the ``boot service'', which produces the boot script.  The boot script is what the initial RAM disk runs when booting.

 -- Scheme Variable: etc-service-type
     The type of the /etc service.  This service is used to create files under /etc and can be extended by passing it name/file tuples such as:

          (list `("issue" ,(plain-file "issue" "Welcome!\n")))

     In this example, the effect would be to add an /etc/issue file pointing to the given file.

 -- Scheme Variable: setuid-program-service-type
     Type for the ``setuid-program service''.  This service collects lists of executable file names, passed as gexps, and adds them to the set of setuid-root programs on the system (see Setuid-Programme).

 -- Scheme Variable: profile-service-type
     Type of the service that populates the system profile---i.e., the programs under /run/current-system/profile.  Other services can extend it by passing it lists of packages to add to the system profile.

Shepherd-Dienste
----------------

The (gnu services shepherd) module provides a way to define services managed by the GNU Shepherd, which is the initialization system---the first process that is started when the system boots, also known as PID 1 (see Einführung (The GNU Shepherd Manual)).

Services in the Shepherd can depend on each other.  For instance, the SSH daemon may need to be started after the syslog daemon has been started, which in turn can only happen once all the file systems have been mounted. The simple operating system defined earlier (see Das Konfigurationssystem nutzen) results in a service graph like this:

Typical shepherd service graph.

You can actually generate such a graph for any operating system definition using the guix system shepherd-graph command (see guix system shepherd-graph).

The %SHEPHERD-ROOT-SERVICE is a service object representing PID 1, of type SHEPHERD-ROOT-SERVICE-TYPE; it can be extended by passing it lists of <shepherd-service> objects.

 -- Data Type: shepherd-service
     The data type representing a service managed by the Shepherd.

     provision
          This is a list of symbols denoting what the service provides.

          These are the names that may be passed to herd start, herd status, and similar commands (see Invoking herd (The GNU Shepherd Manual)).  See the provides slot (The GNU Shepherd Manual), for details.

     requirements (default: '())
          List of symbols denoting the Shepherd services this one depends on.

     respawn? (default: #t)
          Whether to restart the service when it stops, for instance when the underlying process dies.

     start
     stop (default: #~(const #f))
          The start and stop fields refer to the Shepherd's facilities to start and stop processes (see Service De- and Constructors (The GNU Shepherd Manual)).  They are given as G-expressions that get expanded in the Shepherd configuration file (see G-Ausdrücke).

     actions (Vorgabe: '())
          This is a list of shepherd-action objects (see below) defining actions supported by the service, in addition to the standard start and stop actions.  Actions listed here become available as herd sub-commands:

               herd ACTION SERVICE [ARGUMENTS...]

     Dokumentation
          A documentation string, as shown when running:

               herd doc SERVICE-NAME

          where SERVICE-NAME is one of the symbols in PROVISION (see Invoking herd (The GNU Shepherd Manual)).

     modules (default: %DEFAULT-MODULES)
          This is the list of modules that must be in scope when start and stop are evaluated.

 -- Datentyp: shepherd-action
     This is the data type that defines additional actions implemented by a Shepherd service (see above).

     name
          Die Aktion bezeichnendes Symbol.

     Dokumentation
          This is a documentation string for the action.  It can be viewed by running:

               herd doc SERVICE action ACTION

     procedure
          This should be a gexp that evaluates to a procedure of at least one argument, which is the ``running value'' of the service (see Slots of services (The GNU Shepherd Manual)).

     The following example defines an action called say-hello that kindly greets the user:

          (shepherd-action
            (name 'say-hello)
            (documentation "Say hi!")
            (procedure #~(lambda (running . args)
                           (format #t "Hello, friend! arguments: ~s\n"
                                   args)
                           #t)))

     Assuming this action is added to the example service, then you can do:

          # herd say-hello example
          Hello, friend! arguments: ()
          # herd say-hello example a b c
          Hello, friend! arguments: ("a" "b" "c")

     This, as you can see, is a fairly sophisticated way to say hello. See Service Convenience (The GNU Shepherd Manual), for more info on actions.

 -- Scheme Variable: shepherd-root-service-type
     The service type for the Shepherd ``root service''---i.e., PID 1.

     This is the service type that extensions target when they want to create shepherd services (see Diensttypen und Dienste, for an example). Each extension must pass a list of <shepherd-service>.

 -- Scheme Variable: %shepherd-root-service
     This service represents PID 1.

Dokumentation
*************

In most cases packages installed with Guix come with documentation.  There are two main documentation formats: ``Info'', a browseable hypertext format used for GNU software, and ``manual pages'' (or ``man pages''), the linear documentation format traditionally found on Unix.  Info manuals are accessed with the info command or with Emacs, and man pages are accessed using man.

You can look for documentation of software installed on your system by keyword.  For example, the following command searches for information about ``TLS'' in Info manuals:

     $ info -k TLS
     "(emacs)Network Security" -- STARTTLS
     "(emacs)Network Security" -- TLS
     "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_flags
     "(gnutls)Core TLS API" -- gnutls_certificate_set_verify_function
     ...

The command below searches for the same keyword in man pages:

     $ man -k TLS
     SSL (7)              - OpenSSL SSL/TLS library
     certtool (1)         - GnuTLS certificate tool
     ...{}

These searches are purely local to your computer so you have the guarantee that documentation you find corresponds to what you have actually installed, you can access it off-line, and your privacy is respected.

Once you have these results, you can view the relevant documentation by running, say:

     $ info "(gnutls)Core TLS API"

or:

     $ man certtool

Info manuals contain sections and indices as well as hyperlinks like those found in Web pages.  The info reader (see Info reader (Stand-alone GNU Info)) and its Emacs counterpart (see Misc Help (The GNU Emacs Manual)) provide intuitive key bindings to navigate manuals.  See Getting Started (Info: An Introduction), for an introduction to Info navigation.

Dateien zur Fehlersuche installieren
************************************

Program binaries, as produced by the GCC compilers for instance, are typically written in the ELF format, with a section containing debugging information.  Debugging information is what allows the debugger, GDB, to map binary code to source code; it is required to debug a compiled program in good conditions.

The problem with debugging information is that is takes up a fair amount of disk space.  For example, debugging information for the GNU C Library weighs in at more than 60 MiB.  Thus, as a user, keeping all the debugging info of all the installed programs is usually not an option.  Yet, space savings should not come at the cost of an impediment to debugging---especially in the GNU system, which should make it easier for users to exert their computing freedom (see GNU-Distribution).

Thankfully, the GNU Binary Utilities (Binutils) and GDB provide a mechanism that allows users to get the best of both worlds: debugging information can be stripped from the binaries and stored in separate files.  GDB is then able to load debugging information from those files, when they are available (see Separate Debug Files (Debugging with GDB)).

The GNU distribution takes advantage of this by storing debugging information in the lib/debug sub-directory of a separate package output unimaginatively called debug (see Pakete mit mehreren Ausgaben.).  Users can choose to install the debug output of a package when they need it.  For instance, the following command installs the debugging information for the GNU C Library and for GNU Guile:

     guix package -i glibc:debug guile:debug

GDB must then be told to look for debug files in the user's profile, by setting the debug-file-directory variable (consider setting it from the ~/.gdbinit file, see Startup (Debugging with GDB)):

     (gdb) set debug-file-directory ~/.guix-profile/lib/debug

From there on, GDB will pick up debugging information from the .debug files under ~/.guix-profile/lib/debug.

In addition, you will most likely want GDB to be able to show the source code being debugged.  To do that, you will have to unpack the source code of the package of interest (obtained with guix build --source, see Aufruf von guix build), and to point GDB to that source directory using the directory command (see directory (Debugging with GDB)).

The debug output mechanism in Guix is implemented by the gnu-build-system (see Erstellungssysteme).  Currently, it is opt-in---debugging information is available only for the packages with definitions explicitly declaring a debug output.  This may be changed to opt-out in the future if our build farm servers can handle the load.  To check whether a package has a debug output, use guix package --list-available (see Aufruf von guix package).

Sicherheitsaktualisierungen
***************************

Occasionally, important security vulnerabilities are discovered in software packages and must be patched.  Guix developers try hard to keep track of known vulnerabilities and to apply fixes as soon as possible in the master branch of Guix (we do not yet provide a ``stable'' branch containing only security updates.)  The guix lint tool helps developers find out about vulnerable versions of software packages in the distribution:

     $ guix lint -c cve
     gnu/packages/base.scm:652:2: glibc@2.21: probably vulnerable to CVE-2015-1781, CVE-2015-7547
     gnu/packages/gcc.scm:334:2: gcc@4.9.3: probably vulnerable to CVE-2015-5276
     gnu/packages/image.scm:312:2: openjpeg@2.1.0: probably vulnerable to CVE-2016-1923, CVE-2016-1924
     ...

See Aufruf von guix lint, for more information.

     As of version VERSION, the feature described below is considered ``beta''.

Guix follows a functional package management discipline (see Einführung), which implies that, when a package is changed, every package that depends on it must be rebuilt.  This can significantly slow down the deployment of fixes in core packages such as libc or Bash, since basically the whole distribution would need to be rebuilt.  Using pre-built binaries helps (see Substitute), but deployment may still take more time than desired.

To address this, Guix implements grafts, a mechanism that allows for fast deployment of critical updates without the costs associated with a whole-distribution rebuild.  The idea is to rebuild only the package that needs to be patched, and then to ``graft'' it onto packages explicitly installed by the user and that were previously referring to the original package.  The cost of grafting is typically very low, and order of magnitudes lower than a full rebuild of the dependency chain.

For instance, suppose a security update needs to be applied to Bash.  Guix developers will provide a package definition for the ``fixed'' Bash, say BASH-FIXED, in the usual way (see Pakete definieren).  Then, the original package definition is augmented with a replacement field pointing to the package containing the bug fix:

     (define bash
       (package
         (name "bash")
         ;; ...
         (replacement bash-fixed)))

From there on, any package depending directly or indirectly on Bash---as reported by guix gc --requisites (see Aufruf von guix gc)---that is installed is automatically ``rewritten'' to refer to BASH-FIXED instead of BASH.  This grafting process takes time proportional to the size of the package, usually less than a minute for an ``average'' package on a recent machine.  Grafting is recursive: when an indirect dependency requires grafting, then grafting ``propagates'' up to the package that the user is installing.

Currently, the length of the name and version of the graft and that of the package it replaces (BASH-FIXED and BASH in the example above) must be equal.  This restriction mostly comes from the fact that grafting works by patching files, including binary files, directly.  Other restrictions may apply: for instance, when adding a graft to a package providing a shared library, the original shared library and its replacement must have the same SONAME and be binary-compatible.

The --no-grafts command-line option allows you to forcefully avoid grafting (see --no-grafts).  Thus, the command:

     guix build bash --no-grafts

returns the store file name of the original Bash, whereas:

     guix build bash

returns the store file name of the ``fixed'', replacement Bash.  This allows you to distinguish between the two variants of Bash.

To verify which Bash your whole profile refers to, you can run (see Aufruf von guix gc):

     guix gc -R `readlink -f ~/.guix-profile` | grep bash

... and compare the store file names that you get with those above. Likewise for a complete Guix system generation:

     guix gc -R `guix system build my-config.scm` | grep bash

Lastly, to check which Bash running processes are using, you can use the lsof command:

     lsof | grep /gnu/store/.*bash

Bootstrapping
*************

Bootstrapping in our context refers to how the distribution gets built ``from nothing''.  Remember that the build environment of a derivation contains nothing but its declared inputs (see Einführung).  So there's an obvious chicken-and-egg problem: how does the first package get built? How does the first compiler get compiled? Note that this is a question of interest only to the curious hacker, not to the regular user, so you can shamelessly skip this section if you consider yourself a ``regular user''.

The GNU system is primarily made of C code, with libc at its core.  The GNU build system itself assumes the availability of a Bourne shell and command-line tools provided by GNU Coreutils, Awk, Findutils, `sed', and `grep'.  Furthermore, build programs---programs that run ./configure, make, etc.---are written in Guile Scheme (see Ableitungen). Consequently, to be able to build anything at all, from scratch, Guix relies on pre-built binaries of Guile, GCC, Binutils, libc, and the other packages mentioned above---the bootstrap binaries.

These bootstrap binaries are ``taken for granted'', though we can also re-create them if needed (more on that later).

Preparing to Use the Bootstrap Binaries
=======================================

Dependency graph of the early bootstrap derivations

The figure above shows the very beginning of the dependency graph of the distribution, corresponding to the package definitions of the (gnu packages bootstrap) module.  A similar figure can be generated with guix graph (see Aufruf von guix graph), along the lines of:

     guix graph -t derivation \
       -e '(@@ (gnu packages bootstrap) %bootstrap-gcc)' \
       | dot -Tps > t.ps

At this level of detail, things are slightly complex.  First, Guile itself consists of an ELF executable, along with many source and compiled Scheme files that are dynamically loaded when it runs.  This gets stored in the guile-2.0.7.tar.xz tarball shown in this graph.  This tarball is part of Guix's ``source'' distribution, and gets inserted into the store with add-to-store (see Der Store).

But how do we write a derivation that unpacks this tarball and adds it to the store? To solve this problem, the guile-bootstrap-2.0.drv derivation---the first one that gets built---uses bash as its builder, which runs build-bootstrap-guile.sh, which in turn calls tar to unpack the tarball.  Thus, bash, tar, xz, and mkdir are statically-linked binaries, also part of the Guix source distribution, whose sole purpose is to allow the Guile tarball to be unpacked.

Once guile-bootstrap-2.0.drv is built, we have a functioning Guile that can be used to run subsequent build programs.  Its first task is to download tarballs containing the other pre-built binaries---this is what the .tar.xz.drv derivations do.  Guix modules such as ftp-client.scm are used for this purpose.  The module-import.drv derivations import those modules in a directory in the store, using the original layout.  The module-import-compiled.drv derivations compile those modules, and write them in an output directory with the right layout.  This corresponds to the #:modules argument of build-expression->derivation (see Ableitungen).

Finally, the various tarballs are unpacked by the derivations gcc-bootstrap-0.drv, glibc-bootstrap-0.drv, etc., at which point we have a working C tool chain.

Building the Build Tools
========================

Bootstrapping is complete when we have a full tool chain that does not depend on the pre-built bootstrap tools discussed above.  This no-dependency requirement is verified by checking whether the files of the final tool chain contain references to the /gnu/store directories of the bootstrap inputs.  The process that leads to this ``final'' tool chain is described by the package definitions found in the (gnu packages commencement) module.

The guix graph command allows us to ``zoom out'' compared to the graph above, by looking at the level of package objects instead of individual derivations---remember that a package may translate to several derivations, typically one derivation to download its source, one to build the Guile modules it needs, and one to actually build the package from source.  The command:

     guix graph -t bag \
       -e '(@@ (gnu packages commencement)
               glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps

produces the dependency graph leading to the ``final'' C library (You may notice the glibc-intermediate label, suggesting that it is not quite final, but as a good approximation, we will consider it final.), depicted below.

Dependency graph of the early packages

The first tool that gets built with the bootstrap binaries is GNU Make---noted make-boot0 above---which is a prerequisite for all the following packages.  From there Findutils and Diffutils get built.

Then come the first-stage Binutils and GCC, built as pseudo cross tools---i.e., with --target equal to --host.  They are used to build libc.  Thanks to this cross-build trick, this libc is guaranteed not to hold any reference to the initial tool chain.

From there the final Binutils and GCC (not shown above) are built.  GCC uses ld from the final Binutils, and links programs against the just-built libc.  This tool chain is used to build the other packages used by Guix and by the GNU Build System: Guile, Bash, Coreutils, etc.

And voilà! At this point we have the complete set of build tools that the GNU Build System expects.  These are in the %final-inputs variable of the (gnu packages commencement) module, and are implicitly used by any package that uses gnu-build-system (see gnu-build-system).

Building the Bootstrap Binaries
===============================

Because the final tool chain does not depend on the bootstrap binaries, those rarely need to be updated.  Nevertheless, it is useful to have an automated way to produce them, should an update occur, and this is what the (gnu packages make-bootstrap) module provides.

The following command builds the tarballs containing the bootstrap binaries (Guile, Binutils, GCC, libc, and a tarball containing a mixture of Coreutils and other basic command-line tools):

     guix build bootstrap-tarballs

The generated tarballs are those that should be referred to in the (gnu packages bootstrap) module mentioned at the beginning of this section.

Still here? Then perhaps by now you've started to wonder: when do we reach a fixed point? That is an interesting question! The answer is unknown, but if you would like to investigate further (and have significant computational and storage resources to do so), then let us know.

Reducing the Set of Bootstrap Binaries
======================================

Our bootstrap binaries currently include GCC, Guile, etc.  That's a lot of binary code! Why is that a problem? It's a problem because these big chunks of binary code are practically non-auditable, which makes it hard to establish what source code produced them.  Every unauditable binary also leaves us vulnerable to compiler backdoors as described by Ken Thompson in the 1984 paper Reflections on Trusting Trust.

This is mitigated by the fact that our bootstrap binaries were generated from an earlier Guix revision.  Nevertheless it lacks the level of transparency that we get in the rest of the package dependency graph, where Guix always gives us a source-to-binary mapping.  Thus, our goal is to reduce the set of bootstrap binaries to the bare minimum.

The Bootstrappable.org web site (http://bootstrappable.org) lists on-going projects to do that.  One of these is about replacing the bootstrap GCC with a sequence of assemblers, interpreters, and compilers of increasing complexity, which could be built from source starting from a simple and auditable assembler.  Your help is welcome!

Porting to a New Platform
*************************

As discussed above, the GNU distribution is self-contained, and self-containment is achieved by relying on pre-built ``bootstrap binaries'' (see Bootstrapping).  These binaries are specific to an operating system kernel, CPU architecture, and application binary interface (ABI).  Thus, to port the distribution to a platform that is not yet supported, one must build those bootstrap binaries, and update the (gnu packages bootstrap) module to use them on that platform.

Fortunately, Guix can cross compile those bootstrap binaries.  When everything goes well, and assuming the GNU tool chain supports the target platform, this can be as simple as running a command like this one:

     guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs

For this to work, the glibc-dynamic-linker procedure in (gnu packages bootstrap) must be augmented to return the right file name for libc's dynamic linker on that platform; likewise, system->linux-architecture in (gnu packages linux) must be taught about the new platform.

Once these are built, the (gnu packages bootstrap) module needs to be updated to refer to these binaries on the target platform.  That is, the hashes and URLs of the bootstrap tarballs for the new platform must be added alongside those of the currently supported platforms.  The bootstrap Guile tarball is treated specially: it is expected to be available locally, and gnu/local.mk has rules to download it for the supported architectures; a rule for the new platform must be added as well.

In practice, there may be some complications.  First, it may be that the extended GNU triplet that specifies an ABI (like the eabi suffix above) is not recognized by all the GNU tools.  Typically, glibc recognizes some of these, whereas GCC uses an extra --with-abi configure flag (see gcc.scm for examples of how to handle this).  Second, some of the required packages could fail to build for that platform.  Lastly, the generated binaries could be broken for some reason.

     [file contributing.de.texi not included]

Danksagungen
************

Guix is based on the Nix package manager (http://nixos.org/nix/), which was designed and implemented by Eelco Dolstra, with contributions from other people (see the nix/AUTHORS file in Guix.)  Nix pioneered functional package management, and promoted unprecedented features, such as transactional package upgrades and rollbacks, per-user profiles, and referentially transparent build processes.  Without this work, Guix would not exist.

The Nix-based software distributions, Nixpkgs and NixOS, have also been an inspiration for Guix.

GNU Guix itself is a collective work with contributions from a number of people.  See the AUTHORS file in Guix for more information on these fine people.  The THANKS file lists people who have helped by reporting bugs, taking care of the infrastructure, providing artwork and themes, making suggestions, and more---thank you!

GNU-Lizenz für freie Dokumentation
**********************************

     [file fdl-1.3.texi not included]