diff options
Diffstat (limited to 'doc/guix.de.texi')
| -rw-r--r-- | doc/guix.de.texi | 25126 |
1 files changed, 0 insertions, 25126 deletions
diff --git a/doc/guix.de.texi b/doc/guix.de.texi deleted file mode 100644 index 83dae0d3ec..0000000000 --- a/doc/guix.de.texi +++ /dev/null @@ -1,25126 +0,0 @@ -\input texinfo -@c =========================================================================== -@c -@c This file was generated with po4a. Translate the source file. -@c -@c =========================================================================== -@c -*-texinfo-*- - -@c %**start of header -@setfilename guix.de.info -@documentencoding UTF-8 -@documentlanguage de -@frenchspacing on -@settitle Referenzhandbuch zu GNU Guix -@c %**end of header - -@include version-de.texi - -@c Identifier of the OpenPGP key used to sign tarballs and such. -@set OPENPGP-SIGNING-KEY-ID 3CE464558A84FDC69DB40CFB090B11993D9AEBB5 -@set KEY-SERVER pool.sks-keyservers.net - -@c The official substitute server used by default. -@set SUBSTITUTE-SERVER ci.guix.de.info - -@copying -Copyright @copyright{} 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019 -Ludovic Courtès@* Copyright @copyright{} 2013, 2014, 2016 Andreas Enge@* -Copyright @copyright{} 2013 Nikita Karetnikov@* Copyright @copyright{} 2014, -2015, 2016 Alex Kost@* Copyright @copyright{} 2015, 2016 Mathieu Lirzin@* -Copyright @copyright{} 2014 Pierre-Antoine Rault@* Copyright @copyright{} -2015 Taylan Ulrich Bayırlı/Kammer@* Copyright @copyright{} 2015, 2016, 2017 -Leo Famulari@* Copyright @copyright{} 2015, 2016, 2017, 2018, 2019 Ricardo -Wurmus@* Copyright @copyright{} 2016 Ben Woodcroft@* Copyright @copyright{} -2016, 2017, 2018 Chris Marusich@* Copyright @copyright{} 2016, 2017, 2018 -Efraim Flashner@* Copyright @copyright{} 2016 John Darrington@* Copyright -@copyright{} 2016, 2017 ng0@* Copyright @copyright{} 2016, 2017, -2018, 2019 Jan Nieuwenhuizen@* Copyright @copyright{} 2016 Julien Lepiller@* -Copyright @copyright{} 2016 Alex ter Weele@* Copyright @copyright{} 2016, -2017, 2018, 2019 Christopher Baines@* Copyright @copyright{} 2017, 2018 -Clément Lassieur@* Copyright @copyright{} 2017, 2018 Mathieu Othacehe@* -Copyright @copyright{} 2017 Federico Beffa@* Copyright @copyright{} 2017, -2018 Carlo Zancanaro@* Copyright @copyright{} 2017 Thomas Danckaert@* -Copyright @copyright{} 2017 humanitiesNerd@* Copyright @copyright{} 2017 -Christopher Allan Webber@* Copyright @copyright{} 2017, 2018 Marius Bakke@* -Copyright @copyright{} 2017 Hartmut Goebel@* Copyright @copyright{} 2017 -Maxim Cournoyer@* Copyright @copyright{} 2017, 2018 Tobias Geerinckx-Rice@* -Copyright @copyright{} 2017 George Clemmer@* Copyright @copyright{} 2017 -Andy Wingo@* Copyright @copyright{} 2017, 2018 Arun Isaac@* Copyright -@copyright{} 2017 nee@* Copyright @copyright{} 2018 Rutger Helling@* -Copyright @copyright{} 2018 Oleg Pykhalov@* Copyright @copyright{} 2018 Mike -Gerwitz@* Copyright @copyright{} 2018 Pierre-Antoine Rouby@* Copyright -@copyright{} 2018 Gábor Boskovits@* Copyright @copyright{} 2018 Florian -Pelz@* Copyright @copyright{} 2018 Laura Lazzati@* Copyright @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«. -@end copying - -@dircategory Systemadministration -@direntry -* Guix: (guix.de). Installierte Software und Systemkonfigurationen - verwalten. -* guix package: (guix.de)guix package aufrufen. Pakete installieren, - entfernen und - aktualisieren. -* guix gc: (guix.de)guix gc aufrufen. Unbenutzten Plattenspeicher wieder - freigeben. -* guix pull: (guix.de)guix pull aufrufen. Die Liste verfügbarer Pakete - aktualisieren. -* guix system: (guix.de)guix system aufrufen. Die - Betriebssystemkonfiguration - verwalten. -@end direntry - -@dircategory Softwareentwicklung -@direntry -* guix environment: (guix.de)guix environment aufrufen. Umgebungen für - Entwickler - erstellen -* guix build: (guix.de)guix build aufrufen. Erstellen von Paketen. -* guix pack: (guix.de)guix pack aufrufen. Bündel aus Binärdateien - erstellen. -@end direntry - -@titlepage -@title Referenzhandbuch zu GNU Guix -@subtitle Den funktionalen Paketmanager GNU Guix benutzen -@author Die GNU-Guix-Entwickler - -@page -@vskip 0pt plus 1filll -Edition @value{EDITION} @* @value{UPDATED} @* - -@insertcopying -@end titlepage - -@contents - -@c ********************************************************************* -@node Top -@top GNU Guix - -Dieses Dokument beschreibt GNU Guix, Version @value{VERSION}, ein Werkzeug -zur funktionalen Verwaltung von Softwarepaketen, das für das GNU-System -geschrieben wurde. - -@c TRANSLATORS: You can replace the following paragraph with information on -@c how to join your own translation team and how to report issues with the -@c translation. -Dieses Handbuch ist auch auf Englisch (@pxref{Top,,, guix, GNU Guix -Reference Manual}) und Französisch verfügbar (@pxref{Top,,, guix.fr, Manuel -de référence de GNU Guix}). Wenn Sie es in Ihre eigene Sprache übersetzen -möchten, dann sind Sie beim -@uref{https://translationproject.org/domain/guix-manual.html, Translation -Project} herzlich willkommen. - -@menu -* Einführung:: Was ist Guix überhaupt? -* Installation:: Guix installieren. -* Systeminstallation:: Das ganze Betriebssystem installieren. -* Paketverwaltung:: Pakete installieren, aktualisieren usw. -* Development:: Guix-aided software development. -* Programmierschnittstelle:: Guix in Scheme verwenden. -* Zubehör:: Befehle zur Paketverwaltung. -* Systemkonfiguration:: Das Betriebssystem konfigurieren. -* Dokumentation:: Wie man Nutzerhandbücher von Software liest. -* Dateien zur Fehlersuche installieren:: Womit man seinen Debugger - füttert. -* Sicherheitsaktualisierungen:: Sicherheits-Patches schnell einspielen. -* Bootstrapping:: GNU/Linux von Grund auf selbst erstellen. -* Portierung:: Guix auf andere Plattformen und Kernels - bringen. -* Mitwirken:: Ihre Hilfe ist nötig! - -* Danksagungen:: Danke! -* GNU-Lizenz für freie Dokumentation:: Die Lizenz dieses Handbuchs. -* Konzeptverzeichnis:: Konzepte. -* Programmierverzeichnis:: Datentypen, Funktionen und Variable. - -@detailmenu - --- Detaillierte Liste der Knoten --- - - - -Einführung - - - -* Managing Software the Guix Way:: What's special. -* GNU-Distribution:: The packages and tools. - -Installation - - - -* Aus Binärdatei installieren:: Guix installieren, ohne Zeit zu verlieren! -* Voraussetzungen:: Zum Erstellen und Benutzen von Guix nötige - Software. -* Die Testsuite laufen lassen:: Guix testen. -* Den Daemon einrichten:: Wie man die Umgebung des Erstellungs-Daemons - einrichtet. -* Aufruf des guix-daemon:: Den Erstellungs-Daemon laufen lassen. -* Anwendungen einrichten:: Anwendungsspezifische Einstellungen. - -Den Daemon einrichten - - - -* Einrichten der Erstellungsumgebung:: Die isolierte Umgebung zum Erstellen - vorbereiten. -* Auslagern des Daemons einrichten:: Erstellungen auf entfernte Maschinen - auslagern. -* SELinux-Unterstützung:: Wie man eine SELinux-Richtlinie für den Daemon - einrichtet. - -Systeminstallation - - - -* Einschränkungen:: Was Sie erwarten dürfen. -* Hardware-Überlegungen:: Unterstützte Hardware. -* Installation von USB-Stick oder DVD:: Das Installationsmedium - vorbereiten. -* Vor der Installation:: Netzwerkanbindung, Partitionierung etc. -* Fortfahren mit der Installation:: Die Hauptsache. -* Installing Guix in a VM:: Guix System playground. -* Ein Abbild zur Installation erstellen:: Wie ein solches entsteht. - -Paketverwaltung - - - -* Funktionalitäten:: Wie Guix Ihr Leben schöner machen wird. -* Aufruf von guix package:: Pakete installieren, entfernen usw. -* Substitute:: Vorerstelle Binärdateien herunterladen. -* Pakete mit mehreren Ausgaben.:: Ein Quellpaket, mehrere Ausgaben. -* Aufruf von guix gc:: Den Müllsammler laufen lassen. -* Aufruf von guix pull:: Das neueste Guix samt Distribution laden. -* Kanäle:: Die Paketsammlung anpassen. -* Untergeordnete:: Mit einer anderen Version von Guix - interagieren. -* Aufruf von guix describe:: Informationen über Ihre Guix-Version - anzeigen. -* Aufruf von guix archive:: Import und Export von Store-Dateien. - -Substitute - - - -* Offizieller Substitut-Server:: Eine besondere Quelle von Substituten. -* Substitut-Server autorisieren:: Wie man Substitute an- und abschaltet. -* Substitutauthentifizierung:: Wie Guix Substitute verifiziert. -* Proxy-Einstellungen:: Wie Sie Substitute über einen Proxy beziehen. -* Fehler bei der Substitution:: Was passiert, wenn die Substitution - fehlschlägt. -* Vom Vertrauen gegenüber Binärdateien:: Wie können Sie diesem binären - Blob trauen? - -Development - - - -* Aufruf von guix environment:: Entwicklungsumgebungen einrichten. -* Aufruf von guix pack:: Software-Bündel erstellen. - -Programmierschnittstelle - - - -* Paketmodule:: Pakete aus Sicht des Programmierers. -* Pakete definieren:: Wie Sie neue Pakete definieren. -* Erstellungssysteme:: Angeben, wie Pakete erstellt werden. -* Der Store:: Den Paket-Store verändern. -* Ableitungen:: Systemnahe Schnittstelle für Paketableitungen. -* Die Store-Monade:: Rein funktionale Schnittstelle zum Store. -* G-Ausdrücke:: Erstellungsausdrücke verarbeiten. -* Aufruf von guix repl:: Interaktiv an Guix herumbasteln. - -Pakete definieren - - - -* »package«-Referenz:: Der Datentyp für Pakete. -* »origin«-Referenz:: Datentyp für Paketursprünge. - -Zubehör - - - -* Aufruf von guix build:: Pakete aus der Befehlszeile heraus erstellen. -* Aufruf von guix edit:: Paketdefinitionen bearbeiten. -* Aufruf von guix download:: Herunterladen einer Datei und Ausgabe ihres - Hashes. -* Aufruf von guix hash:: Den kryptographischen Hash einer Datei - berechnen. -* Aufruf von guix import:: Paketdefinitionen importieren. -* Aufruf von guix refresh:: Paketdefinitionen aktualisieren. -* Aufruf von guix lint:: Fehler in Paketdefinitionen finden. -* Aufruf von guix size:: Plattenverbrauch profilieren. -* Aufruf von guix graph:: Den Paketgraphen visualisieren. -* Aufruf von guix publish:: Substitute teilen. -* Aufruf von guix challenge:: Die Substitut-Server anfechten. -* Aufruf von guix copy:: Mit einem entfernten Store Dateien austauschen. -* Aufruf von guix container:: Prozesse isolieren. -* Aufruf von guix weather:: Die Verfügbarkeit von Substituten - einschätzen. -* Aufruf von guix processes:: Auflisten der Client-Prozesse - -Aufruf von @command{guix build} - - - -* Gemeinsame Erstellungsoptionen:: Erstellungsoptionen für die meisten - Befehle. -* Paketumwandlungsoptionen:: Varianten von Paketen erzeugen. -* Zusätzliche Erstellungsoptionen:: Optionen spezifisch für »guix - build«. -* Fehlschläge beim Erstellen untersuchen:: Praxiserfahrung bei der - Paketerstellung. - -Systemkonfiguration - - - -* Das Konfigurationssystem nutzen:: Ihr GNU-System anpassen. -* »operating-system«-Referenz:: Details der Betriebssystem-Deklarationen. -* Dateisysteme:: Die Dateisystemeinbindungen konfigurieren. -* Zugeordnete Geräte:: Näheres zu blockorientierten Speichermedien. -* Benutzerkonten:: Benutzerkonten festlegen. -* Locales:: Sprache und kulturelle Konventionen. -* Dienste:: Systemdienste festlegen. -* Setuid-Programme:: Mit Administratorrechten startende Programme. -* X.509-Zertifikate:: HTTPS-Server authentifizieren. -* Name Service Switch:: Den Name Service Switch von libc konfigurieren. -* Initiale RAM-Disk:: Linux-libre hochfahren. -* Bootloader-Konfiguration:: Den Bootloader konfigurieren. -* Aufruf von guix system:: Instanziierung einer Systemkonfiguration. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* Dienste definieren:: Neue Dienstdefinitionen hinzufügen. - -Dienste - - - -* Basisdienste:: Essenzielle Systemdienste. -* Geplante Auftragsausführung:: Der mcron-Dienst. -* Log-Rotation:: Der rottlog-Dienst. -* Netzwerkdienste:: Netzwerkeinrichtung, SSH-Daemon etc. -* X Window:: Grafische Anzeige. -* Druckdienste:: Unterstützung für lokale und entfernte - Drucker. -* Desktop-Dienste:: D-Bus- und Desktop-Dienste. -* Tondienste:: Dienste für ALSA und Pulseaudio. -* Datenbankdienste:: SQL-Datenbanken, Schlüssel-Wert-Speicher etc. -* Mail-Dienste:: IMAP, POP3, SMTP und so weiter. -* Kurznachrichtendienste:: Dienste für Kurznachrichten. -* Telefondienste:: Telefoniedienste. -* Überwachungsdienste:: Dienste zur Systemüberwachung. -* Kerberos-Dienste:: Kerberos-Dienste. -* Web-Dienste:: Web-Server. -* Zertifikatsdienste:: TLS-Zertifikate via Let’s Encrypt. -* DNS-Dienste:: DNS-Daemons. -* VPN-Dienste:: VPN-Daemons. -* Network File System:: Dienste mit Bezug zum Netzwerkdateisystem. -* Kontinuierliche Integration:: Der Cuirass-Dienst. -* Dienste zur Stromverbrauchsverwaltung:: Den Akku schonen. -* Audio-Dienste:: Der MPD. -* Virtualisierungsdienste:: Dienste für virtuelle Maschinen. -* Versionskontrolldienste:: Entfernten Zugang zu Git-Repositorys bieten. -* Spieldienste:: Spielserver. -* Verschiedene Dienste:: Andere Dienste. - -Dienste definieren - - - -* Dienstkompositionen:: Wie Dienste zusammengestellt werden. -* Diensttypen und Dienste:: Typen und Dienste. -* Service-Referenz:: Referenz zur Programmierschnittstelle. -* Shepherd-Dienste:: Eine spezielle Art von Dienst. - -@end detailmenu -@end menu - -@c ********************************************************************* -@node Einführung -@chapter Einführung - -@cindex Zweck -GNU Guix@footnote{``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. - -@cindex Guix System -@cindex GuixSD, now Guix System -@cindex Guix System Distribution, now Guix System -You can install GNU@tie{}Guix on top of an existing GNU/Linux system where -it complements the available tools without interference -(@pxref{Installation}), or you can use it as a standalone operating system -distribution, @dfn{Guix@tie{}System}@footnote{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 @command{guix system} -command, even if you're using a different distro underneath!}. @xref{GNU-Distribution}. - -@menu -* Managing Software the Guix Way:: What's special. -* GNU-Distribution:: The packages and tools. -@end menu - -@node Managing Software the Guix Way -@section Managing Software the Guix Way - -@cindex Benutzeroberflächen -Guix provides a command-line package management interface (@pxref{Paketverwaltung}), tools to help with software development (@pxref{Development}), -command-line utilities for more advanced usage, (@pxref{Zubehör}), as well -as Scheme programming interfaces (@pxref{Programmierschnittstelle}). -@cindex Erstellungs-Daemon -Der @dfn{Erstellungs-Daemon} ist für das Erstellen von Paketen im Auftrag -von Nutzern verantwortlich (@pxref{Den Daemon einrichten}) und für das -Herunterladen vorerstellter Binärdateien aus autorisierten Quellen -(@pxref{Substitute}). - -@cindex Erweiterbarkeit der Distribution -@cindex Anpassung, von Paketen -Guix enthält Paketdefinitionen für viele Pakete, von GNU und nicht von GNU, -die alle @uref{https://www.gnu.org/philosophy/free-sw.html, die Freiheit des -Computernutzers respektieren}. Es ist @emph{erweiterbar}: Nutzer können ihre -eigenen Paketdefinitionen schreiben (@pxref{Pakete definieren}) und sie als -unabhängige Paketmodule verfügbar machen (@pxref{Paketmodule}). Es ist -auch @emph{anpassbar}: Nutzer können spezialisierte Paketdefinitionen aus -bestehenden @emph{ableiten}, auch von der Befehlszeile (@pxref{Paketumwandlungsoptionen}). - -@cindex funktionale Paketverwaltung -@cindex Isolierung -Intern implementiert Guix die Disziplin der @dfn{funktionalen -Paketverwaltung}, zu der Nix schon die Pionierarbeit geleistet hat -(@pxref{Danksagungen}). In Guix wird der Prozess, ein Paket zu erstellen -und zu installieren, als eine @emph{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 @dfn{Container}), wo nur ausdrückliche Eingaben sichtbar sind. - -@cindex Store -Das Ergebnis von Paketerstellungsfunktionen wird im Dateisystem -@dfn{zwischengespeichert} in einem besonderen Verzeichnis, was als @dfn{der -Store} bezeichnet wird (@pxref{Der Store}). Jedes Paket wird in sein eigenes -Verzeichnis im Store installiert — standardmäßig ist er unter -@file{/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 (@pxref{Funktionalitäten}). - - -@node GNU-Distribution -@section GNU-Distribution - -@cindex Guix System -Guix comes with a distribution of the GNU system consisting entirely of free -software@footnote{The term ``free'' here refers to the -@url{http://www.gnu.org/philosophy/free-sw.html,freedom provided to users of -that software}.}. The distribution can be installed on its own -(@pxref{Systeminstallation}), but it is also possible to install Guix as a -package manager on top of an installed GNU/Linux system -(@pxref{Installation}). When we need to distinguish between the two, we -refer to the standalone distribution as Guix@tie{}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 @url{http://www.gnu.org/software/guix/packages,online} -einsehen, oder indem Sie @command{guix package} ausführen (@pxref{Aufruf von guix package}): - -@example -guix package --list-available -@end example - -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: - -@table @code - -@item x86_64-linux -Intel/AMD-@code{x86_64}-Architektur, Linux-Libre als Kernel, - -@item i686-linux -Intel-32-Bit-Architektur (IA-32), Linux-Libre als Kernel, - -@item 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. - -@item 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 -@xref{Mitwirken} steht, wie Sie dabei helfen können! - -@item mips64el-linux -64-Bit-MIPS-Prozessoren, little-endian, insbesondere die Loongson-Reihe, -n32-ABI, mit Linux-Libre als Kernel. - -@end table - -With Guix@tie{}System, you @emph{declare} all aspects of the operating -system configuration and Guix takes care of instantiating the configuration -in a transactional, reproducible, and stateless fashion (@pxref{Systemkonfiguration}). Guix System uses the Linux-libre kernel, the Shepherd -initialization system (@pxref{Einführung,,, shepherd, 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 -@code{mips64el-linux}. - -@noindent -Informationen, wie auf andere Architekturen oder Kernels portiert werden -kann, finden Sie im Abschnitt @pxref{Portierung}. - -Diese Distribution aufzubauen basiert auf Kooperation, und Sie sind herzlich -eingeladen, dabei mitzumachen! Im Abschnitt @xref{Mitwirken} stehen -weitere Informationen, wie Sie uns helfen können. - - -@c ********************************************************************* -@node Installation -@chapter Installation - -@cindex Guix installieren - -@quotation Anmerkung -We recommend the use of this -@uref{https://git.savannah.gnu.org/cgit/guix.git/plain/etc/guix-install.sh, -shell installer script} to install Guix on top of a running GNU/Linux -system, thereafter called a @dfn{foreign distro}.@footnote{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, @pxref{Systeminstallation}.} The script -automates the download, installation, and initial configuration of Guix. It -should be run as the root user. -@end quotation - -@cindex Fremddistribution -@cindex Verzeichnisse auf einer Fremddistribution -When installed on a foreign distro, GNU@tie{}Guix complements the available -tools without interference. Its data lives exclusively in two directories, -usually @file{/gnu/store} and @file{/var/guix}; other files on your system, -such as @file{/etc}, are left untouched. - -Sobald es installiert ist, kann Guix durch Ausführen von @command{guix pull} -aktualisiert werden (@pxref{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. - -@menu -* Aus Binärdatei installieren:: Guix installieren, ohne Zeit zu verlieren! -* Voraussetzungen:: Zum Erstellen und Benutzen von Guix nötige - Software. -* Die Testsuite laufen lassen:: Guix testen. -* Den Daemon einrichten:: Wie man die Umgebung des Erstellungs-Daemons - einrichtet. -* Aufruf des guix-daemon:: Den Erstellungs-Daemon laufen lassen. -* Anwendungen einrichten:: Anwendungsspezifische Einstellungen. -@end menu - -@node Aus Binärdatei installieren -@section Aus Binärdatei installieren - -@cindex Guix aus Binärdateien installieren -@cindex Installations-Skript -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@tie{}tar und Xz verfügbar sind. - -Die Installation läuft so ab: - -@enumerate -@item -@cindex Guix-Binärdatei herunterladen -Laden Sie den binären Tarball von -@indicateurl{https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{System}.tar.xz} -herunter, wobei @var{System} für @code{x86_64-linux} steht, falls Sie es auf -einer Maschine mit @code{x86_64}-Architektur einrichten, auf der bereits der -Linux-Kernel läuft, oder entsprechend für andere Maschinen. - -@c The following is somewhat duplicated in ``System Installation''. -Achten Sie darauf, auch die zugehörige @file{.sig}-Datei herunterzuladen und -verifizieren Sie damit die Authentizität des Tarballs, ungefähr so: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guix-binary-@value{VERSION}.@var{System}.tar.xz.sig -$ gpg --verify guix-binary-@value{VERSION}.@var{System}.tar.xz.sig -@end example - -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: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end authentication part -und den Befehl @code{gpg --verify} erneut ausführen. - -@item -Nun müssen Sie zum Administratornutzer @code{root} wechseln. Abhängig von -Ihrer Distribution müssen Sie dazu etwa @code{su -} oder @code{sudo -i} -ausführen. Danach führen Sie als @code{root}-Nutzer aus: - -@example -# cd /tmp -# tar --warning=no-timestamp -xf \ - guix-binary-@value{VERSION}.@var{System}.tar.xz -# mv var/guix /var/ && mv gnu / -@end example - -Dadurch wird @file{/gnu/store} (@pxref{Der Store}) und @file{/var/guix} -erzeugt. Letzteres enthält ein fertiges Guix-Profil für den -Administratornutzer @code{root} (wie im nächsten Schritt beschrieben). - -Entpacken Sie den Tarball @emph{nicht} auf einem schon funktionierenden -Guix-System, denn es würde seine eigenen essenziellen Dateien überschreiben. - -Die Befehlszeilenoption @code{--warning=no-timestamp} stellt sicher, dass -GNU@tie{}tar nicht vor »unplausibel alten Zeitstempeln« warnt (solche -Warnungen traten bei GNU@tie{}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. - -@item -Machen Sie das Profil als @file{~root/.config/guix/current} verfügbar, wo -@command{guix pull} es aktualisieren kann (@pxref{Aufruf von guix pull}): - -@example -# mkdir -p ~root/.config/guix -# ln -sf /var/guix/profiles/per-user/root/current-guix \ - ~root/.config/guix/current -@end example - -»Sourcen« Sie @file{etc/profile}, um @code{PATH} und andere relevante -Umgebungsvariable zu ergänzen: - -@example -# GUIX_PROFILE="`echo ~root`/.config/guix/current" ; \ - source $GUIX_PROFILE/etc/profile -@end example - -@item -Erzeugen Sie Nutzergruppe und Nutzerkonten für die Erstellungs-Benutzer wie -folgt (@pxref{Einrichten der Erstellungsumgebung}). - -@item -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: - -@c Versions of systemd that supported symlinked service files are not -@c yet widely deployed, so we should suggest that users copy the service -@c files into place. -@c -@c See this thread for more information: -@c http://lists.gnu.org/archive/html/guix-devel/2017-01/msg01199.html - -@example -# cp ~root/.config/guix/current/lib/systemd/system/guix-daemon.service \ - /etc/systemd/system/ -# systemctl start guix-daemon && systemctl enable guix-daemon -@end example - -Wenn Ihre Wirts-Distribution als »init«-System Upstart verwendet: - -@example -# initctl reload-configuration -# cp ~root/.config/guix/current/lib/upstart/system/guix-daemon.conf \ - /etc/init/ -# start guix-daemon -@end example - -Andernfalls können Sie den Daemon immer noch manuell starten, mit: - -@example -# ~root/.config/guix/current/bin/guix-daemon \ - --build-users-group=guixbuild -@end example - -@item -Stellen Sie den @command{guix}-Befehl auch anderen Nutzern Ihrer Maschine -zur Verfügung, zum Beispiel so: - -@example -# mkdir -p /usr/local/bin -# cd /usr/local/bin -# ln -s /var/guix/profiles/per-user/root/current-guix/bin/guix -@end example - -Es ist auch eine gute Idee, die Info-Version dieses Handbuchs ebenso -verfügbar zu machen: - -@example -# mkdir -p /usr/local/share/info -# cd /usr/local/share/info -# for i in /var/guix/profiles/per-user/root/current-guix/share/info/* ; - do ln -s $i ; done -@end example - -Auf diese Art wird, unter der Annahme, dass bei Ihnen -@file{/usr/local/share/info} im Suchpfad eingetragen ist, das Ausführen von -@command{info guix} dieses Handbuch öffnen (@pxref{Other Info Directories,,, -texinfo, GNU Texinfo} hat weitere Details, wie Sie den Info-Suchpfad ändern -können). - -@item -@cindex Substitute, deren Autorisierung -To use substitutes from @code{@value{SUBSTITUTE-SERVER}} or one of its -mirrors (@pxref{Substitute}), authorize them: - -@example -# guix archive --authorize < \ - ~root/.config/guix/current/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@item -Alle Nutzer müssen womöglich ein paar zusätzliche Schritte ausführen, damit -ihre Guix-Umgebung genutzt werden kann, siehe @pxref{Anwendungen einrichten}. -@end enumerate - -Voilà, die Installation ist fertig! - -Sie können nachprüfen, dass Guix funktioniert, indem Sie ein Beispielpaket -in das root-Profil installieren: - -@example -# guix package -i hello -@end example - -Das @code{guix}-Paket muss im Profil von @code{root} installiert bleiben, -damit es nicht vom Müllsammler geholt wird, denn ohne den -@command{guix}-Befehl wären Sie lahmgelegt. Anders gesagt, entfernen Sie -@code{guix} @emph{nicht} mit @code{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: - -@example -make guix-binary.@var{System}.tar.xz -@end example - -@noindent -...@: which, in turn, runs: - -@example -guix pack -s @var{System} --localstatedir \ - --profile-name=current-guix guix -@end example - -Siehe @xref{Aufruf von guix pack} für weitere Informationen zu diesem -praktischen Werkzeug. - -@node Voraussetzungen -@section 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 -@file{README} und @file{INSTALL} im Guix-Quellbaum, um weitere Details zu -erfahren. - -@cindex Offizielle Webpräsenz -GNU Guix is available for download from its website at -@url{https://www.gnu.org/software/guix/}. - -GNU Guix hat folgende Pakete als Abhängigkeiten: - -@itemize -@item @url{http://gnu.org/software/guile/, GNU Guile}, version 2.2.x; -@item @url{https://notabug.org/cwebber/guile-gcrypt, Guile-Gcrypt}, Version -0.1.0 oder neuer, -@item -@uref{http://gnutls.org/, GnuTLS}, im Speziellen dessen Bindungen für Guile -(@pxref{Guile Preparations, how to install the GnuTLS bindings for Guile,, -gnutls-guile, GnuTLS-Guile}), -@item -@uref{https://notabug.org/guile-sqlite3/guile-sqlite3, Guile-SQLite3}, -Version 0.1.0 oder neuer, -@item -@c FIXME: Specify a version number once a release has been made. -@uref{https://gitlab.com/guile-git/guile-git, Guile-Git}, vom August 2017 -oder neuer, -@item @uref{https://savannah.nongnu.org/projects/guile-json/, Guile-JSON}; -@item @url{http://zlib.net, zlib}, -@item @url{http://www.gnu.org/software/make/, GNU Make}. -@end itemize - -Folgende Abhängigkeiten sind optional: - -@itemize -@item -@c Note: We need at least 0.10.2 for 'channel-send-eof'. -Unterstützung für das Auslagern von Erstellungen (@pxref{Auslagern des Daemons einrichten}) und @command{guix copy} (@pxref{Aufruf von guix copy}) hängt von -@uref{https://github.com/artyom-poptsov/guile-ssh, Guile-SSH}, Version -0.10.2 oder neuer, ab. - -@item -Wenn @url{http://www.bzip.org, libbz2} verfügbar ist, kann -@command{guix-daemon} damit Erstellungsprotokolle komprimieren. -@end itemize - -Sofern nicht @code{--disable-daemon} beim Aufruf von @command{configure} -übergeben wurde, benötigen Sie auch folgende Pakete: - -@itemize -@item @url{http://gnupg.org/, GNU libgcrypt}, -@item @url{http://sqlite.org, SQLite 3}, -@item @url{http://gcc.gnu.org, GCC's g++} mit Unterstützung für den -C++11-Standard. -@end itemize - -@cindex Zustandsverzeichnis -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 @code{--localstatedir} des @command{configure}-Skripts -(@pxref{Directory Variables, @code{localstatedir},, standards, GNU Coding -Standards}). Das @command{configure}-Skript schützt vor ungewollter -Fehlkonfiguration der @var{localstatedir}, damit sie nicht versehentlich -Ihren Store verfälschen (@pxref{Der Store}). - -@cindex Nix, Kompatibilität -Wenn eine funktionierende Installation of @url{http://nixos.org/nix/, the -Nix package manager} verfügbar ist, können Sie Guix stattdessen mit -@code{--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 @command{configure} nicht nur denselben -Wert für @code{--with-store-dir} übergeben, sondern auch denselben Wert für -@code{--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 -@code{--with-store-dir=/nix/store} und -@code{--localstatedir=/nix/var}. Beachten Sie, dass @code{--disable-daemon} -nicht erforderlich ist, wenn Sie die Absicht haben, den Store mit Nix zu -teilen. - -@node Die Testsuite laufen lassen -@section Die Testsuite laufen lassen - -@cindex Testkatalog -Nachdem @command{configure} und @code{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: - -@example -make check -@end example - -Testfälle können parallel ausgeführt werden. Sie können die -Befehlszeiltenoption @code{-j} von GNU@tie{}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 @code{TESTS}-Variable des Makefiles ähnlich wie in diesem Beispiel -definieren: - -@example -make check TESTS="tests/store.scm tests/cpio.scm" -@end example - -Standardmäßig werden Testergebnisse pro Datei angezeigt. Um die Details -jedes einzelnen Testfalls zu sehen, können Sie wie in diesem Beispiel die -@code{SCM_LOG_DRIVER_FLAGS}-Variable des Makefiles definieren: - -@example -make check TESTS="tests/base64.scm" SCM_LOG_DRIVER_FLAGS="--brief=no" -@end example - -Kommt es zum Fehlschlag, senden Sie bitte eine E-Mail an -@email{bug-guix@@gnu.org} und fügen Sie die Datei @file{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 -(@pxref{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: - -@example -make check-system -@end example - -@noindent -Oder, auch hier, indem Sie @code{TESTS} definieren, um eine Teilmenge der -auszuführenden Tests anzugeben: - -@example -make check-system TESTS="basic mcron" -@end example - -Diese Systemtests sind in den @code{(gnu tests @dots{})}-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 -(@pxref{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 -@email{bug-guix@@gnu.org}. - -@node Den Daemon einrichten -@section Den Daemon einrichten - -@cindex Daemon -Operationen wie das Erstellen eines Pakets oder Laufenlassen des -Müllsammlers werden alle durch einen spezialisierten Prozess durchgeführt, -den @dfn{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 -@command{guix package} und @command{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 @ref{Substitute} für -Informationen darüber, wie Sie es dem Daemon ermöglichen, vorerstellte -Binärdateien herunterzuladen. - -@menu -* Einrichten der Erstellungsumgebung:: Die isolierte Umgebung zum Erstellen - vorbereiten. -* Auslagern des Daemons einrichten:: Erstellungen auf entfernte Maschinen - auslagern. -* SELinux-Unterstützung:: Wie man eine SELinux-Richtlinie für den Daemon - einrichtet. -@end menu - -@node Einrichten der Erstellungsumgebung -@subsection Einrichten der Erstellungsumgebung - -@cindex Erstellungsumgebung -In einem normalen Mehrbenutzersystem werden Guix und sein Daemon — das -Programm @command{guix-daemon} — vom Systemadministrator installiert; -@file{/gnu/store} gehört @code{root} und @command{guix-daemon} läuft als -@code{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. - -@cindex Erstellungsbenutzer -Wenn @command{guix-daemon} als Administratornutzer @code{root} läuft, wollen -Sie aber vielleicht dennoch nicht, dass Paketerstellungsprozesse auch als -@code{root} ablaufen, aus offensichtlichen Sicherheitsgründen. Um dies zu -vermeiden, sollte ein besonderer Pool aus @dfn{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 @code{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 -(@pxref{Einführung}). - -Auf einem GNU/Linux-System kann ein Pool von Erstellungsbenutzern wie folgt -erzeugt werden (mit Bash-Syntax und den Befehlen von @code{shadow}): - -@c See http://lists.gnu.org/archive/html/bug-guix/2013-01/msg00239.html -@c for why `-G' is needed. -@example -# groupadd --system guixbuild -# for i in `seq -w 1 10`; - do - useradd -g guixbuild -G guixbuild \ - -d /var/empty -s `which nologin` \ - -c "Guix-Erstellungsbenutzer $i" --system \ - guixbuilder$i; - done -@end example - -@noindent -Die Anzahl der Erstellungsbenutzer entscheidet, wieviele Erstellungsaufträge -parallel ausgeführt werden können, wie es mit der Befehlszeilenoption -@option{--max-jobs} vorgegeben werden kann (@pxref{Aufruf des guix-daemon, -@option{--max-jobs}}). Um @command{guix system vm} und ähnliche Befehle -nutzen zu können, müssen Sie die Erstellungsbenutzer unter Umständen zur -@code{kvm}-Benutzergruppe hinzufügen, damit sie Zugriff auf @file{/dev/kvm} -haben, mit @code{-G guixbuild,kvm} statt @code{-G guixbuild} -(@pxref{Aufruf von guix system}). - -Das Programm @code{guix-daemon} kann mit dem folgenden Befehl als -@code{root} gestartet werden@footnote{Wenn Ihre Maschine systemd als -»init«-System verwendet, genügt es, die Datei -@file{@var{prefix}/lib/systemd/system/guix-daemon.service} in -@file{/etc/systemd/system} zu platzieren, damit @command{guix-daemon} -automatisch gestartet wird. Ebenso können Sie, wenn Ihre Maschine Upstart -als »init«-System benutzt, die Datei -@file{@var{prefix}/lib/upstart/system/guix-daemon.conf} in @file{/etc/init} -platzieren.}: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@cindex chroot -@noindent -Auf diese Weise startet der Daemon Erstellungsprozesse in einem chroot als -einer der @code{guixbuilder}-Benutzer. Auf GNU/Linux enthält die -chroot-Umgebung standardmäßig nichts außer: - -@c Keep this list in sync with libstore/build.cc! ----------------------- -@itemize -@item -einem minimalen @code{/dev}-Verzeichnis, was größtenteils vom @code{/dev} -des Wirtssystems unabhängig erstellt wurde@footnote{»Größtenteils«, denn -obwohl die Menge an Dateien, die im @code{/dev} des chroots vorkommen, fest -ist, können die meisten dieser Dateien nur dann erstellt werden, wenn das -Wirtssystem sie auch hat.}, - -@item -dem @code{/proc}-Verzeichnis, es zeigt nur die Prozesse des Containers, weil -ein separater Namensraum für Prozess-IDs (PIDs) benutzt wird, - -@item -@file{/etc/passwd} mit einem Eintrag für den aktuellen Benutzer und einem -Eintrag für den Benutzer @file{nobody}, - -@item -@file{/etc/group} mit einem Eintrag für die Gruppe des Benutzers, - -@item -@file{/etc/hosts} mit einem Eintrag, der @code{localhost} auf -@code{127.0.0.1} abbildet, - -@item -einem @file{/tmp}-Verzeichnis mit Schreibrechten. -@end itemize - -Sie können beeinflussen, in welchem Verzeichnis der Daemon Erstellungsbäume -unterbringt, indem sie den Wert der Umgebungsvariablen @code{TMPDIR} -ändern. Allerdings heißt innerhalb des chroots der Erstellungsbaum immer -@file{/tmp/guix-build-@var{name}.drv-0}, wobei @var{name} der Ableitungsname -ist — z.B. @code{coreutils-8.24}. Dadurch hat der Wert von @code{TMPDIR} -keinen Einfluss auf die Erstellungsumgebung, wodurch Unterschiede vermieden -werden, falls Erstellungsprozesse den Namen ihres Erstellungsbaumes -einfangen. - -@vindex http_proxy -Der Daemon befolgt außerdem den Wert der Umgebungsvariablen -@code{http_proxy} für von ihm durchgeführte HTTP-Downloads, sei es für -Ableitungen mit fester Ausgabe (@pxref{Ableitungen}) oder für Substitute -(@pxref{Substitute}). - -Wenn Sie Guix als ein Benutzer ohne erweiterte Rechte installieren, ist es -dennoch möglich, @command{guix-daemon} auszuführen, sofern Sie -@code{--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 @emph{reine} -Funktionen aufzufassen. - - -@node Auslagern des Daemons einrichten -@subsection Nutzung der Auslagerungsfunktionalität - -@cindex auslagern -@cindex Build-Hook -Wenn erwünscht kann der Erstellungs-Daemon Ableitungserstellungen -@dfn{auslagern} auf andere Maschinen, auf denen Guix läuft, mit Hilfe des -@code{offload}-»@dfn{Build-Hooks}«@footnote{Diese Funktionalität ist nur -verfügbar, wenn @uref{https://github.com/artyom-poptsov/guile-ssh, -Guile-SSH} vorhanden ist.}. Wenn diese Funktionalität aktiviert ist, wird -eine nutzerspezifizierte Liste von Erstellungsmaschinen aus -@file{/etc/guix/machines.scm} gelesen. Wann immer eine Erstellung angefragt -wird, zum Beispiel durch @code{guix build}, versucht der Daemon, sie an eine -der Erstellungsmaschinen auszulagern, die die Einschränkungen der Ableitung -erfüllen, insbesondere ihren Systemtyp — z.B. @file{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 @file{/etc/guix/machines.scm} sieht normalerweise so aus: - -@example -(list (build-machine - (name "eightysix.example.org") - (system "x86_64-linux") - (host-key "ssh-ed25519 AAAAC3Nza@dots{}") - (user "bob") - (speed 2.)) ;unglaublich schnell! - - (build-machine - (name "meeps.example.org") - (system "mips64el-linux") - (host-key "ssh-rsa AAAAB3Nza@dots{}") - (user "alice") - (private-key - (string-append (getenv "HOME") - "/.ssh/identität-für-guix")))) -@end example - -@noindent -Im obigen Beispiel geben wir eine Liste mit zwei Erstellungsmaschinen vor, -eine für die @code{x86_64}-Architektur und eine für die -@code{mips64el}-Architektur. - -Tatsächlich ist diese Datei — wenig überraschend! — eine Scheme-Datei, die -ausgewertet wird, wenn der @code{offload}-Hook gestartet wird. Der Wert, den -sie zurückliefert, muss eine Liste von @code{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 -(@pxref{Einführung, Guile-Avahi,, guile-avahi, Using Avahi in Guile Scheme -Programs}). Der Datentyp @code{build-machine} wird im Folgenden weiter -ausgeführt. - -@deftp {Datentyp} build-machine -Dieser Datentyp repräsentiert Erstellungsmaschinen, an die der Daemon -Erstellungen auslagern darf. Die wichtigen Felder sind: - -@table @code - -@item name -Der Hostname (d.h. der Rechnername) der entfernten Maschine. - -@item system -Der Systemtyp der entfernten Maschine — z.B. @code{"x86_64-linux"}. - -@item user -Das Benutzerkonto, mit dem eine Verbindung zur entfernten Maschine über SSH -aufgebaut werden soll. Beachten Sie, dass das SSH-Schlüsselpaar @emph{nicht} -durch eine Passphrase geschützt sein darf, damit nicht-interaktive -Anmeldungen möglich sind. - -@item host-key -Dies muss der @dfn{ö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: - -@example -ssh-ed25519 AAAAC3NzaC@dots{}mde+UhL hint@@example.org -@end example - -Wenn auf der Maschine der OpenSSH-Daemon, @command{sshd}, läuft, ist der -Host-Schlüssel in einer Datei wie @file{/etc/ssh/ssh_host_ed25519_key.pub} -zu finden. - -Wenn auf der Maschine der SSH-Daemon von GNU@tie{}lsh, nämlich -@command{lshd}, läuft, befindet sich der Host-Schlüssel in -@file{/etc/lsh/host-key.pub} oder einer ähnlichen Datei. Er kann ins -OpenSSH-Format umgewandelt werden durch @command{lsh-export-key} -(@pxref{Converting keys,,, lsh, LSH Manual}): - -@example -$ lsh-export-key --openssh < /etc/lsh/host-key.pub -ssh-rsa AAAAB3NzaC1yc2EAAAAEOp8FoQAAAQEAs1eB46LV@dots{} -@end example - -@end table - -Eine Reihe optionaler Felder kann festgelegt werden: - -@table @asis - -@item @code{port} (Vorgabe: @code{22}) -Portnummer des SSH-Servers auf der Maschine. - -@item @code{private-key} (Vorgabe: @file{~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 @emph{des -root-Benutzers} genommen wird. Vergewissern Sie sich, dass er existiert, -wenn Sie die Standardeinstellung verwenden. - -@item @code{compression} (Vorgabe: @code{"zlib@@openssh.com,zlib"}) -@itemx @code{compression-level} (Vorgabe: @code{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. - -@item @code{daemon-socket} (Vorgabe: @code{"/var/guix/daemon-socket/socket"}) -Dateiname des Unix-Sockets, auf dem @command{guix-daemon} auf der Maschine -lauscht. - -@item @code{parallel-builds} (Vorgabe: @code{1}) -Die Anzahl der Erstellungen, die auf der Maschine parallel ausgeführt werden -können. - -@item @code{speed} (Vorgabe: @code{1.0}) -Ein »relativer Geschwindigkeitsfaktor«. Der Auslagerungsplaner gibt -tendenziell Maschinen mit höherem Geschwindigkeitsfaktor den Vorrang. - -@item @code{features} (Vorgabe: @code{'()}) -Eine Liste von Zeichenketten, die besondere von der Maschine unterstützte -Funktionalitäten bezeichnen. Ein Beispiel ist @code{"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. - -@end table -@end deftp - -The @command{guix} command must be in the search path on the build -machines. You can check whether this is the case by running: - -@example -ssh build-machine guix repl --version -@end example - -Es gibt noch eine weitere Sache zu tun, sobald @file{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 -(@pxref{Aufruf von guix archive}): - -@example -# guix archive --generate-key -@end example - -@noindent -Jede Erstellungsmaschine muss den Schlüssel der Hauptmaschine autorisieren, -damit diese Store-Objekte von der Hauptmaschine empfangen kann: - -@example -# guix archive --authorize < öffentlicher-schlüssel-hauptmaschine.txt -@end example - -@noindent -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. - -@cindex Auslagerung testen -Um zu testen, ob Ihr System funktioniert, führen Sie diesen Befehl auf der -Hauptmaschine aus: - -@example -# guix offload test -@end example - -Dadurch wird versucht, zu jeder Erstellungsmaschine eine Verbindung -herzustellen, die in @file{/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: - -@example -# guix offload test maschinen-qualif.scm -@end example - -Letztendlich können Sie hiermit nur die Teilmenge der Maschinen testen, -deren Name zu einem regulären Ausdruck passt: - -@example -# guix offload test maschinen.scm '\.gnu\.org$' -@end example - -@cindex Auslagerungs-Lagebericht -Um die momentane Auslastung aller Erstellungs-Hosts anzuzeigen, führen Sie -diesen Befehl auf dem Hauptknoten aus: - -@example -# guix offload status -@end example - - -@node SELinux-Unterstützung -@subsection SELinux-Unterstützung - -@cindex SELinux, Policy für den Daemon -@cindex Mandatory Access Control, SELinux -@cindex Sicherheit, des guix-daemon -Guix includes an SELinux policy file at @file{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. - -@subsubsection Installieren der SELinux-Policy -@cindex SELinux, Policy installieren -Um die Richtlinie (Policy) zu installieren, führen Sie folgenden Befehl mit -Administratorrechten aus: - -@example -semodule -i etc/guix-daemon.cil -@end example - -Kennzeichnen Sie dann das Dateisystem neu mit @code{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 -@code{guix_daemon_t} laufen. Sie können dies mit dem folgenden Befehl -nachprüfen: - -@example -ps -Zax | grep guix-daemon -@end example - -Beobachten Sie die Protokolldateien von SELinux, wenn Sie einen Befehl wie -@code{guix build hello} ausführen, um sich zu überzeugen, dass SELinux alle -notwendigen Operationen gestattet. - -@subsubsection Einschränkungen -@cindex SELinux, 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. - -@enumerate -@item -@code{guix_daemon_socket_t} wird nicht wirklich benutzt. Keine der -Socket-Operationen benutzt Kontexte, die irgendetwas mit -@code{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. - -@item -@code{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 @code{user_home_t}, aber Verknüpfungen aus -dem Persönlichen Verzeichnis des Administratornutzers, oder @file{/tmp}, -oder das Arbeitsverzeichnis des HTTP-Servers, etc., funktioniert das -nicht. @code{guix gc} würde es nicht gestattet, diese Verknüpfungen -auszulesen oder zu verfolgen. - -@item -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. - -@item -Derzeit wird allen Dateien mit einem Namen, der zum regulären Ausdruck -@code{/gnu/store/.+-(guix-.+|profile)/bin/guix-daemon} passt, die -Kennzeichnung @code{guix_daemon_exec_t} zugewiesen, wodurch @emph{jede -beliebige} Datei mit diesem Namen in irgendeinem Profil gestattet wäre, in -der Domäne @code{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 @code{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 @emph{genau derselbe} Dateiname des -gerade installierten @code{guix-daemon}-Programms als -@code{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 -@code{guix-daemon}-Programm enthält. -@end enumerate - -@node Aufruf des guix-daemon -@section Aufruf von @command{guix-daemon} - -Das Programm @command{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 -(@code{root}) gestartet: - -@example -# guix-daemon --build-users-group=guixbuild -@end example - -@noindent -Details, wie Sie ihn einrichten, finden Sie im Abschnitt @pxref{Den Daemon einrichten}. - -@cindex chroot -@cindex Container, Erstellungsumgebung -@cindex Erstellungsumgebung -@cindex Reproduzierbare Erstellungen -Standardmäßig führt @command{guix-daemon} Erstellungsprozesse mit -unterschiedlichen UIDs aus, die aus der Erstellungsgruppe stammen, deren -Name mit @code{--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 (@pxref{Programmierschnittstelle, derivation}), und ein paar -bestimmte Systemverzeichnisse, darunter standardmäßig auch @file{/dev} und -@file{/dev/pts}. Zudem ist die Erstellungsumgebung auf GNU/Linux ein -@dfn{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 (@pxref{Funktionalitäten}). - -Wenn der Daemon im Auftrag des Nutzers eine Erstellung durchführt, erzeugt -er ein Erstellungsverzeichnis, entweder in @file{/tmp} oder im Verzeichnis, -das durch die Umgebungsvariable @code{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 -@option{--keep-failed} angegeben hat (@pxref{Aufruf von guix build, -@option{--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 -@command{guix}-Unterbefehle.) Der Befehl @command{guix processes} zeigt -Ihnen eine Übersicht solcher Systemaktivitäten; damit werden Ihnen alle -aktiven Sitzungen und Clients gezeigt. Weitere Informationen finden Sie -unter @xref{Aufruf von guix processes}. - -Die folgenden Befehlszeilenoptionen werden unterstützt: - -@table @code -@item --build-users-group=@var{Gruppe} -Verwende die Benutzerkonten aus der @var{Gruppe}, um Erstellungsprozesse -auszuführen (@pxref{Den Daemon einrichten, build users}). - -@item --no-substitutes -@cindex Substitute -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 (@pxref{Substitute}). - -Wenn der Daemon mit @code{--no-substitutes} ausgeführt wird, können Clients -trotzdem Substitute explizit aktivieren über den entfernten Prozeduraufruf -@code{set-build-options} (@pxref{Der Store}). - -@item --substitute-urls=@var{URLs} -@anchor{daemon-substitute-urls} -Consider @var{urls} the default whitespace-separated list of substitute -source URLs. When this option is omitted, -@indicateurl{https://@value{SUBSTITUTE-SERVER}} is used. - -Das hat zur Folge, dass Substitute von den @var{URLs} heruntergeladen werden -können, solange sie mit einer Signatur versehen sind, der vertraut wird -(@pxref{Substitute}). - -@cindex Build-Hook -@item --no-build-hook -Den »@dfn{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 (@pxref{Auslagern des Daemons einrichten}). - -@item --cache-failures -Fehler bei der Erstellung zwischenspeichern. Normalerweise werden nur -erfolgreiche Erstellungen gespeichert. - -Wenn diese Befehlszeilenoption benutzt wird, kann @command{guix gc ---list-failures} benutzt werden, um die Menge an Store-Objekten abzufragen, -die als Fehlschläge markiert sind; @command{guix gc --clear-failures} -entfernt Store-Objekte aus der Menge zwischengespeicherter -Fehlschläge. @xref{Aufruf von guix gc}. - -@item --cores=@var{n} -@itemx -c @var{n} -@var{n} CPU-Kerne zum Erstellen jeder Ableitung benutzen; @code{0} heißt, so -viele wie verfügbar sind. - -Der Vorgabewert ist @code{0}, jeder Client kann jedoch eine abweichende -Anzahl vorgeben, zum Beispiel mit der Befehlszeilenoption @code{--cores} von -@command{guix build} (@pxref{Aufruf von guix build}). - -Dadurch wird die Umgebungsvariable @code{NIX_BUILD_CORES} im -Erstellungsprozess definiert, welcher sie benutzen kann, um intern parallele -Ausführungen zuzulassen — zum Beispiel durch Nutzung von @code{make --j$NIX_BUILD_CORES}. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Höchstenss @var{n} Erstellungsaufträge parallel bearbeiten. Der Vorgabewert -liegt bei @code{1}. Wird er auf @code{0} gesetzt, werden keine Erstellungen -lokal durchgeführt, stattdessen lagert der Daemon sie nur aus (@pxref{Auslagern des Daemons einrichten}) oder sie schlagen einfach fehl. - -@item --max-silent-time=@var{Sekunden} -Wenn der Erstellungs- oder Substitutionsprozess länger als -@var{Sekunden}-lang keine Ausgabe erzeugt, wird er abgebrochen und ein -Fehler beim Erstellen gemeldet. - -Der Vorgabewert ist @code{0}, was bedeutet, dass es keine Zeitbeschränkung -gibt. - -Clients können einen anderen Wert als den hier angegebenen verwenden lassen -(@pxref{Gemeinsame Erstellungsoptionen, @code{--max-silent-time}}). - -@item --timeout=@var{Sekunden} -Entsprechend wird hier der Erstellungs- oder Substitutionsprozess -abgebrochen und als Fehlschlag gemeldet, wenn er mehr als -@var{Sekunden}-lang dauert. - -Der Vorgabewert ist @code{0}, was bedeutet, dass es keine Zeitbeschränkung -gibt. - -Clients können einen anderen Wert verwenden lassen (@pxref{Gemeinsame Erstellungsoptionen, @code{--timeout}}). - -@item --rounds=@var{N} -Jede Ableitung @var{n}-mal hintereinander erstellen und einen Fehler melden, -wenn nacheinander ausgewertete Erstellungsergebnisse nicht Bit für Bit -identisch sind. Beachten Sie, dass Clients wie @command{guix build} einen -anderen Wert verwenden lassen können (@pxref{Aufruf von guix build}). - -Wenn dies zusammen mit @option{--keep-failed} benutzt wird, bleiben die sich -unterscheidenden Ausgaben im Store unter dem Namen -@file{/gnu/store/@dots{}-check}. Dadurch können Unterschiede zwischen den -beiden Ergebnissen leicht erkannt werden. - -@item --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 @code{--verbosity} von @command{guix build} -(@pxref{Aufruf von guix build}). - -@item --chroot-directory=@var{Verzeichnis} -Füge das @var{Verzeichnis} zum chroot von Erstellungen hinzu. - -Dadurch kann sich das Ergebnis von Erstellungsprozessen ändern — zum -Beispiel, wenn diese optionale Abhängigkeiten aus dem @var{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. - -@item --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 @command{guix-daemon} -auf einem Benutzerkonto ohne ausreichende Berechtigungen ausgeführt wird. - -@item --log-compression=@var{Typ} -Erstellungsprotokolle werden entsprechend dem @var{Typ} komprimiert, der -entweder @code{gzip}, @code{bzip2} oder @code{none} (für keine Kompression) -sein muss. - -Sofern nicht @code{--lose-logs} angegeben wurde, werden alle -Erstellungsprotokolle in der @var{localstatedir} gespeichert. Um Platz zu -sparen, komprimiert sie der Daemon standardmäßig automatisch mit bzip2. - -@item --disable-deduplication -@cindex Deduplizieren -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. - -@item --gc-keep-outputs[=yes|no] -Gibt an, ob der Müllsammler (Garbage Collector, GC) die Ausgaben lebendiger -Ableitungen behalten muss (»yes«) oder nicht (»no«). - -@cindex GC-Wurzeln -@cindex Müllsammlerwurzeln -Für »yes« behält der Müllsammler die Ausgaben aller lebendigen Ableitungen -im Store — die @code{.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 @xref{Aufruf von guix gc} für weitere Informationen zu Müllsammlerwurzeln. - -@item --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. @code{.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 @code{--gc-keep-derivations} auf »yes« -steht, die Lebendigkeit von Ausgaben auf Ableitungen, und wenn -@code{--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. - -@item --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 -@code{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. - -@item --lose-logs -Keine Protokolle der Erstellungen vorhalten. Normalerweise würden solche in -@code{@var{localstatedir}/guix/log} gespeichert. - -@item --system=@var{System} -Verwende @var{System} als aktuellen Systemtyp. Standardmäßig ist dies das -Paar aus Befehlssatz und Kernel, welches beim Aufruf von @code{configure} -erkannt wurde, wie zum Beispiel @code{x86_64-linux}. - -@item --listen=@var{Endpunkt} -Lausche am @var{Endpunkt} auf Verbindungen. Dabei wird der @var{Endpunkt} -als Dateiname eines Unix-Sockets verstanden, wenn er mit einem @code{/} -(Schrägstrich) beginnt. Andernfalls wird der @var{Endpunkt} als Hostname -(d.h. Rechnername) oder als Hostname-Port-Paar verstanden, auf dem gelauscht -wird. Hier sind ein paar Beispiele: - -@table @code -@item --listen=/gnu/var/daemon -Lausche auf Verbindungen am Unix-Socket @file{/gnu/var/daemon}, falls nötig -wird er dazu erstellt. - -@item --listen=localhost -@cindex Daemon, Fernzugriff -@cindex Fernzugriff auf den Daemon -@cindex Daemon, Einrichten auf Clustern -@cindex Cluster, Einrichtung des Daemons -Lausche auf TCP-Verbindungen an der Netzwerkschnittstelle, die -@code{localhost} entspricht, auf Port 44146. - -@item --listen=128.0.0.42:1234 -Lausche auf TCP-Verbindungen an der Netzwerkschnittstelle, die -@code{128.0.0.42} entspricht, auf Port 1234. -@end table - -Diese Befehlszeilenoption kann mehrmals wiederholt werden. In diesem Fall -akzeptiert @command{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 -@code{GUIX_DAEMON_SOCKET} festlegen (@pxref{Der Store, -@code{GUIX_DAEMON_SOCKET}}). - -@quotation Anmerkung -Das Daemon-Protokoll ist @emph{weder authentifiziert noch -verschlüsselt}. Die Benutzung von @code{--listen=@var{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. -@end quotation - -Wird @code{--listen} nicht angegeben, lauscht @command{guix-daemon} auf -Verbindungen auf dem Unix-Socket, der sich unter -@file{@var{localstatedir}/guix/daemon-socket/socket} befindet. -@end table - - -@node Anwendungen einrichten -@section Anwendungen einrichten - -@cindex Fremddistribution -When using Guix on top of GNU/Linux distribution other than Guix System---a -so-called @dfn{foreign distro}---a few additional steps are needed to get -everything in place. Here are some of them. - -@subsection Locales - -@anchor{locales-and-locpath} -@cindex locales, when not on Guix System -@vindex LOCPATH -@vindex GUIX_LOCPATH -Ü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 @code{GUIX_LOCPATH} passend festlegen: - -@example -$ guix package -i glibc-locales -$ export GUIX_LOCPATH=$HOME/.guix-profile/lib/locale -@end example - -Beachten Sie, dass das Paket @code{glibc-locales} Daten für alle von -GNU@tie{}libc unterstützten Locales enthält und deswegen um die 110@tie{}MiB -wiegt. Alternativ gibt es auch @code{glibc-utf8-locales}, was kleiner, aber -auf ein paar UTF-8-Locales beschränkt ist. - -Die Variable @code{GUIX_LOCPATH} spielt eine ähnliche Rolle wie -@code{LOCPATH} (@pxref{Locale Names, @code{LOCPATH},, libc, The GNU C -Library Reference Manual}). Es gibt jedoch zwei wichtige Unterschiede: - -@enumerate -@item -@code{GUIX_LOCPATH} wird nur von der libc in Guix beachtet und nicht der von -Fremddistributionen bereitgestellten libc. Mit @code{GUIX_LOCPATH} können -Sie daher sicherstellen, dass die Programme der Fremddistribution keine -inkompatiblen Locale-Daten von Guix laden. - -@item -libc hängt an jeden @code{GUIX_LOCPATH}-Eintrag @code{/X.Y} an, wobei -@code{X.Y} die Version von libc ist — z.B. @code{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. -@end enumerate - -Das ist wichtig, weil das Locale-Datenformat verschiedener libc-Versionen -inkompatibel sein könnte. - -@subsection Name Service Switch - -@cindex Name Service Switch, glibc -@cindex NSS (Name Service Switch), glibc -@cindex nscd (Name Service Caching Daemon) -@cindex Name Service Caching Daemon (nscd) -Wenn Sie Guix auf einer Fremddistribution verwenden, @emph{empfehlen wir -stärkstens}, dass Sie den @dfn{Name Service Cache Daemon} der -GNU-C-Bibliothek, @command{nscd}, laufen lassen, welcher auf dem Socket -@file{/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. - -@cindex @file{nsswitch.conf} -Die GNU-C-Bibliothek implementiert einen @dfn{Name Service Switch} (NSS), -welcher einen erweiterbaren Mechanismus zur allgemeinen »Namensauflösung« -darstellt: Hostnamensauflösung, Benutzerkonten und weiteres (@pxref{Name Service Switch,,, libc, The GNU C Library Reference Manual}). - -@cindex Network Information Service (NIS) -@cindex NIS (Network Information Service) -Für die Erweiterbarkeit unterstützt der NSS @dfn{Plugins}, welche neue -Implementierungen zur Namensauflösung bieten: Zum Beispiel ermöglicht das -Plugin @code{nss-mdns} die Namensauflösung für @code{.local}-Hostnamen, das -Plugin @code{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 -@file{/etc/nsswitch.conf} und alle auf dem System laufenden Programme halten -sich an diese Einstellungen (@pxref{NSS Configuration File,,, libc, The GNU -C Reference Manual}). - -Wenn sie eine Namensauflösung durchführen — zum Beispiel, indem sie die -@code{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 @file{libnss_*.so}-Dateien — werden mit @code{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 @code{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 @command{nscd} auf dem System wird, neben anderen -Vorteilen, dieses Problem der binären Inkompatibilität vermieden, weil diese -@code{libnss_*.so}-Dateien vom @command{nscd}-Prozess geladen werden, nicht -in den Anwendungen selbst. - -@subsection X11-Schriftarten - -@cindex Schriftarten -Die Mehrheit der grafischen Anwendungen benutzen Fontconfig zum Finden und -Laden von Schriftarten und für die Darstellung im X11-Client. Im Paket -@code{fontconfig} in Guix werden Schriftarten standardmäßig in -@file{$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 @code{gs-fonts}, @code{font-dejavu} und -@code{font-gnu-freefont-ttf}. - -Um auf Chinesisch, Japanisch oder Koreanisch verfassten Text in grafischen -Anwendungen anzeigen zu können, möchten Sie vielleicht -@code{font-adobe-source-han-sans} oder @code{font-wqy-zenhei} -installieren. Ersteres hat mehrere Ausgaben, für jede Sprachfamilie eine -(@pxref{Pakete mit mehreren Ausgaben.}). Zum Beispiel installiert folgender -Befehl Schriftarten für chinesische Sprachen: - -@example -guix package -i font-adobe-source-han-sans:cn -@end example - -@cindex @code{xterm} -Ältere Programme wie @command{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: - -@example --*-dejavu sans-medium-r-normal-*-*-100-*-*-*-*-*-1 -@end example - -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: - -@c Note: 'xset' does not accept symlinks so the trick below arranges to -@c get at the real directory. See <https://bugs.gnu.org/30655>. -@example -xset +fp $(dirname $(readlink -f ~/.guix-profile/share/fonts/truetype/fonts.dir)) -@end example - -@cindex @code{xlsfonts} -Danach können Sie den Befehl @code{xlsfonts} ausführen (aus dem Paket -@code{xlsfonts}), um sicherzustellen, dass dort Ihre TrueType-Schriftarten -aufgeführt sind. - -@cindex @code{fc-cache} -@cindex Font-Cache -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 @code{fc-cache -f} aus. Der Befehl -@code{fc-cache} wird vom Paket @code{fontconfig} angeboten. - -@subsection X.509-Zertifikate - -@cindex @code{nss-certs} -Das Paket @code{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 @xref{X.509-Zertifikate} stehen -genaue Informationen. - -@subsection Emacs-Pakete - -@cindex @code{emacs} -Wenn Sie mit Guix Pakete für Emacs installieren, werden deren elisp-Dateien -entweder in @file{$HOME/.guix-profile/share/emacs/site-lisp/} oder in -Unterverzeichnissen von -@file{$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 -(@pxref{Package Files,,, emacs, 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 -@code{--no-site-file} starten (@pxref{Init File,,, emacs, The GNU Emacs -Manual}). - -@subsection GCC-Toolchain - -@cindex GCC -@cindex ld-wrapper - -Guix bietet individuelle Compiler-Pakete wie etwa @code{gcc}, aber wenn Sie -einen vollständigen Satz an Werkzeugen zum Kompilieren und Binden von -Quellcode brauchen, werden Sie eigentlich das Paket @code{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 @code{debug}-Ausgabe), Binutils und einen Wrapper für den Binder/Linker. - -The wrapper's purpose is to inspect the @code{-L} and @code{-l} switches -passed to the linker, add corresponding @code{-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 -@code{GUIX_LD_WRAPPER_ALLOW_IMPURITIES} environment variable to @code{no}. - -@c TODO What else? - -@c ********************************************************************* -@node Systeminstallation -@chapter Systeminstallation - -@cindex installing Guix System -@cindex Guix System, installation -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, -@pxref{Installation}. - -@ifinfo -@quotation Anmerkung -@c This paragraph is for people reading this from tty2 of the -@c installation image. -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: @pxref{Top, Info -reader,, info-stnd, Stand-alone GNU Info}. Drücken Sie danach @kbd{l}, um -hierher zurückzukommen. - -Führen Sie alternativ @command{info info} auf einer anderen Konsole (tty) -aus, um dieses Handbuch offen zu lassen. -@end quotation -@end ifinfo - -@menu -* Einschränkungen:: Was Sie erwarten dürfen. -* Hardware-Überlegungen:: Unterstützte Hardware. -* Installation von USB-Stick oder DVD:: Das Installationsmedium - vorbereiten. -* Vor der Installation:: Netzwerkanbindung, Partitionierung etc. -* Fortfahren mit der Installation:: Die Hauptsache. -* Installing Guix in a VM:: Guix System playground. -* Ein Abbild zur Installation erstellen:: Wie ein solches entsteht. -@end menu - -@node Einschränkungen -@section Einschränkungen - -As of version @value{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 -@url{http://www.gnu.org/distros/free-distros.html, one of the more -established GNU/Linux distributions}. 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 -(@pxref{Installation}). - -Bevor Sie mit der Installation fortfahren, beachten Sie die folgenden -merklichen Einschränkungen der Version @value{VERSION}: - -@itemize -@item -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). - -@item -Der Logical Volume Manager (LVM) wird nicht unterstützt. - -@item -Immer mehr Systemdienste sind verfügbar (@pxref{Dienste}), aber manche -könnten noch fehlen. - -@item -More than 8,500 packages are available, but you might occasionally find that -a useful package is missing. - -@item -GNOME, Xfce, LXDE und Enlightenment stehen zur Verfügung (@pxref{Desktop-Dienste}), ebenso eine Reihe von X11-Fensterverwaltungsprogrammen. Manche -grafischen Anwendungen könnten aber noch fehlen, ebenso fehlt KDE. -@end itemize - -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 @xref{Mitwirken}. - - -@node Hardware-Überlegungen -@section Hardware-Überlegungen - -@cindex hardware support on Guix System -GNU@tie{}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. - -@cindex WLAN, Hardware-Unterstützung -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 @code{ath9k} Linux-libre -driver, and those using Broadcom/AirForce chips (BCM43xx with Wireless-Core -Revision 5), which corresponds to the @code{b43-open} Linux-libre driver. -Free firmware exists for both and is available out-of-the-box on Guix -System, as part of @var{%base-firmware} (@pxref{»operating-system«-Referenz, -@code{firmware}}). - -@cindex RYF, Respects Your Freedom -Die @uref{https://www.fsf.org/, Free Software Foundation} betreibt -@uref{https://www.fsf.org/ryf, @dfn{Respects Your Freedom}} (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 -@uref{https://www.h-node.org/, H-Node}. Dort steht ein Katalog von -Hardware-Geräten mit Informationen darüber, wie gut sie von GNU/Linux -unterstützt werden. - - -@node Installation von USB-Stick oder DVD -@section Installation von USB-Stick oder DVD - -Sie können ein ISO-9660-Installationsabbild von -@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{System}.iso.xz} -herunterladen, dass Sie auf einen USB-Stick aufspielen oder auf eine DVD -brennen können, wobei Sie für @var{System} eines der folgenden schreiben -müssen: - -@table @code -@item x86_64-linux -für ein GNU/Linux-System auf Intel/AMD-kompatiblen 64-Bit-Prozessoren, - -@item i686-linux -für ein 32-Bit-GNU/Linux-System auf Intel-kompatiblen Prozessoren. -@end table - -@c start duplication of authentication part from ``Binary Installation'' -Laden Sie auch die entsprechende @file{.sig}-Datei herunter und verifizieren -Sie damit die Authentizität Ihres Abbilds, indem Sie diese Befehle eingeben: - -@example -$ wget https://alpha.gnu.org/gnu/guix/guixsd-install-@value{VERSION}.@var{System}.iso.xz.sig -$ gpg --verify guixsd-install-@value{VERSION}.@var{System}.iso.xz.sig -@end example - -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: - -@example -$ gpg --keyserver @value{KEY-SERVER} \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@noindent -@c end duplication -und den Befehl @code{gpg --verify} erneut ausführen. - -Dieses Abbild enthält die Werkzeuge, die Sie zur Installation brauchen. Es -ist dafür gedacht, @emph{so wie es ist} auf einen hinreichend großen -USB-Stick oder eine DVD kopiert zu werden. - -@unnumberedsubsec Kopieren auf einen USB-Stick - -Um das Abbild auf einen USB-Stick zu kopieren, führen Sie folgende Schritte -durch: - -@enumerate -@item -Entpacken Sie das Abbild mit dem @command{xz}-Befehl: - -@example -xz -d guixsd-install-@value{VERSION}.@var{System}.iso.xz -@end example - -@item -Stecken Sie einen USB-Stick in Ihren Rechner ein, der mindestens 1@tie{}GiB -groß ist, und bestimmen Sie seinen Gerätenamen. Ist der Gerätename des -USB-Sticks @file{/dev/sdX}, dann kopieren Sie das Abbild mit dem Befehl: - -@example -dd if=guixsd-install-@value{VERSION}.@var{system}.iso of=/dev/sdX -sync -@end example - -Sie benötigen in der Regel Administratorrechte, um auf @file{/dev/sdX} -zuzugreifen. -@end enumerate - -@unnumberedsubsec Auf eine DVD brennen - -Um das Abbild auf eine DVD zu kopieren, führen Sie diese Schritte durch: - -@enumerate -@item -Entpacken Sie das Abbild mit dem @command{xz}-Befehl: - -@example -xz -d guixsd-install-@value{VERSION}.@var{System}.iso.xz -@end example - -@item -Legen Sie eine unbespielte DVD in Ihren Rechner ein und bestimmen Sie ihren -Gerätenamen. Angenommen der Name des DVD-Laufwerks ist @file{/dev/srX}, -kopieren Sie das Abbild mit: - -@example -growisofs -dvd-compat -Z /dev/srX=guixsd-install-@value{VERSION}.@var{system}.iso -@end example - -Der Zugriff auf @file{/dev/srX} setzt in der Regel Administratorrechte -voraus. -@end enumerate - -@unnumberedsubsec 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. - -@xref{Installing Guix in a VM}, if, instead, you would like to install Guix -System in a virtual machine (VM). - - -@node Vor der Installation -@section 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@tie{}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 -(@pxref{Top,,, info-stnd, 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. - -@quotation Anmerkung -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. -@end quotation - -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 @command{guix package} -(@pxref{Aufruf von guix package}). - -@subsection Tastaturbelegung - -@cindex Tastaturbelegung -Das Installationsabbild verwendet die US-amerikanische -QWERTY-Tastaturbelegung. Wenn Sie dies ändern möchten, können Sie den -@command{loadkeys}-Befehl benutzen. Mit folgendem Befehl würden Sie zum -Beispiel die Dvorak-Tastaturbelegung auswählen: - -@example -loadkeys dvorak -@end example - -Schauen Sie sich an, welche Dateien im Verzeichnis -@file{/run/current-system/profile/share/keymaps} stehen, um eine Liste -verfügbarer Tastaturbelegungen zu sehen. Wenn Sie mehr Informationen -brauchen, führen Sie @command{man loadkeys} aus. - -@subsection Netzwerkkonfiguration - -Führen Sie folgenden Befehl aus, um zu sehen, wie Ihre -Netzwerkschnittstellen benannt sind: - -@example -ifconfig -a -@end example - -@noindent -@dots{} oder mit dem GNU/Linux-eigenen @command{ip}-Befehl: - -@example -ip a -@end example - -@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20 -Der Name kabelgebundener Schnittstellen (engl. Interfaces) beginnt mit dem -Buchstaben @samp{e}, zum Beispiel heißt die dem ersten fest eingebauten -Ethernet-Adapter entsprechende Schnittstelle @samp{eno1}. Drahtlose -Schnittstellen werden mit einem Namen bezeichnet, der mit dem Buchstaben -@samp{w} beginnt, etwa @samp{w1p2s0}. - -@table @asis -@item Kabelverbindung -Um ein kabelgebundenes Netzwerk einzurichten, führen Sie den folgenden -Befehl aus, wobei Sie statt @var{Schnittstelle} den Namen der -kabelgebundenen Schnittstelle eintippen, die Sie benutzen möchten. - -@example -ifconfig @var{Schnittstelle} up -@end example - -@item Drahtlose Verbindung -@cindex WLAN -@cindex WiFi -Um Drahtlosnetzwerke einzurichten, können Sie eine Konfigurationsdatei für -das Konfigurationswerkzeug des @command{wpa_supplicant} schreiben (wo Sie -sie speichern, ist nicht wichtig), indem Sie eines der verfügbaren -Textbearbeitungsprogramme wie etwa @command{nano} benutzen: - -@example -nano wpa_supplicant.conf -@end example - -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: - -@example -network=@{ - ssid="@var{meine-ssid}" - key_mgmt=WPA-PSK - psk="geheime Passphrase des Netzwerks" -@} -@end example - -Starten Sie den Dienst für Drahtlosnetzwerke und lassen Sie ihn im -Hintergrund laufen, indem Sie folgenden Befehl eintippen (ersetzen Sie dabei -@var{Schnittstelle} durch den Namen der Netzwerkschnittstelle, die Sie -benutzen möchten): - -@example -wpa_supplicant -c wpa_supplicant.conf -i @var{Schnittstelle} -B -@end example - -Führen Sie @command{man wpa_supplicant} aus, um mehr Informationen zu -erhalten. -@end table - -@cindex DHCP -Zu diesem Zeitpunkt müssen Sie sich eine IP-Adresse beschaffen. Auf einem -Netzwerk, wo IP-Adressen automatisch @i{via} DHCP zugewiesen werden, können -Sie das hier ausführen: - -@example -dhclient -v @var{Schnittstelle} -@end example - -Versuchen Sie, einen Server zu pingen, um zu prüfen, ob sie mit dem Internet -verbunden sind und alles richtig funktioniert: - -@example -ping -c 3 gnu.org -@end example - -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. - -@cindex Über SSH installieren -Wenn Sie möchten, können Sie die weitere Installation auch per Fernwartung -durchführen, indem Sie einen SSH-Server starten: - -@example -herd start ssh-daemon -@end example - -Vergewissern Sie sich vorher, dass Sie entweder ein Passwort mit -@command{passwd} festgelegt haben, oder dass Sie für OpenSSH eine -Authentifizierung über öffentliche Schlüssel eingerichtet haben, bevor Sie -sich anmelden. - -@subsection 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 (@pxref{Overview,,, parted, GNU Parted User Manual}), -@command{fdisk} und @command{cfdisk}. Starten Sie eines davon und -partitionieren Sie Ihre Festplatte oder sonstigen Massenspeicher: - -@example -cfdisk -@end example - -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 (@pxref{BIOS -installation,,, grub, GNU GRUB manual}). - -@cindex EFI, Installation -@cindex UEFI, Installation -@cindex ESP, EFI-Systempartition -If you instead wish to use EFI-based GRUB, a FAT32 @dfn{EFI System -Partition} (ESP) is required. This partition can be mounted at -@file{/boot/efi} for instance and must have the @code{esp} flag set. E.g., -for @command{parted}: - -@example -parted /dev/sda set 1 esp on -@end example - -@quotation Anmerkung -@vindex grub-bootloader -@vindex grub-efi-bootloader -Falls Sie nicht wissen, ob Sie einen EFI- oder BIOS-basierten GRUB -installieren möchten: Wenn bei Ihnen das Verzeichnis -@file{/sys/firmware/efi} im Dateisystem existiert, möchten Sie vermutlich -eine EFI-Installation durchführen, wozu Sie in Ihrer Konfiguration -@code{grub-efi-bootloader} benutzen. Ansonsten sollten Sie den -BIOS-basierten GRUB benutzen, der mit @code{grub-bootloader} bezeichnet -wird. Siehe @xref{Bootloader-Konfiguration}, wenn Sie mehr Informationen -über Bootloader brauchen. -@end quotation - -Once you are done partitioning the target hard disk drive, you have to -create a file system on the relevant partition(s)@footnote{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 @file{/dev/sda1}, -run: - -@example -mkfs.fat -F32 /dev/sda1 -@end example - -Geben Sie Ihren Dateisystemen auch besser eine Bezeichnung (»Label«), damit -Sie sie zuverlässig wiedererkennen und später in den -@code{file-system}-Deklarationen darauf Bezug nehmen können (@pxref{Dateisysteme}). Dazu benutzen Sie typischerweise die Befehlszeilenoption -@code{-L} des Befehls @command{mkfs.ext4} oder entsprechende Optionen für -andere Befehle. Wenn wir also annehmen, dass @file{/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 @code{my-root} -erstellen: - -@example -mkfs.ext4 -L my-root /dev/sda2 -@end example - -@cindex verschlüsselte Partition -Falls Sie aber vorhaben, die Partition mit dem Wurzeldateisystem zu -verschlüsseln, können Sie dazu die Cryptsetup-/LUKS-Werkzeuge verwenden -(siehe @inlinefmtifelse{html, @uref{https://linux.die.net/man/8/cryptsetup, -@code{man cryptsetup}}, @code{man cryptsetup}}, um mehr darüber zu -erfahren). Angenommen Sie wollen die Partition für das Wurzeldateisystem -verschlüsselt auf @file{/dev/sda2} installieren, dann brauchen Sie eine -Befehlsfolge ähnlich wie diese: - -@example -cryptsetup luksFormat /dev/sda2 -cryptsetup open --type luks /dev/sda2 my-partition -mkfs.ext4 -L my-root /dev/mapper/my-partition -@end example - -Sobald das erledigt ist, binden Sie dieses Dateisystem als Installationsziel -mit dem Einhängepunkt @file{/mnt} ein, wozu Sie einen Befehl wie hier -eintippen (auch hier unter der Annahme, dass @code{my-root} die Bezeichnung -des künftigen Wurzeldateisystems ist): - -@example -mount LABEL=my-root /mnt -@end example - -Also mount any other file systems you would like to use on the target system -relative to this path. If you have opted for @file{/boot/efi} as an EFI -mount point for example, mount it at @file{/mnt/boot/efi} now so it is found -by @code{guix system init} afterwards. - -Wenn Sie zudem auch vorhaben, eine oder mehrere Swap-Partitionen zu benutzen -(@pxref{Memory Concepts, swap space,, libc, The GNU C Library Reference -Manual}), initialisieren Sie diese nun mit @command{mkswap}. Angenommen Sie -haben eine Swap-Partition auf @file{/dev/sda3}, dann würde der Befehl so -lauten: - -@example -mkswap /dev/sda3 -swapon /dev/sda3 -@end example - -Alternativ können Sie eine Swap-Datei benutzen. Angenommen, Sie wollten die -Datei @file{/swapdatei} im neuen System als eine Swapdatei benutzen, dann -müssten Sie Folgendes ausführen@footnote{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 @command{mkswap} und @command{swapon}.}: - -@example -# 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 -@end example - -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. - -@node Fortfahren mit der Installation -@section Fortfahren mit der Installation - -Wenn die Partitionen des Installationsziels bereit sind und dessen -Wurzeldateisystem unter @file{/mnt} eingebunden wurde, kann es losgehen mit -der Installation. Führen Sie zuerst aus: - -@example -herd start cow-store /mnt -@end example - -Dadurch wird @file{/gnu/store} copy-on-write, d.h. dorthin von Guix -erstellte Pakete werden in ihrer Installationsphase auf dem unter -@file{/mnt} befindlichen Zieldateisystem gespeichert, statt den -Arbeitsspeicher auszulasten. Das ist nötig, weil die erste Phase des Befehls -@command{guix system init} (siehe unten) viele Dateien nach -@file{/gnu/store} herunterlädt oder sie erstellt, Änderungen am -@file{/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 (@pxref{Top,,, nano, 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 -@command{vi}-Editors von BSD). Wir empfehlen sehr, dass Sie diese Datei im -Zieldateisystem der Installation speichern, etwa als -@file{/mnt/etc/config.scm}, weil Sie Ihre Konfigurationsdatei im frisch -installierten System noch brauchen werden. - -Der Abschnitt @xref{Das Konfigurationssystem nutzen} gibt einen Überblick -über die Konfigurationsdatei. Die in dem Abschnitt diskutierten -Beispielkonfigurationen sind im Installationsabbild im Verzeichnis -@file{/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: - -@example -# mkdir /mnt/etc -# cp /etc/configuration/desktop.scm /mnt/etc/config.scm -# nano /mnt/etc/config.scm -@end example - -Achten Sie darauf, was in Ihrer Konfigurationsdatei steht, und besonders auf -Folgendes: - -@itemize -@item -Make sure the @code{bootloader-configuration} form refers to the target you -want to install GRUB on. It should mention @code{grub-bootloader} if you -are installing GRUB in the legacy way, or @code{grub-efi-bootloader} for -newer UEFI systems. For legacy systems, the @code{target} field names a -device, like @code{/dev/sda}; for UEFI systems it names a path to a mounted -EFI partition, like @code{/boot/efi}; do make sure the path is currently -mounted and a @code{file-system} entry is specified in your configuration. - -@item -Dateisystembezeichnungen müssen mit den jeweiligen @code{device}-Feldern in -Ihrer @code{file-system}-Konfiguration übereinstimmen, sofern Sie in Ihrer -@code{file-system}-Konfiguration die Prozedur @code{file-system-label} für -ihre @code{device}-Felder benutzen. - -@item -Gibt es verschlüsselte Partitionen oder RAID-Partitionen, dann müssen sie im -@code{mapped-devices}-Feld genannt werden (@pxref{Zugeordnete Geräte}). -@end itemize - -Wenn Sie damit fertig sind, Ihre Konfigurationsdatei vorzubereiten, können -Sie das neue System initialisieren (denken Sie daran, dass zukünftige -Wurzeldateisystem muss unter @file{/mnt} wie bereits beschrieben eingebunden -sein): - -@example -guix system init /mnt/etc/config.scm /mnt -@end example - -@noindent -Dies kopiert alle notwendigen Dateien und installiert GRUB auf -@file{/dev/sdX}, sofern Sie nicht noch die Befehlszeilenoption -@option{--no-bootloader} benutzen. Weitere Informationen finden Sie im -Abschnitt @pxref{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 @command{reboot} das neue System booten lassen. Der -Administratornutzer @code{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 @command{passwd} als @code{root} ausführen, außer Ihre -Konfiguration enthält schon Passwörter (@pxref{user-account-password, user -account passwords}). - -@cindex upgrading Guix System -From then on, you can update the system whenever you want by running, say: - -@example -guix pull -sudo guix system reconfigure /etc/config.scm -@end example - -@noindent -This builds a new system generation with the latest packages and services -(@pxref{Aufruf von guix system}). We recommend doing that regularly so that -your system includes the latest security updates (@pxref{Sicherheitsaktualisierungen}). - -@c See <https://lists.gnu.org/archive/html/guix-devel/2019-01/msg00268.html>. -@quotation Anmerkung -@cindex sudo vs. @command{guix pull} -Note that @command{sudo guix} runs your user's @command{guix} command and -@emph{not} root's, because @command{sudo} leaves @code{PATH} unchanged. To -explicitly run root's @command{guix}, type @command{sudo -i guix @dots{}}. -@end quotation - -Join us on @code{#guix} on the Freenode IRC network or on -@email{guix-devel@@gnu.org} to share your experience---good or not so good. - -@node Installing Guix in a VM -@section Installing Guix in a Virtual Machine - -@cindex virtual machine, Guix System installation -@cindex Virtual Private Server (VPS) -@cindex VPS (Virtual Private Server) -If you'd like to install Guix System in a virtual machine (VM) or on a -virtual private server (VPS) rather than on your beloved machine, this -section is for you. - -To boot a @uref{http://qemu.org/,QEMU} VM for installing Guix System in a -disk image, follow these steps: - -@enumerate -@item -First, retrieve and decompress the Guix system installation image as -described previously (@pxref{Installation von USB-Stick oder DVD}). - -@item -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 @command{qemu-img}: - -@example -qemu-img create -f qcow2 guixsd.img 50G -@end example - -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. - -@item -Starten Sie das USB-Installationsabbild auf einer virtuellen Maschine: - -@example -qemu-system-x86_64 -m 1024 -smp 1 \ - -net user -net nic,model=virtio -boot menu=on \ - -drive file=guixsd-install-@value{VERSION}.@var{System}.iso \ - -drive file=guixsd.img -@end example - -Halten Sie obige Reihenfolge der @option{-drive}-Befehlszeilenoptionen für -die Laufwerke ein. - -Drücken Sie auf der Konsole der virtuellen Maschine schnell die -@kbd{F12}-Taste, um ins Boot-Menü zu gelangen. Drücken Sie dort erst die -Taste @kbd{2} und dann die Eingabetaste @kbd{RET}, um Ihre Auswahl zu -bestätigen. - -@item -Sie sind nun in der virtuellen Maschine als Administratornutzer @code{root} -angemeldet und können mit der Installation wie gewohnt fortfahren. Folgen -Sie der Anleitung im Abschnitt @xref{Vor der Installation}. -@end enumerate - -Once installation is complete, you can boot the system that's on your -@file{guixsd.img} image. @xref{Running Guix in a VM}, for how to do that. - -@node Ein Abbild zur Installation erstellen -@section Ein Abbild zur Installation erstellen - -@cindex Installationsabbild -Das oben beschriebene Installationsabbild wurde mit dem Befehl @command{guix -system} erstellt, genauer gesagt mit: - -@example -guix system disk-image --file-system-type=iso9660 \ - gnu/system/install.scm -@end example - -Die Datei @file{gnu/system/install.scm} finden Sie im Quellbaum von -Guix. Schauen Sie sich die Datei und auch den Abschnitt @ref{Aufruf von guix system} an, um mehr Informationen über das Installationsabbild zu erhalten. - -@section Abbild zur Installation für ARM-Rechner erstellen - -Viele ARM-Chips funktionieren nur mit ihrer eigenen speziellen Variante des -@uref{http://www.denx.de/wiki/U-Boot/, 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: - -@example -guix system disk-image --system=armhf-linux -e '((@@ (gnu system install) os-with-u-boot) (@@ (gnu system install) installation-os) "A20-OLinuXino-Lime2")' -@end example - -@code{A20-OLinuXino-Lime2} ist der Name des Chips. Wenn Sie einen ungültigen -Namen eingeben, wird eine Liste möglicher Chip-Namen ausgegeben. - -@c ********************************************************************* -@node Paketverwaltung -@chapter Paketverwaltung - -@cindex Pakete -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 (@pxref{Aufruf von guix package, @code{guix package}}) können Sie auch mit der -Emacs-Guix-Schnittstelle (@pxref{Top,,, emacs-guix, The Emacs-Guix Reference -Manual}) arbeiten, nachdem Sie das Paket @code{emacs-guix} installiert haben -(führen Sie zum Einstieg in Emacs-Guix den Emacs-Befehl @kbd{M-x guix-help} -aus): - -@example -guix package -i emacs-guix -@end example - -@menu -* Funktionalitäten:: Wie Guix Ihr Leben schöner machen wird. -* Aufruf von guix package:: Pakete installieren, entfernen usw. -* Substitute:: Vorerstelle Binärdateien herunterladen. -* Pakete mit mehreren Ausgaben.:: Ein Quellpaket, mehrere Ausgaben. -* Aufruf von guix gc:: Den Müllsammler laufen lassen. -* Aufruf von guix pull:: Das neueste Guix samt Distribution laden. -* Kanäle:: Die Paketsammlung anpassen. -* Untergeordnete:: Mit einer anderen Version von Guix - interagieren. -* Aufruf von guix describe:: Informationen über Ihre Guix-Version - anzeigen. -* Aufruf von guix archive:: Import und Export von Store-Dateien. -@end menu - -@node Funktionalitäten -@section Funktionalitäten - -Wenn Sie Guix benutzen, landet jedes Paket schließlich im @dfn{Paket-Store} -in seinem eigenen Verzeichnis — der Name ist ähnlich wie -@file{/gnu/store/xxx-package-1.2}, wobei @code{xxx} eine Zeichenkette in -Base32-Darstellung ist. - -Statt diese Verzeichnisse direkt anzugeben, haben Nutzer ihr eigenes -@dfn{Profil}, welches auf diejenigen Pakete zeigt, die sie tatsächlich -benutzen wollen. Diese Profile sind im Persönlichen Verzeichnis des -jeweiligen Nutzers gespeichert als @code{$HOME/.guix-profile}. - -Zum Beispiel installiert @code{alice} GCC 4.7.2. Dadurch zeigt dann -@file{/home/alice/.guix-profile/bin/gcc} auf -@file{/gnu/store/@dots{}-gcc-4.7.2/bin/gcc}. Auf demselben Rechner hat -@code{bob} bereits GCC 4.8.0 installiert. Das Profil von @code{bob} zeigt -dann einfach weiterhin auf @file{/gnu/store/@dots{}-gcc-4.8.0/bin/gcc} — -d.h. beide Versionen von GCC koexistieren auf demselben System, ohne sich zu -stören. - -Der Befehl @command{guix package} ist das zentrale Werkzeug, um Pakete zu -verwalten (@pxref{Aufruf von guix package}). Es arbeitet auf dem eigenen -Profil jedes Nutzers und kann @emph{mit normalen Benutzerrechten} ausgeführt -werden. - -@cindex Transaktionen -Der Befehl stellt die offensichtlichen Installations-, Entfernungs- und -Aktualisierungsoperationen zur Verfügung. Jeder Aufruf ist tatsächlich eine -eigene @emph{Transaktion}: Entweder die angegebene Operation wird -erfolgreich durchgeführt, oder gar nichts passiert. Wenn also der Prozess -von @command{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 @emph{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 -(@pxref{Das Konfigurationssystem nutzen}). - -Alle Pakete im Paket-Store können vom @emph{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 (@pxref{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. - -@cindex Reproduzierbarkeit -@cindex Reproduzierbare Erstellungen -Guix verfolgt einen @dfn{rein funktionalen} Ansatz bei der Paketverwaltung, -wie er in der Einleitung beschrieben wurde (@pxref{Einführung}). Jedes -Paketverzeichnis im @file{/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 @dfn{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 (@pxref{Aufruf des guix-daemon, container}). - -@cindex Substitute -Auf dieser Grundlage kann Guix @dfn{transparent Binär- oder Quelldateien -ausliefern}. Wenn eine vorerstellte Binärdatei für ein -@file{/gnu/store}-Objekt von einer externen Quelle verfügbar ist — ein -@dfn{Substitut} —, lädt Guix sie einfach herunter und entpackt sie, -andernfalls erstellt Guix das Paket lokal aus seinem Quellcode -(@pxref{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 @emph{anfechten} (@pxref{Aufruf von guix challenge}). - -Kontrolle über die Erstellungsumgebung ist eine auch für Entwickler -nützliche Funktionalität. Der Befehl @command{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 (@pxref{Aufruf von guix environment}). - -@cindex Nachbildung, von Software-Umgebungen -@cindex Provenienzverfolgung, von Software-Artefakten -Ganz Guix und all seine Paketdefinitionen stehen unter Versionskontrolle und -@command{guix pull} macht es möglich, auf dem Verlauf der Entwicklung von -Guix selbst »in der Zeit zu reisen« (@pxref{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 @emph{vollständige -Software-Umgebungen gänzlich nachgebildet} werden können, mit genauer -@dfn{Provenienzverfolgung}, wo diese Software herkommt. - -@node Aufruf von guix package -@section Invoking @command{guix package} - -@cindex Installieren von Paketen -@cindex Entfernen von Paketen -@cindex Paketinstallation -@cindex Paketentfernung -Der Befehl @command{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 -(@pxref{Funktionalitäten}). Die Syntax ist: - -@example -guix package @var{Optionen} -@end example -@cindex Transaktionen -In erster Linie geben die @var{Optionen} an, welche Operationen in der -Transaktion durchgeführt werden sollen. Nach Abschluss wird ein neues Profil -erzeugt, aber vorherige @dfn{Generationen} des Profils bleiben verfügbar, -falls der Benutzer auf sie zurückwechseln will. - -Um zum Beispiel @code{lua} zu entfernen und @code{guile} und -@code{guile-cairo} in einer einzigen Transaktion zu installieren: - -@example -guix package -r lua -i guile guile-cairo -@end example - -@command{guix package} unterstützt auch ein @dfn{deklaratives Vorgehen}, -wobei der Nutzer die genaue Menge an Paketen, die verfügbar sein sollen, -festlegt und über die Befehlszeilenoption @option{--manifest} übergibt -(@pxref{profile-manifest, @option{--manifest}}). - -@cindex Profil -Für jeden Benutzer wird automatisch eine symbolische Verknüpfung zu seinem -Standardprofil angelegt als @file{$HOME/.guix-profile}. Diese symbolische -Verknüpfung zeigt immer auf die aktuelle Generation des Standardprofils des -Benutzers. Somit können Nutzer @file{$HOME/.guix-profile/bin} z.B. zu ihrer -Umgebungsvariablen @code{PATH} hinzufügen. -@cindex Suchpfade -Wenn Sie nicht die Guix System Distribution benutzen, sollten Sie in -Betracht ziehen, folgende Zeilen zu Ihrem @file{~/.bash_profile} -hinzuzufügen (@pxref{Bash Startup Files,,, bash, The GNU Bash Reference -Manual}), damit in neu erzeugten Shells alle Umgebungsvariablen richtig -definiert werden: - -@example -GUIX_PROFILE="$HOME/.guix-profile" ; \ -source "$HOME/.guix-profile/etc/profile" -@end example - -Ist Ihr System für mehrere Nutzer eingerichtet, werden Nutzerprofile an -einem Ort gespeichert, der als @dfn{Müllsammlerwurzel} registriert ist, auf -die @file{$HOME/.guix-profile} zeigt (@pxref{Aufruf von guix gc}). Dieses -Verzeichnis ist normalerweise -@code{@var{localstatedir}/guix/profiles/per-user/@var{Benutzer}}, wobei -@var{localstatedir} der an @code{configure} als @code{--localstatedir} -übergebene Wert ist und @var{Benutzer} für den jeweiligen Benutzernamen -steht. Das @file{per-user}-Verzeichnis wird erstellt, wenn -@command{guix-daemon} gestartet wird, und das Unterverzeichnis -@var{Benutzer} wird durch @command{guix package} erstellt. - -Als @var{Optionen} kann vorkommen: - -@table @code - -@item --install=@var{Paket} @dots{} -@itemx -i @var{Paket} @dots{} -Die angegebenen @var{Paket}e installieren. - -Jedes @var{Paket} kann entweder einfach durch seinen Paketnamen aufgeführt -werden, wie @code{guile}, oder als Paketname gefolgt von einem At-Zeichen @@ -und einer Versionsnummer, wie @code{guile@@1.8.8} oder auch nur -@code{guile@@1.8} (in letzterem Fall wird die neueste Version mit Präfix -@code{1.8} ausgewählt.) - -Wird keine Versionsnummer angegeben, wird die neueste verfügbare Version -ausgewählt. Zudem kann im @var{Paket} ein Doppelpunkt auftauchen, gefolgt -vom Namen einer der Ausgaben des Pakets, wie @code{gcc:doc} oder -@code{binutils@@2.22:lib} (@pxref{Pakete mit mehreren Ausgaben.}). Pakete -mit zugehörigem Namen (und optional der Version) werden unter den Modulen -der GNU-Distribution gesucht (@pxref{Paketmodule}). - -@cindex propagierte Eingaben -Manchmal haben Pakete @dfn{propagierte Eingaben}: Als solche werden -Abhängigkeiten bezeichnet, die automatisch zusammen mit dem angeforderten -Paket installiert werden (im Abschnitt @pxref{package-propagated-inputs, -@code{propagated-inputs} in @code{package} objects} sind weitere -Informationen über propagierte Eingaben in Paketdefinitionen zu finden). - -@anchor{package-cmd-propagated-inputs} -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 @code{--search-paths} -weiter unten). Alle fehlenden oder womöglich falschen Definitionen von -Umgebungsvariablen werden hierbei gemeldet. - -@item --install-from-expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Das Paket installieren, zu dem der @var{Ausdruck} ausgewertet wird. - -Beim @var{Ausdruck} muss es sich um einen Scheme-Ausdruck handeln, der zu -einem @code{<package>}-Objekt ausgewertet wird. Diese Option ist besonders -nützlich, um zwischen gleichnamigen Varianten eines Pakets zu unterscheiden, -durch Ausdrücke wie @code{(@@ (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. - -@item --install-from-file=@var{Datei} -@itemx -f @var{Datei} -Das Paket installieren, zu dem der Code in der @var{Datei} ausgewertet wird. - -Zum Beispiel könnte die @var{Datei} eine Definition wie diese enthalten -(@pxref{Pakete definieren}): - -@example -@verbatiminclude package-hello.scm -@end example - -Entwickler könnten es für nützlich erachten, eine solche -@file{guix.scm}-Datei im Quellbaum ihres Projekts abzulegen, mit der -Zwischenstände der Entwicklung getestet und reproduzierbare -Erstellungsumgebungen aufgebaut werden können (@pxref{Aufruf von guix environment}). - -@item --remove=@var{Paket} @dots{} -@itemx -r @var{Paket} @dots{} -Die angegebenen @var{Paket}e entfernen. - -Wie auch bei @code{--install} kann jedes @var{Paket} neben dem Paketnamen -auch eine Versionsnummer und/oder eine Ausgabe benennen. Zum Beispiel würde -@code{-r glibc:debug} die @code{debug}-Ausgabe von @code{glibc} aus dem -Profil entfernen. - -@item --upgrade[=@var{Regexp} @dots{}] -@itemx -u [@var{Regexp} @dots{}] -@cindex Pakete aktualisieren -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 @var{Regexp}s passt. Siehe auch -weiter unten die Befehlszeilenoption @code{--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 -@command{guix pull} ausführen (@pxref{Aufruf von guix pull}). - -@item --do-not-upgrade[=@var{Regexp} @dots{}] -In Verbindung mit der Befehlszeilenoption @code{--upgrade}, führe -@emph{keine} Aktualisierung von Paketen durch, deren Name zum regulären -Ausdruck @var{Regexp} passt. Um zum Beispiel alle Pakete im aktuellen Profil -zu aktualisieren mit Ausnahme derer, die »emacs« im Namen haben: - -@example -$ guix package --upgrade . --do-not-upgrade emacs -@end example - -@item @anchor{profile-manifest}--manifest=@var{Datei} -@itemx -m @var{Datei} -@cindex Profildeklaration -@cindex Profilmanifest -Erstellt eine neue Generation des Profils aus dem vom Scheme-Code in -@var{Datei} gelieferten Manifest-Objekt. - -Dadurch könnrn Sie den Inhalt des Profils @emph{deklarieren}, statt ihn -durch eine Folge von Befehlen wie @code{--install} u.Ä. zu generieren. Der -Vorteil ist, dass die @var{Datei} unter Versionskontrolle gestellt werden -kann, auf andere Maschinen zum Reproduzieren desselben Profils kopiert -werden kann und Ähnliches. - -@c FIXME: Add reference to (guix profile) documentation when available. -Der Code in der @var{Datei} muss ein @dfn{Manifest}-Objekt liefern, was -ungefähr einer Liste von Paketen entspricht: - -@findex packages->manifest -@example -(use-package-modules guile emacs) - -(packages->manifest - (list emacs - guile-2.0 - ;; Eine bestimmte Paketausgabe nutzen. - (list guile-2.0 "debug"))) -@end example - -@findex specifications->manifest -In diesem Beispiel müssen wir wissen, welche Module die Variablen -@code{emacs} und @code{guile-2.0} definieren, um die richtige Angabe mit -@code{use-package-modules} machen zu können, was umständlich sein kann. Wir -können auch normale Paketnamen angeben und sie durch -@code{specifications->manifest} zu den entsprechenden Paketobjekten -auflösen, zum Beispiel so: - -@example -(specifications->manifest - '("emacs" "guile@@2.2" "guile@@2.2:debug")) -@end example - -@item --roll-back -@cindex rücksetzen -@cindex Zurücksetzen von Transaktionen -@cindex Transaktionen, zurücksetzen -Wechselt zur vorherigen @dfn{Generation} des Profils zurück — d.h. macht die -letzte Transaktion rückgängig. - -In Verbindung mit Befehlszeilenoptionen wie @code{--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 @dfn{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. - -@item --switch-generation=@var{Muster} -@itemx -S @var{Muster} -@cindex Generationen -Wechselt zu der bestimmten Generation, die durch das @var{Muster} bezeichnet -wird. - -Als @var{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 -@code{--switch-generation=+1} nach einem Zurücksetzen wieder zur neueren -Generation zurück. - -Der Unterschied zwischen @code{--roll-back} und -@code{--switch-generation=-1} ist, dass @code{--switch-generation} keine -nullte Generation erzeugen wird; existiert die angegebene Generation nicht, -bleibt schlicht die aktuelle Generation erhalten. - -@item --search-paths[=@var{Art}] -@cindex Suchpfade -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 @dfn{Suchpfade} für Dateien -festzulegen, die von einigen installierten Paketen benutzt werden. - -Zum Beispiel braucht GCC die Umgebungsvariablen @code{CPATH} und -@code{LIBRARY_PATH}, um zu wissen, wo sich im Benutzerprofil Header und -Bibliotheken befinden (@pxref{Environment Variables,,, gcc, Using the GNU -Compiler Collection (GCC)}). Wenn GCC und, sagen wir, die C-Bibliothek im -Profil installiert sind, schlägt @code{--search-paths} also vor, diese -Variablen jeweils auf @code{@var{profile}/include} und -@code{@var{profile}/lib} verweisen zu lassen. - -Die typische Nutzung ist, in der Shell diese Variablen zu definieren: - -@example -$ eval `guix package --search-paths` -@end example - -Als @var{Art} kann entweder @code{exact}, @code{prefix} oder @code{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 -@var{Art} an, wird der Vorgabewert @code{exact} verwendet. - -Diese Befehlszeilenoption kann auch benutzt werden, um die -@emph{kombinierten} Suchpfade mehrerer Profile zu berechnen. Betrachten Sie -dieses Beispiel: - -@example -$ guix package -p foo -i guile -$ guix package -p bar -i guile-json -$ guix package -p foo -p bar --search-paths -@end example - -Der letzte Befehl oben meldet auch die Definition der Umgebungsvariablen -@code{GUILE_LOAD_PATH}, obwohl für sich genommen weder @file{foo} noch -@file{bar} zu dieser Empfehlung führen würden. - - -@item --profile=@var{Profil} -@itemx -p @var{Profil} -Auf @var{Profil} anstelle des Standardprofils des Benutzers arbeiten. - -@cindex Kollisionen, in einem Profil -@cindex Paketkollisionen in Profilen -@cindex Profilkollisionen -@item --allow-collisions -Kollidierende Pakete im neuen Profil zulassen. Benutzung auf eigene Gefahr! - -Standardmäßig wird @command{guix package} @dfn{Kollisionen} als Fehler -auffassen und melden. Zu Kollisionen kommt es, wenn zwei oder mehr -verschiedene Versionen oder Varianten desselben Pakets im Profil landen. - -@item --bootstrap -Erstellt das Profil mit dem Bootstrap-Guile. Diese Option ist nur für -Entwickler der Distribution nützlich. - -@end table - -Zusätzlich zu diesen Aktionen unterstützt @command{guix package} folgende -Befehlszeilenoptionen, um den momentanen Zustand eines Profils oder die -Verfügbarkeit von Paketen nachzulesen: - -@table @option - -@item --search=@var{Regexp} -@itemx -s @var{Regexp} -@cindex Suche nach Paketen -List the available packages whose name, synopsis, or description matches -@var{regexp} (in a case-insensitive fashion), sorted by relevance. Print -all the metadata of matching packages in @code{recutils} format (@pxref{Top, -GNU recutils databases,, recutils, GNU recutils manual}). - -So können bestimmte Felder mit dem Befehl @command{recsel} extrahiert -werden, zum Beispiel: - -@example -$ 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 -@end example - -Ebenso kann der Name aller zu den Bedingungen der GNU@tie{}LGPL, Version 3, -verfügbaren Pakete ermittelt werden: - -@example -$ guix package -s "" | recsel -p name -e 'license ~ "LGPL 3"' -name: elfutils - -name: gmp -@dots{} -@end example - -Es ist auch möglich, Suchergebnisse näher einzuschränken, indem Sie -@code{-s} mehrmals übergeben. Zum Beispiel liefert folgender Befehl eines -Liste von Brettspielen: - -@example -$ guix package -s '\<board\>' -s game | recsel -p name -name: gnubg -@dots{} -@end example - -Würden wir @code{-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 @code{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: - -@example -$ guix package -s crypto -s library | \ - recsel -e '! (name ~ "^(ghc|perl|python|ruby)")' -p name,synopsis -@end example - -@noindent -@xref{Selection Expressions,,, recutils, GNU recutils manual} enthält -weitere Informationen über @dfn{Auswahlausdrücke} mit @code{recsel -e}. - -@item --show=@var{Paket} -Zeigt Details über das @var{Paket} aus der Liste verfügbarer Pakete, im -@code{recutils}-Format (@pxref{Top, GNU recutils databases,, recutils, GNU -recutils manual}). - -@example -$ guix package --show=python | recsel -p name,version -name: python -version: 2.7.6 - -name: python -version: 3.3.5 -@end example - -Sie können auch den vollständigen Namen eines Pakets angeben, um Details nur -über diese Version angezeigt zu bekommen: -@example -$ guix package --show=python@@3.4 | recsel -p name,version -name: python -version: 3.4.3 -@end example - - - -@item --list-installed[=@var{Regexp}] -@itemx -I [@var{Regexp}] -Listet die derzeit installierten Pakete im angegebenen Profil auf, die -zuletzt installierten Pakete zuletzt. Wenn ein regulärer Ausdruck -@var{Regexp} angegeben wird, werden nur installierte Pakete aufgeführt, -deren Name zu @var{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 @code{out}, wenn die -Standard-Paketausgabe installiert ist, @code{include}, wenn seine Header -installiert sind, usw.) und an welchem Pfad das Paket im Store zu finden -ist. - -@item --list-available[=@var{Regexp}] -@itemx -A [@var{Regexp}] -Listet Pakete auf, die in der aktuell installierten Distribution dieses -Systems verfügbar sind (@pxref{GNU-Distribution}). Wenn ein regulärer -Ausdruck @var{Regexp} angegeben wird, werden nur Pakete aufgeführt, deren -Name zum regulären Ausdruck @var{Regexp} passt. - -Zu jedem Paket werden folgende Informationen getrennt durch Tabulatorzeichen -ausgegeben: der Name, die Version als Zeichenkette, die Teile des Programms -(@pxref{Pakete mit mehreren Ausgaben.}) und die Stelle im Quellcode, an der -das Paket definiert ist. - -@item --list-generations[=@var{Muster}] -@itemx -l [@var{Muster}] -@cindex Generationen -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 (@pxref{Pakete mit mehreren Ausgaben.}) und an welcher Stelle sich das Paket im Store befindet. - -Wenn ein @var{Muster} angegeben wird, liefert der Befehl nur dazu passende -Generationen. Gültige Muster sind zum Beispiel: - -@itemize -@item @emph{Ganze Zahlen und kommagetrennte ganze Zahlen}. Beide Muster bezeichnen -Generationsnummern. Zum Beispiel liefert @code{--list-generations=1} die -erste Generation. - -Durch @code{--list-generations=1,8,2} werden drei Generationen in der -angegebenen Reihenfolge angezeigt. Weder Leerzeichen noch ein Komma am -Schluss der Liste ist erlaubt. - -@item @emph{Bereiche}. @code{--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 -@code{--list-generations=2..} alle Generationen ab der zweiten. - -@item @emph{Zeitdauern}. Sie können auch die letzten @emph{N}@tie{}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 @code{--list-generations=20d} die -Generationen auf, die höchstens 20 Tage alt sind. -@end itemize - -@item --delete-generations[=@var{Muster}] -@itemx -d [@var{Muster}] -Wird kein @var{Muster} angegeben, werden alle Generationen außer der -aktuellen entfernt. - -Dieser Befehl akzeptiert dieselben Muster wie -@option{--list-generations}. Wenn ein @var{Muster} angegeben wird, werden -die passenden Generationen gelöscht. Wenn das @var{Muster} für eine -Zeitdauer steht, werden diejenigen Generationen gelöscht, die @emph{älter} -als die angegebene Dauer sind. Zum Beispiel löscht -@code{--delete-generations=1m} die Generationen, die mehr als einen Monat -alt sind. - -Falls die aktuelle Generation zum Muster passt, wird sie @emph{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. - -@end table - -Zu guter Letzt können Sie, da @command{guix package} Erstellungsprozesse zu -starten vermag, auch alle gemeinsamen Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}) verwenden. Auch Paketumwandlungsoptionen wie -@option{--with-source} sind möglich (@pxref{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 @code{GUIX_PACKAGE_PATH} hinzufügen -(@pxref{Pakete definieren}). - -@node Substitute -@section Substitute - -@cindex Substitute -@cindex vorerstellte Binärdateien -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 @dfn{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 (@pxref{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. - -@menu -* Offizieller Substitut-Server:: Eine besondere Quelle von Substituten. -* Substitut-Server autorisieren:: Wie man Substitute an- und abschaltet. -* Substitutauthentifizierung:: Wie Guix Substitute verifiziert. -* Proxy-Einstellungen:: Wie Sie Substitute über einen Proxy beziehen. -* Fehler bei der Substitution:: Was passiert, wenn die Substitution - fehlschlägt. -* Vom Vertrauen gegenüber Binärdateien:: Wie können Sie diesem binären - Blob trauen? -@end menu - -@node Offizieller Substitut-Server -@subsection Offizieller Substitut-Server - -@cindex Hydra -@cindex Build-Farm -The @code{@value{SUBSTITUTE-SERVER}} 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 -@option{--substitute-urls} option either to @command{guix-daemon} -(@pxref{daemon-substitute-urls,, @code{guix-daemon --substitute-urls}}) or -to client tools such as @command{guix package} -(@pxref{client-substitute-urls,, client @option{--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 (@pxref{GNU-Distribution}). Auf -Fremddistributionen sind sie allerdings standardmäßig ausgeschaltet, solange -Sie sie nicht ausdrücklich in einem der empfohlenen Installationsschritte -erlaubt haben (@pxref{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. - -@node Substitut-Server autorisieren -@subsection Substitut-Server autorisieren - -@cindex Sicherheit -@cindex Substitute, deren Autorisierung -@cindex Access Control List (ACL), für Substitute -@cindex ACL (Access Control List), für Substitute -To allow Guix to download substitutes from @code{@value{SUBSTITUTE-SERVER}} -or a mirror thereof, you must add its public key to the access control list -(ACL) of archive imports, using the @command{guix archive} command -(@pxref{Aufruf von guix archive}). Doing so implies that you trust -@code{@value{SUBSTITUTE-SERVER}} to not be compromised and to serve genuine -substitutes. - -The public key for @code{@value{SUBSTITUTE-SERVER}} is installed along with -Guix, in @code{@var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub}, where -@var{prefix} is the installation prefix of Guix. If you installed Guix from -source, make sure you checked the GPG signature of -@file{guix-@value{VERSION}.tar.gz}, which contains this public key file. -Then, you can run something like this: - -@example -# guix archive --authorize < @var{prefix}/share/guix/@value{SUBSTITUTE-SERVER}.pub -@end example - -@quotation Anmerkung -Similarly, the @file{hydra.gnu.org.pub} file contains the public key of an -independent build farm also run by the project, reachable at -@indicateurl{https://mirror.hydra.gnu.org}. -@end quotation - -Sobald es eingerichtet wurde, sollte sich die Ausgabe eines Befehls wie -@code{guix build} von so etwas: - -@example -$ 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 -@dots{} -@end example - -@noindent -in so etwas verwandeln: - -@example -$ 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 -@dots{} -@end example - -@noindent -This indicates that substitutes from @code{@value{SUBSTITUTE-SERVER}} are -usable and will be downloaded, when possible, for future builds. - -@cindex Substitute, wie man sie ausschaltet -Der Substitutsmechanismus kann global ausgeschaltet werden, indem Sie dem -@code{guix-daemon} beim Starten die Befehlszeilenoption -@code{--no-substitutes} übergeben (@pxref{Aufruf des guix-daemon}). Er kann -auch temporär ausgeschaltet werden, indem Sie @code{--no-substitutes} an -@command{guix package}, @command{guix build} und andere -Befehlszeilenwerkzeuge übergeben. - -@node Substitutauthentifizierung -@subsection Substitutauthentifizierung - -@cindex digitale Signaturen -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 @emph{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: - -@example ---substitute-urls="https://a.example.org https://b.example.org" -@end example - -@noindent -@cindex Reproduzierbare Erstellungen -Wenn in der ACL nur der Schlüssel für @code{b.example.org} aufgeführt wurde, -aber @code{a.example.org} @emph{exakt dieselben} Substitute anbietet, wird -Guix auch Substitute von @code{a.example.org} herunterladen, weil es in der -Liste zuerst kommt und als Spiegelserver für @code{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 @emph{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). - -@node Proxy-Einstellungen -@subsection Proxy-Einstellungen - -@vindex http_proxy -Substitute werden über HTTP oder HTTPS heruntergeladen. Die -Umgebungsvariable @code{http_proxy} kann in der Umgebung von -@command{guix-daemon} definiert werden und wirkt sich dann auf das -Herunterladen von Substituten aus. Beachten Sie, dass der Wert von -@code{http_proxy} in der Umgebung, in der @command{guix build}, -@command{guix package} und andere Client-Befehle ausgeführt werden, -@emph{keine Rolle spielt}. - -@node Fehler bei der Substitution -@subsection 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 -@code{--fallback} übergeben wurde (@pxref{fallback-option,, common build -option @code{--fallback}}). Genauer gesagt, wird keine lokale Erstellung -durchgeführt, solange kein @code{--fallback} angegeben wurde, und die -Ableitung wird als Fehlschlag angesehen. Wenn @code{--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, @emph{immer} eine -lokale Erstellung durchgeführt wird, egal ob @code{--fallback} übergeben -wurde oder nicht. - -Um eine Vorstellung zu bekommen, wieviele Substitute gerade verfügbar sind, -können Sie den Befehl @command{guix weather} benutzen (@pxref{Aufruf von guix weather}). Dieser Befehl zeigt Statistiken darüber an, wie es um die von -einem Server verfügbaren Substitute steht. - -@node Vom Vertrauen gegenüber Binärdateien -@subsection Vom Vertrauen gegenüber Binärdateien - -@cindex Vertrauen, gegenüber vorerstellten 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 @code{@value{SUBSTITUTE-SERVER}} substitutes can be convenient, we -encourage users to also build on their own, or even run their own build -farm, such that @code{@value{SUBSTITUTE-SERVER}} is less of an interesting -target. One way to help is by publishing the software you build using -@command{guix publish} so that others have one more choice of server to -download substitutes from (@pxref{Aufruf von guix publish}). - -Guix hat die richtigen Grundlagen, um die Reproduzierbarkeit von -Erstellungen zu maximieren (@pxref{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 @command{guix challenge} hat das Ziel, Nutzern zu -ermöglichen, Substitutserver zu beurteilen, und Entwickler dabei zu -unterstützen, nichtdeterministische Paketerstellungen zu finden -(@pxref{Aufruf von guix challenge}). Ebenso ermöglicht es die -Befehlszeilenoption @option{--check} von @command{guix build}, dass Nutzer -bereits installierte Substitute auf Echtheit zu prüfen, indem sie lokal -nachgebaut werden (@pxref{build-check, @command{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 -@email{guix-devel@@gnu.org}. - -@node Pakete mit mehreren Ausgaben. -@section Pakete mit mehreren Ausgaben. - -@cindex mehrere Ausgaben, bei Paketen -@cindex Paketausgaben -@cindex Ausgaben - -Oft haben in Guix definierte Pakete eine einzige @dfn{Ausgabe} — d.h. aus -dem Quellpaket entsteht genau ein Verzeichnis im Store. Wenn Sie -@command{guix package -i glibc} ausführen, wird die Standard-Paketausgabe -des GNU-libc-Pakets installiert; die Standardausgabe wird @code{out} -genannt, aber ihr Name kann weggelassen werden, wie sie an obigem Befehl -sehen. In diesem speziellen Fall enthält die Standard-Paketausgabe von -@code{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 -@code{doc}. Um also die Hauptausgabe von GLib zu installieren, zu der alles -außer der Dokumentation gehört, ist der Befehl: - -@example -guix package -i glib -@end example - -@cindex Dokumentation -Der Befehl, um die Dokumentation zu installieren, ist: - -@example -guix package -i glib:doc -@end example - -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 @command{guix size} kann dabei helfen, solche Situationen zu erkennen -(@pxref{Aufruf von guix size}). @command{guix graph} kann auch helfen -(@pxref{Aufruf von guix graph}). - -In der GNU-Distribution gibt es viele solche Pakete mit mehreren -Ausgaben. Andere Konventionen für Ausgabenamen sind zum Beispiel @code{lib} -für Bibliotheken und eventuell auch ihre Header-Dateien,, @code{bin} für -eigenständige Programme und @code{debug} für Informationen zur -Fehlerbehandlung (@pxref{Dateien zur Fehlersuche installieren}). Die Ausgaben eines -Pakets stehen in der dritten Spalte der Anzeige von @command{guix package ---list-available} (@pxref{Aufruf von guix package}). - - -@node Aufruf von guix gc -@section @command{guix gc} aufrufen - -@cindex Müllsammler -@cindex Plattenspeicher -Pakete, die zwar installiert sind, aber nicht benutzt werden, können vom -@dfn{Müllsammler} entfernt werden. Mit dem Befehl @command{guix gc} können -Benutzer den Müllsammler ausdrücklich aufrufen, um Speicher im Verzeichnis -@file{/gnu/store} freizugeben. Dies ist der @emph{einzige} Weg, Dateien aus -@file{/gnu/store} zu entfernen — das manuelle Entfernen von Dateien kann den -Store irreparabel beschädigen! - -@cindex GC-Wurzeln -@cindex Müllsammlerwurzeln -Der Müllsammler kennt eine Reihe von @dfn{Wurzeln}: Jede Datei in -@file{/gnu/store}, die von einer Wurzel aus erreichbar ist, gilt als -@dfn{lebendig} und kann nicht entfernt werden; jede andere Datei gilt als -@dfn{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 -@file{/var/guix/gcroots} dargestellt. Neue Müllsammlerwurzeln können zum -Beispiel mit @command{guix build --root} festgelegt werden (@pxref{Aufruf von guix build}). - -Bevor Sie mit @code{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 @code{guix package --delete-generations} aus (@pxref{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@tie{}GB auf Ihrer Platte zur -Verfügung haben, benutzen Sie einfach: - -@example -guix gc -F 5G -@end example - -It is perfectly safe to run as a non-interactive periodic job -(@pxref{Geplante Auftragsausführung}, for how to set up such a job). Running -@command{guix gc} with no arguments will collect as much garbage as it can, -but that is often inconvenient: you may find yourself having to rebuild 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 @command{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 -@code{--delete}), um Müllsammlerinformationen auszugeben oder -fortgeschrittenere Anfragen zu verarbeiten. Die -Müllsammler-Befehlszeilenoptionen sind wie folgt: - -@table @code -@item --collect-garbage[=@var{Minimum}] -@itemx -C [@var{Minimum}] -Lässt Müll sammeln — z.B. nicht erreichbare Dateien in @file{/gnu/store} und -seinen Unterverzeichnissen. Wird keine andere Befehlszeilenoption angegeben, -wird standardmäßig diese durchgeführt. - -Wenn ein @var{Minimum} angegeben wurde, hört der Müllsammler auf, sobald -@var{Minimum} Bytes gesammelt wurden. Das @var{Minimum} kann die Anzahl der -Bytes bezeichnen oder mit einer Einheit als Suffix versehen sein, wie etwa -@code{MiB} für Mebibytes und @code{GB} für Gigabytes (@pxref{Block size, -size specifications,, coreutils, GNU Coreutils}). - -Wird kein @var{Minimum} angegeben, sammelt der Müllsammler allen Müll. - -@item --free-space=@var{Menge} -@itemx -F @var{Menge} -Sammelt Müll, bis die angegebene @var{Menge} an freiem Speicher in -@file{/gnu/store} zur Verfügung steht, falls möglich; die @var{Menge} ist -eine Speichergröße wie @code{500MiB}, wie oben beschrieben. - -Wenn die angegebene @var{Menge} oder mehr bereits in @file{/gnu/store} frei -verfügbar ist, passiert nichts. - -@item --delete -@itemx -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. - -@item --list-failures -Store-Objekte auflisten, die zwischengespeicherten Erstellungsfehlern -entsprechen. - -Hierbei wird nichts ausgegeben, sofern der Daemon nicht mit -@option{--cache-failures} gestartet wurde (@pxref{Aufruf des guix-daemon, -@option{--cache-failures}}). - -@item --clear-failures -Die angegebenen Store-Objekte aus dem Zwischenspeicher für fehlgeschlagene -Erstellungen entfernen. - -Auch diese Option macht nur Sinn, wenn der Daemon mit -@option{--cache-failures} gestartet wurde. Andernfalls passiert nichts. - -@item --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. - -@item --list-live -Zeige die Liste lebendiger Store-Dateien und -Verzeichnisse. - -@end table - -Außerdem können Referenzen unter bestehenden Store-Dateien gefunden werden: - -@table @code - -@item --references -@itemx --referrers -@cindex Paketabhängigkeiten -Listet die referenzierten bzw. sie referenzierenden Objekte der angegebenen -Store-Dateien auf. - -@item --requisites -@itemx -R -@cindex Abschluss -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 @dfn{transitive Abschluss} dieser Store-Dateien. - -Der Abschnitt @xref{Aufruf von guix size} erklärt ein Werkzeug, um den -Speicherbedarf des Abschlusses eines Elements zu ermitteln. Siehe -@xref{Aufruf von guix graph} für ein Werkzeug, um den Referenzgraphen zu -veranschaulichen. - -@item --derivers -@cindex Ableitung -Liefert die Ableitung(en), die zu den angegebenen Store-Objekten führen -(@pxref{Ableitungen}). - -Zum Beispiel liefert dieser Befehl: - -@example -guix gc --derivers `guix package -I ^emacs$ | cut -f4` -@end example - -@noindent -die @file{.drv}-Datei(en), die zum in Ihrem Profil installierten -@code{emacs}-Paket führen. - -Beachten Sie, dass es auch sein kann, dass keine passenden -@file{.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 @file{.drv} gibt, bei Ableitungen mit fester Ausgabe. -@end table - -Zuletzt können Sie mit folgenden Befehlszeilenoptionen die Integrität des -Stores prüfen und den Plattenspeicherverbrauch im Zaum halten. - -@table @option - -@item --verify[=@var{Optionen}] -@cindex Integrität, des Stores -@cindex Integritätsprüfung -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 -@file{/gnu/store} existieren. - -Wenn angegeben, müssen die @var{Optionen} eine kommagetrennte Liste aus -mindestens einem der Worte @code{contents} und @code{repair} sein. - -Wenn Sie @option{--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 @emph{alle Dateien im Store} durchlaufen werden, kann -der Befehl viel Zeit brauchen, besonders auf Systemen mit langsamer Platte. - -@cindex Store, reparieren -@cindex Datenbeschädigung, Behebung -Mit @option{--verify=repair} oder @option{--verify=contents,repair} versucht -der Daemon, beschädigte Store-Objekte zu reparieren, indem er Substitute für -selbige herunterlädt (@pxref{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, @command{guix build --repair} zu benutzen -(@pxref{Aufruf von guix build}). - -@item --optimize -@cindex Deduplizieren -Den Store durch Nutzung harter Verknüpfungen für identische Dateien -optimieren — mit anderen Worten wird der Store @dfn{dedupliziert}. - -Der Daemon führt Deduplizierung automatisch nach jeder erfolgreichen -Erstellung und jedem Importieren eines Archivs durch, sofern er nicht mit -@code{--disable-deduplication} (@pxref{Aufruf des guix-daemon, -@code{--disable-deduplication}}) gestartet wurde. Diese Befehlszeilenoption -brauchen Sie also in erster Linie dann, wenn der Daemon zuvor mit -@code{--disable-deduplication} gestartet worden ist. - -@end table - -@node Aufruf von guix pull -@section @command{guix pull} aufrufen - -@cindex Aktualisieren von Guix -@cindex Updaten von Guix -@cindex @command{guix pull} -@cindex pull -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 -@command{guix pull} aus. Der Befehl lädt den neuesten Guix-Quellcode -einschließlich Paketbeschreibungen herunter und installiert ihn. Quellcode -wird aus einem @uref{https://git-scm.com, Git}-Repository geladen, -standardmäßig dem offiziellen Repository von GNU@tie{}Guix, was Sie aber -auch ändern können. - -Danach wird @command{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 @command{guix}-Unterbefehle, die durch die Aktualisierung -hinzugekommen sind, werden also auch verfügbar. - -Jeder Nutzer kann seine Kopie von Guix mittels @command{guix pull} -aktualisieren, wodurch sich nur für den Nutzer etwas verändert, der -@command{guix pull} ausgeführt hat. Wenn also zum Beispiel der -Administratornutzer @code{root} den Befehl @command{guix pull} ausführt, hat -das keine Auswirkungen auf die für den Benutzer @code{alice} sichtbare -Guix-Version, und umgekehrt. - -Das Ergebnis von @command{guix pull} ist ein als -@file{~/.config/guix/current} verfügbares @dfn{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 -(@pxref{Dokumentation}): - -@example -export PATH="$HOME/.config/guix/current/bin:$PATH" -export INFOPATH="$HOME/.config/guix/current/share/info:$INFOPATH" -@end example - -Die Befehlszeilenoption @code{--list-generations} oder kurz @code{-l} listet -ältere von @command{guix pull} erzeugte Generationen auf, zusammen mit -Informationen zu deren Provenienz. - -@example -$ 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, @dots{} - 69 packages upgraded: borg@@1.1.6, cheese@@3.28.0, @dots{} -@end example - -Im Abschnitt @ref{Aufruf von guix describe, @command{guix describe}} werden -andere Möglichkeiten erklärt, sich den momentanen Zustand von Guix -beschreiben zu lassen. - -Das Profil @code{~/.config/guix/current} verhält sich genau wie jedes andere -Profil, das von @command{guix package} erzeugt wurde (@pxref{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: - -@example -$ 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 -@end example - -Der Befehl @command{guix pull} wird in der Regel ohne Befehlszeilenargumente -aufgerufen, aber er versteht auch folgende Befehlszeilenoptionen: - -@table @code -@item --url=@var{URL} -@itemx --commit=@var{Commit} -@itemx --branch=@var{Branch} -Code wird von der angegebenen @var{URL} für den angegebenen @var{Commit} -(eine gültige Commit-ID, dargestellt als hexadezimale Zeichenkette) oder -@var{Branch} heruntergeladen. - -@cindex @file{channels.scm}, Konfigurationsdatei -@cindex Konfigurationsdatei für Kanäle -Diese Befehlszeilenoptionen sind manchmal bequemer, aber Sie können Ihre -Konfiguration auch in der Datei @file{~/.config/guix/channels.scm} oder über -die Option @option{--channels} angeben (siehe unten). - -@item --channels=@var{Datei} -@itemx -C @var{Datei} -Die Liste der Kanäle aus der angegebenen @var{Datei} statt aus -@file{~/.config/guix/channels.scm} auslesen. Die @var{Datei} muss -Scheme-Code enthalten, der zu einer Liste von Kanalobjekten ausgewertet -wird. Siehe @xref{Kanäle} für nähere Informationen. - -@item --list-generations[=@var{Muster}] -@itemx -l [@var{Muster}] -Alle Generationen von @file{~/.config/guix/current} bzw., wenn ein -@var{Muster} angegeben wird, die dazu passenden Generationen auflisten. Die -Syntax für das @var{Muster} ist dieselbe wie bei @code{guix package ---list-generations} (@pxref{Aufruf von guix package}). - -Im Abschnitt @ref{Aufruf von guix describe, @command{guix describe}} wird eine -Möglichkeit erklärt, sich Informationen nur über die aktuelle Generation -anzeigen zu lassen. - -@item --profile=@var{Profil} -@itemx -p @var{Profil} -Auf @var{Profil} anstelle von @file{~/.config/guix/current} arbeiten. - -@item --dry-run -@itemx -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. - -@item --system=@var{System} -@itemx -s @var{System} -Versuchen, für die angegebene Art von @var{System} geeignete Binärdateien zu -erstellen — z.B. @code{i686-linux} — statt für die Art von System, das die -Erstellung durchführt. - -@item --verbose -Ausführliche Informationen ausgeben und Erstellungsprotokolle auf der -Standardfehlerausgabe ausgeben. - -@item --bootstrap -Das neueste Guix mit dem Bootstrap-Guile erstellen. Diese -Befehlszeilenoption ist nur für Guix-Entwickler von Nutzen. -@end table - -Mit Hilfe von @dfn{Kanälen} können Sie bei @command{guix pull} anweisen, von -welchem Repository und welchem Branch Guix aktualisiert werden soll, sowie -von welchen @emph{weiteren} Repositorys Paketmodule bezogen werden -sollen. Im Abschnitt @xref{Kanäle} finden Sie nähere Informationen. - -Außerdem unterstützt @command{guix pull} alle gemeinsamen -Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}). - -@node Kanäle -@section Kanäle - -@cindex Kanäle -@cindex @file{channels.scm}, Konfigurationsdatei -@cindex Konfigurationsdatei für Kanäle -@cindex @command{guix pull}, Konfigurationsdatei -@cindex Konfiguration von @command{guix pull} -Guix und die Sammlung darin verfügbarer Pakete können Sie durch Ausführen -von @command{guix pull} aktualisieren (@pxref{Aufruf von guix pull}). Standardmäßig lädt @command{guix pull} Guix selbst vom offiziellen -Repository von GNU@tie{}Guix herunter und installiert es. Diesen Vorgang -können Sie anpassen, indem Sie @dfn{Kanäle} in der Datei -@file{~/.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 @command{guix pull} veranlassen, die Aktualisierungen von einem -oder mehreren Kanälen zu beziehen. Mit anderen Worten können Kanäle benutzt -werden, um Guix @emph{anzupassen} und zu @emph{erweitern}, wie wir im -Folgenden sehen werden. - -@subsection Einen eigenen Guix-Kanal benutzen - -Der Kanal namens @code{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 @code{example.org} zu finden ist, und zwar im -Branch namens @code{super-hacks}, dann schreiben Sie folgende Spezifikation -in @code{~/.config/guix/channels.scm}: - -@lisp -;; 'guix pull' mein eigenes Repository benutzen lassen. -(list (channel - (name 'guix) - (url "https://example.org/my-guix.git") - (branch "super-hacks"))) -@end lisp - -@noindent -Ab dann wird @command{guix pull} seinen Code vom Branch @code{super-hacks} -des Repositorys auf @code{example.org} beziehen. - -@subsection Weitere Kanäle angeben - -@cindex Paketsammlung erweitern (Kanäle) -@cindex Eigene Pakete (Kanäle) -@cindex Kanäle, für eigene Pakete -Sie können auch @emph{weitere Kanäle} als Bezugsquelle angeben. Sagen wir, -Sie haben ein paar eigene Paketvarianten oder persönliche Pakete, von denen -Sie meinen, dass sie @emph{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 (@pxref{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? - -@c What follows stems from discussions at -@c <https://debbugs.gnu.org/cgi/bugreport.cgi?bug=22629#134> as well as -@c earlier discussions on guix-devel@gnu.org. -@quotation Warnung -Bevor Sie, verehrter Nutzer, ausrufen: »Wow, das ist @emph{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: - -@itemize -@item -Bevor Sie einen Kanal veröffentlichen, überlegen Sie sich bitte erst, ob Sie -die Pakete nicht besser zum eigentlichen Guix-Projekt beisteuern -(@pxref{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. - -@item -Wenn Sie Paketdefinitionen außerhalb von Guix betreuen, sehen wir -Guix-Entwickler es als @emph{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 @emph{nicht} versprechen, APIs nicht zu verändern. - -@item -Das bedeutet auch, dass Sie, wenn Sie einen externen Kanal verwenden und -dieser kaputt geht, Sie dies bitte @emph{den Autoren des Kanals} und nicht -dem Guix-Projekt melden. -@end itemize - -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 -@uref{https://www.gnu.org/philosophy/free-sw.html, freier Software} -entspricht. Bitte schicken Sie eine E-Mail an @email{guix-devel@@gnu.org}, -wenn Sie dies diskutieren möchten. -@end quotation - -To use a channel, write @code{~/.config/guix/channels.scm} to instruct -@command{guix pull} to pull from it @emph{in addition} to the default Guix -channel(s): - -@vindex %default-channels -@lisp -;; 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) -@end lisp - -@noindent -Note that the snippet above is (as always!)@: Scheme code; we use -@code{cons} to add a channel the list of channels that the variable -@code{%default-channels} is bound to (@pxref{Pairs, @code{cons} and lists,, -guile, GNU Guile Reference Manual}). With this file in place, @command{guix -pull} builds not only Guix but also the package modules from your own -repository. The result in @file{~/.config/guix/current} is the union of -Guix with your own package modules: - -@example -$ guix pull --list-generations -@dots{} -Generation 19 Aug 27 2018 16:20:48 - guix d894ab8 - repository URL: https://git.savannah.gnu.org/git/guix.git - branch: master - commit: d894ab8e9bfabcefa6c49d9ba2e834dd5a73a300 - 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, @dots{} - 4 packages upgraded: emacs-racket-mode@@0.0.2-2.1b78827, @dots{} -@end example - -@noindent -Obige Ausgabe von @command{guix pull} zeigt an, dass Generation@tie{}19 -sowohl Guix als auch Pakete aus dem Kanal @code{meine-persönlichen-pakete} -enthält. Unter den aufgeführten neuen und aktualisierten Paketen kommen -vielleicht manche wie @code{mein-gimp} und -@code{mein-emacs-mit-coolen-features} aus @code{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 (@pxref{Load -Paths,,, guile, GNU Guile Reference Manual}). For example, if your channel -contains a file at @file{my-packages/my-tools.scm} that defines a Guile -module, then the module will be available under the name @code{(my-packages -my-tools)}, and you will be able to use it like any other module -(@pxref{Module,,, guile, GNU Guile Reference Manual}). - -@cindex dependencies, channels -@cindex meta-data, channels -@subsection Declaring Channel Dependencies - -Channel authors may decide to augment a package collection provided by other -channels. They can declare their channel to be dependent on other channels -in a meta-data file @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: - -@lisp -(channel - (version 0) - (dependencies - (channel - (name some-collection) - (url "https://example.org/first-collection.git")) - (channel - (name some-other-collection) - (url "https://example.org/second-collection.git") - (branch "testing")))) -@end lisp - -In the above example this channel is declared to depend on two 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. - -@subsection Guix nachbilden - -@cindex Festsetzen, bei Kanälen -@cindex Nachbilden von Guix -@cindex Reproduzierbarkeit von Guix -Die Ausgabe von @command{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 @file{~/.config/guix/channels.scm} angeben, die auf -diese Commits »festgesetzt« ist. - -@lisp -;; 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"))) -@end lisp - -Der Befehl @command{guix describe --format=channels} kann diese Kanalliste -sogar direkt erzeugen (@pxref{Aufruf von guix describe}). - -Somit läuft auf beiden Maschinen @emph{genau dasselbe Guix} und es hat -Zugang zu @emph{genau denselben Paketen}. Die Ausgabe von @command{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 -@xref{Untergeordnete} beschreibt eine weitere Möglichkeit, diese Superkräfte zu -nutzen. - -@node Untergeordnete -@section Untergeordnete - -@c TODO: Remove this once we're more confident about API stability. -@quotation Anmerkung -Die hier beschriebenen Funktionalitäten sind in der Version @value{VERSION} -bloß eine »Technologie-Vorschau«, daher kann sich die Schnittstelle in -Zukunft noch ändern. -@end quotation - -@cindex Untergeordnete -@cindex Mischen von Guix-Versionen -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-@dfn{Untergeordnete} ermöglichen dies, indem Sie verschiedene -Guix-Versionen beliebig mischen können. - -@cindex untergeordnete Pakete -Aus technischer Sicht ist ein »Untergeordneter« im Kern ein separater -Guix-Prozess, der über eine REPL (@pxref{Aufruf von guix repl}) mit Ihrem -Haupt-Guix-Prozess verbunden ist. Das Modul @code{(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 — @dfn{untergeordnete Pakete}. - -In Kombination mit Kanälen (@pxref{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 -@code{guile}-Paket in Ihr Profil installieren, zusammen mit dem -@code{guile-json}, wie es in einer früheren Guix-Version existiert hat — -vielleicht weil das neuere @code{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 @code{guix package --manifest} schreiben (@pxref{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 @code{guile-json}-Paket holen: - -@lisp -(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"))) -@end lisp - -Bei seiner ersten Ausführung könnte für @command{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 @code{(guix inferior)} angeboten, um -einen Untergeordneten zu öffnen: - -@deffn {Scheme-Prozedur} inferior-for-channels @var{Kanäle} @ - [#:cache-directory] [#:ttl] Liefert einen Untergeordneten für die -@var{Kanäle}, einer Liste von Kanälen. Dazu wird der Zwischenspeicher im -Verzeichnis @var{cache-directory} benutzt, dessen Einträge nach @var{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 @var{Kanäle}, was einige Zeit in Anspruch nehmen kann. -@end deffn - -@deffn {Scheme-Prozedur} open-inferior @var{Verzeichnis} @ - [#:command "bin/guix"] Öffnet das untergeordnete Guix mit dem Befehl -@var{command} im angegebenen @var{Verzeichnis} durch Ausführung von -@code{@var{Verzeichnis}/@var{command} repl} oder entsprechend. Liefert -@code{#f}, wenn der Untergeordnete nicht gestartet werden konnte. -@end deffn - -@cindex untergeordnete Pakete -Die im Folgenden aufgeführten Prozeduren ermöglichen es Ihnen, -untergeordnete Pakete abzurufen und zu verändern. - -@deffn {Scheme-Prozedur} inferior-packages @var{Untergeordneter} -Liefert die Liste der Pakete in @var{Untergeordneter}. -@end deffn - -@deffn {Scheme-Prozedur} lookup-inferior-packages @var{Untergeordneter} @var{Name} @ - [@var{Version}] Liefert die sortierte Liste der untergeordneten Pakete in -@var{Untergeordneter}, die zum Muster @var{Name} in @var{Untergeordneter} -passen, dabei kommen höhere Versionsnummern zuerst. Wenn @var{Version} auf -wahr gesetzt ist, werden nur Pakete geliefert, deren Versionsnummer mit dem -Präfix @var{Version} beginnt. -@end deffn - -@deffn {Scheme-Prozedur} inferior-package? @var{Objekt} -Liefert wahr, wenn das @var{obj} ein Untergeordneter ist. -@end deffn - -@deffn {Scheme-Prozedur} inferior-package-name @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-version @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-synopsis @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-description @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-home-page @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-location @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-inputs @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-native-inputs @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-propagated-inputs @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-transitive-propagated-inputs @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-native-search-paths @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-transitive-native-search-paths @var{Paket} -@deffnx {Scheme-Prozedur} inferior-package-search-paths @var{Paket} -Diese Prozeduren sind das Gegenstück zu den Zugriffsmethoden des Verbunds -»package« für Pakete (@pxref{»package«-Referenz}). Die meisten davon -funktionieren durch eine Abfrage auf dem Untergeordneten, von dem das -@var{Paket} kommt, weshalb der Untergeordnete noch lebendig sein muss, wenn -Sie diese Prozeduren aufrufen. -@end deffn - -Untergeordnete Pakete können transparent wie jedes andere Paket oder -dateiartige Objekt in G-Ausdrücken verwendet werden -(@pxref{G-Ausdrücke}). Sie werden auch transparent wie reguläre Pakete von -der Prozedur @code{packages->manifest} behandelt, welche oft in Manifesten -benutzt wird (@pxref{Aufruf von guix package, siehe die Befehlszeilenoption -@option{--manifest} von @command{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 @code{packages} Ihrer -@code{operating-system}-Deklaration und so weiter. - -@node Aufruf von guix describe -@section @command{guix describe} aufrufen - -@cindex Reproduzierbarkeit -@cindex Nachbilden von Guix -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 @emph{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 @command{guix describe} -gibt Ihnen Antwort auf diese Fragen. - -Wenn Sie ihn aus einem mit @command{guix pull} bezogenen @command{guix} -heraus ausführen, zeigt Ihnen @command{guix describe} die Kanäle an, aus -denen es erstellt wurde, jeweils mitsamt ihrer Repository-URL und Commit-ID -(@pxref{Kanäle}): - -@example -$ 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 -@end example - -Wenn Sie mit dem Versionskontrollsystem Git vertraut sind, erkennen Sie -vielleicht die Ähnlichkeit zu @command{git describe}; die Ausgabe ähnelt -auch der von @command{guix pull --list-generations} eingeschränkt auf die -aktuelle Generation (@pxref{Aufruf von guix pull, die Befehlszeilenoption -@option{--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 @command{guix describe} -auch eine Liste der Kanäle statt einer menschenlesbaren Beschreibung wie -oben liefern: - -@example -$ guix describe -f channels -(list (channel - (name 'guix) - (url "https://git.savannah.gnu.org/git/guix.git") - (commit - "e0fa68c7718fffd33d81af415279d6ddb518f727"))) -@end example - -@noindent -Sie können die Ausgabe in einer Datei speichern, die Sie an @command{guix -pull -C} auf einer anderen Maschine oder zu einem späteren Zeitpunkt -übergeben, wodurch dann eine Instanz @emph{von genau derselben Guix-Version} -installiert wird (@pxref{Aufruf von guix pull, die Befehlszeilenoption -@option{-C}}). Daraufhin können Sie, weil Sie jederzeit dieselbe Version von -Guix installieren können, auch gleich @emph{eine vollständige -Softwareumgebung genau nachbilden}. Wir halten das trotz aller -Bescheidenheit für @emph{klasse} und hoffen, dass Ihnen das auch gefällt! - -Die genauen Befehlszeilenoptionen, die @command{guix describe} unterstützt, -lauten wie folgt: - -@table @code -@item --format=@var{Format} -@itemx -f @var{Format} -Die Ausgabe im angegebenen @var{Format} generieren, was eines der Folgenden -sein muss: - -@table @code -@item human -für menschenlesbare Ausgabe, -@item Kanäle -eine Liste von Kanalspezifikationen erzeugen, die an @command{guix pull -C} -übergeben werden oder als @file{~/.config/guix/channels.scm} eingesetzt -werden können (@pxref{Aufruf von guix pull}), -@item json -@cindex JSON -generiert eine Liste von Kanalspezifikationen im JSON-Format, -@item recutils -generiert eine Liste von Kanalspezifikationen im Recutils-Format. -@end table - -@item --profile=@var{Profil} -@itemx -p @var{Profil} -Informationen über das @var{Profil} anzeigen. -@end table - -@node Aufruf von guix archive -@section @command{guix archive} aufrufen - -@cindex @command{guix archive} -@cindex Archivdateien -Der Befehl @command{guix archive} ermöglicht es Nutzern, Dateien im Store in -eine einzelne Archivdatei zu @dfn{exportieren} und diese später auf einer -Maschine, auf der Guix läuft, zu @dfn{importieren}. Insbesondere können so -Store-Objekte von einer Maschine in den Store einer anderen Maschine -übertragen werden. - -@quotation Anmerkung -Wenn Sie nach einer Möglichkeit suchen, Archivdateien für andere Werkzeuge -als Guix zu erstellen, finden Sie Informationen dazu im Abschnitt -@pxref{Aufruf von guix pack}. -@end quotation - -@cindex Store-Objekte exportieren -Führen Sie Folgendes aus, um Store-Dateien als ein Archiv auf die -Standardausgabe zu exportieren: - -@example -guix archive --export @var{Optionen} @var{Spezifikationen}... -@end example - -@var{Spezifikationen} sind dabei entweder die Namen von Store-Dateien oder -Paketspezifikationen wie bei @command{guix package} (@pxref{Aufruf von guix package}). Zum Beispiel erzeugt der folgende Befehl ein Archiv der -@code{gui}-Ausgabe des Pakets @code{git} sowie die Hauptausgabe von -@code{emacs}: - -@example -guix archive --export git:gui /gnu/store/...-emacs-24.3 > groß.nar -@end example - -Wenn die angegebenen Pakete noch nicht erstellt worden sind, werden sie -durch @command{guix archive} automatisch erstellt. Der Erstellungsprozess -kann durch die gemeinsamen Erstellungsoptionen gesteuert werden -(@pxref{Gemeinsame Erstellungsoptionen}). - -Um das @code{emacs}-Paket auf eine über SSH verbundene Maschine zu -übertragen, würde man dies ausführen: - -@example -guix archive --export -r emacs | ssh die-maschine guix archive --import -@end example - -@noindent -Auf gleiche Art kann auch ein vollständiges Benutzerprofil von einer -Maschine auf eine andere übertragen werden: - -@example -guix archive --export -r $(readlink -f ~/.guix-profile) | \ - ssh die-maschine guix-archive --import -@end example - -@noindent -Jedoch sollten Sie in beiden Beispielen beachten, dass alles, was zu -@code{emacs}, dem Profil oder deren Abhängigkeiten (wegen @code{-r}) gehört, -übertragen wird, egal ob es schon im Store der Zielmaschine vorhanden ist -oder nicht. Mit der Befehlszeilenoption @code{--missing} lässt sich -herausfinden, welche Objekte im Ziel-Store noch fehlen. Der Befehl -@command{guix copy} vereinfacht und optimiert diesen gesamten Prozess, ist -also, was Sie in diesem Fall wahrscheinlich eher benutzen wollten -(@pxref{Aufruf von guix copy}). - -@cindex Nar, Archivformat -@cindex Normalisiertes Archiv (Nar) -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. - -@c FIXME: Add xref to daemon doc about signatures. -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: - -@table @code -@item --export -Exportiert die angegebenen Store-Dateien oder Pakete (siehe unten) und -schreibt das resultierende Archiv auf die Standardausgabe. - -Abhängigkeiten @emph{fehlen} in der Ausgabe, außer wenn @code{--recursive} -angegeben wurde. - -@item -r -@itemx --recursive -Zusammen mit @code{--export} wird @command{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. - -@item --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 @code{--authorize} -weiter unten). - -@item --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. - -@item --generate-key[=@var{Parameter}] -@cindex Signieren, von Archiven -Ein neues Schlüsselpaar für den Daemon erzeugen. Dies ist erforderlich, -damit Archive mit @code{--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 @file{/etc/guix} -gespeichert, in den Dateien @file{signing-key.pub} (für den öffentlichen -Schlüssel) und @file{signing-key.sec} (für den privaten Schlüssel, der -geheim gehalten werden muss). Wurden keine @var{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 @var{Parameter} für Libgcrypt geeignete Parameter für -@code{genkey} an (@pxref{General public-key related Functions, -@code{gcry_pk_genkey},, gcrypt, The Libgcrypt Reference Manual}). - -@item --authorize -@cindex Autorisieren, von Archiven -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 @file{signing-key.pub}. - -Die Liste autorisierter Schlüssel wird in der Datei @file{/etc/guix/acl} -gespeichert, die auch von Hand bearbeitet werden kann. Die Datei enthält -@url{http://people.csail.mit.edu/rivest/Sexp.txt, »advanced«-formatierte -S-Ausdrücke} und ist als eine Access Control List für die -@url{http://theworld.com/~cme/spki.txt, Simple Public-Key Infrastructure -(SPKI)} aufgebaut. - -@item --extract=@var{Verzeichnis} -@itemx -x @var{Verzeichnis} -Ein Archiv mit einem einzelnen Objekt lesen, wie es von Substitutservern -geliefert wird (@pxref{Substitute}) und ins @var{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 @code{@value{SUBSTITUTE-SERVER}} to @file{/tmp/emacs}: - -@example -$ wget -O - \ - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-emacs-24.5 \ - | bunzip2 | guix archive -x /tmp/emacs -@end example - -Archive mit nur einem einzelnen Objekt unterscheiden sich von Archiven für -mehrere Dateien, wie sie @command{guix archive --export} erzeugt; sie -enthalten nur ein einzelnes Store-Objekt und @emph{keine} eingebettete -Signatur. Beim Entpacken findet also @emph{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. - -@end table - - -@c ********************************************************************* -@node Development -@chapter Development - -@cindex software 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 @command{guix environment} command provides a convenient way to set up -@dfn{development environments} containing all the dependencies and tools -necessary to work on the software package of your choice. The @command{guix -pack} command allows you to create @dfn{application bundles} that can be -easily distributed to users who do not run Guix. - -@menu -* Aufruf von guix environment:: Entwicklungsumgebungen einrichten. -* Aufruf von guix pack:: Software-Bündel erstellen. -@end menu - -@node Aufruf von guix environment -@section @command{guix environment} aufrufen - -@cindex reproduzierbare Erstellungsumgebungen -@cindex Entwicklungsumgebungen -@cindex @command{guix environment} -@cindex Umgebung, Paketerstellungsumgebung -Der Zweck von @command{guix environment} ist es, Hacker beim Aufbau einer -reproduzierbaren Entwicklungsumgebung zu unterstützen, ohne dass diese ihr -Paketprofil verunreinigen müssen. Das Werkzeug @command{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: - -@example -guix environment @var{Optionen} @var{Paket}@dots{} -@end example - -Folgendes Beispiel zeigt, wie eine neue Shell gestartet wird, auf der alles -für die Entwicklung von GNU@tie{}Guile eingerichtet ist: - -@example -guix environment guile -@end example - -Wenn benötigte Abhängigkeiten noch nicht erstellt worden sind, wird -@command{guix environment} sie automatisch erstellen lassen. Die Umgebung -der neuen Shell ist eine ergänzte Version der Umgebung, in der @command{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 @code{--pure} benutzt werden@footnote{Manchmal ergänzen -Nutzer fälschlicherweise Umgebungsvariable wie @code{PATH} in ihrer -@file{~/.bashrc}-Datei. Das hat zur Folge, dass wenn @code{guix environment} -Bash startet, selbige @file{~/.bashrc} von Bash gelesen wird und die neuen -Umgebungen somit »verunreinigt«. Es ist ein Fehler, solche Umgebungsvariable -in @file{.bashrc} zu definieren, stattdessen sollten sie in -@file{.bash_profile} geschrieben werden, was nur von Login-Shells mit -»source« geladen wird. @xref{Bash Startup Files,,, bash, The GNU Bash -Reference Manual}, für Details über beim Starten von Bash gelesene Dateien}. - -@vindex GUIX_ENVIRONMENT -@command{guix environment} definiert die Variable @code{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 -@file{.bashrc} festzulegen (@pxref{Bash Startup Files,,, bash, The GNU Bash -Reference Manual}): - -@example -if [ -n "$GUIX_ENVIRONMENT" ] -then - export PS1="\u@@\h \w [dev]\$ " -fi -@end example - -@noindent -...@: or to browse the profile: - -@example -$ ls "$GUIX_ENVIRONMENT/bin" -@end example - -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: - -@example -guix environment guile emacs -@end example - -Manchmal will man keine interaktive Shell-Sitzung. Ein beliebiger Befehl -kann aufgerufen werden, indem man nach Angabe der Pakete noch @code{--} vor -den gewünschten Befehl schreibt, um ihn von den übrigen Argumenten -abzutrennen: - -@example -guix environment guile -- make -j4 -@end example - -In anderen Situationen ist es bequemer, aufzulisten, welche Pakete in der -Umgebung benötigt werden. Zum Beispiel führt der folgende Befehl -@command{python} aus einer Umgebung heraus aus, in der Python@tie{}2.7 und -NumPy enthalten sind: - -@example -guix environment --ad-hoc python2-numpy python-2.7 -- python -@end example - -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 @code{--ad-hoc} ab. Pakete, die links von -@code{--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: - -@example -guix environment guix --ad-hoc git strace -@end example - -Sometimes it is desirable to isolate the environment as much as possible, -for maximal purity and reproducibility. In particular, when using Guix on a -host distro that is not Guix System, it is desirable to prevent access to -@file{/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: - -@example -guix environment --ad-hoc --container guile -- guile -@end example - -@quotation Anmerkung -Die Befehlszeilenoption @code{--container} funktioniert nur mit Linux-libre -3.19 oder neuer. -@end quotation - -Im Folgenden werden die verfügbaren Befehlszeilenoptionen zusammengefasst. - -@table @code -@item --root=@var{file} -@itemx -r @var{file} -@cindex persistente Umgebung -@cindex Müllsammlerwurzel, für Umgebungen -Die @var{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 -@command{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. @xref{Aufruf von guix gc} hat mehr Informationen über Müllsammlerwurzeln. - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Eine Umgebung für das Paket oder die Liste von Paketen erzeugen, zu der der -@var{Ausdruck} ausgewertet wird. - -Zum Beispiel startet dies: - -@example -guix environment -e '(@@ (gnu packages maths) petsc-openmpi)' -@end example - -eine Shell mit der Umgebung für eben diese bestimmte Variante des Pakets -PETSc. - -Wenn man dies ausführt: - -@example -guix environment --ad-hoc -e '(@@ (gnu) %base-packages)' -@end example - -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: - -@example -guix environment --ad-hoc -e '(list (@@ (gnu packages bash) bash) "include")' -@end example - -@item --load=@var{Datei} -@itemx -l @var{Datei} -Eine Umgebung erstellen für das Paket oder die Liste von Paketen, zu der der -Code in der @var{Datei} ausgewertet wird. - -Zum Beispiel könnte die @var{Datei} eine Definition wie diese enthalten -(@pxref{Pakete definieren}): - -@example -@verbatiminclude environment-gdb.scm -@end example - -@item --manifest=@var{Datei} -@itemx -m @var{Datei} -Eine Umgebung für die Pakete erzeugen, die im Manifest-Objekt enthalten -sind, das vom Scheme-Code in der @var{Datei} geliefert wird. - -Dies verhält sich ähnlich wie die gleichnamige Option des Befehls -@command{guix package} (@pxref{profile-manifest, @option{--manifest}}) und -benutzt auch dieselben Manifestdateien. - -@item --ad-hoc -Alle angegebenen Pakete in der resultierenden Umgebung einschließen, als -wären sie Eingaben eines @i{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: - -@example -guix environment --ad-hoc guile guile-sdl -- guile -@end example - -@command{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 -@code{guile} und @code{guile-sdl} verwendet wird, es aber auch möglich ist, -eine bestimmte Ausgabe auszuwählen — z.B. wird mit @code{glib:bin} die -Ausgabe @code{bin} von @code{glib} gewählt (@pxref{Pakete mit mehreren Ausgaben.}). - -Diese Befehlszeilenoption kann mit dem standardmäßigen Verhalten von -@command{guix environment} verbunden werden. Pakete, die vor @code{--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. - -@item --pure -Unset existing environment variables when building the new environment, -except those specified with @option{--preserve} (see below.) This has the -effect of creating an environment in which search paths only contain package -inputs. - -@item --preserve=@var{regexp} -@itemx -E @var{regexp} -When used alongside @option{--pure}, preserve the environment variables -matching @var{regexp}---in other words, put them on a ``white list'' of -environment variables that must be preserved. This option can be repeated -several times. - -@example -guix environment --pure --preserve=^SLURM --ad-hoc openmpi @dots{} \ - -- mpirun @dots{} -@end example - -This example runs @command{mpirun} in a context where the only environment -variables defined are @code{PATH}, environment variables whose name starts -with @code{SLURM}, as well as the usual ``precious'' variables (@code{HOME}, -@code{USER}, etc.) - -@item --search-paths -Die Umgebungsvariablendefinitionen anzeigen, aus denen die Umgebung besteht. - -@item --system=@var{System} -@itemx -s @var{System} -Versuchen, für das angegebene @var{System} zu erstellen — -z.B. @code{i686-linux}. - -@item --container -@itemx -C -@cindex container -Den @var{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 @code{--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 @file{/etc/passwd}. Der erzeugte Prozess läuft außerhalb des -Containers als der momentane Nutzer, aber im Kontext des Containers hat er -Administratorrechte. - -@item --network -@itemx -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. - -@item --link-profile -@itemx -P -Bei isolierten Umgebungen (»Containern«) wird das Umgebungsprofil im -Container als @file{~/.guix-profile} verknüpft. Das ist äquivalent dazu, den -Befehl @command{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 @command{guix environment} im persönlichen Verzeichnis des -Benutzers aufgerufen wurde. - -Bestimmte Pakete sind so eingerichtet, dass sie in @code{~/.guix-profile} -nach Konfigurationsdateien und Daten suchen,@footnote{Zum Beispiel -inspiziert das Paket @code{fontconfig} das Verzeichnis -@file{~/.guix-profile/share/fonts}, um zusätzliche Schriftarten zu finden.} -weshalb @code{--link-profile} benutzt werden kann, damit sich diese -Programme auch in der isolierten Umgebung wie erwartet verhalten. - -@item --user=@var{Benutzer} -@itemx -u @var{Benutzer} -Bei isolierten Umgebungen (»Containern«) wird der Benutzername -@var{Benutzer} anstelle des aktuellen Benutzers benutzt. Der erzeugte -Eintrag in @file{/etc/passwd} im Container wird also den Namen -@var{Benutzer} enthalten und das persönliche Verzeichnis wird den Namen -@file{/home/BENUTZER} tragen; keine GECOS-Daten über den Nutzer werden in -die Umgebung übernommen. @var{Benutzer} muss auf dem System nicht -existieren. - -Zusätzlich werden alle geteilten oder exponierten Pfade (siehe jeweils -@code{--share} und @code{--expose}), deren Ziel innerhalb des persönlichen -Verzeichnisses des aktuellen Benutzers liegt, relativ zu -@file{/home/BENUTZER} erscheinen, einschließlich der automatischen Zuordnung -des aktuellen Arbeitsverzeichnisses. - -@example -# 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 -@end example - -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. - -@item --expose=@var{Quelle}[=@var{Ziel}] -Bei isolierten Umgebungen (»Containern«) wird das Dateisystem unter -@var{Quelle} vom Wirtssystem als Nur-Lese-Dateisystem @var{Ziel} im -Container zugänglich gemacht. Wenn kein @var{Ziel} angegeben wurde, wird die -@var{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 -@file{/austausch} nur für Lesezugriffe zugänglich gemacht wurde: - -@example -guix environment --container --expose=$HOME=/austausch --ad-hoc guile -- guile -@end example - -@item --share=@var{Quelle}[=@var{Ziel}] -Bei isolierten Umgebungen (»Containern«) wird das Dateisystem unter -@var{Quelle} vom Wirtssystem als beschreibbares Dateisystem @var{Ziel} im -Container zugänglich gemacht. Wenn kein @var{Ziel} angegeben wurde, wird die -@var{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 -@file{/austausch} sowohl für Lese- als auch für Schreibzugriffe zugänglich -gemacht wurde: - -@example -guix environment --container --share=$HOME=/austausch --ad-hoc guile -- guile -@end example -@end table - -@command{guix environment} also supports all of the common build options -that @command{guix build} supports (@pxref{Gemeinsame Erstellungsoptionen}) as well as -package transformation options (@pxref{Paketumwandlungsoptionen}). - -@node Aufruf von guix pack -@section @command{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 @command{guix package --i @var{irgendetwas}} einzutippen brauchen, aber wenn sie kein Guix haben, -muss es anders gehen. Hier kommt @command{guix pack} ins Spiel. - -@quotation Anmerkung -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 @pxref{Aufruf von guix copy}, @ref{Aufruf von guix publish} und -@ref{Aufruf von guix archive} werfen. -@end quotation - -@cindex Pack -@cindex Bündel -@cindex Anwendungsbündel -@cindex Software-Bündel -Der Befehl @command{guix pack} erzeugt ein gut verpacktes -@dfn{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: - -@example -$ guix pack guile emacs geiser -@dots{} -/gnu/store/@dots{}-pack.tar.gz -@end example - -Als Ergebnis erhalten Sie einen Tarball mit einem Verzeichnis -@file{/gnu/store}, worin sich alles relevanten Pakete befinden. Der -resultierende Tarball enthält auch ein @dfn{Profil} mit den drei angegebenen -Paketen; es ist dieselbe Art von Profil, die auch @command{guix package -i} -erzeugen würde. Mit diesem Mechanismus wird auch der binäre Tarball zur -Installation von Guix erzeugt (@pxref{Aus Binärdatei installieren}). - -Benutzer des Bündels müssten dann aber zum Beispiel -@file{/gnu/store/@dots{}-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 @file{/opt/gnu/bin} auf das Profil anlegen: - -@example -guix pack -S /opt/gnu/bin=bin guile emacs geiser -@end example - -@noindent -Benutzer müssten dann nur noch @file{/opt/gnu/bin/guile} eintippen, um Guile -zu genießen. - -@cindex pfad-agnostische Binärdateien, mit @command{guix pack} -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 @code{--relocatable} benutzen (siehe weiter unten). Mit -dieser Option werden @dfn{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 -@file{./opt/gnu/bin/guile} ausführen. - -@cindex Docker, ein Abbild erstellen mit guix pack -Eine weitere Möglichkeit ist, das Bündel im Format eines Docker-Abbilds -(englisch Docker-Image) zu erzeugen. Das geht mit dem folgenden Befehl: - -@example -guix pack -f docker guile emacs geiser -@end example - -@noindent -Das Ergebnis ist ein Tarball, der dem Befehl @command{docker load} übergeben -werden kann. In der -@uref{https://docs.docker.com/engine/reference/commandline/load/, -Dokumentation von Docker} finden Sie nähere Informationen. - -@cindex Singularity, ein Abbild erstellen mit guix pack -@cindex SquashFS, ein Abbild erstellen mit guix pack -Und noch eine weitere Möglichkeit ist, dass Sie ein SquashFS-Abbild mit -folgendem Befehl erzeugen: - -@example -guix pack -f squashfs guile emacs geiser -@end example - -@noindent -Das Ergebnis ist ein SquashFS-Dateisystemabbild, dass entweder als -Dateisystem eingebunden oder mit Hilfe der @uref{http://singularity.lbl.gov, -Singularity-Container-Ausführungsumgebung} als Dateisystemcontainer benutzt -werden kann, mit Befehlen wie @command{singularity shell} oder -@command{singularity exec}. - -Es gibt mehrere Befehlszeilenoptionen, mit denen Sie Ihr Bündel anpassen -können: - -@table @code -@item --format=@var{Format} -@itemx -f @var{Format} -Generiert ein Bündel im angegebenen @var{Format}. - -Die verfügbaren Formate sind: - -@table @code -@item tarball -Das standardmäßig benutzte Format. Damit wird ein Tarball generiert, der -alle angegebenen Binärdateien und symbolischen Verknüpfungen enthält. - -@item docker -Generiert einen Tarball gemäß der -@uref{https://github.com/docker/docker/blob/master/image/spec/v1.2.md, -Docker Image Specification}, d.h. der Spezifikation für Docker-Abbilder. - -@item 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. -@end table - -@item --relocatable -@itemx -R -Erzeugt @dfn{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: - -@example -guix pack -R -S /meine-bin=bin bash -@end example - -@noindent -...@: you can copy that pack to a machine that lacks Guix, and from your -home directory as a normal user, run: - -@example -tar xf pack.tar.gz -./meine-bin/sh -@end example - -@noindent -Wenn Sie in der so gestarteten Shell dann @code{ls /gnu/store} eintippen, -sehen Sie, dass Ihnen angezeigt wird, in @file{/gnu/store} befänden sich -alle Abhängigkeiten von @code{bash}, obwohl auf der Maschine überhaupt kein -Verzeichnis @file{/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 -@dfn{Benutzernamensräumen} (englisch @dfn{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 @emph{werden -Programme aus dem Bündel nicht funktionieren}, solange sie nicht in das -echte Wurzeldateisystem entpackt werden. - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Paket benutzen, wozu der @var{Ausdruck} ausgewertet wird. - -Der Zweck hiervon ist derselbe wie bei der gleichnamigen Befehlszeilenoption -in @command{guix build} (@pxref{Zusätzliche Erstellungsoptionen, -@code{--expression} in @command{guix build}}). - -@item --manifest=@var{Datei} -@itemx -m @var{Datei} -Die Pakete benutzen, die im Manifest-Objekt aufgeführt sind, das vom -Scheme-Code in der angegebenen @var{Datei} geliefert wird. - -Dies hat einen ähnlichen Zweck wie die gleichnamige Befehlszeilenoption in -@command{guix package} (@pxref{profile-manifest, @option{--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 @emph{entweder} eine -Manifest-Datei @emph{oder} eine Liste von Paketen angeben können, aber nicht -beides. - -@item --system=@var{System} -@itemx -s @var{System} -Versuchen, für die angegebene Art von @var{System} geeignete Binärdateien zu -erstellen — z.B. @code{i686-linux} — statt für die Art von System, das die -Erstellung durchführt. - -@item --target=@var{Tripel} -@cindex Cross-Kompilieren -Lässt für das angegebene @var{Tripel} cross-erstellen, dieses muss ein -gültiges GNU-Tripel wie z.B. @code{"mips64el-linux-gnu"} sein -(@pxref{Specifying target triplets, GNU configuration triplets,, autoconf, -Autoconf}). - -@item --compression=@var{Werkzeug} -@itemx -C @var{Werkzeug} -Komprimiert den resultierenden Tarball mit dem angegebenen @var{Werkzeug} — -dieses kann @code{gzip}, @code{bzip2}, @code{xz}, @code{lzip} oder -@code{none} für keine Kompression sein. - -@item --symlink=@var{Spezifikation} -@itemx -S @var{Spezifikation} -Fügt die in der @var{Spezifikation} festgelegten symbolischen Verknüpfungen -zum Bündel hinzu. Diese Befehlszeilenoption darf mehrmals vorkommen. - -Die @var{Spezifikation} muss von der Form -@code{@var{Quellort}=@var{Zielort}} sein, wobei der @var{Quellort} der Ort -der symbolischen Verknüpfung, die erstellt wird, und @var{Zielort} das Ziel -der symbolischen Verknüpfung ist. - -Zum Beispiel wird mit @code{-S /opt/gnu/bin=bin} eine symbolische -Verknüpfung @file{/opt/gnu/bin} auf das Unterverzeichnis @file{bin} im -Profil erzeugt. - -@item --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 -(@pxref{Kanäle}). - -Provenance information is saved in the -@file{/gnu/store/@dots{}-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. - -@item --localstatedir -@itemx --profile-name=@var{Name} -Das »lokale Zustandsverzeichnis« @file{/var/guix} ins resultierende Bündel -aufnehmen, speziell auch das Profil -@file{/var/guix/profiles/per-user/root/@var{Name}} — der vorgegebene -@var{Name} ist @code{guix-profile}, was @file{~root/.guix-profile} -entspricht. - -@file{/var/guix} enthält die Store-Datenbank (@pxref{Der Store}) sowie die -Müllsammlerwurzeln (@pxref{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 (@pxref{Aus Binärdatei installieren}). - -@item --bootstrap -Mit den Bootstrap-Binärdateien das Bündel erstellen. Diese Option ist nur -für Guix-Entwickler nützlich. -@end table - -Außerdem unterstützt @command{guix pack} alle gemeinsamen -Erstellungsoptionen (@pxref{Gemeinsame Erstellungsoptionen}) und alle -Paketumwandlungsoptionen (@pxref{Paketumwandlungsoptionen}). - - -@c ********************************************************************* -@node Programmierschnittstelle -@chapter 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 @file{/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. - -@cindex Ableitung -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 @dfn{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 @emph{abgeleitet} werden. - -Dieses Kapitel beschreibt der Reihe nach all diese Programmierschnittstellen -(APIs), angefangen mit hochsprachlichen Paketdefinitionen. - -@menu -* Paketmodule:: Pakete aus Sicht des Programmierers. -* Pakete definieren:: Wie Sie neue Pakete definieren. -* Erstellungssysteme:: Angeben, wie Pakete erstellt werden. -* Der Store:: Den Paket-Store verändern. -* Ableitungen:: Systemnahe Schnittstelle für Paketableitungen. -* Die Store-Monade:: Rein funktionale Schnittstelle zum Store. -* G-Ausdrücke:: Erstellungsausdrücke verarbeiten. -* Aufruf von guix repl:: Interaktiv an Guix herumbasteln. -@end menu - -@node Paketmodule -@section Paketmodule - -From a programming viewpoint, the package definitions of the GNU -distribution are provided by Guile modules in the @code{(gnu packages -@dots{})} name space@footnote{Note that packages under the @code{(gnu -packages @dots{})} module name space are not necessarily ``GNU packages''. -This module naming scheme follows the usual Guile module naming convention: -@code{gnu} means that these modules are distributed as part of the GNU -system, and @code{packages} identifies modules that define packages.} -(@pxref{Module, Guile modules,, guile, GNU Guile Reference Manual}). For -instance, the @code{(gnu packages emacs)} module exports a variable named -@code{emacs}, which is bound to a @code{<package>} object (@pxref{Pakete definieren}). - -The @code{(gnu packages @dots{})} module name space is automatically scanned -for packages by the command-line tools. For instance, when running -@code{guix package -i emacs}, all the @code{(gnu packages @dots{})} modules -are scanned until one that exports a package object whose name is -@code{emacs} is found. This package search facility is implemented in the -@code{(gnu packages)} module. - -@cindex Anpassung, von Paketen -@cindex package module search path -Users can store package definitions in modules with different names---e.g., -@code{(my-packages emacs)}@footnote{Note that the file name and module name -must match. For instance, the @code{(my-packages emacs)} module must be -stored in a @file{my-packages/emacs.scm} file relative to the load path -specified with @option{--load-path} or @code{GUIX_PACKAGE_PATH}. -@xref{Modules and the File System,,, guile, GNU Guile Reference Manual}, for -details.}. There are two ways to make these package definitions visible to -the user interfaces: - -@enumerate -@item -By adding the directory containing your package modules to the search path -with the @code{-L} flag of @command{guix package} and other commands -(@pxref{Gemeinsame Erstellungsoptionen}), or by setting the @code{GUIX_PACKAGE_PATH} -environment variable described below. - -@item -By defining a @dfn{channel} and configuring @command{guix pull} so that it -pulls from it. A channel is essentially a Git repository containing package -modules. @xref{Kanäle}, for more information on how to define and use -channels. -@end enumerate - -@code{GUIX_PACKAGE_PATH} works similarly to other search path variables: - -@defvr {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. -@end defvr - -The distribution is fully @dfn{bootstrapped} and @dfn{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 @dfn{bootstrap binaries}, -provided by the @code{(gnu packages bootstrap)} module. For more -information on bootstrapping, @pxref{Bootstrapping}. - -@node Pakete definieren -@section Pakete definieren - -Mit den Modulen @code{(guix packages)} und @code{(guix build-system)} können -Paketdefinitionen auf einer hohen Abstraktionsebene geschrieben werden. Zum -Beispiel sieht die Paketdefinition bzw. das @dfn{Rezept} für das Paket von -GNU Hello so aus: - -@example -(define-module (gnu packages hello) - #:use-module (guix packages) - #:use-module (guix download) - #:use-module (guix build-system gnu) - #:use-module (guix licenses) - #:use-module (gnu packages gawk)) - -(define-public hello - (package - (name "hello") - (version "2.10") - (source (origin - (method url-fetch) - (uri (string-append "mirror://gnu/hello/hello-" version - ".tar.gz")) - (sha256 - (base32 - "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i")))) - (build-system gnu-build-system) - (arguments '(#:configure-flags '("--enable-silent-rules"))) - (inputs `(("gawk" ,gawk))) - (synopsis "Hello, GNU world: An example GNU package") - (description "Guess what GNU Hello prints!") - (home-page "http://www.gnu.org/software/hello/") - (license gpl3+))) -@end example - -@noindent -Auch ohne ein Experte in Scheme zu sein, könnten Leser erraten haben, was -die verschiedenen Felder dabei bedeuten. Dieser Ausdruck bindet die Variable -@code{hello} an ein @code{<package>}-Objekt, was an sich nur ein Verbund -(Record) ist (@pxref{SRFI-9, Scheme records,, guile, GNU Guile Reference -Manual}). Die Felder dieses Paket-Objekts lassen sich mit den Prozeduren aus -dem Modul @code{(guix packages)} auslesen, zum Beispiel liefert -@code{(package-name hello)} — Überraschung! — @code{"hello"}. - -Mit etwas Glück können Sie die Definition vielleicht teilweise oder sogar -ganz aus einer anderen Paketsammlung importieren, indem Sie den Befehl -@code{guix import} verwenden (@pxref{Aufruf von guix import}). - -In obigem Beispiel wurde @var{hello} in einem eigenen Modul ganz für sich -alleine definiert, und zwar @code{(gnu packages hello)}. Technisch gesehen -muss es nicht unbedingt in einem solchen Modul definiert werden, aber es ist -bequem, denn alle Module unter @code{(gnu packages @dots{})} werden -automatisch von den Befehlszeilenwerkzeugen gefunden (@pxref{Paketmodule}). - -Ein paar Dinge sind noch erwähnenswert in der obigen Paketdefinition: - -@itemize -@item -Das @code{source}-Feld für die Quelle des Pakets ist ein -@code{<origin>}-Objekt, was den Paketursprung angibt (siehe @pxref{»origin«-Referenz}, für eine vollständige Referenz). Hier wird dafür die Methode -@code{url-fetch} aus dem Modul @code{(guix download)} benutzt, d.h. die -Quelle ist eine Datei, die über FTP oder HTTP heruntergeladen werden soll. - -Das Präfix @code{mirror://gnu} lässt @code{url-fetch} einen der -GNU-Spiegelserver benutzen, die in @code{(guix download)} definiert sind. - -Das Feld @code{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 @code{(base32 -@dots{})} geht der base32-Darstellung des Hash-Wertes voraus. Sie finden die -base32-Darstellung mit Hilfe der Befehle @code{guix download} -(@pxref{Aufruf von guix download}) und @code{guix hash} (@pxref{Aufruf von guix hash}). - -@cindex Patches -Wenn nötig kann in der @code{origin}-Form auch ein @code{patches}-Feld -stehen, wo anzuwendende Patches aufgeführt werden, sowie ein -@code{snippet}-Feld mit einem Scheme-Ausdruck mit den Anweisungen, wie der -Quellcode zu modifizieren ist. - -@item -@cindex GNU-Erstellungssystem -Das Feld @code{build-system} legt fest, mit welcher Prozedur das Paket -erstellt werden soll (@pxref{Erstellungssysteme}). In diesem Beispiel steht -@var{gnu-build-system} für das wohlbekannte GNU-Erstellungssystem, wo Pakete -mit der üblichen Befehlsfolge @code{./configure && make && make check && -make install} konfiguriert, erstellt und installiert werden. - -@item -Das Feld @code{arguments} gibt an, welche Optionen dem Erstellungssystem -mitgegeben werden sollen (@pxref{Erstellungssysteme}). In diesem Fall -interpretiert @var{gnu-build-system} diese als Auftrag, @file{configure} mit -der Befehlszeilenoption @code{--enable-silent-rules} auszuführen. - -@cindex quote -@cindex Maskierung -@findex ' -@findex quote -Was hat es mit diesen einfachen Anführungszeichen (@code{'}) 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. @code{'} ist -synonym mit @code{quote}. @xref{Expression Syntax, quoting,, guile, GNU -Guile Reference Manual}, enthält weitere Details. Hierbei ist also der Wert -des @code{arguments}-Feldes eine Liste von Argumenten, die an das -Erstellungssystem weitergereicht werden, wie bei @code{apply} (@pxref{Fly -Evaluation, @code{apply},, guile, GNU Guile Reference Manual}). - -Ein Doppelkreuz gefolgt von einem Doppelpunkt (@code{#:}) definiert ein -Scheme-@dfn{Schlüsselwort} (@pxref{Keywords,,, guile, GNU Guile Reference -Manual}) und @code{#:configure-flags} ist ein Schlüsselwort, um eine -Befehlszeilenoption an das Erstellungssystem mitzugeben (@pxref{Coding With -Keywords,,, guile, GNU Guile Reference Manual}). - -@item -Das Feld @code{inputs} legt Eingaben an den Erstellungsprozess fest — -d.h. Abhängigkeiten des Pakets zur Erstellungs- oder Laufzeit. Hier -definieren wir eine Eingabe namens @code{"gawk"}, deren Wert wir auf den -Wert der @var{gawk}-Variablen festlegen; @var{gawk} ist auch selbst wiederum -an ein @code{<package>}-Objekt als Variablenwert gebunden. - -@cindex Backquote (Quasimaskierung) -@findex ` -@findex quasiquote -@cindex Komma (Demaskierung) -@findex , -@findex unquote -@findex ,@@ -@findex unquote-splicing -Auch mit @code{`} (einem Backquote, stattdessen kann man auch das längere -Synonym @code{quasiquote} schreiben) können wir eine wörtlich als Daten -interpretierte Liste im @code{inputs}-Feld einführen, aber bei dieser -»Quasimaskierung« kann @code{,} (ein Komma, oder dessen Synonym -@code{unquote}) benutzt werden, um den ausgewerteten Wert eines Ausdrucks in -diese Liste einzufügen (@pxref{Expression Syntax, unquote,, guile, 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 -@var{gnu-build-system} dafür, dass diese vorhanden sein müssen (@pxref{Erstellungssysteme}). - -Sämtliche anderen Abhängigkeiten müssen aber im @code{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. -@end itemize - -Siehe @xref{»package«-Referenz} für eine umfassende Beschreibung aller -erlaubten Felder. - -Sobald eine Paketdefinition eingesetzt wurde, können Sie das Paket mit Hilfe -des Befehlszeilenwerkzeugs @code{guix build} dann auch tatsächlich erstellen -(@pxref{Aufruf von guix build}) und dabei jegliche Erstellungsfehler, auf die -Sie stoßen, beseitigen (@pxref{Fehlschläge beim Erstellen untersuchen}). Sie können den -Befehl @command{guix edit} benutzen, um leicht zur Paketdefinition -zurückzuspringen (@pxref{Aufruf von guix edit}). Unter @xref{Paketrichtlinien} finden Sie mehr Informationen darüber, wie Sie Paketdefinitionen -testen, und unter @ref{Aufruf von guix lint} finden Sie Informationen, wie Sie -prüfen, ob eine Definition alle Stilkonventionen einhält. -@vindex GUIX_PACKAGE_PATH -Zuletzt finden Sie unter @pxref{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 @command{guix refresh} teilweise automatisieren können -(@pxref{Aufruf von guix refresh}). - -Hinter den Kulissen wird die einem @code{<package>}-Objekt entsprechende -Ableitung zuerst durch @code{package-derivation} berechnet. Diese Ableitung -wird in der @code{.drv}-Datei unter @file{/gnu/store} gespeichert. Die von -ihr vorgeschriebenen Erstellungsaktionen können dann durch die Prozedur -@code{build-derivations} umgesetzt werden (@pxref{Der Store}). - -@deffn {Scheme-Prozedur} package-derivation @var{Store} @var{Paket} [@var{System}] -Das @code{<derivation>}-Objekt zum @var{Paket} für das angegebene -@var{System} liefern (@pxref{Ableitungen}). - -Als @var{Paket} muss ein gültiges @code{<package>}-Objekt angegeben werden -und das @var{System} muss eine Zeichenkette sein, die das Zielsystem angibt -— z.B. @code{"x86_64-linux"} für ein auf x86_64 laufendes Linux-basiertes -GNU-System. @var{Store} muss eine Verbindung zum Daemon sein, der die -Operationen auf dem Store durchführt (@pxref{Der Store}). -@end deffn - -@noindent -@cindex Cross-Kompilieren -Auf ähnliche Weise kann eine Ableitung berechnet werden, die ein Paket für -ein anderes System cross-erstellt. - -@deffn {Scheme-Prozedur} package-cross-derivation @var{Store} @ - @var{Paket} @var{Ziel} [@var{System}] Liefert das -@code{<derivation>}-Objekt, um das @var{Paket} zu cross-erstellen vom -@var{System} aus für das @var{Ziel}-System. - -Als @var{Ziel} muss ein gültiges GNU-Tripel angegeben werden, was die -Ziel-Hardware und das zugehörige Betriebssystem beschreibt, wie -z.B. @code{"mips64el-linux-gnu"} (@pxref{Configuration Names, GNU -configuration triplets,, configure, GNU Configure and Build System}). -@end deffn - -@cindex Paketumwandlungen -@cindex Eingaben umschreiben -@cindex Abhängigkeitsbaum umschreiben -Pakete können auf beliebige Art verändert werden. Ein Beispiel für eine -nützliche Veränderung ist das @dfn{Umschreiben von Eingaben}, womit der -Abhängigkeitsbaum eines Pakets umgeschrieben wird, indem bestimmte Eingaben -durch andere ersetzt werden: - -@deffn {Scheme-Prozedur} package-input-rewriting @var{Ersetzungen} @ - [@var{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 @var{Ersetzungen} -umschreibt. @var{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 @var{umgeschriebener-Name} eine ein Argument nehmende -Prozedur angegeben werden, die einen Paketnamen nimmt und den Namen nach dem -Umschreiben zurückliefert. -@end deffn - -@noindent -Betrachten Sie dieses Beispiel: - -@example -(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)) -@end example - -@noindent -Hier definieren wir zuerst eine Umschreibeprozedur, die @var{openssl} durch -@var{libressl} ersetzt. Dann definieren wir damit eine @dfn{Variante} des -@var{git}-Pakets, die @var{libressl} statt @var{openssl} benutzt. Das ist -genau, was auch die Befehlszeilenoption @option{--with-input} tut -(@pxref{Paketumwandlungsoptionen, @option{--with-input}}). - -Eine allgemeiner anwendbare Prozedur, um den Abhängigkeitsgraphen eines -Pakets umzuschreiben, ist @code{package-mapping}. Sie unterstützt beliebige -Änderungen an den Knoten des Graphen. - -@deffn {Scheme-Prozedur} package-mapping @var{Prozedur} [@var{Schnitt?}] -Liefert eine Prozedur, die, wenn ihr ein Paket übergeben wird, die an -@code{package-mapping} übergebene @var{Prozedur} auf alle vom Paket -abhängigen Pakete anwendet. Die Prozedur liefert das resultierende -Paket. Wenn @var{Schnitt?} für ein Paket davon einen wahren Wert liefert, -findet kein rekursiver Abstieg in dessen Abhängigkeiten statt. -@end deffn - -@menu -* »package«-Referenz:: Der Datentyp für Pakete. -* »origin«-Referenz:: Datentyp für Paketursprünge. -@end menu - - -@node »package«-Referenz -@subsection @code{package}-Referenz - -Dieser Abschnitt fasst alle in @code{package}-Deklarationen zur Verfügung -stehenden Optionen zusammen (@pxref{Pakete definieren}). - -@deftp {Datentyp} package -Dieser Datentyp steht für ein Paketrezept. - -@table @asis -@item @code{name} -Der Name des Pakets als Zeichenkette. - -@item @code{version} -Die Version des Pakets als Zeichenkette. - -@item @code{source} -Ein Objekt, das beschreibt, wie der Quellcode des Pakets bezogen werden -soll. Meistens ist es ein @code{origin}-Objekt, welches für eine aus dem -Internet heruntergeladene Datei steht (@pxref{»origin«-Referenz}). Es kann -aber auch ein beliebiges anderes »dateiähnliches« Objekt sein, wie z.B. ein -@code{local-file}, was eine Datei im lokalen Dateisystem bezeichnet -(@pxref{G-Ausdrücke, @code{local-file}}). - -@item @code{build-system} -Das Erstellungssystem, mit dem das Paket erstellt werden soll (@pxref{Erstellungssysteme}). - -@item @code{arguments} (Vorgabe: @code{'()}) -Die Argumente, die an das Erstellungssystem übergeben werden sollen. Dies -ist eine Liste, typischerweise eine Reihe von Schlüssel-Wert-Paaren. - -@item @code{inputs} (Vorgabe: @code{'()}) -@itemx @code{native-inputs} (Vorgabe: @code{'()}) -@itemx @code{propagated-inputs} (Vorgabe: @code{'()}) -@cindex Eingaben, von Paketen -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 @code{"out"} -(siehe @pxref{Pakete mit mehreren Ausgaben.} für mehr Informationen zu -Paketausgaben). Im folgenden Beispiel etwa werden drei Eingaben festgelegt: - -@example -`(("libffi" ,libffi) - ("libunistring" ,libunistring) - ("glib:bin" ,glib "bin")) ;Ausgabe "bin" von Glib -@end example - -@cindex Cross-Kompilieren, Paketabhängigkeiten -Die Unterscheidung zwischen @code{native-inputs} und @code{inputs} ist -wichtig, damit Cross-Kompilieren möglich ist. Beim Cross-Kompilieren werden -als @code{inputs} aufgeführte Abhängigkeiten für die -Ziel-Prozessorarchitektur (@emph{target}) erstellt, andersherum werden als -@code{native-inputs} aufgeführte Abhängigkeiten für die Prozessorarchitektur -der erstellenden Maschine (@emph{build}) erstellt. - -@code{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. @command{guix lint} kann melden, ob wahrscheinlich Fehler in der -Auflistung sind (@pxref{Aufruf von guix lint}). - -@anchor{package-propagated-inputs} -Schließlich ist @code{propagated-inputs} ähnlich wie @code{inputs}, aber die -angegebenen Pakete werden automatisch mit ins Profil installiert, wenn das -Paket installiert wird, zu dem sie gehören (siehe -@pxref{package-cmd-propagated-inputs, @command{guix package}}, für -Informationen darüber, wie @command{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 -@code{Requires}-Eintrag bezieht. - -Noch ein Beispiel, wo @code{propagated-inputs} nützlich ist, sind Sprachen, -die den Laufzeit-Suchpfad @emph{nicht} zusammen mit dem Programm abspeichern -(@emph{nicht} wie etwa im @code{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 @code{propagated-inputs} statt in -@code{inputs} aufgeführt werden. - -@item @code{self-native-input?} (Vorgabe: @code{#f}) -Dieses boolesche Feld gibt an, ob das Paket sich selbst als eine native -Eingabe beim Cross-Kompilieren braucht. - -@item @code{outputs} (Vorgabe: @code{'("out")}) -Die Liste der Benennungen der Ausgaben des Pakets. Der Abschnitt -@xref{Pakete mit mehreren Ausgaben.} beschreibt übliche Nutzungen -zusätzlicher Ausgaben. - -@item @code{native-search-paths} (Vorgabe: @code{'()}) -@itemx @code{search-paths} (Vorgabe: @code{'()}) -Eine Liste von @code{search-path-specification}-Objekten, die -Umgebungsvariable für von diesem Paket beachtete Suchpfade (»search paths«) -beschreiben. - -@item @code{replacement} (Vorgabe: @code{#f}) -Dies muss entweder @code{#f} oder ein package-Objekt sein, das als Ersatz -(@dfn{replacement}) dieses Pakets benutzt werden soll. Im Abschnitt -@xref{Sicherheitsaktualisierungen, grafts}, wird dies erklärt. - -@item @code{synopsis} -Eine einzeilige Beschreibung des Pakets. - -@item @code{description} -Eine ausführlichere Beschreibung des Pakets. - -@item @code{license} -@cindex Lizenz, von Paketen -Die Lizenz des Pakets; benutzt werden kann ein Wert aus dem Modul -@code{(guix licenses)} oder eine Liste solcher Werte. - -@item @code{home-page} -Die URL, die die Homepage des Pakets angibt, als Zeichenkette. - -@item @code{supported-systems} (Vorgabe: @var{%supported-systems}) -Die Liste der vom Paket unterstützten Systeme als Zeichenketten der Form -@code{Architektur-Kernel}, zum Beispiel @code{"x86_64-linux"}. - -@item @code{maintainers} (Vorgabe: @code{'()}) -Die Liste der Betreuer (Maintainer) des Pakets als -@code{maintainer}-Objekte. - -@item @code{location} (Vorgabe: die Stelle im Quellcode, wo die @code{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. -@end table -@end deftp - - -@node »origin«-Referenz -@subsection @code{origin}-Referenz - -Dieser Abschnitt fasst alle Optionen zusammen, die in -@code{origin}-Deklarationen zur Verfügung stehen (@pxref{Pakete definieren}). - -@deftp {Datentyp} origin -Mit diesem Datentyp wird ein Ursprung, von dem Quellcode geladen werden -kann, beschrieben. - -@table @asis -@item @code{uri} -Ein Objekt, was die URI des Quellcodes enthält. Der Objekttyp hängt von der -@code{Methode} ab (siehe unten). Zum Beispiel sind, wenn die -@var{url-fetch}-Methode aus @code{(guix download)} benutzt wird, die -gültigen Werte für @code{uri}: eine URL dargestellt als Zeichenkette oder -eine Liste solcher URLs. - -@item @code{method} -Eine Prozedur, die die URI verwertet. - -Beispiele sind unter Anderem: - -@table @asis -@item @var{url-fetch} aus @code{(guix download)} -Herunterladen einer Datei von einer HTTP-, HTTPS- oder FTP-URL, die im -@code{uri}-Feld angegeben wurde. - -@vindex git-fetch -@item @var{git-fetch} aus @code{(guix git-download)} -Das im @code{uri}-Feld spezifizierte Repository des -Git-Versionskontrollsystems klonen und davon den im @code{uri}-Feld als ein -@code{git-reference}-Objekt angegebenen Commit benutzen; eine -@code{git-reference} sieht so aus: - -@example -(git-reference - (url "git://git.debian.org/git/pkg-shadow/shadow") - (commit "v4.1.5.1")) -@end example -@end table - -@item @code{sha256} -Ein Bytevektor, der den SHA-256-Hash der Quelldateien -enthält. Typischerweise wird hier mit der @code{base32}-Form der Bytevektor -aus einer Base-32-Zeichenkette generiert. - -Diese Informationen liefert Ihnen der Befehl @code{guix download} -(@pxref{Aufruf von guix download}) oder @code{guix hash} (@pxref{Aufruf von guix hash}). - -@item @code{file-name} (Vorgabe: @code{#f}) -Der Dateiname, unter dem der Quellcode abgespeichert werden sollte. Wenn er -auf @code{#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. - -@item @code{patches} (Vorgabe: @code{'()}) -Eine Liste von Dateinamen, Ursprüngen oder dateiähnlichen Objekten -(@pxref{G-Ausdrücke, 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 @code{%current-system} -oder @code{%current-target-system} abḧängen. - -@item @code{snippet} (Vorgabe: @code{#f}) -Ein im Quellcode-Verzeichnis auszuführender G-Ausdruck -(@pxref{G-Ausdrücke}) oder S-Ausdruck. Hiermit kann der Quellcode bequem -modifiziert werden, manchmal ist dies bequemer als mit einem Patch. - -@item @code{patch-flags} (Vorgabe: @code{'("-p1")}) -Eine Liste der Befehlszeilenoptionen, die dem @code{patch}-Befehl übergeben -werden sollen. - -@item @code{patch-inputs} (Vorgabe: @code{#f}) -Eingabepakete oder -ableitungen für den Patch-Prozess. Bei @code{#f} werden -die üblichen Patcheingaben wie GNU@tie{}Patch bereitgestellt. - -@item @code{modules} (Vorgabe: @code{'()}) -Eine Liste von Guile-Modulen, die während des Patch-Prozesses und während -der Ausführung des @code{snippet}-Felds geladen werden sollten. - -@item @code{patch-guile} (Vorgabe: @code{#f}) -Welches Guile-Paket für den Patch-Prozess benutzt werden sollte. Bei -@code{#f} wird ein vernünftiger Vorgabewert angenommen. -@end table -@end deftp - - -@node Erstellungssysteme -@section Erstellungssysteme - -@cindex Erstellungssystem -Jede Paketdefinition legt ein @dfn{Erstellungssystem} (»build system«) sowie -dessen Argumente fest (@pxref{Pakete definieren}). Das -@code{build-system}-Feld steht für die Erstellungsprozedur des Pakets sowie -für weitere implizite Eingaben für die Erstellungsprozedur. - -Erstellungssysteme sind @code{<build-system>}-Objekte. Die Schnittstelle, um -solche zu erzeugen und zu verändern, ist im Modul @code{(guix build-system)} -zu finden, und die eigentlichen Erstellungssysteme werden jeweils von ihren -eigenen Modulen exportiert. - -@cindex Bag (systemnahe Paketrepräsentation) -Intern funktionieren Erstellungssysteme, indem erst Paketobjekte zu -@dfn{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 -(@pxref{Ableitungen}). - -Erstellungssysteme akzeptieren optional eine Liste von @dfn{Argumenten}. In -Paketdefinitionen werden diese über das @code{arguments}-Feld übergeben -(@pxref{Pakete definieren}). Sie sind in der Regel Schlüsselwort-Argumente -(@pxref{Optional Arguments, keyword arguments in Guile,, guile, GNU Guile -Reference Manual}). Der Wert dieser Argumente wird normalerweise vom -Erstellungssystem in der @dfn{Erstellungsschicht} ausgewertet, d.h. von -einem durch den Daemon gestarteten Guile-Prozess (@pxref{Ableitungen}). - -Das häufigste Erstellungssystem ist @var{gnu-build-system}, was die übliche -Erstellungsprozedur für GNU-Pakete und viele andere Pakete darstellt. Es -wird vom Modul @code{(guix build-system gnu)} bereitgestellt. - -@defvr {Scheme-Variable} gnu-build-system -@var{gnu-build-system} steht für das GNU-Erstellungssystem und Varianten -desselben (@pxref{Configuration, configuration and makefile conventions,, -standards, GNU Coding Standards}). - -@cindex Erstellungsphasen -Kurz gefasst werden Pakete, die es benutzen, konfiguriert, erstellt und -installiert mit der üblichen Befehlsfolge @code{./configure && make && make -check && make install}. In der Praxis braucht man oft noch ein paar weitere -Schritte. Alle Schritte sind in voneinander getrennte @dfn{Phasen} -unterteilt. Erwähnt werden sollten@footnote{Bitte schauen Sie in den Modulen -unter @code{(guix build gnu-build-system)}, wenn Sie mehr Details zu -Erstellungsphasen brauchen.}: - -@table @code -@item 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. - -@item patch-source-shebangs -»Shebangs« in Quelldateien beheben, damit Sie sich auf die richtigen -Store-Dateipfade beziehen. Zum Beispiel könnte @code{#!/bin/sh} zu -@code{#!/gnu/store/@dots{}-bash-4.3/bin/sh} geändert werden. - -@item configure -Das Skript @file{configure} mit einigen vorgegebenen Befehlszeilenoptionen -ausführen, wie z.B. mit @code{--prefix=/gnu/store/@dots{}}, sowie mit den im -@code{#:configure-flags}-Argument angegebenen Optionen. - -@item build -@code{make} ausführen mit den Optionen aus der Liste in -@code{#:make-flags}. Wenn das Argument @code{#:parallel-build?} auf wahr -gesetzt ist (was der Vorgabewert ist), wird @code{make -j} zum Erstellen -ausgeführt. - -@item check -@code{make check} (oder statt @code{check} ein anderes bei -@code{#:test-target} angegebenes Ziel) ausführen, außer falls @code{#:tests? -#f} gesetzt ist. Wenn das Argument @code{#:parallel-tests?} auf wahr gesetzt -ist (der Vorgabewert), führe @code{make check -j} aus. - -@item install -@code{make install} mit den in @code{#:make-flags} aufgelisteten Optionen -ausführen. - -@item patch-shebangs -Shebangs in den installierten ausführbaren Dateien beheben. - -@item strip -Symbole zur Fehlerbehebung aus ELF-Dateien entfernen (außer -@code{#:strip-binaries?} ist auf falsch gesetzt) und in die -@code{debug}-Ausgabe kopieren, falls diese verfügbar ist (@pxref{Dateien zur Fehlersuche installieren}). -@end table - -@vindex %standard-phases -Das erstellungsseitige Modul @code{(guix build gnu-build-system)} definiert -@var{%standard-phases} als die vorgegebene Liste der -Erstellungsphasen. @var{%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 @code{#:phases} überschrieben werden. Zum Beispiel werden -bei Übergabe von: - -@example -#:phases (modify-phases %standard-phases (delete 'configure)) -@end example - -alle oben beschriebenen Phasen benutzt außer der @code{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 @code{(guix build-system gnu)} für eine vollständige -Liste). Wir bezeichnen sie als @dfn{implizite Eingaben} eines Pakets, weil -Paketdefinitionen sie nicht aufführen müssen. -@end defvr - -Andere @code{<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 -@var{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. - -@defvr {Scheme-Variable} ant-build-system -Diese Variable wird vom Modul @code{(guix build-system ant)} exportiert. Sie -implementiert die Erstellungsprozedur für Java-Pakete, die mit dem -@url{http://ant.apache.org/, Ant build tool} erstellt werden können. - -Sowohl @code{ant} als auch der @dfn{Java Development Kit} (JDK), wie er vom -Paket @code{icedtea} bereitgestellt wird, werden zu den Eingaben -hinzugefügt. Wenn andere Pakete dafür benutzt werden sollen, können sie -jeweils mit den Parametern @code{#:ant} und @code{#:jdk} festgelegt werden. - -Falls das ursprüngliche Paket über keine nutzbare Ant-Erstellungsdatei -(»Ant-Buildfile«) verfügt, kann aus der Angabe im Parameter -@code{#:jar-name} eine minimale Ant-Erstellungsdatei @file{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 @code{#:source-dir} benutzt werden, um das -Unterverzeichnis mit dem Quellcode anzugeben; sein Vorgabewert ist »src«. - -Der Parameter @code{#: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 @code{#:test-include} kann eine Liste angegeben -werden, welche Junit-Tests auszuführen sind. Der Vorgabewert ist @code{(list -"**/*Test.java")}. Mit @code{#:test-exclude} kann ein Teil der Testdateien -ignoriert werden. Der Vorgabewert ist @code{(list "**/Abstract*.java")}, -weil abstrakte Klassen keine ausführbaren Tests enthalten können. - -Der Parameter @code{#:build-target} kann benutzt werden, um die Ant-Aufgabe -(Task) anzugeben, die während der @code{build}-Phase ausgeführt werden -soll. Vorgabe ist, dass die Aufgabe (Task) »jar« ausgeführt wird. - -@end defvr - -@defvr {Scheme-Variable} android-ndk-build-system -@cindex Android-Distribution -@cindex Android-NDK-Erstellungssystem -Diese Variable wird von @code{(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. - -@end defvr - -@defvr {Scheme-Variable} asdf-build-system/source -@defvrx {Scheme-Variable} asdf-build-system/sbcl -@defvrx {Scheme-Variable} asdf-build-system/ecl - -Diese Variablen, die vom Modul @code{(guix build-system asdf)} exportiert -werden, implementieren Erstellungsprozeduren für Common-Lisp-Pakete, welche -@url{https://common-lisp.net/project/asdf/, »ASDF«} benutzen. ASDF dient der -Systemdefinition für Common-Lisp-Programme und -Bibliotheken. - -Das Erstellungssystem @code{asdf-build-system/source} installiert die Pakete -in Quellcode-Form und kann @i{via} ASDF mit jeder -Common-Lisp-Implementierung geladen werden. Die anderen Erstellungssysteme -wie @code{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.@code{sbcl-} für @code{asdf-build-system/sbcl}. - -Zudem sollte das entsprechende Quellcode-Paket mit der Konvention wie bei -Python-Paketen (siehe @ref{Python-Module}) ein @code{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 @code{origin} mehrere Systeme enthalten -sind, können Paketvarianten geschrieben werden, mit denen alle Systeme -erstellt werden. Quellpakete, die @code{asdf-build-system/source} benutzen, -können mehrere Systeme enthalten. - -Um ausführbare Programme und Abbilder zu erzeugen, können die -erstellungsseitigen Prozeduren @code{build-program} und @code{build-image} -benutzt werden. Sie sollten in einer Erstellungsphase nach der -@code{create-symlinks}-Phase aufgerufen werden, damit das gerade erstellte -System Teil des resultierenden Abbilds sein kann. An @code{build-program} -muss eine Liste von Common-Lisp-Ausdrücken über das Argument -@code{#:entry-program} übergeben werden. - -Wenn das System nicht in seiner eigenen gleichnamigen @code{.asd}-Datei -definiert ist, sollte der Parameter @code{#: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 -@code{#:test-asd-file} steht. Ist dafür kein Wert gesetzt, werden die -Dateien @code{<system>-tests.asd}, @code{<system>-test.asd}, -@code{tests.asd} und @code{test.asd} durchsucht, wenn sie existieren. - -Wenn aus irgendeinem Grund der Paketname nicht den Namenskonventionen folgen -kann, kann der Parameter @code{#:asd-system-name} benutzt werden, um den -Namen des Systems anzugeben. - -@end defvr - -@defvr {Scheme-Variable} cargo-build-system -@cindex Rust-Programmiersprache -@cindex Cargo (Rust-Erstellungssystem) -Diese Variable wird vom Modul @code{(guix build-system cargo)} -exportiert. Damit können Pakete mit Cargo erstellt werden, dem -Erstellungswerkzeug der @uref{https://www.rust-lang.org, -Rust-Programmiersprache}. - -In seiner @code{configure}-Phase ersetzt dieses Erstellungssystem in der -Datei @file{Carto.toml} angegebene Abhängigkeiten durch Eingaben im -Guix-Paket. Die Phase @code{install} installiert die Binärdateien und auch -den Quellcode und die @file{Cargo.toml}-Datei. -@end defvr - -@cindex Clojure (Programmiersprache) -@cindex einfaches Clojure-Erstellungssystem -@defvr {Scheme-Variable} clojure-build-system -Diese Variable wird durch das Modul @code{(guix build-system clojure)} -exportiert. Sie implementiert eine einfache Erstellungsprozedur für in -@uref{https://clojure.org/, Clojure} geschriebene Pakete mit dem guten alten -@code{compile} in Clojure. Cross-Kompilieren wird noch nicht unterstützt. - -Das Erstellungssystem fügt @code{clojure}, @code{icedtea} und @code{zip} zu -den Eingaben hinzu. Sollen stattdessen andere Pakete benutzt werden, können -diese jeweils mit den Parametern @code{#:clojure}, @code{#:jdk} und -@code{#:zip} spezifiziert werden. - -Eine Liste der Quellcode-Verzeichnisse, Test-Verzeichnisse und Namen der -Jar-Dateien können jeweils über die Parameter @code{#:source-dirs}, -@code{#:test-dirs} und @code{#:jar-names} angegeben werden. Das Verzeichnis, -in das kompiliert wird, sowie die Hauptklasse können jeweils mit den -Parametern @code{#:compile-dir} und @code{#:main-class} angegeben -werden. Andere Parameter sind im Folgenden dokumentiert. - -Dieses Erstellungssystem ist eine Erweiterung des @var{ant-build-system}, -bei der aber die folgenden Phasen geändert wurden: - -@table @code - -@item build -Diese Phase ruft @code{compile} in Clojure auf, um Quelldateien zu -kompilieren, und führt @command{jar} aus, um Jar-Dateien aus sowohl -Quelldateien als auch kompilierten Dateien zu erzeugen, entsprechend der -jeweils in @code{#:aot-include} und @code{#: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 @code{#:all} entsprechen, was für alle im -Quellverzeichis gefundenen Clojure-Bibliotheken steht. Der Parameter -@code{#:omit-source?} entscheidet, ob Quelldateien in die Jar-Archive -aufgenommen werden sollten. - -@item check -In dieser Phase werden Tests auf die durch Einschluss- und Ausschlussliste -@code{#:test-include} bzw. @code{#:test-exclude} angegebenen Dateien -ausgeführt. Deren Bedeutung ist analog zu @code{#:aot-include} und -@code{#:aot-exclude}, außer dass das besondere Schlüsselwort @code{#:all} -jetzt für alle Clojure-Bibliotheken in den Test-Verzeichnissen steht. Der -Parameter @code{#:tests?} entscheidet, ob Tests ausgeführt werden sollen. - -@item install -In dieser Phase werden alle zuvor erstellten Jar-Dateien installiert. -@end table - -Zusätzlich zu den bereits angegebenen enthält dieses Erstellungssystem noch -eine weitere Phase. - -@table @code - -@item install-doc -Diese Phase installiert alle Dateien auf oberster Ebene, deren Basisnamen -ohne Verzeichnisangabe zu @var{%doc-regex} passen. Ein anderer regulärer -Ausdruck kann mit dem Parameter @code{#:doc-regex} verwendet werden. All die -so gefundenen oder (rekursiv) in den mit @code{#:doc-dirs} angegebenen -Dokumentationsverzeichnissen liegenden Dateien werden installiert. -@end table -@end defvr - -@defvr {Scheme-Variable} cmake-build-system -Diese Variable wird von @code{(guix build-system cmake)} exportiert. Sie -implementiert die Erstellungsprozedur für Pakete, die das -@url{http://www.cmake.org, CMake-Erstellungswerkzeug} benutzen. - -Das Erstellungssystem fügt automatisch das Paket @code{cmake} zu den -Eingaben hinzu. Welches Paket benutzt wird, kann mit dem Parameter -@code{#:cmake} geändert werden. - -Der Parameter @code{#:configure-flags} wird als Liste von -Befehlszeilenoptionen aufgefasst, die an den Befehl @command{cmake} -übergeben werden. Der Parameter @code{#:build-type} abstrahiert, welche -Befehlszeilenoptionen dem Compiler übergeben werden; der Vorgabewert ist -@code{"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 @code{-O2 -g} -entspricht, wie bei der Vorgabe für Autoconf-basierte Pakete. -@end defvr - -@defvr {Scheme Variable} dune-build-system -This variable is exported by @code{(guix build-system dune)}. It supports -builds of packages using @uref{https://dune.build/, Dune}, a build tool for -the OCaml programming language. It is implemented as an extension of the -@code{ocaml-build-system} which is described below. As such, the -@code{#:ocaml} and @code{#:findlib} parameters can be passed to this build -system. - -It automatically adds the @code{dune} package to the set of inputs. Which -package is used can be specified with the @code{#:dune} parameter. - -There is no @code{configure} phase because dune packages typically don't -need to be configured. The @code{#:build-flags} parameter is taken as a -list of flags passed to the @code{dune} command during the build. - -The @code{#:jbuild?} parameter can be passed to use the @code{jbuild} -command instead of the more recent @code{dune} command while building a -package. Its default value is @code{#f}. -@end defvr - -@defvr {Scheme-Variable} go-build-system -Diese Variable wird vom Modul @code{(guix build-system go)} exportiert. Mit -ihr ist eine Erstellungsprozedur für Go-Pakete implementiert, die dem -normalen -@url{https://golang.org/cmd/go/#hdr-Compile_packages_and_dependencies, -Go-Erstellungsmechanismus} entspricht. - -Beim Aufruf wird ein Wert für den Schlüssel @code{#:import-path} und -manchmal auch für @code{#:unpack-path} erwartet. Der -@url{https://golang.org/doc/code.html#ImportPaths, »import path«} 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 @code{#:unpack-path} angegeben werden. - -Pakete, die Go-Bibliotheken zur Verfügung stellen, sollten zusammen mit -ihrem Quellcode installiert werden. Der Schlüssel @code{#:install-source?}, -sein Vorgabewert ist @code{#t}, steuert, ob Quellcode installiert wird. Bei -Paketen, die nur ausführbare Dateien liefern, kann der Wert auf @code{#f} -gesetzt werden. -@end defvr - -@defvr {Scheme-Variable} glib-or-gtk-build-system -Diese Variable wird vom Modul @code{(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 -@var{gnu-build-system} hinzu: - -@table @code -@item glib-or-gtk-wrap -Die Phase @code{glib-or-gtk-wrap} stellt sicher, dass Programme in -@file{bin/} in der Lage sind, GLib-»Schemata« und -@uref{https://developer.gnome.org/gtk3/stable/gtk-running.html, GTK-Module} -zu finden. Dazu wird für das Programm ein Wrapper-Skript erzeugt, dass das -eigentliche Programm mit den richtigen Werten für die Umgebungsvariablen -@code{XDG_DATA_DIRS} und @code{GTK_PATH} aufruft. - -Es ist möglich, bestimmte Paketausgaben von diesem Wrapping-Prozess -auszunehmen, indem Sie eine Liste ihrer Namen im Parameter -@code{#: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. - -@item glib-or-gtk-compile-schemas -Mit der Phase @code{glib-or-gtk-compile-schemas} wird sichergestellt, dass -alle @uref{https://developer.gnome.org/gio/stable/glib-compile-schemas.html, -GSettings-Schemata} für GLib kompiliert werden. Dazu wird das Programm -@command{glib-compile-schemas} ausgeführt. Es kommt aus dem Paket -@code{glib:bin}, was automatisch vom Erstellungssystem importiert -wird. Welches @code{glib}-Paket dieses @command{glib-compile-schemas} -bereitstellt, kann mit dem Parameter @code{#:glib} spezifiziert werden. -@end table - -Beide Phasen finden nach der @code{install}-Phase statt. -@end defvr - -@defvr {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 @file{configure}-Skript enthalten. Hierzu -wird Scheme-Code mit @command{guild compile} kompiliert -(@pxref{Compilation,,, guile, GNU Guile Reference Manual}) und die -@file{.scm}- und @file{.go}-Dateien an den richtigen Pfad installiert. Auch -Dokumentation wird installiert. - -Das Erstellungssystem unterstützt Cross-Kompilieren durch die -Befehlszeilenoption @code{--target} für @command{guild compile}. - -Mit @code{guile-build-system} erstellte Pakete müssen ein Guile-Paket in -ihrem @code{native-inputs}-Feld aufführen. -@end defvr - -@defvr {Scheme-Variable} minify-build-system -Diese Variable wird vom Modul @code{(guix build-system minify)} -exportiert. Sie implementiert eine Prozedur zur Minifikation einfacher -JavaScript-Pakete. - -Es fügt @code{uglify-js} zur Menge der Eingaben hinzu und komprimiert damit -alle JavaScript-Dateien im @file{src}-Verzeichnis. Ein anderes Programm zur -Minifikation kann verwendet werden, indem es mit dem Parameter -@code{#: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 @file{src}-Verzeichnis -liegen, kann mit dem Parameter @code{#:javascript-files} eine Liste der -Dateinamen übergeben werden, auf die das Minifikationsprogramm aufgerufen -wird. -@end defvr - -@defvr {Scheme-Variable} ocaml-build-system -Diese Variable wird vom Modul @code{(guix build-system ocaml)} -exportiert. Mit ihr ist ein Erstellungssystem für @uref{https://ocaml.org, -OCaml}-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 @file{setup.ml} auf oberster Ebene vorhanden ist, -wird @code{ocaml setup.ml -configure}, @code{ocaml setup.ml -build} und -@code{ocaml setup.ml -install} ausgeführt. Das Erstellungssystem wird -annehmen, dass die Datei durch @uref{http://oasis.forge.ocamlcore.org/, -OASIS} 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 @code{#:configure-flags} und -@code{#:build-flags} übergeben. Der Schlüssel @code{#:test-flags} kann -übergeben werden, um die Befehlszeilenoptionen zu ändern, mit denen die -Tests aktiviert werden. Mit dem Parameter @code{#:use-make?} kann dieses -Erstellungssystem für die build- und install-Phasen abgeschaltet werden. - -Verfügt das Paket über eine @file{configure}-Datei, wird angenommen, dass -diese von Hand geschrieben wurde mit einem anderen Format für Argumente als -bei einem Skript des @code{gnu-build-system}. Sie können weitere -Befehlszeilenoptionen mit dem Schlüssel @code{#:configure-flags} hinzufügen. - -Falls dem Paket ein @file{Makefile} beiliegt (oder @code{#:use-make?} auf -@code{#t} gesetzt wurde), wird dieses benutzt und weitere -Befehlszeilenoptionen können mit dem Schlüssel @code{#: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 @code{ocaml -pkg/pkg.ml} oder @code{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 @code{#:build-flags} -übergeben werden. Um die Installation kümmert sich -@command{opam-installer}. In diesem Fall muss das @code{opam}-Paket im -@code{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 -@file{.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 @code{CAML_LD_LIBRARY_PATH}. Diese Umgebungsvariable -zeigt auf @file{lib/ocaml/site-lib/stubslibs} und dorthin sollten -@file{.so}-Bibliotheken installiert werden. -@end defvr - -@defvr {Scheme-Variable} python-build-system -Diese Variable wird vom Modul @code{(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 -@code{python setup.py build} ausgeführt und dann @code{python setup.py -install --prefix=/gnu/store/@dots{}}. - -Für Pakete, die eigenständige Python-Programme nach @code{bin/} -installieren, sorgt dieses Erstellungssystem dafür, dass die Programme in -ein Wrapper-Skript verpackt werden, welches die eigentlichen Programme mit -einer Umgebungsvariablen @code{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 @code{#: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 @code{setup.py} auf, was zu @code{setuptools} -gehört, ähnlich wie es auch @command{pip} tut. Manche Pakete sind mit -setuptools (und pip) inkompatibel, deswegen können Sie diese Einstellung -abschalten, indem Sie den Parameter @code{#:use-setuptools} auf @code{#f} -setzen. -@end defvr - -@defvr {Scheme-Variable} perl-build-system -Diese Variable wird vom Modul @code{(guix build-system perl)} -exportiert. Mit ihr wird die Standard-Erstellungsprozedur für Perl-Pakete -implementiert, welche entweder darin besteht, @code{perl Build.PL ---prefix=/gnu/store/@dots{}} gefolgt von @code{Build} und @code{Build -install} auszuführen, oder @code{perl Makefile.PL PREFIX=/gnu/store/@dots{}} -gefolgt von @code{make} und @code{make install} auszuführen, je nachdem, ob -eine Datei @code{Build.PL} oder eine Datei @code{Makefile.PL} in der -Paketdistribution vorliegt. Den Vorrang hat erstere, wenn sowohl -@code{Build.PL} als auch @code{Makefile.PL} in der Paketdistribution -existieren. Der Vorrang kann umgekehrt werden, indem @code{#t} für den -Parameter @code{#:make-maker?} angegeben wird. - -Der erste Aufruf von @code{perl Makefile.PL} oder @code{perl Build.PL} -übergibt die im Parameter @code{#:make-maker-flags} -bzw. @code{#:module-build-flags} angegebenen Befehlszeilenoptionen, je -nachdem, was verwendet wird. - -Welches Perl-Paket dafür benutzt wird, kann mit @code{#:perl} angegeben -werden. -@end defvr - -@defvr {Scheme-Variable} r-build-system -Diese Variable wird vom Modul @code{(guix build-system r)} exportiert. Sie -entspricht einer Implementierung der durch @uref{http://r-project.org, -R}-Pakete genutzten Erstellungsprozedur, die wenig mehr tut, als @code{R CMD -INSTALL --library=/gnu/store/@dots{}} in einer Umgebung auszuführen, in der -die Umgebungsvariable @code{R_LIBS_SITE} die Pfade aller R-Pakete unter den -Paketeingaben enthält. Tests werden nach der Installation mit der R-Funktion -@code{tools::testInstalledPackage} ausgeführt. -@end defvr - -@defvr {Scheme-Variable} texlive-build-system -Diese Variable wird vom Modul @code{(guix build-system texlive)} -exportiert. Mit ihr werden TeX-Pakete in Stapelverarbeitung (»batch mode«) -mit der angegebenen Engine erstellt. Das Erstellungssystem setzt die -Variable @code{TEXINPUTS} so, dass alle TeX-Quelldateien unter den Eingaben -gefunden werden können. - -Standardmäßig wird @code{luatex} auf allen Dateien mit der Dateiendung -@code{ins} ausgeführt. Eine andere Engine oder ein anderes Format kann mit -dem Argument @code{#:tex-format} angegeben werden. Verschiedene -Erstellungsziele können mit dem Argument @code{#:build-targets} festgelegt -werden, das eine Liste von Dateinamen erwartet. Das Erstellungssystem fügt -nur @code{texlive-bin} und @code{texlive-latex-base} zu den Eingaben hinzu -(beide kommen aus dem Modul @code{(gnu packages tex}). Für beide kann das zu -benutzende Paket jeweils mit den Argumenten @code{#:texlive-bin} oder -@code{#:texlive-latex-base} geändert werden. - -Der Parameter @code{#:tex-directory} sagt dem Erstellungssystem, wohin die -installierten Dateien im texmf-Verzeichnisbaum installiert werden sollen. -@end defvr - -@defvr {Scheme-Variable} ruby-build-system -Diese Variable wird vom Modul @code{(guix build-system ruby)} -exportiert. Sie steht für eine Implementierung der -RubyGems-Erstellungsprozedur, die für Ruby-Pakete benutzt wird, wobei -@code{gem build} gefolgt von @code{gem install} ausgeführt wird. - -Das @code{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 @code{#:ruby} -festgelegt werden. Eine Liste zusätzlicher Befehlszeilenoptionen für den -Aufruf des @command{gem}-Befehls kann mit dem Parameter @code{#:gem-flags} -angegeben werden. -@end defvr - -@defvr {Scheme-Variable} waf-build-system -Diese Variable wird durch das Modul @code{(guix build-system waf)} -exportiert. Damit ist eine Erstellungsprozedur rund um das @code{waf}-Skript -implementiert. Die üblichen Phasen — @code{configure}, @code{build} und -@code{install} — sind implementiert, indem deren Namen als Argumente an das -@code{waf}-Skript übergeben werden. - -Das @code{waf}-Skript wird vom Python-Interpetierer ausgeführt. Mit welchem -Python-Paket das Skript ausgeführt werden soll, kann mit dem Parameter -@code{#:python} angegeben werden. -@end defvr - -@defvr {Scheme-Variable} scons-build-system -Diese Variable wird vom Modul @code{(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 @code{scons} aus, um das Paket zu -erstellen, führt mit @code{scons test} Tests aus und benutzt @code{scons -install}, um das Paket zu installieren. - -Zusätzliche Optionen, die an @code{scons} übergeben werden sollen, können -mit dem Parameter @code{#: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 @code{#:scons} ausgewählt wird. -@end defvr - -@defvr {Scheme-Variable} haskell-build-system -Diese Variable wird vom Modul @code{(guix build-system haskell)} -exportiert. Sie bietet Zugang zur Cabal-Erstellungsprozedur, die von -Haskell-Paketen benutzt wird, was bedeutet, @code{runhaskell Setup.hs -configure --prefix=/gnu/store/@dots{}} und @code{runhaskell Setup.hs build} -auszuführen. Statt das Paket mit dem Befehl @code{runhaskell Setup.hs -install} zu installieren, benutzt das Erstellungssystem @code{runhaskell -Setup.hs copy} gefolgt von @code{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 @code{runhaskell Setup.hs haddock}, außer -@code{#:haddock? #f} wurde übergeben. Optional können an Haddock Parameter -mit Hilfe des Parameters @code{#:haddock-flags} übergeben werden. Wird die -Datei @code{Setup.hs} nicht gefunden, sucht das Erstellungssystem -stattdessen nach @code{Setup.lhs}. - -Welcher Haskell-Compiler benutzt werden soll, kann über den -@code{#:haskell}-Parameter angegeben werden. Als Vorgabewert verwendet er -@code{ghc}. -@end defvr - -@defvr {Scheme-Variable} dub-build-system -Diese Variable wird vom Modul @code{(guix build-system dub)} exportiert. Sie -verweist auf eine Implementierung des Dub-Erstellungssystems, das von -D-Paketen benutzt wird. Dabei werden @code{dub build} und @code{dub run} -ausgeführt. Die Installation wird durch manuelles Kopieren der Dateien -durchgeführt. - -Welcher D-Compiler benutzt wird, kann mit dem Parameter @code{#:ldc} -festgelegt werden, was als Vorgabewert @code{ldc} benutzt. -@end defvr - -@defvr {Scheme-Variable} emacs-build-system -Diese Variable wird vom Modul @code{(guix build-system emacs)} -exportiert. Darin wird eine Installationsprozedur ähnlich der des -Paketsystems von Emacs selbst implementiert (@pxref{Packages,,, emacs, The -GNU Emacs Manual}). - -Zunächst wird eine Datei @code{@var{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 @file{dir} -gelöscht. Jedes Paket wird in sein eigenes Verzeichnis unter -@file{share/emacs/site-lisp/guix.d} installiert. -@end defvr - -@defvr {Scheme-Variable} font-build-system -This variable is exported by @code{(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. -@end defvr - -@defvr {Scheme-Variable} meson-build-system -Diese Variable wird vom Modul @code{(guix build-system meson)} -exportiert. Sie enthält die Erstellungsprozedur für Pakete, die -@url{http://mesonbuild.com, Meson} als ihr Erstellungssystem benutzen. - -Mit ihr werden sowohl Meson als auch @uref{https://ninja-build.org/, Ninja} -zur Menge der Eingaben hinzugefügt; die Pakete dafür können mit den -Parametern @code{#:meson} und @code{#:ninja} geändert werden, wenn -nötig. Das vorgegebene Meson-Paket ist @code{meson-for-build}, ein -besonderes Paket, dessen Besonderheit darin besteht, den @code{RUNPATH} von -Binärdateien und Bibliotheken @emph{nicht} zu entfernen, wenn sie -installiert werden. - -Dieses Erstellungssystem ist eine Erweiterung für das -@var{gnu-build-system}, aber mit Änderungen an den folgenden Phasen, die -Meson-spezifisch sind: - -@table @code - -@item configure -Diese Phase führt den @code{meson}-Befehl mit den in -@code{#:configure-flags} angegebenen Befehlszeilenoptionen aus. Die -Befehlszeilenoption @code{--build-type} wird immer auf @code{plain} gesetzt, -solange nichts anderes mit dem Parameter @code{#:build-type} angegeben -wurde. - -@item build -Diese Phase ruft @code{ninja} auf, um das Paket standardmäßig parallel zu -erstellen. Die Vorgabeeinstellung, dass parallel erstellt wird, kann -verändert werden durch Setzen von @code{#:parallel-build?}. - -@item check -Diese Phase führt @code{ninja} mit dem als @code{#:test-target} -spezifizierten Ziel für Tests auf, der Vorgabewert ist das Ziel namens -@code{"test"}. - -@item install -Diese Phase führt @code{ninja install} aus und kann nicht verändert werden. -@end table - -Dazu fügt das Erstellungssystem noch folgende neue Phasen: - -@table @code - -@item 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 -@code{RUNPATH} hinzugefügt, wann immer es nötig ist. Auch werden diejenigen -Referenzen zu Bibliotheken aus der Erstellungsphase wieder entfernt, die bei -@code{meson-for-build} hinzugefügt wurden, aber eigentlich zur Laufzeit -nicht gebraucht werden, wie Abhängigkeiten nur für Tests. - -@item glib-or-gtk-wrap -Diese Phase ist dieselbe, die auch im @code{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 -@code{#:glib-or-gtk?} aktiviert werden. - -@item glib-or-gtk-compile-schemas -Diese Phase ist dieselbe, die auch im @code{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 -@code{#:glib-or-gtk?} aktiviert werden. -@end table -@end defvr - -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. - -@defvr {Scheme-Variable} trivial-build-system -Diese Variable wird vom Modul @code{(guix build-system trivial)} exportiert. - -Diesem Erstellungssystem muss im Argument @code{#:builder} ein -Scheme-Ausdruck übergeben werden, der die Paketausgabe(n) erstellt — wie bei -@code{build-expression->derivation} (@pxref{Ableitungen, -@code{build-expression->derivation}}). -@end defvr - -@node Der Store -@section Der Store - -@cindex Store -@cindex Store-Objekte -@cindex Store-Pfade - -Konzeptionell ist der @dfn{Store} der Ort, wo Ableitungen nach erfolgreicher -Erstellung gespeichert werden — standardmäßig finden Sie ihn in -@file{/gnu/store}. Unterverzeichnisse im Store werden @dfn{Store-Objekte} -oder manchmal auch @dfn{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 @emph{gültig} sind, also Ergebnisse erfolgreicher Erstellungen -sind. Die Datenbank befindet sich in @file{@var{localstatedir}/guix/db}, -wobei @var{localstatedir} das mit @option{--localstatedir} bei der -Ausführung von »configure« angegebene Zustandsverzeichnis ist, normalerweise -@file{/var}. - -Auf den Store wird @emph{nur} durch den Daemon im Auftrag seiner Clients -zugegriffen (@pxref{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). - -@quotation Anmerkung -Benutzer dürfen @emph{niemals} Dateien in @file{/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 (@pxref{Einführung}). - -Siehe @xref{Aufruf von guix gc, @command{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. -@end quotation - -Das Modul @code{(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 @code{open-connection}, -und daher allen @command{guix}-Befehlen, ist, sich mit dem lokalen Daemon -oder dem an der in der Umgebungsvariablen @code{GUIX_DAEMON_SOCKET} -angegeben URL zu verbinden. - -@defvr {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: - -@table @code -@item file -@itemx unix -Für Unix-Sockets. @code{file:///var/guix/daemon-socket/socket} kann -gleichbedeutend auch als @file{/var/guix/daemon-socket/socket} angegeben -werden. - -@item guix -@cindex Daemon, Fernzugriff -@cindex Fernzugriff auf den Daemon -@cindex Daemon, Einrichten auf Clustern -@cindex Cluster, Einrichtung des Daemons -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): - -@example -guix://master.guix.example.org:1234 -@end example - -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 @code{master.guix.example.org} verbinden können. - -Die Befehlszeilenoption @code{--listen} von @command{guix-daemon} kann -benutzt werden, damit er auf TCP-Verbindungen lauscht (@pxref{Aufruf des guix-daemon, @code{--listen}}). - -@item ssh -@cindex SSH-Zugriff auf Erstellungs-Daemons -Mit solchen URIs kann eine Verbindung zu einem entfernten Daemon über SSH -hergestellt werden@footnote{Diese Funktionalitäts setzt Guile-SSH voraus -(@pxref{Voraussetzungen}).}. Eine typische URL sieht so aus: - -@example -ssh://charlie@@guix.example.org:22 -@end example - -Was @command{guix copy} betrifft, richtet es sich nach den üblichen -OpenSSH-Client-Konfigurationsdateien (@pxref{Aufruf von guix copy}). -@end table - -In Zukunft könnten weitere URI-Schemata unterstützt werden. - -@c XXX: Remove this note when the protocol incurs fewer round trips -@c and when (guix derivations) no longer relies on file system access. -@quotation Anmerkung -Die Fähigkeit, sich mit entfernten Erstellungs-Daemons zu verbinden, sehen -wir als experimentell an, Stand @value{VERSION}. Bitte diskutieren Sie mit -uns jegliche Probleme oder Vorschläge, die Sie haben könnten -(@pxref{Mitwirken}). -@end quotation -@end defvr - -@deffn {Scheme-Prozedur} open-connection [@var{Uri}] [#:reserve-space? #t] -Sich mit dem Daemon über den Unix-Socket an @var{Uri} verbinden (einer -Zeichenkette). Wenn @var{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. - -@var{Uri} nimmt standardmäßig den Wert von @var{%default-socket-path} an, -was dem bei der Installation mit dem Aufruf von @command{configure} -ausgewählten Vorgabeort entspricht, gemäß den Befehlszeilenoptionen, mit -denen @command{configure} aufgerufen wurde. -@end deffn - -@deffn {Scheme-Prozedur} close-connection @var{Server} -Die Verbindung zum @var{Server} trennen. -@end deffn - -@defvr {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. -@end defvr - -Prozeduren, die entfernte Prozeduraufrufe durchführen, nehmen immer ein -Server-Objekt als ihr erstes Argument. - -@deffn {Scheme-Prozedur} valid-path? @var{Server} @var{Pfad} -@cindex ungültige Store-Objekte -Liefert @code{#t}, wenn der @var{Pfad} ein gültiges Store-Objekt benennt, -und sonst @code{#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 @code{&store-protocol-error} condition is raised if @var{path} is not -prefixed by the store directory (@file{/gnu/store}). -@end deffn - -@deffn {Scheme-Prozedur} add-text-to-store @var{Server} @var{Name} @var{Text} [@var{Referenzen}] -Den @var{Text} im Store in einer Datei namens @var{Name} ablegen und ihren -Store-Pfad zurückliefern. @var{Referenzen} ist die Liste der Store-Pfade, -die der Store-Pfad dann referenzieren soll. -@end deffn - -@deffn {Scheme-Prozedur} build-derivations @var{Server} @var{Ableitungen} -Die @var{Ableitungen} erstellen (eine Liste von @code{<derivation>}-Objekten -oder von Pfaden zu Ableitungen) und terminieren, sobald der Worker-Prozess -mit dem Erstellen fertig ist. Liefert @code{#t} bei erfolgreicher -Erstellung. -@end deffn - -Es sei erwähnt, dass im Modul @code{(guix monads)} eine Monade sowie -monadische Versionen obiger Prozeduren angeboten werden, damit an Code, der -auf den Store zugreift, bequemer gearbeitet werden kann (@pxref{Die Store-Monade}). - -@c FIXME -@i{Dieser Abschnitt ist im Moment noch unvollständig.} - -@node Ableitungen -@section Ableitungen - -@cindex Ableitungen -Systemnahe Erstellungsaktionen sowie die Umgebung, in der selbige -durchzuführen sind, werden durch @dfn{Ableitungen} dargestellt. Eine -Ableitung enthält folgende Informationen: - -@itemize -@item -Die Ausgaben, die die Ableitung hat. Ableitungen erzeugen mindestens eine -Datei bzw. ein Verzeichnis im Store, können aber auch mehrere erzeugen. - -@item -@cindex build-time dependencies -@cindex dependencies, build-time -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.) - -@item -Das System, wofür mit der Ableitung erstellt wird, also ihr Ziel — -z.B. @code{x86_64-linux}. - -@item -Der Dateiname eines Erstellungsskripts im Store, zusammen mit den -Argumenten, mit denen es aufgerufen werden soll. - -@item -Eine Liste zu definierender Umgebungsvariabler. - -@end itemize - -@cindex Ableitungspfad -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 @code{.drv} enden — diese Dateien -werden als @dfn{Ableitungspfade} bezeichnet. Ableitungspfade können an die -Prozedur @code{build-derivations} übergeben werden, damit die darin -niedergeschriebenen Erstellungsaktionen durchgeführt werden (@pxref{Der Store}). - -@cindex Ableitungen mit fester Ausgabe -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 @dfn{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. - -@cindex references -@cindex run-time dependencies -@cindex dependencies, run-time -The outputs of derivations---i.e., the build results---have a set of -@dfn{references}, as reported by the @code{references} RPC or the -@command{guix gc --references} command (@pxref{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 @code{(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 @code{derivation}: - -@deffn {Scheme-Prozedur} derivation @var{Store} @var{Name} @var{Ersteller} @ - @var{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 -@var{Argumente}n erstellen und das resultierende @code{<derivation>}-Objekt -liefern. - -Wurden @var{hash} und @var{hash-algo} angegeben, wird eine @dfn{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 -@var{recursive?} wahr ist, darf die Ableitung mit fester Ausgabe eine -ausführbare Datei oder ein Verzeichnis sein und @var{hash} muss die -Prüfsumme eines Archivs mit dieser Ausgabe sein. - -Ist @var{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 @var{allowed-references} ein wahr, muss es eine Liste von Store-Objekten -oder Ausgaben sein, die die Ausgabe der Ableitung referenzieren darf. Ebenso -muss @var{disallowed-references}, wenn es auf wahr gesetzt ist, eine Liste -von Dingen bezeichnen, die die Ausgaben @emph{nicht} referenzieren dürfen. - -Ist @var{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 @var{hash} wahr -ist. So ein Leck kann zum Beispiel benutzt werden, um Variable wie -@code{http_proxy} an Ableitungen zu übergeben, die darüber Dateien -herunterladen. - -Ist @var{local-build?} wahr, wird die Ableitung als schlechter Kandidat für -das Auslagern deklariert, der besser lokal erstellt werden sollte -(@pxref{Auslagern des Daemons einrichten}). Dies betrifft kleine Ableitungen, wo das -Übertragen der Daten aufwendiger als ihre Erstellung ist. - -Ist @var{substitutable?} falsch, wird deklariert, dass für die Ausgabe der -Ableitung keine Substitute benutzt werden sollen (@pxref{Substitute}). Das -ist nützlich, wenn Pakete erstellt werden, die Details über den -Prozessorbefehlssatz des Wirtssystems auslesen. - -@var{properties} muss eine assoziative Liste enthalten, die »Eigenschaften« -der Ableitungen beschreibt. Sie wird genau so, wie sie ist, in der Ableitung -gespeichert. -@end deffn - -@noindent -Hier ist ein Beispiel mit einem Shell-Skript, das als Ersteller benutzt -wird. Es wird angenommen, dass @var{Store} eine offene Verbindung zum Daemon -ist und @var{bash} auf eine ausführbare Bash im Store verweist: - -@lisp -(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")))) -@result{} #<derivation /gnu/store/@dots{}-foo.drv => /gnu/store/@dots{}-foo> -@end lisp - -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 @code{gexp->derivation}. Mehr Informationen finden Sie im -Abschnitt @pxref{G-Ausdrücke}. - -Doch es gab einmal eine Zeit, zu der @code{gexp->derivation} noch nicht -existiert hatte und wo das Zusammenstellen von Ableitungen mit -Scheme-Erstellungscode noch mit @code{build-expression->derivation} -bewerkstelligt wurde, was im Folgenden beschrieben wird. Diese Prozedur gilt -als veraltet und man sollte nunmehr die viel schönere Prozedur -@code{gexp->derivation} benutzen. - -@deffn {Scheme-Prozedur} build-expression->derivation @var{Store} @ - @var{Name} @var{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 @var{Ausdruck} als Ersteller einer Ableitung namens -@var{Name} ausführt. @var{inputs} muss die Liste der Eingaben enthalten, -jeweils als Tupel @code{(Name Ableitungspfad Unterableitung)}; wird keine -@var{Unterableitung} angegeben, wird @code{"out"} angenommen. @var{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 -@var{Ausdruck} ausgeführt wird — z.B. @code{((guix build utils) (guix build -gnu-build-system))}. - -Der @var{Ausdruck} wird in einer Umgebung ausgewertet, in der -@code{%outputs} an eine Liste von Ausgabe-/Pfad-Paaren gebunden wurde und in -der @code{%build-inputs} an eine Liste von Zeichenkette-/Ausgabepfad-Paaren -gebunden wurde, die aus den @var{inputs}-Eingaben konstruiert worden -ist. Optional kann in @var{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 @code{exit} -mit dem Ergebnis des @var{Ausdruck}s aufruft; wenn also der @var{Ausdruck} -den Wert @code{#f} liefert, wird angenommen, dass die Erstellung -fehlgeschlagen ist. - -@var{Ausdruck} wird mit einer Ableitung @var{guile-for-build} erstellt. Wird -kein @var{guile-for-build} angegeben oder steht es auf @code{#f}, wird -stattdessen der Wert der Fluiden @code{%guile-for-build} benutzt. - -Siehe die Erklärungen zur Prozedur @code{derivation} für die Bedeutung von -@var{references-graphs}, @var{allowed-references}, -@var{disallowed-references}, @var{local-build?} und @var{substitutable?}. -@end deffn - -@noindent -Hier ist ein Beispiel einer Ableitung mit nur einer Ausgabe, die ein -Verzeichnis erzeugt, in dem eine einzelne Datei enthalten ist: - -@lisp -(let ((builder '(let ((out (assoc-ref %outputs "out"))) - (mkdir out) ; das Verzeichnis - ; /gnu/store/@dots{}-goo erstellen - (call-with-output-file (string-append out "/test") - (lambda (p) - (display '(Hallo Guix) p)))))) - (build-expression->derivation store "goo" builder)) - -@result{} #<derivation /gnu/store/@dots{}-goo.drv => @dots{}> -@end lisp - - -@node Die Store-Monade -@section Die Store-Monade - -@cindex 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. - -@cindex monadische Werte -@cindex monadische Funktionen -Hier kommt das Modul @code{(guix monads)} ins Spiel. Im Rahmen dieses Moduls -können @dfn{Monaden} benutzt werden und dazu gehört insbesondere eine für -unsere Zwecke sehr nützliche Monade, die @dfn{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 @dfn{monadische Werte} genannt; Prozeduren, -die solche Werte liefern, heißen @dfn{monadische Prozeduren}. - -Betrachten Sie folgende »normale« Prozedur: - -@example -(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)))) -@end example - -Unter Verwendung von @code{(guix monads)} und @code{(guix gexp)} lässt sie -sich als monadische Funktion aufschreiben: - -@example -(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)))) -@end example - -An der zweiten Version lassen sich mehrere Dinge beobachten: Der Parameter -@code{Store} ist jetzt implizit geworden und wurde in die Aufrufe der -monadischen Prozeduren @code{package->derivation} und -@code{gexp->derivation} »eingefädelt« und der von @code{package->derivation} -gelieferte monadische Wert wurde mit @code{mlet} statt einem einfachen -@code{let} @dfn{gebunden}. - -Wie sich herausstellt, muss man den Aufruf von @code{package->derivation} -nicht einmal aufschreiben, weil er implizit geschieht, wie wir später sehen -werden (siehe @pxref{G-Ausdrücke}): - -@example -(define (sh-symlink) - (gexp->derivation "sh" - #~(symlink (string-append #$bash "/bin/bash") - #$output))) -@end example - -@c See -@c <https://syntaxexclamation.wordpress.com/2014/06/26/escaping-continuations/> -@c for the funny quote. -Die monadische @code{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 -@code{run-with-store} benutzen: - -@example -(run-with-store (open-connection) (sh-symlink)) -@result{} /gnu/store/...-sh-symlink -@end example - -Erwähnenswert ist, dass das Modul @code{(guix monad-repl)} die REPL von -Guile um neue »Meta-Befehle« erweitert, mit denen es leichter ist, mit -monadischen Prozeduren umzugehen: @code{run-in-store} und -@code{enter-store-monad}. Mit Ersterer wird ein einzelner monadischer Wert -durch den Store »laufen gelassen«: - -@example -scheme@@(guile-user)> ,run-in-store (package->derivation hello) -$1 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> -@end example - -Mit Letzterer wird rekursiv eine weitere REPL betreten, in der alle -Rückgabewerte automatisch durch den Store laufen gelassen werden: - -@example -scheme@@(guile-user)> ,enter-store-monad -store-monad@@(guile-user) [1]> (package->derivation hello) -$2 = #<derivation /gnu/store/@dots{}-hello-2.9.drv => @dots{}> -store-monad@@(guile-user) [1]> (text-file "foo" "Hallo!") -$3 = "/gnu/store/@dots{}-foo" -store-monad@@(guile-user) [1]> ,q -scheme@@(guile-user)> -@end example - -@noindent -Beachten Sie, dass in einer @code{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 @code{(guix monads)} bereitgestellt und sind im -Folgenden beschrieben. - -@deffn {Scheme-Syntax} with-monad @var{Monade} @var{Rumpf} ... -Alle @code{>>=}- oder @code{return}-Formen im @var{Rumpf} in der -@var{Monade} auswerten. -@end deffn - -@deffn {Scheme-Syntax} return @var{Wert} -Einen monadischen Wert liefern, der den übergebenen @var{Wert} kapselt. -@end deffn - -@deffn {Scheme-Syntax} >>= @var{mWert} @var{mProz} ... -Den monadischen Wert @var{mWert} @dfn{binden}, wobei sein »Inhalt« an die -monadischen Prozeduren @var{mProz}@dots{} übergeben wird@footnote{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 @var{mProz} oder mehrere -davon geben, wie in diesem Beispiel: - -@example -(run-with-state - (with-monad %state-monad - (>>= (return 1) - (lambda (x) (return (+ 1 x))) - (lambda (x) (return (* 2 x))))) - 'irgendein-Zustand) - -@result{} 4 -@result{} irgendein-Zustand -@end example -@end deffn - -@deffn {Scheme-Syntax} mlet @var{Monade} ((@var{Variable} @var{mWert}) ...) @ - @var{Rumpf} ... -@deffnx {Scheme-Syntax} mlet* @var{Monade} ((@var{Variable} @var{mWert}) ...) @ - @var{Rumpf} ... Die @var{Variable}n an die monadischen Werte @var{mWert} im -@var{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 @var{mWert} steckt, wobei anschließend -dieser rohe, nicht-monadische Wert im Sichtbarkeitsbereich des @var{Rumpf}s -von der @var{Variable}n bezeichnet wird. Die Form (@var{Variable} -> -@var{Wert}) bindet die @var{Variable} an den »normalen« @var{Wert}, wie es -@code{let} tun würde. Die Bindungsoperation geschieht in der Reihenfolge von -links nach rechts. Der letzte Ausdruck des @var{Rumpfs} muss ein monadischer -Ausdruck sein und dessen Ergebnis wird das Ergebnis von @code{mlet} oder -@code{mlet*} werden, wenn es durch die @var{Monad} laufen gelassen wurde. - -@code{mlet*} verhält sich gegenüber @code{mlet} wie @code{let*} gegenüber -@code{let} (@pxref{Local Bindings,,, guile, GNU Guile Reference Manual}). -@end deffn - -@deffn {Scheme-System} mbegin @var{Monade} @var{mAusdruck} ... -Der Reihe nach den @var{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 @code{mlet}, außer dass die Rückgabewerte der -monadischen Prozeduren ignoriert werden. In diesem Sinn verhält es sich -analog zu @code{begin}, nur auf monadischen Ausdrücken. -@end deffn - -@deffn {Scheme-System} mwhen @var{Bedingung} @var{mAusdr0} @var{mAusdr*} ... -Wenn die @var{Bedingung} wahr ist, wird die Folge monadischer Ausdrücke -@var{mAusdr0}..@var{mAusdr*} wie bei @code{mbegin} ausgewertet. Wenn die -@var{Bedingung} falsch ist, wird @code{*unspecified*} in der momentanen -Monade zurückgeliefert. Jeder Ausdruck in der Folge muss ein monadischer -Ausdruck sein. -@end deffn - -@deffn {Scheme-System} munless @var{Bedingung} @var{mAusdr0} @var{mAusdr*} ... -Wenn die @var{Bedingung} falsch ist, wird die Folge monadischer Ausdrücke -@var{mAusdr0}..@var{mAusdr*} wie bei @code{mbegin} ausgewertet. Wenn die -@var{Bedingung} wahr ist, wird @code{*unspecified*} in der momentanen Monade -zurückgeliefert. Jeder Ausdruck in der Folge muss ein monadischer Ausdruck -sein. -@end deffn - -@cindex Zustandsmonade -Das Modul @code{(guix monads)} macht die @dfn{Zustandsmonade} (englisch -»state monad«) verfügbar, mit der ein zusätzlicher Wert — der Zustand — -durch die monadischen Prozeduraufrufe @emph{gefädelt} werden kann. - -@defvr {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 @code{Quadrat} liefert -einen Wert in der Zustandsmonade zurück. Sie liefert das Quadrat ihres -Arguments, aber sie inkrementiert auch den momentanen Zustandswert: - -@example -(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) -@result{} (0 1 4) -@result{} 3 -@end example - -Wird das »durch« die Zustandsmonade @var{%state-monad} laufen gelassen, -erhalten wir jenen zusätzlichen Zustandswert, der der Anzahl der Aufrufe von -@code{Quadrat} entspricht. -@end defvr - -@deffn {Monadische Prozedur} current-state -Liefert den momentanen Zustand als einen monadischen Wert. -@end deffn - -@deffn {Monadische Prozedur} set-current-state @var{Wert} -Setzt den momentanen Zustand auf @var{Wert} und liefert den vorherigen -Zustand als einen monadischen Wert. -@end deffn - -@deffn {Monadische Prozedur} state-push @var{Wert} -Hängt den @var{Wert} vorne an den momentanen Zustand an, der eine Liste sein -muss. Liefert den vorherigen Zustand als monadischen Wert. -@end deffn - -@deffn {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. -@end deffn - -@deffn {Scheme-Prozedur} run-with-state @var{mWert} [@var{Zustand}] -Den monadischen Wert @var{mWert} mit @var{Zustand} als initialem Zustand -laufen lassen. Dies liefert zwei Werte: den Ergebniswert und den -Ergebniszustand. -@end deffn - -Die zentrale Schnittstelle zur Store-Monade, wie sie vom Modul @code{(guix -store)} angeboten wird, ist die Folgende: - -@defvr {Scheme-Variable} %store-monad -Die Store-Monade — ein anderer Name für @var{%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 @code{run-with-store} übergeben wird (siehe unten). -@end defvr - -@deffn {Scheme-Prozedur} run-with-store @var{Store} @var{mWert} [#:guile-for-build] [#:system (%current-system)] -Den @var{mWert}, einen monadischen Wert in der Store-Monade, in der offenen -Verbindung @var{Store} laufen lassen. -@end deffn - -@deffn {Monadische Prozedur} text-file @var{Name} @var{Text} [@var{Referenzen}] -Als monadischen Wert den absoluten Dateinamen im Store für eine Datei -liefern, deren Inhalt der der Zeichenkette @var{Text} ist. @var{Referenzen} -ist dabei eine Liste von Store-Objekten, die die Ergebnis-Textdatei -referenzieren wird; der Vorgabewert ist die leere Liste. -@end deffn - -@deffn {Monadische Prozedur} binary-file @var{Name} @var{Daten} [@var{Referenzen}] -Den absoluten Dateinamen im Store als monadischen Wert für eine Datei -liefern, deren Inhalt der des Byte-Vektors @var{Daten} ist. @var{Referenzen} -ist dabei eine Liste von Store-Objekten, die die Ergebnis-Binärdatei -referenzieren wird; der Vorgabewert ist die leere Liste. -@end deffn - -@deffn {Monadische Prozedur} interned-file @var{Datei} [@var{Name}] @ - [#:recursive? #t] [#:select? (const #t)] Liefert den Namen der @var{Datei}, -nachdem sie in den Store interniert wurde. Dabei wird der @var{Name} als ihr -Store-Name verwendet, oder, wenn kein @var{Name} angegeben wurde, der -Basisname der @var{Datei}. - -Ist @var{recursive?} wahr, werden in der @var{Datei} enthaltene Dateien -rekursiv hinzugefügt; ist die @var{Datei} eine flache Datei und -@var{recursive?} ist wahr, wird ihr Inhalt in den Store eingelagert und ihre -Berechtigungs-Bits übernommen. - -Steht @var{recursive?} auf wahr, wird @code{(@var{select?} @var{Datei} -@var{Stat})} für jeden Verzeichniseintrag aufgerufen, wobei @var{Datei} der -absolute Dateiname und @var{Stat} das Ergebnis von @code{lstat} ist, außer -auf den Einträgen, wo @var{select?} keinen wahren Wert liefert. - -Folgendes Beispiel fügt eine Datei unter zwei verschiedenen Namen in den -Store ein: - -@example -(run-with-store (open-connection) - (mlet %store-monad ((a (interned-file "README")) - (b (interned-file "README" "LEGU-MIN"))) - (return (list a b)))) - -@result{} ("/gnu/store/rwm@dots{}-README" "/gnu/store/44i@dots{}-LEGU-MIN") -@end example - -@end deffn - -Das Modul @code{(guix packages)} exportiert die folgenden paketbezogenen -monadischen Prozeduren: - -@deffn {Monadische Prozedur} package-file @var{Paket} [@var{Datei}] @ - [#:system (%current-system)] [#:target #f] @ [#:output "out"] Liefert als -monadischen Wert den absoluten Dateinamen der @var{Datei} innerhalb des -Ausgabeverzeichnisses @var{output} des @var{Paket}s. Wird keine @var{Datei} -angegeben, wird der Name des Ausgabeverzeichnisses @var{output} für das -@var{Paket} zurückgeliefert. Ist @var{target} wahr, wird sein Wert als das -Zielsystem bezeichnendes Tripel zum Cross-Kompilieren benutzt. -@end deffn - -@deffn {Monadische Prozedur} package->derivation @var{Paket} [@var{System}] -@deffnx {Monadische Prozedur} package->cross-derivation @var{Paket} @ - @var{Ziel} [@var{System}] Monadische Version von @code{package-derivation} -und @code{package-cross-derivation} (@pxref{Pakete definieren}). -@end deffn - - -@node G-Ausdrücke -@section G-Ausdrücke - -@cindex G-Ausdruck -@cindex Erstellungscode maskieren -Es gibt also »Ableitungen«, die eine Abfolge von Erstellungsaktionen -repräsentieren, die durchgeführt werden müssen, um ein Objekt im Store zu -erzeugen (@pxref{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 (@pxref{Aufruf des guix-daemon}). - -@cindex Schichten von Code -Wenig überraschend ist, dass wir diese Erstellungsaktionen gerne in Scheme -schreiben würden. Wenn wir das tun, bekommen wir zwei verschiedene -@dfn{Schichten} von Scheme-Code@footnote{Der Begriff @dfn{Schicht}, englisch -Stratum, wurde in diesem Kontext von Manuel Serrano et al.@: in ihrer Arbeit -an Hop geprägt. Oleg Kiselyov, der aufschlussreiche -@url{http://okmij.org/ftp/meta-programming/#meta-scheme, Essays und Code zu -diesem Thema} geschrieben hat, nennt diese Art der Code-Generierung -@dfn{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, @command{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 @code{quasiquote} in Scheme, wenn -wir Erstellungsausdrücke konstruieren möchten. - -Das Modul @code{(guix gexp)} implementiert @dfn{G-Ausdrücke}, eine Form von -S-Ausdrücken, die zu Erstellungsausdrücken angepasst wurden. G-Ausdrücke -(englisch »G-expressions«, kurz @dfn{Gexps}) setzen sich grundlegend aus -drei syntaktischen Formen zusammen: @code{gexp}, @code{ungexp} und -@code{ungexp-splicing} (alternativ einfach: @code{#~}, @code{#$} und -@code{#$@@}), die jeweils mit @code{quasiquote}, @code{unquote} und -@code{unquote-splicing} vergleichbar sind (@pxref{Expression Syntax, -@code{quasiquote},, guile, GNU Guile Reference Manual}). Es gibt aber auch -erhebliche Unterschiede: - -@itemize -@item -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. - -@item -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. - -@item -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. -@end itemize - -@cindex Herunterbrechen, von abstrakten Objekten in G-Ausdrücken -Dieser Mechanismus ist nicht auf Pakete und Ableitung beschränkt: Es können -@dfn{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 @code{local-file} und -@code{plain-file}). - -Zur Veranschaulichung dieser Idee soll uns dieses Beispiel eines G-Ausdrucks -dienen: - -@example -(define build-exp - #~(begin - (mkdir #$output) - (chdir #$output) - (symlink (string-append #$coreutils "/bin/ls") - "list-files"))) -@end example - -Indem wir diesen G-Ausdruck an @code{gexp->derivation} übergeben, bekommen -wir eine Ableitung, die ein Verzeichnis mit genau einer symbolischen -Verknüpfung auf @file{/gnu/store/@dots{}-coreutils-8.22/bin/ls} erstellt: - -@example -(gexp->derivation "das-ding" build-exp) -@end example - -Wie man es erwarten würde, wird die Zeichenkette -@code{"/gnu/store/@dots{}-coreutils-8.22"} anstelle der Referenzen auf das -Paket @var{coreutils} im eigentlichen Erstellungscode eingefügt und -@var{coreutils} automatisch zu einer Eingabe der Ableitung gemacht. Genauso -wird auch @code{#$output} (was äquivalent zur Schreibweise @code{(ungexp -output)} ist) ersetzt durch eine Zeichenkette mit dem Namen der Ausgabe der -Ableitung. - -@cindex Cross-Kompilieren -Im Kontext der Cross-Kompilierung bietet es sich an, zwischen Referenzen auf -die @emph{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 @code{#+} dieselbe Rolle wie -@code{#$}, steht aber für eine Referenz auf eine native Paketerstellung. - -@example -(gexp->derivation "vi" - #~(begin - (mkdir #$output) - (system* (string-append #+coreutils "/bin/ln") - "-s" - (string-append #$emacs "/bin/emacs") - (string-append #$output "/bin/vi"))) - #:target "mips64el-linux-gnu") -@end example - -@noindent -Im obigen Beispiel wird die native Erstellung der @var{coreutils} benutzt, -damit @command{ln} tatsächlich auf dem Wirtssystem ausgeführt werden kann, -aber danach die cross-kompilierte Erstellung von @var{emacs} referenziert. - -@cindex importierte Module, in G-Ausdrücken -@findex with-imported-modules -Eine weitere Funktionalität von G-Ausdrücken stellen @dfn{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 -@code{with-imported-modules}-Form macht das möglich: - -@example -(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))) -@end example - -@noindent -In diesem Beispiel wird das Modul @code{(guix build utils)} automatisch in -die isolierte Erstellungsumgebung unseres G-Ausdrucks geholt, so dass -@code{(use-modules (guix build utils))} wie erwartet funktioniert. - -@cindex Modulabschluss -@findex source-module-closure -Normalerweise möchten Sie, dass der @emph{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 @code{source-module-closure} -berechnet den Abschluss eines Moduls, indem es den Kopf seiner Quelldatei -analysiert, deswegen schafft die Prozedur hier Abhilfe: - -@example -(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)) - @dots{}))) -@end example - -@cindex Erweiterungen, für G-Ausdrücke -@findex with-extensions -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 @code{guile-json} auf der -Erstellungsseite, dann könnten Sie es hiermit bekommen: - -@example -(use-modules (gnu packages guile)) ;für »guile-json« - -(with-extensions (list guile-json) - (gexp->derivation "etwas-mit-json" - #~(begin - (use-modules (json)) - @dots{}))) -@end example - -Die syntaktische Form, in der G-Ausdrücke konstruiert werden, ist im -Folgenden zusammengefasst. - -@deffn {Scheme-Syntax} #~@var{Ausdruck} -@deffnx {Scheme-Syntax} (gexp @var{Ausdruck}) -Liefert einen G-Ausdruck, der den @var{Ausdruck} enthält. Der @var{Ausdruck} -kann eine oder mehrere der folgenden Formen enthalten: - -@table @code -@item #$@var{Objekt} -@itemx (ungexp @var{Objekt}) -Eine Referenz auf das @var{Objekt} einführen. Das @var{Objekt} kann einen -der unterstützten Typen haben, zum Beispiel ein Paket oder eine Ableitung, -so dass die @code{ungexp}-Form durch deren Ausgabedateiname ersetzt wird — -z.B. @code{"/gnu/store/@dots{}-coreutils-8.22}. - -Wenn das @var{Objekt} eine Liste ist, wird diese durchlaufen und alle -unterstützten Objekte darin auf diese Weise ersetzt. - -Wenn das @var{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 @var{Objekt} eine andere Art von Objekt ist, wird es so wie es ist -eingefügt. - -@item #$@var{Objekt}:@var{Ausgabe} -@itemx (ungexp @var{Objekt} @var{Ausgabe}) -Dies verhält sich wie die Form oben, bezieht sich aber ausdrücklich auf die -angegebene @var{Ausgabe} des @var{Objekt}s — dies ist nützlich, wenn das -@var{Objekt} mehrere Ausgaben generiert (@pxref{Pakete mit mehreren Ausgaben.}). - -@item #+@var{Objekt} -@itemx #+@var{Objekt}:@var{Ausgabe} -@itemx (ungexp-native @var{Objekt}) -@itemx (ungexp-native @var{Objekt} @var{Ausgabe}) -Das Gleiche wie @code{ungexp}, jedoch wird im Kontext einer -Cross-Kompilierung eine Referenz auf die @emph{native} Erstellung des -@var{Objekt}s eingefügt. - -@item #$output[:@var{Ausgabe}] -@itemx (ungexp output [@var{Ausgabe}]) -Fügt eine Referenz auf die angegebene @var{Ausgabe} dieser Ableitung ein, -oder auf die Hauptausgabe, wenn keine @var{Ausgabe} angegeben wurde. - -Dies ist nur bei G-Ausdrücken sinnvoll, die an @code{gexp->derivation} -übergeben werden. - -@item #$@@@var{Liste} -@itemx (ungexp-splicing @var{Liste}) -Das Gleiche wie oben, jedoch wird nur der Inhalt der @var{Liste} in die -äußere Liste eingespleißt. - -@item #+@@@var{Liste} -@itemx (ungexp-native-splicing @var{Liste}) -Das Gleiche, aber referenziert werden native Erstellungen der Objekte in der -@var{Liste}. - -@end table - -G-Ausdrücke, die mit @code{gexp} oder @code{#~} erzeugt wurden, sind zur -Laufzeit Objekte vom Typ @code{gexp?} (siehe unten). -@end deffn - -@deffn {Scheme-Syntax} with-imported-modules @var{Module} @var{Rumpf}@dots{} -Markiert die in @var{Rumpf}@dots{} definierten G-Ausdrücke, dass sie in -ihrer Ausführungsumgebung die angegebenen @var{Module} brauchen. - -Jedes Objekt unter den @var{Module}n kann der Name eines Moduls wie -@code{(guix build utils)} sein, oder es kann nacheinander ein Modulname, ein -Pfeil und ein dateiartiges Objekt sein: - -@example -`((guix build utils) - (guix gcrypt) - ((guix config) => ,(scheme-file "config.scm" - #~(define-module @dots{})))) -@end example - -@noindent -Im Beispiel oben werden die ersten beiden Module vom Suchpfad genommen und -das letzte aus dem angegebenen dateiartigen Objekt erzeugt. - -Diese Form hat einen @emph{lexikalischen} Sichtbarkeitsbereich: Sie wirkt -sich auf die direkt in @var{Rumpf}@dots{} definierten G-Ausdrücke aus, aber -nicht auf jene, die, sagen wir, in aus @var{Rumpf}@dots{} heraus -aufgerufenen Prozeduren definiert wurden. -@end deffn - -@deffn {Scheme-Syntax} with-extensions @var{Erweiterungen} @var{Rumpf}@dots{} -Markiert die in @var{Rumpf}@dots{} definierten G-Ausdrücke, dass sie -@var{Erweiterungen} in ihrer Erstellungs- und Ausführungsumgebung -benötigen. @var{Erweiterungen} sind typischerweise eine Liste von -Paketobjekten wie zum Beispiel die im Modul @code{(gnu packages guile)} -definierten. - -Konkret werden die unter den @var{Erweiterungen} aufgeführten Pakete zum -Ladepfad hinzugefügt, während die in @var{Rumpf}@dots{} aufgeführten -importierten Module kompiliert werden und sie werden auch zum Ladepfad des -von @var{Rumpf}@dots{} gelieferten G-Ausdrucks hinzugefügt. -@end deffn - -@deffn {Scheme-Prozedur} gexp? @var{Objekt} -Liefert @code{#t}, wenn das @var{Objekt} ein G-Ausdruck ist. -@end deffn - -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 (@pxref{Die Store-Monade}, wenn Sie mehr Informationen über Monaden suchen). - -@deffn {Monadische Prozedur} gexp->derivation @var{Name} @var{Ausdruck} @ - [#:system (%current-system)] [#:target #f] [#:graft? #t] @ [#:hash #f] -[#:hash-algo #f] @ [#:recursive? #f] [#:env-vars '()] [#:modules '()] @ -[#:module-path @var{%load-path}] @ [#:effective-version "2.2"] @ -[#:references-graphs #f] [#:allowed-references #f] @ -[#:disallowed-references #f] @ [#:leaked-env-vars #f] @ [#:script-name -(string-append @var{Name} "-builder")] @ [#:deprecation-warnings #f] @ -[#:local-build? #f] [#:substitutable? #t] @ [#:properties '()] -[#:guile-for-build #f] Liefert eine Ableitung unter dem @var{Name}n, die -jeden @var{Ausdruck} (ein G-Ausdruck) mit @var{guile-for-build} (eine -Ableitung) für das @var{System} erstellt; der @var{Ausdruck} wird dabei in -einer Datei namens @var{script-name} gespeichert. Wenn »@var{target}« wahr -ist, wird es beim Cross-Kompilieren als Zieltripel für mit @var{Ausdruck} -bezeichnete Pakete benutzt. - -@var{modules} gilt als veraltet; stattdessen sollte -@code{with-imported-modules} benutzt werden. Die Bedeutung ist, dass die -@var{Module} im Ausführungskontext des @var{Ausdruck}s verfügbar gemacht -werden; @var{modules} ist dabei eine Liste von Namen von Guile-Modulen, die -im Modulpfad @var{module-path} gesucht werden, um sie in den Store zu -kopieren, zu kompilieren und im Ladepfad während der Ausführung des -@var{Ausdruck}s verfügbar zu machen — z.B. @code{((guix build utils) (guix -build gnu-build-system))}. - -@var{effective-version} bestimmt, unter welcher Zeichenkette die -Erweiterungen des @var{Ausdruck}s zum Suchpfad hinzugefügt werden (siehe -@code{with-extensions}) — z.B. @code{"2.2"}. - -@var{graft?} bestimmt, ob vom @var{Ausdruck} benannte Pakete veredelt werden -sollen, falls Veredelungen zur Verfügung stehen. - -Ist @var{references-graphs} wahr, muss es eine Liste von Tupeln in einer der -folgenden Formen sein: - -@example -(@var{Dateiname} @var{Paket}) -(@var{Dateiname} @var{Paket} @var{Ausgabe}) -(@var{Dateiname} @var{Ableitung}) -(@var{Dateiname} @var{Ableitung} @var{Ausgabe}) -(@var{Dateiname} @var{Store-Objekt}) -@end example - -Bei jedem Element von @var{references-graphs} wird das rechts Stehende -automatisch zu einer Eingabe des Erstellungsprozesses vom @var{Ausdruck} -gemacht. In der Erstellungsumgebung enthält das, was mit @var{Dateiname} -bezeichnet wird, den Referenzgraphen des entsprechenden Objekts in einem -einfachen Textformat. - -@var{allowed-references} muss entweder @code{#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 @var{disallowed-references}, was eine Liste von Objekten sein -kann, die von den Ausgaben nicht referenziert werden dürfen. - -@var{deprecation-warnings} bestimmt, ob beim Kompilieren von Modulen -Warnungen angezeigt werden sollen, wenn auf als veraltet markierten Code -zugegriffen wird (»deprecation warnings«). @var{deprecation-warnings} kann -@code{#f}, @code{#t} oder @code{'detailed} (detailliert) sein. - -Die anderen Argumente verhalten sich wie bei @code{derivation} -(@pxref{Ableitungen}). -@end deffn - -@cindex dateiartige Objekte -Die im Folgenden erklärten Prozeduren @code{local-file}, @code{plain-file}, -@code{computed-file}, @code{program-file} und @code{scheme-file} liefern -@dfn{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: - -@example -#~(system* #$(file-append glibc "/sbin/nscd") "-f" - #$(local-file "/tmp/my-nscd.conf")) -@end example - -Der Effekt hiervon ist, dass @file{/tmp/my-nscd.conf} »interniert« wird, -indem es in den Store kopiert wird. Sobald er umgeschrieben wurde, zum -Beispiel über @code{gexp->derivation}, referenziert der G-Ausdruck diese -Kopie im @file{/gnu/store}. Die Datei in @file{/tmp} zu bearbeiten oder zu -löschen, hat dann keinen Effekt mehr darauf, was der G-Ausdruck -tut. @code{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. - -@deffn {Scheme-Prozedur} local-file @var{Datei} [@var{Name}] @ - [#:recursive? #f] [#:select? (const #t)] Liefert ein Objekt, dass die lokale -Datei @var{Datei} repräsentiert und sie zum Store hinzufügen lässt; dieses -Objekt kann in einem G-Ausdruck benutzt werden. Wurde für die @var{Datei} -ein relativer Dateiname angegeben, wird sie relativ zur Quelldatei gesucht, -in der diese Form steht. Die @var{Datei} wird unter dem angegebenen -@var{Name}n im Store abgelegt — als Vorgabe wird dabei der Basisname der -@var{Datei} genommen. - -Ist @var{recursive?} wahr, werden in der @var{Datei} enthaltene Dateien -rekursiv hinzugefügt; ist die @var{Datei} eine flache Datei und -@var{recursive?} ist wahr, wird ihr Inhalt in den Store eingelagert und ihre -Berechtigungs-Bits übernommen. - -Steht @var{recursive?} auf wahr, wird @code{(@var{select?} @var{Datei} -@var{Stat})} für jeden Verzeichniseintrag aufgerufen, wobei @var{Datei} der -absolute Dateiname und @var{Stat} das Ergebnis von @code{lstat} ist, außer -auf den Einträgen, wo @var{select?} keinen wahren Wert liefert. - -Dies ist das deklarative Gegenstück zur monadischen Prozedur -@code{interned-file} (@pxref{Die Store-Monade, @code{interned-file}}). -@end deffn - -@deffn {Scheme-Prozedur} plain-file @var{Name} @var{Inhalt} -Liefert ein Objekt, das eine Textdatei mit dem angegebenen @var{Name}n -repräsentiert, die den angegebenen @var{Inhalt} hat (eine Zeichenkette oder -ein Bytevektor), welche zum Store hinzugefügt werden soll. - -Dies ist das deklarative Gegenstück zu @code{text-file}. -@end deffn - -@deffn {Scheme-Prozedur} computed-file @var{Name} @var{G-Ausdruck} @ - [#:options '(#:local-build? #t)] Liefert ein Objekt, das das Store-Objekt -mit dem @var{Name}n repräsentiert, eine Datei oder ein Verzeichnis, das vom -@var{G-Ausdruck} berechnet wurde. @var{options} ist eine Liste zusätzlicher -Argumente, die an @code{gexp->derivation} übergeben werden. - -Dies ist das deklarative Gegenstück zu @code{gexp->derivation}. -@end deffn - -@deffn {Monadische Prozedur} gexp->script @var{Name} @var{Ausdruck} @ - [#:guile (default-guile)] [#:module-path %load-path] Liefert ein -ausführbares Skript namens @var{Name}, das den @var{Ausdruck} mit dem -angegebenen @var{guile} ausführt, wobei vom @var{Ausdruck} importierte -Module in seinem Suchpfad stehen. Die Module des @var{Ausdruck}s werden dazu -im Modulpfad @var{module-path} gesucht. - -Folgendes Beispiel erstellt ein Skript, das einfach nur den Befehl -@command{ls} ausführt: - -@example -(use-modules (guix gexp) (gnu packages base)) - -(gexp->script "list-files" - #~(execl #$(file-append coreutils "/bin/ls") - "ls")) -@end example - -Lässt man es durch den Store »laufen« (siehe @pxref{Die Store-Monade, -@code{run-with-store}}), erhalten wir eine Ableitung, die eine ausführbare -Datei @file{/gnu/store/@dots{}-list-files} generiert, ungefähr so: - -@example -#!/gnu/store/@dots{}-guile-2.0.11/bin/guile -ds -!# -(execl "/gnu/store/@dots{}-coreutils-8.22"/bin/ls" "ls") -@end example -@end deffn - -@deffn {Scheme-Prozedur} program-file @var{Name} @var{G-Ausdruck} @ - [#:guile #f] [#:module-path %load-path] Liefert ein Objekt, das eine -ausführbare Store-Datei @var{Name} repräsentiert, die den @var{G-Ausdruck} -ausführt. @var{guile} ist das zu verwendende Guile-Paket, mit dem das Skript -ausgeführt werden kann. Importierte Module des @var{G-Ausdruck}s werden im -Modulpfad @var{module-path} gesucht. - -Dies ist das deklarative Gegenstück zu @code{gexp->script}. -@end deffn - -@deffn {Monadische Prozedur} gexp->file @var{Name} @var{G-Ausdruck} @ - [#:set-load-path? #t] [#:module-path %load-path] @ [#:splice? #f] @ [#:guile -(default-guile)] Liefert eine Ableitung, die eine Datei @var{Name} erstellen -wird, deren Inhalt der @var{G-Ausdruck} ist. Ist @var{splice?} wahr, dann -wird @var{G-Ausdruck} stattdessen als eine Liste von mehreren G-Ausdrücken -behandelt, die alle in die resultierende Datei gespleißt werden. - -Ist @var{set-load-path?} wahr, wird in die resultierende Datei Code -hinzugefügt, der den Ladepfad @code{%load-path} und den Ladepfad für -kompilierte Dateien @code{%load-compiled-path} festlegt, die für die -importierten Module des @var{G-Ausdruck}s nötig sind. Die Module des -@var{G-Ausdruck}s werden im Modulpfad @var{module-path} gesucht. - -Die resultierende Datei referenziert alle Abhängigkeiten des -@var{G-Ausdruck}s oder eine Teilmenge davon. -@end deffn - -@deffn {Scheme-Prozedur} scheme-file @var{Name} @var{G-Ausdruck} [#:splice? #f] -Liefert ein Objekt, das die Scheme-Datei @var{Name} mit dem @var{G-Ausdruck} -als Inhalt repräsentiert. - -Dies ist das deklarative Gegenstück zu @code{gexp->file}. -@end deffn - -@deffn {Monadische Prozedur} text-file* @var{Name} @var{Text} @dots{} -Liefert eine Ableitung als monadischen Wert, welche eine Textdatei erstellt, -in der der gesamte @var{Text} enthalten ist. @var{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 @code{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: - -@example -(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")) -@end example - -In diesem Beispiel wird die resultierende Datei -@file{/gnu/store/@dots{}-profile.sh} sowohl @var{coreutils}, @var{grep} als -auch @var{sed} referenzieren, so dass der Müllsammler diese nicht löscht, -während die resultierende Datei noch lebendig ist. -@end deffn - -@deffn {Scheme-Prozedur} mixed-text-file @var{Name} @var{Text} @dots{} -Liefert ein Objekt, was die Store-Datei @var{Name} repräsentiert, die -@var{Text} enthält. @var{Text} ist dabei eine Folge von Zeichenketten und -dateiartigen Objekten wie zum Beispiel: - -@example -(mixed-text-file "profile" - "export PATH=" coreutils "/bin:" grep "/bin") -@end example - -Dies ist das deklarative Gegenstück zu @code{text-file*}. -@end deffn - -@deffn {Scheme-Prozedur} file-union @var{Name} @var{Dateien} -Liefert ein @code{<computed-file>}, das ein Verzeichnis mit allen -@var{Dateien} enthält. Jedes Objekt in @var{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: - -@example -(file-union "etc" - `(("hosts" ,(plain-file "hosts" - "127.0.0.1 localhost")) - ("bashrc" ,(plain-file "bashrc" - "alias ls='ls --color=auto'")))) -@end example - -Dies liefert ein Verzeichnis @code{etc}, das zwei Dateien enthält. -@end deffn - -@deffn {Scheme-Prozedur} directory-union @var{Name} @var{Dinge} -Liefert ein Verzeichnis, was die Vereinigung (englisch »Union«) der -@var{Dinge} darstellt, wobei @var{Dinge} eine Liste dateiartiger Objekte -sein muss, die Verzeichnisse bezeichnen. Zum Beispiel: - -@example -(directory-union "guile+emacs" (list guile emacs)) -@end example - -Das liefert ein Verzeichnis, welches die Vereinigung der Pakete @code{guile} -und @code{emacs} ist. -@end deffn - -@deffn {Scheme-Prozedur} file-append @var{Objekt} @var{Suffix} @dots{} -Liefert ein dateiartiges Objekt, das zur Aneinanderreihung von @var{Objekt} -und @var{Suffix} umgeschrieben wird, wobei das @var{Objekt} ein -herunterbrechbares Objekt und jedes @var{Suffix} eine Zeichenkette sein -muss. - -Betrachten Sie zum Beispiel diesen G-Ausdruck: - -@example -(gexp->script "uname-ausfuehren" - #~(system* #$(file-append coreutils - "/bin/uname"))) -@end example - -Denselben Effekt könnte man erreichen mit: - -@example -(gexp->script "uname-ausfuehren" - #~(system* (string-append #$coreutils - "/bin/uname"))) -@end example - -Es gibt jedoch einen Unterschied, nämlich enthält das resultierende Skript -bei @code{file-append} tatsächlich den absoluten Dateinamen als -Zeichenkette, während im anderen Fall das resultierende Skript einen -Ausdruck @code{(string-append @dots{})} enthält, der den Dateinamen erst -@emph{zur Laufzeit} zusammensetzt. -@end deffn - - -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 @code{(guix build -@dots{})}. - -@cindex Herunterbrechen, von abstrakten Objekten in G-Ausdrücken -Intern werden hochsprachliche, abstrakte Objekte mit ihrem Compiler entweder -zu Ableitungen oder zu Store-Objekten @dfn{heruntergebrochen}. Wird zum -Beispiel ein Paket heruntergebrochen, bekommt man eine Ableitung, während -ein @code{plain-file} zu einem Store-Objekt heruntergebrochen wird. Das wird -mit der monadischen Prozedur @code{lower-object} bewerkstelligt. - -@deffn {Monadische Prozedur} lower-object @var{Objekt} [@var{System}] @ - [#:target #f] Liefert die Ableitung oder das Store-Objekt, das dem -@var{Objekt} für @var{System} als Wert in der Store-Monade -@var{%store-monad} entspricht, cross-kompiliert für das Zieltripel -@var{target}, wenn @var{target} wahr ist. Das @var{Objekt} muss ein Objekt -sein, für das es einen mit ihm assoziierten G-Ausdruck-Compiler gibt, wie -zum Beispiel ein @code{<package>}. -@end deffn - -@node Aufruf von guix repl -@section @command{guix repl} aufrufen - -@cindex REPL (Lese-Auswerten-Schreiben-Schleife) -The @command{guix repl} command spawns a Guile @dfn{read-eval-print loop} -(REPL) for interactive programming (@pxref{Using Guile Interactively,,, -guile, GNU Guile Reference Manual}). Compared to just launching the -@command{guile} command, @command{guix repl} guarantees that all the Guix -modules and all its dependencies are available in the search path. You can -use it this way: - -@example -$ guix repl -scheme@@(guile-user)> ,use (gnu packages base) -scheme@@(guile-user)> coreutils -$1 = #<package coreutils@@8.29 gnu/packages/base.scm:327 3e28300> -@end example - -@cindex Untergeordnete -In addition, @command{guix repl} implements a simple machine-readable REPL -protocol for use by @code{(guix inferior)}, a facility to interact with -@dfn{inferiors}, separate processes running a potentially different revision -of Guix. - -Folgende @var{Optionen} gibt es: - -@table @code -@item --type=@var{type} -@itemx -t @var{type} -Start a REPL of the given @var{TYPE}, which can be one of the following: - -@table @code -@item guile -This is default, and it spawns a standard full-featured Guile REPL. -@item machine -Spawn a REPL that uses the machine-readable protocol. This is the protocol -that the @code{(guix inferior)} module speaks. -@end table - -@item --listen=@var{Endpunkt} -By default, @command{guix repl} reads from standard input and writes to -standard output. When this option is passed, it will instead listen for -connections on @var{endpoint}. Here are examples of valid options: - -@table @code -@item --listen=tcp:37146 -Accept connections on localhost on port 37146. - -@item --listen=unix:/tmp/socket -Accept connections on the Unix-domain socket @file{/tmp/socket}. -@end table -@end table - -@c ********************************************************************* -@node Zubehör -@chapter 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. - -@menu -* Aufruf von guix build:: Pakete aus der Befehlszeile heraus erstellen. -* Aufruf von guix edit:: Paketdefinitionen bearbeiten. -* Aufruf von guix download:: Herunterladen einer Datei und Ausgabe ihres - Hashes. -* Aufruf von guix hash:: Den kryptographischen Hash einer Datei - berechnen. -* Aufruf von guix import:: Paketdefinitionen importieren. -* Aufruf von guix refresh:: Paketdefinitionen aktualisieren. -* Aufruf von guix lint:: Fehler in Paketdefinitionen finden. -* Aufruf von guix size:: Plattenverbrauch profilieren. -* Aufruf von guix graph:: Den Paketgraphen visualisieren. -* Aufruf von guix publish:: Substitute teilen. -* Aufruf von guix challenge:: Die Substitut-Server anfechten. -* Aufruf von guix copy:: Mit einem entfernten Store Dateien austauschen. -* Aufruf von guix container:: Prozesse isolieren. -* Aufruf von guix weather:: Die Verfügbarkeit von Substituten - einschätzen. -* Aufruf von guix processes:: Auflisten der Client-Prozesse -@end menu - -@node Aufruf von guix build -@section Aufruf von @command{guix build} - -@cindex Paketerstellung -@cindex @command{guix build} -Der Befehl @command{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 @command{guix package} -(@pxref{Aufruf von guix package}). @command{guix build} wird also -hauptsächlich von Entwicklern der Distribution benutzt. - -Die allgemeine Syntax lautet: - -@example -guix build @var{Optionen} @var{Paket-oder-Ableitung}@dots{} -@end example - -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: - -@example -guix build emacs guile -@end example - -Folgender Befehl erstellt alle Pakete, die zur Verfügung stehen: - -@example -guix build --quiet --keep-going \ - `guix package -A | cut -f1,2 --output-delimiter=@@` -@end example - -Als @var{Paket-oder-Ableitung} muss entweder der Name eines in der -Software-Distribution zu findenden Pakets, wie etwa @code{coreutils} oder -@code{coreutils@@8.20}, oder eine Ableitung wie -@file{/gnu/store/@dots{}-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 (@pxref{Paketmodule}). - -Alternativ kann die Befehlszeilenoption @code{--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 @var{Optionen} können angegeben werden. Zur Verfügung stehen -die in den folgenden Unterabschnitten beschriebenen Befehlszeilenoptionen. - -@menu -* Gemeinsame Erstellungsoptionen:: Erstellungsoptionen für die meisten - Befehle. -* Paketumwandlungsoptionen:: Varianten von Paketen erzeugen. -* Zusätzliche Erstellungsoptionen:: Optionen spezifisch für »guix - build«. -* Fehlschläge beim Erstellen untersuchen:: Praxiserfahrung bei der - Paketerstellung. -@end menu - -@node Gemeinsame Erstellungsoptionen -@subsection Gemeinsame Erstellungsoptionen - -Einige dieser Befehlszeilenoptionen zur Steuerung des Erstellungsprozess -haben @command{guix build} und andere Befehle, mit denen Erstellungen -ausgelöst werden können, wie @command{guix package} oder @command{guix -archive}, gemeinsam. Das sind folgende: - -@table @code - -@item --load-path=@var{Verzeichnis} -@itemx -L @var{Verzeichnis} -Das @var{Verzeichnis} vorne an den Suchpfad für Paketmodule anfügen -(@pxref{Paketmodule}). - -Damit können Nutzer dafür sorgen, dass ihre eigenen selbstdefinierten Pakete -für die Befehlszeilenwerkzeuge sichtbar sind. - -@item --keep-failed -@itemx -K -Den Verzeichnisbaum, in dem fehlgeschlagene Erstellungen durchgeführt -wurden, behalten. Wenn also eine Erstellung fehlschlägt, bleibt ihr -Erstellungsbaum in @file{/tmp} erhalten. Der Name dieses Unterverzeichnisses -wird am Ende dem Erstellungsprotokolls ausgegeben. Dies hilft bei der Suche -nach Fehlern in Erstellungen. Der Abschnitt @xref{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 @code{guix://}-URI verwendet wurde (@pxref{Der Store, the @code{GUIX_DAEMON_SOCKET} variable}). - -@item --keep-going -@itemx -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. - -@item --dry-run -@itemx -n -Die Ableitungen nicht erstellen. - -@anchor{fallback-option} -@item --fallback -Wenn das Substituieren vorerstellter Binärdateien fehlschlägt, diese als -»Fallback« lokal selbst erstellen (@pxref{Fehler bei der Substitution}). - -@item --substitute-urls=@var{URLs} -@anchor{client-substitute-urls} -Die @var{urls} als durch Leerraumzeichen getrennte Liste von Quell-URLs für -Substitute anstelle der vorgegebenen URL-Liste für den @command{guix-daemon} -verwenden (@pxref{daemon-substitute-urls,, @command{guix-daemon} URLs}). - -Das heißt, die Substitute dürfen von den @var{urls} heruntergeladen werden, -sofern sie mit einem durch den Systemadministrator autorisierten Schlüssel -signiert worden sind (@pxref{Substitute}). - -Wenn als @var{urls} eine leere Zeichenkette angegeben wurde, verhält es -sich, als wären Substitute abgeschaltet. - -@item --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 (@pxref{Substitute}). - -@item --no-grafts -Pakete nicht »veredeln« (engl. »graft«). Praktisch heißt das, dass als -Veredelungen verfügbare Paketaktualisierungen nicht angewandt werden. Der -Abschnitt @xref{Sicherheitsaktualisierungen} hat weitere Informationen zu Veredelungen. - -@item --rounds=@var{n} -Jede Ableitung @var{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 @emph{verifizieren} -können, ob von Drittanbietern bereitgestellte Binärdateien echt sind. Der -Abschnitt @xref{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 @code{guix -archive --export} auslagern (@pxref{Aufruf von guix archive}), dann neu -erstellen und letztlich die beiden Erstellungsergebnisse vergleichen. - -@item --no-build-hook -Nicht versuchen, Erstellungen über den »Build-Hook« des Daemons auszulagern -(@pxref{Auslagern des Daemons einrichten}). Somit wird lokal erstellt, statt -Erstellungen auf entfernte Maschinen auszulagern. - -@item --max-silent-time=@var{Sekunden} -Wenn der Erstellungs- oder Substitutionsprozess länger als -@var{Sekunden}-lang keine Ausgabe erzeugt, wird er abgebrochen und ein -Fehler beim Erstellen gemeldet. - -Standardmäßig wird die Einstellung für den Daemon benutzt (@pxref{Aufruf des guix-daemon, @code{--max-silent-time}}). - -@item --timeout=@var{Sekunden} -Entsprechend wird hier der Erstellungs- oder Substitutionsprozess -abgebrochen und als Fehlschlag gemeldet, wenn er mehr als -@var{Sekunden}-lang dauert. - -Standardmäßig wird die Einstellung für den Daemon benutzt (@pxref{Aufruf des guix-daemon, @code{--timeout}}). - -@c Note: This option is actually not part of %standard-build-options but -@c most programs honor it. -@cindex verbosity, of the command-line tools -@cindex build logs, verbosity -@item -v @var{level} -@itemx --verbosity=@var{Stufe} -Use the given verbosity @var{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. - -@item --cores=@var{n} -@itemx -c @var{n} -Die Nutzung von bis zu @var{n} Prozessorkernen für die Erstellungen -gestatten. Der besondere Wert @code{0} bedeutet, dass so viele wie möglich -benutzt werden. - -@item --max-jobs=@var{n} -@itemx -M @var{n} -Höchstens @var{n} gleichzeitige Erstellungsaufträge erlauben. Im Abschnitt -@xref{Aufruf des guix-daemon, @code{--max-jobs}}, finden Sie Details zu dieser -Option und der äquivalenten Option des @command{guix-daemon}. - -@item --debug=@var{level} -Produce debugging output coming from the build daemon. @var{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. - -@end table - -Intern ist @command{guix build} im Kern eine Schnittstelle zur Prozedur -@code{package-derivation} aus dem Modul @code{(guix packages)} und zu der -Prozedur @code{build-derivations} des Moduls @code{(guix derivations)}. - -Neben auf der Befehlszeile übergebenen Optionen beachten @command{guix -build} und andere @command{guix}-Befehle, die Erstellungen durchführen -lassen, die Umgebungsvariable @code{GUIX_BUILD_OPTIONS}. - -@defvr {Umgebungsvariable} GUIX_BUILD_OPTIONS -Nutzer können diese Variable auf eine Liste von Befehlszeilenoptionen -definieren, die automatisch von @command{guix build} und anderen -@command{guix}-Befehlen, die Erstellungen durchführen lassen, benutzt wird, -wie in folgendem Beispiel: - -@example -$ export GUIX_BUILD_OPTIONS="--no-substitutes -c 2 -L /foo/bar" -@end example - -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. -@end defvr - - -@node Paketumwandlungsoptionen -@subsection Paketumwandlungsoptionen - -@cindex Paketvarianten -Eine weitere Gruppe von Befehlszeilenoptionen, die @command{guix build} und -auch @command{guix package} unterstützen, sind -@dfn{Paketumwandlungsoptionen}. Diese Optionen ermöglichen es, -@dfn{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 (@pxref{Pakete definieren}). - -@table @code - -@item --with-source=@var{Quelle} -@itemx --with-source=@var{Paket}=@var{Quelle} -@itemx --with-source=@var{Paket}@@@var{Version}=@var{Quelle} -Den Paketquellcode für das @var{Paket} von der angegebenen @var{Quelle} -holen und die @var{Version} als seine Versionsnummer verwenden. Die -@var{Quelle} muss ein Dateiname oder eine URL sein wie bei @command{guix -download} (@pxref{Aufruf von guix download}). - -Wird kein @var{Paket} angegeben, wird als Paketname derjenige auf der -Befehlszeile angegebene Paketname angenommen, der zur Basis am Ende der -@var{Quelle} passt — wenn z.B. als @var{Quelle} die Datei -@code{/src/guile-2.0.10.tar.gz} angegeben wurde, entspricht das dem -@code{guile}-Paket. - -Ebenso wird, wenn keine @var{Version} angegeben wurde, die Version als -Zeichenkette aus der @var{Quelle} abgeleitet; im vorherigen Beispiel wäre -sie @code{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 @file{ed-1.7.tar.gz} von einem GNU-Spiegelserver herunter und -benutzt es als Quelle für das @code{ed}-Paket: - -@example -guix build ed --with-source=mirror://gnu/ed/ed-1.7.tar.gz -@end example - -Für Entwickler wird es einem durch @code{--with-source} leicht gemacht, -»Release Candidates«, also Vorabversionen, zu testen: - -@example -guix build guile --with-source=../guile-2.0.9.219-e1bb7.tar.xz -@end example - -@dots{} oder ein Checkout eines versionskontrollierten Repositorys in einer -isolierten Umgebung zu erstellen: - -@example -$ git clone git://git.sv.gnu.org/guix.git -$ guix build guix --with-source=guix@@1.0=./guix -@end example - -@item --with-input=@var{Paket}=@var{Ersatz} -Abhängigkeiten vom @var{Paket} durch eine Abhängigkeit vom -@var{Ersatz}-Paket ersetzen. Als @var{Paket} muss ein Paketname angegeben -werden und als @var{Ersatz} eine Paketspezifikation wie @code{guile} oder -@code{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 -@code{guile@@2.0} ab: - -@example -guix build --with-input=guile=guile@@2.0 guix -@end example - -Die Ersetzung ist rekursiv und umfassend. In diesem Beispiel würde nicht nur -@code{guix}, sondern auch seine Abhängigkeit @code{guile-json} (was auch von -@code{guile} abhängt) für @code{guile@@2.0} neu erstellt. - -Implementiert wird das alles mit der Scheme-Prozedur -@code{package-input-rewriting} (@pxref{Pakete definieren, -@code{package-input-rewriting}}). - -@item --with-graft=@var{Paket}=@var{Ersatz} -Dies verhält sich ähnlich wie mit @code{--with-input}, aber mit dem -wichtigen Unterschied, dass nicht die gesamte Abhängigkeitskette neu -erstellt wird, sondern das @var{Ersatz}-Paket erstellt und die -ursprünglichen Binärdateien, die auf das @var{Paket} verwiesen haben, damit -@dfn{veredelt} werden. Im Abschnitt @xref{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: - -@example -guix build --with-graft=gnutls=gnutls@@3.5.4 wget -@end example - -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 @var{Paket} und sein @var{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 @var{Ersatz}-Paket auf irgendeine Art inkompatibel -mit dem @var{Paket} ist, könnte das Ergebnispaket unbrauchbar sein. Vorsicht -ist also geboten! - -@item --with-branch=@var{package}=@var{branch} -@cindex Git, using the latest commit -@cindex latest commit, building -Build @var{package} from the latest commit of @var{branch}. The -@code{source} field of @var{package} must be an origin with the -@code{git-fetch} method (@pxref{»origin«-Referenz}) or a @code{git-checkout} -object; the repository URL is taken from that @code{source}. Git -sub-modules of the repository are fetched, recursively. - -For instance, the following command builds @code{guile-sqlite3} from the -latest commit of its @code{master} branch, and then builds @code{guix} -(which depends on it) and @code{cuirass} (which depends on @code{guix}) -against this specific @code{guile-sqlite3} build: - -@example -guix build --with-branch=guile-sqlite3=master cuirass -@end example - -@cindex continuous integration -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 @file{~/.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. - -@item --with-commit=@var{package}=@var{commit} -This is similar to @code{--with-branch}, except that it builds from -@var{commit} rather than the tip of a branch. @var{commit} must be a valid -Git commit SHA1 identifier. -@end table - -@node Zusätzliche Erstellungsoptionen -@subsection Zusätzliche Erstellungsoptionen - -Die unten aufgeführten Befehlszeilenoptionen funktionieren nur mit -@command{guix build}. - -@table @code - -@item --quiet -@itemx -q -Build quietly, without displaying the build log; this is equivalent to -@code{--verbosity=0}. Upon completion, the build log is kept in @file{/var} -(or similar) and can always be retrieved using the @option{--log-file} -option. - -@item --file=@var{Datei} -@itemx -f @var{Datei} -Das Paket, die Ableitung oder das dateiähnliche Objekt erstellen, zu dem der -Code in der @var{Datei} ausgewertet wird (@pxref{G-Ausdrücke, file-like -objects}). - -Zum Beispiel könnte in der @var{Datei} so eine Paketdefinition stehen -(@pxref{Pakete definieren}): - -@example -@verbatiminclude package-hello.scm -@end example - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Build the package or derivation @var{expr} evaluates to. - -For example, @var{expr} may be @code{(@@ (gnu packages guile) guile-1.8)}, -which unambiguously designates this specific variant of version 1.8 of -Guile. - -Alternatively, @var{expr} may be a G-expression, in which case it is used as -a build program passed to @code{gexp->derivation} (@pxref{G-Ausdrücke}). - -Lastly, @var{expr} may refer to a zero-argument monadic procedure -(@pxref{Die Store-Monade}). The procedure must return a derivation as a -monadic value, which is then passed through @code{run-with-store}. - -@item --source -@itemx -S -Build the source derivations of the packages, rather than the packages -themselves. - -For instance, @code{guix build -S gcc} returns something like -@file{/gnu/store/@dots{}-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 @code{origin} (@pxref{Pakete definieren}). - -@item --sources -Fetch and return the source of @var{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 @var{packages}, allowing you to -eventually build them even without network access. It is an extension of -the @code{--source} option and can accept one of the following optional -argument values: - -@table @code -@item package -This value causes the @code{--sources} option to behave in the same way as -the @code{--source} option. - -@item all -Build the source derivations of all packages, including any source that -might be listed as @code{inputs}. This is the default value. - -@example -$ guix build --sources tzdata -The following derivations will be built: - /gnu/store/@dots{}-tzdata2015b.tar.gz.drv - /gnu/store/@dots{}-tzcode2015b.tar.gz.drv -@end example - -@item 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. - -@example -$ guix build --sources=transitive tzdata -The following derivations will be built: - /gnu/store/@dots{}-tzcode2015b.tar.gz.drv - /gnu/store/@dots{}-findutils-4.4.2.tar.xz.drv - /gnu/store/@dots{}-grep-2.21.tar.xz.drv - /gnu/store/@dots{}-coreutils-8.23.tar.xz.drv - /gnu/store/@dots{}-make-4.1.tar.xz.drv - /gnu/store/@dots{}-bash-4.3.tar.xz.drv -@dots{} -@end example - -@end table - -@item --system=@var{System} -@itemx -s @var{System} -Versuchen, für die angegebene Art von @var{System} geeignete Binärdateien zu -erstellen — z.B. @code{i686-linux} — statt für die Art von System, das die -Erstellung durchführt. - -@quotation Anmerkung -The @code{--system} flag is for @emph{native} compilation and must not be -confused with cross-compilation. See @code{--target} below for information -on cross-compilation. -@end quotation - -An example use of this is on Linux-based systems, which can emulate -different personalities. For instance, passing @code{--system=i686-linux} -on an @code{x86_64-linux} system or @code{--system=armhf-linux} on an -@code{aarch64-linux} system allows you to build packages in a complete -32-bit environment. - -@quotation Anmerkung -Building for an @code{armhf-linux} system is unconditionally enabled on -@code{aarch64-linux} machines, although certain aarch64 chipsets do not -allow for this functionality, notably the ThunderX. -@end quotation - -Similarly, when transparent emulation with QEMU and @code{binfmt_misc} is -enabled (@pxref{Virtualisierungsdienste, @code{qemu-binfmt-service-type}}), -you can build for any system for which a QEMU @code{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. @xref{Auslagern des Daemons einrichten}, for more information on offloading. - -@item --target=@var{Tripel} -@cindex Cross-Kompilieren -Lässt für das angegebene @var{Tripel} cross-erstellen, dieses muss ein -gültiges GNU-Tripel wie z.B. @code{"mips64el-linux-gnu"} sein -(@pxref{Specifying target triplets, GNU configuration triplets,, autoconf, -Autoconf}). - -@anchor{build-check} -@item --check -@cindex determinism, checking -@cindex reproducibility, checking -Rebuild @var{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 (@pxref{Substitute}), or whether the build result of a package -is deterministic. @xref{Aufruf von guix challenge}, for more background -information and tools. - -Wenn dies zusammen mit @option{--keep-failed} benutzt wird, bleiben die sich -unterscheidenden Ausgaben im Store unter dem Namen -@file{/gnu/store/@dots{}-check}. Dadurch können Unterschiede zwischen den -beiden Ergebnissen leicht erkannt werden. - -@item --repair -@cindex repairing store items -@cindex Datenbeschädigung, Behebung -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 @code{root}. - -@item --derivations -@itemx -d -Return the derivation paths, not the output paths, of the given packages. - -@item --root=@var{file} -@itemx -r @var{file} -@cindex GC roots, adding -@cindex garbage collector roots, adding -Make @var{file} a symlink to the result, and register it as a garbage -collector root. - -Consequently, the results of this @command{guix build} invocation are -protected from garbage collection until @var{file} is removed. When that -option is omitted, build results are eligible for garbage collection as soon -as the build completes. @xref{Aufruf von guix gc}, for more on GC roots. - -@item --log-file -@cindex build logs, access -Return the build log file names or URLs for the given -@var{package-or-derivation}, or raise an error if build logs are missing. - -This works regardless of how packages or derivations are specified. For -instance, the following invocations are equivalent: - -@example -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)' -@end example - -If a log is unavailable locally, and unless @code{--no-substitutes} is -passed, the command looks for a corresponding log on one of the substitute -servers (as specified with @code{--substitute-urls}.) - -So for instance, imagine you want to see the build log of GDB on MIPS, but -you are actually on an @code{x86_64} machine: - -@example -$ guix build --log-file gdb -s mips64el-linux -https://@value{SUBSTITUTE-SERVER}/log/@dots{}-gdb-7.10 -@end example - -You can freely access a huge library of build logs! -@end table - -@node Fehlschläge beim Erstellen untersuchen -@subsection Fehlschläge beim Erstellen untersuchen - -@cindex build failures, debugging -When defining a new package (@pxref{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 @option{--keep-failed} or -@option{-K} option of @command{guix build}, which will keep the failed build -tree in @file{/tmp} or whatever directory you specified as @code{TMPDIR} -(@pxref{Aufruf von guix build, @code{--keep-failed}}). - -From there on, you can @command{cd} to the failed build tree and source the -@file{environment-variables} file, which contains all the environment -variable definitions that were in place when the build failed. So let's say -you're debugging a build failure in package @code{foo}; a typical session -would look like this: - -@example -$ guix build foo -K -@dots{} @i{build fails} -$ cd /tmp/guix-build-foo.drv-0 -$ source ./environment-variables -$ cd foo-1.2 -@end example - -Now, you can invoke commands as if you were the daemon (almost) 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, @file{/bin/sh} does not exist, -etc. (@pxref{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: - -@example -$ guix build -K foo -@dots{} -$ cd /tmp/guix-build-foo.drv-0 -$ guix environment --no-grafts -C foo --ad-hoc strace gdb -[env]# source ./environment-variables -[env]# cd foo-1.2 -@end example - -Here, @command{guix environment -C} creates a container and spawns a new -shell in it (@pxref{Aufruf von guix environment}). The @command{--ad-hoc -strace gdb} part adds the @command{strace} and @command{gdb} commands to the -container, which would may find handy while debugging. The -@option{--no-grafts} option makes sure we get the exact same environment, -with ungrafted packages (@pxref{Sicherheitsaktualisierungen}, for more info on grafts). - -To get closer to a container like that used by the build daemon, we can -remove @file{/bin/sh}: - -@example -[env]# rm /bin/sh -@end example - -(Don't worry, this is harmless: this is all happening in the throw-away -container created by @command{guix environment}.) - -The @command{strace} command is probably not in the search path, but we can -run: - -@example -[env]# $GUIX_ENVIRONMENT/bin/strace -f -o log make check -@end example - -In this way, not only you will have reproduced the environment variables the -daemon uses, you will also be running the build process in a container -similar to the one the daemon uses. - - -@node Aufruf von guix edit -@section Invoking @command{guix edit} - -@cindex @command{guix edit} -@cindex package definition, editing -So many packages, so many source files! The @command{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: - -@example -guix edit gcc@@4.9 vim -@end example - -@noindent -launches the program specified in the @code{VISUAL} or in the @code{EDITOR} -environment variable to view the recipe of GCC@tie{}4.9.3 and that of Vim. - -If you are using a Guix Git checkout (@pxref{Erstellung aus dem Git}), or have -created your own packages on @code{GUIX_PACKAGE_PATH} (@pxref{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. - - -@node Aufruf von guix download -@section Invoking @command{guix download} - -@cindex @command{guix download} -@cindex downloading package sources -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 (@pxref{Pakete definieren}). The @command{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 -@command{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 (@pxref{Aufruf von guix gc}). - -The @command{guix download} command supports the same URIs as used in -package definitions. In particular, it supports @code{mirror://} URIs. -@code{https} URIs (HTTP over TLS) are supported @emph{provided} the Guile -bindings for GnuTLS are available in the user's environment; when they are -not available, an error is raised. @xref{Guile Preparations, how to install -the GnuTLS bindings for Guile,, gnutls-guile, GnuTLS-Guile}, for more -information. - -@command{guix download} verifies HTTPS server certificates by loading the -certificates of X.509 authorities from the directory pointed to by the -@code{SSL_CERT_DIR} environment variable (@pxref{X.509-Zertifikate}), -unless @option{--no-check-certificate} is used. - -The following options are available: - -@table @code -@item --format=@var{fmt} -@itemx -f @var{fmt} -Write the hash in the format specified by @var{fmt}. For more information -on the valid values for @var{fmt}, @pxref{Aufruf von guix hash}. - -@item --no-check-certificate -Do not validate the X.509 certificates of HTTPS servers. - -When using this option, you have @emph{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. - -@item --output=@var{file} -@itemx -o @var{file} -Save the downloaded file to @var{file} instead of adding it to the store. -@end table - -@node Aufruf von guix hash -@section Invoking @command{guix hash} - -@cindex @command{guix hash} -The @command{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 (@pxref{Pakete definieren}). - -Die allgemeine Syntax lautet: - -@example -guix hash @var{option} @var{file} -@end example - -When @var{file} is @code{-} (a hyphen), @command{guix hash} computes the -hash of data read from standard input. @command{guix hash} has the -following options: - -@table @code - -@item --format=@var{fmt} -@itemx -f @var{fmt} -Write the hash in the format specified by @var{fmt}. - -Supported formats: @code{nix-base32}, @code{base32}, @code{base16} -(@code{hex} and @code{hexadecimal} can be used as well). - -If the @option{--format} option is not specified, @command{guix hash} will -output the hash in @code{nix-base32}. This representation is used in the -definitions of packages. - -@item --recursive -@itemx -r -Compute the hash on @var{file} recursively. - -@c FIXME: Replace xref above with xref to an ``Archive'' section when -@c it exists. -In this case, the hash is computed on an archive containing @var{file}, -including its children if it is a directory. Some of the metadata of -@var{file} is part of the archive; for instance, when @var{file} is a -regular file, the hash is different depending on whether @var{file} is -executable or not. Metadata such as time stamps has no impact on the hash -(@pxref{Aufruf von guix archive}). - -@item --exclude-vcs -@itemx -x -When combined with @option{--recursive}, exclude version control system -directories (@file{.bzr}, @file{.git}, @file{.hg}, etc.) - -@vindex git-fetch -As an example, here is how you would compute the hash of a Git checkout, -which is useful when using the @code{git-fetch} method (@pxref{»origin«-Referenz}): - -@example -$ git clone http://example.org/foo.git -$ cd foo -$ guix hash -rx . -@end example -@end table - -@node Aufruf von guix import -@section Invoking @command{guix import} - -@cindex importing packages -@cindex package import -@cindex package conversion -@cindex Invoking @command{guix import} -The @command{guix import} command is useful for people who would like to 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 (@pxref{Pakete definieren}). - -Die allgemeine Syntax lautet: - -@example -guix import @var{importer} @var{options}@dots{} -@end example - -@var{importer} specifies the source from which to import package metadata, -and @var{options} specifies a package identifier and other options specific -to @var{importer}. Currently, the available ``importers'' are: - -@table @code -@item 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@tie{}Hello: - -@example -guix import gnu hello -@end example - -Specific command-line options are: - -@table @code -@item --key-download=@var{policy} -As for @code{guix refresh}, specify the policy to handle missing OpenPGP -keys when verifying the package signature. @xref{Aufruf von guix refresh, -@code{--key-download}}. -@end table - -@item pypi -@cindex pypi -Import metadata from the @uref{https://pypi.python.org/, Python Package -Index}. Information is taken from the JSON-formatted description available -at @code{pypi.python.org} and usually includes all the relevant information, -including package dependencies. For maximum efficiency, it is recommended -to install the @command{unzip} utility, so that the importer can unzip -Python wheels and gather data from them. - -The command below imports metadata for the @code{itsdangerous} Python -package: - -@example -guix import pypi itsdangerous -@end example - -@table @code -@item --recursive -@itemx -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. -@end table - -@item gem -@cindex gem -Import metadata from @uref{https://rubygems.org/, RubyGems}. Information is -taken from the JSON-formatted description available at @code{rubygems.org} -and includes most relevant information, including runtime dependencies. -There are some caveats, however. The metadata doesn't distinguish 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 @code{rails} Ruby package: - -@example -guix import gem rails -@end example - -@table @code -@item --recursive -@itemx -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. -@end table - -@item cpan -@cindex CPAN -Import metadata from @uref{https://www.metacpan.org/, MetaCPAN}. -Information is taken from the JSON-formatted metadata provided through -@uref{https://fastapi.metacpan.org/, MetaCPAN's API} and includes most -relevant information, such as module dependencies. License information -should be checked closely. If Perl is available in the store, then the -@code{corelist} utility will be used to filter core modules out of the list -of dependencies. - -The command command below imports metadata for the @code{Acme::Boolean} Perl -module: - -@example -guix import cpan Acme::Boolean -@end example - -@item cran -@cindex CRAN -@cindex Bioconductor -Import metadata from @uref{https://cran.r-project.org/, CRAN}, the central -repository for the @uref{http://r-project.org, GNU@tie{}R statistical and -graphical environment}. - -Information is extracted from the @code{DESCRIPTION} file of the package. - -The command command below imports metadata for the @code{Cairo} R package: - -@example -guix import cran Cairo -@end example - -When @code{--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 @code{--archive=bioconductor} is added, metadata is imported from -@uref{https://www.bioconductor.org/, Bioconductor}, a repository of R -packages for for the analysis and comprehension of high-throughput genomic -data in bioinformatics. - -Information is extracted from the @code{DESCRIPTION} file of a package -published on the web interface of the Bioconductor SVN repository. - -The command below imports metadata for the @code{GenomicRanges} R package: - -@example -guix import cran --archive=bioconductor GenomicRanges -@end example - -@item texlive -@cindex TeX Live -@cindex CTAN -Import metadata from @uref{http://www.ctan.org/, CTAN}, the comprehensive -TeX archive network for TeX packages that are part of the -@uref{https://www.tug.org/texlive/, TeX Live distribution}. - -Information about the package is obtained through the XML API provided 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 @code{fontspec} TeX -package: - -@example -guix import texlive fontspec -@end example - -When @code{--archive=DIRECTORY} is added, the source code is downloaded not -from the @file{latex} sub-directory of the @file{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 @code{ifxetex} package from CTAN -while fetching the sources from the directory @file{texmf/source/generic}: - -@example -guix import texlive --archive=generic ifxetex -@end example - -@item json -@cindex JSON, import -Import package metadata from a local JSON file. Consider the following -example package definition in JSON format: - -@example -@{ - "name": "hello", - "version": "2.10", - "source": "mirror://gnu/hello/hello-2.10.tar.gz", - "build-system": "gnu", - "home-page": "https://www.gnu.org/software/hello/", - "synopsis": "Hello, GNU world: An example GNU package", - "description": "GNU Hello prints a greeting.", - "license": "GPL-3.0+", - "native-inputs": ["gcc@@6"] -@} -@end example - -The field names are the same as for the @code{<package>} record -(@xref{Pakete definieren}). References to other packages are provided as -JSON lists of quoted package specification strings such as @code{guile} or -@code{guile@@2.0}. - -The importer also supports a more explicit source definition using the -common fields for @code{<origin>} records: - -@example -@{ - @dots{} - "source": @{ - "method": "url-fetch", - "uri": "mirror://gnu/hello/hello-2.10.tar.gz", - "sha256": @{ - "base32": "0ssi1wpaf7plaswqqjwigppsg5fyh99vdlb9kzl7c9lng89ndq1i" - @} - @} - @dots{} -@} -@end example - -The command below reads metadata from the JSON file @code{hello.json} and -outputs a package expression: - -@example -guix import json hello.json -@end example - -@item nix -Import metadata from a local copy of the source of the -@uref{http://nixos.org/nixpkgs/, Nixpkgs distribution}@footnote{This relies -on the @command{nix-instantiate} command of @uref{http://nixos.org/nix/, -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: - -@example -export NIX_REMOTE=daemon -@end example - -@noindent -so that @command{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 @code{libreoffice} top-level attribute): - -@example -guix import nix ~/path/to/nixpkgs libreoffice -@end example - -@item hackage -@cindex hackage -Import metadata from the Haskell community's central package archive -@uref{https://hackage.haskell.org/, Hackage}. Information is taken from -Cabal files and includes all the relevant information, including package -dependencies. - -Specific command-line options are: - -@table @code -@item --stdin -@itemx -s -Read a Cabal file from standard input. -@item --no-test-dependencies -@itemx -t -Do not include dependencies required only by the test suites. -@item --cabal-environment=@var{alist} -@itemx -e @var{alist} -@var{alist} is a Scheme alist defining the environment in which the Cabal -conditionals are evaluated. The accepted keys are: @code{os}, @code{arch}, -@code{impl} and a string representing the name of a flag. The value -associated with a flag has to be either the symbol @code{true} or -@code{false}. The value associated with other keys has to conform to the -Cabal file format definition. The default value associated with the keys -@code{os}, @code{arch} and @code{impl} is @samp{linux}, @samp{x86_64} and -@samp{ghc}, respectively. -@item --recursive -@itemx -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. -@end table - -The command below imports metadata for the latest version of the @code{HTTP} -Haskell package without including test dependencies and specifying the value -of the flag @samp{network-uri} as @code{false}: - -@example -guix import hackage -t -e "'((\"network-uri\" . false))" HTTP -@end example - -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: - -@example -guix import hackage mtl@@2.1.3.1 -@end example - -@item stackage -@cindex stackage -The @code{stackage} importer is a wrapper around the @code{hackage} one. It -takes a package name, looks up the package version included in a long-term -support (LTS) @uref{https://www.stackage.org, Stackage} release and uses the -@code{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: - -@table @code -@item --no-test-dependencies -@itemx -t -Do not include dependencies required only by the test suites. -@item --lts-version=@var{version} -@itemx -l @var{Version} -@var{version} is the desired LTS release version. If omitted the latest -release is used. -@item --recursive -@itemx -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. -@end table - -The command below imports metadata for the @code{HTTP} Haskell package -included in the LTS Stackage release version 7.18: - -@example -guix import stackage --lts-version=7.18 HTTP -@end example - -@item elpa -@cindex elpa -Import metadata from an Emacs Lisp Package Archive (ELPA) package repository -(@pxref{Packages,,, emacs, The GNU Emacs Manual}). - -Specific command-line options are: - -@table @code -@item --archive=@var{repo} -@itemx -a @var{repo} -@var{repo} identifies the archive repository from which to retrieve the -information. Currently the supported repositories and their identifiers -are: -@itemize - -@item -@uref{http://elpa.gnu.org/packages, GNU}, selected by the @code{gnu} -identifier. This is the default. - -Packages from @code{elpa.gnu.org} are signed with one of the keys contained -in the GnuPG keyring at @file{share/emacs/25.1/etc/package-keyring.gpg} (or -similar) in the @code{emacs} package (@pxref{Package Installation, ELPA -package signatures,, emacs, The GNU Emacs Manual}). - -@item -@uref{http://stable.melpa.org/packages, MELPA-Stable}, selected by the -@code{melpa-stable} identifier. - -@item -@uref{http://melpa.org/packages, MELPA}, selected by the @code{melpa} -identifier. -@end itemize - -@item --recursive -@itemx -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. -@end table - -@item crate -@cindex crate -Import metadata from the crates.io Rust package repository -@uref{https://crates.io, crates.io}. - -@item opam -@cindex OPAM -@cindex OCaml -Import metadata from the @uref{https://opam.ocaml.org/, OPAM} package -repository used by the OCaml community. -@end table - -The structure of the @command{guix import} code is modular. It would be -useful to have more importers for other package formats, and your help is -welcome here (@pxref{Mitwirken}). - -@node Aufruf von guix refresh -@section Invoking @command{guix refresh} - -@cindex @command{guix refresh} -The primary audience of the @command{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: - -@example -$ 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 -@end example - -Alternately, one can specify packages to consider, in which case a warning -is emitted for packages that lack an updater: - -@example -$ 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 -@end example - -@command{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 @option{--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! - -@table @code - -@item --recursive -Consider the packages specified, and all the packages upon which they -depend. - -@example -$ 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 -@dots{} -@end example - -@end table - -Sometimes the upstream name differs from the package name used in Guix, and -@command{guix refresh} needs a little help. Most updaters honor the -@code{upstream-name} property in package definitions, which can be used to -that effect: - -@example -(define-public network-manager - (package - (name "network-manager") - ;; @dots{} - (properties '((upstream-name . "NetworkManager"))))) -@end example - -When passed @code{--update}, it modifies distribution source files to update -the version numbers and source tarball hashes of those package recipes -(@pxref{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 @command{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, @command{guix refresh} reports an -error. - -The following options are supported: - -@table @code - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Paket benutzen, wozu der @var{Ausdruck} ausgewertet wird. - -This is useful to precisely refer to a package, as in this example: - -@example -guix refresh -l -e '(@@@@ (gnu packages commencement) glibc-final)' -@end example - -This command lists the dependents of the ``final'' libc (essentially all the -packages.) - -@item --update -@itemx -u -Update distribution source files (package recipes) in place. This is -usually run from a checkout of the Guix source tree (@pxref{Guix vor der Installation ausführen}): - -@example -$ ./pre-inst-env guix refresh -s non-core -u -@end example - -@xref{Pakete definieren}, for more information on package definitions. - -@item --select=[@var{subset}] -@itemx -s @var{subset} -Select all the packages in @var{subset}, one of @code{core} or -@code{non-core}. - -The @code{core} subset refers to all the packages at the core of 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 @code{non-core} subset refers to the remaining packages. It is -typically useful in cases where an update of the core packages would be -inconvenient. - -@item --manifest=@var{Datei} -@itemx -m @var{Datei} -Select all the packages from the manifest in @var{file}. This is useful to -check if any packages of the user manifest can be updated. - -@item --type=@var{updater} -@itemx -t @var{updater} -Select only packages handled by @var{updater} (may be a comma-separated list -of updaters). Currently, @var{updater} may be one of: - -@table @code -@item gnu -the updater for GNU packages; -@item gnome -the updater for GNOME packages; -@item kde -the updater for KDE packages; -@item xorg -the updater for X.org packages; -@item kernel.org -the updater for packages hosted on kernel.org; -@item elpa -the updater for @uref{http://elpa.gnu.org/, ELPA} packages; -@item cran -the updater for @uref{https://cran.r-project.org/, CRAN} packages; -@item bioconductor -the updater for @uref{https://www.bioconductor.org/, Bioconductor} R -packages; -@item cpan -the updater for @uref{http://www.cpan.org/, CPAN} packages; -@item pypi -the updater for @uref{https://pypi.python.org, PyPI} packages. -@item gem -the updater for @uref{https://rubygems.org, RubyGems} packages. -@item github -the updater for @uref{https://github.com, GitHub} packages. -@item hackage -the updater for @uref{https://hackage.haskell.org, Hackage} packages. -@item stackage -the updater for @uref{https://www.stackage.org, Stackage} packages. -@item crate -the updater for @uref{https://crates.io, Crates} packages. -@end table - -For instance, the following command only checks for updates of Emacs -packages hosted at @code{elpa.gnu.org} and for updates of CRAN packages: - -@example -$ 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 -@end example - -@end table - -In addition, @command{guix refresh} can be passed one or more package names, -as in this example: - -@example -$ ./pre-inst-env guix refresh -u emacs idutils gcc@@4.8 -@end example - -@noindent -The command above specifically updates the @code{emacs} and @code{idutils} -packages. The @code{--select} option would have no effect in this case. - -When considering whether to upgrade a package, it is sometimes convenient 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 -@command{guix refresh} one or more package names: - -@table @code - -@item --list-updaters -@itemx -L -List available updaters and exit (see @option{--type} above.) - -For each updater, display the fraction of packages it covers; at the end, -display the fraction of packages covered by all these updaters. - -@item --list-dependent -@itemx -l -List top-level dependent packages that would need to be rebuilt as a result -of upgrading one or more packages. - -@xref{Aufruf von guix graph, the @code{reverse-package} type of @command{guix -graph}}, for information on how to visualize the list of dependents of a -package. - -@end table - -Be aware that the @code{--list-dependent} option only @emph{approximates} -the rebuilds that would be required as a result of an upgrade. More -rebuilds might be required under some circumstances. - -@example -$ 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 @dots{} -@end example - -The command above lists a set of packages that could be built to check for -compatibility with an upgraded @code{flex} package. - -@table @code - -@item --list-transitive -List all the packages which one or more packages depend upon. - -@example -$ 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 @dots{} -@end example - -@end table - -The command above lists a set of packages which, when changed, would cause -@code{flex} to be rebuilt. - -The following options can be used to customize GnuPG operation: - -@table @code - -@item --gpg=@var{command} -Use @var{command} as the GnuPG 2.x command. @var{command} is searched for -in @code{$PATH}. - -@item --keyring=@var{Datei} -Use @var{file} as the keyring for upstream keys. @var{file} must be in the -@dfn{keybox format}. Keybox files usually have a name ending in @file{.kbx} -and the GNU@tie{}Privacy Guard (GPG) can manipulate these files -(@pxref{kbxutil, @command{kbxutil},, gnupg, Using the GNU Privacy Guard}, -for information on a tool to manipulate keybox files). - -When this option is omitted, @command{guix refresh} uses -@file{~/.config/guix/upstream/trustedkeys.kbx} as the keyring for upstream -signing keys. OpenPGP signatures are checked against keys from this -keyring; missing keys are downloaded to this keyring as well (see -@option{--key-download} below.) - -You can export keys from your default GPG keyring into a keybox file using -commands like this one: - -@example -gpg --export rms@@gnu.org | kbxutil --import-openpgp >> mykeyring.kbx -@end example - -Likewise, you can fetch keys to a specific keybox file like this: - -@example -gpg --no-default-keyring --keyring mykeyring.kbx \ - --recv-keys @value{OPENPGP-SIGNING-KEY-ID} -@end example - -@ref{GPG Configuration Options, @option{--keyring},, gnupg, Using the GNU -Privacy Guard}, for more information on GPG's @option{--keyring} option. - -@item --key-download=@var{policy} -Handle missing OpenPGP keys according to @var{policy}, which may be one of: - -@table @code -@item always -Always download missing OpenPGP keys from the key server, and add them to -the user's GnuPG keyring. - -@item never -Never try to download missing OpenPGP keys. Instead just bail out. - -@item 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. -@end table - -@item --key-server=@var{host} -Use @var{host} as the OpenPGP key server when importing a public key. - -@end table - -The @code{github} updater uses the @uref{https://developer.github.com/v3/, -GitHub API} to query for new releases. When used repeatedly e.g.@: 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 -@code{GUIX_GITHUB_TOKEN} to a token procured from -@uref{https://github.com/settings/tokens} or otherwise. - - -@node Aufruf von guix lint -@section Invoking @command{guix lint} - -@cindex @command{guix lint} -@cindex package, checking for errors -The @command{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 @dfn{checkers} include (see @code{--list-checkers} -for a complete list): - -@table @code -@item synopsis -@itemx description -Validate certain typographical and stylistic rules about package -descriptions and synopses. - -@item inputs-should-be-native -Identify inputs that should most likely be native inputs. - -@item source -@itemx home-page -@itemx mirror-url -@itemx github-url -@itemx source-file-name -Probe @code{home-page} and @code{source} URLs and report those that are -invalid. Suggest a @code{mirror://} URL when applicable. If the -@code{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 @code{file-name} -(@pxref{»origin«-Referenz}). - -@item source-unstable-tarball -Parse the @code{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. - -@item cve -@cindex security vulnerabilities -@cindex CVE, Common Vulnerabilities and Exposures -Report known vulnerabilities found in the Common Vulnerabilities and -Exposures (CVE) databases of the current and past year -@uref{https://nvd.nist.gov/download.cfm#CVE_FEED, published by the US NIST}. - -To view information about a particular vulnerability, visit pages such as: - -@itemize -@item -@indicateurl{https://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-YYYY-ABCD} -@item -@indicateurl{https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-YYYY-ABCD} -@end itemize - -@noindent -where @code{CVE-YYYY-ABCD} is the CVE identifier---e.g., -@code{CVE-2015-7554}. - -Package developers can specify in package recipes the -@uref{https://nvd.nist.gov/cpe.cfm,Common Platform Enumeration (CPE)} name -and version of the package when they differ from the name or version that -Guix uses, as in this example: - -@example -(package - (name "grub") - ;; @dots{} - ;; CPE calls this package "grub2". - (properties '((cpe-name . "grub2") - (cpe-version . "2.3"))) -@end example - -@c See <http://www.openwall.com/lists/oss-security/2017/03/15/3>. -Some entries in the CVE database do not specify which version of a 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: - -@example -(package - (name "t1lib") - ;; @dots{} - ;; These CVEs no longer apply and can be safely ignored. - (properties `((lint-hidden-cve . ("CVE-2011-0433" - "CVE-2011-1553" - "CVE-2011-1554" - "CVE-2011-5244"))))) -@end example - -@item formatting -Warn about obvious source code formatting issues: trailing white space, use -of tabulations, etc. -@end table - -Die allgemeine Syntax lautet: - -@example -guix lint @var{options} @var{package}@dots{} -@end example - -If no package is given on the command line, then all packages are checked. -The @var{options} may be zero or more of the following: - -@table @code -@item --list-checkers -@itemx -l -List and describe all the available checkers that will be run on packages -and exit. - -@item --checkers -@itemx -c -Only enable the checkers specified in a comma-separated list using the names -returned by @code{--list-checkers}. - -@end table - -@node Aufruf von guix size -@section Invoking @command{guix size} - -@cindex size -@cindex package size -@cindex Abschluss -@cindex @command{guix size} -The @command{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 (@pxref{Pakete mit mehreren Ausgaben.}). Such are the typical issues that @command{guix size} can -highlight. - -The command can be passed one or more package specifications such as -@code{gcc@@4.8} or @code{guile:debug}, or a file name in the store. -Consider this example: - -@example -$ guix size coreutils -store item total self -/gnu/store/@dots{}-gcc-5.5.0-lib 60.4 30.1 38.1% -/gnu/store/@dots{}-glibc-2.27 30.3 28.8 36.6% -/gnu/store/@dots{}-coreutils-8.28 78.9 15.0 19.0% -/gnu/store/@dots{}-gmp-6.1.2 63.1 2.7 3.4% -/gnu/store/@dots{}-bash-static-4.4.12 1.5 1.5 1.9% -/gnu/store/@dots{}-acl-2.2.52 61.1 0.4 0.5% -/gnu/store/@dots{}-attr-2.4.47 60.6 0.2 0.3% -/gnu/store/@dots{}-libcap-2.25 60.5 0.2 0.2% -total: 78.9 MiB -@end example - -@cindex Abschluss -The store items listed here constitute the @dfn{transitive closure} of -Coreutils---i.e., Coreutils and all its dependencies, recursively---as would -be returned by: - -@example -$ guix gc -R /gnu/store/@dots{}-coreutils-8.23 -@end example - -Here the output shows three columns next to store items. The first column, -labeled ``total'', shows the size in mebibytes (MiB) of the closure of 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@tie{}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 @i{per se} because they are always available on the -system anyway.) - -When the package(s) passed to @command{guix size} are available in the -store@footnote{More precisely, @command{guix size} looks for the -@emph{ungrafted} variant of the given package(s), as returned by @code{guix -build @var{package} --no-grafts}. @xref{Sicherheitsaktualisierungen}, for information -on grafts.}, @command{guix size} queries the daemon to determine its -dependencies, and measures its size in the store, similar to @command{du -ms ---apparent-size} (@pxref{du invocation,,, coreutils, GNU Coreutils}). - -When the given packages are @emph{not} in the store, @command{guix size} -reports information based on the available substitutes -(@pxref{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: - -@example -$ guix size coreutils grep sed bash -store item total self -/gnu/store/@dots{}-coreutils-8.24 77.8 13.8 13.4% -/gnu/store/@dots{}-grep-2.22 73.1 0.8 0.8% -/gnu/store/@dots{}-bash-4.3.42 72.3 4.7 4.6% -/gnu/store/@dots{}-readline-6.3 67.6 1.2 1.2% -@dots{} -total: 102.3 MiB -@end example - -@noindent -In this example we see that the combination of the four packages takes -102.3@tie{}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: - -@table @option - -@item --substitute-urls=@var{URLs} -Use substitute information from @var{urls}. @xref{client-substitute-urls, -the same option for @code{guix build}}. - -@item --sort=@var{key} -Sort lines according to @var{key}, one of the following options: - -@table @code -@item self -the size of each item (the default); -@item Abschluss -the total size of the item's closure. -@end table - -@item --map-file=@var{file} -Write a graphical map of disk usage in PNG format to @var{file}. - -For the example above, the map looks like this: - -@image{images/coreutils-size-map,5in,, map of Coreutils disk usage produced -by @command{guix size}} - -This option requires that -@uref{http://wingolog.org/software/guile-charting/, Guile-Charting} be -installed and visible in Guile's module search path. When that is not the -case, @command{guix size} fails as it tries to load it. - -@item --system=@var{System} -@itemx -s @var{System} -Consider packages for @var{system}---e.g., @code{x86_64-linux}. - -@end table - -@node Aufruf von guix graph -@section Invoking @command{guix graph} - -@cindex DAG -@cindex @command{guix graph} -@cindex Paketabhängigkeiten -Packages and their dependencies form a @dfn{graph}, specifically a directed -acyclic graph (DAG). It can quickly become difficult to have a mental model -of the package DAG, so the @command{guix graph} command provides a visual -representation of the DAG. By default, @command{guix graph} emits a DAG -representation in the input format of @uref{http://www.graphviz.org/, -Graphviz}, so its output can be passed directly to the @command{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 -@uref{https://d3js.org/, d3.js} library, or emit Cypher queries to construct -a graph in a graph database supporting the @uref{http://www.opencypher.org/, -openCypher} query language. The general syntax is: - -@example -guix graph @var{options} @var{package}@dots{} -@end example - -For example, the following command generates a PDF file representing the -package DAG for the GNU@tie{}Core Utilities, showing its build-time -dependencies: - -@example -guix graph coreutils | dot -Tpdf > dag.pdf -@end example - -The output looks like this: - -@image{images/coreutils-graph,2in,,Dependency graph of the GNU Coreutils} - -Nice little graph, no? - -But there is more than one graph! The one above is concise: it is the 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. @command{guix graph} supports several types of graphs, -allowing you to choose the level of detail: - -@table @code -@item 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. - -@item reverse-package -This shows the @emph{reverse} DAG of packages. For example: - -@example -guix graph --type=reverse-package ocaml -@end example - -...@: 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 -@command{guix refresh --list-dependent} (@pxref{Aufruf von guix refresh, -@option{--list-dependent}}). - -@item bag-emerged -This is the package DAG, @emph{including} implicit inputs. - -For instance, the following command: - -@example -guix graph --type=bag-emerged coreutils | dot -Tpdf > dag.pdf -@end example - -...@: yields this bigger graph: - -@image{images/coreutils-bag-graph,,5in,Detailed dependency graph of the GNU -Coreutils} - -At the bottom of the graph, we see all the implicit inputs of -@var{gnu-build-system} (@pxref{Erstellungssysteme, @code{gnu-build-system}}). - -Now, note that the dependencies of these implicit inputs---that is, the -@dfn{bootstrap dependencies} (@pxref{Bootstrapping})---are not shown here, -for conciseness. - -@item bag -Similar to @code{bag-emerged}, but this time including all the bootstrap -dependencies. - -@item bag-with-origins -Similar to @code{bag}, but also showing origins and their dependencies. - -@item Ableitung -This is the most detailed representation: It shows the DAG of derivations -(@pxref{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 @file{.drv} file name -instead of a package name, as in: - -@example -guix graph -t derivation `guix system build -d my-config.scm` -@end example - -@item module -This is the graph of @dfn{package modules} (@pxref{Paketmodule}). For -example, the following command shows the graph for the package module that -defines the @code{guile} package: - -@example -guix graph -t module guile | dot -Tpdf > module-graph.pdf -@end example -@end table - -All the types above correspond to @emph{build-time dependencies}. The -following graph type represents the @emph{run-time dependencies}: - -@table @code -@item references -This is the graph of @dfn{references} of a package output, as returned by -@command{guix gc --references} (@pxref{Aufruf von guix gc}). - -If the given package output is not available in the store, @command{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!): - -@example -guix graph -t references `readlink -f ~/.guix-profile` -@end example - -@item referrers -This is the graph of the @dfn{referrers} of a store item, as returned by -@command{guix gc --referrers} (@pxref{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; @command{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. - -@end table - -The available options are the following: - -@table @option -@item --type=@var{type} -@itemx -t @var{type} -Produce a graph output of @var{type}, where @var{type} must be one of the -values listed above. - -@item --list-types -List the supported graph types. - -@item --backend=@var{backend} -@itemx -b @var{backend} -Produce a graph using the selected @var{backend}. - -@item --list-backends -List the supported graph backends. - -Currently, the available backends are Graphviz and d3.js. - -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Als Paket benutzen, wozu der @var{Ausdruck} ausgewertet wird. - -This is useful to precisely refer to a package, as in this example: - -@example -guix graph -e '(@@@@ (gnu packages commencement) gnu-make-final)' -@end example - -@item --system=@var{System} -@itemx -s @var{System} -Display the graph for @var{system}---e.g., @code{i686-linux}. - -The package dependency graph is largely architecture-independent, but there -are some architecture-dependent bits that this option allows you to -visualize. -@end table - - - -@node Aufruf von guix publish -@section @command{guix publish} aufrufen - -@cindex @command{guix publish} -Der Zweck von @command{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 (@pxref{Substitute}). - -When @command{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 -@code{@value{SUBSTITUTE-SERVER}} 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 -@pxref{Substitute}). Weil @command{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 @code{--user} werden Administratorrechte bald nach dem -Start wieder abgelegt. - -Das Schlüsselpaar zum Signieren muss erzeugt werden, bevor @command{guix -publish} gestartet wird. Dazu können Sie @command{guix archive ---generate-key} ausführen (@pxref{Aufruf von guix archive}). - -Die allgemeine Syntax lautet: - -@example -guix publish @var{Optionen}@dots{} -@end example - -Wird @command{guix publish} ohne weitere Argumente ausgeführt, wird damit -ein HTTP-Server gestartet, der auf Port 8080 lauscht: - -@example -guix publish -@end example - -Sobald ein Server zum Veröffentlichen autorisiert wurde (@pxref{Aufruf von guix archive}), kann der Daemon davon Substitute herunterladen: - -@example -guix-daemon --substitute-urls=http://example.org:8080 -@end example - -Nach den Voreinstellungen komprimiert @command{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 @option{--cache} benutzen, die das -Zwischenspeichern der komprimierten Archive aktiviert, bevor diese an die -Clients geschickt werden — siehe unten für Details. Mit dem Befehl -@command{guix weather} haben Sie eine praktische Methode zur Hand, zu -überprüfen, was so ein Server anbietet (@pxref{Aufruf von guix weather}). - -Als Bonus dient @command{guix publish} auch als inhaltsadressierbarer -Spiegelserver für Quelldateien, die in @code{origin}-Verbundsobjekten -eingetragen sind (@pxref{»origin«-Referenz}). Wenn wir zum Beispiel annehmen, -dass @command{guix publish} auf @code{example.org} läuft, liefert folgende -URL die rohe @file{hello-2.10.tar.gz}-Datei mit dem angegebenen SHA256-Hash -als ihre Prüfsumme (dargestellt im @code{nix-base32}-Format, siehe -@pxref{Aufruf von guix hash}): - -@example -http://example.org/file/hello-2.10.tar.gz/sha256/0ssi1@dots{}ndq1i -@end example - -Offensichtlich funktionieren diese URLs nur mit solchen Dateien, die auch im -Store vorliegen; in anderen Fällen werden sie 404 (»Nicht gefunden«) -zurückliefern. - -@cindex Erstellungsprotokolle, Veröffentlichen -Erstellungsprotokolle sind unter @code{/log}-URLs abrufbar: - -@example -http://example.org/log/gwspk@dots{}-guile-2.2.3 -@end example - -@noindent -Ist der @command{guix-daemon} so eingestellt, dass er Erstellungsprotokolle -komprimiert abspeichert, wie es voreingestellt ist (@pxref{Aufruf des guix-daemon}), liefern @code{/log}-URLs das unveränderte komprimierte -Protokoll, mit einer entsprechenden @code{Content-Type}- und/oder -@code{Content-Encoding}-Kopfzeile. Wir empfehlen dabei, dass Sie den -@command{guix-daemon} mit @code{--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: - -@table @code -@item --port=@var{Port} -@itemx -p @var{Port} -Auf HTTP-Anfragen auf diesem @var{Port} lauschen. - -@item --listen=@var{Host} -Auf der Netzwerkschnittstelle für den angegebenen @var{Host}, also der -angegebenen Rechneradresse, lauschen. Vorgegeben ist, Verbindungen mit jeder -Schnittstelle zu akzeptieren. - -@item --user=@var{Benutzer} -@itemx -u @var{Benutzer} -So früh wie möglich alle über die Berechtigungen des @var{Benutzer}s -hinausgehenden Berechtigungen ablegen — d.h. sobald der Server-Socket -geöffnet und der Signierschlüssel gelesen wurde. - -@item --compression[=@var{Stufe}] -@itemx -C [@var{Stufe}] -Daten auf der angegebenen Kompressions-@var{Stufe} komprimieren. Wird als -@var{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 @option{--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 @command{guix publish} läuft, zu reduzieren, kann es eine gute Idee -sein, eine niedrige Kompressionsstufe zu wählen, @command{guix publish} -einen Proxy mit Zwischenspeicher (einen »Caching Proxy«) voranzuschalten, -oder @option{--cache} zu benutzen. @option{--cache} zu benutzen, hat den -Vorteil, dass @command{guix publish} damit eine -@code{Content-Length}-HTTP-Kopfzeile seinen Antworten beifügen kann. - -@item --cache=@var{Verzeichnis} -@itemx -c @var{Verzeichnis} -Archive und Metadaten (@code{.narinfo}-URLs) in das @var{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, @command{guix publish} also keine -@code{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 @option{--cache} benutzt wird, die erste -Anfrage nach einem Store-Objekt (über dessen @code{.narinfo}-URL) den -Fehlercode 404, und im Hintergrund wird ein Prozess gestartet, der das -Archiv in den Zwischenspeicher einlagert (auf Englisch sagen wir »@dfn{bake} -the archive«), d.h. seine @code{.narinfo} wird berechnet und das Archiv, -falls nötig, komprimiert. Sobald das Archiv im @var{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 @option{--workers} weiter unten. - -Wird @option{--ttl} verwendet, werden zwischengespeicherte Einträge -automatisch gelöscht, sobald die dabei angegebene Zeit abgelaufen ist. - -@item --workers=@var{N} -Wird @option{--cache} benutzt, wird die Reservierung von @var{N} -Worker-Threads angefragt, um Archive einzulagern. - -@item --ttl=@var{ttl} -@code{Cache-Control}-HTTP-Kopfzeilen erzeugen, die eine Time-to-live (TTL) -von @var{ttl} signalisieren. Für @var{ttl} muss eine Dauer (mit dem -Anfangsbuchstaben der Maßeinheit der Dauer im Englischen) angegeben werden: -@code{5d} bedeutet 5 Tage, @code{1m} bedeutet 1 Monat und so weiter. - -Das ermöglicht es Guix, Substitutinformationen @var{ttl} lang -zwischenzuspeichern. Beachten Sie allerdings, dass @code{guix publish} -selbst @emph{nicht} garantiert, dass die davon angebotenen Store-Objekte so -lange verfügbar bleiben, wie es die @var{ttl} vorsieht. - -Des Weiteren können bei Nutzung von @option{--cache} die -zwischengespeicherten Einträge gelöscht werden, wenn auf sie @var{ttl} lang -nicht zugegriffen wurde und kein ihnen entsprechendes Objekt mehr im Store -existiert. - -@item --nar-path=@var{Pfad} -Den @var{Pfad} als Präfix für die URLs von »nar«-Dateien benutzen -(@pxref{Aufruf von guix archive, normalized archives}). - -Vorgegeben ist, dass Nars unter einer URL mit -@code{/nar/gzip/@dots{}-coreutils-8.25} angeboten werden. Mit dieser -Befehlszeilenoption können Sie den @code{/nar}-Teil durch den angegebenen -@var{Pfad} ersetzen. - -@item --public-key=@var{Datei} -@itemx --private-key=@var{Datei} -Die angegebenen @var{Datei}en 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 @command{guix archive --generate-key} erzeugt wird (@pxref{Aufruf von guix archive}). Vorgegeben ist, dass @file{/etc/guix/signing-key.pub} und -@file{/etc/guix/signing-key.sec} benutzt werden. - -@item --repl[=@var{Port}] -@itemx -r [@var{Port}] -Einen Guile-REPL-Server (@pxref{REPL Servers,,, guile, GNU Guile Reference -Manual}) auf diesem @var{Port} starten (37146 ist voreingestellt). Dies kann -zur Fehlersuche auf einem laufenden »@command{guix publish}«-Server benutzt -werden. -@end table - -Enabling @command{guix publish} on Guix System is a one-liner: just -instantiate a @code{guix-publish-service-type} service in the -@code{services} field of the @code{operating-system} declaration -(@pxref{guix-publish-service-type, @code{guix-publish-service-type}}). - -Falls Sie Guix aber auf einer »Fremddistribution« laufen lassen, folgen Sie -folgenden Anweisungen: - -@itemize -@item -Wenn Ihre Wirtsdistribution systemd als »init«-System benutzt: - -@example -# ln -s ~root/.guix-profile/lib/systemd/system/guix-publish.service \ - /etc/systemd/system/ -# systemctl start guix-publish && systemctl enable guix-publish -@end example - -@item -Wenn Ihre Wirts-Distribution als »init«-System Upstart verwendet: - -@example -# ln -s ~root/.guix-profile/lib/upstart/system/guix-publish.conf /etc/init/ -# start guix-publish -@end example - -@item -Verfahren Sie andernfalls auf die gleiche Art für das »init«-System, das -Ihre Distribution verwendet. -@end itemize - -@node Aufruf von guix challenge -@section Invoking @command{guix challenge} - -@cindex Reproduzierbare Erstellungen -@cindex verifiable builds -@cindex @command{guix challenge} -@cindex 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 @command{guix challenge} command attempts to answer. - -The former is obviously an important question: Before using a substitute -server (@pxref{Substitute}), one had better @emph{verify} that it provides -the right binaries, and thus @emph{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 @file{/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. (@pxref{Einführung}). Assuming deterministic build processes, one -store file name should map to exactly one build output. @command{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: - -@smallexample -$ guix challenge --substitute-urls="https://@value{SUBSTITUTE-SERVER} https://guix.example.org" -updating list of substitutes from 'https://@value{SUBSTITUTE-SERVER}'... 100.0% -updating list of substitutes from 'https://guix.example.org'... 100.0% -/gnu/store/@dots{}-openssl-1.0.2d contents differ: - local hash: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-openssl-1.0.2d: 0725l22r5jnzazaacncwsvp9kgf42266ayyp814v7djxs7nk963q - https://guix.example.org/nar/@dots{}-openssl-1.0.2d: 1zy4fmaaqcnjrzzajkdn3f5gmjk754b43qkq47llbyak9z0qjyim -/gnu/store/@dots{}-git-2.5.0 contents differ: - local hash: 00p3bmryhjxrhpn2gxs2fy0a15lnip05l97205pgbk5ra395hyha - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0: 069nb85bv4d4a6slrwjdy8v1cn4cwspm3kdbmyb81d6zckj3nq9f - https://guix.example.org/nar/@dots{}-git-2.5.0: 0mdqa9w1p6cmli6976v4wi0sw9r4p5prkj7lzfd1877wk11c9c73 -/gnu/store/@dots{}-pius-2.1.1 contents differ: - local hash: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-pius-2.1.1: 0k4v3m9z1zp8xzzizb7d8kjj72f9172xv078sq4wl73vnq9ig3ax - https://guix.example.org/nar/@dots{}-pius-2.1.1: 1cy25x1a4fzq5rk0pmvc8xhwyffnqz95h2bpvqsz2mpvlbccy0gs - -@dots{} - -6,406 store items were analyzed: - - 4,749 (74.1%) were identical - - 525 (8.2%) differed - - 1,132 (17.7%) were inconclusive -@end smallexample - -@noindent -In this example, @command{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. - -@cindex non-determinism, in package builds -As an example, @code{guix.example.org} always gets a different answer. -Conversely, @code{@value{SUBSTITUTE-SERVER}} agrees with local builds, -except in the case of Git. This might indicate that the build process 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 (@pxref{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 @uref{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 (@pxref{Aufruf von guix archive}): - -@example -$ wget -q -O - https://@value{SUBSTITUTE-SERVER}/nar/@dots{}-git-2.5.0 \ - | guix archive -x /tmp/git -$ diff -ur --no-dereference /gnu/store/@dots{}-git.2.5.0 /tmp/git -@end example - -This command shows the difference between the files resulting from the local -build, and the files resulting from the build on -@code{@value{SUBSTITUTE-SERVER}} (@pxref{Overview, Comparing and Merging -Files,, diffutils, Comparing and Merging Files}). The @command{diff} -command works great for text files. When binary files differ, a better -option is @uref{https://diffoscope.org/, Diffoscope}, 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, -@command{guix challenge} is one tool to help address the problem. - -If you are writing packages for Guix, you are encouraged to check whether -@code{@value{SUBSTITUTE-SERVER}} and other substitute servers obtain the -same build result as you did with: - -@example -$ guix challenge @var{package} -@end example - -@noindent -where @var{package} is a package specification such as @code{guile@@2.0} or -@code{glibc:debug}. - -Die allgemeine Syntax lautet: - -@example -guix challenge @var{options} [@var{packages}@dots{}] -@end example - -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: - -@table @code - -@item --substitute-urls=@var{URLs} -Consider @var{urls} the whitespace-separated list of substitute source URLs -to compare to. - -@item --verbose -@itemx -v -Show details about matches (identical contents) in addition to information -about mismatches. - -@end table - -@node Aufruf von guix copy -@section Invoking @command{guix copy} - -@cindex copy, of store items, over SSH -@cindex SSH, copy of store items -@cindex sharing store items across machines -@cindex transferring store items across machines -The @command{guix copy} command copies items from the store of one machine -to that of another machine over a secure shell (SSH) -connection@footnote{This command is available only when Guile-SSH was -found. @xref{Voraussetzungen}, for details.}. For example, the following -command copies the @code{coreutils} package, the user's profile, and all -their dependencies over to @var{host}, logged in as @var{user}: - -@example -guix copy --to=@var{user}@@@var{host} \ - coreutils `readlink -f ~/.guix-profile` -@end example - -If some of the items to be copied are already present on @var{host}, they -are not actually sent. - -The command below retrieves @code{libreoffice} and @code{gimp} from -@var{host}, assuming they are available there: - -@example -guix copy --from=@var{host} libreoffice gimp -@end example - -The SSH connection is established using the Guile-SSH client, which is -compatible with OpenSSH: it honors @file{~/.ssh/known_hosts} and -@file{~/.ssh/config}, and uses the SSH agent for authentication. - -The key used to sign items that are sent must be accepted by the remote -machine. Likewise, the key used by the remote machine to sign items you are -retrieving must be in @file{/etc/guix/acl} so it is accepted by your own -daemon. @xref{Aufruf von guix archive}, for more information about store item -authentication. - -Die allgemeine Syntax lautet: - -@example -guix copy [--to=@var{spec}|--from=@var{spec}] @var{items}@dots{} -@end example - -You must always specify one of the following options: - -@table @code -@item --to=@var{spec} -@itemx --from=@var{spec} -Specify the host to send to or receive from. @var{spec} must be an SSH spec -such as @code{example.org}, @code{charlie@@example.org}, or -@code{charlie@@example.org:2222}. -@end table - -The @var{items} can be either package names, such as @code{gimp}, or store -items, such as @file{/gnu/store/@dots{}-idutils-4.6}. - -When specifying the name of a package to send, it is first built if needed, -unless @option{--dry-run} was specified. Common build options are supported -(@pxref{Gemeinsame Erstellungsoptionen}). - - -@node Aufruf von guix container -@section Invoking @command{guix container} -@cindex container -@cindex @command{guix container} -@quotation Anmerkung -As of version @value{VERSION}, this tool is experimental. The interface is -subject to radical change in the future. -@end quotation - -The purpose of @command{guix container} is to manipulate processes running -within an isolated environment, commonly known as a ``container'', typically -created by the @command{guix environment} (@pxref{Aufruf von guix environment}) and @command{guix system container} (@pxref{Aufruf von guix system}) commands. - -Die allgemeine Syntax lautet: - -@example -guix container @var{action} @var{options}@dots{} -@end example - -@var{action} specifies the operation to perform with a container, and -@var{options} specifies the context-specific arguments for the action. - -The following actions are available: - -@table @code -@item exec -Execute a command within the context of a running container. - -The syntax is: - -@example -guix container exec @var{pid} @var{program} @var{arguments}@dots{} -@end example - -@var{pid} specifies the process ID of the running container. @var{program} -specifies an executable file name within the root file system of the -container. @var{arguments} are the additional options that will be passed -to @var{program}. - -The following command launches an interactive login shell inside a Guix -system container, started by @command{guix system container}, and whose -process ID is 9001: - -@example -guix container exec 9001 /run/current-system/profile/bin/bash --login -@end example - -Note that the @var{pid} cannot be the parent process of a container. It -must be PID 1 of the container or one of its child processes. - -@end table - -@node Aufruf von guix weather -@section Invoking @command{guix weather} - -Occasionally you're grumpy because substitutes are lacking and you end up -building packages by yourself (@pxref{Substitute}). The @command{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 -@command{guix publish} (@pxref{Aufruf von guix publish}). - -@cindex statistics, for substitutes -@cindex availability of substitutes -@cindex substitute availability -@cindex weather, substitute availability -Here's a sample run: - -@example -$ 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 -@end example - -@cindex continuous integration, statistics -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 @option{--coverage} option, -@command{guix weather} can list ``important'' package substitutes missing on -the server (see below). - -To achieve that, @command{guix weather} queries over HTTP(S) meta-data -(@dfn{narinfos}) for all the relevant store items. Like @command{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. - -@table @code -@item --substitute-urls=@var{URLs} -@var{urls} is the space-separated list of substitute server URLs to query. -When this option is omitted, the default set of substitute servers is -queried. - -@item --system=@var{System} -@itemx -s @var{System} -Query substitutes for @var{system}---e.g., @code{aarch64-linux}. This -option can be repeated, in which case @command{guix weather} will query -substitutes for several system types. - -@item --manifest=@var{Datei} -Instead of querying substitutes for all the packages, only ask for those -specified in @var{file}. @var{file} must contain a @dfn{manifest}, as with -the @code{-m} option of @command{guix package} (@pxref{Aufruf von guix package}). - -@item --coverage[=@var{count}] -@itemx -c [@var{count}] -Report on substitute coverage for packages: list packages with at least -@var{count} dependents (zero by default) for which substitutes are -unavailable. Dependent packages themselves are not listed: if @var{b} -depends on @var{a} and @var{a} has no substitutes, only @var{a} is listed, -even though @var{b} usually lacks substitutes as well. The result looks -like this: - -@example -$ 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) -@dots{} -2502 packages are missing from 'https://ci.guix.de.info' for 'x86_64-linux', among which: - 58 kcoreaddons@@5.49.0 /gnu/store/@dots{}-kcoreaddons-5.49.0 - 46 qgpgme@@1.11.1 /gnu/store/@dots{}-qgpgme-1.11.1 - 37 perl-http-cookiejar@@0.008 /gnu/store/@dots{}-perl-http-cookiejar-0.008 - @dots{} -@end example - -What this example shows is that @code{kcoreaddons} and presumably the 58 -packages that depend on it have no substitutes at @code{ci.guix.de.info}; -likewise for @code{qgpgme} and the 46 packages that depend on it. - -If you are a Guix developer, or if you are taking care of this build farm, -you'll probably want to have a closer look at these packages: they may -simply fail to build. -@end table - -@node Aufruf von guix processes -@section @command{guix processes} aufrufen - -The @command{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@footnote{Remote sessions, when -@command{guix-daemon} is started with @option{--listen} specifying a TCP -endpoint, are @emph{not} listed.}. Here's an example of the information it -returns: - -@example -$ 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 @dots{} - -SessionPID: 19444 -ClientPID: 19419 -ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} -LockHeld: /gnu/store/@dots{}-perl-ipc-cmd-0.96.lock -LockHeld: /gnu/store/@dots{}-python-six-bootstrap-1.11.0.lock -LockHeld: /gnu/store/@dots{}-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 -@end example - -In this example we see that @command{guix-daemon} has three clients: -@command{guix environment}, @command{guix publish}, and the Cuirass -continuous integration tool; their process identifier (PID) is given by the -@code{ClientPID} field. The @code{SessionPID} field gives the PID of the -@command{guix-daemon} sub-process of this particular session. - -The @code{LockHeld} fields show which store items are currently locked by -this session, which corresponds to store items being built or substituted -(the @code{LockHeld} field is not displayed when @command{guix processes} is -not running as root.) Last, by looking at the @code{ChildProcess} field, we -understand that these three builds are being offloaded (@pxref{Auslagern des Daemons einrichten}). - -The output is in Recutils format so we can use the handy @command{recsel} -command to select sessions of interest (@pxref{Selection Expressions,,, -recutils, GNU recutils manual}). As an example, the command shows the -command line and PID of the client that triggered the build of a Perl -package: - -@example -$ sudo guix processes | \ - recsel -p ClientPID,ClientCommand -e 'LockHeld ~ "perl"' -ClientPID: 19419 -ClientCommand: cuirass --cache-directory /var/cache/cuirass @dots{} -@end example - - -@node Systemkonfiguration -@chapter Systemkonfiguration - -@cindex 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 -@dfn{Systemkonfiguration} kann @dfn{instanziiert}, also umgesetzt, werden. - -@c Yes, we're talking of Puppet, Chef, & co. here. ↑ -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 (@pxref{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. - -@menu -* Das Konfigurationssystem nutzen:: Ihr GNU-System anpassen. -* »operating-system«-Referenz:: Details der Betriebssystem-Deklarationen. -* Dateisysteme:: Die Dateisystemeinbindungen konfigurieren. -* Zugeordnete Geräte:: Näheres zu blockorientierten Speichermedien. -* Benutzerkonten:: Benutzerkonten festlegen. -* Locales:: Sprache und kulturelle Konventionen. -* Dienste:: Systemdienste festlegen. -* Setuid-Programme:: Mit Administratorrechten startende Programme. -* X.509-Zertifikate:: HTTPS-Server authentifizieren. -* Name Service Switch:: Den Name Service Switch von libc konfigurieren. -* Initiale RAM-Disk:: Linux-libre hochfahren. -* Bootloader-Konfiguration:: Den Bootloader konfigurieren. -* Aufruf von guix system:: Instanziierung einer Systemkonfiguration. -* Running Guix in a VM:: How to run Guix System in a virtual machine. -* Dienste definieren:: Neue Dienstdefinitionen hinzufügen. -@end menu - -@node Das Konfigurationssystem nutzen -@section Das Konfigurationssystem nutzen - -Das Betriebssystem können Sie konfigurieren, indem Sie eine -@code{operating-system}-Deklaration in einer Datei speichern, die Sie dann -dem Befehl @command{guix system} übergeben (@pxref{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: - -@findex operating-system -@lisp -@include os-config-bare-bones.texi -@end lisp - -Dieses Beispiel sollte selbsterklärend sein. Manche der Felder oben, wie -etwa @code{host-name} und @code{bootloader}, müssen angegeben werden. Andere -sind optional, wie etwa @code{packages} und @code{services}, sind optional; -werden sie nicht angegeben, nehmen sie einen Vorgabewert an. - -Im Folgenden werden die Effekte von einigen der wichtigsten Feldern -erläutert (@pxref{»operating-system«-Referenz}, für Details zu allen -verfügbaren Feldern), dann wird beschrieben, wie man das Betriebssystem mit -@command{guix system} @dfn{instanziieren} kann. - -@unnumberedsubsec Bootloader - -@cindex Legacy-Boot, auf Intel-Maschinen -@cindex BIOS-Boot, auf Intel-Maschinen -@cindex UEFI-Boot -@cindex EFI-Boot -Das @code{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 -@dfn{Unified Extensible Firmware Interface} (UEFI) zum Booten. In diesem -Fall sollte das @code{bootloader}-Feld in etwa so aussehen: - -@example -(bootloader-configuration - (bootloader grub-efi-bootloader) - (target "/boot/efi")) -@end example - -Siehe den Abschnitt @xref{Bootloader-Konfiguration} für weitere -Informationen zu den verfügbaren Konfigurationsoptionen. - -@unnumberedsubsec global sichtbare Pakete - -@vindex %base-packages -Im Feld @code{packages} werden Pakete aufgeführt, die auf dem System für -alle Benutzerkonten global sichtbar sein sollen, d.h. in der -@code{PATH}-Umgebungsvariablen jedes Nutzers, zusätzlich zu den -nutzereigenen Profilen (@pxref{Aufruf von guix package}). Die Variable -@var{%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, @command{find}, @command{grep} und so weiter. Obiges Beispiel fügt -zu diesen noch das Programm GNU@tie{}Screen hinzu, welches aus dem Modul -@code{(gnu packages screen)} genommen wird (@pxref{Paketmodule}). Die -Syntax @code{(list package output)} kann benutzt werden, um eine bestimmte -Ausgabe eines Pakets auszuwählen: - -@lisp -(use-modules (gnu packages)) -(use-modules (gnu packages dns)) - -(operating-system - ;; ... - (packages (cons (list bind "utils") - %base-packages))) -@end lisp - -@findex specification->package -Sich auf Pakete anhand ihres Variablennamens zu beziehen, wie oben bei -@code{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 -@code{use-package-modules} entsprechend zu ergänzen. Um dies zu vermeiden, -kann man auch die Prozedur @code{specification->package} aus dem Modul -@code{(gnu packages)} aufrufen, welche das einem angegebenen Namen oder -Name-Versions-Paar zu Grunde liegende Paket liefert: - -@lisp -(use-modules (gnu packages)) - -(operating-system - ;; ... - (packages (append (map specification->package - '("tcpdump" "htop" "gnupg@@2.0")) - %base-packages))) -@end lisp - -@unnumberedsubsec Systemdienste - -@cindex services -@vindex %base-services -The @code{services} field lists @dfn{system services} to be made available -when the system starts (@pxref{Dienste}). The @code{operating-system} -declaration above specifies that, in addition to the basic services, we want -the OpenSSH secure shell daemon listening on port 2222 (@pxref{Netzwerkdienste, @code{openssh-service-type}}). Under the hood, -@code{openssh-service-type} arranges so that @command{sshd} is started with -the right command-line options, possibly with supporting configuration files -generated as needed (@pxref{Dienste definieren}). - -@cindex Anpassung, von Diensten -@findex modify-services -Gelegentlich werden Sie die Basis-Dienste nicht einfach so, wie sie sind, -benutzen, sondern anpassen wollen. Benutzen Sie @code{modify-services} -(@pxref{Service-Referenz, @code{modify-services}}), um die Liste der -Basis-Dienste zu modifizieren. - -Wenn Sie zum Beispiel @code{guix-daemon} und Mingetty (das Programm, womit -Sie sich auf der Konsole anmelden) in der @var{%base-services}-Liste -modifizieren möchten (@pxref{Basisdienste, @code{%base-services}}), -schreiben Sie das Folgende in Ihre Betriebssystemdeklaration: - -@lisp -(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 - ;; @dots{} - (services %my-services)) -@end lisp - -Dadurch ändert sich die Konfiguration — d.h. die Dienst-Parameter — der -@code{guix-service-type}-Instanz und die aller -@code{mingetty-service-type}-Instanzen in der -@var{%base-services}-Liste. Das funktioniert so: Zunächst arrangieren wir, -dass die ursprüngliche Konfiguration an den Bezeichner @code{config} im -@var{Rumpf} gebunden wird, dann schreiben wir den @var{Rumpf}, damit er zur -gewünschten Konfiguration ausgewertet wird. Beachten Sie insbesondere, wie -wir mit @code{inherit} eine neue Konfiguration erzeugen, die dieselben Werte -wie die alte Konfiguration hat, aber mit ein paar Modifikationen. - -@cindex verschlüsselte Partition -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 -@kbd{F1} drücken), Netzwerkverwaltung, Verwaltungswerkzeugen für den -Energieverbrauch, und Weiteres, würde so aussehen: - -@lisp -@include os-config-desktop.texi -@end lisp - -Ein grafisches System mit einer Auswahl an leichtgewichtigen -Fenster-Managern statt voll ausgestatteten Arbeitsumgebungen würde so -aussehen: - -@lisp -@include os-config-lightweight-desktop.texi -@end lisp - -Dieses Beispiel bezieht sich auf das Dateisystem hinter @file{/boot/efi} -über dessen UUID, @code{1234-ABCD}. Schreiben Sie statt dieser UUID die -richtige UUID für Ihr System, wie sie der Befehl @command{blkid} liefert. - -Im Abschnitt @xref{Desktop-Dienste} finden Sie eine genaue Liste der unter -@var{%desktop-services} angebotenen Dienste. Der Abschnitt @xref{X.509-Zertifikate} hat Hintergrundinformationen über das @code{nss-certs}-Paket, -das hier benutzt wird. - -Beachten Sie, dass @var{%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 -(@pxref{SRFI-1 Filtering and Partitioning,,, guile, GNU Guile Reference -Manual}). Beispielsweise liefert der folgende Ausdruck eine Liste mit allen -Diensten von @var{%desktop-services} außer dem Avahi-Dienst. - -@example -(remove (lambda (service) - (eq? (service-kind service) avahi-service-type)) - %desktop-services) -@end example - -@unnumberedsubsec Das System instanziieren - -Angenommen, Sie haben die @code{operating-system}-Deklaration in einer Datei -@file{my-system-config.scm} gespeichert, dann instanziiert der Befehl -@command{guix system reconfigure my-system-config.scm} diese Konfiguration -und macht sie zum voreingestellten GRUB-Boot-Eintrag (@pxref{Aufruf von guix system}). - -Der normale Weg, die Systemkonfiguration nachträglich zu ändern, ist, die -Datei zu aktualisieren und @command{guix system reconfigure} erneut -auszuführen. Man sollte nie die Dateien in @file{/etc} bearbeiten oder den -Systemzustand mit Befehlen wie @command{useradd} oder @command{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. - -@cindex Zurücksetzen, des Betriebssystems -Zurücksetzen bezieht sich hierbei darauf, dass jedes Mal, wenn Sie -@command{guix system reconfigure} ausführen, eine neue @dfn{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 @command{guix system list-generations} führt -die auf der Platte verfügbaren Systemgenerationen auf. Es ist auch möglich, -das System mit den Befehlen @command{guix system roll-back} und -@command{guix system switch-generation} zurückzusetzen. - -Obwohl der Befehl @command{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 @command{guix -system roll-back}), weil @command{guix system reconfigure} alle neueren -Generationen überschreibt (@pxref{Aufruf von guix system}). - -@unnumberedsubsec Die Programmierschnittstelle - -Auf der Ebene von Scheme wird der Großteil der -@code{operating-system}-Deklaration mit der folgenden monadischen Prozedur -instanziiert (@pxref{Die Store-Monade}): - -@deffn {Monadische Prozedur} operating-system-derivation os -Liefert eine Ableitung, mit der ein @code{operating-system}-Objekt @var{os} -erstellt wird (@pxref{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 @var{os} zu instanziieren. -@end deffn - -This procedure is provided by the @code{(gnu system)} module. Along with -@code{(gnu services)} (@pxref{Dienste}), this module contains the guts of -Guix System. Make sure to visit it! - - -@node »operating-system«-Referenz -@section @code{operating-system}-Referenz - -Dieser Abschnitt fasst alle Optionen zusammen, die für -@code{operating-system}-Deklarationen zur Verfügung stehen (@pxref{Das Konfigurationssystem nutzen}). - -@deftp {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 (@pxref{Das Konfigurationssystem nutzen}). - -@table @asis -@item @code{kernel} (Vorgabe: @var{linux-libre}) -Das Paket für den zu nutzenden Betriebssystem-Kernel als -»package«-Objekt@footnote{Derzeit wird nur der Kernel Linux-libre -unterstützt. In der Zukunft wird man auch GNU@tie{}Hurd benutzen können.}. - -@item @code{kernel-arguments} (Vorgabe: @code{'()}) -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. @code{("console=ttyS0")}. - -@item @code{bootloader} -Das Konfigurationsobjekt für den Bootloader, mit dem das System gestartet -wird. Siehe @xref{Bootloader-Konfiguration}. - -@item @code{initrd-modules} (Vorgabe: @code{%base-initrd-modules}) -@cindex initrd -@cindex initiale RAM-Disk -Die Liste der Linux-Kernel-Module, die in der initialen RAM-Disk zur -Verfügung stehen sollen @xref{Initiale RAM-Disk}. - -@item @code{initrd} (Vorgabe: @code{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 @xref{Initiale RAM-Disk}. - -@item @code{firmware} (Vorgabe: @var{%base-firmware}) -@cindex 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 -@code{ath9k} und @code{b43-open}). Siehe den Abschnitt @xref{Hardware-Überlegungen}, für mehr Informationen zu unterstützter Hardware. - -@item @code{host-name} -Der Hostname - -@item @code{hosts-file} -@cindex hosts-Datei -Ein dateiartiges Objekt (@pxref{G-Ausdrücke, file-like objects}), das für -@file{/etc/hosts} benutzt werden soll (@pxref{Host Names,,, libc, The GNU C -Library Reference Manual}). Der Vorgabewert ist eine Datei mit Einträgen für -@code{localhost} und @var{host-name}. - -@item @code{mapped-devices} (Vorgabe: @code{'()}) -Eine Liste zugeordneter Geräte (»mapped devices«). Siehe @xref{Zugeordnete Geräte}. - -@item @code{file-systems} -Eine Liste von Dateisystemen. Siehe @xref{Dateisysteme}. - -@item @code{swap-devices} (Vorgabe: @code{'()}) -@cindex Swap-Geräte -Eine Liste von Zeichenketten, die Geräte identifizieren oder als -»Swap-Speicher« genutzte Dateien identifizieren (@pxref{Memory Concepts,,, -libc, The GNU C Library Reference Manual}). Beispiele wären etwa -@code{'("/dev/sda3")} oder @code{'("/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 -@xref{Zugeordnete Geräte} und @ref{Dateisysteme}. - -@item @code{users} (Vorgabe: @code{%base-user-accounts}) -@itemx @code{groups} (Vorgabe: @var{%base-groups}) -Liste der Benutzerkonten und Benutzergruppen. Siehe @xref{Benutzerkonten}. - -Wenn in der @code{users}-Liste kein Benutzerkonto mit der UID-Kennung@tie{}0 -aufgeführt wird, wird automatisch für den Administrator ein -»root«-Benutzerkonto mit UID-Kennung@tie{}0 hinzugefügt. - -@item @code{skeletons} (Vorgabe: @code{(default-skeletons)}) -Eine Liste von Tupeln aus je einem Ziel-Dateinamen und einem dateiähnlichen -Objekt (@pxref{G-Ausdrücke, 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: - -@example -`((".bashrc" ,(plain-file "bashrc" "echo Hallo\n")) - (".guile" ,(plain-file "guile" - "(use-modules (ice-9 readline)) - (activate-readline)"))) -@end example - -@item @code{issue} (Vorgabe: @var{%default-issue}) -Eine Zeichenkette, die als Inhalt der Datei @file{/etc/issue} verwendet -werden soll, der jedes Mal angezeigt wird, wenn sich ein Nutzer auf einer -Textkonsole anmeldet. - -@item @code{packages} (Vorgabe: @var{%base-packages}) -Die Menge der Pakete, die ins globale Profil installiert werden sollen, -welches unter @file{/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 -(@pxref{Aufruf von guix package}). - -@item @code{timezone} -Eine Zeichenkette, die die Zeitzone bezeichnet, wie -z.B. @code{"Europe/Berlin"}. - -Mit dem Befehl @command{tzselect} können Sie herausfinden, welche -Zeichenkette der Zeitzone Ihrer Region entspricht. Wenn Sie eine ungültige -Zeichenkette angeben, schlägt @command{guix system} fehl. - -@item @code{locale} (Vorgabe: @code{"en_US.utf8"}) -Der Name der als Voreinstellung zu verwendenden Locale (@pxref{Locale -Names,,, libc, The GNU C Library Reference Manual}). Siehe @xref{Locales} -für weitere Informationen. - -@item @code{locale-definitions} (Vorgabe: @var{%default-locale-definitions}) -Die Liste der Locale-Definitionen, die kompiliert werden sollen und dann im -laufenden System benutzt werden können. Siehe @xref{Locales}. - -@item @code{locale-libcs} (Vorgabe: @code{(list @var{glibc})}) -Die Liste der GNU-libc-Pakete, deren Locale-Daten und -Werkzeuge zum -Erzeugen der Locale-Definitionen verwendet werden sollen. Siehe -@xref{Locales} für eine Erläuterung der Kompatibilitätsauswirkungen, -deretwegen man diese Option benutzen wollen könnte. - -@item @code{name-service-switch} (Vorgabe: @var{%default-nss}) -Die Konfiguration des Name Service Switch (NSS) der libc — ein -@code{<name-service-switch>}-Objekt. Siehe @xref{Name Service Switch}, für -Details. - -@item @code{services} (Vorgabe: @var{%base-services}) -Eine Liste von »service«-Objekten, die die Systemdienste -repräsentieren. Siehe @xref{Dienste}. - -@item @code{pam-services} (Vorgabe: @code{(base-pam-services)}) -@cindex PAM -@cindex Pluggable Authentication Modules -@c FIXME: Add xref to PAM services section. -Dienste für »@dfn{Pluggable Authentication Modules}« (PAM) von Linux. - -@item @code{setuid-programs} (Vorgabe: @var{%setuid-programs}) -Eine Liste von Zeichenketten liefernden G-Ausdrücken, die setuid-Programme -bezeichnen. Siehe @xref{Setuid-Programme}. - -@item @code{sudoers-file} (Vorgabe: @var{%sudoers-specification}) -@cindex sudoers-Datei -Der Inhalt der Datei @file{/etc/sudoers} als ein dateiähnliches Objekt -(@pxref{G-Ausdrücke, @code{local-file} und @code{plain-file}}). - -Diese Datei gibt an, welche Nutzer den Befehl @command{sudo} benutzen -dürfen, was sie damit tun und welche Berechtigungen sie so erhalten -können. Die Vorgabe ist, dass nur der Administratornutzer @code{root} und -Mitglieder der Benutzergruppe @code{wheel} den @code{sudo}-Befehl verwenden -dürfen. - -@end table -@end deftp - -@node Dateisysteme -@section Dateisysteme - -Die Liste der Dateisysteme, die eingebunden werden sollen, steht im -@code{file-systems}-Feld der Betriebssystemdeklaration (@pxref{Das Konfigurationssystem nutzen}). Jedes Dateisystem wird mit der -@code{file-system}-Form deklariert, etwa so: - -@example -(file-system - (mount-point "/home") - (device "/dev/sda3") - (type "ext4")) -@end example - -Wie immer müssen manche Felder angegeben werden — die, die im Beispiel oben -stehen —, während andere optional sind. Die Felder werden nun beschrieben. - -@deftp {Datentyp} file-system -Objekte dieses Typs repräsentieren einzubindende Dateisysteme. Sie weisen -folgende Komponenten auf: - -@table @asis -@item @code{type} -Eine Zeichenkette, die den Typ des Dateisystems spezifiziert, -z.B. @code{"ext4"}. - -@item @code{mount-point} -Der Einhängepunkt, d.h. der Pfad, an dem das Dateisystem eingebunden werden -soll. - -@item @code{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 @file{/dev}-Knotens. Mit -Bezeichnungen und UUIDs kann man Dateisysteme benennen, ohne den Gerätenamen -festzuschreiben@footnote{Beachten Sie: Obwohl es verführerisch ist, mit -@file{/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.}. - -@findex file-system-label -Dateisystem-Bezeichnungen (»Labels«) werden mit der Prozedur -@code{file-system-label} erzeugt und UUID-Kennungen werden mit @code{uuid} -erzeugt, während Knoten in @file{/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 -@command{e2label} angezeigt wird: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (file-system-label "my-home"))) -@end example - -@findex uuid -UUID-Kennungen werden mit der @code{uuid}-Form von ihrer Darstellung als -Zeichenkette (wie sie vom Befehl @command{tune2fs -l} angezeigt wird) -konvertiert@footnote{Die @code{uuid}-Form nimmt 16-Byte-UUIDs entgegen, wie -sie in @uref{https://tools.ietf.org/html/rfc4122, RFC@tie{}4122} 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: - -@example -(file-system - (mount-point "/home") - (type "ext4") - (device (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) -@end example - -Wenn die Quelle eines Dateisystems ein zugeordnetes Gerät (@pxref{Zugeordnete Geräte}) ist, @emph{muss} sich das @code{device}-Feld auf den zugeordneten -Gerätenamen beziehen — z.B. @file{"/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. - -@item @code{flags} (Vorgabe: @code{'()}) -Eine Liste von Symbolen, die Einbinde-Flags (»mount flags«) -bezeichnen. Erkannt werden unter Anderem @code{read-only}, -@code{bind-mount}, @code{no-dev} (Zugang zu besonderen Dateien verweigern), -@code{no-suid} (setuid- und setgid-Bits ignorieren) und @code{no-exec} -(Programmausführungen verweigern). - -@item @code{options} (Vorgabe: @code{#f}) -Entweder @code{#f} oder eine Zeichenkette mit Einbinde-Optionen (»mount -options«). - -@item @code{mount?} (Vorgabe: @code{#t}) -Dieser Wert zeigt an, ob das Dateisystem automatisch eingebunden werden -soll, wenn das System gestartet wird. Ist der Wert @code{#f}, dann erhält -das Dateisystem nur einen Eintrag in der Datei @file{/etc/fstab} (welche vom -@command{mount}-Befehl zum Einbinden gelesen wird), es wird aber nicht -automatisch eingebunden. - -@item @code{needed-for-boot?} (Vorgabe: @code{#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. - -@item @code{check?} (Vorgabe: @code{#t}) -Dieser boolesche Wert sagt aus, ob das Dateisystem vor dem Einbinden auf -Fehler hin geprüft werden soll. - -@item @code{create-mount-point?} (Vorgabe: @code{#f}) -Steht dies auf wahr, wird der Einhängepunkt vor dem Einbinden erstellt, wenn -er noch nicht existiert. - -@item @code{dependencies} (Vorgabe: @code{'()}) -Dies ist eine Liste von @code{<file-system>}- oder -@code{<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: -@file{/sys/fs/cgroup} ist eine Abhängigkeit von @file{/sys/fs/cgroup/cpu} -und @file{/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 (@pxref{Zugeordnete Geräte}). -@end table -@end deftp - -Das Modul @code{(gnu system file-systems)} exportiert die folgenden -nützlichen Variablen. - -@defvr {Scheme-Variable} %base-file-systems -Hiermit werden essenzielle Dateisysteme bezeichnet, die für normale Systeme -unverzichtbar sind, wie zum Beispiel @var{%pseudo-terminal-file-system} und -@var{%immutable-store} (siehe unten). Betriebssystemdeklaration sollten auf -jeden Fall mindestens diese enthalten. -@end defvr - -@defvr {Scheme-Variable} %pseudo-terminal-file-system -Das als @file{/dev/pts} einzubindende Dateisystem. Es unterstützt über -@code{openpty} und ähnliche Funktionen erstellte @dfn{Pseudo-Terminals} -(@pxref{Pseudo-Terminals,,, libc, The GNU C Library Reference -Manual}). Pseudo-Terminals werden von Terminal-Emulatoren wie -@command{xterm} benutzt. -@end defvr - -@defvr {Scheme-Variable} %shared-memory-file-system -Dieses Dateisystem wird als @file{/dev/shm} eingebunden, um Speicher -zwischen Prozessen teilen zu können (@pxref{Memory-mapped I/O, -@code{shm_open},, libc, The GNU C Library Reference Manual}). -@end defvr - -@defvr {Scheme-Variable} %immutable-store -Dieses Dateisystem vollzieht einen »bind mount« des @file{/gnu/store}, um -ihn für alle Nutzer einschließlich des Administratornutzers @code{root} nur -lesbar zu machen, d.h. Schreibrechte zu entziehen. Dadurch kann als -@code{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. -@end defvr - -@defvr {Scheme-Variable} %binary-format-file-system -Das @code{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 -@code{binfmt.ko} geladen wurde. -@end defvr - -@defvr {Scheme-Variable} %fuse-control-file-system -Das @code{fusectl}-Dateisystem, womit »unprivilegierte« Nutzer ohne -besondere Berechtigungen im User Space FUSE-Dateisysteme einbinden und -aushängen können. Dazu muss das Kernel-Modul @code{fuse.ko} geladen sein. -@end defvr - -@node Zugeordnete Geräte -@section Zugeordnete Geräte - -@cindex Gerätezuordnung -@cindex zugeordnete Geräte -Der Linux-Kernel unterstützt das Konzept der @dfn{Gerätezuordnung}: Ein -blockorientiertes Gerät wie eine Festplattenpartition kann einem neuen Gerät -@dfn{zugeordnet} werden, gewöhnlich unter @code{/dev/mapper/}, wobei das -neue Gerät durchlaufende Daten zusätzlicher Verarbeitung unterzogen -werden@footnote{Beachten Sie, dass mit GNU@tie{}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 @emph{übersetzt}. Hurd -implementiert zugeordnete Geräte genau wie Dateisysteme mit dem generischen -@dfn{Übersetzer}-Mechanismus (@pxref{Translators,,, hurd, 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 @dfn{umgewandelt} wird, um ein -neues Gerät zu bilden; zum Beispiel entstehen auch RAID-Geräte aus einem -@dfn{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 @code{mapped-device}-Form -deklariert, die wie folgt definiert ist; Beispiele folgen weiter unten. - -@deftp {Datentyp} mapped-device -Objekte dieses Typs repräsentieren Gerätezuordnungen, die gemacht werden, -wenn das System hochfährt. - -@table @code -@item source -Es handelt sich entweder um eine Zeichenkette, die den Namen eines -zuzuordnenden blockorientierten Geräts angibt, wie @code{"/dev/sda3"}, oder -um eine Liste solcher Zeichenketten, sofern mehrere Geräts zu einem neuen -Gerät verbunden werden. - -@item target -Diese Zeichenkette gibt den Namen des neuen zugeordneten Geräts an. Bei -Kernel-Zuordnern, wie verschlüsselten Geräten vom Typ -@code{luks-device-mapping}, wird durch Angabe von @code{"my-partition"} ein -Gerät @code{"/dev/mapper/my-partition"} erzeugt. Bei RAID-Geräten vom Typ -@code{raid-device-mapping} muss der Gerätename als voller Pfad wie zum -Beispiel @code{"/dev/md0"} angegeben werden. - -@item type -Dies muss ein @code{mapped-device-kind}-Objekt sein, das angibt, wie die -Quelle @var{source} dem Ziel @var{target} zugeordnet wird. -@end table -@end deftp - -@defvr {Scheme-Variable} luks-device-mapping -Hiermit wird ein blockorientiertes Gerät mit LUKS verschlüsselt, mit Hilfe -des Befehls @command{cryptsetup} aus dem gleichnamigen Paket. Dazu wird das -Linux-Kernel-Modul @code{dm-crypt} vorausgesetzt. -@end defvr - -@defvr {Scheme-Variable} raid-device-mapping -Dies definiert ein RAID-Gerät, das mit dem Befehl @code{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. @code{raid456} für RAID-4, RAID-5 oder RAID-6, oder @code{raid10} für -RAID-10. -@end defvr - -@cindex Laufwerksverschlüsselung -@cindex LUKS -Das folgende Beispiel gibt eine Zuordnung von @file{/dev/sda3} auf -@file{/dev/mapper/home} mit LUKS an — dem -@url{https://gitlab.com/cryptsetup/cryptsetup,Linux Unified Key Setup}, -einem Standardmechanismus zur Plattenverschlüsselung. Das Gerät -@file{/dev/mapper/home} kann dann als @code{device} einer -@code{file-system}-Deklaration benutzt werden (@pxref{Dateisysteme}). - -@example -(mapped-device - (source "/dev/sda3") - (target "home") - (type luks-device-mapping)) -@end example - -Um nicht davon abhängig zu sein, wie Ihre Geräte nummeriert werden, können -Sie auch die LUKS-UUID (@dfn{unique identifier}, d.h. den eindeutigen -Bezeichner) des Quellgeräts auf der Befehlszeile ermitteln: - -@example -cryptsetup luksUUID /dev/sda3 -@end example - -und wie folgt benutzen: - -@example -(mapped-device - (source (uuid "cb67fc72-0d54-4c88-9d4b-b225f30b0f44")) - (target "home") - (type luks-device-mapping)) -@end example - -@cindex Swap-Verschlüsselung -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 -@xref{Vor der Installation,,Disk Partitioning}. - -Ein RAID-Gerät als Verbund der Partitionen @file{/dev/sda1} und -@file{/dev/sdb1} kann wie folgt deklariert werden: - -@example -(mapped-device - (source (list "/dev/sda1" "/dev/sdb1")) - (target "/dev/md0") - (type raid-device-mapping)) -@end example - -Das Gerät @file{/dev/md0} kann als @code{device} in einer -@code{file-system}-Deklaration dienen (@pxref{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. - - -@node Benutzerkonten -@section Benutzerkonten - -@cindex Benutzer -@cindex Konten -@cindex Benutzerkonten -Benutzerkonten und Gruppen werden allein durch die -@code{operating-system}-Deklaration des Betriebssystems verwaltet. Sie -werden mit den @code{user-account}- und @code{user-group}-Formen angegeben: - -@example -(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")) -@end example - -Beim Hochfahren oder nach Abschluss von @command{guix system reconfigure} -stellt das System sicher, dass nur die in der -@code{operating-system}-Deklaration angegebenen Benutzerkonten und Gruppen -existieren, mit genau den angegebenen Eigenschaften. Daher gehen durch -direkten Aufruf von Befehlen wie @command{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. - -@deftp {Datentyp} user-account -Objekte dieses Typs repräsentieren Benutzerkonten. Darin können folgende -Komponenten aufgeführt werden: - -@table @asis -@item @code{name} -Der Name des Benutzerkontos. - -@item @code{group} -@cindex Gruppen -Dies ist der Name (als Zeichenkette) oder die Bezeichnung (als Zahl) der -Benutzergruppe, zu der dieses Konto gehört. - -@item @code{supplementary-groups} (Vorgabe: @code{'()}) -Dies kann optional als Liste von Gruppennamen angegeben werden, zu denen -dieses Konto auch gehört. - -@item @code{uid} (Vorgabe: @code{#f}) -Dies ist entweder der Benutzeridentifikator dieses Kontos (seine »User ID«) -als Zahl oder @code{#f}. Bei Letzterem wird vom System automatisch eine Zahl -gewählt, wenn das Benutzerkonto erstellt wird. - -@item @code{comment} (Vorgabe: @code{""}) -Ein Kommentar zu dem Konto, wie etwa der vollständige Name des -Kontoinhabers. - -@item @code{home-directory} -Der Name des Persönlichen Verzeichnisses (»Home«-Verzeichnis) für dieses -Konto. - -@item @code{create-home-directory?} (Vorgabe: @code{#t}) -Zeigt an, ob das Persönliche Verzeichnis für das Konto automatisch erstellt -werden soll, falls es noch nicht existiert. - -@item @code{shell} (Vorgabe: Bash) -Ein G-Ausdruck, der den Dateinamen des Programms angibt, das dem Benutzer -als Shell dienen soll (@pxref{G-Ausdrücke}). - -@item @code{system?} (Vorgabe: @code{#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. - -@anchor{user-account-password} -@cindex password, for user accounts -@item @code{password} (Vorgabe: @code{#f}) -Normalerweise lassen Sie dieses Feld auf @code{#f} und initialisieren -Benutzerpasswörter als @code{root} mit dem @command{passwd}-Befehl. Die -Benutzer lässt man ihr eigenes Passwort dann mit @command{passwd} -ändern. Mit @command{passwd} festgelegte Passwörter bleiben natürlich beim -Neustarten und beim Rekonfigurieren erhalten. - -If you @emph{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 -@code{crypt} procedure for this purpose: - -@example -(user-account - (name "charlie") - (home-directory "/home/charlie") - (group "users") - - ;; Specify a SHA-512-hashed initial password. - (password (crypt "InitialPassword!" "$6$abc"))) -@end example - -@quotation Anmerkung -The hash of this initial password will be available in a file in -@file{/gnu/store}, readable by all the users, so this method must be used -with care. -@end quotation - -@xref{Passphrase Storage,,, libc, The GNU C Library Reference Manual}, for -more information on password encryption, and @ref{Encryption,,, guile, GNU -Guile Reference Manual}, for information on Guile's @code{crypt} procedure. - -@end table -@end deftp - -@cindex Gruppen -Benutzergruppen-Deklarationen sind noch einfacher aufgebaut: - -@example -(user-group (name "students")) -@end example - -@deftp {Datentyp} user-group -Dieser Typ gibt, nun ja, eine Benutzergruppe an. Es gibt darin nur ein paar -Felder: - -@table @asis -@item @code{name} -Der Name der Gruppe. - -@item @code{id} (Vorgabe: @code{#f}) -Der Gruppenbezeichner (eine Zahl). Wird er als @code{#f} angegeben, wird -automatisch eine neue Zahl reserviert, wenn die Gruppe erstellt wird. - -@item @code{system?} (Vorgabe: @code{#f}) -Dieser boolesche Wert gibt an, ob es sich um eine »System«-Gruppe -handelt. Systemgruppen sind solche mit einer kleinen Zahl als Bezeichner. - -@item @code{password} (Vorgabe: @code{#f}) -Wie, Benutzergruppen können ein Passwort haben? Nun ja, anscheinend -schon. Wenn es nicht auf @code{#f} steht, gibt dieses Feld das Passwort der -Gruppe an. - -@end table -@end deftp - -Um Ihnen das Leben zu erleichtern, gibt es eine Variable, worin alle -grundlegenden Benutzergruppen aufgeführt sind, die man erwarten könnte: - -@defvr {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«. -@end defvr - -@defvr {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. -@end defvr - -@node Locales -@section Locales - -@cindex Locale -Eine @dfn{Locale} legt die kulturellen Konventionen einer bestimmten Sprache -und Region auf der Welt fest (@pxref{Locales,,, libc, The GNU C Library -Reference Manual}). Jede Locale hat einen Namen, der typischerweise von der -Form @code{@var{Sprache}_@var{Territorium}.@var{Kodierung}} — z.B. benennt -@code{fr_LU.utf8} die Locale für französische Sprache mit den kulturellen -Konventionen aus Luxemburg unter Verwendung der UTF-8-Kodierung. - -@cindex Locale-Definition -Normalerweise werden Sie eine standardmäßig zu verwendende Locale für die -Maschine vorgeben wollen, indem Sie das @code{locale}-Feld der -@code{operating-system}-Deklaration verwenden (@pxref{»operating-system«-Referenz, @code{locale}}). - -Die ausgewählte Locale wird automatisch zu den dem System bekannten -@dfn{Locale-Definitionen} hinzugefügt, falls nötig, und ihre Kodierung wird -aus dem Namen hergeleitet — z.B. wird angenommen, dass @code{bo_CN.utf8} als -Kodierung @code{UTF-8} verwendet. Zusätzliche Locale-Definitionen können im -Feld @code{locale-definitions} vom @code{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: - -@example -(cons (locale-definition - (name "fy_DE.utf8") (source "fy_DE")) - %default-locale-definitions) -@end example - -Um Platz zu sparen, könnte man auch wollen, dass @code{locale-definitions} -nur die tatsächlich benutzen Locales aufführt, wie etwa: - -@example -(list (locale-definition - (name "ja_JP.eucjp") (source "ja_JP") - (charset "EUC-JP"))) -@end example - -@vindex LOCPATH -Die kompilierten Locale-Definitionen sind unter -@file{/run/current-system/locale/X.Y} verfügbar, wobei @code{X.Y} die -Version von libc bezeichnet. Dies entspricht dem Pfad, an dem eine von Guix -ausgelieferte GNU@tie{}libc standardmäßig nach Locale-Daten sucht. Er kann -überschrieben werden durch die Umgebungsvariable @code{LOCPATH} -(@pxref{locales-and-locpath, @code{LOCPATH} und Locale-Pakete}). - -Die @code{locale-definition}-Form wird vom Modul @code{(gnu system locale)} -zur Verfügung gestellt. Details folgen unten. - -@deftp {Datentyp} locale-definition -Dies ist der Datentyp einer Locale-Definition. - -@table @asis - -@item @code{name} -Der Name der Locale. Siehe @xref{Locale Names,,, libc, The GNU C Library -Reference Manual} für mehr Informationen zu Locale-Namen. - -@item @code{source} -Der Name der Quelle der Locale. Typischerweise ist das der Teil aus -@code{@var{Sprache}_@var{Territorium}} des Locale-Namens. - -@item @code{charset} (Vorgabe: @code{"UTF-8"}) -Der »Zeichensatz« oder das »Code set«, d.h. die Kodierung dieser Locale, -@uref{http://www.iana.org/assignments/character-sets, wie die IANA sie -definiert}. - -@end table -@end deftp - -@defvr {Scheme-Variable} %default-locale-definitions -Eine Liste häufig benutzter UTF-8-Locales, die als Vorgabewert des -@code{locale-definitions}-Feldes in @code{operating-system}-Deklarationen -benutzt wird. - -@cindex Locale-Name -@cindex Normalisiertes Codeset in Locale-Namen -Diese Locale-Definitionen benutzen das @dfn{normalisierte Codeset} für den -Teil des Namens, der nach dem Punkt steht (@pxref{Using gettextized -software, normalized codeset,, libc, The GNU C Library Reference -Manual}). Zum Beispiel ist @code{uk_UA.utf8} enthalten, dagegen ist etwa -@code{uk_UA.UTF-8} darin @emph{nicht} enthalten. -@end defvr - -@subsection Kompatibilität der Locale-Daten - -@cindex Inkompatibilität, von Locale-Daten -@code{operating-system}-Deklarationen verfügen über ein -@code{locale-libcs}-Feld, um die GNU@tie{}libc-Pakete anzugeben, die zum -Kompilieren von Locale-Deklarationen verwendet werden sollen -(@pxref{»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. - -@c See <https://sourceware.org/ml/libc-alpha/2015-09/msg00575.html> -@c and <https://lists.gnu.org/archive/html/guix-devel/2015-08/msg00737.html>. -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 -@emph{terminiert} statt einfach die inkompatiblen Locale-Daten zu -ignorieren@footnote{Versionen 2.23 von GNU@tie{}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 -@code{LC_COLLATE} sind aber zum Beispiel inkompatibel); somit schlagen -Aufrufe von @code{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 -@var{GUIX_LOCPATH} entsprechend definieren (@pxref{locales-and-locpath, -@code{GUIX_LOCPATH} und Locale-Pakete}). - -Trotzdem ist es am besten, wenn die systemweiten Locale-Daten unter -@file{/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 -@code{locale-libcs}-Feld vom @code{operating-system} angeben: - -@example -(use-package-modules base) - -(operating-system - ;; @dots{} - (locale-libcs (list glibc-2.21 (canonical-package glibc)))) -@end example - -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 -@file{/run/current-system/locale} hat. - - -@node Dienste -@section Dienste - -@cindex Systemdienste -Ein wichtiger Bestandteil des Schreibens einer -@code{operating-system}-Deklaration ist das Auflisten der -@dfn{Systemdienste} und ihrer Konfiguration (@pxref{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'' (@pxref{Dienstkompositionen}), -but many services are managed by the GNU@tie{}Shepherd (@pxref{Shepherd-Dienste}). On a running system, the @command{herd} command allows you to -list the available services, show their status, start and stop them, or do -other specific operations (@pxref{Jump Start,,, shepherd, The GNU Shepherd -Manual}). For example: - -@example -# herd status -@end example - -Dieser Befehl, durchgeführt als @code{root}, listet die momentan definierten -Dienste auf. Der Befehl @command{herd doc} fasst kurz zusammen, was ein -gegebener Dienst ist und welche Aktionen mit ihm assoziiert sind: - -@example -# 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. -@end example - -Die Unterbefehle @command{start}, @command{stop} und @command{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: - -@example -# herd stop nscd -Service nscd has been stopped. -# herd restart xorg-server -Service xorg-server has been stopped. -Service xorg-server has been started. -@end example - -Die folgenden Abschnitte dokumentieren die verfügbaren Dienste, die in einer -@code{operating-system}-Deklaration benutzt werden können, angefangen mit -den Diensten im Kern des Systems (»core services«) - -@menu -* Basisdienste:: Essenzielle Systemdienste. -* Geplante Auftragsausführung:: Der mcron-Dienst. -* Log-Rotation:: Der rottlog-Dienst. -* Netzwerkdienste:: Netzwerkeinrichtung, SSH-Daemon etc. -* X Window:: Grafische Anzeige. -* Druckdienste:: Unterstützung für lokale und entfernte - Drucker. -* Desktop-Dienste:: D-Bus- und Desktop-Dienste. -* Tondienste:: Dienste für ALSA und Pulseaudio. -* Datenbankdienste:: SQL-Datenbanken, Schlüssel-Wert-Speicher etc. -* Mail-Dienste:: IMAP, POP3, SMTP und so weiter. -* Kurznachrichtendienste:: Dienste für Kurznachrichten. -* Telefondienste:: Telefoniedienste. -* Überwachungsdienste:: Dienste zur Systemüberwachung. -* Kerberos-Dienste:: Kerberos-Dienste. -* Web-Dienste:: Web-Server. -* Zertifikatsdienste:: TLS-Zertifikate via Let’s Encrypt. -* DNS-Dienste:: DNS-Daemons. -* VPN-Dienste:: VPN-Daemons. -* Network File System:: Dienste mit Bezug zum Netzwerkdateisystem. -* Kontinuierliche Integration:: Der Cuirass-Dienst. -* Dienste zur Stromverbrauchsverwaltung:: Den Akku schonen. -* Audio-Dienste:: Der MPD. -* Virtualisierungsdienste:: Dienste für virtuelle Maschinen. -* Versionskontrolldienste:: Entfernten Zugang zu Git-Repositorys bieten. -* Spieldienste:: Spielserver. -* Verschiedene Dienste:: Andere Dienste. -@end menu - -@node Basisdienste -@subsection Basisdienste - -Das Modul @code{(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. - -@defvr {Scheme-Variable} %base-services -Diese Variable enthält eine Liste von Basis-Diensten, die man auf einem -System vorzufinden erwartet (siehe @pxref{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 @code{services}-Feld für die Dienste von -@code{operating-system}-Deklarationen. Normalerweise werden Sie, wenn Sie -ein Betriebssystem anpassen, Dienste an die @var{%base-services}-Liste -anhängen, wie hier gezeigt: - -@example -(append (list (service avahi-service-type) - (service openssh-service-type)) - %base-services) -@end example -@end defvr - -@defvr {Scheme-Variable} special-files-service-type -Dieser Dienst richtet »besondere Dateien« wie @file{/bin/sh} ein; eine -Instanz des Dienstes ist Teil der @code{%base-services}. - -Der mit @code{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: - -@cindex @file{/bin/sh} -@cindex @file{sh}, in @file{/bin} -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh"))) -@end example - -@cindex @file{/usr/bin/env} -@cindex @file{env}, in @file{/usr/bin} -Wenn Sie zum Beispiel auch @code{/usr/bin/env} zu Ihrem System hinzufügen -möchten, können Sie den Wert ändern auf: - -@example -`(("/bin/sh" ,(file-append @var{bash} "/bin/sh")) - ("/usr/bin/env" ,(file-append @var{coreutils} "/bin/env"))) -@end example - -Da dieser Dienst Teil der @code{%base-services} ist, können Sie -@code{modify-services} benutzen, um die Liste besonderer Dateien abzuändern -(@pxref{Service-Referenz, @code{modify-services}}). Die leichte -Alternative, um eine besondere Datei hinzuzufügen, ist über die Prozedur -@code{extra-special-file} (siehe unten). -@end defvr - -@deffn {Scheme-Prozedur} extra-special-file @var{Datei} @var{Ziel} -Das @var{Ziel} als »besondere Datei« @var{Datei} verwenden. - -Beispielsweise können Sie die folgenden Zeilen in das @code{services}-Feld -Ihrer Betriebssystemdeklaration einfügen für eine symbolische Verknüpfung -@file{/usr/bin/env}: - -@example -(extra-special-file "/usr/bin/env" - (file-append coreutils "/bin/env")) -@end example -@end deffn - -@deffn {Scheme-Prozedur} host-name-service @var{Name} -Liefert einen Dienst, der den Rechnernamen (den »Host«-Namen des Rechners) -als @var{Name} festlegt. -@end deffn - -@deffn {Scheme-Prozedur} login-service @var{Konfiguration} -Liefert einen Dienst, der die Benutzeranmeldung möglich macht. Dazu -verwendet er die angegebene @var{Konfiguration}, ein -@code{<login-configuration>}-Objekt, das unter Anderem die beim Anmelden -angezeigte Mitteilung des Tages (englisch »Message of the Day«) festlegt. -@end deffn - -@deftp {Datentyp} login-configuration -Dies ist der Datentyp, der die Anmeldekonfiguration repräsentiert. - -@table @asis - -@item @code{motd} -@cindex Message of the Day -Ein dateiartiges Objekt, das die »Message of the Day« enthält. - -@item @code{allow-empty-passwords?} (Vorgabe: @code{#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. - -@end table -@end deftp - -@deffn {Scheme-Prozedur} mingetty-service @var{Konfiguration} -Liefert einen Dienst, der mingetty nach den Vorgaben der @var{Konfiguration} -ausführt, einem @code{<mingetty-configuration>}-Objekt, das unter Anderem -die Konsole (das »tty«) festlegt, auf der mingetty laufen soll. -@end deffn - -@deftp {Datentyp} mingetty-configuration -Dieser Datentyp repräsentiert die Konfiguration von Mingetty, der -vorgegebenen Implementierung zur Anmeldung auf einer virtuellen Konsole. - -@table @asis - -@item @code{tty} -Der Name der Konsole, auf der diese Mingetty-Instanz läuft — -z.B. @code{"tty1"}. - -@item @code{auto-login} (Vorgabe: @code{#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 @code{#f}, so muss zur Anmeldung ein Benutzername und ein -Passwort eingegeben werden. - -@item @code{login-program} (Vorgabe: @code{#f}) -Dies muss entweder @code{#f} sein, dann wird das voreingestellte -Anmeldeprogramm benutzt (@command{login} aus dem Shadow-Werkzeugsatz) oder -der Name des Anmeldeprogramms als G-Ausdruck. - -@item @code{login-pause?} (Vorgabe: @code{#f}) -Ist es auf @code{#t} gesetzt, sorgt es in Verbindung mit @var{auto-login} -dafür, dass der Benutzer eine Taste drücken muss, ehe eine Anmelde-Shell -gestartet wird. - -@item @code{mingetty} (Vorgabe: @var{mingetty}) -Welches Mingetty-Paket benutzt werden soll. - -@end table -@end deftp - -@deffn {Scheme-Prozedur} agetty-service @var{Konfiguration} -Liefert einen Dienst, um agetty entsprechend der @var{Konfiguration} -auszuführen, welche ein @code{<agetty-configuration>}-Objekt sein muss, das -unter Anderem festlegt, auf welchem tty es laufen soll. -@end deffn - -@deftp {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 @code{agetty(8)} für mehr Informationen. - -@table @asis - -@item @code{tty} -Der Name der Konsole, auf der diese Instanz von agetty läuft, als -Zeichenkette — z.B. @code{"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 -@code{agetty.tty} festgelegt wurde, der Gerätename daraus für agetty -extrahiert und benutzt. - -Andernfalls wird agetty, falls auf der Kernel-Befehlszeile eine Option -@code{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. - -@item @code{baud-rate} (Vorgabe: @code{#f}) -Eine Zeichenkette, die aus einer kommagetrennten Liste von einer oder -mehreren Baud-Raten besteht, absteigend sortiert. - -@item @code{term} (Vorgabe: @code{#f}) -Eine Zeichenkette, die den Wert enthält, der für die Umgebungsvariable -@code{TERM} benutzt werden soll. - -@item @code{eight-bits?} (Vorgabe: @code{#f}) -Steht dies auf @code{#t}, wird angenommen, dass das tty 8-Bit-korrekt ist, -so dass die Paritätserkennung abgeschaltet wird. - -@item @code{auto-login} (Vorgabe: @code{#f}) -Wird hier ein Anmeldename als eine Zeichenkette übergeben, wird der -angegebene Nutzer automatisch angemeldet, ohne nach einem Anmeldenamen oder -Passwort zu fragen. - -@item @code{no-reset?} (Vorgabe: @code{#f}) -Steht dies auf @code{#t}, werden die Cflags des Terminals (d.h. dessen -Steuermodi) nicht zurückgesetzt. - -@item @code{host} (Vorgabe: @code{#f}) -Dies akzeptiert eine Zeichenkette mit dem einzutragenden -Anmeldungs-Rechnernamen "login_host", der in die Datei @file{/var/run/utmpx} -geschrieben wird. - -@item @code{remote?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird in Verbindung mit @var{host} eine -Befehlszeilenoption @code{-r} für einen falschen Rechnernamen (»Fakehost«) -in der Befehlszeile des mit @var{login-program} angegebenen Anmeldeprogramms -übergeben. - -@item @code{flow-control?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird Hardware-Flusssteuerung (RTS/CTS) -aktiviert. - -@item @code{no-issue?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird der Inhalt der Datei @file{/etc/issue} -@emph{nicht} angezeigt, bevor die Anmeldeaufforderung zu sehen ist. - -@item @code{init-string} (Vorgabe: @code{#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. - -@item @code{no-clear?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird agetty den Bildschirm @emph{nicht} -löschen, bevor es die Anmeldeaufforderung anzeigt. - -@item @code{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 @command{login} aus dem Shadow-Werkzeugsatz -verwendet wird. - -@item @code{local-line} (Vorgabe: @code{#f}) -Steuert den Leitungsschalter CLOCAL. Hierfür wird eines von drei Symbolen -als Argument akzeptiert, @code{'auto}, @code{'always} oder -@code{'never}. Für @code{#f} wählt agetty als Vorgabewert @code{'auto}. - -@item @code{extract-baud?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, so wird agetty angewiesen, die Baud-Rate aus -den Statusmeldungen mancher Arten von Modem abzulesen. - -@item @code{skip-login?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird der Benutzer nicht aufgefordert, einen -Anmeldenamen einzugeben. Dies kann zusammen mit dem @var{login-program}-Feld -benutzt werden, um nicht standardkonforme Anmeldesysteme zu benutzen. - -@item @code{no-newline?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird @emph{kein} Zeilenumbruch ausgegeben, -bevor die Datei @file{/etc/issue} ausgegeben wird. - -@c Is this dangerous only when used with login-program, or always? -@item @code{login-options} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine Zeichenkette mit den Befehlszeilenoptionen für -das Anmeldeprogramm. Beachten Sie, dass bei einem selbst gewählten -@var{login-program} ein böswilliger Nutzer versuchen könnte, als -Anmeldenamen etwas mit eingebetteten Befehlszeilenoptionen anzugeben, die -vom Anmeldeprogramm interpretiert werden könnten. - -@item @code{login-pause} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird auf das Drücken einer beliebigen Taste -gewartet, bevor die Anmeldeaufforderung angezeigt wird. Hiermit kann in -Verbindung mit @var{auto-login} weniger Speicher verbraucht werden, indem -man Shells erst erzeugt, wenn sie benötigt werden. - -@item @code{chroot} (Vorgabe: @code{#f}) -Wechselt die Wurzel des Dateisystems auf das angegebene Verzeichnis. Dieses -Feld akzeptiert einen Verzeichnispfad als Zeichenkette. - -@item @code{hangup?} (Vorgabe: @code{#f}) -Mit dem Linux-Systemaufruf @code{vhangup} auf dem angegebenen Terminal -virtuell auflegen. - -@item @code{keep-baud?} (Vorgabe: @code{#f}) -Ist dies auf @code{#t} gesetzt, wird versucht, die bestehende Baud-Rate -beizubehalten. Die Baud-Raten aus dem Feld @var{baud-rate} werden benutzt, -wenn agetty ein @key{BREAK}-Zeichen empfängt. - -@item @code{timeout} (Vorgabe: @code{#f}) -Ist dies auf einen ganzzahligen Wert gesetzt, wird terminiert, falls kein -Benutzername innerhalb von @var{timeout} Sekunden eingelesen werden konnte. - -@item @code{detect-case?} (Vorgabe: @code{#f}) -Ist dies auf @code{#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 @emph{keine} Unicode-Zeichen unterstützt -werden. - -@item @code{wait-cr?} (Vorgabe: @code{#f}) -Wenn dies auf @code{#t} gesetzt ist, wird gewartet, bis der Benutzer oder -das Modem einen Wagenrücklauf (»Carriage Return«) oder einen Zeilenvorschub -(»Linefeed«) absendet, ehe @file{/etc/issue} oder eine Anmeldeaufforderung -angezeigt wird. Dies wird typischerweise zusammen mit dem Feld -@var{init-string} benutzt. - -@item @code{no-hints?} (Vorgabe: @code{#f}) -Ist es auf @code{#t} gesetzt, werden @emph{keine} Hinweise zu den -Feststelltasten Num-Taste, Umschaltsperre (»Caps Lock«) und Rollen-Taste -(»Scroll Lock«) angezeigt. - -@item @code{no-hostname?} (Vorgabe: @code{#f}) -Das vorgegebene Verhalten ist, den Rechnernamen auszugeben. Ist dieses Feld -auf @code{#t} gesetzt, wird überhaupt kein Rechnername angezeigt. - -@item @code{long-hostname?} (Vorgabe: @code{#f}) -Das vorgegebene Verhalten ist, den Rechnernamen nur bis zu seinem ersten -Punkt anzuzeigen. Ist dieses Feld auf @code{#t} gesetzt, wird der -vollständige Rechnername (der »Fully Qualified Hostname«), wie ihn -@code{gethostname} oder @code{getaddrinfo} liefern, angezeigt. - -@item @code{erase-characters} (Vorgabe: @code{#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. - -@item @code{kill-characters} (Vorgabe: @code{#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. - -@item @code{chdir} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine Zeichenkette, die einen Verzeichnispfad angibt, -zu dem vor der Anmeldung gewechselt wird. - -@item @code{delay} (Vorgabe: @code{#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. - -@item @code{nice} (Vorgabe: @code{#f}) -Dieses Feld akzeptiert eine ganze Zahl mit dem »nice«-Wert, mit dem das -Anmeldeprogramm ausgeführt werden soll. - -@item @code{extra-options} (Vorgabe: @code{'()}) -Dieses Feld ist ein »Notausstieg«, mit dem Nutzer beliebige -Befehlszeilenoptionen direkt an @command{agetty} übergeben können. Diese -müssen hier als eine Liste von Zeichenketten angegeben werden. - -@end table -@end deftp - -@deffn {Scheme-Prozedur} kmscon-service-type @var{Konfiguration} -Liefert einen Dienst, um -@uref{https://www.freedesktop.org/wiki/Software/kmscon,kmscon} entsprechend -der @var{Konfiguration} auszuführen. Diese ist ein -@code{<kmscon-configuration>}-Objekt, das unter Anderem angibt, auf welchem -tty es ausgeführt werden soll. -@end deffn - -@deftp {Datentyp} kmscon-configuration -Dieser Datentyp repräsentiert die Konfiguration von Kmscon, die das Anmelden -auf virtuellen Konsolen ermöglicht. - -@table @asis - -@item @code{virtual-terminal} -Der Name der Konsole, auf der diese Kmscon läuft — z.B. @code{"tty1"}. - -@item @code{login-program} (Vorgabe: @code{#~(string-append #$shadow "/bin/login")}) -Ein G-Ausdruck, der den Namen des Anmeldeprogramms angibt. Als Vorgabe wird -das Anmeldeprogramm @command{login} aus dem Shadow-Werkzeugsatz verwendet. - -@item @code{login-arguments} (Vorgabe: @code{'("-p")}) -Eine Liste der Argumente, die an @command{login} übergeben werden sollen. - -@item @code{auto-login} (Vorgabe: @code{#f}) -Wird hier ein Anmeldename als eine Zeichenkette übergeben, wird der -angegebene Nutzer automatisch angemeldet, ohne nach einem Anmeldenamen oder -Passwort zu fragen. - -@item @code{hardware-acceleration?} (Vorgabe: #f) -Ob Hardware-Beschleunigung verwendet werden soll. - -@item @code{kmscon} (Vorgabe: @var{kmscon}) -Das Kmscon-Paket, das benutzt werden soll. - -@end table -@end deftp - -@cindex Name Service Cache Daemon -@cindex nscd -@deffn {Scheme-Prozedur} nscd-service [@var{Konfiguration}] [#:glibc glibc] @ - [#:name-services '()] Liefert einen Dienst, der den Name Service Cache -Daemon (nscd) von libc mit der angegebenen @var{Konfiguration} ausführt — -diese muss ein @code{<nscd-configuration>}-Objekt sein. Siehe @xref{Name Service Switch} für ein Beispiel. - -Der Einfachheit halber bietet der Shepherd-Dienst für nscd die folgenden -Aktionen an: - -@table @code -@item invalidate -@cindex Zwischenspeicher ungültig machen, nscd -@cindex nscd, Ungültigmachen des Zwischenspeichers -Dies macht den angegebenen Zwischenspeicher ungültig. Wenn Sie zum Beispiel: - -@example -herd invalidate nscd hosts -@end example - -@noindent -ausführen, wird der Zwischenspeicher für die Auflösung von Rechnernamen (von -»Host«-Namen) des nscd ungültig. - -@item statistics -Wenn Sie @command{herd statistics nscd} ausführen, werden Ihnen -Informationen angezeigt, welche Ihnen Informationen über den nscd-Zustand -und die Zwischenspeicher angezeigt. -@end table - -@end deffn - -@defvr {Scheme-Variable} %nscd-default-configuration -Dies ist der vorgegebene Wert für die @code{<nscd-configuration>} (siehe -unten), die @code{nscd-service} benutzt. Die Konfiguration benutzt die -Zwischenspeicher, die in @var{%nscd-default-caches} definiert sind; siehe -unten. -@end defvr - -@deftp {Datentyp} nscd-configuration -Dieser Datentyp repräsentiert die Konfiguration des Name Service Caching -Daemon (kurz »nscd«). - -@table @asis - -@item @code{name-services} (Vorgabe: @code{'()}) -Liste von Paketen, die @dfn{Namensdienste} bezeichnen, die für den nscd -sichtbar sein müssen, z.B. @code{(list @var{nss-mdns})}. - -@item @code{glibc} (Vorgabe: @var{glibc}) -Ein Paket-Objekt, das die GNU-C-Bibliothek angibt, woraus der -@command{nscd}-Befehl genommen werden soll. - -@item @code{log-file} (Vorgabe: @code{"/var/log/nscd.log"}) -Name der nscd-Protokolldatei. Hierhin werden Ausgaben zur Fehlersuche -geschrieben, falls @code{debug-level} echt positiv ist. - -@item @code{debug-level} (Vorgabe: @code{0}) -Eine ganze Zahl, die den Detailgrad der Ausgabe zur Fehlersuche -angibt. Größere Zahlen bewirken eine ausführlichere Ausgabe. - -@item @code{caches} (Vorgabe: @var{%nscd-default-caches}) -Liste der @code{<nscd-cache>}-Objekte, die repräsentieren, was alles -zwischengespeichert werden soll; siehe unten. - -@end table -@end deftp - -@deftp {Datentyp} nscd-cache -Ein Datentyp, der eine Zwischenspeicher-Datenbank von nscd mitsamt ihren -Parametern definiert. - -@table @asis - -@item @code{Datenbank} -Dies ist ein Symbol, was den Namen der Datenbank repräsentiert, die -zwischengespeichert werden soll. Gültige Werte sind @code{passwd}, -@code{group}, @code{hosts} und @code{services}, womit jeweils die -entsprechende NSS-Datenbank bezeichnet wird (@pxref{NSS Basics,,, libc, The -GNU C Library Reference Manual}). - -@item @code{positive-time-to-live} -@itemx @code{negative-time-to-live} (Vorgabe: @code{20}) -Eine Zahl, die für die Anzahl an Sekunden steht, die ein erfolgreiches -(positives) oder erfolgloses (negatives) Nachschlageresultat im -Zwischenspeicher verbleibt. - -@item @code{check-files?} (Vorgabe: @code{#t}) -Ob auf Änderungen an den der @var{database} entsprechenden Dateien reagiert -werden soll. - -Wenn @var{database} zum Beispiel @code{hosts} ist, wird, wenn dieses Feld -gesetzt ist, nscd Änderungen an @file{/etc/hosts} beobachten und -berücksichtigen. - -@item @code{persistent?} (Vorgabe: @code{#t}) -Ob der Zwischenspeicher dauerhaft auf der Platte gespeichert werden soll. - -@item @code{shared?} (Vorgabe: @code{#t}) -Ob der Zwischenspeicher zwischen den Nutzern geteilt werden soll. - -@item @code{max-database-size} (Vorgabe: 32@tie{}MiB) -Die Maximalgröße des Datenbank-Zwischenspeichers in Bytes. - -@c XXX: 'suggested-size' and 'auto-propagate?' seem to be expert -@c settings, so leave them out. - -@end table -@end deftp - -@defvr {Scheme-Variable} %nscd-default-caches -Liste von @code{<nscd-cache>}-Objekten, die von der vorgegebenen -@code{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. -@end defvr - -@anchor{syslog-configuration-type} -@cindex syslog -@cindex Protokollierung -@deftp {Datentyp} syslog-configuration -Dieser Datentyp repräsentiert die Konfiguration des syslog-Daemons. - -@table @asis -@item @code{syslogd} (Vorgabe: @code{#~(string-append #$inetutils "/libexec/syslogd")}) -Welcher Syslog-Daemon benutzt werden soll. - -@item @code{config-file} (Vorgabe: @code{%default-syslog.conf}) -Die zu benutzende syslog-Konfigurationsdatei. - -@end table -@end deftp - -@anchor{syslog-service} -@cindex syslog -@deffn {Scheme-Prozedur} syslog-service @var{Konfiguration} -Liefert einen Dienst, der einen syslog-Daemon entsprechend der -@var{Konfiguration} ausführt. - -@xref{syslogd invocation,,, inetutils, GNU Inetutils}, für weitere -Informationen über die Syntax der Konfiguration. -@end deffn - -@defvr {Scheme-Variable} guix-service-type -Dies ist der Typ für den Dienst, der den Erstellungs-Daemon -@command{guix-daemon} ausführt (@pxref{Aufruf des guix-daemon}). Als Wert muss -ein @code{guix-configuration}-Verbundsobjekt verwendet werden, wie unten -beschrieben. -@end defvr - -@anchor{guix-configuration-type} -@deftp {Datentyp} guix-configuration -Dieser Datentyp repräsentiert die Konfiguration des Erstellungs-Daemons von -Guix. Siehe @xref{Aufruf des guix-daemon} für weitere Informationen. - -@table @asis -@item @code{guix} (Vorgabe: @var{guix}) -Das zu verwendende Guix-Paket. - -@item @code{build-group} (Vorgabe: @code{"guixbuild"}) -Der Name der Gruppe, zu der die Erstellungs-Benutzerkonten gehören. - -@item @code{build-accounts} (Vorgabe: @code{10}) -Die Anzahl zu erzeugender Erstellungs-Benutzerkonten. - -@item @code{authorize-key?} (Vorgabe: @code{#t}) -@cindex Substitute, deren Autorisierung -Whether to authorize the substitute keys listed in -@code{authorized-keys}---by default that of @code{@value{SUBSTITUTE-SERVER}} -(@pxref{Substitute}). - -@vindex %default-authorized-guix-keys -@item @code{authorized-keys} (Vorgabe: @var{%default-authorized-guix-keys}) -The list of authorized key files for archive imports, as a list of -string-valued gexps (@pxref{Aufruf von guix archive}). By default, it -contains that of @code{@value{SUBSTITUTE-SERVER}} (@pxref{Substitute}). - -@item @code{use-substitutes?} (Vorgabe: @code{#t}) -Ob Substitute benutzt werden sollen. - -@item @code{substitute-urls} (Vorgabe: @var{%default-substitute-urls}) -Die Liste der URLs, auf denen nach Substituten gesucht wird, wenn nicht -anders angegeben. - -@item @code{max-silent-time} (Vorgabe: @code{0}) -@itemx @code{timeout} (Vorgabe: @code{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. - -@item @code{log-compression} (Vorgabe: @code{'bzip2}) -Die für Erstellungsprotokolle zu benutzende Kompressionsmethode — entweder -@code{gzip}, @code{bzip2} oder @code{none}. - -@item @code{extra-options} (Vorgabe: @code{'()}) -Eine Liste zusätzlicher Befehlszeilenoptionen zu @command{guix-daemon}. - -@item @code{log-file} (Vorgabe: @code{"/var/log/guix-daemon.log"}) -Die Datei, in die die Standardausgabe und die Standardfehlerausgabe von -@command{guix-daemon} geschrieben werden. - -@item @code{http-proxy} (Vorgabe: @code{#f}) -Der für das Herunterladen von Ableitungen mit fester Ausgabe und von -Substituten zu verwendende HTTP-Proxy. - -@item @code{tmpdir} (Vorgabe: @code{#f}) -Ein Verzeichnispfad, der angibt, wo @command{guix-daemon} seine Erstellungen -durchführt. - -@end table -@end deftp - -@deffn {Scheme-Prozedur} udev-service [#:udev @var{eudev} #:rules @code{'()}] -Führt @var{udev} aus, was zur Laufzeit Gerätedateien ins Verzeichnis -@file{/dev} einfügt. udev-Regeln können über die @var{rules}-Variable als -eine Liste von Dateien übergeben werden. Die Prozeduren @var{udev-rule} und -@var{file->udev-rule} aus @code{(gnu services base)} vereinfachen die -Erstellung einer solchen Regeldatei. -@end deffn - -@deffn {Scheme-Prozedur} udev-rule [@var{Dateiname} @var{Inhalt}] -Liefert eine udev-Regeldatei mit dem angegebenen @var{Dateiname}n, in der -die vom Literal @var{Inhalt} definierten Regeln stehen. - -Im folgenden Beispiel wird eine Regel für ein USB-Gerät definiert und in der -Datei @file{90-usb-ding.rules} gespeichert. Mit der Regel wird ein Skript -ausgeführt, sobald ein USB-Gerät mit der angegebenen Produktkennung erkannt -wird. - -@example -(define %beispiel-udev-rule - (udev-rule - "90-usb-ding.rules" - (string-append "ACTION==\"add\", SUBSYSTEM==\"usb\", " - "ATTR@{product@}==\"Beispiel\", " - "RUN+=\"/pfad/zum/skript\""))) -@end example - -The @command{herd rules udev} command, as root, returns the name of the -directory containing all the active udev rules. -@end deffn - -Hier zeigen wir, wie man den vorgegebenen @var{udev-service} um sie -erweitern kann. - -@example -(operating-system - ;; @dots{} - (services - (modify-services %desktop-services - (udev-service-type config => - (udev-configuration (inherit config) - (rules (append (udev-configuration-rules config) - (list %beispiel-udev-rule)))))))) -@end example - -@deffn {Scheme-Prozedur} file->udev-rule [@var{Dateiname} @var{Datei}] -Liefert eine udev-Datei mit dem angegebenen @var{Dateiname}n, in der alle in -der @var{Datei}, einem dateiartigen Objekt, definierten Regeln stehen. - -Folgendes Beispiel stellt dar, wie wir eine bestehende Regeldatei verwenden -können. - -@example -(use-modules (guix download) ;für url-fetch - (guix packages) ;für origin - ;; @dots{}) - -(define %android-udev-rules - (file->udev-rule - "51-android-udev.rules" - (let ((version "20170910")) - (origin - (method url-fetch) - (uri (string-append "https://raw.githubusercontent.com/M0Rf30/" - "android-udev-rules/" version "/51-android.rules")) - (sha256 - (base32 "0lmmagpyb6xsq6zcr2w1cyx9qmjqmajkvrdbhjx32gqf1d9is003")))))) -@end example -@end deffn - -Zusätzlich können Guix-Paketdefinitionen unter den @var{rules} aufgeführt -werden, um die udev-Regeln um diejenigen Definitionen zu ergänzen, die im -Unterverzeichnis @file{lib/udev/rules.d} des jeweiligen Pakets aufgeführt -sind. Statt des bisherigen Beispiels zu @var{file->udev-rule} hätten wir -also auch das Paket @var{android-udev-rules} benutzen können, das in Guix im -Modul @code{(gnu packages android)} vorhanden ist. - -Das folgende Beispiel zeit, wie dieses Paket @var{android-udev-rules} -benutzt werden kann, damit das »Android-Tool« @command{adb} Geräte erkennen -kann, ohne dafür Administratorrechte vorauszusetzen. Man sieht hier auch, -wie die Benutzergruppe @code{adbusers} erstellt werden kann, die existieren -muss, damit die im Paket @var{android-udev-rules} definierten Regeln richtig -funktionieren. Um so eine Benutzergruppe zu erzeugen, müssen wir sie sowohl -unter den @var{supplementary-groups} unserer @var{user-account}-Deklaration -aufführen, als auch sie im @var{groups}-Feld des -@var{operating-system}-Verbundsobjekts aufführen. - -@example -(use-modules (gnu packages android) ;für android-udev-rules - (gnu system shadow) ;für user-group - ;; @dots{}) - -(operating-system - ;; @dots{} - (users (cons (user-acount - ;; @dots{} - (supplementary-groups - '("adbusers" ;für adb - "wheel" "netdev" "audio" "video")) - ;; @dots{}))) - - (groups (cons (user-group (system? #t) (name "adbusers")) - %base-groups)) - - ;; @dots{} - - (services - (modify-services %desktop-services - (udev-service-type - config => - (udev-configuration (inherit config) - (rules (cons android-udev-rules - (udev-configuration-rules config)))))))) -@end example - -@defvr {Scheme-Variable} urandom-seed-service-type -Etwas Entropie in der Datei @var{%random-seed-file} aufsparen, die als -Startwert (als sogenannter »Seed«) für @file{/dev/urandom} dienen kann, -nachdem das System neu gestartet wurde. Es wird auch versucht, -@file{/dev/urandom} beim Hochfahren mit Werten aus @file{/dev/hwrng} zu -starten, falls @file{/dev/hwrng} existiert und lesbar ist. -@end defvr - -@defvr {Scheme-Variable} %random-seed-file -Der Name der Datei, in der einige zufällige Bytes vom -@var{urandom-seed-service} abgespeichert werden, um sie nach einem Neustart -von dort als Startwert für @file{/dev/urandom} auslesen zu können. Als -Vorgabe wird @file{/var/lib/random-seed} verwendet. -@end defvr - -@cindex Keymap -@cindex Tastatur -@deffn {Scheme-Prozedur} console-keymap-service @var{Dateien} ... -@cindex Tastaturbelegung -Liefert einen Dienst, um Tastenzuordnungen (»Keymaps«) für die Konsole aus -den @var{Dateien} laden zu können. Dazu wird der Befehl @command{loadkeys} -aufgerufen. Wahrscheinlich möchten Sie irgendeine vorgefertigte Keymap -laden, etwa so: - -@example -(console-keymap-service "dvorak") -@end example - -Oder um zum Beispiel eine schwedische Tastaturbelegung zu bekommen, könnten -Sie die folgenden Keymaps kombinieren müssen: -@example -(console-keymap-service "se-lat6" "se-fi-lat6") -@end example - -Sie können alternativ auch den oder die vollständigen Dateinamen Ihrer -Keymap(s) angeben. Siehe @code{man loadkeys} für Details. - -@end deffn - -@cindex Maus -@cindex gpm -@defvr {Scheme-Variable} gpm-service-type -Dieser Typ wird für den Dienst verwendet, der GPM ausführt, den -»@dfn{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 @code{gpm-configuration} sein -(siehe unten). Dieser Dienst gehört @emph{nicht} zu den -@var{%base-services}. -@end defvr - -@deftp {Datentyp} gpm-configuration -Repräsentiert die Konfiguration von GPM. - -@table @asis -@item @code{options} (Vorgabe: @code{%default-gpm-options}) -Befehlszeilenoptionen, die an @command{gpm} übergeben werden. Die -vorgegebenen Optionen weisen @command{gpm} an, auf Maus-Ereignisse auf der -Datei @file{/dev/input/mice} zu lauschen. Siehe @xref{Command Line,,, gpm, -gpm manual} für weitere Informationen. - -@item @code{gpm} (Vorgabe: @code{gpm}) -Das GPM-Paket, was benutzt werden soll. - -@end table -@end deftp - -@anchor{guix-publish-service-type} -@deffn {Scheme-Variable} guix-publish-service-type -Dies ist der Diensttyp für @command{guix publish} (@pxref{Aufruf von guix publish}). Sein Wert muss ein @code{guix-publish-configuration}-Objekt sein, -wie im Folgenden beschrieben. - -Hierbei wird angenommen, dass @file{/etc/guix} bereits ein mit @command{guix -archive --generate-key} erzeugtes Schlüsselpaar zum Signieren enthält -(@pxref{Aufruf von guix archive}). Falls nicht, wird der Dienst beim Starten -fehlschlagen. -@end deffn - -@deftp {Datentyp} guix-publish-configuration -Der Datentyp, der die Konfiguration des »@code{guix publish}«-Dienstes -repräsentiert. - -@table @asis -@item @code{guix} (Vorgabe: @code{guix}) -Das zu verwendende Guix-Paket. - -@item @code{port} (Vorgabe: @code{80}) -Der TCP-Port, auf dem auf Verbindungen gelauscht werden soll. - -@item @code{host} (Vorgabe: @code{"localhost"}) -Unter welcher Rechneradresse (welchem »Host«, also welcher -Netzwerkschnittstelle) auf Verbindungen gelauscht wird. Benutzen Sie -@code{"0.0.0.0"}, wenn auf allen verfügbaren Netzwerkschnittstellen -gelauscht werden soll. - -@item @code{compression-level} (Vorgabe: @code{3}) -Die gzip-Kompressionsstufe, mit der Substitute komprimiert werden -sollen. Benutzen Sie @code{0}, um Kompression völlig abzuschalten, und -@code{9} für das höchste Kompressionsverhältnis, zu Lasten von zusätzlicher -Prozessorauslastung. - -@item @code{nar-path} (Vorgabe: @code{"nar"}) -Der URL-Pfad, unter dem »Nars« zum Herunterladen angeboten werden. Siehe -@xref{Aufruf von guix publish, @code{--nar-path}}, für Details. - -@item @code{cache} (Vorgabe: @code{#f}) -Wenn dies @code{#f} ist, werden Archive nicht zwischengespeichert, sondern -erst bei einer Anfrage erzeugt. Andernfalls sollte dies der Name eines -Verzeichnisses sein — z.B. @code{"/var/cache/guix/publish"} —, in das -@command{guix publish} fertige Archive und Metadaten zwischenspeichern -soll. Siehe @xref{Aufruf von guix publish, @option{--cache}}, für weitere -Informationen über die jeweiligen Vor- und Nachteile. - -@item @code{workers} (Vorgabe: @code{#f}) -Ist dies eine ganze Zahl, gibt es die Anzahl der Worker-Threads an, die zum -Zwischenspeichern benutzt werden; ist es @code{#f}, werden so viele benutzt, -wie es Prozessoren gibt. Siehe @xref{Aufruf von guix publish, -@option{--workers}}, für mehr Informationen. - -@item @code{ttl} (Vorgabe: @code{#f}) -Wenn dies eine ganze Zahl ist, bezeichnet sie die @dfn{Time-to-live} als die -Anzahl der Sekunden, die heruntergeladene veröffentlichte Archive -zwischengespeichert werden dürfen. Siehe @xref{Aufruf von guix publish, -@option{--ttl}}, für mehr Informationen. -@end table -@end deftp - -@anchor{rngd-service} -@deffn {Scheme-Prozedur} rngd-service [#:rng-tools @var{rng-tools}] @ - [#:device "/dev/hwrng"] Liefert einen Dienst, der das -@command{rngd}-Programm aus den @var{rng-tools} benutzt, um das mit -@var{device} bezeichnete Gerät zum Entropie-Pool des Kernels -hinzuzufügen. Dieser Dienst wird fehlschlagen, falls das mit @var{device} -bezeichnete Gerät nicht existiert. -@end deffn - -@anchor{pam-limits-service} -@cindex Sitzungs-Limits -@cindex ulimit -@cindex Priorität -@cindex Echtzeit -@cindex jackd -@deffn {Scheme-Prozedur} pam-limits-service [#:limits @code{'()}] - -Liefert einen Dienst, der eine Konfigurationsdatei für das -@uref{http://linux-pam.org/Linux-PAM-html/sag-pam_limits.html, -@code{pam_limits}-Modul} installiert. Diese Prozedur nimmt optional eine -Liste von @code{pam-limits-entry}-Werten entgegen, die benutzt werden -können, um @code{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 @code{realtime}-Gruppe. - -@example -(pam-limits-service - (list - (pam-limits-entry "@@realtime" 'both 'rtprio 99) - (pam-limits-entry "@@realtime" 'both 'memlock 'unlimited))) -@end example - -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. -@end deffn - -@node Geplante Auftragsausführung -@subsection Geplante Auftragsausführung - -@cindex cron -@cindex mcron -@cindex scheduling jobs -The @code{(gnu services mcron)} module provides an interface to -GNU@tie{}mcron, a daemon to run jobs at scheduled times (@pxref{Top,,, -mcron, GNU@tie{}mcron}). GNU@tie{}mcron is similar to the traditional Unix -@command{cron} daemon; the main difference is that it is implemented 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 -@command{updatedb} (@pxref{Invoking updatedb,,, find, Finding Files}) and -the @command{guix gc} commands (@pxref{Aufruf von guix gc}) daily, as well as -the @command{mkid} command on behalf of an unprivileged user (@pxref{mkid -invocation,,, idutils, ID Database Utilities}). It uses gexps to introduce -job definitions that are passed to mcron (@pxref{G-Ausdrücke}). - -@lisp -(use-modules (guix) (gnu) (gnu services mcron)) -(use-package-modules base idutils) - -(define updatedb-job - ;; Run 'updatedb' at 3AM every day. Here we write the - ;; job's action as a Scheme procedure. - #~(job '(next-hour '(3)) - (lambda () - (execl (string-append #$findutils "/bin/updatedb") - "updatedb" - "--prunepaths=/tmp /var/tmp /gnu/store")))) - -(define garbage-collector-job - ;; Collect garbage 5 minutes after midnight every day. - ;; The job's action is a shell command. - #~(job "5 0 * * *" ;Vixie cron syntax - "guix gc -F 1G")) - -(define idutils-job - ;; Update the index database as user "charlie" at 12:15PM - ;; and 19:15PM. This runs from the user's home directory. - #~(job '(next-minute-from (next-hour '(12 19)) '(15)) - (string-append #$idutils "/bin/mkid src") - #:user "charlie")) - -(operating-system - ;; @dots{} - (services (cons (service mcron-service-type - (mcron-configuration - (jobs (list garbage-collector-job - updatedb-job - idutils-job)))) - %base-services))) -@end lisp - -@xref{Guile Syntax, mcron job specifications,, mcron, GNU@tie{}mcron}, for -more information on mcron job specifications. Below is the reference of the -mcron service. - -On a running system, you can use the @code{schedule} action of the service -to visualize the mcron jobs that will be executed next: - -@example -# herd schedule mcron -@end example - -@noindent -The example above lists the next five tasks that will be executed, but you -can also specify the number of tasks to display: - -@example -# herd schedule mcron 10 -@end example - -@defvr {Scheme Variable} mcron-service-type -This is the type of the @code{mcron} service, whose value is an -@code{mcron-configuration} object. - -This service type can be the target of a service extension that provides it -additional job specifications (@pxref{Dienstkompositionen}). In other -words, it is possible to define services that provide additional mcron jobs -to run. -@end defvr - -@deftp {Data Type} mcron-configuration -Data type representing the configuration of mcron. - -@table @asis -@item @code{mcron} (default: @var{mcron}) -The mcron package to use. - -@item @code{jobs} -This is a list of gexps (@pxref{G-Ausdrücke}), where each gexp corresponds -to an mcron job specification (@pxref{Syntax, mcron job specifications,, -mcron, GNU@tie{}mcron}). -@end table -@end deftp - - -@node Log-Rotation -@subsection Log-Rotation - -@cindex rottlog -@cindex log rotation -@cindex Protokollierung -Log files such as those found in @file{/var/log} tend to grow endlessly, so -it's a good idea to @dfn{rotate} them once in a while---i.e., archive their -contents in separate files, possibly compressed. The @code{(gnu services -admin)} module provides an interface to GNU@tie{}Rot[t]log, a log rotation -tool (@pxref{Top,,, rottlog, 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. - -@lisp -(use-modules (guix) (gnu)) -(use-service-modules admin mcron) -(use-package-modules base idutils) - -(operating-system - ;; @dots{} - (services (cons (service rottlog-service-type) - %base-services))) -@end lisp - -@defvr {Scheme Variable} rottlog-service-type -This is the type of the Rottlog service, whose value is a -@code{rottlog-configuration} object. - -Other services can extend this one with new @code{log-rotation} objects (see -below), thereby augmenting the set of files to be rotated. - -This service type can define mcron jobs (@pxref{Geplante Auftragsausführung}) to -run the rottlog service. -@end defvr - -@deftp {Data Type} rottlog-configuration -Data type representing the configuration of rottlog. - -@table @asis -@item @code{rottlog} (default: @code{rottlog}) -The Rottlog package to use. - -@item @code{rc-file} (default: @code{(file-append rottlog "/etc/rc")}) -The Rottlog configuration file to use (@pxref{Mandatory RC Variables,,, -rottlog, GNU Rot[t]log Manual}). - -@item @code{rotations} (default: @code{%default-rotations}) -A list of @code{log-rotation} objects as defined below. - -@item @code{jobs} -This is a list of gexps where each gexp corresponds to an mcron job -specification (@pxref{Geplante Auftragsausführung}). -@end table -@end deftp - -@deftp {Data Type} log-rotation -Data type representing the rotation of a group of log files. - -Taking an example from the Rottlog manual (@pxref{Period Related File -Examples,,, rottlog, GNU Rot[t]log Manual}), a log rotation might be defined -like this: - -@example -(log-rotation - (frequency 'daily) - (files '("/var/log/apache/*")) - (options '("storedir apache-archives" - "rotate 6" - "notifempty" - "nocompress"))) -@end example - -The list of fields is as follows: - -@table @asis -@item @code{frequency} (default: @code{'weekly}) -The log rotation frequency, a symbol. - -@item @code{files} -The list of files or file glob patterns to rotate. - -@item @code{options} (default: @code{'()}) -The list of rottlog options for this rotation (@pxref{Configuration -parameters,,, rottlog, GNU Rot[t]lg Manual}). - -@item @code{post-rotate} (default: @code{#f}) -Either @code{#f} or a gexp to execute once the rotation has completed. -@end table -@end deftp - -@defvr {Scheme Variable} %default-rotations -Specifies weekly rotation of @var{%rotated-files} and a couple of other -files. -@end defvr - -@defvr {Scheme Variable} %rotated-files -The list of syslog-controlled files to be rotated. By default it is: -@code{'("/var/log/messages" "/var/log/secure")}. -@end defvr - -@node Netzwerkdienste -@subsection Netzwerkdienste - -The @code{(gnu services networking)} module provides services to configure -the network interface. - -@cindex DHCP, networking service -@defvr {Scheme Variable} dhcp-client-service-type -This is the type of services that run @var{dhcp}, a Dynamic Host -Configuration Protocol (DHCP) client, on all the non-loopback network -interfaces. Its value is the DHCP client package to use, @code{isc-dhcp} by -default. -@end defvr - -@deffn {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 @code{<dhcpd-configuration>}. For example: - -@example -(service dhcpd-service-type - (dhcpd-configuration - (config-file (local-file "my-dhcpd.conf")) - (interfaces '("enp0s25")))) -@end example -@end deffn - -@deftp {Data Type} dhcpd-configuration -@table @asis -@item @code{package} (default: @code{isc-dhcp}) -The package that provides the DHCP daemon. This package is expected to -provide the daemon at @file{sbin/dhcpd} relative to its output directory. -The default package is the @uref{http://www.isc.org/products/DHCP, ISC's -DHCP server}. -@item @code{config-file} (default: @code{#f}) -The configuration file to use. This is required. It will be passed to -@code{dhcpd} via its @code{-cf} option. This may be any ``file-like'' -object (@pxref{G-Ausdrücke, file-like objects}). See @code{man -dhcpd.conf} for details on the configuration file syntax. -@item @code{version} (default: @code{"4"}) -The DHCP version to use. The ISC DHCP server supports the values ``4'', -``6'', and ``4o6''. These correspond to the @code{dhcpd} program options -@code{-4}, @code{-6}, and @code{-4o6}. See @code{man dhcpd} for details. -@item @code{run-directory} (default: @code{"/run/dhcpd"}) -The run directory to use. At service activation time, this directory will -be created if it does not exist. -@item @code{pid-file} (default: @code{"/run/dhcpd/dhcpd.pid"}) -The PID file to use. This corresponds to the @code{-pf} option of -@code{dhcpd}. See @code{man dhcpd} for details. -@item @code{interfaces} (default: @code{'()}) -The names of the network interfaces on which dhcpd should listen for -broadcasts. If this list is not empty, then its elements (which must be -strings) will be appended to the @code{dhcpd} invocation when starting the -daemon. It may not be necessary to explicitly specify any interfaces here; -see @code{man dhcpd} for details. -@end table -@end deftp - -@defvr {Scheme Variable} static-networking-service-type -@c TODO Document <static-networking> data structures. -This is the type for statically-configured network interfaces. -@end defvr - -@deffn {Scheme Procedure} static-networking-service @var{interface} @var{ip} @ - [#:netmask #f] [#:gateway #f] [#:name-servers @code{'()}] @ [#:requirement -@code{'(udev)}] Return a service that starts @var{interface} with address -@var{ip}. If @var{netmask} is true, use it as the network mask. If -@var{gateway} is true, it must be a string specifying the default network -gateway. @var{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 -@code{static-networking-service-type} with additional network interfaces to -handle. - -Zum Beispiel: - -@example -(static-networking-service "eno1" "192.168.1.82" - #:gateway "192.168.1.2" - #:name-servers '("192.168.1.2")) -@end example -@end deffn - -@cindex wicd -@cindex WLAN -@cindex WiFi -@cindex network management -@deffn {Scheme Procedure} wicd-service [#:wicd @var{wicd}] -Return a service that runs @url{https://launchpad.net/wicd,Wicd}, a network -management daemon that aims to simplify wired and wireless networking. - -This service adds the @var{wicd} package to the global profile, providing -several commands to interact with the daemon and configure networking: -@command{wicd-client}, a graphical user interface, and the -@command{wicd-cli} and @command{wicd-curses} user interfaces. -@end deffn - -@cindex ModemManager - -@defvr {Scheme Variable} modem-manager-service-type -This is the service type for the -@uref{https://wiki.gnome.org/Projects/ModemManager, ModemManager} -service. The value for this service type is a -@code{modem-manager-configuration} record. - -This service is part of @code{%desktop-services} (@pxref{Desktop-Dienste}). -@end defvr - -@deftp {Data Type} modem-manager-configuration -Repräsentiert die Konfiguration vom ModemManager. - -@table @asis -@item @code{modem-manager} (Vorgabe: @code{modem-manager}) -Das ModemManager-Paket, was benutzt werden soll. - -@end table -@end deftp - -@cindex NetworkManager - -@defvr {Scheme Variable} network-manager-service-type -This is the service type for the -@uref{https://wiki.gnome.org/Projects/NetworkManager, NetworkManager} -service. The value for this service type is a -@code{network-manager-configuration} record. - -This service is part of @code{%desktop-services} (@pxref{Desktop-Dienste}). -@end defvr - -@deftp {Data Type} network-manager-configuration -Data type representing the configuration of NetworkManager. - -@table @asis -@item @code{network-manager} (default: @code{network-manager}) -The NetworkManager package to use. - -@item @code{dns} (default: @code{"default"}) -Processing mode for DNS, which affects how NetworkManager uses the -@code{resolv.conf} configuration file. - -@table @samp -@item default -NetworkManager will update @code{resolv.conf} to reflect the nameservers -provided by currently active connections. - -@item dnsmasq -NetworkManager will run @code{dnsmasq} as a local caching nameserver, using -a "split DNS" configuration if you are connected to a VPN, and then update -@code{resolv.conf} to point to the local nameserver. - -@item none -NetworkManager will not modify @code{resolv.conf}. -@end table - -@item @code{vpn-plugins} (default: @code{'()}) -This is the list of available plugins for virtual private networks (VPNs). -An example of this is the @code{network-manager-openvpn} package, which -allows NetworkManager to manage VPNs @i{via} OpenVPN. - -@end table -@end deftp - -@cindex Connman -@deffn {Scheme Variable} connman-service-type -This is the service type to run @url{https://01.org/connman,Connman}, a -network connection manager. - -Its value must be an @code{connman-configuration} record as in this example: - -@example -(service connman-service-type - (connman-configuration - (disable-vpn? #t))) -@end example - -See below for details about @code{connman-configuration}. -@end deffn - -@deftp {Data Type} connman-configuration -Data Type representing the configuration of connman. - -@table @asis -@item @code{connman} (default: @var{connman}) -The connman package to use. - -@item @code{disable-vpn?} (default: @code{#f}) -When true, disable connman's vpn plugin. -@end table -@end deftp - -@cindex WPA Supplicant -@defvr {Scheme Variable} wpa-supplicant-service-type -This is the service type to run @url{https://w1.fi/wpa_supplicant/,WPA -supplicant}, an authentication daemon required to authenticate against -encrypted WiFi or ethernet networks. -@end defvr - -@deftp {Data Type} wpa-supplicant-configuration -Repräsentiert die Konfiguration des WPA-Supplikanten. - -Sie hat folgende Parameter: - -@table @asis -@item @code{wpa-supplicant} (Vorgabe: @code{wpa-supplicant}) -Das WPA-Supplicant-Paket, was benutzt werden soll. - -@item @code{dbus?} (Vorgabe: @code{#t}) -Whether to listen for requests on D-Bus. - -@item @code{pid-file} (Vorgabe: @code{"/var/run/wpa_supplicant.pid"}) -Wo die PID-Datei abgelegt wird. - -@item @code{interface} (Vorgabe: @code{#f}) -If this is set, it must specify the name of a network interface that WPA -supplicant will control. - -@item @code{config-file} (default: @code{#f}) -Optionale Konfigurationsdatei. - -@item @code{extra-options} (Vorgabe: @code{'()}) -List of additional command-line arguments to pass to the daemon. -@end table -@end deftp - -@cindex iptables -@defvr {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. - -@lisp -(service iptables-service-type - (iptables-configuration - (ipv4-rules (plain-file "iptables.rules" "*filter -:INPUT ACCEPT -:FORWARD ACCEPT -:OUTPUT ACCEPT --A INPUT -p tcp --dport 22 -j ACCEPT --A INPUT -j REJECT --reject-with icmp-port-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 -")))) -@end lisp -@end defvr - -@deftp {Datentyp} iptables-configuration -Repräsentiert die iptables-Konfiguration. - -@table @asis -@item @code{iptables} (Vorgabe: @code{iptables}) -The iptables package that provides @code{iptables-restore} and -@code{ip6tables-restore}. -@item @code{ipv4-rules} (Vorgabe: @code{%iptables-accept-all-rules}) -The iptables rules to use. It will be passed to @code{iptables-restore}. -This may be any ``file-like'' object (@pxref{G-Ausdrücke, file-like -objects}). -@item @code{ipv6-rules} (Vorgabe: @code{%iptables-accept-all-rules}) -The ip6tables rules to use. It will be passed to @code{ip6tables-restore}. -This may be any ``file-like'' object (@pxref{G-Ausdrücke, file-like -objects}). -@end table -@end deftp - -@cindex NTP (Network Time Protocol), Dienst -@cindex real time clock -@defvr {Scheme Variable} ntp-service-type -This is the type of the service running the @uref{http://www.ntp.org, -Network Time Protocol (NTP)} daemon, @command{ntpd}. The daemon will keep -the system clock synchronized with that of the specified NTP servers. - -The value of this service is an @code{ntpd-configuration} object, as -described below. -@end defvr - -@deftp {Datentyp} ntp-configuration -Der Datentyp für die Dienstkonfiguration des NTP-Dienstes. - -@table @asis -@item @code{servers} (Vorgabe: @code{%ntp-servers}) -This is the list of servers (host names) with which @command{ntpd} will be -synchronized. - -@item @code{allow-large-adjustment?} (default: @code{#f}) -This determines whether @command{ntpd} is allowed to make an initial -adjustment of more than 1,000 seconds. - -@item @code{ntp} (Vorgabe: @code{ntp}) -Das NTP-Paket, was benutzt werden soll. -@end table -@end deftp - -@defvr {Scheme Variable} %ntp-servers -List of host names used as the default NTP servers. These are servers of -the @uref{https://www.ntppool.org/en/, NTP Pool Project}. -@end defvr - -@cindex OpenNTPD -@deffn {Scheme Procedure} openntpd-service-type -Run the @command{ntpd}, the Network Time Protocol (NTP) daemon, as -implemented by @uref{http://www.openntpd.org, OpenNTPD}. The daemon will -keep the system clock synchronized with that of the given servers. - -@example -(service - openntpd-service-type - (openntpd-configuration - (listen-on '("127.0.0.1" "::1")) - (sensor '("udcf0 correction 70000")) - (constraint-from '("www.gnu.org")) - (constraints-from '("https://www.google.com/")) - (allow-large-adjustment? #t))) - -@end example -@end deffn - -@deftp {Data Type} openntpd-configuration -@table @asis -@item @code{openntpd} (default: @code{(file-append openntpd "/sbin/ntpd")}) -The openntpd executable to use. -@item @code{listen-on} (default: @code{'("127.0.0.1" "::1")}) -A list of local IP addresses or hostnames the ntpd daemon should listen on. -@item @code{query-from} (default: @code{'()}) -A list of local IP address the ntpd daemon should use for outgoing queries. -@item @code{sensor} (default: @code{'()}) -Specify a list of timedelta sensor devices ntpd should use. @code{ntpd} -will listen to each sensor that acutally exists and ignore non-existant -ones. See @uref{https://man.openbsd.org/ntpd.conf, upstream documentation} -for more information. -@item @code{server} (default: @var{%ntp-servers}) -Specify a list of IP addresses or hostnames of NTP servers to synchronize -to. -@item @code{servers} (default: @code{'()}) -Specify a list of IP addresses or hostnames of NTP pools to synchronize to. -@item @code{constraint-from} (default: @code{'()}) -@code{ntpd} can be configured to query the ‘Date’ from trusted HTTPS 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. -@item @code{constraints-from} (default: @code{'()}) -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, @code{ntpd} will calculate a median constraint from -all of them. -@item @code{allow-large-adjustment?} (default: @code{#f}) -Determines if @code{ntpd} is allowed to make an initial adjustment of more -than 180 seconds. -@end table -@end deftp - -@cindex inetd -@deffn {Scheme variable} inetd-service-type -This service runs the @command{inetd} (@pxref{inetd invocation,,, inetutils, -GNU Inetutils}) daemon. @command{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 @code{inetd-configuration} object. The -following example configures the @command{inetd} daemon to provide the -built-in @command{echo} service, as well as an smtp service which forwards -smtp traffic over ssh to a server @code{smtp-server} behind a gateway -@code{hostname}: - -@example -(service - inetd-service-type - (inetd-configuration - (entries (list - (inetd-entry - (name "echo") - (socket-type 'stream) - (protocol "tcp") - (wait? #f) - (user "root")) - (inetd-entry - (node "127.0.0.1") - (name "smtp") - (socket-type 'stream) - (protocol "tcp") - (wait? #f) - (user "root") - (program (file-append openssh "/bin/ssh")) - (arguments - '("ssh" "-qT" "-i" "/path/to/ssh_key" - "-W" "smtp-server:25" "user@@hostname"))))) -@end example - -See below for more details about @code{inetd-configuration}. -@end deffn - -@deftp {Data Type} inetd-configuration -Data type representing the configuration of @command{inetd}. - -@table @asis -@item @code{program} (default: @code{(file-append inetutils "/libexec/inetd")}) -The @command{inetd} executable to use. - -@item @code{entries} (default: @code{'()}) -A list of @command{inetd} service entries. Each entry should be created by -the @code{inetd-entry} constructor. -@end table -@end deftp - -@deftp {Data Type} inetd-entry -Data type representing an entry in the @command{inetd} configuration. Each -entry corresponds to a socket where @command{inetd} will listen for -requests. - -@table @asis -@item @code{node} (Vorgabe: @code{#f}) -Optional string, a comma-separated list of local addresses @command{inetd} -should use when listening for this service. @xref{Configuration file,,, -inetutils, GNU Inetutils} for a complete description of all options. -@item @code{name} -A string, the name must correspond to an entry in @code{/etc/services}. -@item @code{socket-type} -One of @code{'stream}, @code{'dgram}, @code{'raw}, @code{'rdm} or -@code{'seqpacket}. -@item @code{protocol} -A string, must correspond to an entry in @code{/etc/protocols}. -@item @code{wait?} (Vorgabe: @code{#t}) -Whether @command{inetd} should wait for the server to exit before listening -to new service requests. -@item @code{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.@: @code{"user"}, @code{"user:group"} or -@code{"user.group"}. -@item @code{program} (default: @code{"internal"}) -The server program which will serve the requests, or @code{"internal"} if -@command{inetd} should use a built-in service. -@item @code{arguments} (Vorgabe: @code{'()}) -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 @command{inetd}'s internal services, this entry must be -@code{'()} or @code{'("internal")}. -@end table - -@xref{Configuration file,,, inetutils, GNU Inetutils} for a more detailed -discussion of each configuration field. -@end deftp - -@cindex Tor -@defvr {Scheme Variable} tor-service-type -This is the type for a service that runs the @uref{https://torproject.org, -Tor} anonymous networking daemon. The service is configured using a -@code{<tor-configuration>} record. By default, the Tor daemon runs as the -@code{tor} unprivileged user, which is a member of the @code{tor} group. - -@end defvr - -@deftp {Datentyp} tor-configuration -@table @asis -@item @code{tor} (Vorgabe: @code{tor}) -The package that provides the Tor daemon. This package is expected to -provide the daemon at @file{bin/tor} relative to its output directory. The -default package is the @uref{https://www.torproject.org, Tor Project's} -implementation. - -@item @code{config-file} (Vorgabe: @code{(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 -@code{tor} via its @code{-f} option. This may be any ``file-like'' object -(@pxref{G-Ausdrücke, file-like objects}). See @code{man tor} for details -on the configuration file syntax. - -@item @code{hidden-services} (Vorgabe: @code{'()}) -The list of @code{<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 @code{<hidden-service>} records using the -@code{tor-hidden-service} procedure described below. - -@item @code{socks-socket-type} (Vorgabe: @code{'tcp}) -The default socket type that Tor should use for its SOCKS socket. This must -be either @code{'tcp} or @code{'unix}. If it is @code{'tcp}, then by -default Tor will listen on TCP port 9050 on the loopback interface (i.e., -localhost). If it is @code{'unix}, then Tor will listen on the UNIX domain -socket @file{/var/run/tor/socks-sock}, which will be made writable by -members of the @code{tor} group. - -If you want to customize the SOCKS socket in more detail, leave -@code{socks-socket-type} at its default value of @code{'tcp} and use -@code{config-file} to override the default by providing your own -@code{SocksPort} option. -@end table -@end deftp - -@cindex hidden service -@deffn {Scheme Procedure} tor-hidden-service @var{name} @var{mapping} -Define a new Tor @dfn{hidden service} called @var{name} and implementing -@var{mapping}. @var{mapping} is a list of port/host tuples, such as: - -@example - '((22 "127.0.0.1:22") - (80 "127.0.0.1:8080")) -@end example - -In this example, port 22 of the hidden service is mapped to local port 22, -and port 80 is mapped to local port 8080. - -This creates a @file{/var/lib/tor/hidden-services/@var{name}} directory, -where the @file{hostname} file contains the @code{.onion} host name for the -hidden service. - -See @uref{https://www.torproject.org/docs/tor-hidden-service.html.en, the -Tor project's documentation} for more information. -@end deffn - -The @code{(gnu services rsync)} module provides the following services: - -You might want an rsync daemon if you have files that you want available so -anyone (or just yourself) can download existing files or upload new files. - -@deffn {Scheme Variable} rsync-service-type -This is the type for the @uref{https://rsync.samba.org, rsync} rsync daemon, -@command{rsync-configuration} record as in this example: - -@example -(service rsync-service-type) -@end example - -See below for details about @code{rsync-configuration}. -@end deffn - -@deftp {Data Type} rsync-configuration -Data type representing the configuration for @code{rsync-service}. - -@table @asis -@item @code{package} (default: @var{rsync}) -@code{rsync} package to use. - -@item @code{port-number} (default: @code{873}) -TCP port on which @command{rsync} listens for incoming connections. If port -is less than @code{1024} @command{rsync} needs to be started as the -@code{root} user and group. - -@item @code{pid-file} (default: @code{"/var/run/rsyncd/rsyncd.pid"}) -Name of the file where @command{rsync} writes its PID. - -@item @code{lock-file} (default: @code{"/var/run/rsyncd/rsyncd.lock"}) -Name of the file where @command{rsync} writes its lock file. - -@item @code{log-file} (default: @code{"/var/log/rsyncd.log"}) -Name of the file where @command{rsync} writes its log file. - -@item @code{use-chroot?} (default: @var{#t}) -Whether to use chroot for @command{rsync} shared directory. - -@item @code{share-path} (default: @file{/srv/rsync}) -Location of the @command{rsync} shared directory. - -@item @code{share-comment} (default: @code{"Rsync share"}) -Comment of the @command{rsync} shared directory. - -@item @code{read-only?} (default: @var{#f}) -Read-write permissions to shared directory. - -@item @code{timeout} (default: @code{300}) -I/O timeout in seconds. - -@item @code{user} (default: @var{"root"}) -Owner of the @code{rsync} process. - -@item @code{group} (default: @var{"root"}) -Group of the @code{rsync} process. - -@item @code{uid} (default: @var{"rsyncd"}) -User name or user ID that file transfers to and from that module should take -place as when the daemon was run as @code{root}. - -@item @code{gid} (default: @var{"rsyncd"}) -Group name or group ID that will be used when accessing the module. - -@end table -@end deftp - -Furthermore, @code{(gnu services ssh)} provides the following services. -@cindex SSH -@cindex SSH server - -@deffn {Scheme Procedure} lsh-service [#:host-key "/etc/lsh/host-key"] @ - [#:daemonic? #t] [#:interfaces '()] [#:port-number 22] @ -[#:allow-empty-passwords? #f] [#:root-login? #f] @ [#:syslog-output? #t] -[#:x11-forwarding? #t] @ [#:tcp/ip-forwarding? #t] -[#:password-authentication? #t] @ [#:public-key-authentication? #t] -[#:initialize? #t] Run the @command{lshd} program from @var{lsh} to listen -on port @var{port-number}. @var{host-key} must designate a file containing -the host key, and readable only by root. - -When @var{daemonic?} is true, @command{lshd} will detach from the -controlling terminal and log its output to syslogd, unless one sets -@var{syslog-output?} to false. Obviously, it also makes lsh-service depend -on existence of syslogd service. When @var{pid-file?} is true, -@command{lshd} writes its PID to the file called @var{pid-file}. - -When @var{initialize?} is true, automatically create the seed and host key -upon service activation if they do not exist yet. This may take long and -require interaction. - -When @var{initialize?} is false, it is up to the user to initialize the -randomness generator (@pxref{lsh-make-seed,,, lsh, LSH Manual}), and to -create a key pair with the private key stored in file @var{host-key} -(@pxref{lshd basics,,, lsh, LSH Manual}). - -When @var{interfaces} is empty, lshd listens for connections on all the -network interfaces; otherwise, @var{interfaces} must be a list of host names -or addresses. - -@var{allow-empty-passwords?} specifies whether to accept log-ins with empty -passwords, and @var{root-login?} specifies whether to accept log-ins as -root. - -The other options should be self-descriptive. -@end deffn - -@cindex SSH -@cindex SSH server -@deffn {Scheme Variable} openssh-service-type -This is the type for the @uref{http://www.openssh.org, OpenSSH} secure shell -daemon, @command{sshd}. Its value must be an @code{openssh-configuration} -record as in this example: - -@example -(service openssh-service-type - (openssh-configuration - (x11-forwarding? #t) - (permit-root-login 'without-password) - (authorized-keys - `(("alice" ,(local-file "alice.pub")) - ("bob" ,(local-file "bob.pub")))))) -@end example - -See below for details about @code{openssh-configuration}. - -This service can be extended with extra authorized keys, as in this example: - -@example -(service-extension openssh-service-type - (const `(("charlie" - ,(local-file "charlie.pub"))))) -@end example -@end deffn - -@deftp {Data Type} openssh-configuration -This is the configuration record for OpenSSH's @command{sshd}. - -@table @asis -@item @code{pid-file} (default: @code{"/var/run/sshd.pid"}) -Name of the file where @command{sshd} writes its PID. - -@item @code{port-number} (default: @code{22}) -TCP port on which @command{sshd} listens for incoming connections. - -@item @code{permit-root-login} (default: @code{#f}) -This field determines whether and when to allow logins as root. If -@code{#f}, root logins are disallowed; if @code{#t}, they are allowed. If -it's the symbol @code{'without-password}, then root logins are permitted but -not with password-based authentication. - -@item @code{allow-empty-passwords?} (default: @code{#f}) -When true, users with empty passwords may log in. When false, they may not. - -@item @code{password-authentication?} (default: @code{#t}) -When true, users may log in with their password. When false, they have -other authentication methods. - -@item @code{public-key-authentication?} (default: @code{#t}) -When true, users may log in using public key authentication. When false, -users have to use other authentication method. - -Authorized public keys are stored in @file{~/.ssh/authorized_keys}. This is -used only by protocol version 2. - -@item @code{x11-forwarding?} (default: @code{#f}) -When true, forwarding of X11 graphical client connections is enabled---in -other words, @command{ssh} options @option{-X} and @option{-Y} will work. - -@item @code{allow-agent-forwarding?} (Vorgabe: @code{#t}) -Whether to allow agent forwarding. - -@item @code{allow-tcp-forwarding?} (Vorgabe: @code{#t}) -Whether to allow TCP forwarding. - -@item @code{gateway-ports?} (Vorgabe: @code{#f}) -Whether to allow gateway ports. - -@item @code{challenge-response-authentication?} (default: @code{#f}) -Specifies whether challenge response authentication is allowed (e.g.@: via -PAM). - -@item @code{use-pam?} (default: @code{#t}) -Enables the Pluggable Authentication Module interface. If set to @code{#t}, -this will enable PAM authentication using -@code{challenge-response-authentication?} and -@code{password-authentication?}, in addition to PAM account and session -module processing for all authentication types. - -Because PAM challenge response authentication usually serves an equivalent -role to password authentication, you should disable either -@code{challenge-response-authentication?} or -@code{password-authentication?}. - -@item @code{print-last-log?} (default: @code{#t}) -Specifies whether @command{sshd} should print the date and time of the last -user login when a user logs in interactively. - -@item @code{subsystems} (default: @code{'(("sftp" "internal-sftp"))}) -Configures external subsystems (e.g.@: file transfer daemon). - -This is a list of two-element lists, each of which containing the subsystem -name and a command (with optional arguments) to execute upon subsystem -request. - -The command @command{internal-sftp} implements an in-process SFTP server. -Alternately, one can specify the @command{sftp-server} command: -@example -(service openssh-service-type - (openssh-configuration - (subsystems - `(("sftp" ,(file-append openssh "/libexec/sftp-server")))))) -@end example - -@item @code{accepted-environment} (default: @code{'()}) -List of strings describing which environment variables may be exported. - -Each string gets on its own line. See the @code{AcceptEnv} option in -@code{man sshd_config}. - -This example allows ssh-clients to export the @code{COLORTERM} variable. 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. - -@example -(service openssh-service-type - (openssh-configuration - (accepted-environment '("COLORTERM")))) -@end example - -@item @code{authorized-keys} (default: @code{'()}) -@cindex authorized keys, SSH -@cindex SSH authorized keys -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: - -@example -(openssh-configuration - (authorized-keys - `(("rekado" ,(local-file "rekado.pub")) - ("chris" ,(local-file "chris.pub")) - ("root" ,(local-file "rekado.pub") ,(local-file "chris.pub"))))) -@end example - -@noindent -registers the specified public keys for user accounts @code{rekado}, -@code{chris}, and @code{root}. - -Additional authorized keys can be specified @i{via} -@code{service-extension}. - -Note that this does @emph{not} interfere with the use of -@file{~/.ssh/authorized_keys}. - -@item @code{log-level} (Vorgabe: @code{'info}) -This is a symbol specifying the logging level: @code{quiet}, @code{fatal}, -@code{error}, @code{info}, @code{verbose}, @code{debug}, etc. See the man -page for @file{sshd_config} for the full list of level names. - -@item @code{extra-content} (Vorgabe: @code{""}) -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: - -@example -(openssh-configuration - (extra-content "\ -Match Address 192.168.0.1 - PermitRootLogin yes")) -@end example - -@end table -@end deftp - -@deffn {Scheme Procedure} dropbear-service [@var{config}] -Run the @uref{https://matt.ucc.asn.au/dropbear/dropbear.html,Dropbear SSH -daemon} with the given @var{config}, a @code{<dropbear-configuration>} -object. - -For example, to specify a Dropbear service listening on port 1234, add this -call to the operating system's @code{services} field: - -@example -(dropbear-service (dropbear-configuration - (port-number 1234))) -@end example -@end deffn - -@deftp {Data Type} dropbear-configuration -This data type represents the configuration of a Dropbear SSH daemon. - -@table @asis -@item @code{dropbear} (default: @var{dropbear}) -The Dropbear package to use. - -@item @code{port-number} (default: 22) -The TCP port where the daemon waits for incoming connections. - -@item @code{syslog-output?} (default: @code{#t}) -Whether to enable syslog output. - -@item @code{pid-file} (default: @code{"/var/run/dropbear.pid"}) -File name of the daemon's PID file. - -@item @code{root-login?} (default: @code{#f}) -Whether to allow @code{root} logins. - -@item @code{allow-empty-passwords?} (default: @code{#f}) -Whether to allow empty passwords. - -@item @code{password-authentication?} (default: @code{#t}) -Whether to enable password-based authentication. -@end table -@end deftp - -@defvr {Scheme Variable} %facebook-host-aliases -This variable contains a string for use in @file{/etc/hosts} (@pxref{Host -Names,,, libc, 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., -@code{www.facebook.com}---to the local host---@code{127.0.0.1} or its IPv6 -equivalent, @code{::1}. - -This variable is typically used in the @code{hosts-file} field of an -@code{operating-system} declaration (@pxref{»operating-system«-Referenz, -@file{/etc/hosts}}): - -@example -(use-modules (gnu) (guix)) - -(operating-system - (host-name "mymachine") - ;; ... - (hosts-file - ;; Create a /etc/hosts file with aliases for "localhost" - ;; and "mymachine", as well as for Facebook servers. - (plain-file "hosts" - (string-append (local-host-aliases host-name) - %facebook-host-aliases)))) -@end example - -This mechanism can prevent programs running locally, such as Web browsers, -from accessing Facebook. -@end defvr - -The @code{(gnu services avahi)} provides the following definition. - -@defvr {Scheme Variable} avahi-service-type -This is the service that runs @command{avahi-daemon}, a system-wide -mDNS/DNS-SD responder that allows for service discovery and -``zero-configuration'' host name lookups (see @uref{http://avahi.org/}). -Its value must be a @code{zero-configuration} record---see below. - -This service extends the name service cache daemon (nscd) so that it can -resolve @code{.local} host names using -@uref{http://0pointer.de/lennart/projects/nss-mdns/, nss-mdns}. @xref{Name Service Switch}, for information on host name resolution. - -Additionally, add the @var{avahi} package to the system profile so that -commands such as @command{avahi-browse} are directly usable. -@end defvr - -@deftp {Data Type} avahi-configuration -Data type representation the configuration for Avahi. - -@table @asis - -@item @code{host-name} (default: @code{#f}) -If different from @code{#f}, use that as the host name to publish for this -machine; otherwise, use the machine's actual host name. - -@item @code{publish?} (default: @code{#t}) -When true, allow host names and services to be published (broadcast) over -the network. - -@item @code{publish-workstation?} (default: @code{#t}) -When true, @command{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: - -@example -avahi-browse _workstation._tcp -@end example - -@item @code{wide-area?} (default: @code{#f}) -When true, DNS-SD over unicast DNS is enabled. - -@item @code{ipv4?} (default: @code{#t}) -@itemx @code{ipv6?} (default: @code{#t}) -These fields determine whether to use IPv4/IPv6 sockets. - -@item @code{domains-to-browse} (default: @code{'()}) -This is a list of domains to browse. -@end table -@end deftp - -@deffn {Scheme Variable} openvswitch-service-type -This is the type of the @uref{http://www.openvswitch.org, Open vSwitch} -service, whose value should be an @code{openvswitch-configuration} object. -@end deffn - -@deftp {Data Type} openvswitch-configuration -Data type representing the configuration of Open vSwitch, a multilayer -virtual switch which is designed to enable massive network automation -through programmatic extension. - -@table @asis -@item @code{package} (default: @var{openvswitch}) -Package object of the Open vSwitch. - -@end table -@end deftp - -@node X Window -@subsection X Window - -@cindex X11 -@cindex X Window System -@cindex login manager -Support for the X Window graphical display system---specifically Xorg---is -provided by the @code{(gnu services xorg)} module. Note that there is no -@code{xorg-service} procedure. Instead, the X server is started by the -@dfn{login manager}, by default SLiM. - -@cindex window manager -To use X11, you must install at least one @dfn{window manager}---for example -the @code{windowmaker} or @code{openbox} packages---preferably by adding it -to the @code{packages} field of your operating system definition -(@pxref{»operating-system«-Referenz, system-wide packages}). - -@defvr {Scheme Variable} slim-service-type -This is the type for the SLiM graphical login manager for X11. - -@cindex session types (X11) -@cindex X11 session types -SLiM looks for @dfn{session types} described by the @file{.desktop} files in -@file{/run/current-system/profile/share/xsessions} and allows users to -choose a session from the log-in screen using @kbd{F1}. Packages such as -@code{xfce}, @code{sawfish}, and @code{ratpoison} provide @file{.desktop} -files; adding them to the system-wide set of packages automatically makes -them available at the log-in screen. - -In addition, @file{~/.xsession} files are honored. When available, -@file{~/.xsession} must be an executable that starts a window manager and/or -other X clients. -@end defvr - -@deftp {Data Type} slim-configuration -Data type representing the configuration of @code{slim-service-type}. - -@table @asis -@item @code{allow-empty-passwords?} (Vorgabe: @code{#t}) -Whether to allow logins with empty passwords. - -@item @code{auto-login?} (default: @code{#f}) -@itemx @code{default-user} (default: @code{""}) -When @code{auto-login?} is false, SLiM presents a log-in screen. - -When @code{auto-login?} is true, SLiM logs in directly as -@code{default-user}. - -@item @code{theme} (default: @code{%default-slim-theme}) -@itemx @code{theme-name} (default: @code{%default-slim-theme-name}) -The graphical theme to use and its name. - -@item @code{auto-login-session} (default: @code{#f}) -If true, this must be the name of the executable to start as the default -session---e.g., @code{(file-append windowmaker "/bin/windowmaker")}. - -If false, a session described by one of the available @file{.desktop} files -in @code{/run/current-system/profile} and @code{~/.guix-profile} will be -used. - -@quotation Anmerkung -You must install at least one window manager in the system profile or in -your user profile. Failing to do that, if @code{auto-login-session} is -false, you will be unable to log in. -@end quotation - -@item @code{startx} (default: @code{(xorg-start-command)}) -The command used to start the X11 graphical server. - -@item @code{xauth} (default: @code{xauth}) -The XAuth package to use. - -@item @code{shepherd} (default: @code{shepherd}) -The Shepherd package used when invoking @command{halt} and @command{reboot}. - -@item @code{sessreg} (default: @code{sessreg}) -The sessreg package used in order to register the session. - -@item @code{slim} (default: @code{slim}) -The SLiM package to use. -@end table -@end deftp - -@defvr {Scheme Variable} %default-theme -@defvrx {Scheme Variable} %default-theme-name -The default SLiM theme and its name. -@end defvr - - -@deftp {Data Type} sddm-configuration -This is the data type representing the sddm service configuration. - -@table @asis -@item @code{display-server} (default: "x11") -Select display server to use for the greeter. Valid values are "x11" or -"wayland". - -@item @code{numlock} (default: "on") -Valid values are "on", "off" or "none". - -@item @code{halt-command} (default @code{#~(string-apppend #$shepherd "/sbin/halt")}) -Command to run when halting. - -@item @code{reboot-command} (default @code{#~(string-append #$shepherd "/sbin/reboot")}) -Command to run when rebooting. - -@item @code{theme} (default "maldives") -Theme to use. Default themes provided by SDDM are "elarun" or "maldives". - -@item @code{themes-directory} (default "/run/current-system/profile/share/sddm/themes") -Directory to look for themes. - -@item @code{faces-directory} (default "/run/current-system/profile/share/sddm/faces") -Directory to look for faces. - -@item @code{default-path} (default "/run/current-system/profile/bin") -Default PATH to use. - -@item @code{minimum-uid} (default 1000) -Minimum UID to display in SDDM. - -@item @code{maximum-uid} (default 2000) -Maximum UID to display in SDDM - -@item @code{remember-last-user?} (default #t) -Remember last user. - -@item @code{remember-last-session?} (default #t) -Remember last session. - -@item @code{hide-users} (default "") -Usernames to hide from SDDM greeter. - -@item @code{hide-shells} (default @code{#~(string-append #$shadow "/sbin/nologin")}) -Users with shells listed will be hidden from the SDDM greeter. - -@item @code{session-command} (default @code{#~(string-append #$sddm "/share/sddm/scripts/wayland-session")}) -Script to run before starting a wayland session. - -@item @code{sessions-directory} (default "/run/current-system/profile/share/wayland-sessions") -Directory to look for desktop files starting wayland sessions. - -@item @code{xorg-server-path} (default @code{xorg-start-command}) -Path to xorg-server. - -@item @code{xauth-path} (default @code{#~(string-append #$xauth "/bin/xauth")}) -Path to xauth. - -@item @code{xephyr-path} (default @code{#~(string-append #$xorg-server "/bin/Xephyr")}) -Path to Xephyr. - -@item @code{xdisplay-start} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xsetup")}) -Script to run after starting xorg-server. - -@item @code{xdisplay-stop} (default @code{#~(string-append #$sddm "/share/sddm/scripts/Xstop")}) -Script to run before stopping xorg-server. - -@item @code{xsession-command} (Vorgabe: @code{xinitrc}) -Script to run before starting a X session. - -@item @code{xsessions-directory} (default: "/run/current-system/profile/share/xsessions") -Directory to look for desktop files starting X sessions. - -@item @code{minimum-vt} (default: 7) -Minimum VT to use. - -@item @code{xserver-arguments} (default "-nolisten tcp") -Arguments to pass to xorg-server. - -@item @code{auto-login-user} (default "") -User to use for auto-login. - -@item @code{auto-login-session} (default "") -Desktop file to use for auto-login. - -@item @code{relogin?} (default #f) -Relogin after logout. - -@end table -@end deftp - -@cindex login manager -@cindex X11 login -@deffn {Scheme Procedure} sddm-service config -Return a service that spawns the SDDM graphical login manager for config of -type @code{<sddm-configuration>}. - -@example - (sddm-service (sddm-configuration - (auto-login-user "Alice") - (auto-login-session "xfce.desktop"))) -@end example -@end deffn - -@deffn {Scheme Procedure} xorg-start-command [#:guile] @ - [#:modules %default-xorg-modules] @ [#:fonts %default-xorg-fonts] @ -[#:configuration-file (xorg-configuration-file @dots{})] @ [#:xorg-server -@var{xorg-server}] [#:xserver-arguments '("-nolisten" "tcp")] Return a -@code{startx} script in which @var{modules}, a list of X module packages, -and @var{fonts}, a list of X font directories, are available. See -@code{xorg-wrapper} for more details on the arguments. The result should be -used in place of @code{startx}. - -Usually the X server is started by a login manager. -@end deffn - -@cindex @code{-listen tcp}, for X11. -This procedure is useful to override command line options for the X server, -such as having it listen to over TCP: - -@example -(operating-system - ... - (services - (modify-services %desktop-services - (slim-service-type config => - (slim-configuration - (inherit config) - (startx (xorg-start-command - #:xserver-arguments '("-listen" "tcp")))))))) -@end example - -@deffn {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. - -@var{modules} must be a list of @dfn{module packages} loaded by the Xorg -server---e.g., @code{xf86-video-vesa}, @code{xf86-input-keyboard}, and so -on. @var{fonts} must be a list of font directories to add to the server's -@dfn{font path}. - -@var{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., @code{("modesetting" "vesa")}. - -Likewise, when @var{resolutions} is the empty list, Xorg chooses an -appropriate screen resolution; otherwise, it must be a list of -resolutions---e.g., @code{((1024 768) (640 480))}. - -Last, @var{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. - -@cindex Keymap -@cindex Tastaturbelegung -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: - -@example -(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))))))))) -@end example - -The @code{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 @code{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 -@code{xkb_variant} line can be omitted to select the default variant. -@end deffn - -@deffn {Scheme Procedure} screen-locker-service @var{package} [@var{program}] -Add @var{package}, a package for a screen locker or screen saver whose -command is @var{program}, to the set of setuid programs and add a PAM entry -for it. For example: - -@lisp -(screen-locker-service xlockmore "xlock") -@end lisp - -makes the good ol' XlockMore usable. -@end deffn - - -@node Druckdienste -@subsection Druckdienste - -@cindex printer support with CUPS -The @code{(gnu services cups)} module provides a Guix service definition for -the CUPS printing service. To add printer support to a Guix system, add a -@code{cups-service} to the operating system definition: - -@deffn {Scheme Variable} cups-service-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: -@example -(service cups-service-type) -@end example -@end deffn - -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 @url{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 @i{via} the @code{escpr} package and for HP printers -@i{via} the @code{hplip-minimal} package. You can do that directly, like -this (you need to use the @code{(gnu packages cups)} module): - -@example -(service cups-service-type - (cups-configuration - (web-interface? #t) - (extensions - (list cups-filters escpr hplip-minimal)))) -@end example - -Note: If you wish to use the Qt5 based GUI which comes with the hplip -package then it is suggested that you install the @code{hplip} package, -either in your OS configuration file or as your user. - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{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 -@code{cupsd.conf} file that you want to port over from some other system; -see the end for more details. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services cups). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@c needed. However if the change you want to make to this documentation -@c can be done in an automated way, it's probably easier to change -@c (generate-documentation) than to make it below and have to deal with -@c the churn as CUPS updates. - - -Available @code{cups-configuration} fields are: - -@deftypevr {@code{cups-configuration} parameter} package cups -The CUPS package. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} package-list extensions -Drivers and other extensions to the CUPS package. -@end deftypevr - -@deftypevr {@code{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 @code{files-configuration} fields are: - -@deftypevr {@code{files-configuration} parameter} log-location access-log -Defines the access log filename. Specifying a blank filename disables -access log generation. The value @code{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 @code{syslog} causes log entries to be sent to the system log daemon. -The server name may be included in filenames using the string @code{%s}, as -in @code{/var/log/cups/%s-access_log}. - -Defaults to @samp{"/var/log/cups/access_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name cache-dir -Where CUPS should cache data. - -Defaults to @samp{"/var/cache/cups"}. -@end deftypevr - -@deftypevr {@code{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 @samp{"0640"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} log-location error-log -Defines the error log filename. Specifying a blank filename disables access -log generation. The value @code{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 -@code{syslog} causes log entries to be sent to the system log daemon. The -server name may be included in filenames using the string @code{%s}, as in -@code{/var/log/cups/%s-error_log}. - -Defaults to @samp{"/var/log/cups/error_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string fatal-errors -Specifies which errors are fatal, causing the scheduler to exit. The kind -strings are: - -@table @code -@item none -No errors are fatal. - -@item all -All of the errors below are fatal. - -@item browse -Browsing initialization errors are fatal, for example failed connections to -the DNS-SD daemon. - -@item config -Configuration file syntax errors are fatal. - -@item listen -Listen or Port errors are fatal, except for IPv6 failures on the loopback or -@code{any} addresses. - -@item log -Log file creation or write errors are fatal. - -@item permissions -Bad startup file permissions are fatal, for example shared TLS certificate -and key files with world-read permissions. -@end table - -Defaults to @samp{"all -browse"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} boolean file-device? -Specifies whether the file pseudo-device can be used for new printer -queues. The URI @uref{file:///dev/null} is always allowed. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string group -Specifies the group name or ID that will be used when executing external -programs. - -Defaults to @samp{"lp"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string log-file-perm -Specifies the permissions for all log files that the scheduler writes. - -Defaults to @samp{"0644"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} log-location page-log -Defines the page log filename. Specifying a blank filename disables access -log generation. The value @code{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 -@code{syslog} causes log entries to be sent to the system log daemon. The -server name may be included in filenames using the string @code{%s}, as in -@code{/var/log/cups/%s-page_log}. - -Defaults to @samp{"/var/log/cups/page_log"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string remote-root -Specifies the username that is associated with unauthenticated accesses by -clients claiming to be the root user. The default is @code{remroot}. - -Defaults to @samp{"remroot"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name request-root -Specifies the directory that contains print jobs and other HTTP request -data. - -Defaults to @samp{"/var/spool/cups"}. -@end deftypevr - -@deftypevr {@code{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 @code{relaxed} -or @code{strict}. This directive is currently only used/supported on macOS. - -Defaults to @samp{strict}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name server-keychain -Specifies the location of TLS certificates and private keys. CUPS will look -for public and private keys in this directory: a @code{.crt} files for -PEM-encoded certificates and corresponding @code{.key} files for PEM-encoded -private keys. - -Defaults to @samp{"/etc/cups/ssl"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name server-root -Specifies the directory containing the server configuration files. - -Defaults to @samp{"/etc/cups"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} boolean sync-on-close? -Specifies whether the scheduler calls fsync(2) after writing configuration -or state files. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} space-separated-string-list system-group -Specifies the group(s) to use for @code{@@SYSTEM} group authentication. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} file-name temp-dir -Specifies the directory where temporary files are stored. - -Defaults to @samp{"/var/spool/cups/tmp"}. -@end deftypevr - -@deftypevr {@code{files-configuration} parameter} string user -Specifies the user name or ID that is used when running external programs. - -Defaults to @samp{"lp"}. -@end deftypevr -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} access-log-level access-log-level -Specifies the logging level for the AccessLog file. The @code{config} level -logs when printers and classes are added, deleted, or modified and when -configuration files are accessed or updated. The @code{actions} level logs -when print jobs are submitted, held, released, modified, or canceled, and -any of the conditions for @code{config}. The @code{all} level logs all -requests. - -Defaults to @samp{actions}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean auto-purge-jobs? -Specifies whether to purge job history data automatically when it is no -longer required for quotas. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} browse-local-protocols browse-local-protocols -Specifies which protocols to use for local printer sharing. - -Defaults to @samp{dnssd}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean browse-web-if? -Specifies whether the CUPS web interface is advertised. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean browsing? -Specifies whether shared printers are advertised. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string 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 @samp{""}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean classify-override? -Specifies whether users may override the classification (cover page) of -individual print jobs using the @code{job-sheets} option. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} default-auth-type default-auth-type -Specifies the default type of authentication to use. - -Defaults to @samp{Basic}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} default-encryption default-encryption -Specifies whether encryption will be used for authenticated requests. - -Defaults to @samp{Required}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-language -Specifies the default language to use for text and web content. - -Defaults to @samp{"en"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-paper-size -Specifies the default paper size for new print queues. @samp{"Auto"} uses a -locale-specific default, while @samp{"None"} specifies there is no default -paper size. Specific size names are typically @samp{"Letter"} or -@samp{"A4"}. - -Defaults to @samp{"Auto"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string default-policy -Specifies the default access policy to use. - -Defaults to @samp{"default"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean default-shared? -Specifies whether local printers are shared by default. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer dirty-clean-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 @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} error-policy error-policy -Specifies what to do when an error occurs. Possible values are -@code{abort-job}, which will discard the failed print job; @code{retry-job}, -which will retry the job at a later time; @code{retry-this-job}, which -retries the failed job immediately; and @code{stop-printer}, which stops the -printer. - -Defaults to @samp{stop-printer}. -@end deftypevr - -@deftypevr {@code{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 @samp{0}. -@end deftypevr - -@deftypevr {@code{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 @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} host-name-lookups host-name-lookups -Specifies whether to do reverse lookups on connecting clients. The -@code{double} setting causes @code{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 @code{#t} or -@code{double} if absolutely required. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{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 @samp{30}. -@end deftypevr - -@deftypevr {@code{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 @code{retry-job} or @code{retry-current-job}. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{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 @code{retry-job} or @code{retry-current-job}. - -Defaults to @samp{5}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean keep-alive? -Specifies whether to support HTTP keep-alive connections. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer keep-alive-timeout -Specifies how long an idle client connection remains open, in seconds. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer limit-request-body -Specifies the maximum size of print files, IPP requests, and HTML form -data. A limit of 0 disables the limit check. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} multiline-string-list listen -Listens on the specified interfaces for connections. Valid values are of -the form @var{address}:@var{port}, where @var{address} is either an IPv6 -address enclosed in brackets, an IPv4 address, or @code{*} 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. -@end deftypevr - -@deftypevr {@code{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 @samp{128}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} location-access-control-list location-access-controls -Specifies a set of additional access controls. - -Available @code{location-access-controls} fields are: - -@deftypevr {@code{location-access-controls} parameter} file-name path -Specifies the URI path to which the access control applies. -@end deftypevr - -@deftypevr {@code{location-access-controls} parameter} access-control-list access-controls -Access controls for all access to this path, in the same format as the -@code{access-controls} of @code{operation-access-control}. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{location-access-controls} parameter} method-access-control-list method-access-controls -Access controls for method-specific access to this path. - -Defaults to @samp{()}. - -Available @code{method-access-controls} fields are: - -@deftypevr {@code{method-access-controls} parameter} boolean reverse? -If @code{#t}, apply access controls to all methods except the listed -methods. Otherwise apply to only the listed methods. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{method-access-controls} parameter} method-list methods -Methods to which this access control applies. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{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 @samp{()}. -@end deftypevr -@end deftypevr -@end deftypevr - -@deftypevr {@code{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 @samp{100}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} log-level log-level -Specifies the level of logging for the ErrorLog file. The value @code{none} -stops all logging while @code{debug2} logs everything. - -Defaults to @samp{info}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} log-time-format log-time-format -Specifies the format of the date and time in the log files. The value -@code{standard} logs whole seconds while @code{usecs} logs microseconds. - -Defaults to @samp{standard}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-clients -Specifies the maximum number of simultaneous clients that are allowed by the -scheduler. - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{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 @samp{100}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-copies -Specifies the maximum number of copies that a user can print of each job. - -Defaults to @samp{9999}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer max-hold-time -Specifies the maximum time a job may remain in the @code{indefinite} hold -state before it is canceled. A value of 0 disables cancellation of held -jobs. - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{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 @samp{500}. -@end deftypevr - -@deftypevr {@code{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 @samp{0}. -@end deftypevr - -@deftypevr {@code{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 @samp{0}. -@end deftypevr - -@deftypevr {@code{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 @samp{10800}. -@end deftypevr - -@deftypevr {@code{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 @samp{1048576}. -@end deftypevr - -@deftypevr {@code{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 @samp{300}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string page-log-format -Specifies the format of PageLog lines. Sequences beginning with percent -(@samp{%}) characters are replaced with the corresponding information, while -all other characters are copied literally. The following percent sequences -are recognized: - -@table @samp -@item %% -insert a single percent character - -@item %@{name@} -insert the value of the specified IPP attribute - -@item %C -insert the number of copies for the current page - -@item %P -insert the current page number - -@item %T -insert the current date and time in common log format - -@item %j -insert the job ID - -@item %p -insert the printer name - -@item %u -insert the username -@end table - -A value of the empty string disables page logging. The string @code{%p %u -%j %T %P %C %@{job-billing@} %@{job-originating-host-name@} %@{job-name@} -%@{media@} %@{sides@}} creates a page log with the standard items. - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} environment-variables environment-variables -Passes the specified environment variable(s) to child processes; a list of -strings. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} policy-configuration-list policies -Specifies named access control policies. - -Available @code{policy-configuration} fields are: - -@deftypevr {@code{policy-configuration} parameter} string name -Name of the policy. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string job-private-access -Specifies an access list for a job's private values. @code{@@ACL} maps to -the printer's requesting-user-name-allowed or requesting-user-name-denied -values. @code{@@OWNER} maps to the job's owner. @code{@@SYSTEM} maps to -the groups listed for the @code{system-group} field of the -@code{files-config} configuration, which is reified into the -@code{cups-files.conf(5)} file. Other possible elements of the access list -include specific user names, and @code{@@@var{group}} to indicate members of -a specific group. The access list may also be simply @code{all} or -@code{default}. - -Defaults to @samp{"@@OWNER @@SYSTEM"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string job-private-values -Specifies the list of job values to make private, or @code{all}, -@code{default}, or @code{none}. - -Defaults to @samp{"job-name job-originating-host-name -job-originating-user-name phone"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string subscription-private-access -Specifies an access list for a subscription's private values. @code{@@ACL} -maps to the printer's requesting-user-name-allowed or -requesting-user-name-denied values. @code{@@OWNER} maps to the job's -owner. @code{@@SYSTEM} maps to the groups listed for the -@code{system-group} field of the @code{files-config} configuration, which is -reified into the @code{cups-files.conf(5)} file. Other possible elements of -the access list include specific user names, and @code{@@@var{group}} to -indicate members of a specific group. The access list may also be simply -@code{all} or @code{default}. - -Defaults to @samp{"@@OWNER @@SYSTEM"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} string subscription-private-values -Specifies the list of job values to make private, or @code{all}, -@code{default}, or @code{none}. - -Defaults to @samp{"notify-events notify-pull-method notify-recipient-uri -notify-subscriber-user-name notify-user-data"}. -@end deftypevr - -@deftypevr {@code{policy-configuration} parameter} operation-access-control-list access-controls -Access control by IPP operation. - -Defaults to @samp{()}. -@end deftypevr -@end deftypevr - -@deftypevr {@code{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 @samp{86400}. -@end deftypevr - -@deftypevr {@code{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 @code{#t}, the job history is -preserved until the MaxJobs limit is reached. - -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer reload-timeout -Specifies the amount of time to wait for job completion before restarting -the scheduler. - -Defaults to @samp{30}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string rip-cache -Specifies the maximum amount of memory to use when converting documents into -bitmaps for a printer. - -Defaults to @samp{"128m"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string server-admin -Specifies the email address of the server administrator. - -Defaults to @samp{"root@@localhost.localdomain"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} host-name-list-or-* server-alias -The ServerAlias directive is used for HTTP Host header validation when -clients connect to the scheduler from external interfaces. Using the -special name @code{*} 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 @code{*}. - -Defaults to @samp{*}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string server-name -Specifies the fully-qualified host name of the server. - -Defaults to @samp{"localhost"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} server-tokens server-tokens -Specifies what information is included in the Server header of HTTP -responses. @code{None} disables the Server header. @code{ProductOnly} -reports @code{CUPS}. @code{Major} reports @code{CUPS 2}. @code{Minor} -reports @code{CUPS 2.0}. @code{Minimal} reports @code{CUPS 2.0.0}. -@code{OS} reports @code{CUPS 2.0.0 (@var{uname})} where @var{uname} is the -output of the @code{uname} command. @code{Full} reports @code{CUPS 2.0.0 -(@var{uname}) IPP/2.0}. - -Defaults to @samp{Minimal}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} string set-env -Set the specified environment variable to be passed to child processes. - -Defaults to @samp{"variable value"}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} multiline-string-list ssl-listen -Listens on the specified interfaces for encrypted connections. Valid values -are of the form @var{address}:@var{port}, where @var{address} is either an -IPv6 address enclosed in brackets, an IPv4 address, or @code{*} to indicate -all addresses. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{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 @code{AllowRC4} -option enables the 128-bit RC4 cipher suites, which are required for some -older clients that do not implement newer ones. The @code{AllowSSL3} option -enables SSL v3.0, which is required for some older clients that do not -support TLS v1.0. - -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean strict-conformance? -Specifies whether the scheduler requires clients to strictly adhere to the -IPP specifications. - -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} non-negative-integer timeout -Specifies the HTTP request timeout, in seconds. - -Defaults to @samp{300}. - -@end deftypevr - -@deftypevr {@code{cups-configuration} parameter} boolean web-interface? -Specifies whether the web interface is enabled. - -Defaults to @samp{#f}. -@end deftypevr - -At this point you're probably thinking ``oh dear, Guix manual, I like you -but you can stop already with the configuration options''. Indeed. -However, one more point: it could be that you have an existing -@code{cupsd.conf} that you want to use. In that case, you can pass an -@code{opaque-cups-configuration} as the configuration of a -@code{cups-service-type}. - -Available @code{opaque-cups-configuration} fields are: - -@deftypevr {@code{opaque-cups-configuration} parameter} package cups -The CUPS package. -@end deftypevr - -@deftypevr {@code{opaque-cups-configuration} parameter} string cupsd.conf -The contents of the @code{cupsd.conf}, as a string. -@end deftypevr - -@deftypevr {@code{opaque-cups-configuration} parameter} string cups-files.conf -The contents of the @code{cups-files.conf} file, as a string. -@end deftypevr - -For example, if your @code{cupsd.conf} and @code{cups-files.conf} are in -strings of the same name, you could instantiate a CUPS service like this: - -@example -(service cups-service-type - (opaque-cups-configuration - (cupsd.conf cupsd.conf) - (cups-files.conf cups-files.conf))) -@end example - - -@node Desktop-Dienste -@subsection Desktop-Dienste - -The @code{(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: - -@defvr {Scheme Variable} %desktop-services -This is a list of services that builds upon @var{%base-services} and adds or -adjusts services for a typical ``desktop'' setup. - -In particular, it adds a graphical login manager (@pxref{X Window, -@code{slim-service}}), screen lockers, a network management tool -(@pxref{Netzwerkdienste, @code{network-manager-service-type}}), energy -and color management services, the @code{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 (@pxref{Netzwerkdienste}), the Avahi daemon, and has the -name service switch service configured to be able to use @code{nss-mdns} -(@pxref{Name Service Switch, mDNS}). -@end defvr - -The @var{%desktop-services} variable can be used as the @code{services} -field of an @code{operating-system} declaration (@pxref{»operating-system«-Referenz, @code{services}}). - -Additionally, the @code{gnome-desktop-service}, @code{xfce-desktop-service}, -@code{mate-desktop-service-type} and -@code{enlightenment-desktop-service-type} procedures can add GNOME, XFCE, -MATE and/or Enlightenment to a system. To ``add GNOME'' means that -system-level services like the backlight adjustment helpers and the power -management utilities are added to the system, extending @code{polkit} and -@code{dbus} appropriately, allowing GNOME to operate with elevated -privileges on a limited number of special-purpose system interfaces. -Additionally, adding a service made by @code{gnome-desktop-service} adds the -GNOME metapackage to the system profile. Likewise, adding the XFCE service -not only adds the @code{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 @code{polkit} and @code{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 -@code{mate-desktop-service-type} adds the MATE metapackage to the system -profile. ``Adding Enlightenment'' means that @code{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 @code{sddm-service} instead of the @code{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. - -@deffn {Scheme Procedure} gnome-desktop-service -Return a service that adds the @code{gnome} package to the system profile, -and extends polkit with the actions from @code{gnome-settings-daemon}. -@end deffn - -@deffn {Scheme Procedure} xfce-desktop-service -Return a service that adds the @code{xfce} package to the system profile, -and extends polkit with the ability for @code{thunar} to manipulate the file -system as root from within a user session, after the user has authenticated -with the administrator's password. -@end deffn - -@deffn {Scheme Variable} mate-desktop-service-type -This is the type of the service that runs the -@uref{https://mate-desktop.org/, MATE desktop environment}. Its value is a -@code{mate-desktop-configuration} object (see below.) - -This service adds the @code{mate} package to the system profile, and extends -polkit with the actions from @code{mate-settings-daemon}. -@end deffn - -@deftp {Data Type} mate-desktop-configuration -Configuration record for the MATE desktop environment. - -@table @asis -@item @code{mate} (default @code{mate}) -The MATE package to use. -@end table -@end deftp - -@deffn {Scheme Variable} enlightenment-desktop-service-type -Return a service that adds the @code{enlightenment} package to the system -profile, and extends dbus with actions from @code{efl}. -@end deffn - -@deftp {Data Type} enlightenment-desktop-service-configuration -@table @asis -@item @code{enlightenment} (Vorgabe: @code{enlightenment}) -Das Enlightenment-Paket, was benutzt werden soll. -@end table -@end deftp - -Because the GNOME, XFCE and MATE desktop services pull in so many packages, -the default @code{%desktop-services} variable doesn't include any of them by -default. To add GNOME, XFCE or MATE, just @code{cons} them onto -@code{%desktop-services} in the @code{services} field of your -@code{operating-system}: - -@example -(use-modules (gnu)) -(use-service-modules desktop) -(operating-system - ... - ;; cons* adds items to the list given as its last argument. - (services (cons* (gnome-desktop-service) - (xfce-desktop-service) - %desktop-services)) - ...) -@end example - -These desktop environments will then be available as options in the -graphical login window. - -The actual service definitions included in @code{%desktop-services} and -provided by @code{(gnu services dbus)} and @code{(gnu services desktop)} are -described below. - -@deffn {Scheme Procedure} dbus-service [#:dbus @var{dbus}] [#:services '()] -Return a service that runs the ``system bus'', using @var{dbus}, with -support for @var{services}. - -@uref{http://dbus.freedesktop.org/, D-Bus} 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. - -@var{services} must be a list of packages that provide an -@file{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, @var{services} must be equal to @code{(list avahi)}. -@end deffn - -@deffn {Scheme Procedure} elogind-service [#:config @var{config}] -Return a service that runs the @code{elogind} login and seat management -daemon. @uref{https://github.com/elogind/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 @var{config} keyword argument specifies the configuration for elogind, -and should be the result of an @code{(elogind-configuration (@var{parameter} -@var{value})...)} invocation. Available parameters and their default values -are: - -@table @code -@item kill-user-processes? -@code{#f} -@item kill-only-users -@code{()} -@item kill-exclude-users -@code{("root")} -@item inhibit-delay-max-seconds -@code{5} -@item handle-power-key -@code{poweroff} -@item handle-suspend-key -@code{suspend} -@item handle-hibernate-key -@code{hibernate} -@item handle-lid-switch -@code{suspend} -@item handle-lid-switch-docked -@code{ignore} -@item power-key-ignore-inhibited? -@code{#f} -@item suspend-key-ignore-inhibited? -@code{#f} -@item hibernate-key-ignore-inhibited? -@code{#f} -@item lid-switch-ignore-inhibited? -@code{#t} -@item holdoff-timeout-seconds -@code{30} -@item idle-action -@code{ignore} -@item idle-action-seconds -@code{(* 30 60)} -@item runtime-directory-size-percent -@code{10} -@item runtime-directory-size -@code{#f} -@item remove-ipc? -@code{#t} -@item suspend-state -@code{("mem" "standby" "freeze")} -@item suspend-mode -@code{()} -@item hibernate-state -@code{("disk")} -@item hibernate-mode -@code{("platform" "shutdown")} -@item hybrid-sleep-state -@code{("disk")} -@item hybrid-sleep-mode -@code{("suspend" "platform" "shutdown")} -@end table -@end deffn - -@deffn {Scheme Procedure} accountsservice-service @ - [#:accountsservice @var{accountsservice}] Return a service that 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. -@uref{https://www.freedesktop.org/wiki/Software/AccountsService/, the -accountsservice web site} for more information. - -The @var{accountsservice} keyword argument is the @code{accountsservice} -package to expose as a service. -@end deffn - -@deffn {Scheme Procedure} polkit-service @ - [#:polkit @var{polkit}] Return a service that runs the -@uref{http://www.freedesktop.org/wiki/Software/polkit/, Polkit privilege -management service}, 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. -@end deffn - -@defvr {Scheme Variable} upower-service-type -Service that runs @uref{http://upower.freedesktop.org/, @command{upowerd}}, -a system-wide monitor for power consumption and battery levels, with the -given configuration settings. - -It implements the @code{org.freedesktop.UPower} D-Bus interface, and is -notably used by GNOME. -@end defvr - -@deftp {Data Type} upower-configuration -Data type representation the configuration for UPower. - -@table @asis - -@item @code{upower} (default: @var{upower}) -Package to use for @code{upower}. - -@item @code{watts-up-pro?} (default: @code{#f}) -Enable the Watts Up Pro device. - -@item @code{poll-batteries?} (default: @code{#t}) -Enable polling the kernel for battery level changes. - -@item @code{ignore-lid?} (default: @code{#f}) -Ignore the lid state, this can be useful if it's incorrect on a device. - -@item @code{use-percentage-for-policy?} (default: @code{#f}) -Whether battery percentage based policy should be used. The default is to -use the time left, change to @code{#t} to use the percentage. - -@item @code{percentage-low} (default: @code{10}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which the battery is considered low. - -@item @code{percentage-critical} (default: @code{3}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which the battery is considered critical. - -@item @code{percentage-action} (default: @code{2}) -When @code{use-percentage-for-policy?} is @code{#t}, this sets the -percentage at which action will be taken. - -@item @code{time-low} (default: @code{1200}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which the battery is considered low. - -@item @code{time-critical} (default: @code{300}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which the battery is considered critical. - -@item @code{time-action} (default: @code{120}) -When @code{use-time-for-policy?} is @code{#f}, this sets the time remaining -in seconds at which action will be taken. - -@item @code{critical-power-action} (default: @code{'hybrid-sleep}) -The action taken when @code{percentage-action} or @code{time-action} is -reached (depending on the configuration of -@code{use-percentage-for-policy?}). - -Possible values are: - -@itemize @bullet -@item -@code{'power-off} - -@item -@code{'hibernate} - -@item -@code{'hybrid-sleep}. -@end itemize - -@end table -@end deftp - -@deffn {Scheme Procedure} udisks-service [#:udisks @var{udisks}] -Return a service for @uref{http://udisks.freedesktop.org/docs/latest/, -UDisks}, a @dfn{disk management} daemon that provides user interfaces with -notifications and ways to mount/unmount disks. Programs that talk to UDisks -include the @command{udisksctl} command, part of UDisks, and GNOME Disks. -@end deffn - -@deffn {Scheme Procedure} colord-service [#:colord @var{colord}] -Return a service that runs @command{colord}, a system service with a D-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 @uref{http://www.freedesktop.org/software/colord/, the -colord web site} for more information. -@end deffn - -@deffn {Scheme Procedure} geoclue-application name [#:allowed? #t] [#:system? #f] [#:users '()] -Return a configuration allowing an application to access GeoClue location -data. @var{name} is the Desktop ID of the application, without the -@code{.desktop} part. If @var{allowed?} is true, the application will have -access to location information by default. The boolean @var{system?} value -indicates whether an application is a system component or not. Finally -@var{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. -@end deffn - -@defvr {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. -@end defvr - -@deffn {Scheme Procedure} geoclue-service [#:colord @var{colord}] @ - [#:whitelist '()] @ [#:wifi-geolocation-url -"https://location.services.mozilla.com/v1/geolocate?key=geoclue"] @ -[#:submit-data? #f] [#:wifi-submission-url -"https://location.services.mozilla.com/v1/submit?key=geoclue"] @ -[#:submission-nick "geoclue"] @ [#:applications -%standard-geoclue-applications] Return a service that runs the 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 -@uref{https://wiki.freedesktop.org/www/Software/GeoClue/, the GeoClue web -site} for more information. -@end deffn - -@deffn {Scheme Procedure} bluetooth-service [#:bluez @var{bluez}] @ - [@w{#:auto-enable? #f}] Return a service that runs the @command{bluetoothd} -daemon, which manages all the Bluetooth devices and provides a number 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 @code{lp} group to access the D-Bus service. -@end deffn - -@node Tondienste -@subsection Tondienste - -@cindex sound support -@cindex ALSA -@cindex PulseAudio, sound support - -The @code{(gnu services sound)} module provides a service to configure the -Advanced Linux Sound Architecture (ALSA) system, which makes PulseAudio the -preferred ALSA output driver. - -@deffn {Scheme Variable} alsa-service-type -This is the type for the @uref{https://alsa-project.org/, Advanced Linux -Sound Architecture} (ALSA) system, which generates the -@file{/etc/asound.conf} configuration file. The value for this type is a -@command{alsa-configuration} record as in this example: - -@example -(service alsa-service-type) -@end example - -See below for details about @code{alsa-configuration}. -@end deffn - -@deftp {Datentyp} alsa-configuration -Repräsentiert die Konfiguration für den Dienst @code{alsa-service}. - -@table @asis -@item @code{alsa-plugins} (Vorgabe: @var{alsa-plugins}) -@code{alsa-plugins}-Paket, was benutzt werden soll. - -@item @code{pulseaudio?} (Vorgabe: @var{#t}) -Whether ALSA applications should transparently be made to use the -@uref{http://www.pulseaudio.org/, PulseAudio} sound server. - -Using PulseAudio allows you to run several sound-producing applications at -the same time and to individual control them @i{via} @command{pavucontrol}, -among other things. - -@item @code{extra-options} (Vorgabe: @var{""}) -String to append to the @file{/etc/asound.conf} file. - -@end table -@end deftp - -Individual users who want to override the system configuration of ALSA can -do it with the @file{~/.asoundrc} file: - -@example -# In guix, we have to specify the absolute path for plugins. -pcm_type.jack @{ - lib "/home/alice/.guix-profile/lib/alsa-lib/libasound_module_pcm_jack.so" -@} - -# Routing ALSA to jack: -# <http://jackaudio.org/faq/routing_alsa.html>. -pcm.rawjack @{ - type jack - playback_ports @{ - 0 system:playback_1 - 1 system:playback_2 - @} - - capture_ports @{ - 0 system:capture_1 - 1 system:capture_2 - @} -@} - -pcm.!default @{ - type plug - slave @{ - pcm "rawjack" - @} -@} -@end example - -See @uref{https://www.alsa-project.org/main/index.php/Asoundrc} for the -details. - - -@node Datenbankdienste -@subsection Datenbankdienste - -@cindex Datenbank -@cindex SQL -The @code{(gnu services databases)} module provides the following services. - -@deffn {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 @var{postgresql}, the PostgreSQL database server. - -The PostgreSQL daemon loads its runtime configuration from -@var{config-file}, creates a database cluster with @var{locale} as the -default locale, stored in @var{data-directory}. It then listens on -@var{port}. - -@cindex postgresql extension-packages -Additional extensions are loaded from packages listed in -@var{extension-packages}. Extensions are available at runtime. For -instance, to create a geographic database using the @code{postgis} -extension, a user can configure the postgresql-service as in this example: - -@cindex postgis -@example -(use-package-modules databases geo) - -(operating-system - ... - ;; postgresql is required to run `psql' but postgis is not required for - ;; proper operation. - (packages (cons* postgresql %base-packages)) - (services - (cons* - (postgresql-service #:extension-packages (list postgis)) - %base-services))) -@end example - -Then the extension becomes visible and you can initialise an empty -geographic database in this way: - -@example -psql -U postgres -> create database postgistest; -> \connect postgistest; -> create extension postgis; -> create extension postgis_topology; -@end example - -There is no need to add this field for contrib extensions such as hstore or -dblink as they are already loadable by postgresql. This field is only -required to add extensions provided by other packages. -@end deffn - -@deffn {Scheme Procedure} mysql-service [#:config (mysql-configuration)] -Return a service that runs @command{mysqld}, the MySQL or MariaDB database -server. - -The optional @var{config} argument specifies the configuration for -@command{mysqld}, which should be a @code{<mysql-configuration>} object. -@end deffn - -@deftp {Data Type} mysql-configuration -Data type representing the configuration of @var{mysql-service}. - -@table @asis -@item @code{mysql} (default: @var{mariadb}) -Package object of the MySQL database server, can be either @var{mariadb} or -@var{mysql}. - -For MySQL, a temporary root password will be displayed at activation time. -For MariaDB, the root password is empty. - -@item @code{port} (default: @code{3306}) -TCP port on which the database server listens for incoming connections. -@end table -@end deftp - -@defvr {Scheme Variable} memcached-service-type -This is the service type for the @uref{https://memcached.org/, Memcached} -service, which provides a distributed in memory cache. The value for the -service type is a @code{memcached-configuration} object. -@end defvr - -@example -(service memcached-service-type) -@end example - -@deftp {Data Type} memcached-configuration -Data type representing the configuration of memcached. - -@table @asis -@item @code{memcached} (default: @code{memcached}) -The Memcached package to use. - -@item @code{interfaces} (default: @code{'("0.0.0.0")}) -Network interfaces on which to listen. - -@item @code{tcp-port} (default: @code{11211}) -Port on which to accept connections on, - -@item @code{udp-port} (default: @code{11211}) -Port on which to accept UDP connections on, a value of 0 will disable -listening on a UDP socket. - -@item @code{additional-options} (default: @code{'()}) -Additional command line options to pass to @code{memcached}. -@end table -@end deftp - -@defvr {Scheme Variable} mongodb-service-type -This is the service type for @uref{https://www.mongodb.com/, MongoDB}. The -value for the service type is a @code{mongodb-configuration} object. -@end defvr - -@example -(service mongodb-service-type) -@end example - -@deftp {Data Type} mongodb-configuration -Data type representing the configuration of mongodb. - -@table @asis -@item @code{mongodb} (default: @code{mongodb}) -The MongoDB package to use. - -@item @code{config-file} (default: @code{%default-mongodb-configuration-file}) -The configuration file for MongoDB. - -@item @code{data-directory} (default: @code{"/var/lib/mongodb"}) -This value is used to create the directory, so that it exists and is owned -by the mongodb user. It should match the data-directory which MongoDB is -configured to use through the configuration file. -@end table -@end deftp - -@defvr {Scheme Variable} redis-service-type -This is the service type for the @uref{https://redis.io/, Redis} key/value -store, whose value is a @code{redis-configuration} object. -@end defvr - -@deftp {Data Type} redis-configuration -Data type representing the configuration of redis. - -@table @asis -@item @code{redis} (default: @code{redis}) -The Redis package to use. - -@item @code{bind} (default: @code{"127.0.0.1"}) -Network interface on which to listen. - -@item @code{port} (default: @code{6379}) -Port on which to accept connections on, a value of 0 will disable listening -on a TCP socket. - -@item @code{working-directory} (default: @code{"/var/lib/redis"}) -Directory in which to store the database and related files. -@end table -@end deftp - -@node Mail-Dienste -@subsection Mail-Dienste - -@cindex mail -@cindex email -The @code{(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. - -@subsubheading Dovecot Service - -@deffn {Scheme Procedure} dovecot-service [#:config (dovecot-configuration)] -Return a service that runs the Dovecot IMAP/POP3/LMTP mail server. -@end deffn - -By default, Dovecot does not need much configuration; the default -configuration object created by @code{(dovecot-configuration)} will suffice -if your mail is delivered to @code{~/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 @code{maildir~/.mail}, one -would instantiate the Dovecot service like this: - -@example -(dovecot-service #:config - (dovecot-configuration - (mail-location "maildir:~/.mail"))) -@end example - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{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 -@code{dovecot.conf} file that you want to port over from some other system; -see the end for more details. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services mail). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@c needed. However if the change you want to make to this documentation -@c can be done in an automated way, it's probably easier to change -@c (generate-documentation) than to make it below and have to deal with -@c the churn as dovecot updates. - -Available @code{dovecot-configuration} fields are: - -@deftypevr {@code{dovecot-configuration} parameter} package dovecot -The dovecot package. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} comma-separated-string-list listen -A list of IPs or hosts where to listen for connections. @samp{*} listens on -all IPv4 interfaces, @samp{::} 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 @samp{inet-listener} of the specific services you are -interested in. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} protocol-configuration-list protocols -List of protocols we want to serve. Available protocols include -@samp{imap}, @samp{pop3}, and @samp{lmtp}. - -Available @code{protocol-configuration} fields are: - -@deftypevr {@code{protocol-configuration} parameter} string name -The name of the protocol. -@end deftypevr - -@deftypevr {@code{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 -@samp{"/var/run/dovecot/auth-userdb"}. -@end deftypevr - -@deftypevr {@code{protocol-configuration} parameter} space-separated-string-list mail-plugins -Space separated list of plugins to load. -@end deftypevr - -@deftypevr {@code{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 @samp{10}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} service-configuration-list services -List of services to enable. Available services include @samp{imap}, -@samp{imap-login}, @samp{pop3}, @samp{pop3-login}, @samp{auth}, and -@samp{lmtp}. - -Available @code{service-configuration} fields are: - -@deftypevr {@code{service-configuration} parameter} string kind -The service kind. Valid values include @code{director}, @code{imap-login}, -@code{pop3-login}, @code{lmtp}, @code{imap}, @code{pop3}, @code{auth}, -@code{auth-worker}, @code{dict}, @code{tcpwrap}, @code{quota-warning}, or -anything else. -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} listener-configuration-list listeners -Listeners for the service. A listener is either a -@code{unix-listener-configuration}, a @code{fifo-listener-configuration}, or -an @code{inet-listener-configuration}. Defaults to @samp{()}. - -Available @code{unix-listener-configuration} fields are: - -@deftypevr {@code{unix-listener-configuration} parameter} string path -Path to the file, relative to @code{base-dir} field. This is also used as -the section name. -@end deftypevr - -@deftypevr {@code{unix-listener-configuration} parameter} string mode -The access mode for the socket. Defaults to @samp{"0600"}. -@end deftypevr - -@deftypevr {@code{unix-listener-configuration} parameter} string user -The user to own the socket. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{unix-listener-configuration} parameter} string group -The group to own the socket. Defaults to @samp{""}. -@end deftypevr - - -Available @code{fifo-listener-configuration} fields are: - -@deftypevr {@code{fifo-listener-configuration} parameter} string path -Path to the file, relative to @code{base-dir} field. This is also used as -the section name. -@end deftypevr - -@deftypevr {@code{fifo-listener-configuration} parameter} string mode -The access mode for the socket. Defaults to @samp{"0600"}. -@end deftypevr - -@deftypevr {@code{fifo-listener-configuration} parameter} string user -The user to own the socket. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{fifo-listener-configuration} parameter} string group -The group to own the socket. Defaults to @samp{""}. -@end deftypevr - - -Available @code{inet-listener-configuration} fields are: - -@deftypevr {@code{inet-listener-configuration} parameter} string protocol -The protocol to listen for. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} string address -The address on which to listen, or empty for all addresses. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} non-negative-integer port -The port on which to listen. -@end deftypevr - -@deftypevr {@code{inet-listener-configuration} parameter} boolean ssl? -Whether to use SSL for this service; @samp{yes}, @samp{no}, or -@samp{required}. Defaults to @samp{#t}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer client-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, @code{default-client-limit} -is used instead. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{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 @samp{1}. - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer process-limit -Maximum number of processes that can exist for this service. If set to 0, -@code{default-process-limit} is used instead. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer process-min-avail -Number of processes to always keep waiting for more connections. Defaults -to @samp{0}. -@end deftypevr - -@deftypevr {@code{service-configuration} parameter} non-negative-integer vsz-limit -If you set @samp{service-count 0}, you probably need to grow this. Defaults -to @samp{256000000}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} dict-configuration dict -Dict configuration, as created by the @code{dict-configuration} constructor. - -Available @code{dict-configuration} fields are: - -@deftypevr {@code{dict-configuration} parameter} free-form-fields entries -A list of key-value pairs that this dict should hold. Defaults to -@samp{()}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} passdb-configuration-list passdbs -A list of passdb configurations, each one created by the -@code{passdb-configuration} constructor. - -Available @code{passdb-configuration} fields are: - -@deftypevr {@code{passdb-configuration} parameter} string driver -The driver that the passdb should use. Valid values include @samp{pam}, -@samp{passwd}, @samp{shadow}, @samp{bsdauth}, and @samp{static}. Defaults -to @samp{"pam"}. -@end deftypevr - -@deftypevr {@code{passdb-configuration} parameter} space-separated-string-list args -Space separated list of arguments to the passdb driver. Defaults to -@samp{""}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} userdb-configuration-list userdbs -List of userdb configurations, each one created by the -@code{userdb-configuration} constructor. - -Available @code{userdb-configuration} fields are: - -@deftypevr {@code{userdb-configuration} parameter} string driver -The driver that the userdb should use. Valid values include @samp{passwd} -and @samp{static}. Defaults to @samp{"passwd"}. -@end deftypevr - -@deftypevr {@code{userdb-configuration} parameter} space-separated-string-list args -Space separated list of arguments to the userdb driver. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{userdb-configuration} parameter} free-form-args override-fields -Override fields from passwd. Defaults to @samp{()}. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} plugin-configuration plugin-configuration -Plug-in configuration, created by the @code{plugin-configuration} -constructor. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} list-of-namespace-configuration namespaces -List of namespaces. Each item in the list is created by the -@code{namespace-configuration} constructor. - -Available @code{namespace-configuration} fields are: - -@deftypevr {@code{namespace-configuration} parameter} string name -Name for this namespace. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string type -Namespace type: @samp{private}, @samp{shared} or @samp{public}. Defaults to -@samp{"private"}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string separator -Hierarchy separator to use. You should use the same separator for all -namespaces or some clients get confused. @samp{/} is usually a good one. -The default however depends on the underlying mail storage format. Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} string prefix -Prefix required to access this namespace. This needs to be different for -all namespaces. For example @samp{Public/}. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean inbox? -There can be only one INBOX, and this setting defines which namespace has -it. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{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 @samp{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 @samp{~/mail/}, @samp{~%u/mail/} and -@samp{mail/}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean list? -Show the mailboxes under this namespace with the LIST command. This makes -the namespace visible for clients that do not support the NAMESPACE -extension. The special @code{children} value lists child mailboxes, but -hides the namespace prefix. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} boolean subscriptions? -Namespace handles its own subscriptions. If set to @code{#f}, the parent -namespace handles them. The empty prefix should always have this as -@code{#t}). Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{namespace-configuration} parameter} mailbox-configuration-list mailboxes -List of predefined mailboxes in this namespace. Defaults to @samp{()}. - -Available @code{mailbox-configuration} fields are: - -@deftypevr {@code{mailbox-configuration} parameter} string name -Name for this mailbox. -@end deftypevr - -@deftypevr {@code{mailbox-configuration} parameter} string auto -@samp{create} will automatically create this mailbox. @samp{subscribe} will -both create and subscribe to the mailbox. Defaults to @samp{"no"}. -@end deftypevr - -@deftypevr {@code{mailbox-configuration} parameter} space-separated-string-list special-use -List of IMAP @code{SPECIAL-USE} attributes as specified by RFC 6154. Valid -values are @code{\All}, @code{\Archive}, @code{\Drafts}, @code{\Flagged}, -@code{\Junk}, @code{\Sent}, and @code{\Trash}. Defaults to @samp{()}. -@end deftypevr - -@end deftypevr - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name base-dir -Base directory where to store runtime data. Defaults to -@samp{"/var/run/dovecot/"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string login-greeting -Greeting message for clients. Defaults to @samp{"Dovecot ready."}. -@end deftypevr - -@deftypevr {@code{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). @samp{disable-plaintext-auth} is also ignored for these networks. -Typically you would specify your IMAP proxy servers here. Defaults to -@samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-access-sockets -List of login access check sockets (e.g.@: tcpwrap). Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-proctitle? -Show more verbose process titles (in ps). Currently shows user name and 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 @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean shutdown-clients? -Should all processes be killed when Dovecot master process shuts down. -Setting this to @code{#f} means that Dovecot can be upgraded without 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 @samp{#t}. -@end deftypevr - -@deftypevr {@code{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 @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string doveadm-socket-path -UNIX socket or host:port used for connecting to doveadm server. Defaults to -@samp{"doveadm-server"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list import-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. -@end deftypevr - -@deftypevr {@code{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 @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-cache-size -Authentication cache size (e.g.@: @samp{#e10e6}). 0 means it's disabled. -Note that bsdauth, PAM and vpopmail require @samp{cache-key} to be set for -caching to be used. Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{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 @samp{"1 -hour"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-cache-negative-ttl -TTL for negative hits (user not found, password mismatch). 0 disables -caching them completely. Defaults to @samp{"1 hour"}. -@end deftypevr - -@deftypevr {@code{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 @samp{()}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{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 -@samp{"abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ01234567890.-_@@"}. -@end deftypevr - -@deftypevr {@code{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 @samp{#@@/@@} -means that @samp{#} and @samp{/} characters are translated to @samp{@@}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{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 @samp{%n-AT-%d} would change the -@samp{@@} into @samp{-AT-}. This translation is done after -@samp{auth-username-translation} changes. Defaults to @samp{"%Lu"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-master-user-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 -@samp{*} as the separator, so that could be a good choice. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-anonymous-username -Username to use for users logging in with ANONYMOUS SASL mechanism. -Defaults to @samp{"anonymous"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer auth-worker-max-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 @samp{30}. -@end deftypevr - -@deftypevr {@code{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 @samp{$ALL} (with quotes) to allow all -keytab entries. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-krb5-keytab -Kerberos keytab to use for the GSSAPI mechanism. Will use the system -default (usually @file{/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 @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-use-winbind? -Do NTLM and GSS-SPNEGO authentication using Samba's winbind daemon and -@samp{ntlm-auth} helper. <doc/wiki/Authentication/Mechanisms/Winbind.txt>. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name auth-winbind-helper-path -Path for Samba's @samp{ntlm-auth} helper binary. Defaults to -@samp{"/usr/bin/ntlm_auth"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string auth-failure-delay -Time to delay before replying to failed authentications. Defaults to -@samp{"2 secs"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-require-client-cert? -Require a valid SSL client certificate or the authentication fails. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-ssl-username-from-cert? -Take the username from client's SSL certificate, using -@code{X509_NAME_get_text_by_NID()} which returns the subject's DN's -CommonName. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list auth-mechanisms -List of wanted authentication mechanisms. Supported mechanisms are: -@samp{plain}, @samp{login}, @samp{digest-md5}, @samp{cram-md5}, @samp{ntlm}, -@samp{rpa}, @samp{apop}, @samp{anonymous}, @samp{gssapi}, @samp{otp}, -@samp{skey}, and @samp{gss-spnego}. NOTE: See also -@samp{disable-plaintext-auth} setting. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list director-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 @samp{inet-listener} is using. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{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 @samp{()}. -@end deftypevr - -@deftypevr {@code{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 @samp{"15 min"}. -@end deftypevr - -@deftypevr {@code{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 @samp{"%Lu"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string log-path -Log file to use for error messages. @samp{syslog} logs to syslog, -@samp{/dev/stderr} logs to stderr. Defaults to @samp{"syslog"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string info-log-path -Log file to use for informational messages. Defaults to @samp{log-path}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string debug-log-path -Log file to use for debug messages. Defaults to @samp{info-log-path}. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string syslog-facility -Syslog facility to use if you're logging to syslog. Usually if you don't -want to use @samp{mail}, you'll use local0..local7. Also other standard -facilities are supported. Defaults to @samp{"mail"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose? -Log unsuccessful authentication attempts and the reasons why they failed. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-verbose-passwords? -In case of password mismatches, log the attempted password. Valid 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 @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug? -Even more verbose logging for debugging purposes. Shows for example SQL -queries. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean auth-debug-passwords? -In case of password mismatches, log the passwords and used scheme so the -problem can be debugged. Enabling this also enables @samp{auth-debug}. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-debug? -Enable mail process debugging. This can help you figure out why Dovecot -isn't finding your mails. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean verbose-ssl? -Show protocol level SSL errors. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string log-timestamp -Prefix for each line written to log file. % codes are in strftime(3) -format. Defaults to @samp{"\"%b %d %H:%M:%S \""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list login-log-format-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. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string login-log-format -Login log format. %s contains @samp{login-log-format-elements} string, %$ -contains the data we want to log. Defaults to @samp{"%$: %s"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-log-prefix -Log prefix for mail processes. See doc/wiki/Variables.txt for list of -possible variables you can use. Defaults to -@samp{"\"%s(%u)<%@{pid@}><%@{session@}>: \""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string deliver-log-format -Format to use for logging mail deliveries. You can use variables: -@table @code -@item %$ -Delivery status message (e.g.@: @samp{saved to INBOX}) -@item %m -Message-ID -@item %s -Subject -@item %f -From address -@item %p -Physical size -@item %w -Virtual size. -@end table -Defaults to @samp{"msgid=%m: %$"}. -@end deftypevr - -@deftypevr {@code{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 @samp{mail-location} setting. - -There are a few special variables you can use, eg.: - -@table @samp -@item %u -username -@item %n -user part in user@@domain, same as %u if there's no domain -@item %d -domain part in user@@domain, empty if there's no domain -@item %h -home director -@end table - -See doc/wiki/Variables.txt for full list. Some examples: -@table @samp -@item maildir:~/Maildir -@item mbox:~/mail:INBOX=/var/mail/%u -@item mbox:/var/mail/%d/%1n/%n:INDEX=/var/indexes/%d/%1n/% -@end table -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-gid - -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{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 -@samp{""}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-full-filesystem-access? -Allow full file system access to clients. There's no access checks 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 @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mmap-disable? -Don't use mmap() at all. This is required if you store indexes to shared -file systems (NFS or clustered file system). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean dotlock-use-excl? -Rely on @samp{O_EXCL} to work when creating dotlock files. NFS supports -@samp{O_EXCL} since version 3, so this should be safe to use nowadays by -default. Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-fsync -When to use fsync() or fdatasync() calls: -@table @code -@item optimized -Whenever necessary to avoid losing important data -@item always -Useful with e.g.@: NFS when write()s are delayed -@item never -Never use it (best performance, but crashes can lose data). -@end table -Defaults to @samp{"optimized"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-storage? -Mail storage exists in NFS. Set this to yes to make Dovecot flush NFS -caches whenever needed. If you're using only a single mail server this -isn't needed. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-nfs-index? -Mail index files also exist in NFS. Setting this to yes requires -@samp{mmap-disable? #t} and @samp{fsync-disable? #f}. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string lock-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 -@samp{mmap-disable}. Defaults to @samp{"fcntl"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name mail-temp-dir -Directory in which LDA/LMTP temporarily stores incoming mails >128 kB. -Defaults to @samp{"/tmp"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-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 @samp{first-valid-uid} -is set to 0. Defaults to @samp{500}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-uid - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer first-valid-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 @samp{1}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer last-valid-gid - -Defaults to @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mail-max-keyword-length -Maximum allowed length for mail keyword name. It's only forced when trying -to create new keywords. Defaults to @samp{50}. -@end deftypevr - -@deftypevr {@code{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 @samp{login-chroot} @samp{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 @samp{()}. -@end deftypevr - -@deftypevr {@code{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 @samp{mail-chroot}. -<doc/wiki/Chrooting.txt>. Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{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 -@samp{"/var/run/dovecot/auth-userdb"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name mail-plugin-dir -Directory where to look up mail plugins. Defaults to -@samp{"/usr/lib/dovecot"}. -@end deftypevr - -@deftypevr {@code{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 -@samp{()}. -@end deftypevr - -@deftypevr {@code{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 @samp{0}. -@end deftypevr - -@deftypevr {@code{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 -@samp{"30 secs"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mail-save-crlf? -Save mails with CR+LF instead of plain LF. This makes sending those 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 @samp{#f}. -@end deftypevr - -@deftypevr {@code{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 @samp{dirent->d_type} this check is free -and it's done always regardless of this setting). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-copy-with-hardlinks? -When copying a message, do it with hard links whenever possible. This makes -the performance much better, and it's unlikely to have any side effects. -Defaults to @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean maildir-very-dirty-syncs? -Assume Dovecot is the only MUA accessing Maildir: Scan cur/ directory only -when its mtime changes unexpectedly or when we can't find the mail -otherwise. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-read-locks -Which locking methods to use for locking mbox. There are four available: - -@table @code -@item 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. -@item dotlock-try -Same as dotlock, but if it fails because of permissions or because there -isn't enough disk space, just skip it. -@item fcntl -Use this if possible. Works with NFS too if lockd is used. -@item flock -May not exist in all systems. Doesn't work with NFS. -@item lockf -May not exist in all systems. Doesn't work with NFS. -@end table - -You can use multiple locking methods; if you do the order they're 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. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list mbox-write-locks - -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mbox-lock-timeout -Maximum time to wait for lock (all of them) before aborting. Defaults to -@samp{"5 mins"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mbox-dotlock-change-timeout -If dotlock exists but the mailbox isn't modified in any way, override the -lock file after this much time. Defaults to @samp{"2 mins"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-dirty-syncs? -When mbox changes unexpectedly we have to fully read it to find out 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 @samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-very-dirty-syncs? -Like @samp{mbox-dirty-syncs}, but don't do full syncs even with SELECT, -EXAMINE, EXPUNGE or CHECK commands. If this is set, @samp{mbox-dirty-syncs} -is ignored. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mbox-lazy-writes? -Delay writing mbox headers until doing a full write sync (EXPUNGE and 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 @samp{#t}. -@end deftypevr - -@deftypevr {@code{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 @samp{0}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer mdbox-rotate-size -Maximum dbox file size until it's rotated. Defaults to @samp{10000000}. -@end deftypevr - -@deftypevr {@code{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 @samp{"1d"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean mdbox-preallocate-space? -When creating new mdbox files, immediately preallocate their size to -@samp{mdbox-rotate-size}. This setting currently works only in Linux with -some file systems (ext4, xfs). Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{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 @samp{128000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-fs -File system backend to use for saving attachments: -@table @code -@item posix -No SiS done by Dovecot (but this might help FS's own deduplication) -@item sis posix -SiS with immediate byte-by-byte comparison during saving -@item sis-queue posix -SiS with delayed comparison and deduplication. -@end table -Defaults to @samp{"sis posix"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string mail-attachment-hash -Hash format to use in attachment filenames. You can add any text and -variables: @code{%@{md4@}}, @code{%@{md5@}}, @code{%@{sha1@}}, -@code{%@{sha256@}}, @code{%@{sha512@}}, @code{%@{size@}}. Variables can be -truncated, e.g.@: @code{%@{sha256:80@}} returns only first 80 bits. -Defaults to @samp{"%@{sha1@}"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-process-limit - -Defaults to @samp{100}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-client-limit - -Defaults to @samp{1000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer default-vsz-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 @samp{256000000}. -@end deftypevr - -@deftypevr {@code{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 @samp{"dovenull"}. -@end deftypevr - -@deftypevr {@code{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 @samp{"dovecot"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl? -SSL/TLS support: yes, no, required. <doc/wiki/SSL.txt>. Defaults to -@samp{"required"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert -PEM encoded X.509 SSL/TLS certificate (public key). Defaults to -@samp{"</etc/dovecot/default.pem"}. -@end deftypevr - -@deftypevr {@code{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 -@samp{"</etc/dovecot/private/default.pem"}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-ca -PEM encoded trusted certificate authority. Set this only if you intend to -use @samp{ssl-verify-client-cert? #t}. The file should contain the CA -certificate(s) followed by the matching CRL(s). (e.g.@: @samp{ssl-ca -</etc/ssl/certs/ca.pem}). Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-require-crl? -Require that CRL check succeeds for client certificates. Defaults to -@samp{#t}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean ssl-verify-client-cert? -Request client to send a certificate. If you also want to require it, set -@samp{auth-ssl-require-client-cert? #t} in auth section. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-cert-username-field -Which field from certificate to use for username. commonName and -x500UniqueIdentifier are the usual choices. You'll also need to set -@samp{auth-ssl-username-from-cert? #t}. Defaults to @samp{"commonName"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-min-protocol -Minimum SSL protocol version to accept. Defaults to @samp{"TLSv1"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-cipher-list -SSL ciphers to use. Defaults to -@samp{"ALL:!kRSA:!SRP:!kDHd:!DSS:!aNULL:!eNULL:!EXPORT:!DES:!3DES:!MD5:!PSK:!RC4:!ADH:!LOW@@STRENGTH"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string ssl-crypto-device -SSL crypto device to use, for valid values run "openssl engine". Defaults -to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string postmaster-address -Address to use when sending rejection mails. %d expands to recipient -domain. Defaults to @samp{"postmaster@@%d"}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean quota-full-tempfail? -If user is over quota, return with temporary failure instead of bouncing the -mail. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} file-name sendmail-path -Binary to use for sending mails. Defaults to @samp{"/usr/sbin/sendmail"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string submission-host -If non-empty, send mails via this SMTP host[:port] instead of sendmail. -Defaults to @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string rejection-subject -Subject: header to use for rejection mails. You can use the same variables -as for @samp{rejection-reason} below. Defaults to @samp{"Rejected: %s"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string rejection-reason -Human readable error message for rejection mails. You can use variables: - -@table @code -@item %n -CRLF -@item %r -reason -@item %s -original subject -@item %t -recipient -@end table -Defaults to @samp{"Your message to <%t> was automatically rejected:%n%r"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string recipient-delimiter -Delimiter character between local-part and detail in email address. -Defaults to @samp{"+"}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autocreate? -Should saving a mail to a nonexistent mailbox automatically create it?. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} boolean lda-mailbox-autosubscribe? -Should automatically created mailboxes be also automatically subscribed?. -Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} non-negative-integer imap-max-line-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 -@samp{64000}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-logout-format -IMAP logout format string: -@table @code -@item %i -total number of bytes read from client -@item %o -total number of bytes sent to client. -@end table -See @file{doc/wiki/Variables.txt} for a list of all the variables you can -use. Defaults to @samp{"in=%i out=%o deleted=%@{deleted@} -expunged=%@{expunged@} trashed=%@{trashed@} hdr_count=%@{fetch_hdr_count@} -hdr_bytes=%@{fetch_hdr_bytes@} body_count=%@{fetch_body_count@} -body_bytes=%@{fetch_body_bytes@}"}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-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 @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-idle-notify-interval -How long to wait between "OK Still here" notifications when client is -IDLEing. Defaults to @samp{"2 mins"}. -@end deftypevr - -@deftypevr {@code{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 @samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-id-log -ID fields sent by client to log. * means everything. Defaults to -@samp{""}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} space-separated-string-list imap-client-workarounds -Workarounds for various client bugs: - -@table @code -@item 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". - -@item tb-extra-mailbox-sep -Thunderbird gets somehow confused with LAYOUT=fs (mbox and dbox) and adds -extra @samp{/} suffixes to mailbox names. This option causes Dovecot to -ignore the extra @samp{/} instead of treating it as invalid mailbox name. - -@item 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. -@end table -Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{dovecot-configuration} parameter} string imap-urlauth-host -Host allowed in URLAUTH URLs sent by client. "*" allows all. Defaults to -@samp{""}. -@end deftypevr - - -Whew! Lots of configuration options. The nice thing about it though is 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 @code{dovecot.conf} up and -running. In that case, you can pass an @code{opaque-dovecot-configuration} -as the @code{#:config} parameter to @code{dovecot-service}. As its name -indicates, an opaque configuration does not have easy reflective -capabilities. - -Available @code{opaque-dovecot-configuration} fields are: - -@deftypevr {@code{opaque-dovecot-configuration} parameter} package dovecot -The dovecot package. -@end deftypevr - -@deftypevr {@code{opaque-dovecot-configuration} parameter} string string -The contents of the @code{dovecot.conf}, as a string. -@end deftypevr - -For example, if your @code{dovecot.conf} is just the empty string, you could -instantiate a dovecot service like this: - -@example -(dovecot-service #:config - (opaque-dovecot-configuration - (string ""))) -@end example - -@subsubheading OpenSMTPD Service - -@deffn {Scheme Variable} opensmtpd-service-type -This is the type of the @uref{https://www.opensmtpd.org, OpenSMTPD} service, -whose value should be an @code{opensmtpd-configuration} object as in this -example: - -@example -(service opensmtpd-service-type - (opensmtpd-configuration - (config-file (local-file "./my-smtpd.conf")))) -@end example -@end deffn - -@deftp {Data Type} opensmtpd-configuration -Data type representing the configuration of opensmtpd. - -@table @asis -@item @code{package} (default: @var{opensmtpd}) -Package object of the OpenSMTPD SMTP server. - -@item @code{config-file} (default: @var{%default-opensmtpd-file}) -File-like object of the OpenSMTPD configuration file to use. By default 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 @command{man smtpd.conf} for more information. - -@end table -@end deftp - -@subsubheading Exim Service - -@cindex mail transfer agent (MTA) -@cindex MTA (mail transfer agent) -@cindex SMTP - -@deffn {Scheme Variable} exim-service-type -This is the type of the @uref{https://exim.org, Exim} mail transfer agent -(MTA), whose value should be an @code{exim-configuration} object as in this -example: - -@example -(service exim-service-type - (exim-configuration - (config-file (local-file "./my-exim.conf")))) -@end example -@end deffn - -In order to use an @code{exim-service-type} service you must also have a -@code{mail-aliases-service-type} service present in your -@code{operating-system} (even if it has no aliases). - -@deftp {Data Type} exim-configuration -Data type representing the configuration of exim. - -@table @asis -@item @code{package} (default: @var{exim}) -Package object of the Exim server. - -@item @code{config-file} (default: @code{#f}) -File-like object of the Exim configuration file to use. If its value is -@code{#f} then use the default configuration file from the package provided -in @code{package}. The resulting configuration file is loaded after setting -the @code{exim_user} and @code{exim_group} configuration variables. - -@end table -@end deftp - -@subsubheading Mail Aliases Service - -@cindex email aliases -@cindex aliases, for email addresses - -@deffn {Scheme Variable} mail-aliases-service-type -This is the type of the service which provides @code{/etc/aliases}, -specifying how to deliver mail to users on this system. - -@example -(service mail-aliases-service-type - '(("postmaster" "bob") - ("bob" "bob@@example.com" "bob@@example2.com"))) -@end example -@end deffn - -The configuration for a @code{mail-aliases-service-type} service is an -association list denoting how to deliver mail that comes to this -system. Each entry is of the form @code{(alias addresses ...)}, with -@code{alias} specifying the local alias and @code{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 @code{postmaster} entry in the -@code{operating-system}'s @code{user-accounts} in order to deliver the -@code{postmaster} mail to @code{bob} (which subsequently would deliver mail -to @code{bob@@example.com} and @code{bob@@example2.com}). - -@node Kurznachrichtendienste -@subsection Kurznachrichtendienste - -@cindex messaging -@cindex jabber -@cindex XMPP -The @code{(gnu services messaging)} module provides Guix service definitions -for messaging services: currently only Prosody is supported. - -@subsubheading Prosody Service - -@deffn {Scheme Variable} prosody-service-type -This is the type for the @uref{https://prosody.im, Prosody XMPP -communication server}. Its value must be a @code{prosody-configuration} -record as in this example: - -@example -(service prosody-service-type - (prosody-configuration - (modules-enabled (cons "groups" "mam" %default-modules-enabled)) - (int-components - (list - (int-component-configuration - (hostname "conference.example.net") - (plugin "muc") - (mod-muc (mod-muc-configuration))))) - (virtualhosts - (list - (virtualhost-configuration - (domain "example.net")))))) -@end example - -See below for details about @code{prosody-configuration}. - -@end deffn - -By default, Prosody does not need much configuration. Only one -@code{virtualhosts} field is needed: it specifies the domain you wish -Prosody to serve. - -You can perform various sanity checks on the generated configuration with -the @code{prosodyctl check} command. - -Prosodyctl will also help you to import certificates from the -@code{letsencrypt} directory so that the @code{prosody} user can access -them. See @url{https://prosody.im/doc/letsencrypt}. - -@example -prosodyctl --root cert import /etc/letsencrypt/live -@end example - -The available configuration parameters follow. Each parameter definition is -preceded by its type; for example, @samp{string-list foo} indicates that the -@code{foo} parameter should be specified as a list of strings. Types -starting with @code{maybe-} denote parameters that won't show up in -@code{prosody.cfg.lua} when their value is @code{'disabled}. - -There is also a way to specify the configuration as a string, if you have an -old @code{prosody.cfg.lua} file that you want to port over from some other -system; see the end for more details. - -The @code{file-object} type designates either a file-like object -(@pxref{G-Ausdrücke, file-like objects}) or a file name. - -@c The following documentation was initially generated by -@c (generate-documentation) in (gnu services messaging). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@c needed. However if the change you want to make to this documentation -@c can be done in an automated way, it's probably easier to change -@c (generate-documentation) than to make it below and have to deal with -@c the churn as Prosody updates. - -Available @code{prosody-configuration} fields are: - -@deftypevr {@code{prosody-configuration} parameter} package prosody -The Prosody package. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-name data-path -Location of the Prosody data storage directory. See -@url{https://prosody.im/doc/configure}. Defaults to -@samp{"/var/lib/prosody"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-object-list plugin-paths -Additional plugin directories. They are searched in all the specified paths -in order. See @url{https://prosody.im/doc/plugins_directory}. Defaults to -@samp{()}. -@end deftypevr - -@deftypevr {@code{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 -@samp{"/etc/prosody/certs"}. -@end deftypevr - -@deftypevr {@code{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 -@url{https://prosody.im/doc/admins} and -@url{https://prosody.im/doc/creating_accounts}. Example: @code{(admins -'("user1@@example.com" "user2@@example.net"))} Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean use-libevent? -Enable use of libevent for better performance under high load. See -@url{https://prosody.im/doc/libevent}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} module-list modules-enabled -This is the list of modules Prosody will load on startup. It looks for -@code{mod_modulename.lua} in the plugins folder, so make sure that exists -too. Documentation on modules can be found at: -@url{https://prosody.im/doc/modules}. Defaults to @samp{("roster" -"saslauth" "tls" "dialback" "disco" "carbons" "private" "blocklist" "vcard" -"version" "uptime" "time" "ping" "pep" "register" "admin_adhoc")}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list modules-disabled -@samp{"offline"}, @samp{"c2s"} and @samp{"s2s"} are auto-loaded, but should -you want to disable them then add them to this list. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-object groups-file -Path to a text file where the shared groups are defined. If this path is -empty then @samp{mod_groups} does nothing. See -@url{https://prosody.im/doc/modules/mod_groups}. Defaults to -@samp{"/var/lib/prosody/sharedgroups.txt"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean allow-registration? -Disable account creation by default, for security. See -@url{https://prosody.im/doc/creating_accounts}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-ssl-configuration 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 @url{https://prosody.im/doc/advanced_ssl_config}. - -Available @code{ssl-configuration} fields are: - -@deftypevr {@code{ssl-configuration} parameter} maybe-string protocol -This determines what handshake to use. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-name key -Path to your private key file. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-name certificate -Path to your certificate file. -@end deftypevr - -@deftypevr {@code{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 -@samp{"/etc/ssl/certs"}. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-file-object cafile -Path to a file containing root certificates that you wish Prosody to trust. -Similar to @code{capath} but with all certificates concatenated together. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verify -A list of verification options (these mostly map to OpenSSL's -@code{set_verify()} flags). -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list options -A list of general options relating to SSL/TLS. These map to OpenSSL's -@code{set_options()}. For a full list of options available in LuaSec, see -the LuaSec source. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-non-negative-integer depth -How long a chain of certificate authorities to check when looking for a -trusted root certificate. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string ciphers -An OpenSSL cipher string. This selects what ciphers Prosody will offer to -clients, and in what order. -@end deftypevr - -@deftypevr {@code{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: @code{openssl dhparam -out -/etc/prosody/certs/dh-2048.pem 2048} -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string curve -Curve for Elliptic curve Diffie-Hellman. Prosody's default is -@samp{"secp384r1"}. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string-list verifyext -A list of "extra" verification options. -@end deftypevr - -@deftypevr {@code{ssl-configuration} parameter} maybe-string password -Password for encrypted private keys. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean c2s-require-encryption? -Whether to force all client-to-server connections to be encrypted or not. -See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list disable-sasl-mechanisms -Set of mechanisms that will never be offered. See -@url{https://prosody.im/doc/modules/mod_saslauth}. Defaults to -@samp{("DIGEST-MD5")}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean s2s-require-encryption? -Whether to force all server-to-server connections to be encrypted or not. -See @url{https://prosody.im/doc/modules/mod_tls}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} boolean s2s-secure-auth? -Whether to require encryption and certificate authentication. This provides -ideal security, but requires servers you communicate with to support -encryption AND present valid, trusted certificates. See -@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{#f}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list s2s-insecure-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 -@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string-list s2s-secure-domains -Even if you leave @code{s2s-secure-auth?} disabled, you can still require -valid certificates for some domains by specifying a list here. See -@url{https://prosody.im/doc/s2s#security}. Defaults to @samp{()}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string 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 -@url{https://prosody.im/doc/modules/mod_auth_internal_hashed} for -information about using the hashed backend. See also -@url{https://prosody.im/doc/authentication} Defaults to -@samp{"internal_plain"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-string log -Set logging options. Advanced logging configuration is not yet supported by -the Guix Prosody Service. See @url{https://prosody.im/doc/logging}. -Defaults to @samp{"*syslog"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} file-name pidfile -File to write pid in. See @url{https://prosody.im/doc/modules/mod_posix}. -Defaults to @samp{"/var/run/prosody/prosody.pid"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-non-negative-integer http-max-content-size -Maximum allowed size of the HTTP body (in bytes). -@end deftypevr - -@deftypevr {@code{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 @code{http-external-url} instead. See -@url{https://prosody.im/doc/http#external_url}. -@end deftypevr - -@deftypevr {@code{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 -@samp{"john.smith@@example.com"} then you need to add a host -@samp{"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 @url{https://prosody.im/doc/configure#virtual_host_settings}. - -Available @code{virtualhost-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{virtualhost-configuration} parameter} string domain -Domain you wish Prosody to serve. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{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 -@samp{"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 @url{https://prosody.im/doc/components}. Defaults to @samp{()}. - -Available @code{int-component-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{int-component-configuration} parameter} string hostname -Hostname of the component. -@end deftypevr - -@deftypevr {@code{int-component-configuration} parameter} string plugin -Plugin you wish to use for the component. -@end deftypevr - -@deftypevr {@code{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 -(@url{https://prosody.im/doc/chatrooms}), which you should read if you are -new to XMPP chatrooms. - -See also @url{https://prosody.im/doc/modules/mod_muc}. - -Available @code{mod-muc-configuration} fields are: - -@deftypevr {@code{mod-muc-configuration} parameter} string name -The name to return in service discovery responses. Defaults to -@samp{"Prosody Chatrooms"}. -@end deftypevr - -@deftypevr {@code{mod-muc-configuration} parameter} string-or-boolean restrict-room-creation -If @samp{#t}, this will only allow admins to create new chatrooms. -Otherwise anyone can create a room. The value @samp{"local"} restricts room -creation to users on the service's parent domain. E.g.@: -@samp{user@@example.com} can create rooms on @samp{rooms.example.com}. The -value @samp{"admin"} restricts to service administrators only. Defaults to -@samp{#f}. -@end deftypevr - -@deftypevr {@code{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 @samp{20}. -@end deftypevr - -@end deftypevr - -@end deftypevr - -@deftypevr {@code{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 -@url{https://prosody.im/doc/components}. Defaults to @samp{()}. - -Available @code{ext-component-configuration} fields are: - -all these @code{prosody-configuration} fields: @code{admins}, -@code{use-libevent?}, @code{modules-enabled}, @code{modules-disabled}, -@code{groups-file}, @code{allow-registration?}, @code{ssl}, -@code{c2s-require-encryption?}, @code{disable-sasl-mechanisms}, -@code{s2s-require-encryption?}, @code{s2s-secure-auth?}, -@code{s2s-insecure-domains}, @code{s2s-secure-domains}, -@code{authentication}, @code{log}, @code{http-max-content-size}, -@code{http-external-url}, @code{raw-content}, plus: -@deftypevr {@code{ext-component-configuration} parameter} string component-secret -Password which the component will use to log in. -@end deftypevr - -@deftypevr {@code{ext-component-configuration} parameter} string hostname -Hostname of the component. -@end deftypevr - -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} non-negative-integer-list component-ports -Port(s) Prosody listens on for component connections. Defaults to -@samp{(5347)}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} string component-interface -Interface Prosody listens on for component connections. Defaults to -@samp{"127.0.0.1"}. -@end deftypevr - -@deftypevr {@code{prosody-configuration} parameter} maybe-raw-content raw-content -Raw content that will be added to the configuration file. -@end deftypevr - -It could be that you just want to get a @code{prosody.cfg.lua} up and -running. In that case, you can pass an @code{opaque-prosody-configuration} -record as the value of @code{prosody-service-type}. As its name indicates, -an opaque configuration does not have easy reflective capabilities. -Available @code{opaque-prosody-configuration} fields are: - -@deftypevr {@code{opaque-prosody-configuration} parameter} package prosody -The prosody package. -@end deftypevr - -@deftypevr {@code{opaque-prosody-configuration} parameter} string prosody.cfg.lua -The contents of the @code{prosody.cfg.lua} to use. -@end deftypevr - -For example, if your @code{prosody.cfg.lua} is just the empty string, you -could instantiate a prosody service like this: - -@example -(service prosody-service-type - (opaque-prosody-configuration - (prosody.cfg.lua ""))) -@end example - -@c end of Prosody auto-generated documentation - -@subsubheading BitlBee Service - -@cindex IRC (Internet Relay Chat) -@cindex IRC gateway -@url{http://bitlbee.org,BitlBee} is a gateway that provides an IRC interface -to a variety of messaging protocols such as XMPP. - -@defvr {Scheme Variable} bitlbee-service-type -This is the service type for the @url{http://bitlbee.org,BitlBee} IRC -gateway daemon. Its value is a @code{bitlbee-configuration} (see below). - -To have BitlBee listen on port 6667 on localhost, add this line to your -services: - -@example -(service bitlbee-service-type) -@end example -@end defvr - -@deftp {Data Type} bitlbee-configuration -This is the configuration for BitlBee, with the following fields: - -@table @asis -@item @code{interface} (default: @code{"127.0.0.1"}) -@itemx @code{port} (default: @code{6667}) -Listen on the network interface corresponding to the IP address specified in -@var{interface}, on @var{port}. - -When @var{interface} is @code{127.0.0.1}, only local clients can connect; -when it is @code{0.0.0.0}, connections can come from any networking -interface. - -@item @code{package} (default: @code{bitlbee}) -The BitlBee package to use. - -@item @code{plugins} (Vorgabe: @code{'()}) -List of plugin packages to use---e.g., @code{bitlbee-discord}. - -@item @code{extra-settings} (default: @code{""}) -Configuration snippet added as-is to the BitlBee configuration file. -@end table -@end deftp - -@subsubheading Quassel Service - -@cindex IRC (Internet Relay Chat) -@url{https://quassel-irc.org/,Quassel} is a distributed IRC client, meaning -that one or more clients can attach to and detach from the central core. - -@defvr {Scheme Variable} quassel-service-type -This is the service type for the @url{https://quassel-irc.org/,Quassel} IRC -backend daemon. Its value is a @code{quassel-configuration} (see below). -@end defvr - -@deftp {Data Type} quassel-configuration -This is the configuration for Quassel, with the following fields: - -@table @asis -@item @code{quassel} (default: @code{quassel}) -The Quassel package to use. - -@item @code{interface} (default: @code{"::,0.0.0.0"}) -@item @code{port} (default: @code{4242}) -Listen on the network interface(s) corresponding to the IPv4 or IPv6 -interfaces specified in the comma delimited @var{interface}, on @var{port}. - -@item @code{loglevel} (default: @code{"Info"}) -The level of logging desired. Accepted values are Debug, Info, Warning and -Error. -@end table -@end deftp - -@node Telefondienste -@subsection Telefondienste - -@cindex Murmur (VoIP server) -@cindex VoIP server -This section describes how to set up and run a Murmur server. Murmur is the -server of the @uref{https://mumble.info, Mumble} voice-over-IP (VoIP) suite. - -@deftp {Data Type} murmur-configuration -The service type for the Murmur server. An example configuration can look -like this: - -@example -(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"))) -@end example - -After reconfiguring your system, you can manually set the murmur -@code{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 @code{mumble} client to login as -new normal user, register yourself, and log out. For the next step login -with the name @code{SuperUser} use the @code{SuperUser} password that you -set previously, and grant your newly registered mumble user administrator or -moderator rights and create some channels. - -Available @code{murmur-configuration} fields are: - -@table @asis -@item @code{package} (default: @code{mumble}) -Package that contains @code{bin/murmurd}. - -@item @code{user} (default: @code{"murmur"}) -User who will run the Murmur server. - -@item @code{group} (default: @code{"murmur"}) -Group of the user who will run the murmur server. - -@item @code{port} (default: @code{64738}) -Port on which the server will listen. - -@item @code{welcome-text} (default: @code{""}) -Welcome text sent to clients when they connect. - -@item @code{server-password} (default: @code{""}) -Password the clients have to enter in order to connect. - -@item @code{max-users} (default: @code{100}) -Maximum of users that can be connected to the server at once. - -@item @code{max-user-bandwidth} (default: @code{#f}) -Maximum voice traffic a user can send per second. - -@item @code{database-file} (default: @code{"/var/lib/murmur/db.sqlite"}) -File name of the sqlite database. The service's user will become the owner -of the directory. - -@item @code{log-file} (default: @code{"/var/log/murmur/murmur.log"}) -File name of the log file. The service's user will become the owner of the -directory. - -@item @code{autoban-attempts} (default: @code{10}) -Maximum number of logins a user can make in @code{autoban-timeframe} without -getting auto banned for @code{autoban-time}. - -@item @code{autoban-timeframe} (default: @code{120}) -Timeframe for autoban in seconds. - -@item @code{autoban-time} (default: @code{300}) -Amount of time in seconds for which a client gets banned when violating the -autoban limits. - -@item @code{opus-threshold} (default: @code{100}) -Percentage of clients that need to support opus before switching over to -opus audio codec. - -@item @code{channel-nesting-limit} (default: @code{10}) -How deep channels can be nested at maximum. - -@item @code{channelname-regex} (default: @code{#f}) -A string in form of a Qt regular expression that channel names must conform -to. - -@item @code{username-regex} (default: @code{#f}) -A string in form of a Qt regular expression that user names must conform to. - -@item @code{text-message-length} (default: @code{5000}) -Maximum size in bytes that a user can send in one text chat message. - -@item @code{image-message-length} (default: @code{(* 128 1024)}) -Maximum size in bytes that a user can send in one image message. - -@item @code{cert-required?} (default: @code{#f}) -If it is set to @code{#t} clients that use weak password authentification -will not be accepted. Users must have completed the certificate wizard to -join. - -@item @code{remember-channel?} (Vorgabe: @code{#f}) -Should murmur remember the last channel each user was in when they -disconnected and put them into the remembered channel when they rejoin. - -@item @code{allow-html?} (default: @code{#f}) -Should html be allowed in text messages, user comments, and channel -descriptions. - -@item @code{allow-ping?} (default: @code{#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. - -@item @code{bonjour?} (default: @code{#f}) -Should the server advertise itself in the local network through the bonjour -protocol. - -@item @code{send-version?} (default: @code{#f}) -Should the murmur server version be exposed in ping requests. - -@item @code{log-days} (default: @code{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. - -@item @code{obfuscate-ips?} (Vorgabe: @code{#t}) -Should logged ips be obfuscated to protect the privacy of users. - -@item @code{ssl-cert} (default: @code{#f}) -File name of the SSL/TLS certificate used for encrypted connections. - -@example -(ssl-cert "/etc/letsencrypt/live/example.com/fullchain.pem") -@end example -@item @code{ssl-key} (default: @code{#f}) -Filepath to the ssl private key used for encrypted connections. -@example -(ssl-key "/etc/letsencrypt/live/example.com/privkey.pem") -@end example - -@item @code{ssl-dh-params} (default: @code{#f}) -File name of a PEM-encoded file with Diffie-Hellman parameters for the -SSL/TLS encryption. Alternatively you set it to @code{"@@ffdhe2048"}, -@code{"@@ffdhe3072"}, @code{"@@ffdhe4096"}, @code{"@@ffdhe6144"} or -@code{"@@ffdhe8192"} to use bundled parameters from RFC 7919. - -@item @code{ssl-ciphers} (default: @code{#f}) -The @code{ssl-ciphers} option chooses the cipher suites to make available -for use in SSL/TLS. - -This option is specified using -@uref{https://www.openssl.org/docs/apps/ciphers.html#CIPHER-LIST-FORMAT, -OpenSSL cipher list notation}. - -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. - -@item @code{public-registration} (default: @code{#f}) -Must be a @code{<murmur-public-registration-configuration>} record or -@code{#f}. - -You can optionally register your server in the public server list that the -@code{mumble} client shows on startup. You cannot register your server if -you have set a @code{server-password}, or set @code{allow-ping} to -@code{#f}. - -It might take a few hours until it shows up in the public list. - -@item @code{file} (default: @code{#f}) -Optional alternative override for this configuration. -@end table -@end deftp - -@deftp {Data Type} murmur-public-registration-configuration -Configuration for public registration of a murmur service. - -@table @asis -@item @code{name} -This is a display name for your server. Not to be confused with the -hostname. - -@item @code{password} -A password to identify your registration. Subsequent updates will need the -same password. Don't lose your password. - -@item @code{url} -This should be a @code{http://} or @code{https://} link to your web site. - -@item @code{hostname} (default: @code{#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. -@end table -@end deftp - - - -@node Überwachungsdienste -@subsection Überwachungsdienste - -@subsubheading Tailon Service - -@uref{https://tailon.readthedocs.io/, Tailon} 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 (@code{http://localhost:8080}). - -@example -(service tailon-service-type) -@end example - -The following example customises more of the Tailon configuration, adding -@command{sed} to the list of allowed commands. - -@example -(service tailon-service-type - (tailon-configuration - (config-file - (tailon-configuration-file - (allowed-commands '("tail" "grep" "awk" "sed")))))) -@end example - - -@deftp {Data Type} tailon-configuration -Data type representing the configuration of Tailon. This type has the -following parameters: - -@table @asis -@item @code{config-file} (default: @code{(tailon-configuration-file)}) -The configuration file to use for Tailon. This can be set to a -@dfn{tailon-configuration-file} record value, or any gexp -(@pxref{G-Ausdrücke}). - -For example, to instead use a local file, the @code{local-file} function can -be used: - -@example -(service tailon-service-type - (tailon-configuration - (config-file (local-file "./my-tailon.conf")))) -@end example - -@item @code{package} (default: @code{tailon}) -The tailon package to use. - -@end table -@end deftp - -@deftp {Data Type} tailon-configuration-file -Data type representing the configuration options for Tailon. This type has -the following parameters: - -@table @asis -@item @code{files} (default: @code{(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. - -@item @code{bind} (default: @code{"localhost:8080"}) -Address and port to which Tailon should bind on. - -@item @code{relative-root} (default: @code{#f}) -URL path to use for Tailon, set to @code{#f} to not use a path. - -@item @code{allow-transfers?} (default: @code{#t}) -Allow downloading the log files in the web interface. - -@item @code{follow-names?} (default: @code{#t}) -Allow tailing of not-yet existent files. - -@item @code{tail-lines} (default: @code{200}) -Number of lines to read initially from each file. - -@item @code{allowed-commands} (default: @code{(list "tail" "grep" "awk")}) -Commands to allow running. By default, @code{sed} is disabled. - -@item @code{debug?} (default: @code{#f}) -Set @code{debug?} to @code{#t} to show debug messages. - -@item @code{wrap-lines} (default: @code{#t}) -Initial line wrapping state in the web interface. Set to @code{#t} to -initially wrap lines (the default), or to @code{#f} to initially not wrap -lines. - -@item @code{http-auth} (default: @code{#f}) -HTTP authentication type to use. Set to @code{#f} to disable authentication -(the default). Supported values are @code{"digest"} or @code{"basic"}. - -@item @code{users} (default: @code{#f}) -If HTTP authentication is enabled (see @code{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. - -@example -(tailon-configuration-file - (http-auth "basic") - (users '(("user1" . "password1") - ("user2" . "password2")))) -@end example - -@end table -@end deftp - - -@subsubheading Darkstat Service -@cindex darkstat -Darkstat is a packet sniffer that captures network traffic, calculates -statistics about usage, and serves reports over HTTP. - -@defvar {Scheme Variable} darkstat-service-type -This is the service type for the @uref{https://unix4lyfe.org/darkstat/, -darkstat} service, its value must be a @code{darkstat-configuration} record -as in this example: - -@example -(service darkstat-service-type - (darkstat-configuration - (interface "eno1"))) -@end example -@end defvar - -@deftp {Data Type} darkstat-configuration -Data type representing the configuration of @command{darkstat}. - -@table @asis -@item @code{package} (default: @code{darkstat}) -The darkstat package to use. - -@item @code{interface} -Capture traffic on the specified network interface. - -@item @code{port} (default: @code{"667"}) -Bind the web interface to the specified port. - -@item @code{bind-address} (default: @code{"127.0.0.1"}) -Bind the web interface to the specified address. - -@item @code{base} (default: @code{"/"}) -Specify the path of the base URL. This can be useful if @command{darkstat} -is accessed via a reverse proxy. - -@end table -@end deftp - -@subsubheading Prometheus Node Exporter Service - -@cindex prometheus-node-exporter -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. - -@defvar {Scheme variable} prometheus-node-exporter-service-type -This is the service type for the -@uref{https://github.com/prometheus/node_exporter/, -prometheus-node-exporter} service, its value must be a -@code{prometheus-node-exporter-configuration} record as in this example: - -@example -(service prometheus-node-exporter-service-type - (prometheus-node-exporter-configuration - (web-listen-address ":9100"))) -@end example -@end defvar - -@deftp {Data Type} prometheus-node-exporter-configuration -Repräsentiert die Konfiguration von @command{node_exporter}. - -@table @asis -@item @code{package} (Vorgabe: @code{go-github-com-prometheus-node-exporter}) -Das Paket für den prometheus-node-exporter, was benutzt werden soll. - -@item @code{web-listen-address} (Vorgabe: @code{":9100"}) -Bind the web interface to the specified address. - -@end table -@end deftp - -@subsubheading Zabbix server -@cindex zabbix zabbix-server -Zabbix provides monitoring metrics, among others network utilization, CPU -load and disk space consumption: - -@itemize -@item High performance, high capacity (able to monitor hundreds of thousands of devices). -@item Auto-discovery of servers and network devices and interfaces. -@item Low-level discovery, allows to automatically start monitoring new items, file systems or network interfaces among others. -@item Distributed monitoring with centralized web administration. -@item Native high performance agents. -@item SLA, and ITIL KPI metrics on reporting. -@item High-level (business) view of monitored resources through user-defined visual console screens and dashboards. -@item Remote command execution through Zabbix proxies. -@end itemize - -@c %start of fragment - -Available @code{zabbix-server-configuration} fields are: - -@deftypevr {@code{zabbix-server-configuration} parameter} package zabbix-server -The zabbix-server package. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string user -User who will run the Zabbix server. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} group group -Group who will run the Zabbix server. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-host -Database host name. - -Defaults to @samp{"127.0.0.1"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-name -Database name. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-user -Database user. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string db-password -Database password. Please, use @code{include-files} with -@code{DBPassword=SECRET} inside a specified file instead. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} number db-port -Database port. - -Defaults to @samp{5432}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string log-type -Specifies where log messages are written to: - -@itemize @bullet -@item -@code{system} - syslog. - -@item -@code{file} - file specified with @code{log-file} parameter. - -@item -@code{console} - standard output. - -@end itemize - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string log-file -Log file name for @code{log-type} @code{file} parameter. - -Defaults to @samp{"/var/log/zabbix/server.log"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string pid-file -Name of PID file. - -Defaults to @samp{"/var/run/zabbix/zabbix_server.pid"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-ca-location -The location of certificate authority (CA) files for SSL server certificate -verification. - -Defaults to @samp{"/etc/ssl/certs/ca-certificates.crt"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string ssl-cert-location -Location of SSL client certificates. - -Defaults to @samp{"/etc/ssl/certs"}. - -@end deftypevr - -@deftypevr {@code{zabbix-server-configuration} parameter} string extra-options -Extra options will be appended to Zabbix server configuration file. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{()}. - -@end deftypevr - -@c %end of fragment - -@subsubheading Zabbix agent -@cindex zabbix zabbix-agent - -Zabbix agent gathers information for Zabbix server. - -@c %start of fragment - -Available @code{zabbix-agent-configuration} fields are: - -@deftypevr {@code{zabbix-agent-configuration} parameter} package zabbix-agent -The zabbix-agent package. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string user -User who will run the Zabbix agent. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} group group -Group who will run the Zabbix agent. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"Zabbix server"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string log-type -Specifies where log messages are written to: - -@itemize @bullet -@item -@code{system} - syslog. - -@item -@code{file} - file specified with @code{log-file} parameter. - -@item -@code{console} - standard output. - -@end itemize - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string log-file -Log file name for @code{log-type} @code{file} parameter. - -Defaults to @samp{"/var/log/zabbix/agent.log"}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string pid-file -Name of PID file. - -Defaults to @samp{"/var/run/zabbix/zabbix_agent.pid"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{("127.0.0.1")}. - -@end deftypevr - -@deftypevr {@code{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 @samp{("127.0.0.1")}. - -@end deftypevr - -@deftypevr {@code{zabbix-agent-configuration} parameter} string extra-options -Extra options will be appended to Zabbix server configuration file. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{()}. - -@end deftypevr - -@c %end of fragment - -@subsubheading Zabbix front-end -@cindex zabbix zabbix-front-end - -This service provides a WEB interface to Zabbix server. - -@c %start of fragment - -Available @code{zabbix-front-end-configuration} fields are: - -@deftypevr {@code{zabbix-front-end-configuration} parameter} nginx-server-configuration-list nginx -NGINX configuration. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-host -Database host name. - -Defaults to @samp{"localhost"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} number db-port -Database port. - -Defaults to @samp{5432}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-name -Database name. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-user -Database user. - -Defaults to @samp{"zabbix"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-password -Database password. Please, use @code{db-secret-file} instead. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string db-secret-file -Secret file which will be appended to @file{zabbix.conf.php} file. This -file contains credentials for use by Zabbix front-end. You are expected to -create it manually. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} string zabbix-host -Zabbix server hostname. - -Defaults to @samp{"localhost"}. - -@end deftypevr - -@deftypevr {@code{zabbix-front-end-configuration} parameter} number zabbix-port -Zabbix server port. - -Defaults to @samp{10051}. - -@end deftypevr - - -@c %end of fragment - -@node Kerberos-Dienste -@subsection Kerberos-Dienste -@cindex Kerberos - -The @code{(gnu services kerberos)} module provides services relating to the -authentication protocol @dfn{Kerberos}. - -@subsubheading Krb5 Service - -Programs using a Kerberos client library normally expect a configuration -file in @file{/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, -@code{mit-krb5}. Other implementations have not been tested. - -@defvr {Scheme Variable} krb5-service-type -A service type for Kerberos 5 clients. -@end defvr - -@noindent -Here is an example of its use: -@lisp -(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")))))) -@end lisp - -@noindent -This example provides a Kerberos@tie{}5 client configuration which: -@itemize -@item Recognizes two realms, @i{viz:} ``EXAMPLE.COM'' and ``ARGRX.EDU'', both -of which have distinct administration servers and key distribution centers; -@item Will default to the realm ``EXAMPLE.COM'' if the realm is not explicitly -specified by clients; -@item Accepts services which only support encryption types known to be weak. -@end itemize - -The @code{krb5-realm} and @code{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 -@uref{http://web.mit.edu/kerberos/krb5-devel/doc/admin/conf_files/krb5_conf.html,,krb5.conf} -documentation. - - -@deftp {Data Type} krb5-realm -@cindex realm, kerberos -@table @asis -@item @code{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. - -@item @code{admin-server} -This field is a string identifying the host where the administration server -is running. - -@item @code{kdc} -This field is a string identifying the key distribution center for the -realm. -@end table -@end deftp - -@deftp {Data Type} krb5-configuration - -@table @asis -@item @code{allow-weak-crypto?} (default: @code{#f}) -If this flag is @code{#t} then services which only offer encryption -algorithms known to be weak will be accepted. - -@item @code{default-realm} (default: @code{#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 @code{#f} then a realm must be specified with every Kerberos -principal when invoking programs such as @command{kinit}. - -@item @code{realms} -This should be a non-empty list of @code{krb5-realm} objects, which clients -may access. Normally, one of them will have a @code{name} field matching -the @code{default-realm} field. -@end table -@end deftp - - -@subsubheading PAM krb5 Service -@cindex pam-krb5 - -The @code{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. - -@defvr {Scheme Variable} pam-krb5-service-type -A service type for the Kerberos 5 PAM module. -@end defvr - -@deftp {Data Type} pam-krb5-configuration -Data type representing the configuration of the Kerberos 5 PAM module This -type has the following parameters: -@table @asis -@item @code{pam-krb5} (default: @code{pam-krb5}) -The pam-krb5 package to use. - -@item @code{minimum-uid} (default: @code{1000}) -The smallest user ID for which Kerberos authentications should be -attempted. Local accounts with lower values will silently fail to -authenticate. -@end table -@end deftp - - -@node Web-Dienste -@subsection Web-Dienste - -@cindex web -@cindex www -@cindex HTTP -The @code{(gnu services web)} module provides the Apache HTTP Server, the -nginx web server, and also a fastcgi wrapper daemon. - -@subsubheading Apache HTTP Server - -@deffn {Scheme Variable} httpd-service-type -Service type for the @uref{https://httpd.apache.org/,Apache HTTP} server -(@dfn{httpd}). The value for this service type is a -@code{httpd-configuration} record. - -A simple example configuration is given below. - -@example -(service httpd-service-type - (httpd-configuration - (config - (httpd-config-file - (server-name "www.example.com") - (document-root "/srv/http/www.example.com"))))) -@end example - -Other services can also extend the @code{httpd-service-type} to add to the -configuration. - -@example -(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\""))))) -@end example -@end deffn - -The details for the @code{httpd-configuration}, @code{httpd-module}, -@code{httpd-config-file} and @code{httpd-virtualhost} record types are given -below. - -@deffn {Data Type} httpd-configuration -This data type represents the configuration for the httpd service. - -@table @asis -@item @code{package} (default: @code{httpd}) -The httpd package to use. - -@item @code{pid-file} (default: @code{"/var/run/httpd"}) -The pid file used by the shepherd-service. - -@item @code{config} (default: @code{(httpd-config-file)}) -The configuration file to use with the httpd service. The default value is a -@code{httpd-config-file} record, but this can also be a different -G-expression that generates a file, for example a @code{plain-file}. A file -outside of the store can also be specified through a string. - -@end table -@end deffn - -@deffn {Data Type} httpd-module -This data type represents a module for the httpd service. - -@table @asis -@item @code{name} -The name of the module. - -@item @code{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 @code{(file-append mod-wsgi "/modules/mod_wsgi.so")}. - -@end table -@end deffn - -@defvr {Scheme Variable} %default-httpd-modules -A default list of @code{httpd-module} objects. -@end defvr - -@deffn {Data Type} httpd-config-file -This data type represents a configuration file for the httpd service. - -@table @asis -@item @code{modules} (default: @code{%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 -@code{mod_proxy_fcgi} module along with @code{php-fpm-service-type}: - -@example -(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"))) -@end example - -@item @code{server-root} (default: @code{httpd}) -The @code{ServerRoot} in the configuration file, defaults to the httpd -package. Directives including @code{Include} and @code{LoadModule} are taken -as relative to the server root. - -@item @code{server-name} (default: @code{#f}) -The @code{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 @code{#f} to not specify a @code{ServerName}. - -@item @code{document-root} (default: @code{"/srv/http"}) -The @code{DocumentRoot} from which files will be served. - -@item @code{listen} (default: @code{'("80")}) -The list of values for the @code{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. - -@item @code{pid-file} (default: @code{"/var/run/httpd"}) -The @code{PidFile} to use. This should match the @code{pid-file} set in the -@code{httpd-configuration} so that the Shepherd service is configured -correctly. - -@item @code{error-log} (default: @code{"/var/log/httpd/error_log"}) -The @code{ErrorLog} to which the server will log errors. - -@item @code{user} (default: @code{"httpd"}) -The @code{User} which the server will answer requests as. - -@item @code{group} (default: @code{"httpd"}) -The @code{Group} which the server will answer requests as. - -@item @code{extra-config} (default: @code{(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. - -@end table -@end deffn - -@deffn {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. - -@example -(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\""))))) -@end example - -@table @asis -@item @code{addresses-and-ports} -The addresses and ports for the @code{VirtualHost} directive. - -@item @code{contents} -The contents of the @code{VirtualHost} directive, this should be a list of -strings and G-expressions. - -@end table -@end deffn - -@subsubheading NGINX - -@deffn {Scheme Variable} nginx-service-type -Service type for the @uref{https://nginx.org/,NGinx} web server. The value -for this service type is a @code{<nginx-configuration>} record. - -A simple example configuration is given below. - -@example -(service nginx-service-type - (nginx-configuration - (server-blocks - (list (nginx-server-configuration - (server-name '("www.example.com")) - (root "/srv/http/www.example.com")))))) -@end example - -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: - -@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"))))) -@end example -@end deffn - -At startup, @command{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 -@file{/var/run/nginx/logs/error.log}, and after configuration in -@file{/var/log/nginx/error.log}. The second location can be changed with -the @var{log-directory} configuration option. - -@deffn {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. - -@table @asis -@item @code{nginx} (default: @code{nginx}) -The nginx package to use. - -@item @code{log-directory} (default: @code{"/var/log/nginx"}) -The directory to which NGinx will write log files. - -@item @code{run-directory} (default: @code{"/var/run/nginx"}) -The directory in which NGinx will create a pid file, and write temporary -files. - -@item @code{server-blocks} (default: @code{'()}) -A list of @dfn{server blocks} to create in the generated configuration file, -the elements should be of type @code{<nginx-server-configuration>}. - -The following example would setup NGinx to serve @code{www.example.com} from -the @code{/srv/http/www.example.com} directory, without using HTTPS. -@example -(service nginx-service-type - (nginx-configuration - (server-blocks - (list (nginx-server-configuration - (server-name '("www.example.com")) - (root "/srv/http/www.example.com")))))) -@end example - -@item @code{upstream-blocks} (default: @code{'()}) -A list of @dfn{upstream blocks} to create in the generated configuration -file, the elements should be of type @code{<nginx-upstream-configuration>}. - -Configuring upstreams through the @code{upstream-blocks} can be useful when -combined with @code{locations} in the @code{<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. - -@example -(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"))))))) -@end example - -@item @code{file} (default: @code{#f}) -If a configuration @var{file} is provided, this will be used, rather than -generating a configuration file from the provided @code{log-directory}, -@code{run-directory}, @code{server-blocks} and @code{upstream-blocks}. For -proper operation, these arguments should match what is in @var{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. - -@item @code{server-names-hash-bucket-size} (default: @code{#f}) -Bucket size for the server names hash tables, defaults to @code{#f} to use -the size of the processors cache line. - -@item @code{server-names-hash-bucket-max-size} (default: @code{#f}) -Maximum bucket size for the server names hash tables. - -@item @code{extra-content} (Vorgabe: @code{""}) -Extra content for the @code{http} block. Should be string or a string -valued G-expression. - -@end table -@end deffn - -@deftp {Data Type} nginx-server-configuration -Data type representing the configuration of an nginx server block. This -type has the following parameters: - -@table @asis -@item @code{listen} (default: @code{'("80" "443 ssl")}) -Each @code{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: - -@example -'("127.0.0.1:8000" "127.0.0.1" "8000" "*:8000" "localhost:8000") -@end example - -@item @code{server-name} (default: @code{(list 'default)}) -A list of server names this server represents. @code{'default} represents -the default server for connections matching no other server. - -@item @code{root} (default: @code{"/srv/http"}) -Root of the website nginx will serve. - -@item @code{locations} (default: @code{'()}) -A list of @dfn{nginx-location-configuration} or -@dfn{nginx-named-location-configuration} records to use within this server -block. - -@item @code{index} (default: @code{(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. - -@item @code{try-files} (default: @code{'()}) -A list of files whose existence is checked in the specified order. -@code{nginx} will use the first file it finds to process the request. - -@item @code{ssl-certificate} (default: @code{#f}) -Where to find the certificate for secure connections. Set it to @code{#f} -if you don't have a certificate or you don't want to use HTTPS. - -@item @code{ssl-certificate-key} (default: @code{#f}) -Where to find the private key for secure connections. Set it to @code{#f} -if you don't have a key or you don't want to use HTTPS. - -@item @code{server-tokens?} (default: @code{#f}) -Whether the server should add its configuration to response. - -@item @code{raw-content} (default: @code{'()}) -A list of raw lines added to the server block. - -@end table -@end deftp - -@deftp {Data Type} nginx-upstream-configuration -Data type representing the configuration of an nginx @code{upstream} block. -This type has the following parameters: - -@table @asis -@item @code{name} -Name for this group of servers. - -@item @code{servers} -Specify the addresses of the servers in the group. The address can be -specified as a IP address (e.g.@: @samp{127.0.0.1}), domain name (e.g.@: -@samp{backend1.example.com}) or a path to a UNIX socket using the prefix -@samp{unix:}. For addresses using an IP address or domain name, the default -port is 80, and a different port can be specified explicitly. - -@end table -@end deftp - -@deftp {Data Type} nginx-location-configuration -Data type representing the configuration of an nginx @code{location} block. -This type has the following parameters: - -@table @asis -@item @code{uri} -URI which this location block matches. - -@anchor{nginx-location-configuration body} -@item @code{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 @code{nginx-upstream-configuration} block, the -following directive would be specified in the body @samp{(list "proxy_pass -http://upstream-name;")}. - -@end table -@end deftp - -@deftp {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: - -@table @asis -@item @code{name} -Name to identify this location block. - -@item @code{body} -@xref{nginx-location-configuration body}, as the body for named location -blocks can be used in a similar way to the -@code{nginx-location-configuration body}. One restriction is that the body -of a named location block cannot contain location blocks. - -@end table -@end deftp - -@subsubheading Varnish Cache -@cindex Varnish -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. - -@defvr {Scheme Variable} varnish-service-type -Service type for the Varnish daemon. -@end defvr - -@deftp {Data Type} varnish-configuration -Data type representing the @code{varnish} service configuration. This type -has the following parameters: - -@table @asis -@item @code{package} (Vorgabe: @code{varnish}) -Das Varnish-Paket, was benutzt werden soll. - -@item @code{name} (Vorgabe: @code{"default"}) -A name for this Varnish instance. Varnish will create a directory in -@file{/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 @code{-n} argument to other Varnish programs to connect to the -named instance, e.g.@: @command{varnishncsa -n default}. - -@item @code{backend} (Vorgabe: @code{"localhost:8080"}) -The backend to use. This option has no effect if @code{vcl} is set. - -@item @code{vcl} (Vorgabe: #f) -The @dfn{VCL} (Varnish Configuration Language) program to run. If this is -@code{#f}, Varnish will proxy @code{backend} using the default -configuration. Otherwise this must be a file-like object with valid VCL -syntax. - -@c Varnish does not support HTTPS, so keep this URL to avoid confusion. -For example, to mirror @url{http://www.gnu.org,www.gnu.org} with VCL you can -do something along these lines: - -@example -(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))) -@end example - -The configuration of an already running Varnish instance can be inspected -and changed using the @command{varnishadm} program. - -Consult the @url{https://varnish-cache.org/docs/,Varnish User Guide} and -@url{https://book.varnish-software.com/4.0/,Varnish Book} for comprehensive -documentation on Varnish and its configuration language. - -@item @code{listen} (Vorgabe: @code{'("localhost:80")}) -List of addresses Varnish will listen on. - -@item @code{storage} (Vorgabe: @code{'("malloc,128m")}) -List of storage backends that will be available in VCL. - -@item @code{parameters} (Vorgabe: @code{'()}) -List of run-time parameters in the form @code{'(("parameter" . "value"))}. - -@item @code{extra-options} (Vorgabe: @code{'()}) -Additional arguments to pass to the @command{varnishd} process. - -@end table -@end deftp - -@subsubheading FastCGI -@cindex fastcgi -@cindex fcgiwrap -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 @code{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 @code{fcgiwrap} process. - -@defvr {Scheme Variable} fcgiwrap-service-type -A service type for the @code{fcgiwrap} FastCGI proxy. -@end defvr - -@deftp {Data Type} fcgiwrap-configuration -Data type representing the configuration of the @code{fcgiwrap} service. -This type has the following parameters: -@table @asis -@item @code{package} (default: @code{fcgiwrap}) -The fcgiwrap package to use. - -@item @code{socket} (default: @code{tcp:127.0.0.1:9000}) -The socket on which the @code{fcgiwrap} process should listen, as a string. -Valid @var{socket} values include @code{unix:@var{/path/to/unix/socket}}, -@code{tcp:@var{dot.ted.qu.ad}:@var{port}} and -@code{tcp6:[@var{ipv6_addr}]:port}. - -@item @code{user} (default: @code{fcgiwrap}) -@itemx @code{group} (default: @code{fcgiwrap}) -The user and group names, as strings, under which to run the @code{fcgiwrap} -process. The @code{fastcgi} service will ensure that if the user asks for -the specific user or group names @code{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 -@code{fcgiwrap} to run the back-end process as a corresponding local user. -To enable this capability on the back-end., run @code{fcgiwrap} as the -@code{root} user and group. Note that this capability also has to be -configured on the front-end as well. -@end table -@end deftp - -@cindex php-fpm -PHP-FPM (FastCGI Process Manager) is an alternative PHP FastCGI -implementation with some additional features useful for sites of any size. - -These features include: -@itemize @bullet -@item Adaptive process spawning -@item Basic statistics (similar to Apache's mod_status) -@item Advanced process management with graceful stop/start -@item Ability to start workers with different uid/gid/chroot/environment -and different php.ini (replaces safe_mode) -@item Stdout & stderr logging -@item Emergency restart in case of accidental opcode cache destruction -@item Accelerated upload support -@item Support for a "slowlog" -@item 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.) -@end itemize -...@: and much more. - -@defvr {Scheme Variable} php-fpm-service-type -A Service type for @code{php-fpm}. -@end defvr - -@deftp {Data Type} php-fpm-configuration -Data Type for php-fpm service configuration. -@table @asis -@item @code{php} (default: @code{php}) -The php package to use. -@item @code{socket} (default: @code{(string-append "/var/run/php" (version-major (package-version php)) "-fpm.sock")}) -The address on which to accept FastCGI requests. Valid syntaxes are: -@table @asis -@item @code{"ip.add.re.ss:port"} -Listen on a TCP socket to a specific address on a specific port. -@item @code{"port"} -Listen on a TCP socket to all addresses on a specific port. -@item @code{"/path/to/unix/socket"} -Listen on a unix socket. -@end table - -@item @code{user} (default: @code{php-fpm}) -User who will own the php worker processes. -@item @code{group} (default: @code{php-fpm}) -Group of the worker processes. -@item @code{socket-user} (default: @code{php-fpm}) -User who can speak to the php-fpm socket. -@item @code{socket-group} (default: @code{php-fpm}) -Group that can speak to the php-fpm socket. -@item @code{pid-file} (default: @code{(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. -@item @code{log-file} (default: @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.log")}) -Log for the php-fpm master process. -@item @code{process-manager} (default: @code{(php-fpm-dynamic-process-manager-configuration)}) -Detailed settings for the php-fpm process manager. Must be either: -@table @asis -@item @code{<php-fpm-dynamic-process-manager-configuration>} -@item @code{<php-fpm-static-process-manager-configuration>} -@item @code{<php-fpm-on-demand-process-manager-configuration>} -@end table -@item @code{display-errors} (default @code{#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. -@item @code{timezone} (default @code{#f}) -Specifies @code{php_admin_value[date.timezone]} parameter. -@item @code{workers-logfile} (default @code{(string-append "/var/log/php" (version-major (package-version php)) "-fpm.www.log")}) -This file will log the @code{stderr} outputs of php worker processes. Can -be set to @code{#f} to disable logging. -@item @code{file} (default @code{#f}) -An optional override of the whole configuration. You can use the -@code{mixed-text-file} function or an absolute filepath for it. -@end table -@end deftp - -@deftp {Data type} php-fpm-dynamic-process-manager-configuration -Data Type for the @code{dynamic} php-fpm process manager. With the -@code{dynamic} process manager, spare worker processes are kept around based -on it's configured limits. -@table @asis -@item @code{max-children} (default: @code{5}) -Maximum of worker processes. -@item @code{start-servers} (default: @code{2}) -How many worker processes should be started on start-up. -@item @code{min-spare-servers} (default: @code{1}) -How many spare worker processes should be kept around at minimum. -@item @code{max-spare-servers} (default: @code{3}) -How many spare worker processes should be kept around at maximum. -@end table -@end deftp - -@deftp {Data type} php-fpm-static-process-manager-configuration -Data Type for the @code{static} php-fpm process manager. With the -@code{static} process manager, an unchanging number of worker processes are -created. -@table @asis -@item @code{max-children} (default: @code{5}) -Maximum of worker processes. -@end table -@end deftp - -@deftp {Data type} php-fpm-on-demand-process-manager-configuration -Data Type for the @code{on-demand} php-fpm process manager. With the -@code{on-demand} process manager, worker processes are only created as -requests arrive. -@table @asis -@item @code{max-children} (default: @code{5}) -Maximum of worker processes. -@item @code{process-idle-timeout} (default: @code{10}) -The time in seconds after which a process with no requests is killed. -@end table -@end deftp - - -@deffn {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 @code{nginx-server-configuration}. -@end deffn - -A simple services setup for nginx with php can look like this: -@example -(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)) -@end example - -@cindex cat-avatar-generator -The cat avatar generator is a simple service to demonstrate the use of -php-fpm in @code{Nginx}. It is used to generate cat avatar from a seed, for -instance the hash of a user's email address. - -@deffn {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 @code{configuration}. -It extends the nginx configuration to add a server block that serves -@code{package}, a version of cat-avatar-generator. During execution, -cat-avatar-generator will be able to use @code{cache-dir} as its cache -directory. -@end deffn - -A simple setup for cat-avatar-generator can look like this: -@example -(services (cons* (cat-avatar-generator-service - #:configuration - (nginx-server-configuration - (server-name '("example.com")))) - ... - %base-services)) -@end example - -@subsubheading Hpcguix-web - -@cindex hpcguix-web -The @uref{hpcguix-web, https://github.com/UMCUGenetics/hpcguix-web/} program -is a customizable web interface to browse Guix packages, initially designed -for users of high-performance computing (HPC) clusters. - -@defvr {Scheme Variable} hpcguix-web-service-type -The service type for @code{hpcguix-web}. -@end defvr - -@deftp {Data Type} hpcguix-web-configuration -Data type for the hpcguix-web service configuration. - -@table @asis -@item @code{specs} -A gexp (@pxref{G-Ausdrücke}) specifying the hpcguix-web service -configuration. The main items available in this spec are: - -@table @asis -@item @code{title-prefix} (Vorgabe: @code{"hpcguix | "}) -Das Präfix der Webseitentitel. - -@item @code{guix-command} (Vorgabe: @code{"guix"}) -Der @command{guix}-Befehl. - -@item @code{package-filter-proc} (Vorgabe: @code{(const #t)}) -Eine Prozedur, die festlegt, wie anzuzeigende Pakete gefiltert werden. - -@item @code{package-page-extension-proc} (Vorgabe: @code{(const '())}) -Extension package for @code{hpcguix-web}. - -@item @code{menu} (Vorgabe: @code{'()}) -Additional entry in page @code{menu}. - -@item @code{channels} (Vorgabe: @code{%default-channels}) -List of channels from which the package list is built (@pxref{Kanäle}). - -@item @code{package-list-expiration} (Vorgabe: @code{(* 12 3600)}) -The expiration time, in seconds, after which the package list is rebuilt -from the latest instances of the given channels. -@end table - -See the hpcguix-web repository for a -@uref{https://github.com/UMCUGenetics/hpcguix-web/blob/master/hpcweb-configuration.scm, -complete example}. - -@item @code{package} (Vorgabe: @code{hpcguix-web}) -Das hpcguix-web-Paket, was benutzt werden soll. -@end table -@end deftp - -A typical hpcguix-web service declaration looks like this: - -@example -(service hpcguix-web-service-type - (hpcguix-web-configuration - (specs - #~(define site-config - (hpcweb-configuration - (title-prefix "Guix-HPC - ") - (menu '(("/about" "ABOUT")))))))) -@end example - -@quotation Anmerkung -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 @file{/etc/ssl/certs} contains those -certificates. - -Thus, make sure to add @code{nss-certs} or another certificate package to -the @code{packages} field of your configuration. @ref{X.509-Zertifikate}, -for more information on X.509 certificates. -@end quotation - -@node Zertifikatsdienste -@subsection Zertifikatsdienste - -@cindex Web -@cindex HTTP, HTTPS -@cindex Let's Encrypt -@cindex TLS certificates -The @code{(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. - -@url{https://letsencrypt.org/, Let's Encrypt} provides the @code{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: @url{https://acme-v01.api.letsencrypt.org/directory}. - -@defvr {Scheme Variable} certbot-service-type -A service type for the @code{certbot} Let's Encrypt client. Its value must -be a @code{certbot-configuration} record as in this example: - -@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"))))))) -@end example - -See below for details about @code{certbot-configuration}. -@end defvr - -@deftp {Data Type} certbot-configuration -Data type representing the configuration of the @code{certbot} service. -This type has the following parameters: - -@table @asis -@item @code{package} (default: @code{certbot}) -The certbot package to use. - -@item @code{webroot} (default: @code{/var/www}) -The directory from which to serve the Let's Encrypt challenge/response -files. - -@item @code{certificates} (default: @code{()}) -A list of @code{certificates-configuration}s for which to generate -certificates and request signatures. Each certificate has a @code{name} and -several @code{domains}. - -@item @code{email} -Mandatory email used for registration, recovery contact, and important -account notifications. - -@item @code{rsa-key-size} (default: @code{2048}) -Size of the RSA key. - -@item @code{default-location} (default: @i{see below}) -The default @code{nginx-location-configuration}. Because @code{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 @code{nginx} web service with -an @code{nginx-server-configuration} listening on the @var{domains} on port -80, and which has a @code{nginx-location-configuration} for the -@code{/.well-known/} URI path subspace used by Let's Encrypt. @xref{Web-Dienste}, for more on these nginx configuration data types. - -Requests to other URL paths will be matched by the @code{default-location}, -which if present is added to all @code{nginx-server-configuration}s. - -By default, the @code{default-location} will issue a redirect from -@code{http://@var{domain}/...} to @code{https://@var{domain}/...}, leaving -you to define what to serve on your site via @code{https}. - -Pass @code{#f} to not issue a default location. -@end table -@end deftp - -@deftp {Data Type} certificate-configuration -Data type representing the configuration of a certificate. This type has -the following parameters: - -@table @asis -@item @code{name} (default: @i{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 -@code{certbot certificates}. - -Its default is the first provided domain. - -@item @code{domains} (default: @code{()}) -The first domain provided will be the subject CN of the certificate, and all -domains will be Subject Alternative Names on the certificate. - -@item @code{deploy-hook} (default: @code{#f}) -Command to be run in a shell once for each successfully issued certificate. -For this command, the shell variable @code{$RENEWED_LINEAGE} will point to -the config live subdirectory (for example, -@samp{"/etc/letsencrypt/live/example.com"}) containing the new certificates -and keys; the shell variable @code{$RENEWED_DOMAINS} will contain a -space-delimited list of renewed certificate domains (for example, -@samp{"example.com www.example.com"}. - -@end table -@end deftp - -For each @code{certificate-configuration}, the certificate is saved to -@code{/etc/letsencrypt/live/@var{name}/fullchain.pem} and the key is saved -to @code{/etc/letsencrypt/live/@var{name}/privkey.pem}. -@node DNS-Dienste -@subsection DNS-Dienste -@cindex DNS (domain name system) -@cindex domain name system (DNS) - -The @code{(gnu services dns)} module provides services related to the -@dfn{domain name system} (DNS). It provides a server service for hosting an -@emph{authoritative} DNS server for multiple zones, slave or master. This -service uses @uref{https://www.knot-dns.cz/, Knot DNS}. And also a caching -and forwarding DNS server for the LAN, which uses -@uref{http://www.thekelleys.org.uk/dnsmasq/doc.html, dnsmasq}. - -@subsubheading Knot-Dienst - -An example configuration of an authoritative server for two zones, one -master and one slave, is: - -@lisp -(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))) -@end lisp - -@deffn {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: -@end deffn - -@deftp {Data Type} knot-key-configuration -Data type representing a key. This type has the following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for other configuration fields to refer to this key. IDs must -be unique and must not be empty. - -@item @code{algorithm} (default: @code{#f}) -The algorithm to use. Choose between @code{#f}, @code{'hmac-md5}, -@code{'hmac-sha1}, @code{'hmac-sha224}, @code{'hmac-sha256}, -@code{'hmac-sha384} and @code{'hmac-sha512}. - -@item @code{secret} (default: @code{""}) -The secret key itself. - -@end table -@end deftp - -@deftp {Data Type} knot-acl-configuration -Data type representing an Access Control List (ACL) configuration. This -type has the following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for ether configuration fields to refer to this key. IDs must -be unique and must not be empty. - -@item @code{address} (default: @code{'()}) -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. - -@item @code{key} (default: @code{'()}) -An ordered list of references to keys represented with strings. The string -must match a key ID defined in a @code{knot-key-configuration}. No key -means that a key is not require to match that ACL. - -@item @code{action} (default: @code{'()}) -An ordered list of actions that are permitted or forbidden by this ACL. -Possible values are lists of zero or more elements from @code{'transfer}, -@code{'notify} and @code{'update}. - -@item @code{deny?} (default: @code{#f}) -When true, the ACL defines restrictions. Listed actions are forbidden. -When false, listed actions are allowed. - -@end table -@end deftp - -@deftp {Data Type} zone-entry -Data type represnting a record entry in a zone file. This type has the -following parameters: - -@table @asis -@item @code{name} (default: @code{"@@"}) -The name of the record. @code{"@@"} refers to the origin of the zone. -Names are relative to the origin of the zone. For example, in the -@code{example.org} zone, @code{"ns.example.org"} actually refers to -@code{ns.example.org.example.org}. Names ending with a dot are absolute, -which means that @code{"ns.example.org."} refers to @code{ns.example.org}. - -@item @code{ttl} (default: @code{""}) -The Time-To-Live (TTL) of this record. If not set, the default TTL is used. - -@item @code{class} (default: @code{"IN"}) -The class of the record. Knot currently supports only @code{"IN"} and -partially @code{"CH"}. - -@item @code{type} (default: @code{"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. - -@item @code{data} (default: @code{""}) -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. - -@end table -@end deftp - -@deftp {Data Type} zone-file -Data type representing the content of a zone file. This type has the -following parameters: - -@table @asis -@item @code{entries} (default: @code{'()}) -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 @code{define-zone-entries} to define a object -containing the list of entries more easily, that you can later pass to the -@code{entries} field of the @code{zone-file}. - -@item @code{origin} (default: @code{""}) -The name of your zone. This parameter cannot be empty. - -@item @code{ns} (default: @code{"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. - -@item @code{mail} (default: @code{"hostmaster"}) -An email address people can contact you at, as the owner of the zone. This -is translated as @code{<mail>@@<origin>}. - -@item @code{serial} (default: @code{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 @emph{never} decreases. -Always increment it when you make a change in your zone. - -@item @code{refresh} (default: @code{(* 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 -@code{(string->duration)}. - -@item @code{retry} (default: @code{(* 15 60)}) -The period after which a slave will retry to contact its master when it -fails to do so a first time. - -@item @code{expiry} (default: @code{(* 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. - -@item @code{nx} (default: @code{3600}) -Default TTL of inexistant records. This delay is usually short because you -want your new domains to reach everyone quickly. - -@end table -@end deftp - -@deftp {Data Type} knot-remote-configuration -Data type representing a remote configuration. This type has the following -parameters: - -@table @asis -@item @code{id} (default: @code{""}) -An identifier for other configuration fields to refer to this remote. IDs -must be unique and must not be empty. - -@item @code{address} (default: @code{'()}) -An ordered list of destination IP addresses. Addresses are tried in -sequence. An optional port can be given with the @@ separator. For -instance: @code{(list "1.2.3.4" "2.3.4.5@@53")}. Default port is 53. - -@item @code{via} (default: @code{'()}) -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. - -@item @code{key} (default: @code{#f}) -A reference to a key, that is a string containing the identifier of a key -defined in a @code{knot-key-configuration} field. - -@end table -@end deftp - -@deftp {Data Type} knot-keystore-configuration -Data type representing a keystore to hold dnssec keys. This type has the -following parameters: - -@table @asis -@item @code{id} (default: @code{""}) -The id of the keystore. It must not be empty. - -@item @code{backend} (default: @code{'pem}) -The backend to store the keys in. Can be @code{'pem} or @code{'pkcs11}. - -@item @code{config} (default: @code{"/var/lib/knot/keys/keys"}) -The configuration string of the backend. An example for the PKCS#11 is: -@code{"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. - -@end table -@end deftp - -@deftp {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: - -@table @asis -@item @code{id} (default: @code{""}) -The id of the policy. It must not be empty. - -@item @code{keystore} (default: @code{"default"}) -A reference to a keystore, that is a string containing the identifier of a -keystore defined in a @code{knot-keystore-configuration} field. The -@code{"default"} identifier means the default keystore (a kasp database that -was setup by this service). - -@item @code{manual?} (default: @code{#f}) -Whether the key management is manual or automatic. - -@item @code{single-type-signing?} (default: @code{#f}) -When @code{#t}, use the Single-Type Signing Scheme. - -@item @code{algorithm} (default: @code{"ecdsap256sha256"}) -An algorithm of signing keys and issued signatures. - -@item @code{ksk-size} (default: @code{256}) -The length of the KSK. Note that this value is correct for the default -algorithm, but would be unsecure for other algorithms. - -@item @code{zsk-size} (default: @code{256}) -The length of the ZSK. Note that this value is correct for the default -algorithm, but would be unsecure for other algorithms. - -@item @code{dnskey-ttl} (default: @code{'default}) -The TTL value for DNSKEY records added into zone apex. The special -@code{'default} value means same as the zone SOA TTL. - -@item @code{zsk-lifetime} (default: @code{(* 30 24 3600)}) -The period between ZSK publication and the next rollover initiation. - -@item @code{propagation-delay} (default: @code{(* 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. - -@item @code{rrsig-lifetime} (default: @code{(* 14 24 3600)}) -A validity period of newly issued signatures. - -@item @code{rrsig-refresh} (default: @code{(* 7 24 3600)}) -A period how long before a signature expiration the signature will be -refreshed. - -@item @code{nsec3?} (default: @code{#f}) -When @code{#t}, NSEC3 will be used instead of NSEC. - -@item @code{nsec3-iterations} (default: @code{5}) -The number of additional times the hashing is performed. - -@item @code{nsec3-salt-length} (default: @code{8}) -The length of a salt field in octets, which is appended to the original -owner name before hashing. - -@item @code{nsec3-salt-lifetime} (default: @code{(* 30 24 3600)}) -The validity period of newly issued salt field. - -@end table -@end deftp - -@deftp {Data Type} knot-zone-configuration -Data type representing a zone served by Knot. This type has the following -parameters: - -@table @asis -@item @code{domain} (default: @code{""}) -The domain served by this configuration. It must not be empty. - -@item @code{file} (default: @code{""}) -The file where this zone is saved. This parameter is ignored by master -zones. Empty means default location that depends on the domain name. - -@item @code{zone} (default: @code{(zone-file)}) -The content of the zone file. This parameter is ignored by slave zones. It -must contain a zone-file record. - -@item @code{master} (default: @code{'()}) -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. - -@item @code{ddns-master} (default: @code{#f}) -The main master. When empty, it defaults to the first master in the list of -masters. - -@item @code{notify} (default: @code{'()}) -A list of slave remote identifiers. - -@item @code{acl} (default: @code{'()}) -A list of acl identifiers. - -@item @code{semantic-checks?} (default: @code{#f}) -When set, this adds more semantic checks to the zone. - -@item @code{disable-any?} (default: @code{#f}) -When set, this forbids queries of the ANY type. - -@item @code{zonefile-sync} (default: @code{0}) -The delay between a modification in memory and on disk. 0 means immediate -synchronization. - -@item @code{serial-policy} (default: @code{'increment}) -A policy between @code{'increment} and @code{'unixtime}. - -@end table -@end deftp - -@deftp {Data Type} knot-configuration -Data type representing the Knot configuration. This type has the following -parameters: - -@table @asis -@item @code{knot} (default: @code{knot}) -The Knot package. - -@item @code{run-directory} (default: @code{"/var/run/knot"}) -The run directory. This directory will be used for pid file and sockets. - -@item @code{listen-v4} (default: @code{"0.0.0.0"}) -An ip address on which to listen. - -@item @code{listen-v6} (default: @code{"::"}) -An ip address on which to listen. - -@item @code{listen-port} (default: @code{53}) -A port on which to listen. - -@item @code{keys} (default: @code{'()}) -The list of knot-key-configuration used by this configuration. - -@item @code{acls} (default: @code{'()}) -The list of knot-acl-configuration used by this configuration. - -@item @code{remotes} (default: @code{'()}) -The list of knot-remote-configuration used by this configuration. - -@item @code{zones} (default: @code{'()}) -The list of knot-zone-configuration used by this configuration. - -@end table -@end deftp - -@subsubheading Dnsmasq-Dienst - -@deffn {Scheme Variable} dnsmasq-service-type -This is the type of the dnsmasq service, whose value should be an -@code{dnsmasq-configuration} object as in this example: - -@example -(service dnsmasq-service-type - (dnsmasq-configuration - (no-resolv? #t) - (servers '("192.168.1.1")))) -@end example -@end deffn - -@deftp {Datentyp} dnsmasq-configuration -Repräsentiert die dnsmasq-Konfiguration. - -@table @asis -@item @code{package} (Vorgabe: @var{dnsmasq}) -Package object of the dnsmasq server. - -@item @code{no-hosts?} (Vorgabe: @code{#f}) -When true, don't read the hostnames in /etc/hosts. - -@item @code{port} (Vorgabe: @code{53}) -The port to listen on. Setting this to zero completely disables DNS -responses, leaving only DHCP and/or TFTP functions. - -@item @code{local-service?} (Vorgabe: @code{#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. - -@item @code{listen-addresses} (Vorgabe: @code{'()}) -Listen on the given IP addresses. - -@item @code{resolv-file} (Vorgabe: @code{"/etc/resolv.conf"}) -The file to read the IP address of the upstream nameservers from. - -@item @code{no-resolv?} (Vorgabe: @code{#f}) -When true, don't read @var{resolv-file}. - -@item @code{servers} (default: @code{'()}) -Specify IP address of upstream servers directly. - -@item @code{cache-size} (Vorgabe: @code{150}) -Set the size of dnsmasq's cache. Setting the cache size to zero disables -caching. - -@item @code{negative-cache?} (Vorgabe: @code{#t}) -When false, disable negative caching. - -@end table -@end deftp - -@subsubheading ddclient-Dienst - -@cindex ddclient -The ddclient service described below runs the ddclient daemon, which takes -care of automatically updating DNS entries for service providers such as -@uref{https://dyn.com/dns/, Dyn}. - -The following example show instantiates the service with its default -configuration: - -@example -(service ddclient-service-type) -@end example - -Note that ddclient needs to access credentials that are stored in a -@dfn{secret file}, by default @file{/etc/ddclient/secrets} (see -@code{secret-file} below.) You are expected to create this file manually, -in an ``out-of-band'' fashion (you @emph{could} make this file part of the -service configuration, for instance by using @code{plain-file}, but it will -be world-readable @i{via} @file{/gnu/store}.) See the examples in the -@file{share/ddclient} directory of the @code{ddclient} package. - -@c %start of fragment - -Available @code{ddclient-configuration} fields are: - -@deftypevr {@code{ddclient-configuration} parameter} package ddclient -Das ddclient-Paket. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} integer daemon -The period after which ddclient will retry to check IP and domain name. - -Defaults to @samp{300}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} boolean syslog -Use syslog for the output. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string mail -Mail to user. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string mail-failure -Den Nutzer per Mail bei fehlgeschlagenen Aktualisierungen benachrichtigen. - -Defaults to @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string pid -PID-Datei für den ddclient. - -Defaults to @samp{"/var/run/ddclient/ddclient.pid"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} boolean ssl -Enable SSL support. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string user -Specifies the user name or ID that is used when running ddclient program. - -Defaults to @samp{"ddclient"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string group -Group of the user who will run the ddclient program. - -Defaults to @samp{"ddclient"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} string secret-file -Secret file which will be appended to @file{ddclient.conf} file. This file -contains credentials for use by ddclient. You are expected to create it -manually. - -Defaults to @samp{"/etc/ddclient/secrets.conf"}. - -@end deftypevr - -@deftypevr {@code{ddclient-configuration} parameter} list extra-options -Extra options will be appended to @file{ddclient.conf} file. - -Defaults to @samp{()}. - -@end deftypevr - - -@c %end of fragment - - -@node VPN-Dienste -@subsection VPN-Dienste -@cindex VPN (virtual private network) -@cindex virtual private network (VPN) - -The @code{(gnu services vpn)} module provides services related to -@dfn{virtual private networks} (VPNs). It provides a @emph{client} service -for your machine to connect to a VPN, and a @emph{servire} service for your -machine to host a VPN. Both services use @uref{https://openvpn.net/, -OpenVPN}. - -@deffn {Scheme Procedure} openvpn-client-service @ - [#:config (openvpn-client-configuration)] - -Return a service that runs @command{openvpn}, a VPN daemon, as a client. -@end deffn - -@deffn {Scheme Procedure} openvpn-server-service @ - [#:config (openvpn-server-configuration)] - -Return a service that runs @command{openvpn}, a VPN daemon, as a server. - -Both can be run simultaneously. -@end deffn - -@c %automatically generated documentation - -Available @code{openvpn-client-configuration} fields are: - -@deftypevr {@code{openvpn-client-configuration} parameter} package openvpn -The OpenVPN package. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} string pid-file -The OpenVPN pid file. - -Defaults to @samp{"/var/run/openvpn/openvpn.pid"}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} proto proto -The protocol (UDP or TCP) used to open a channel between clients and -servers. - -Defaults to @samp{udp}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} dev dev -The device type used to represent the VPN connection. - -Defaults to @samp{tun}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} string ca -The certificate authority to check connections against. - -Defaults to @samp{"/etc/openvpn/ca.crt"}. - -@end deftypevr - -@deftypevr {@code{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 @code{ca}. - -Defaults to @samp{"/etc/openvpn/client.crt"}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} string key -The key of the machine the daemon is running on. It must be the key whose -certificate is @code{cert}. - -Defaults to @samp{"/etc/openvpn/client.key"}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} boolean comp-lzo? -Whether to use the lzo compression algorithm. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} boolean persist-key? -Don't re-read key files across SIGUSR1 or --ping-restart. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} number verbosity -Verbosity level. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} key-usage verify-key-usage? -Whether to check the server certificate has server usage extension. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} bind bind? -Bind to a specific local port number. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} resolv-retry resolv-retry? -Retry resolving server address. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-client-configuration} parameter} openvpn-remote-list remote -A list of remote servers to connect to. - -Defaults to @samp{()}. - -Available @code{openvpn-remote-configuration} fields are: - -@deftypevr {@code{openvpn-remote-configuration} parameter} string name -Server name. - -Defaults to @samp{"my-server"}. - -@end deftypevr - -@deftypevr {@code{openvpn-remote-configuration} parameter} number port -Port number the server listens to. - -Defaults to @samp{1194}. - -@end deftypevr - -@end deftypevr -@c %end of automatic openvpn-client documentation - -@c %automatically generated documentation - -Available @code{openvpn-server-configuration} fields are: - -@deftypevr {@code{openvpn-server-configuration} parameter} package openvpn -The OpenVPN package. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string pid-file -The OpenVPN pid file. - -Defaults to @samp{"/var/run/openvpn/openvpn.pid"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} proto proto -The protocol (UDP or TCP) used to open a channel between clients and -servers. - -Defaults to @samp{udp}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} dev dev -The device type used to represent the VPN connection. - -Defaults to @samp{tun}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string ca -The certificate authority to check connections against. - -Defaults to @samp{"/etc/openvpn/ca.crt"}. - -@end deftypevr - -@deftypevr {@code{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 @code{ca}. - -Defaults to @samp{"/etc/openvpn/client.crt"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string key -The key of the machine the daemon is running on. It must be the key whose -certificate is @code{cert}. - -Defaults to @samp{"/etc/openvpn/client.key"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} boolean comp-lzo? -Whether to use the lzo compression algorithm. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} boolean persist-key? -Don't re-read key files across SIGUSR1 or --ping-restart. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#t}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} number verbosity -Verbosity level. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} number port -Specifies the port number on which the server listens. - -Defaults to @samp{1194}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} ip-mask server -An ip and mask specifying the subnet inside the virtual network. - -Defaults to @samp{"10.8.0.0 255.255.255.0"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} cidr6 server-ipv6 -A CIDR notation specifying the IPv6 subnet inside the virtual network. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string dh -The Diffie-Hellman parameters file. - -Defaults to @samp{"/etc/openvpn/dh2048.pem"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} string ifconfig-pool-persist -The file that records client IPs. - -Defaults to @samp{"/etc/openvpn/ipp.txt"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} gateway redirect-gateway? -When true, the server will act as a gateway for its clients. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} boolean client-to-client? -When true, clients are allowed to talk to each other inside the VPN. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{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. @code{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. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} number max-clients -The maximum number of clients. - -Defaults to @samp{100}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"/var/run/openvpn/status"}. - -@end deftypevr - -@deftypevr {@code{openvpn-server-configuration} parameter} openvpn-ccd-list client-config-dir -The list of configuration for some clients. - -Defaults to @samp{()}. - -Available @code{openvpn-ccd-configuration} fields are: - -@deftypevr {@code{openvpn-ccd-configuration} parameter} string name -Client name. - -Defaults to @samp{"client"}. - -@end deftypevr - -@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask iroute -Client own network - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{openvpn-ccd-configuration} parameter} ip-mask ifconfig-push -Client VPN IP. - -Defaults to @samp{#f}. - -@end deftypevr - -@end deftypevr - - -@c %end of automatic openvpn-server documentation - - -@node Network File System -@subsection Network File System -@cindex NFS - -The @code{(gnu services nfs)} module provides the following services, which -are most commonly used in relation to mounting or exporting directory trees -as @dfn{network file systems} (NFS). - -@subsubheading RPC Bind Service -@cindex rpcbind - -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. - -@defvr {Scheme Variable} rpcbind-service-type -A service type for the RPC portmapper daemon. -@end defvr - - -@deftp {Data Type} rpcbind-configuration -Data type representing the configuration of the RPC Bind Service. This type -has the following parameters: -@table @asis -@item @code{rpcbind} (default: @code{rpcbind}) -The rpcbind package to use. - -@item @code{warm-start?} (default: @code{#t}) -If this parameter is @code{#t}, then the daemon will read a state file on -startup thus reloading state information saved by a previous instance. -@end table -@end deftp - - -@subsubheading Pipefs Pseudo File System -@cindex pipefs -@cindex rpc_pipefs - -The pipefs file system is used to transfer NFS related data between the -kernel and user space programs. - -@defvr {Scheme Variable} pipefs-service-type -A service type for the pipefs pseudo file system. -@end defvr - -@deftp {Data Type} pipefs-configuration -Data type representing the configuration of the pipefs pseudo file system -service. This type has the following parameters: -@table @asis -@item @code{mount-point} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory to which the file system is to be attached. -@end table -@end deftp - - -@subsubheading GSS Daemon Service -@cindex GSSD -@cindex GSS -@cindex global security system - -The @dfn{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 @command{kinit} or automatically at login time using PAM services -(@pxref{Kerberos-Dienste}). - -@defvr {Scheme Variable} gss-service-type -A service type for the Global Security System (GSS) daemon. -@end defvr - -@deftp {Data Type} gss-configuration -Data type representing the configuration of the GSS daemon service. This -type has the following parameters: -@table @asis -@item @code{nfs-utils} (default: @code{nfs-utils}) -The package in which the @command{rpc.gssd} command is to be found. - -@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory where the pipefs file system is mounted. - -@end table -@end deftp - - -@subsubheading IDMAP Daemon Service -@cindex idmapd -@cindex name mapper - -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. - -@defvr {Scheme Variable} idmap-service-type -A service type for the Identity Mapper (IDMAP) daemon. -@end defvr - -@deftp {Data Type} idmap-configuration -Data type representing the configuration of the IDMAP daemon service. This -type has the following parameters: -@table @asis -@item @code{nfs-utils} (default: @code{nfs-utils}) -The package in which the @command{rpc.idmapd} command is to be found. - -@item @code{pipefs-directory} (default: @code{"/var/lib/nfs/rpc_pipefs"}) -The directory where the pipefs file system is mounted. - -@item @code{domain} (default: @code{#f}) -The local NFSv4 domain name. This must be a string or @code{#f}. If it is -@code{#f} then the daemon will use the host's fully qualified domain name. - -@end table -@end deftp - -@node Kontinuierliche Integration -@subsection Kontinuierliche Integration - -@cindex continuous integration -@uref{https://git.savannah.gnu.org/cgit/guix/guix-cuirass.git, Cuirass} is a -continuous integration tool for Guix. It can be used both for development -and for providing substitutes to others (@pxref{Substitute}). - -The @code{(gnu services cuirass)} module provides the following service. - -@defvr {Scheme Procedure} cuirass-service-type -The type of the Cuirass service. Its value must be a -@code{cuirass-configuration} object, as described below. -@end defvr - -To add build jobs, you have to set the @code{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 @code{"custom-packages"} input, which is the equivalent -of @code{GUIX_PACKAGE_PATH}. - -@example -(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))) -@end example - -While information related to build jobs is located directly in the -specifications, global settings for the @command{cuirass} process are -accessible in other @code{cuirass-configuration} fields. - -@deftp {Data Type} cuirass-configuration -Data type representing the configuration of Cuirass. - -@table @asis -@item @code{log-file} (default: @code{"/var/log/cuirass.log"}) -Location of the log file. - -@item @code{cache-directory} (default: @code{"/var/cache/cuirass"}) -Location of the repository cache. - -@item @code{user} (default: @code{"cuirass"}) -Owner of the @code{cuirass} process. - -@item @code{group} (default: @code{"cuirass"}) -Owner's group of the @code{cuirass} process. - -@item @code{interval} (default: @code{60}) -Number of seconds between the poll of the repositories followed by the -Cuirass jobs. - -@item @code{database} (Vorgabe: @code{"/var/lib/cuirass/cuirass.db"}) -Location of sqlite database which contains the build results and previously -added specifications. - -@item @code{ttl} (Vorgabe: @code{(* 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 @var{ttl} seconds. - -@item @code{port} (default: @code{8081}) -Port number used by the HTTP server. - -@item --listen=@var{Host} -Listen on the network interface for @var{host}. The default is to accept -connections from localhost. - -@item @code{specifications} (default: @code{#~'()}) -A gexp (@pxref{G-Ausdrücke}) that evaluates to a list of specifications, -where a specification is an association list (@pxref{Associations Lists,,, -guile, GNU Guile Reference Manual}) whose keys are keywords -(@code{#:keyword-example}) as shown in the example above. - -@item @code{use-substitutes?} (default: @code{#f}) -This allows using substitutes to avoid building every dependencies of a job -from source. - -@item @code{one-shot?} (default: @code{#f}) -Only evaluate specifications and build derivations once. - -@item @code{fallback?} (default: @code{#f}) -When substituting a pre-built binary fails, fall back to building packages -locally. - -@item @code{cuirass} (default: @code{cuirass}) -The Cuirass package to use. -@end table -@end deftp - -@node Dienste zur Stromverbrauchsverwaltung -@subsection Dienste zur Stromverbrauchsverwaltung - -@cindex tlp -@cindex power management with TLP -@subsubheading TLP-Daemon - -The @code{(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 -@code{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 @uref{http://linrunner.de/en/tlp/tlp.html, TLP -home page}. - -@deffn {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: -@example -(service tlp-service-type) -@end example -@end deffn - -By default TLP does not need much configuration but most TLP parameters can -be tweaked using @code{tlp-configuration}. - -Each parameter definition is preceded by its type; for example, -@samp{boolean foo} indicates that the @code{foo} parameter should be -specified as a boolean. Types starting with @code{maybe-} denote parameters -that won't show up in TLP config file when their value is @code{'disabled}. - -@c The following documentation was initially generated by -@c (generate-tlp-documentation) in (gnu services pm). Manually maintained -@c documentation is better, so we shouldn't hesitate to edit below as -@c needed. However if the change you want to make to this documentation -@c can be done in an automated way, it's probably easier to change -@c (generate-documentation) than to make it below and have to deal with -@c the churn as TLP updates. - -Available @code{tlp-configuration} fields are: - -@deftypevr {@code{tlp-configuration} parameter} package tlp -The TLP package. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean tlp-enable? -Set to true if you wish to enable TLP. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string tlp-default-mode -Default mode when no power supply can be detected. Alternatives are AC and -BAT. - -Defaults to @samp{"AC"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{0}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer disk-idle-secs-on-bat -Same as @code{disk-idle-ac} but on BAT mode. - -Defaults to @samp{2}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-ac -Dirty pages flushing periodicity, expressed in seconds. - -Defaults to @samp{15}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer max-lost-work-secs-on-bat -Same as @code{max-lost-work-secs-on-ac} but on BAT mode. - -Defaults to @samp{60}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list cpu-scaling-governor-on-bat -Same as @code{cpu-scaling-governor-on-ac} but on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-min-perf-on-bat -Same as @code{cpu-min-perf-on-ac} on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-non-negative-integer cpu-max-perf-on-bat -Same as @code{cpu-max-perf-on-ac} on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-ac? -Enable CPU turbo boost feature on AC mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean cpu-boost-on-bat? -Same as @code{cpu-boost-on-ac?} on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean sched-powersave-on-bat? -Same as @code{sched-powersave-on-ac?} but on BAT mode. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean nmi-watchdog? -Enable Linux kernel NMI watchdog. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-string phc-controls -For Linux kernels with PHC patch applied, change CPU voltages. An example -value would be @samp{"F:V F:V F:V F:V"}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"performance"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string energy-perf-policy-on-bat -Same as @code{energy-perf-policy-ac} but on BAT mode. - -Defaults to @samp{"powersave"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disks-devices -Hard disk devices. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-ac -Hard disk advanced power management level. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list disk-apm-level-on-bat -Same as @code{disk-apm-bat} but on BAT mode. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list disk-spindown-timeout-on-bat -Same as @code{disk-spindown-timeout-on-ac} but on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"max_performance"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string sata-linkpwr-on-bat -Same as @code{sata-linkpwr-ac} but on BAT mode. - -Defaults to @samp{"min_power"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-string sata-linkpwr-blacklist -Exclude specified SATA host devices for link power management. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{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 @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-on-off-boolean ahci-runtime-pm-on-bat? -Same as @code{ahci-runtime-pm-on-ac} on BAT mode. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer ahci-runtime-pm-timeout -Seconds of inactivity before disk is suspended. - -Defaults to @samp{15}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-ac -PCI Express Active State Power Management level. Alternatives are default, -performance, powersave. - -Defaults to @samp{"performance"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string pcie-aspm-on-bat -Same as @code{pcie-aspm-ac} but on BAT mode. - -Defaults to @samp{"powersave"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-ac -Radeon graphics clock speed level. Alternatives are low, mid, high, auto, -default. - -Defaults to @samp{"high"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-power-profile-on-bat -Same as @code{radeon-power-ac} but on BAT mode. - -Defaults to @samp{"low"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-ac -Radeon dynamic power management method (DPM). Alternatives are battery, -performance. - -Defaults to @samp{"performance"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-state-on-bat -Same as @code{radeon-dpm-state-ac} but on BAT mode. - -Defaults to @samp{"battery"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-ac -Radeon DPM performance level. Alternatives are auto, low, high. - -Defaults to @samp{"auto"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string radeon-dpm-perf-level-on-bat -Same as @code{radeon-dpm-perf-ac} but on BAT mode. - -Defaults to @samp{"auto"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-ac? -Wifi power saving mode. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} on-off-boolean wifi-pwr-on-bat? -Same as @code{wifi-power-ac?} but on BAT mode. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} y-n-boolean wol-disable? -Disable wake on LAN. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{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 @samp{0}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} non-negative-integer sound-power-save-on-bat -Same as @code{sound-powersave-ac} but on BAT mode. - -Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} y-n-boolean sound-power-save-controller? -Disable controller in powersaving mode on Intel HDA devices. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string bay-device -Name of the optical drive device to power off. - -Defaults to @samp{"sr0"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-ac -Runtime Power Management for PCI(e) bus devices. Alternatives are on and -auto. - -Defaults to @samp{"on"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} string runtime-pm-on-bat -Same as @code{runtime-pm-ac} but on BAT mode. - -Defaults to @samp{"auto"}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean runtime-pm-all? -Runtime Power Management for all PCI(e) bus devices, except blacklisted -ones. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-space-separated-string-list runtime-pm-blacklist -Exclude specified PCI(e) device addresses from Runtime Power Management. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} space-separated-string-list runtime-pm-driver-blacklist -Exclude PCI(e) devices assigned to the specified drivers from Runtime Power -Management. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean usb-autosuspend? -Enable USB autosuspend feature. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-blacklist -Exclude specified devices from USB autosuspend. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean usb-blacklist-wwan? -Exclude WWAN devices from USB autosuspend. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-string usb-whitelist -Include specified devices into USB autosuspend, even if they are already -excluded by the driver or via @code{usb-blacklist-wwan?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} maybe-boolean usb-autosuspend-disable-on-shutdown? -Enable USB autosuspend before shutdown. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{tlp-configuration} parameter} boolean restore-device-state-on-startup? -Restore radio device state (bluetooth, wifi, wwan) from previous shutdown on -system startup. - -Defaults to @samp{#f}. - -@end deftypevr - -@cindex thermald -@cindex CPU frequency scaling with thermald -@subsubheading Thermald-Daemon - -The @code{(gnu services pm)} module provides an interface to thermald, a CPU -frequency scaling service which helps prevent overheating. - -@defvr {Scheme Variable} thermald-service-type -This is the service type for @uref{https://01.org/linux-thermal-daemon/, -thermald}, the Linux Thermal Daemon, which is responsible for controlling -the thermal state of processors and preventing overheating. -@end defvr - -@deftp {Data Type} thermald-configuration -Data type representing the configuration of @code{thermald-service-type}. - -@table @asis -@item @code{ignore-cpuid-check?} (default: @code{#f}) -Ignore cpuid check for supported CPU models. - -@item @code{thermald} (default: @var{thermald}) -Package object of thermald. - -@end table -@end deftp - -@node Audio-Dienste -@subsection Audio-Dienste - -The @code{(gnu services audio)} module provides a service to start MPD (the -Music Player Daemon). - -@cindex mpd -@subsubheading 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 @code{mpd} as user -@code{"bob"} on port @code{6666}. It uses pulseaudio for output. - -@example -(service mpd-service-type - (mpd-configuration - (user "bob") - (port "6666"))) -@end example - -@defvr {Scheme Variable} mpd-service-type -The service type for @command{mpd} -@end defvr - -@deftp {Data Type} mpd-configuration -Data type representing the configuration of @command{mpd}. - -@table @asis -@item @code{user} (default: @code{"mpd"}) -The user to run mpd as. - -@item @code{music-dir} (default: @code{"~/Music"}) -The directory to scan for music files. - -@item @code{playlist-dir} (default: @code{"~/.mpd/playlists"}) -The directory to store playlists. - -@item @code{port} (default: @code{"6600"}) -The port to run mpd on. - -@item @code{address} (default: @code{"any"}) -The address that mpd will bind to. To use a Unix domain socket, an absolute -path can be specified here. - -@end table -@end deftp - -@node Virtualisierungsdienste -@subsection Virtualization services - -The @code{(gnu services virtualization)} module provides services for the -libvirt and virtlog daemons, as well as other virtualization-related -services. - -@subsubheading Libvirt daemon -@code{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. - -@deffn {Scheme Variable} libvirt-service-type -This is the type of the @uref{https://libvirt.org, libvirt daemon}. Its -value must be a @code{libvirt-configuration}. - -@example -(service libvirt-service-type - (libvirt-configuration - (unix-sock-group "libvirt") - (tls-port "16555"))) -@end example -@end deffn - -@c Auto-generated with (generate-libvirt-documentation) -Available @code{libvirt-configuration} fields are: - -@deftypevr {@code{libvirt-configuration} parameter} package libvirt -Libvirt package. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tls? -Flag listening for secure TLS connections on the public TCP/IP port. must -set @code{listen} for this to have any effect. - -It is necessary to setup a CA and issue server certificates before using -this capability. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean listen-tcp? -Listen for unencrypted TCP connections on the public TCP/IP port. must set -@code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string tls-port -Port for accepting secure TLS connections This can be a port number, or -service name - -Defaults to @samp{"16514"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string tcp-port -Port for accepting insecure TCP connections This can be a port number, or -service name - -Defaults to @samp{"16509"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string listen-addr -IP address or hostname used for client connections. - -Defaults to @samp{"0.0.0.0"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string mdns-name -Default mDNS advertisement name. This must be unique on the immediate -broadcast network. - -Defaults to @samp{"Virtualization Host <hostname>"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"root"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"0777"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"0770"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"0777"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string unix-sock-dir -The directory in which sockets will be found/created. - -Defaults to @samp{"/var/run/libvirt"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string auth-unix-ro -Authentication scheme for UNIX read-only sockets. By default socket -permissions allow anyone to connect - -Defaults to @samp{"polkit"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"polkit"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"sasl"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"none"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{()}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string key-file -Server key file path. If set to an empty string, then no private key is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string cert-file -Server key file path. If set to an empty string, then no certificate is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string ca-file -Server key file path. If set to an empty string, then no CA certificate is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string crl-file -Certificate revocation list path. If set to an empty string, then no CRL is -loaded. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-list tls-allowed-dn-list -Whitelist of allowed x509 Distinguished Name. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{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 @samp{()}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"NORMAL"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-clients -Maximum number of concurrent client connections to allow over all sockets -combined. - -Defaults to @samp{5000}. - -@end deftypevr - -@deftypevr {@code{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 @samp{1000}. - -@end deftypevr - -@deftypevr {@code{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 @samp{20}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer min-workers -Number of workers to start up initially. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-workers -Maximum number of worker threads. - -If the number of active clients exceeds @code{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 @samp{20}. - -@end deftypevr - -@deftypevr {@code{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 @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer max-requests -Total global limit on concurrent RPC calls. - -Defaults to @samp{20}. - -@end deftypevr - -@deftypevr {@code{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 @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-min-workers -Same as @code{min-workers} but for the admin interface. - -Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-workers -Same as @code{max-workers} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-clients -Same as @code{max-clients} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-queued-clients -Same as @code{max-queued-clients} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-max-client-requests -Same as @code{max-client-requests} but for the admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer log-level -Logging level. 4 errors, 3 warnings, 2 information, 1 debug. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{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: - -@itemize @bullet -@item -x:name - -@item -x:+name - -@end itemize - -where @code{name} is a string which is matched against the category given in -the @code{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 @code{x} is the minimal level where matching messages -should be logged: - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple filters can be defined in a single filters statement, they just -need to be separated by spaces. - -Defaults to @samp{"3:remote 4:event"}. - -@end deftypevr - -@deftypevr {@code{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: - -@table @code -@item x:stderr -output goes to stderr - -@item x:syslog:name -use syslog for the output and use the given name as the ident - -@item x:file:file_path -output to a file, with the given filepath - -@item x:journald -output to journald logging system - -@end table - -In all case the x prefix is the minimal level, acting as a filter - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple outputs can be defined, they just need to be separated by spaces. - -Defaults to @samp{"3:stderr"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer audit-level -Allows usage of the auditing subsystem to be altered - -@itemize @bullet -@item -0: disable all auditing - -@item -1: enable auditing, only if enabled on host - -@item -2: enable auditing, and exit if disabled on host. - -@end itemize - -Defaults to @samp{1}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} boolean audit-logging -Send audit messages via libvirt logging infrastructure. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} optional-string host-uuid -Host UUID. UUID must not have all digits be the same. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} string host-uuid-source -Source to read host UUID. - -@itemize @bullet -@item -@code{smbios}: fetch the UUID from @code{dmidecode -s system-uuid} - -@item -@code{machine-id}: fetch the UUID from @code{/etc/machine-id} - -@end itemize - -If @code{dmidecode} does not provide a valid UUID a temporary UUID will be -generated. - -Defaults to @samp{"smbios"}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer keepalive-interval -A keepalive message is sent to a client after @code{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 @samp{5}. - -@end deftypevr - -@deftypevr {@code{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 -@code{keepalive_interval * (keepalive_count + 1)} seconds since the last -message received from the client. When @code{keepalive-count} is set to 0, -connections will be automatically closed after @code{keepalive-interval} -seconds of inactivity without sending any keepalive messages. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-interval -Same as above but for admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer admin-keepalive-count -Same as above but for admin interface. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{libvirt-configuration} parameter} integer ovs-timeout -Timeout for Open vSwitch calls. - -The @code{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 @samp{5}. - -@end deftypevr - -@c %end of autogenerated docs - -@subsubheading 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 @code{libvirtd}. By maintaining the logs in a -standalone daemon, the main @code{libvirtd} daemon can be restarted without -risk of losing logs. The @code{virtlogd} daemon has the ability to re-exec() -itself upon receiving @code{SIGUSR1}, to allow live upgrades without -downtime. - -@deffn {Scheme Variable} virtlog-service-type -This is the type of the virtlog daemon. Its value must be a -@code{virtlog-configuration}. - -@example -(service virtlog-service-type - (virtlog-configuration - (max-clients 1000))) -@end example -@end deffn - -@deftypevr {@code{virtlog-configuration} parameter} integer log-level -Logging level. 4 errors, 3 warnings, 2 information, 1 debug. - -Defaults to @samp{3}. - -@end deftypevr - -@deftypevr {@code{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: - -@itemize @bullet -@item -x:name - -@item -x:+name - -@end itemize - -where @code{name} is a string which is matched against the category given in -the @code{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 @code{x} is the minimal level where matching messages -should be logged: - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple filters can be defined in a single filters statement, they just -need to be separated by spaces. - -Defaults to @samp{"3:remote 4:event"}. - -@end deftypevr - -@deftypevr {@code{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: - -@table @code -@item x:stderr -output goes to stderr - -@item x:syslog:name -use syslog for the output and use the given name as the ident - -@item x:file:file_path -output to a file, with the given filepath - -@item x:journald -output to journald logging system - -@end table - -In all case the x prefix is the minimal level, acting as a filter - -@itemize @bullet -@item -1: DEBUG - -@item -2: INFO - -@item -3: WARNING - -@item -4: ERROR - -@end itemize - -Multiple outputs can be defined, they just need to be separated by spaces. - -Defaults to @samp{"3:stderr"}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-clients -Maximum number of concurrent client connections to allow over all sockets -combined. - -Defaults to @samp{1024}. - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-size -Maximum file size before rolling over. - -Defaults to @samp{2MB} - -@end deftypevr - -@deftypevr {@code{virtlog-configuration} parameter} integer max-backups -Maximum number of backup files to keep. - -Defaults to @samp{3} - -@end deftypevr - -@subsubheading Transparent Emulation with QEMU - -@cindex emulation -@cindex @code{binfmt_misc} -@code{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 @uref{https://www.qemu.org, QEMU} emulator and the -@code{binfmt_misc} feature of the kernel Linux. - -@defvr {Scheme Variable} qemu-binfmt-service-type -This is the type of the QEMU/binfmt service for transparent emulation. Its -value must be a @code{qemu-binfmt-configuration} object, which specifies the -QEMU package to use as well as the architecture we want to emulated: - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm" "aarch64" "ppc")))) -@end example - -In this example, we enable transparent emulation for the ARM and aarch64 -platforms. Running @code{herd stop qemu-binfmt} turns it off, and running -@code{herd start qemu-binfmt} turns it back on (@pxref{Invoking herd, the -@command{herd} command,, shepherd, The GNU Shepherd Manual}). -@end defvr - -@deftp {Data Type} qemu-binfmt-configuration -This is the configuration for the @code{qemu-binfmt} service. - -@table @asis -@item @code{platforms} (default: @code{'()}) -The list of emulated QEMU platforms. Each item must be a @dfn{platform -object} as returned by @code{lookup-qemu-platforms} (see below). - -@item @code{guix-support?} (default: @code{#f}) -When it is true, QEMU and all its dependencies are added to the build -environment of @command{guix-daemon} (@pxref{Aufruf des guix-daemon, -@code{--chroot-directory} option}). This allows the @code{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: - -@example -(service qemu-binfmt-service-type - (qemu-binfmt-configuration - (platforms (lookup-qemu-platforms "arm")) - (guix-support? #t))) -@end example - -You can run: - -@example -guix build -s armhf-linux inkscape -@end example - -@noindent -and it will build Inkscape for ARMv7 @emph{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! - -@item @code{qemu} (default: @code{qemu}) -The QEMU package to use. -@end table -@end deftp - -@deffn {Scheme Procedure} lookup-qemu-platforms @var{platforms}@dots{} -Return the list of QEMU platform objects corresponding to -@var{platforms}@dots{}. @var{platforms} must be a list of strings -corresponding to platform names, such as @code{"arm"}, @code{"sparc"}, -@code{"mips64el"}, and so on. -@end deffn - -@deffn {Scheme Procedure} qemu-platform? @var{obj} -Return true if @var{obj} is a platform object. -@end deffn - -@deffn {Scheme Procedure} qemu-platform-name @var{platform} -Return the name of @var{platform}---a string such as @code{"arm"}. -@end deffn - -@node Versionskontrolldienste -@subsection Versionskontrolldienste - -The @code{(gnu services version-control)} module provides a service to allow -remote access to local Git repositories. There are three options: the -@code{git-daemon-service}, which provides access to repositories via the -@code{git://} unsecured TCP-based protocol, extending the @code{nginx} web -server to proxy some requests to @code{git-http-backend}, or providing a web -interface with @code{cgit-service-type}. - -@deffn {Scheme Procedure} git-daemon-service [#:config (git-daemon-configuration)] - -Return a service that runs @command{git daemon}, a simple TCP server to -expose repositories over the Git protocol for anonymous access. - -The optional @var{config} argument should be a -@code{<git-daemon-configuration>} object, by default it allows read-only -access to exported@footnote{By creating the magic file -"git-daemon-export-ok" in the repository directory.} repositories under -@file{/srv/git}. - -@end deffn - -@deftp {Data Type} git-daemon-configuration -Data type representing the configuration for @code{git-daemon-service}. - -@table @asis -@item @code{package} (default: @var{git}) -Package object of the Git distributed version control system. - -@item @code{export-all?} (default: @var{#f}) -Whether to allow access for all Git repositories, even if they do not have -the @file{git-daemon-export-ok} file. - -@item @code{base-path} (default: @file{/srv/git}) -Whether to remap all the path requests as relative to the given path. If -you run git daemon with @var{(base-path "/srv/git")} on example.com, then if -you later try to pull @code{git://example.com/hello.git}, git daemon will -interpret the path as @code{/srv/git/hello.git}. - -@item @code{user-path} (default: @var{#f}) -Whether to allow @code{~user} notation to be used in requests. When -specified with empty string, requests to @code{git://host/~alice/foo} is -taken as a request to access @code{foo} repository in the home directory of -user @code{alice}. If @var{(user-path "path")} is specified, the same -request is taken as a request to access @code{path/foo} repository in the -home directory of user @code{alice}. - -@item @code{listen} (default: @var{'()}) -Whether to listen on specific IP addresses or hostnames, defaults to all. - -@item @code{port} (default: @var{#f}) -Whether to listen on an alternative port, which defaults to 9418. - -@item @code{whitelist} (default: @var{'()}) -If not empty, only allow access to this list of directories. - -@item @code{extra-options} (default: @var{'()}) -Extra options will be passed to @code{git daemon}, please run @command{man -git-daemon} for more information. - -@end table -@end deftp - -The @code{git://} protocol lacks authentication. When you pull from a -repository fetched via @code{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 @code{https}. Although Git -allows you to serve repositories using unsophisticated file-based web -servers, there is a faster protocol implemented by the -@code{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. @xref{Web-Dienste}, for more on running the necessary @code{fcgiwrap} daemon. - -Guix has a separate configuration data type for serving Git repositories -over HTTP. - -@deftp {Data Type} git-http-configuration -Data type representing the configuration for @code{git-http-service}. - -@table @asis -@item @code{package} (default: @var{git}) -Package object of the Git distributed version control system. - -@item @code{git-root} (default: @file{/srv/git}) -Directory containing the Git repositories to expose to the world. - -@item @code{export-all?} (default: @var{#f}) -Whether to expose access for all Git repositories in @var{git-root}, even if -they do not have the @file{git-daemon-export-ok} file. - -@item @code{uri-path} (default: @file{/git/}) -Path prefix for Git access. With the default @code{/git/} prefix, this will -map @code{http://@var{server}/git/@var{repo}.git} to -@code{/srv/git/@var{repo}.git}. Requests whose URI paths do not begin with -this prefix are not passed on to this Git instance. - -@item @code{fcgiwrap-socket} (default: @code{127.0.0.1:9000}) -The socket on which the @code{fcgiwrap} daemon is listening. @xref{Web-Dienste}. -@end table -@end deftp - -There is no @code{git-http-service-type}, currently; instead you can create -an @code{nginx-location-configuration} from a @code{git-http-configuration} -and then add that location to a web server. - -@deffn {Scheme Procedure} git-http-nginx-location-configuration @ - [config=(git-http-configuration)] Compute an -@code{nginx-location-configuration} that corresponds to the given Git http -configuration. An example nginx service definition to serve the default -@file{/srv/git} over HTTPS might be: - -@example -(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 "/")))))))))) -@end example - -This example assumes that you are using Let's Encrypt to get your TLS -certificate. @xref{Zertifikatsdienste}. The default @code{certbot} -service will redirect all HTTP traffic on @code{git.my-host.org} to HTTPS. -You will also need to add an @code{fcgiwrap} proxy to your system services. -@xref{Web-Dienste}. -@end deffn - -@subsubheading Cgit Service - -@cindex Cgit service -@cindex Git, web interface -@uref{https://git.zx2c4.com/cgit/, 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 (@code{http://localhost:80}). - -@example -(service cgit-service-type) -@end example - -The @code{file-object} type designates either a file-like object -(@pxref{G-Ausdrücke, file-like objects}) or a string. - -@c %start of fragment - -Available @code{cgit-configuration} fields are: - -@deftypevr {@code{cgit-configuration} parameter} package package -The CGIT package. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} nginx-server-configuration-list nginx -NGINX configuration. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object auth-filter -Specifies a command that will be invoked for authenticating repository -access. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string branch-sort -Flag which, when set to @samp{age}, enables date ordering in the branch ref -list, and when set @samp{name} enables ordering by branch name. - -Defaults to @samp{"name"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string cache-root -Path used to store the cgit cache entries. - -Defaults to @samp{"/var/cache/cgit"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{-1}. - -@end deftypevr - -@deftypevr {@code{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 @samp{5}. - -@end deftypevr - -@deftypevr {@code{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 @samp{5}. - -@end deftypevr - -@deftypevr {@code{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 @samp{5}. - -@end deftypevr - -@deftypevr {@code{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 @samp{15}. - -@end deftypevr - -@deftypevr {@code{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 @samp{15}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-snapshot-ttl -Number which specifies the time-to-live, in minutes, for the cached version -of snapshots. - -Defaults to @samp{5}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer cache-size -The maximum number of entries in the cgit cache. When set to @samp{0}, -caching is disabled. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean case-sensitive-sort? -Sort items in the repo list case sensitively. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{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 @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list clone-url -List of @code{clone-url} templates. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object commit-filter -Command which will be invoked to format commit messages. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string commit-sort -Flag which, when set to @samp{date}, enables strict date ordering in the -commit log, and when set to @samp{topo} enables strict topological ordering. - -Defaults to @samp{"git log"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object css -URL which specifies the css document to include in all cgit pages. - -Defaults to @samp{"/share/cgit/cgit.css"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean embedded? -Flag which, when set to @samp{#t}, will make cgit generate a HTML fragment -suitable for embedding in other HTML pages. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-commit-graph? -Flag which, when set to @samp{#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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-filter-overrides? -Flag which, when set to @samp{#t}, allows all filter settings to be -overridden in repository-specific cgitrc files. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-follow-links? -Flag which, when set to @samp{#t}, allows users to follow a file in the log -view. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-http-clone? -If set to @samp{#t}, cgit will act as an dumb HTTP endpoint for Git clones. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-links? -Flag which, when set to @samp{#t}, will make cgit generate extra links -"summary", "commit", "tree" for each repo in the repository index. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-index-owner? -Flag which, when set to @samp{#t}, will make cgit display the owner of each -repo in the repository index. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-filecount? -Flag which, when set to @samp{#t}, will make cgit print the number of -modified files for each commit on the repository log page. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-log-linecount? -Flag which, when set to @samp{#t}, will make cgit print the number of added -and removed lines for each commit on the repository log page. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-remote-branches? -Flag which, when set to @code{#t}, will make cgit display remote branches in -the summary and refs views. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-subject-links? -Flag which, when set to @code{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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-html-serving? -Flag which, when set to @samp{#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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-tree-linenumbers? -Flag which, when set to @samp{#t}, will make cgit generate linenumber links -for plaintext blobs printed in the tree view. - -Defaults to @samp{#t}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean enable-git-config? -Flag which, when set to @samp{#f}, will allow cgit to use Git config to set -any repo specific settings. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object favicon -URL used as link to a shortcut icon for cgit. - -Defaults to @samp{"/favicon.ico"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object include -Name of a configfile to include before the rest of the current config- file -is parsed. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean local-time? -Flag which, if set to @samp{#t}, makes cgit print commit and tag times in -the servers timezone. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{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 @samp{"/share/cgit/cgit.png"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string logo-link -URL loaded when clicking on the cgit logo image. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object owner-filter -Command which will be invoked to format the Owner column of the main page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-atom-items -Number of items to display in atom feeds view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-commit-count -Number of entries to list per page in "log" view. - -Defaults to @samp{50}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-message-length -Number of commit message characters to display in "log" view. - -Defaults to @samp{80}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-repo-count -Specifies the number of entries to list per page on the repository index -page. - -Defaults to @samp{50}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-repodesc-length -Specifies the maximum number of repo description characters to display on -the repository index page. - -Defaults to @samp{80}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer max-blob-size -Specifies the maximum size of a blob to display HTML for in KBytes. - -Defaults to @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string max-stats -Maximum statistics period. Valid values are @samp{week},@samp{month}, -@samp{quarter} and @samp{year}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} mimetype-alist mimetype -Mimetype for the specified filename extension. - -Defaults to @samp{((gif "image/gif") (html "text/html") (jpg "image/jpeg") -(jpeg "image/jpeg") (pdf "application/pdf") (png "image/png") (svg -"image/svg+xml"))}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object mimetype-file -Specifies the file to use for automatic mimetype lookup. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean nocache? -If set to the value @samp{#t} caching will be disabled. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean noplainemail? -If set to @samp{#t} showing full author email addresses will be disabled. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean noheader? -Flag which, when set to @samp{#t}, will make cgit omit the standard header -on all pages. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} project-list project-list -A list of subdirectories inside of @code{repository-directory}, relative to -it, that should loaded as Git repositories. An empty list means that all -subdirectories will be loaded. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object readme -Text which will be used as default value for @code{cgit-repo-readme}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean remove-suffix? -If set to @code{#t} and @code{repository-directory} is enabled, if any -repositories are found with a suffix of @code{.git}, this suffix will be -removed for the URL and name. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer renamelimit -Maximum number of files to consider when detecting renames. - -Defaults to @samp{-1}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string repository-sort -The way in which repositories in each section are sorted. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} robots-list robots -Text used as content for the @code{robots} meta-tag. - -Defaults to @samp{("noindex" "nofollow")}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-desc -Text printed below the heading on the repository index page. - -Defaults to @samp{"a fast webinterface for the git dscm"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string root-title -Text printed as heading on the repository index page. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean scan-hidden-path -If set to @samp{#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 @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list snapshots -Text which specifies the default set of snapshot formats that cgit generates -links for. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} repository-directory repository-directory -Name of the directory to scan for repositories (represents -@code{scan-path}). - -Defaults to @samp{"/srv/git"}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string section-sort -Flag which, when set to @samp{1}, will sort the sections on the repository -listing by name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{0}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} boolean side-by-side-diffs? -If set to @samp{#t} shows side-by-side diffs instead of unidiffs per -default. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} file-object source-filter -Specifies a command which will be invoked to format plaintext blobs in the -tree view. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-branches -Specifies the number of branches to display in the repository "summary" -view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-log -Specifies the number of log entries to display in the repository "summary" -view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} integer summary-tags -Specifies the number of tags to display in the repository "summary" view. - -Defaults to @samp{10}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} string virtual-root -URL which, if specified, will be used as root for all cgit links. - -Defaults to @samp{"/"}. - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} repository-cgit-configuration-list repositories -A list of @dfn{cgit-repo} records to use with config. - -Defaults to @samp{()}. - -Available @code{repository-cgit-configuration} fields are: - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list snapshots -A mask of snapshot formats for this repo that cgit generates links for, -restricted by the global @code{snapshots} setting. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object source-filter -Override the default @code{source-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string url -The relative URL used to access the repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object about-filter -Override the default @code{about-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string branch-sort -Flag which, when set to @samp{age}, enables date ordering in the branch ref -list, and when set to @samp{name} enables ordering by branch name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list clone-url -A list of URLs which can be used to clone repo. - -Defaults to @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object commit-filter -Override the default @code{commit-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string commit-sort -Flag which, when set to @samp{date}, enables strict date ordering in the -commit log, and when set to @samp{topo} enables strict topological ordering. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string desc -The value to show as repository description. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string homepage -The value to show as repository homepage. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object email-filter -Override the default @code{email-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-commit-graph? -A flag which can be used to disable the global setting -@code{enable-commit-graph?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-filecount? -A flag which can be used to disable the global setting -@code{enable-log-filecount?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-log-linecount? -A flag which can be used to disable the global setting -@code{enable-log-linecount?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-remote-branches? -Flag which, when set to @code{#t}, will make cgit display remote branches in -the summary and refs views. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-subject-links? -A flag which can be used to override the global setting -@code{enable-subject-links?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} maybe-repo-boolean enable-html-serving? -A flag which can be used to override the global setting -@code{enable-html-serving?}. - -Defaults to @samp{disabled}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean hide? -Flag which, when set to @code{#t}, hides the repository from the repository -index. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-boolean ignore? -Flag which, when set to @samp{#t}, ignores the repository. - -Defaults to @samp{#f}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string logo-link -URL loaded when clicking on the cgit logo image. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-file-object owner-filter -Override the default @code{owner-filter}. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{()}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string max-stats -Override the default maximum statistics period. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string name -The value to show as repository name. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string owner -A value used to identify the owner of the repository. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-string path -An absolute path to the repository directory. - -Defaults to @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{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 @samp{""}. - -@end deftypevr - -@deftypevr {@code{repository-cgit-configuration} parameter} repo-list extra-options -Extra options will be appended to cgitrc file. - -Defaults to @samp{()}. - -@end deftypevr - -@end deftypevr - -@deftypevr {@code{cgit-configuration} parameter} list extra-options -Extra options will be appended to cgitrc file. - -Defaults to @samp{()}. - -@end deftypevr - - -@c %end of fragment - -However, it could be that you just want to get a @code{cgitrc} up and -running. In that case, you can pass an @code{opaque-cgit-configuration} as -a record to @code{cgit-service-type}. As its name indicates, an opaque -configuration does not have easy reflective capabilities. - -Available @code{opaque-cgit-configuration} fields are: - -@deftypevr {@code{opaque-cgit-configuration} parameter} package cgit -The cgit package. -@end deftypevr - -@deftypevr {@code{opaque-cgit-configuration} parameter} string string -The contents of the @code{cgitrc}, as a string. -@end deftypevr - -For example, if your @code{cgitrc} is just the empty string, you could -instantiate a cgit service like this: - -@example -(service cgit-service-type - (opaque-cgit-configuration - (cgitrc ""))) -@end example - -@subsubheading Gitolite-Dienst - -@cindex Gitolite-Dienst -@cindex Git, hosting -@uref{http://gitolite.com/gitolite/, 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 @code{git} -user, and the provided SSH public key. - -@example -(service gitolite-service-type - (gitolite-configuration - (admin-pubkey (plain-file - "yourname.pub" - "ssh-rsa AAAA... guix@@example.com")))) -@end example - -Gitolite is configured through a special admin repository which you can -clone, for example, if you setup Gitolite on @code{example.com}, you would -run the following command to clone the admin repository. - -@example -git clone git@@example.com:gitolite-admin -@end example - -When the Gitolite service is activated, the provided @code{admin-pubkey} -will be inserted in to the @file{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''. - -@deftp {Datentyp} gitolite-configuration -Repräsentiert die Konfiguration vom @code{gitolite-service-type}. - -@table @asis -@item @code{package} (Vorgabe: @var{gitolite}) -Welches Gitolite-Paket benutzt werden soll. - -@item @code{user} (Vorgabe: @var{git}) -User to use for Gitolite. This will be user that you use when accessing -Gitolite over SSH. - -@item @code{group} (Vorgabe: @var{git}) -Group to use for Gitolite. - -@item @code{home-directory} (Vorgabe: @var{"/var/lib/gitolite"}) -Directory in which to store the Gitolite configuration and repositories. - -@item @code{rc-file} (Vorgabe: @var{(gitolite-rc-file)}) -A ``file-like'' object (@pxref{G-Ausdrücke, file-like objects}), -representing the configuration for Gitolite. - -@item @code{admin-pubkey} (Vorgabe: @var{#f}) -A ``file-like'' object (@pxref{G-Ausdrücke, file-like objects}) used to -setup Gitolite. This will be inserted in to the @file{keydir} directory -within the gitolite-admin repository. - -To specify the SSH key as a string, use the @code{plain-file} function. - -@example -(plain-file "yourname.pub" "ssh-rsa AAAA... guix@@example.com") -@end example - -@end table -@end deftp - -@deftp {Datentyp} gitolite-rc-file -Repräsentiert die Gitolie-RC-Datei. - -@table @asis -@item @code{umask} (Vorgabe: @code{#o0077}) -This controls the permissions Gitolite sets on the repositories and their -contents. - -A value like @code{#o0027} will give read access to the group used by -Gitolite (by default: @code{git}). This is necessary when using Gitolite -with software like cgit or gitweb. - -@item @code{git-config-keys} (Vorgabe: @code{""}) -Gitolite allows you to set git config values using the "config" -keyword. This setting allows control over the config keys to accept. - -@item @code{roles} (Vorgabe: @code{'(("READERS" . 1) ("WRITERS" . ))}) -Set the role names allowed to be used by users running the perms command. - -@item @code{enable} (default: @code{'("help" "desc" "info" "perms" "writable" "ssh-authkeys" "git-config" "daemon" "gitweb")}) -This setting controls the commands and features to enable within Gitolite. - -@end table -@end deftp - - -@node Spieldienste -@subsection Spieldienste - -@subsubheading The Battle for Wesnoth Service -@cindex wesnothd -@uref{https://wesnoth.org, The Battle for Wesnoth} is a fantasy, turn based -tactical strategy game, with several single player campaigns, and -multiplayer games (both networked and local). - -@defvar {Scheme Variable} wesnothd-service-type -Service type for the wesnothd service. Its value must be a -@code{wesnothd-configuration} object. To run wesnothd in the default -configuration, instantiate it as: - -@example -(service wesnothd-service-type) -@end example -@end defvar - -@deftp {Data Type} wesnothd-configuration -Data type representing the configuration of @command{wesnothd}. - -@table @asis -@item @code{package} (default: @code{wesnoth-server}) -The wesnoth server package to use. - -@item @code{port} (default: @code{15000}) -The port to bind the server to. -@end table -@end deftp - -@node Verschiedene Dienste -@subsection Verschiedene Dienste - -@cindex fingerprint -@subsubheading Fingerabdrucklese-Dienst - -The @code{(gnu services fingerprint)} module provides a DBus service to read -and identify fingerprints via a fingerprint sensor. - -@defvr {Scheme Variable} fprintd-service-type -The service type for @command{fprintd}, which provides the fingerprint -reading capability. - -@example -(service fprintd-service-type) -@end example -@end defvr - -@cindex sysctl -@subsubheading System Control Service - -The @code{(gnu services sysctl)} provides a service to configure kernel -parameters at boot. - -@defvr {Scheme Variable} sysctl-service-type -The service type for @command{sysctl}, which modifies kernel parameters -under @file{/proc/sys/}. To enable IPv4 forwarding, it can be instantiated -as: - -@example -(service sysctl-service-type - (sysctl-configuration - (settings '(("net.ipv4.ip_forward" . "1"))))) -@end example -@end defvr - -@deftp {Data Type} sysctl-configuration -The data type representing the configuration of @command{sysctl}. - -@table @asis -@item @code{sysctl} (default: @code{(file-append procps "/sbin/sysctl"}) -The @command{sysctl} executable to use. - -@item @code{settings} (default: @code{'()}) -An association list specifies kernel parameters and their values. -@end table -@end deftp - -@cindex pcscd -@subsubheading PC/SC Smart Card Daemon Service - -The @code{(gnu services security-token)} module provides the following -service to run @command{pcscd}, the PC/SC Smart Card Daemon. -@command{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. - -@defvr {Scheme Variable} pcscd-service-type -Service type for the @command{pcscd} service. Its value must be a -@code{pcscd-configuration} object. To run pcscd in the default -configuration, instantiate it as: - -@example -(service pcscd-service-type) -@end example -@end defvr - -@deftp {Datentyp} pcscd-configuration -Repräsentiert die Konfiguration von @command{pcscd}. - -@table @asis -@item @code{pcsc-lite} (Vorgabe: @code{pcsc-lite}) -The pcsc-lite package that provides pcscd. -@item @code{usb-drivers} (Vorgabe: @code{(list ccid)}) -List of packages that provide USB drivers to pcscd. Drivers are expected to -be under @file{pcsc/drivers} in the store directory of the package. -@end table -@end deftp - -@cindex lirc -@subsubheading Lirc Service - -The @code{(gnu services lirc)} module provides the following service. - -@deffn {Scheme Procedure} lirc-service [#:lirc lirc] @ - [#:device #f] [#:driver #f] [#:config-file #f] @ [#:extra-options '()] -Return a service that runs @url{http://www.lirc.org,LIRC}, a daemon that -decodes infrared signals from remote controls. - -Optionally, @var{device}, @var{driver} and @var{config-file} (configuration -file name) may be specified. See @command{lircd} manual for details. - -Finally, @var{extra-options} is a list of additional command-line options -passed to @command{lircd}. -@end deffn - -@cindex spice -@subsubheading Spice Service - -The @code{(gnu services spice)} module provides the following service. - -@deffn {Scheme Procedure} spice-vdagent-service [#:spice-vdagent] -Returns a service that runs @url{http://www.spice-space.org,VDAGENT}, a -daemon that enables sharing the clipboard with a vm and setting the guest -display resolution when the graphical console window resizes. -@end deffn - -@subsection Dictionary Services -@cindex dictionary -The @code{(gnu services dict)} module provides the following service: - -@deffn {Scheme Procedure} dicod-service [#:config (dicod-configuration)] -Return a service that runs the @command{dicod} daemon, an implementation of -DICT server (@pxref{Dicod,,, dico, GNU Dico Manual}). - -The optional @var{config} argument specifies the configuration for -@command{dicod}, which should be a @code{<dicod-configuration>} object, by -default it serves the GNU Collaborative International Dictonary of English. - -You can add @command{open localhost} to your @file{~/.dico} file to make -@code{localhost} the default server for @command{dico} client -(@pxref{Initialization File,,, dico, GNU Dico Manual}). -@end deffn - -@deftp {Data Type} dicod-configuration -Data type representing the configuration of dicod. - -@table @asis -@item @code{dico} (default: @var{dico}) -Package object of the GNU Dico dictionary server. - -@item @code{interfaces} (default: @var{'("localhost")}) -This is the list of IP addresses and ports and possibly socket file names to -listen to (@pxref{Server Settings, @code{listen} directive,, dico, GNU Dico -Manual}). - -@item @code{handlers} (default: @var{'()}) -List of @code{<dicod-handler>} objects denoting handlers (module instances). - -@item @code{databases} (default: @var{(list %dicod-database:gcide)}) -List of @code{<dicod-database>} objects denoting dictionaries to be served. -@end table -@end deftp - -@deftp {Data Type} dicod-handler -Data type representing a dictionary handler (module instance). - -@table @asis -@item @code{name} -Name of the handler (module instance). - -@item @code{module} (default: @var{#f}) -Name of the dicod module of the handler (instance). If it is @code{#f}, the -module has the same name as the handler. (@pxref{Module,,, dico, GNU Dico -Manual}). - -@item @code{options} -List of strings or gexps representing the arguments for the module handler -@end table -@end deftp - -@deftp {Data Type} dicod-database -Data type representing a dictionary database. - -@table @asis -@item @code{name} -Name of the database, will be used in DICT commands. - -@item @code{handler} -Name of the dicod handler (module instance) used by this database -(@pxref{Handlers,,, dico, GNU Dico Manual}). - -@item @code{complex?} (default: @var{#f}) -Whether the database configuration complex. The complex configuration will -need a corresponding @code{<dicod-handler>} object, otherwise not. - -@item @code{options} -List of strings or gexps representing the arguments for the database -(@pxref{Databases,,, dico, GNU Dico Manual}). -@end table -@end deftp - -@defvr {Scheme Variable} %dicod-database:gcide -A @code{<dicod-database>} object serving the GNU Collaborative International -Dictionary of English using the @code{gcide} package. -@end defvr - -The following is an example @code{dicod-service} configuration. - -@example -(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)))) -@end example - -@cindex Docker -@subsubheading Docker Service - -The @code{(gnu services docker)} module provides the following service. - -@defvr {Scheme Variable} docker-service-type - -This is the type of the service that runs -@url{http://www.docker.com,Docker}, a daemon that can execute application -bundles (sometimes referred to as ``containers'') in isolated environments. - -@end defvr - -@deftp {Data Type} docker-configuration -This is the data type representing the configuration of Docker and -Containerd. - -@table @asis - -@item @code{package} (default: @code{docker}) -The Docker package to use. - -@item @code{containerd} (default: @var{containerd}) -The Containerd package to use. - -@end table -@end deftp - -@node Setuid-Programme -@section Setuid-Programme - -@cindex setuid programs -Some programs need to run with ``root'' privileges, even when they are -launched by unprivileged users. A notorious example is the @command{passwd} -program, which users can run to change their password, and which needs to -access the @file{/etc/passwd} and @file{/etc/shadow} files---something -normally restricted to root, for obvious security reasons. To address that, -these executables are @dfn{setuid-root}, meaning that they always run with -root privileges (@pxref{How Change Persona,,, libc, The GNU C Library -Reference Manual}, for more info about the setuid mechanism.) - -The store itself @emph{cannot} contain setuid programs: that would be a -security issue since any user on the system can write derivations that -populate the store (@pxref{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 @emph{declare} which programs should -be setuid root. - -The @code{setuid-programs} field of an @code{operating-system} declaration -contains a list of G-expressions denoting the names of programs to be -setuid-root (@pxref{Das Konfigurationssystem nutzen}). For instance, the -@command{passwd} program, which is part of the Shadow package, can be -designated by this G-expression (@pxref{G-Ausdrücke}): - -@example -#~(string-append #$shadow "/bin/passwd") -@end example - -A default set of setuid programs is defined by the @code{%setuid-programs} -variable of the @code{(gnu system)} module. - -@defvr {Scheme Variable} %setuid-programs -A list of G-expressions denoting common programs that are setuid-root. - -The list includes commands such as @command{passwd}, @command{ping}, -@command{su}, and @command{sudo}. -@end defvr - -Under the hood, the actual setuid programs are created in the -@file{/run/setuid-programs} directory at system activation time. The files -in this directory refer to the ``real'' binaries, which are in the store. - -@node X.509-Zertifikate -@section X.509-Zertifikate - -@cindex HTTPS, Zertifikate -@cindex X.509-Zertifikate -@cindex TLS -Über HTTPS verfügbare Webserver (also HTTP mit gesicherter Transportschicht, -englisch »Transport-Layer Security«, kurz TLS) senden Client-Programmen ein -@dfn{X.509-Zertifikat}, mit dem der Client den Server dann -@emph{authentifizieren} kann. Dazu verifiziert der Client, dass das -Zertifikat des Servers von einer sogenannten Zertifizierungsstelle signiert -wurde (englisch @dfn{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@tie{}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 — @command{wget}, -@command{git}, @command{w3m} etc. — muss allerdings erst mitgeteilt werden, -wo die CA-Zertifikate installiert sind. - -@cindex @code{nss-certs} -In Guix, this is done by adding a package that provides certificates to the -@code{packages} field of the @code{operating-system} declaration -(@pxref{»operating-system«-Referenz}). Guix includes one such package, -@code{nss-certs}, which is a set of CA certificates provided as part of -Mozilla's Network Security Services. - -Beachten Sie, dass es @emph{nicht} zu den @var{%base-packages} gehört, Sie -es also ausdrücklich hinzufügen müssen. Das Verzeichnis -@file{/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 -@code{SSL_CERT_DIR} und @code{SSL_CERT_FILE}, manche Anwendungen benutzen -stattdessen aber ihre eigenen Umgebungsvariablen. Das Versionskontrollsystem -Git liest den Ort zum Beispiel aus der Umgebungsvariablen -@code{GIT_SSL_CAINFO} aus. Sie würden typischerweise also so etwas -ausführen: - -@example -$ 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" -@end example - -Ein weiteres Beispiel ist R, was voraussetzt, dass die Umgebungsvariable -@code{CURL_CA_BUNDLE} auf ein Zertifikatsbündel verweist, weshalb Sie etwas -wie hier ausführen müssten: - -@example -$ guix package -i nss-certs -$ export CURL_CA_BUNDLE="$HOME/.guix-profile/etc/ssl/certs/ca-certificates.crt" -@end example - -Für andere Anwendungen möchten Sie die Namen der benötigten -Umgebungsvariablen vielleicht in deren Dokumentation nachschlagen. - - -@node Name Service Switch -@section Name Service Switch - -@cindex Name Service Switch -@cindex NSS -The @code{(gnu system nss)} module provides bindings to the configuration -file of the libc @dfn{name service switch} or @dfn{NSS} (@pxref{NSS -Configuration File,,, libc, 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 (@pxref{Name Service Switch, System -Databases and Name Service Switch,, libc, 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 @code{name-service-switch} -field of @code{operating-system} declarations (@pxref{»operating-system«-Referenz, @code{name-service-switch}}). - -@cindex nss-mdns -@cindex .local, host name lookup -As an example, the declaration below configures the NSS to use the -@uref{http://0pointer.de/lennart/projects/nss-mdns/, @code{nss-mdns} -back-end}, which supports host name lookups over multicast DNS (mDNS) for -host names ending in @code{.local}: - -@example -(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"))))) -@end example - -Do not worry: the @code{%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 @code{.local} host lookup working. - -Note that, in this case, in addition to setting the -@code{name-service-switch} of the @code{operating-system} declaration, you -also need to use @code{avahi-service-type} (@pxref{Netzwerkdienste, -@code{avahi-service-type}}), or @var{%desktop-services}, which includes it -(@pxref{Desktop-Dienste}). Doing this makes @code{nss-mdns} accessible to -the name service cache daemon (@pxref{Basisdienste, @code{nscd-service}}). - -For convenience, the following variables provide typical NSS configurations. - -@defvr {Scheme Variable} %default-nss -This is the default name service switch configuration, a -@code{name-service-switch} object. -@end defvr - -@defvr {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 @code{.local}. -@end defvr - -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 (@pxref{NSS Configuration -File,,, libc, 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 @command{guix -system}. - -@deftp {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. - -@table @code -@item aliases -@itemx ethers -@itemx group -@itemx gshadow -@itemx hosts -@itemx initgroups -@itemx netgroup -@itemx networks -@itemx password -@itemx public-key -@itemx rpc -@itemx services -@itemx shadow -The system databases handled by the NSS. Each of these fields must be a -list of @code{<name-service>} objects (see below). -@end table -@end deftp - -@deftp {Data Type} name-service - -This is the data type representing an actual name service and the associated -lookup action. - -@table @code -@item name -A string denoting the name service (@pxref{Services in the NSS -configuration,,, libc, The GNU C Library Reference Manual}). - -Note that name services listed here must be visible to nscd. This is -achieved by passing the @code{#:name-services} argument to -@code{nscd-service} the list of packages providing the needed name services -(@pxref{Basisdienste, @code{nscd-service}}). - -@item reaction -An action specified using the @code{lookup-specification} macro -(@pxref{Actions in the NSS configuration,,, libc, The GNU C Library -Reference Manual}). For example: - -@example -(lookup-specification (unavailable => continue) - (success => return)) -@end example -@end table -@end deftp - -@node Initiale RAM-Disk -@section Initiale RAM-Disk - -@cindex initrd -@cindex initiale RAM-Disk -For bootstrapping purposes, the Linux-Libre kernel is passed an @dfn{initial -RAM disk}, or @dfn{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 @code{initrd-modules} field of an @code{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 @code{initrd-modules} should cover most use cases. For -example, assuming you need the @code{megaraid_sas} module in addition to the -default modules to be able to access your root file system, you would write: - -@example -(operating-system - ;; @dots{} - (initrd-modules (cons "megaraid_sas" %base-initrd-modules))) -@end example - -@defvr {Scheme Variable} %base-initrd-modules -This is the list of kernel modules included in the initrd by default. -@end defvr - -Furthermore, if you need lower-level customization, the @code{initrd} field -of an @code{operating-system} declaration allows you to specify which initrd -you would like to use. The @code{(gnu system linux-initrd)} module provides -three ways to build an initrd: the high-level @code{base-initrd} procedure -and the low-level @code{raw-initrd} and @code{expression->initrd} -procedures. - -The @code{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 @code{initrd} field of the operating system -declaration like this: - -@example -(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))) -@end example - -The @code{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 @code{base-initrd} procedure is built from @code{raw-initrd} procedure. -Unlike @code{base-initrd}, @code{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 @code{raw-initrd} is when a user has a -custom Linux kernel configuration and default kernel modules included by -@code{base-initrd} are not available. - -The initial RAM disk produced by @code{base-initrd} or @code{raw-initrd} -honors several options passed on the Linux kernel command line (that is, -arguments passed @i{via} the @code{linux} command of GRUB, or the -@code{-append} option of QEMU), notably: - -@table @code -@item --load=@var{boot} -Tell the initial RAM disk to load @var{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@tie{}Shepherd, the -initialization system. - -@item --root=@var{root} -Mount @var{root} as the root file system. @var{root} can be a device name -like @code{/dev/sda1}, a file system label, or a file system UUID. - -@item --system=@var{System} -Have @file{/run/booted-system} and @file{/run/current-system} point to -@var{system}. - -@item modprobe.blacklist=@var{modules}@dots{} -@cindex module, black-listing -@cindex black list, of kernel modules -Instruct the initial RAM disk as well as the @command{modprobe} command -(from the kmod package) to refuse to load @var{modules}. @var{modules} must -be a comma-separated list of module names---e.g., @code{usbkbd,9pnet}. - -@item --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 @dfn{boot-to-Guile}. The Schemer in you will love -it. @xref{Using Guile Interactively,,, guile, GNU Guile Reference Manual}, -for more information on Guile's REPL. - -@end table - -Now that you know all the features that initial RAM disks produced by -@code{base-initrd} and @code{raw-initrd} provide, here is how to use it and -customize it further. - -@cindex initrd -@cindex initiale RAM-Disk -@deffn {Scheme Procedure} raw-initrd @var{file-systems} @ - [#:linux-modules '()] [#:mapped-devices '()] @ [#:helper-packages '()] -[#:qemu-networking? #f] [#:volatile-root? #f] Return a derivation that -builds a raw initrd. @var{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 @code{--root}. @var{linux-modules} -is a list of kernel modules to be loaded at boot time. @var{mapped-devices} -is a list of device mappings to realize before @var{file-systems} are -mounted (@pxref{Zugeordnete Geräte}). @var{helper-packages} is a list of -packages to be copied in the initrd. It may include @code{e2fsck/static} or -other packages needed by the initrd to check the root file system. - -When @var{qemu-networking?} is true, set up networking with the standard -QEMU parameters. When @var{virtio?} is true, load additional modules so -that the initrd can be used as a QEMU guest with para-virtualized I/O -drivers. - -When @var{volatile-root?} is true, the root file system is writable but any -changes to it are lost. -@end deffn - -@deffn {Scheme Procedure} base-initrd @var{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 @var{linux}. @var{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 @code{--root}. -@var{mapped-devices} is a list of device mappings to realize before -@var{file-systems} are mounted. - -@var{qemu-networking?} and @var{volatile-root?} behaves as in -@code{raw-initrd}. - -The initrd is automatically populated with all the kernel modules necessary -for @var{file-systems} and for the given options. Additional kernel modules -can be listed in @var{linux-modules}. They will be added to the initrd, and -loaded at boot time in the order in which they appear. -@end deffn - -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 @code{expression->initrd} procedure builds such an -initrd, given the program to run in that initrd. - -@deffn {Scheme Procedure} expression->initrd @var{exp} @ - [#:guile %guile-static-stripped] [#:name "guile-initrd"] Return as a -file-like object a Linux initrd (a gzipped cpio archive) containing -@var{guile} and that evaluates @var{exp}, a G-expression, upon booting. All -the derivations referenced by @var{exp} are automatically copied to the -initrd. -@end deffn - -@node Bootloader-Konfiguration -@section Bootloader-Konfiguration - -@cindex bootloader -@cindex boot loader - -The operating system supports multiple bootloaders. The bootloader is -configured using @code{bootloader-configuration} declaration. All the -fields of this structure are bootloader agnostic except for one field, -@code{bootloader} that indicates the bootloader to be configured and -installed. - -Some of the bootloaders do not honor every field of -@code{bootloader-configuration}. For instance, the extlinux bootloader does -not support themes and thus ignores the @code{theme} field. - -@deftp {Data Type} bootloader-configuration -The type of a bootloader configuration declaration. - -@table @asis - -@item @code{bootloader} -@cindex EFI, bootloader -@cindex UEFI, bootloader -@cindex BIOS, bootloader -The bootloader to use, as a @code{bootloader} object. For now -@code{grub-bootloader}, @code{grub-efi-bootloader}, -@code{extlinux-bootloader} and @code{u-boot-bootloader} are supported. - -@vindex grub-efi-bootloader -@code{grub-efi-bootloader} allows to boot on modern systems using the -@dfn{Unified Extensible Firmware Interface} (UEFI). This is what you should -use if the installation image contains a @file{/sys/firmware/efi} directory -when you boot it on your system. - -@vindex grub-bootloader -@code{grub-bootloader} allows you to boot in particular Intel-based machines -in ``legacy'' BIOS mode. - -@cindex ARM, bootloaders -@cindex AArch64, bootloaders -Available bootloaders are described in @code{(gnu bootloader @dots{})} -modules. In particular, @code{(gnu bootloader u-boot)} contains definitions -of bootloaders for a wide range of ARM and AArch64 systems, using the -@uref{http://www.denx.de/wiki/U-Boot/, U-Boot bootloader}. - -@item @code{target} -This is a string denoting the target onto which to install the bootloader. - -The interpretation depends on the bootloader in question. For -@code{grub-bootloader}, for example, it should be a device name understood -by the bootloader @command{installer} command, such as @code{/dev/sda} or -@code{(hd0)} (@pxref{Invoking grub-install,,, grub, GNU GRUB Manual}). For -@code{grub-efi-bootloader}, it should be the mount point of the EFI file -system, usually @file{/boot/efi}. - -@item @code{menu-entries} (default: @code{()}) -A possibly empty list of @code{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. - -@item @code{default-entry} (default: @code{0}) -The index of the default boot menu entry. Index 0 is for the entry of the -current system. - -@item @code{timeout} (default: @code{5}) -The number of seconds to wait for keyboard input before booting. Set to 0 -to boot immediately, and to -1 to wait indefinitely. - -@item @code{theme} (default: @var{#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. - -@item @code{terminal-outputs} (default: @code{'gfxterm}) -The output terminals used for the bootloader boot menu, as a list of -symbols. GRUB accepts the values: @code{console}, @code{serial}, -@code{serial_@{0-3@}}, @code{gfxterm}, @code{vga_text}, @code{mda_text}, -@code{morse}, and @code{pkmodem}. This field corresponds to the GRUB -variable @code{GRUB_TERMINAL_OUTPUT} (@pxref{Simple configuration,,, -grub,GNU GRUB manual}). - -@item @code{terminal-inputs} (default: @code{'()}) -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: @code{console}, -@code{serial}, @code{serial_@{0-3@}}, @code{at_keyboard}, and -@code{usb_keyboard}. This field corresponds to the GRUB variable -@code{GRUB_TERMINAL_INPUT} (@pxref{Simple configuration,,, grub,GNU GRUB -manual}). - -@item @code{serial-unit} (default: @code{#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 (@pxref{Serial terminal,,, grub,GNU GRUB manual}). - -@item @code{serial-speed} (default: @code{#f}) -The speed of the serial interface, as an integer. For GRUB, the default -value is chosen at run-time; currently GRUB chooses 9600@tie{}bps -(@pxref{Serial terminal,,, grub,GNU GRUB manual}). -@end table - -@end deftp - -@cindex dual boot -@cindex boot menu -Should you want to list additional boot menu entries @i{via} the -@code{menu-entries} field above, you will need to create them with the -@code{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: - -@example -(menu-entry - (label "The Other Distro") - (linux "/boot/old/vmlinux-2.6.32") - (linux-arguments '("root=/dev/sda2")) - (initrd "/boot/old/initrd")) -@end example - -Details below. - -@deftp {Data Type} menu-entry -The type of an entry in the bootloader menu. - -@table @asis - -@item @code{label} -The label to show in the menu---e.g., @code{"GNU"}. - -@item @code{linux} -The Linux kernel image to boot, for example: - -@example -(file-append linux-libre "/bzImage") -@end example - -For GRUB, it is also possible to specify a device explicitly in the file -path using GRUB's device naming convention (@pxref{Naming convention,,, -grub, GNU GRUB manual}), for example: - -@example -"(hd0,msdos1)/boot/vmlinuz" -@end example - -If the device is specified explicitly as above, then the @code{device} field -is ignored entirely. - -@item @code{linux-arguments} (default: @code{()}) -The list of extra Linux kernel command-line arguments---e.g., -@code{("console=ttyS0")}. - -@item @code{initrd} -A G-Expression or string denoting the file name of the initial RAM disk to -use (@pxref{G-Ausdrücke}). -@item @code{device} (default: @code{#f}) -The device where the kernel and initrd are to be found---i.e., for GRUB, -@dfn{root} for this menu entry (@pxref{root,,, grub, GNU GRUB manual}). - -This may be a file system label (a string), a file system UUID (a -bytevector, @pxref{Dateisysteme}), or @code{#f}, in which case the -bootloader will search the device containing the file specified by the -@code{linux} field (@pxref{search,,, grub, GNU GRUB manual}). It must -@emph{not} be an OS device name such as @file{/dev/sda1}. - -@end table -@end deftp - -@c FIXME: Write documentation once it's stable. -Fow now only GRUB has theme support. GRUB themes are created using the -@code{grub-theme} form, which is not documented yet. - -@defvr {Scheme Variable} %default-theme -This is the default GRUB theme used by the operating system if no -@code{theme} field is specified in @code{bootloader-configuration} record. - -It comes with a fancy background image displaying the GNU and Guix logos. -@end defvr - - -@node Aufruf von guix system -@section @code{guix system} aufrufen - -Sobald Sie eine Betriebssystemdeklaration geschrieben haben, wie wir sie in -den vorangehenden Abschnitten gesehen haben, kann diese @dfn{instanziiert} -werden, indem Sie den Befehl @command{guix system} -aufrufen. Zusammengefasst: - -@example -guix system @var{Optionen}@dots{} @var{Aktion} @var{Datei} -@end example - -@var{Datei} muss der Name einer Datei sein, in der eine -Betriebssystemdeklaration als @code{operating-system}-Objekt -steht. @var{Aktion} gibt an, wie das Betriebssystem instanziiert -wird. Derzeit werden folgende Werte dafür unterstützt: - -@table @code -@item search -Verfügbare Diensttypendefinitionen anzeigen, die zum angegebenen regulären -Ausdruck passen, sortiert nach Relevanz: - -@example -$ 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 - -@dots{} -@end example - -Wie auch bei @command{guix package --search} wird das Ergebnis im -@code{recutils}-Format geliefert, so dass es leicht ist, die Ausgabe zu -filtern (@pxref{Top, GNU recutils databases,, recutils, GNU recutils -manual}). - -@item reconfigure -Build the operating system described in @var{file}, activate it, and switch -to it@footnote{This action (and the related actions @code{switch-generation} -and @code{roll-back}) are usable only on systems already running Guix -System.}. - -This effects all the configuration specified in @var{file}: user accounts, -system services, global package list, setuid programs, etc. The command -starts system services specified in @var{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 @code{herd stop X} or -@code{herd restart X}). - -Dieser Befehl erzeugt eine neue Generation, deren Nummer (wie @command{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 @command{guix -package} (@pxref{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 -@option{--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. - -@quotation Anmerkung -@c The paragraph below refers to the problem discussed at -@c <http://lists.gnu.org/archive/html/guix-devel/2014-08/msg00057.html>. -Es ist sehr zu empfehlen, @command{guix pull} einmal auszuführen, bevor Sie -@command{guix system reconfigure} zum ersten Mal aufrufen (@pxref{Aufruf von guix pull}). Wenn Sie das nicht tun, könnten Sie nach dem Abschluss von -@command{reconfigure} eine ältere Version von Guix vorfinden, als Sie vorher -hatten. -@end quotation - -@item switch-generation -@cindex Generationen -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 @emph{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: - -@example -guix system switch-generation 7 -@end example - -Die Zielgeneration kann auch relativ zur aktuellen Generation angegeben -werden, in der Form @code{+N} oder @code{-N}, wobei @code{+3} zum Beispiel -»3 Generationen weiter als die aktuelle Generation« bedeuten würde und -@code{-1} »1 Generation vor der aktuellen Generation« hieße. Wenn Sie einen -negativen Wert wie @code{-1} angeben, müssen Sie @code{--} der -Befehlszeilenoption voranstellen, damit die negative Zahl nicht selbst als -Befehlszeilenoption aufgefasst wird. Zum Beispiel: - -@example -guix system switch-generation -- -1 -@end example - -Zur Zeit bewirkt ein Aufruf dieser Aktion @emph{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 @command{reconfigure}, also etwa Dienste -aktivieren und deaktivieren. - -Diese Aktion schlägt fehl, wenn die angegebene Generation nicht existiert. - -@item roll-back -@cindex rücksetzen -Zur vorhergehenden Systemgeneration wechseln. Wenn das System das nächste -Mal hochgefahren wird, wird es die vorhergehende Systemgeneration -benutzen. Dies ist die Umkehrung von @command{reconfigure} und tut genau -dasselbe, wie @command{switch-generation} mit dem Argument @code{-1} -aufzurufen. - -Wie auch bei @command{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. - -@item delete-generations -@cindex deleting system generations -@cindex saving space -Delete system generations, making them candidates for garbage collection -(@pxref{Aufruf von guix gc}, for information on how to run the ``garbage -collector''). - -This works in the same way as @command{guix package --delete-generations} -(@pxref{Aufruf von guix package, @code{--delete-generations}}). With no -arguments, all system generations but the current one are deleted: - -@example -guix system delete-generations -@end example - -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: - -@example -guix system delete-generations 2m -@end example - -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. - -@item 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. - -@item init -Populate the given directory with all the files necessary to run the -operating system specified in @var{file}. This is useful for first-time -installations of Guix System. For instance: - -@example -guix system init my-os-config.scm /mnt -@end example - -Hiermit werden alle Store-Objekte nach @file{/mnt} kopiert, die von der in -@file{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 @file{/etc}, -@file{/var} und @file{/run} und die Datei @file{/bin/sh}. - -Dieser Befehl installiert auch den Bootloader auf dem in @file{my-os-config} -angegebenen Ziel, außer die Befehlszeilenoption @option{--no-bootloader} -wurde übergeben. - -@item vm -@cindex virtuelle Maschine -@cindex VM -@anchor{guix system vm} -Build a virtual machine that contains the operating system declared in -@var{file}, and return a script to run that virtual machine (VM). - -@quotation Anmerkung -The @code{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 -@file{/dev/kvm} device node must exist and be readable and writable by the -user and by the build users of the daemon (@pxref{Einrichten der Erstellungsumgebung}). -@end quotation - -Arguments given to the script are passed to QEMU as in the example below, -which enables networking and requests 1@tie{}GiB of RAM for the emulated -machine: - -@example -$ /gnu/store/@dots{}-run-vm.sh -m 1024 -net user -@end example - -Die virtuelle Maschine verwendet denselben Store wie das Wirtssystem. - -Mit den Befehlszeilenoptionen @code{--share} und @code{--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 @file{/austausch} aber mit Lese- und Schreibzugriff dem -Verzeichnis @file{$HOME/tmp} auf dem Wirtssystem zugeordnet wurde: - -@example -guix system vm my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/austausch -@end example - -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 @code{--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 @code{--image-size} kann -die Größe des Disk-Images angegeben werden. - -@cindex System-Disk-Images, Erstellung in verschiedenen Formaten -@cindex Erzeugen von System-Disk-Images in verschiedenen Formaten -@item vm-image -@itemx disk-image -@itemx 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 @var{Datei} deklarierte -Betriebssystem liefern. Das vorgegebene Verhalten von @command{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 -@option{--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 -@option{--image-size} im Fall von @code{docker-image} ignoriert. - -Sie können den Dateisystemtyp für das Wurzeldateisystem mit der -Befehlszeilenoption @option{--file-system-type} festlegen. Vorgegeben ist, -@code{ext4} zu verwenden. - -When using @code{vm-image}, the returned image is in qcow2 format, which the -QEMU emulator can efficiently use. @xref{Running Guix in a VM}, for more -information on how to run the image in a virtual machine. - -Wenn Sie ein @code{disk-image} anfordern, wird ein rohes Disk-Image -hergestellt; es kann zum Beispiel auf einen USB-Stick kopiert -werden. Angenommen @code{/dev/sdc} ist das dem USB-Stick entsprechende -Gerät, dann kann das Disk-Image mit dem folgenden Befehls darauf kopiert -werden: - -@example -# dd if=$(guix system disk-image my-os.scm) of=/dev/sdc -@end example - -Wenn Sie ein @code{docker-image} anfordern, wird ein Abbild für Docker -hergestellt. Guix erstellt das Abbild von Grund auf und @emph{nicht} aus -einem vorerstellten Docker-Basisabbild heraus, daher enthält es @emph{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: - -@example -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 -@end example - -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 -@option{--privileged} option to @code{docker run}. - -@item container -Liefert ein Skript, um das in der @var{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 @code{vm} (@pxref{guix system vm}) können zusätzlich -weitere Dateisysteme zwischen Wirt und Container geteilt werden, indem man -die Befehlszeilenoptionen @option{--share} und @option{--expose} verwendet: - -@example -guix system container my-config.scm \ - --expose=$HOME --share=$HOME/tmp=/austausch -@end example - -@quotation Anmerkung -Diese Befehlszeilenoption funktioniert nur mit Linux-libre 3.19 oder neuer. -@end quotation - -@end table - -Unter den @var{Optionen} können beliebige gemeinsame Erstellungsoptionen -aufgeführt werden (siehe @pxref{Gemeinsame Erstellungsoptionen}). Des Weiteren kann -als @var{Optionen} Folgendes angegeben werden: - -@table @option -@item --expression=@var{Ausdruck} -@itemx -e @var{Ausdruck} -Consider the operating-system @var{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 @pxref{Ein Abbild zur Installation erstellen}). - -@item --system=@var{System} -@itemx -s @var{System} -Versuche, für das angegebene @var{System} statt für denselben Systemtyp wie -auf dem Wirtssystem zu erstellen. Dies funktioniert wie bei @command{guix -build} (@pxref{Aufruf von guix build}). - -@item --derivation -@itemx -d -Liefert den Namen der Ableitungsdatei für das angegebene Betriebssystem, -ohne dazu etwas zu erstellen. - -@item --file-system-type=@var{Typ} -@itemx -t @var{type} -Für die Aktion @code{disk-image} wird hiermit ein Dateisystem des -angegebenen @var{Typ}s im Abbild bzw. Disk-Image erzeugt. - -Wird diese Befehlszeilenoption nicht angegeben, so benutzt @command{guix -system} als Dateisystemtyp @code{ext4}. - -@cindex ISO-9660-Format -@cindex CD-Abbild-Format -@cindex DVD-Abbild-Format -@code{--file-system-type=iso9660} erzeugt ein Abbild im Format ISO-9660, was -für das Brennen auf CDs und DVDs geeignet ist. - -@item --image-size=@var{Größe} -Für die Aktionen @code{vm-image} und @code{disk-image} wird hiermit -festgelegt, dass ein Abbild der angegebenen @var{Größe} erstellt werden -soll. Die @var{Größe} kann als Zahl die Anzahl Bytes angeben oder mit einer -Einheit als Suffix versehen werden (siehe @pxref{Block size, size -specifications,, coreutils, GNU Coreutils}). - -Wird keine solche Befehlszeilenoption angegeben, berechnet @command{guix -system} eine Schätzung der Abbildgröße anhand der Größe des in der -@var{Datei} deklarierten Systems. - -@item --root=@var{file} -@itemx -r @var{file} -Make @var{file} a symlink to the result, and register it as a garbage -collector root. - -@item --skip-checks -Die Konfiguration @emph{nicht} vor der Installation zur Sicherheit auf -Fehler prüfen. - -Das vorgegebene Verhalten von @command{guix system init} und @command{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 @code{operating-system}-Deklaration -erwähnten Dateisysteme tatsächlich existieren (@pxref{Dateisysteme}) und -dass alle Linux-Kernelmodule, die beim Booten benötigt werden könnten, auch -im @code{initrd-modules}-Feld aufgeführt sind (@pxref{Initiale RAM-Disk}). Mit dieser Befehlszeilenoption werden diese Tests allesamt -übersprungen. - -@cindex on-error -@cindex on-error strategy -@cindex error strategy -@item --on-error=@var{Strategie} -Beim Auftreten eines Fehlers beim Einlesen der @var{Datei} die angegebene -@var{Strategie} verfolgen. Als @var{Strategie} dient eine der Folgenden: - -@table @code -@item nothing-special -Nichts besonderes; der Fehler wird kurz gemeldet und der Vorgang -abgebrochen. Dies ist die vorgegebene Strategie. - -@item backtrace -Ebenso, aber zusätzlich wird eine Rückverfolgung des Fehlers (ein -»Backtrace«) angezeigt. - -@item 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 @code{,bt} eine Rückverfolgung (»Backtrace«) anzeigen lassen und -mit @code{,locals} die Werte lokaler Variabler anzeigen lassen. Im -Allgemeinen können Sie mit Befehlen den Zustand des Programms -inspizieren. Siehe @xref{Debug Commands,,, guile, GNU Guile Reference -Manual} für eine Liste verfügbarer Befehle zur Fehlersuche. -@end table -@end table - -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: - -@table @code - -@item list-generations -Eine für Menschen verständliche Zusammenfassung jeder auf der Platte -verfügbaren Generation des Betriebssystems ausgeben. Dies ähnelt der -Befehlszeilenoption @option{--list-generations} von @command{guix package} -(@pxref{Aufruf von guix package}). - -Optional kann ein Muster angegeben werden, was dieselbe Syntax wie -@command{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: - -@example -$ guix system list-generations 10d -@end example - -@end table - -Der Befehl @command{guix system} hat sogar noch mehr zu bieten! Mit -folgenden Unterbefehlen wird Ihnen visualisiert, wie Ihre Systemdienste -voneinander abhängen: - -@anchor{system-extension-graph} -@table @code - -@item extension-graph -Im Dot-/Graphviz-Format auf die Standardausgabe den -@dfn{Diensterweiterungsgraphen} des in der @var{Datei} definierten -Betriebssystems ausgeben (@pxref{Dienstkompositionen}, für mehr -Informationen zu Diensterweiterungen). - -Der Befehl: - -@example -$ guix system extension-graph @var{file} | dot -Tpdf > services.pdf -@end example - -erzeugt eine PDF-Datei, in der die Erweiterungsrelation unter Diensten -angezeigt wird. - -@anchor{system-shepherd-graph} -@item shepherd-graph -Im Dot-/Graphviz-Format auf die Standardausgabe den -@dfn{Abhängigkeitsgraphen} der Shepherd-Dienste des in der @var{Datei} -definierten Betriebssystems ausgeben. Siehe @xref{Shepherd-Dienste} für -mehr Informationen sowie einen Beispielgraphen. - -@end table - -@node Running Guix in a VM -@section Running Guix in a Virtual Machine - -@cindex virtuelle Maschine -To run Guix in a virtual machine (VM), one can either use the pre-built Guix -VM image distributed at -@indicateurl{https://alpha.gnu.org/gnu/guix/guixsd-vm-image-@value{VERSION}.@var{system}.xz} -, or build their own virtual machine image using @command{guix system -vm-image} (@pxref{Aufruf von guix system}). The returned image is in qcow2 -format, which the @uref{http://qemu.org/, QEMU emulator} can efficiently -use. - -@cindex QEMU -If you built your own image, you must copy it out of the store (@pxref{Der Store}) and give yourself permission to write to the copy before you can use -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 @command{guix system vm-image} on x86_64 hardware: - -@example -$ qemu-system-x86_64 \ - -net user -net nic,model=virtio \ - -enable-kvm -m 256 /tmp/qemu-image -@end example - -Here is what each of these options means: - -@table @code -@item qemu-system-x86_64 -This specifies the hardware platform to emulate. This should match the -host. - -@item -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. - -@item -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 -@command{qemu-system-x86_64 -net nic,model=help}. - -@item -enable-kvm -If your system has hardware virtualization extensions, enabling the virtual -machine support (KVM) of the Linux kernel will make things run faster. - -@item -m 256 -RAM available to the guest OS, in mebibytes. Defaults to 128@tie{}MiB, -which may be insufficient for some operations. - -@item /tmp/qemu-image -The file name of the qcow2 image. -@end table - -The default @command{run-vm.sh} script that is returned by an invocation of -@command{guix system vm} does not add a @command{-net user} flag by -default. To get network access from within the vm add the -@code{(dhcp-client-service)} to your system definition and start the VM -using @command{`guix system vm config.scm` -net user}. An important caveat -of using @command{-net user} for networking is that @command{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 @command{guix -download}. - -@subsection Connecting Through SSH - -@cindex SSH -@cindex SSH server -To enable SSH inside a VM you need to add a SSH server like -@code{(dropbear-service)} or @code{(lsh-service)} to your VM. The -@code{(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 - -@example -`guix system vm config.scm` -net user,hostfwd=tcp::10022-:22 -@end example - -To connect to the VM you can run - -@example -ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 10022 -@end example - -The @command{-p} tells @command{ssh} the port you want to connect to. -@command{-o UserKnownHostsFile=/dev/null} prevents @command{ssh} from -complaining every time you modify your @command{config.scm} file and the -@command{-o StrictHostKeyChecking=no} prevents you from having to allow a -connection to an unknown host every time you connect. - -@subsection Using @command{virt-viewer} with Spice - -As an alternative to the default @command{qemu} graphical client you can use -the @command{remote-viewer} from the @command{virt-viewer} package. To -connect pass the @command{-spice port=5930,disable-ticketing} flag to -@command{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 -@command{qemu}: - -@example --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 -@end example - -You'll also need to add the @pxref{Verschiedene Dienste, Spice service}. - -@node Dienste definieren -@section Dienste definieren - -The previous sections show the available services and how one can combine -them in an @code{operating-system} declaration. But how do we define them -in the first place? And what is a service anyway? - -@menu -* Dienstkompositionen:: Wie Dienste zusammengestellt werden. -* Diensttypen und Dienste:: Typen und Dienste. -* Service-Referenz:: Referenz zur Programmierschnittstelle. -* Shepherd-Dienste:: Eine spezielle Art von Dienst. -@end menu - -@node Dienstkompositionen -@subsection Dienstkompositionen - -@cindex services -@cindex daemons -Here we define a @dfn{service} as, broadly, something that extends the -functionality of the operating system. Often a service is a process---a -@dfn{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 @command{inetd} or a D-Bus service activated by @command{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 @file{/etc} service populates -the @file{/etc} directory of the system. - -@cindex service extensions -Guix system services are connected by @dfn{extensions}. For instance, the -secure shell service @emph{extends} the Shepherd---the initialization -system, running as PID@tie{}1---by giving it the command lines to start and -stop the secure shell daemon (@pxref{Netzwerkdienste, -@code{openssh-service-type}}); the UPower service extends the D-Bus service -by passing it its @file{.service} specification, and extends the udev -service by passing it device management rules (@pxref{Desktop-Dienste, -@code{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 -(@pxref{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: - -@image{images/service-graph,,5in,Typical service extension graph.} - -@cindex system service -At the bottom, we see the @dfn{system service}, which produces the directory -containing everything to run and boot the system, as returned by the -@command{guix system build} command. @xref{Service-Referenz}, to learn -about the other service types shown here. @xref{system-extension-graph, the -@command{guix system extension-graph} command}, for information on how to -generate this representation for a particular operating system definition. - -@cindex service types -Technically, developers can define @dfn{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 @code{lsh-service-type}, with -different parameters. - -The following section describes the programming interface for service types -and services. - -@node Diensttypen und Dienste -@subsection Diensttypen und Dienste - -A @dfn{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 -(@pxref{Aufruf des guix-daemon}): - -@example -(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)))) -@end example - -@noindent -It defines three things: - -@enumerate -@item -A name, whose sole purpose is to make inspection and debugging easier. - -@item -A list of @dfn{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 @dfn{boot service type}, which is the ultimate service. - -@item -Optionally, a default value for instances of this type. -@end enumerate - -In this example, @var{guix-service-type} extends three services: - -@table @var -@item shepherd-root-service-type -The @var{guix-shepherd-service} procedure defines how the Shepherd service -is extended. Namely, it returns a @code{<shepherd-service>} object that -defines how @command{guix-daemon} is started and stopped (@pxref{Shepherd-Dienste}). - -@item account-service-type -This extension for this service is computed by @var{guix-accounts}, which -returns a list of @code{user-group} and @code{user-account} objects -representing the build user accounts (@pxref{Aufruf des guix-daemon}). - -@item activation-service-type -Here @var{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. -@end table - -A service of this type is instantiated like this: - -@example -(service guix-service-type - (guix-configuration - (build-accounts 5) - (use-substitutes? #f))) -@end example - -The second argument to the @code{service} form is a value representing the -parameters of this specific service instance. -@xref{guix-configuration-type, @code{guix-configuration}}, for information -about the @code{guix-configuration} data type. When the value is omitted, -the default value specified by @code{guix-service-type} is used: - -@example -(service guix-service-type) -@end example - -@var{guix-service-type} is quite simple because it extends other services -but is not extensible itself. - -@c @subsubsubsection Extensible Service Types - -The service type for an @emph{extensible} service looks like this: - -@example -(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))))))))) -@end example - -This is the service type for the -@uref{https://wiki.gentoo.org/wiki/Project:Eudev, eudev device management -daemon}. Compared to the previous example, in addition to an extension of -@var{shepherd-root-service-type}, we see two new fields: - -@table @code -@item compose -This is the procedure to @dfn{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. - -@item extend -This procedure defines how the value of the service is @dfn{extended} with -the composition of the extensions. - -Udev extensions are composed into a list of rules, but the udev service -value is itself a @code{<udev-configuration>} record. So here, we extend -that record by appending the list of rules it contains to the list of -contributed rules. - -@item description -This is a string giving an overview of the service type. The string can -contain Texinfo markup (@pxref{Overview,,, texinfo, GNU Texinfo}). The -@command{guix system search} command searches these strings and displays -them (@pxref{Aufruf von guix system}). -@end table - -There can be only one instance of an extensible service type such as -@var{udev-service-type}. If there were more, the @code{service-extension} -specifications would be ambiguous. - -Still here? The next section provides a reference of the programming -interface for services. - -@node Service-Referenz -@subsection Service-Referenz - -We have seen an overview of service types (@pxref{Diensttypen und Dienste}). This section provides a reference on how to manipulate services -and service types. This interface is provided by the @code{(gnu services)} -module. - -@deffn {Scheme Procedure} service @var{type} [@var{value}] -Return a new service of @var{type}, a @code{<service-type>} object (see -below.) @var{value} can be any object; it represents the parameters of this -particular service instance. - -When @var{value} is omitted, the default value specified by @var{type} is -used; if @var{type} does not specify a default value, an error is raised. - -For instance, this: - -@example -(service openssh-service-type) -@end example - -@noindent -is equivalent to this: - -@example -(service openssh-service-type - (openssh-configuration)) -@end example - -In both cases the result is an instance of @code{openssh-service-type} with -the default configuration. -@end deffn - -@deffn {Scheme Procedure} service? @var{obj} -Return true if @var{obj} is a service. -@end deffn - -@deffn {Scheme Procedure} service-kind @var{service} -Return the type of @var{service}---i.e., a @code{<service-type>} object. -@end deffn - -@deffn {Scheme Procedure} service-value @var{service} -Return the value associated with @var{service}. It represents its -parameters. -@end deffn - -Here is an example of how a service is created and manipulated: - -@example -(define s - (service nginx-service-type - (nginx-configuration - (nginx nginx) - (log-directory log-directory) - (run-directory run-directory) - (file config-file)))) - -(service? s) -@result{} #t - -(eq? (service-kind s) nginx-service-type) -@result{} #t -@end example - -The @code{modify-services} form provides a handy way to change the -parameters of some of the services of a list such as @var{%base-services} -(@pxref{Basisdienste, @code{%base-services}}). It evaluates to a list of -services. Of course, you could always use standard list combinators such as -@code{map} and @code{fold} to do that (@pxref{SRFI-1, List Library,, guile, -GNU Guile Reference Manual}); @code{modify-services} simply provides a more -concise form for this common pattern. - -@deffn {Scheme-Syntax} modify-services @var{Dienste} @ - (@var{Typ} @var{Variable} => @var{Rumpf}) @dots{} - -Passt die von @var{Dienste} bezeichnete Dienst-Liste entsprechend den -angegebenen Klauseln an. Jede Klausel hat die Form: - -@example -(@var{Typ} @var{Variable} => @var{Rumpf}) -@end example - -wobei @var{Typ} einen Diensttyp (»service type«) bezeichnet — wie zum -Beispiel @code{guix-service-type} — und @var{Variable} ein Bezeichner ist, -der im @var{Rumpf} an die Dienst-Parameter — z.B. eine -@code{guix-configuration}-Instanz — des ursprünglichen Dienstes mit diesem -@var{Typ} gebunden wird. - -Der @var{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 @code{define-record-type*} erzeugt -werden, können Sie einen kurzen @var{Rumpf} schreiben, der zu den neuen -Dienstparametern ausgewertet wird, indem Sie die Funktionalität namens -@code{inherit} benutzen, die von @code{define-record-type*} bereitgestellt -wird. - -Siehe @xref{Das Konfigurationssystem nutzen} für ein Anwendungsbeispiel. - -@end deffn - -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 @code{operating-system} -declaration. - -@deftp {Data Type} service-type -@cindex service type -This is the representation of a @dfn{service type} (@pxref{Diensttypen und Dienste}). - -@table @asis -@item @code{name} -This is a symbol, used only to simplify inspection and debugging. - -@item @code{extensions} -A non-empty list of @code{<service-extension>} objects (see below). - -@item @code{compose} (default: @code{#f}) -If this is @code{#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 -@code{fold-services} and is passed a list of values collected from -extensions. It may return any single value. - -@item @code{extend} (default: @code{#f}) -If this is @code{#f}, services of this type cannot be extended. - -Otherwise, it must be a two-argument procedure: @code{fold-services} calls -it, passing it the initial value of the service as the first argument and -the result of applying @code{compose} to the extension values as the second -argument. It must return a value that is a valid parameter value for the -service instance. -@end table - -@xref{Diensttypen und Dienste}, for examples. -@end deftp - -@deffn {Scheme Procedure} service-extension @var{target-type} @ - @var{compute} Return a new extension for services of type -@var{target-type}. @var{compute} must be a one-argument procedure: -@code{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. -@end deffn - -@deffn {Scheme Procedure} service-extension? @var{obj} -Return true if @var{obj} is a service extension. -@end deffn - -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 @code{simple-service} procedure provides -a shorthand for this. - -@deffn {Scheme Procedure} simple-service @var{name} @var{target} @var{value} -Return a service that extends @var{target} with @var{value}. This works by -creating a singleton service type @var{name}, of which the returned service -is an instance. - -For example, this extends mcron (@pxref{Geplante Auftragsausführung}) with an -additional job: - -@example -(simple-service 'my-mcron-job mcron-service-type - #~(job '(next-hour (3)) "guix gc -F 2G")) -@end example -@end deffn - -At the core of the service abstraction lies the @code{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 @command{guix system build} command -(@pxref{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. - -@deffn {Scheme Procedure} fold-services @var{services} @ - [#:target-type @var{system-service-type}] Fold @var{services} by propagating -their extensions down to the root of type @var{target-type}; return the root -service adjusted accordingly. -@end deffn - -Lastly, the @code{(gnu services)} module also defines several essential -service types, some of which are listed below. - -@defvr {Scheme Variable} system-service-type -This is the root of the service graph. It produces the system directory as -returned by the @command{guix system build} command. -@end defvr - -@defvr {Scheme Variable} boot-service-type -The type of the ``boot service'', which produces the @dfn{boot script}. The -boot script is what the initial RAM disk runs when booting. -@end defvr - -@defvr {Scheme Variable} etc-service-type -The type of the @file{/etc} service. This service is used to create files -under @file{/etc} and can be extended by passing it name/file tuples such -as: - -@example -(list `("issue" ,(plain-file "issue" "Welcome!\n"))) -@end example - -In this example, the effect would be to add an @file{/etc/issue} file -pointing to the given file. -@end defvr - -@defvr {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 (@pxref{Setuid-Programme}). -@end defvr - -@defvr {Scheme Variable} profile-service-type -Type of the service that populates the @dfn{system profile}---i.e., the -programs under @file{/run/current-system/profile}. Other services can -extend it by passing it lists of packages to add to the system profile. -@end defvr - - -@node Shepherd-Dienste -@subsection Shepherd-Dienste - -@cindex shepherd services -@cindex PID 1 -@cindex init system -The @code{(gnu services shepherd)} module provides a way to define services -managed by the GNU@tie{}Shepherd, which is the initialization system---the -first process that is started when the system boots, also known as -PID@tie{}1 (@pxref{Einführung,,, shepherd, 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 (@pxref{Das Konfigurationssystem nutzen}) results in a service graph like this: - -@image{images/shepherd-graph,,5in,Typical shepherd service graph.} - -You can actually generate such a graph for any operating system definition -using the @command{guix system shepherd-graph} command -(@pxref{system-shepherd-graph, @command{guix system shepherd-graph}}). - -The @var{%shepherd-root-service} is a service object representing -PID@tie{}1, of type @var{shepherd-root-service-type}; it can be extended by -passing it lists of @code{<shepherd-service>} objects. - -@deftp {Data Type} shepherd-service -The data type representing a service managed by the Shepherd. - -@table @asis -@item @code{provision} -This is a list of symbols denoting what the service provides. - -These are the names that may be passed to @command{herd start}, -@command{herd status}, and similar commands (@pxref{Invoking herd,,, -shepherd, The GNU Shepherd Manual}). @xref{Slots of services, the -@code{provides} slot,, shepherd, The GNU Shepherd Manual}, for details. - -@item @code{requirements} (default: @code{'()}) -List of symbols denoting the Shepherd services this one depends on. - -@item @code{respawn?} (default: @code{#t}) -Whether to restart the service when it stops, for instance when the -underlying process dies. - -@item @code{start} -@itemx @code{stop} (default: @code{#~(const #f)}) -The @code{start} and @code{stop} fields refer to the Shepherd's facilities -to start and stop processes (@pxref{Service De- and Constructors,,, -shepherd, The GNU Shepherd Manual}). They are given as G-expressions that -get expanded in the Shepherd configuration file (@pxref{G-Ausdrücke}). - -@item @code{actions} (Vorgabe: @code{'()}) -@cindex Aktionen, bei Shepherd-Diensten -This is a list of @code{shepherd-action} objects (see below) defining -@dfn{actions} supported by the service, in addition to the standard -@code{start} and @code{stop} actions. Actions listed here become available -as @command{herd} sub-commands: - -@example -herd @var{action} @var{service} [@var{arguments}@dots{}] -@end example - -@item @code{Dokumentation} -A documentation string, as shown when running: - -@example -herd doc @var{service-name} -@end example - -where @var{service-name} is one of the symbols in @var{provision} -(@pxref{Invoking herd,,, shepherd, The GNU Shepherd Manual}). - -@item @code{modules} (default: @var{%default-modules}) -This is the list of modules that must be in scope when @code{start} and -@code{stop} are evaluated. - -@end table -@end deftp - -@deftp {Datentyp} shepherd-action -This is the data type that defines additional actions implemented by a -Shepherd service (see above). - -@table @code -@item name -Die Aktion bezeichnendes Symbol. - -@item Dokumentation -This is a documentation string for the action. It can be viewed by running: - -@example -herd doc @var{service} action @var{action} -@end example - -@item procedure -This should be a gexp that evaluates to a procedure of at least one -argument, which is the ``running value'' of the service (@pxref{Slots of -services,,, shepherd, The GNU Shepherd Manual}). -@end table - -The following example defines an action called @code{say-hello} that kindly -greets the user: - -@example -(shepherd-action - (name 'say-hello) - (documentation "Say hi!") - (procedure #~(lambda (running . args) - (format #t "Hello, friend! arguments: ~s\n" - args) - #t))) -@end example - -Assuming this action is added to the @code{example} service, then you can -do: - -@example -# herd say-hello example -Hello, friend! arguments: () -# herd say-hello example a b c -Hello, friend! arguments: ("a" "b" "c") -@end example - -This, as you can see, is a fairly sophisticated way to say hello. -@xref{Service Convenience,,, shepherd, The GNU Shepherd Manual}, for more -info on actions. -@end deftp - -@defvr {Scheme Variable} shepherd-root-service-type -The service type for the Shepherd ``root service''---i.e., PID@tie{}1. - -This is the service type that extensions target when they want to create -shepherd services (@pxref{Diensttypen und Dienste}, for an example). -Each extension must pass a list of @code{<shepherd-service>}. -@end defvr - -@defvr {Scheme Variable} %shepherd-root-service -This service represents PID@tie{}1. -@end defvr - - -@node Dokumentation -@chapter Dokumentation - -@cindex documentation, searching for -@cindex searching for documentation -@cindex Info, documentation format -@cindex man pages -@cindex manual pages -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 @command{info} command or with Emacs, and man pages are accessed -using @command{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: - -@example -$ 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 -@dots{} -@end example - -@noindent -The command below searches for the same keyword in man pages: - -@example -$ man -k TLS -SSL (7) - OpenSSL SSL/TLS library -certtool (1) - GnuTLS certificate tool -@dots {} -@end example - -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: - -@example -$ info "(gnutls)Core TLS API" -@end example - -@noindent -or: - -@example -$ man certtool -@end example - -Info manuals contain sections and indices as well as hyperlinks like those -found in Web pages. The @command{info} reader (@pxref{Top, Info reader,, -info-stnd, Stand-alone GNU Info}) and its Emacs counterpart (@pxref{Misc -Help,,, emacs, The GNU Emacs Manual}) provide intuitive key bindings to -navigate manuals. @xref{Getting Started,,, info, Info: An Introduction}, -for an introduction to Info navigation. - -@node Dateien zur Fehlersuche installieren -@chapter Dateien zur Fehlersuche installieren - -@cindex debugging files -Program binaries, as produced by the GCC compilers for instance, are -typically written in the ELF format, with a section containing -@dfn{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 (@pxref{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 -(@pxref{Separate Debug Files,,, gdb, Debugging with GDB}). - -The GNU distribution takes advantage of this by storing debugging -information in the @code{lib/debug} sub-directory of a separate package -output unimaginatively called @code{debug} (@pxref{Pakete mit mehreren Ausgaben.}). Users can choose to install the @code{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: - -@example -guix package -i glibc:debug guile:debug -@end example - -GDB must then be told to look for debug files in the user's profile, by -setting the @code{debug-file-directory} variable (consider setting it from -the @file{~/.gdbinit} file, @pxref{Startup,,, gdb, Debugging with GDB}): - -@example -(gdb) set debug-file-directory ~/.guix-profile/lib/debug -@end example - -From there on, GDB will pick up debugging information from the @code{.debug} -files under @file{~/.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 @code{guix build --source}, -@pxref{Aufruf von guix build}), and to point GDB to that source directory -using the @code{directory} command (@pxref{Source Path, @code{directory},, -gdb, Debugging with GDB}). - -@c XXX: keep me up-to-date -The @code{debug} output mechanism in Guix is implemented by the -@code{gnu-build-system} (@pxref{Erstellungssysteme}). Currently, it is -opt-in---debugging information is available only for the packages with -definitions explicitly declaring a @code{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 @code{debug} output, use @command{guix package ---list-available} (@pxref{Aufruf von guix package}). - - -@node Sicherheitsaktualisierungen -@chapter Sicherheitsaktualisierungen - -@cindex security updates -@cindex security vulnerabilities -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 -@code{master} branch of Guix (we do not yet provide a ``stable'' branch -containing only security updates.) The @command{guix lint} tool helps -developers find out about vulnerable versions of software packages in the -distribution: - -@smallexample -$ 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 -@dots{} -@end smallexample - -@xref{Aufruf von guix lint}, for more information. - -@quotation Anmerkung -As of version @value{VERSION}, the feature described below is considered -``beta''. -@end quotation - -Guix follows a functional package management discipline -(@pxref{Einführung}), which implies that, when a package is changed, -@emph{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 (@pxref{Substitute}), but -deployment may still take more time than desired. - -@cindex grafts -To address this, Guix implements @dfn{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. - -@cindex replacements of packages, for grafts -For instance, suppose a security update needs to be applied to Bash. Guix -developers will provide a package definition for the ``fixed'' Bash, say -@var{bash-fixed}, in the usual way (@pxref{Pakete definieren}). Then, the -original package definition is augmented with a @code{replacement} field -pointing to the package containing the bug fix: - -@example -(define bash - (package - (name "bash") - ;; @dots{} - (replacement bash-fixed))) -@end example - -From there on, any package depending directly or indirectly on Bash---as -reported by @command{guix gc --requisites} (@pxref{Aufruf von guix gc})---that -is installed is automatically ``rewritten'' to refer to @var{bash-fixed} -instead of @var{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 (@var{bash-fixed} and @var{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 @code{SONAME} and be binary-compatible. - -The @option{--no-grafts} command-line option allows you to forcefully avoid -grafting (@pxref{Gemeinsame Erstellungsoptionen, @option{--no-grafts}}). Thus, the -command: - -@example -guix build bash --no-grafts -@end example - -@noindent -returns the store file name of the original Bash, whereas: - -@example -guix build bash -@end example - -@noindent -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 -(@pxref{Aufruf von guix gc}): - -@example -guix gc -R `readlink -f ~/.guix-profile` | grep bash -@end example - -@noindent -@dots{} and compare the store file names that you get with those above. -Likewise for a complete Guix system generation: - -@example -guix gc -R `guix system build my-config.scm` | grep bash -@end example - -Lastly, to check which Bash running processes are using, you can use the -@command{lsof} command: - -@example -lsof | grep /gnu/store/.*bash -@end example - - -@node Bootstrapping -@chapter Bootstrapping - -@c Adapted from the ELS 2013 paper. - -@cindex 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 (@pxref{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''. - -@cindex bootstrap binaries -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 @code{./configure}, -@code{make}, etc.---are written in Guile Scheme (@pxref{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 @dfn{bootstrap binaries}. - -These bootstrap binaries are ``taken for granted'', though we can also -re-create them if needed (more on that later). - -@unnumberedsec Preparing to Use the Bootstrap Binaries - -@c As of Emacs 24.3, Info-mode displays the image, but since it's a -@c large image, it's hard to scroll. Oh well. -@image{images/bootstrap-graph,6in,,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 @code{(gnu -packages bootstrap)} module. A similar figure can be generated with -@command{guix graph} (@pxref{Aufruf von guix graph}), along the lines of: - -@example -guix graph -t derivation \ - -e '(@@@@ (gnu packages bootstrap) %bootstrap-gcc)' \ - | dot -Tps > t.ps -@end example - -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 -@file{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 -@code{add-to-store} (@pxref{Der Store}). - -But how do we write a derivation that unpacks this tarball and adds it to -the store? To solve this problem, the @code{guile-bootstrap-2.0.drv} -derivation---the first one that gets built---uses @code{bash} as its -builder, which runs @code{build-bootstrap-guile.sh}, which in turn calls -@code{tar} to unpack the tarball. Thus, @file{bash}, @file{tar}, @file{xz}, -and @file{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 @code{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 -@code{.tar.xz.drv} derivations do. Guix modules such as -@code{ftp-client.scm} are used for this purpose. The -@code{module-import.drv} derivations import those modules in a directory in -the store, using the original layout. The @code{module-import-compiled.drv} -derivations compile those modules, and write them in an output directory -with the right layout. This corresponds to the @code{#:modules} argument of -@code{build-expression->derivation} (@pxref{Ableitungen}). - -Finally, the various tarballs are unpacked by the derivations -@code{gcc-bootstrap-0.drv}, @code{glibc-bootstrap-0.drv}, etc., at which -point we have a working C tool chain. - - -@unnumberedsec 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 @file{/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 @code{(gnu packages -commencement)} module. - -The @command{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: - -@example -guix graph -t bag \ - -e '(@@@@ (gnu packages commencement) - glibc-final-with-bootstrap-bash)' | dot -Tps > t.ps -@end example - -@noindent -produces the dependency graph leading to the ``final'' C -library@footnote{You may notice the @code{glibc-intermediate} label, -suggesting that it is not @emph{quite} final, but as a good approximation, -we will consider it final.}, depicted below. - -@image{images/bootstrap-packages,6in,,Dependency graph of the early -packages} - -@c See <http://lists.gnu.org/archive/html/gnu-system-discuss/2012-10/msg00000.html>. -The first tool that gets built with the bootstrap binaries is -GNU@tie{}Make---noted @code{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 @code{--target} equal to @code{--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 -@code{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 @code{%final-inputs} variable of -the @code{(gnu packages commencement)} module, and are implicitly used by -any package that uses @code{gnu-build-system} (@pxref{Erstellungssysteme, -@code{gnu-build-system}}). - - -@unnumberedsec Building the Bootstrap Binaries - -@cindex 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 -@code{(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): - -@example -guix build bootstrap-tarballs -@end example - -The generated tarballs are those that should be referred to in the -@code{(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. - -@unnumberedsec 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 @emph{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 @uref{http://bootstrappable.org, Bootstrappable.org web site} 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! - - -@node Portierung -@chapter 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'' -(@pxref{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 @code{(gnu packages -bootstrap)} module to use them on that platform. - -Fortunately, Guix can @emph{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: - -@example -guix build --target=armv5tel-linux-gnueabi bootstrap-tarballs -@end example - -For this to work, the @code{glibc-dynamic-linker} procedure in @code{(gnu -packages bootstrap)} must be augmented to return the right file name for -libc's dynamic linker on that platform; likewise, -@code{system->linux-architecture} in @code{(gnu packages linux)} must be -taught about the new platform. - -Once these are built, the @code{(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 -@file{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 @code{eabi} suffix -above) is not recognized by all the GNU tools. Typically, glibc recognizes -some of these, whereas GCC uses an extra @code{--with-abi} configure flag -(see @code{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. - -@c ********************************************************************* -@include contributing.de.texi - -@c ********************************************************************* -@node Danksagungen -@chapter Danksagungen - -Guix is based on the @uref{http://nixos.org/nix/, Nix package manager}, -which was designed and implemented by Eelco Dolstra, with contributions from -other people (see the @file{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@tie{}Guix itself is a collective work with contributions from a number -of people. See the @file{AUTHORS} file in Guix for more information on -these fine people. The @file{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! - - -@c ********************************************************************* -@node GNU-Lizenz für freie Dokumentation -@appendix GNU-Lizenz für freie Dokumentation -@cindex license, GNU Free Documentation License -@include fdl-1.3.texi - -@c ********************************************************************* -@node Konzeptverzeichnis -@unnumbered Konzeptverzeichnis -@printindex cp - -@node Programmierverzeichnis -@unnumbered Programmierverzeichnis -@syncodeindex tp fn -@syncodeindex vr fn -@printindex fn - -@bye - -@c Local Variables: -@c ispell-local-dictionary: "american"; -@c End: |